Skip to content
datadata

@repo/datadata/system

The system documents an application reads directly: access and identity, sync status, the document index and trash, schema documents and presence channels.

Functions

listingEntries

export declare function listingEntries<S extends SchemaRegistry, Type extends keyof RegistryFor<S> & string>(schemas: S, listing: DatadataDocument<TrashDocument> | null | undefined, type: Type): TrashListingEntry<TypedDocumentId<RegistryFor<S>, Type>>[];

Project a listing document's (sys:index / sys:trash) entries with each entry's id typed as its docType's branded document id. This is the lossless typed view of a listing: iterating listing.data.documents by hand yields plain-string ids, because the correlation "an entry whose type is 'todo' sits under a TodoListId key" is not expressible on a record type (and Object.entries widens keys to string regardless) — so every consumer re-branded ids with an unchecked cast. Here the re-brand happens once, justified by the server invariant that a listing entry's type IS the docType its document was created as.

Two forms: - **Type-filtered** (type passed): only that docType's entries, as { id, name } — the "list my todo lists" shape. - **No-filter** (type omitted): every entry of a docType the registry declares, as the discriminated union { id, type, name } — narrowing on type narrows id. Entries of UNdeclared docTypes are omitted (they cannot be typed); this is the one place the schemas VALUE is consulted (its keys), everywhere else it rides along for its TYPE alone — TypeScript cannot infer Type's literal once any type argument is explicit, so the registry comes in as a value, the same way createClient({ schemas }) types the client.

Pure over the passed listing — read it through the scope whose view you want (a staging session's overlaid sys:index projects its staged creates). A null/undefined listing (not yet synced) projects to []. Entry order is the record's own; sort in the caller. A sys:trash listing's entries additionally carry deletedAt.

export declare function listingEntries<S extends SchemaRegistry, Type extends keyof RegistryFor<S> & string>(schemas: S, listing: DatadataDocument<IndexDocument> | null | undefined, type: Type): ListingEntry<TypedDocumentId<RegistryFor<S>, Type>>[];

Project a sys:index listing's entries of one docType as { id, name }, with each id typed as that docType's branded id; [] for a null/undefined listing. See the sys:trash overload for the full contract.

export declare function listingEntries<S extends SchemaRegistry>(schemas: S, listing: DatadataDocument<TrashDocument> | null | undefined): TrashListingEntryOf<S>[];

Project every sys:trash entry of a docType schemas declares into the discriminated union TrashListingEntryOf, so narrowing on type narrows id; entries of undeclared docTypes are omitted.

export declare function listingEntries<S extends SchemaRegistry>(schemas: S, listing: DatadataDocument<IndexDocument> | null | undefined): ListingEntryOf<S>[];

Project every sys:index entry of a docType schemas declares into the discriminated union ListingEntryOf, so narrowing on type narrows id; entries of undeclared docTypes are omitted.

presenceDocId

export declare function presenceDocId(presenceType: string, docId: string): string;

Id of the presence channel sys:presence:<presenceType>:<docId>. The channel is ephemeral and never stored; its value is a record of PresenceCells keyed by presence id. Its presenceType must have a presence schema declared (see presenceSchemaDocId), and docId is whatever the app means it to be: the server never resolves it.

presenceViewDocId

export declare function presenceViewDocId(presenceType: string, docId: string): string;

Id of a session's view of a presence channel: sys:presence-view:<presenceType>:<docId>. Read through a session, it projects the channel presenceDocId as { self, peers }; it is never stored or synced, and the live client returns null for it.

schemaDocId

export declare function schemaDocId(docType: string): string;

Id of the schema document for docType: sys:schema:<docType>.

Interfaces

ListingEntry

export interface ListingEntry<Id extends string = string>

One document of a given docType in a sys:index listing, as projected by the type-filtered form of listingEntries: its (branded) id and its index-level name (null = unnamed; see sys:index).

id: Id;

The document's id, branded with its docType.

name: string | null;

The document's index-level name; null = unnamed.

TrashListingEntry

export interface TrashListingEntry<Id extends string = string> extends ListingEntry<Id>

A ListingEntry from the sys:trash listing — the same projection plus the entry's tombstone timestamp, so a trash UI can sort/expire entries.

deletedAt: number;

When the document was deleted, in milliseconds since the Unix epoch.

Types

AccessDocument

export type AccessDocument = InferJsonSchema<typeof AccessDocumentSchema>;

Data of the folder's access document (sys:access): a role per subject in roles, the role for authenticated subjects not listed (authenticatedDefault) and for anonymous principals (anonymousDefault), and per-document access rules in documents, which take precedence over the document type's rules. A folder without this document treats every authenticated subject as admin.

ClientDocumentsStatusDocument

export type ClientDocumentsStatusDocument = InferJsonSchema<typeof ClientDocumentsStatusDocumentSchema>;

Data of the client's status document (sys:client-docs-status): per document, its subscription and load state, the number of pending optimistic writes, any error, and whether it is shown from the persisted cache. Also counts documents shown from the cache, offline writes discarded instead of re-sent, and cached documents evicted at startup.

DiscardedWriteReason

export type DiscardedWriteReason = (typeof DISCARDED_WRITE_REASONS)[number];

Why a queued offline write was discarded instead of re-sent: retentionExpired, it outlived ClientConfig.persistedWriteMaxAgeMs; or replayHorizon, it was sent but unconfirmed for longer than MAX_REPLAY_AGE_MS, so its outcome is unknown.

IndexDocument

export type IndexDocument = InferJsonSchema<typeof IndexDocumentSchema>;

Data of the sys:index listing: one entry per live document, keyed by document id, with its type and index name (null when unnamed).

ListingEntryOf

export type ListingEntryOf<S extends SchemaRegistry> = {
    [T in keyof S & string]: {
        id: TypedDocumentId<RegistryFor<S>, T>;
        type: T;
        name: string | null;
    };
}[keyof S & string];

The discriminated union the no-filter form of listingEntries projects a sys:index listing into: one member per docType the schema registry declares, carrying that docType's branded id — so narrowing on type narrows id (if (e.type === "todo") → e.id: TodoListId). Built over the registry's OWN docTypes (not the merged sys:* ones, which never appear in a listing).

PrincipalDocument

export type PrincipalDocument = Omit<InferJsonSchema<typeof PrincipalDocumentSchema>, "scopes"> & {
    scopes?: AccessScope[];
};

Data of the connection's own identity document (sys:principal): structurally a Principal. The server synthesizes it from the connection's principal, so a scope's kinds are the access kinds it was built from — the schema checks them as strings, since no enum can name every command an app defines.

TrashDocument

export type TrashDocument = InferJsonSchema<typeof TrashDocumentSchema>;

Data of the sys:trash listing: one entry per soft-deleted document, keyed by document id, with its type, deletedAt (milliseconds since the Unix epoch), name at deletion, and the generation a restore is aimed at.

TrashListingEntryOf

export type TrashListingEntryOf<S extends SchemaRegistry> = {
    [T in keyof S & string]: {
        id: TypedDocumentId<RegistryFor<S>, T>;
        type: T;
        name: string | null;
        deletedAt: number;
    };
}[keyof S & string];

The sys:trash counterpart of ListingEntryOf — the same discriminated union with each member carrying the entry's tombstone timestamp.

Variables

ACCESS_DOCUMENT_ID

ACCESS_DOCUMENT_ID = "sys:access"

Id of the folder's access document (see AccessDocument): roles per subject, role defaults and per-document access rules. One per folder, stored and client-writable, but writing it requires the admin role.

ACCESS_DOCUMENT_TYPE

ACCESS_DOCUMENT_TYPE = "sys:access"

Document type of the ACCESS_DOCUMENT_ID access document.

CLIENT_DOCUMENTS_STATUS_DOCUMENT_ID

CLIENT_DOCUMENTS_STATUS_DOCUMENT_ID = "sys:client-docs-status"

Id of the client's sync-status document (see ClientDocumentsStatusDocument): a client-local document reporting each document's subscription, pending writes and errors.

CLIENT_DOCUMENTS_STATUS_DOCUMENT_TYPE

CLIENT_DOCUMENTS_STATUS_DOCUMENT_TYPE = "sys:client-docs-status"

Document type of the CLIENT_DOCUMENTS_STATUS_DOCUMENT_ID status document.

INDEX_DOCUMENT_ID

INDEX_DOCUMENT_ID = "sys:index"

Id of the folder's document listing: a virtual document with one entry per live document (see IndexDocument).

INDEX_DOCUMENT_TYPE

INDEX_DOCUMENT_TYPE = "sys:index"

Document type of the INDEX_DOCUMENT_ID listing.

PRINCIPAL_DOCUMENT_ID

PRINCIPAL_DOCUMENT_ID = "sys:principal"

Id of the connection's identity document (see PrincipalDocument): the principal the server runs this connection's writes as. Virtual and read-only; once connected it, not ClientConfig.principal, is what the client predicts capabilities from.

PRINCIPAL_DOCUMENT_TYPE

PRINCIPAL_DOCUMENT_TYPE = "sys:principal"

Document type of the PRINCIPAL_DOCUMENT_ID identity document.

SCHEMA_DOCUMENT_TYPE

SCHEMA_DOCUMENT_TYPE = "sys:schema"

Document type of every schema document.

TRASH_DOCUMENT_ID

TRASH_DOCUMENT_ID = "sys:trash"

Id of the trash listing: a virtual document with one entry per soft-deleted document (see TrashDocument). Subscribe to it to build a trash or restore UI.

TRASH_DOCUMENT_TYPE

TRASH_DOCUMENT_TYPE = "sys:trash"

Document type of the TRASH_DOCUMENT_ID listing.