Skip to main content
Module

x/earthstar/mod.ts>IFormat

Earthstar is a tool for private, undiscoverable, offline-first networks.
earthstar-project/earthstar
Go to Latest
interface IFormat
Re-export
import { type IFormat } from "https://deno.land/x/earthstar@v10.0.0-alpha.2/mod.ts";

Formats are each responsible for one document format such as "es.4". They are used for signing and validating documents, as well as generating new documents from a given input.

Type Parameters

FormatType extends FormatName
DocInputType extends DocInputBase<FormatType>
DocType extends DocBase<FormatType>

Properties

id: FormatType

The string name of the format, like "es.4"

Methods

hashDocument(doc: DocType): Promise<Base32String | ValidationError>

Deterministic hash of this version of the document

generateDocument(opts: FormatterGenerateOpts<FormatType, DocInputType, DocType>): Promise<{ doc: DocType; attachment?: ReadableStream<Uint8Array> | Uint8Array; } | ValidationError>

Generate a signed document from the input format the validator expects.

signDocument(keypair: AuthorKeypair, doc: DocType): Promise<DocType | ValidationError>

Sign an unsigned document.

wipeDocument(keypair: AuthorKeypair, docToWipe: DocType): Promise<DocType | ValidationError>

Overwrite the user-written contents of a document, wipes any associated attachments, and signs the document.

removeExtraFields(doc: DocType): { doc: DocType; extras: Record<string, unknown>; } | ValidationError

Return a copy of the doc without extra fields, plus the extra fields as a separate object. If the input is not a plain javascript object, return a ValidationError. This should be run before checkDocumentIsValid. The output doc will be more likely to be valid once the extra fields have been removed.

checkDocumentIsValid(doc: DocType, now?: number): true | ValidationError

This calls all the more detailed functions which start with underscores. Returns true if the document is ok.

getAttachmentInfo(doc: DocType): { size: number; hash: string; } | ValidationError

Returns information about a doc's attachment, if it has one. If it doesn't, a ValidationError will be returned. This does not indicate if that attachment is actually present locally.

updateAttachmentFields(
doc: DocType,
size: number,
hash: string,
): DocType | ValidationError

Some information can only be known once an attachment (especially if it comes in the form of a stream) has been consumed. For this reason, a Formatter's generateDocument method may not be able to generate a valid document for a attachment, even if it already knows it has one.