Skip to main content
Deno 2 is finally here 🎉️
Learn more
Module

x/earthstar/src/entries/npm.ts>MultiformatReplica

Storage for private, distributed, offline-first applications.
earthstar-project/earthstar
Go to Latest
class MultiformatReplica
Re-export
import { MultiformatReplica } from "https://deno.land/x/earthstar@v10.2.0/src/entries/npm.ts";

A replica holding a share's data, used to read, write, and synchronise data to.

Should be closed using the close method when no longer being used.

const gardeningKeypair = await Crypto.generateShareKeypair("gardening");

const myReplica = new Replica({
 driver: new ReplicaDriverMemory(gardeningKeypair.shareAddress),
 config: {
   "es.5": { shareSecret: gardeningKeypair.secret }
 }
});

Constructors

new
MultiformatReplica(unnamed 0: MultiFormatReplicaOpts)

Properties

private
_isClosed: boolean
private
callbackSink: CallbackSink<ReplicaEvent<DocBase<string>>>
private
eraseInterval: number
private
eventMultiStream: ChannelMultiStream<ReplicaEvent<DocBase<string>>["kind"], "kind", ReplicaEvent<DocBase<string>>>
private
eventWriter: WritableStreamDefaultWriter<ReplicaEvent<DocBase<string>>>
private
expireEventTimeouts: Map<string, number>
private
ingestLockStream: LockStream
formatsConfig: Record<string, unknown>
replicaDriver: IReplicaDriver

The validator used to validate ingested documents.

replicaId: ReplicaId
share: ShareAddress

The address of the share this replica belongs to.

Methods

private
pruneExpiredDocsAndAttachments<F>(formats?: FormatsArg<F>)

Erases expired docs and dangling attachments

private
wipeDocument<F>(
keypair: AuthorKeypair,
doc: FormatDocType<F>,
format: FormatArg<F>,
): Promise<IngestEvent<FormatDocType<F>>>
addAttachments<F = DefaultFormats>(docs: FormatDocType<F>[], formats?: FormatsArg<F>): Promise<Awaited<DocWithAttachment<FormatDocType<F>>>[]>

Returns the given array of documents with a new attachment property merged in. The value of this property can be:

  • DocAttachment
  • undefined (the associated document can have an attachment, but we don't have a copy)
  • ValidationError (the associated document can't have an attachment)
close(erase: boolean): Promise<void>

Closes the replica, preventing new documents from being ingested or events being emitted. Any methods called after closing will return ReplicaIsClosedError.

deleteConfig(key: string): Promise<boolean>
getAllDocs<F = DefaultFormats>(formats?: FormatsArg<F>): Promise<FormatDocType<F>[]>

Returns all documents, including historical versions of documents by other identities.

getAllDocsAtPath<F = DefaultFormats>(path: Path, formats?: FormatsArg<F>): Promise<FormatDocType<F>[]>

Returns all versions of a document by different authors from a specific path.

getAttachment<F = DefaultFormat>(doc: FormatDocType<F>, format?: FormatArg<F>): Promise<DocAttachment | undefined | ValidationError>

Gets an attachment for a given document. Returns a ValidationError if the given document can't have an attachment.

getConfig(key: string): Promise<string | undefined>
getEventStream(channel?: OrCh<ReplicaEvent<DocBase<string>>["kind"]>): ReadableStream<ReplicaEvent<DocBase<string>>>

Returns a readable stream of replica events, such as new ingestions, document expirations, or the replica preparing to close.

getLatestDocAtPath<F = DefaultFormat>(path: Path, format?: FormatArg<F>): Promise<FormatDocType<F> | undefined>

Returns the most recently written version of a document at a path.

getLatestDocs<F = DefaultFormats>(formats?: FormatsArg<F>): Promise<FormatDocType<F>[]>

Returns latest document from every path.

getMaxLocalIndex(): Promise<number>

Returns the max local index of all stored documents

getQueryStream<F = DefaultFormats>(
query?: Omit<Query<[string]>, "formats">,
formats?: FormatsArg<F>,
): ReadableStream<QuerySourceEvent<FormatDocType<F>>>

Returns a readable stream of document events which match a given query. The events can represent existing documents, newly ingested documents, or expiring documents.

ingest<F = DefaultFormat>(
format: FormatArg<F>,
docToIngest: FormatDocType<F>,
sourceId: "local" | string,
): Promise<IngestEvent<FormatDocType<F>>>

Ingest an existing signed document to the replica.

ingestAttachment<F = DefaultFormat>(
format: FormatArg<F>,
doc: FormatDocType<F>,
attachment: Uint8Array | ReadableStream<Uint8Array>,
sourceId: "local" | string,
): Promise<true | false | ValidationError>

Ingest an attachment for a given document.

isClosed(): boolean

Returns whether the replica is closed or not.

listConfigKeys(): Promise<string[]>
onEvent(callback: (event: ReplicaEvent<DocBase<FormatName>>) => void | Promise<void>)

Provide a callback to be triggered every time a replica event occurs.

overwriteAllDocsByAuthor<F = DefaultFormat>(keypair: AuthorKeypair, format?: FormatArg<F>): Promise<number | ValidationError>

Overwrite every document from this author, including history versions, with an empty doc.

queryAuthors<F = DefaultFormats>(query?: Omit<Query<[string]>, "formats">, formats?: FormatsArg<F>): Promise<AuthorAddress[]>

Returns an array of all unique authors of documents returned by a given query.

queryDocs<F = DefaultFormats>(query?: Omit<Query<[string]>, "formats">, formats?: FormatsArg<F>): Promise<FormatDocType<F>[]>

Returns an array of docs for a given query. ``` const myQuery = { filter: { pathEndsWith: ".txt" }, limit: 5, };

const firstFiveTextDocs = await myReplica.queryDocs(myQuery);
```
queryPaths<F = DefaultFormats>(query?: Omit<Query<[string]>, "formats">, formats?: FormatsArg<F>): Promise<Path[]>

Returns an array of all unique paths of documents returned by a given query.

set<F = DefaultFormat>(
keypair: AuthorKeypair,
docToSet: Omit<FormatInputType<F>, "format">,
format?: FormatArg<F>,
): Promise<IngestEvent<FormatDocType<F>>>

Adds a new document to the replica. If a document signed by the same identity exists at the same path, it will be overwritten.

setConfig(key: string, value: string): Promise<void>
wipeDocAtPath<F = DefaultFormat>(
keypair: AuthorKeypair,
path: string,
format?: FormatArg<F>,
): Promise<IngestEvent<FormatDocType<F>> | ValidationError>

Wipe all content from a document at a given path, and erase its attachment (if it has one).