Skip to main content

Interface: IStorageBackend

Defined in: src/types/interfaces/storage.interface.ts:180

Storage backend interface for Chive's local index.

Remarks​

This interface stores indexes, not source data. All data can be rebuilt from the AT Protocol firehose.

Implementation uses PostgreSQL for relational queries, JSONB columns for flexible schema, partitioning for scalability, and indexes on uri, author, and createdAt.

Methods​

getPreprint()​

getPreprint(uri): Promise<null | StoredPreprint>

Defined in: src/types/interfaces/storage.interface.ts:244

Retrieves a preprint index record by URI.

Parameters​

uri​

AtUri

AT URI of the preprint

Returns​

Promise<null | StoredPreprint>

Preprint if indexed, null otherwise

Remarks​

Returns null if the preprint has not been indexed by Chive. The preprint may still exist in the user's PDS.

Example​

const preprint = await storage.getPreprint(
  toAtUri('at://did:plc:abc/pub.chive.preprint.submission/xyz')!
);

if (preprint) {
  console.log('Title:', preprint.title);
}

getPreprintsByAuthor()​

getPreprintsByAuthor(author, options?): Promise<StoredPreprint[]>

Defined in: src/types/interfaces/storage.interface.ts:269

Queries preprints by author.

Parameters​

author​

DID

Author DID

options?​

PreprintQueryOptions

Query options (limit, offset, sort)

Returns​

Promise<StoredPreprint[]>

Array of preprints by this author

Remarks​

Returns preprints in order specified by options.sortBy. For full-text search across all fields, use ISearchEngine instead.

Example​

const preprints = await storage.getPreprintsByAuthor(
  toDID('did:plc:abc')!,
  { limit: 10, sortBy: 'createdAt', sortOrder: 'desc' }
);

preprints.forEach(p => console.log(p.title));

isStale()​

isStale(uri): Promise<boolean>

Defined in: src/types/interfaces/storage.interface.ts:343

Checks if an indexed record is stale (PDS has newer version).

Parameters​

uri​

AtUri

Record URI

Returns​

Promise<boolean>

True if index is stale, false otherwise

Remarks​

Staleness is detected by comparing:

  • Indexed CID vs current PDS CID
  • Last sync time vs PDS update time

When stale, the indexing pipeline should re-fetch and re-index.

Example​

const isStale = await storage.isStale(
  toAtUri('at://did:plc:abc/pub.chive.preprint.submission/xyz')!
);

if (isStale) {
  console.log('Re-indexing required');
}

listPreprintUris()​

listPreprintUris(options?): Promise<readonly string[]>

Defined in: src/types/interfaces/storage.interface.ts:288

Lists all preprint URIs with pagination.

Parameters​

options?​

Query options including limit

cursor​

string

limit​

number

Returns​

Promise<readonly string[]>

Array of preprint URIs

Remarks​

Used for browsing all preprints without facet filtering. Returns URIs only for efficiency; full metadata can be fetched separately.

Example​

const uris = await storage.listPreprintUris({ limit: 100 });

storePreprint()​

storePreprint(preprint): Promise<Result<void, Error>>

Defined in: src/types/interfaces/storage.interface.ts:219

Stores or updates a preprint index record.

Parameters​

preprint​

StoredPreprint

Preprint metadata to index

Returns​

Promise<Result<void, Error>>

Result indicating success or failure

Remarks​

Upserts the preprint (insert or update based on URI). Updates indexedAt timestamp on every call.

ATProto Compliance: Stores metadata only, not source data.

Example​

const result = await storage.storePreprint({
  uri: toAtUri('at://did:plc:abc/pub.chive.preprint.submission/xyz')!,
  cid: toCID('bafyreib...')!,
  author: toDID('did:plc:abc')!,
  title: 'Neural Networks in Biology',
  abstract: 'This paper explores...',
  pdfBlobRef: {
    $type: 'blob',
    ref: toCID('bafyreib...')!,
    mimeType: 'application/pdf',
    size: 2048576
  },
  pdsUrl: 'https://pds.example.com',
  indexedAt: new Date(),
  createdAt: new Date()
});

if (!result.ok) {
  console.error('Failed to store:', result.error);
}

trackPDSSource()​

trackPDSSource(uri, pdsUrl, lastSynced): Promise<Result<void, Error>>

Defined in: src/types/interfaces/storage.interface.ts:315

Tracks PDS source for staleness detection.

Parameters​

uri​

AtUri

Record URI

pdsUrl​

string

URL of the user's PDS

lastSynced​

Date

Last successful sync timestamp

Returns​

Promise<Result<void, Error>>

Result indicating success or failure

Remarks​

ATProto Compliance: Essential for detecting when index is stale (PDS has newer data) and triggering re-indexing.

This enables rebuilding the index from scratch if needed.

Example​

await storage.trackPDSSource(
  toAtUri('at://did:plc:abc/pub.chive.preprint.submission/xyz')!,
  'https://pds.example.com',
  new Date()
);