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

x/earthstar/src/entries/universal.ts>IFormat

Storage for private, distributed, offline-first applications.
earthstar-project/earthstar
Go to Latest
interface IFormat
Re-export
import { type IFormat } from "https://deno.land/x/earthstar@v10.0.1/src/entries/universal.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>
ConfigType extends Record<string, unknown> | undefined

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, ConfigType>): Promise<{ doc: DocType; attachment?: ReadableStream<Uint8Array> | Uint8Array; } | ValidationError>

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

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

Sign an unsigned document.

wipeDocument(
keypair: AuthorKeypair,
docToWipe: DocType,
config: ConfigType,
): 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): Promise<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(
keypair: AuthorKeypair,
doc: DocType,
size: number,
hash: string,
config: ConfigType,
): Promise<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.