@brass-build/client 0.4.0 → 0.5.0

package/dist/sealed-store.d.ts

@@ -0,0 +1,242 @@
+import { type PackedRecord } from './record-paging.js';
+import type { ArrowReader } from './sealed-arrow.js';
+/**
+ * The peer every conversion of frozen content into a CRDT authors as.
+ *
+ * Pinned, so one frozen stream produces one document: two sides that convert
+ * the same content independently write the same ops, and their later edits
+ * merge rather than doubling every record.
+ *
+ * A live editor never authors as this peer. It keeps the one its own document
+ * was opened with, so every op it writes after a conversion is its own.
+ */
+export declare const CONVERSION_PEER_ID: "1";
+/** Named roots, every map as typed Arrow tables, the whole stream one ZSTD
+ *  frame. What the platform stores; only its encoder writes it. */
+export declare const VERSION_ARROW = 4;
+/** Frame 4's body under gzip rather than ZSTD: what a producer without a ZSTD
+ *  compressor (a browser) uploads. Staging only; the seal stores it as frame
+ *  4, so no reader is ever handed it. */
+export declare const VERSION_ARROW_STAGED = 5;
+/** The newest frame this build reads. */
+export declare const NEWEST_VERSION = 4;
+/** The join `accept` token naming the stored frames this build decodes. */
+export declare const SEALED_ACCEPT = "sealed@4";
+/** One root of frozen content, as JSON: an object is a map, an array a list,
+ *  a string a text. */
+export type SealedRootValue = Record<string, unknown> | readonly unknown[] | string;
+/** A stream's content as JSON, one entry per root. */
+export type SealedContentJson = Record<string, SealedRootValue>;
+export type SealedRootKind = 'map' | 'list' | 'text';
+/** The kind a JSON value would be stored as, or null for a value no root can
+ *  hold. */
+export declare function sealedRootKindOf(value: unknown): SealedRootKind | null;
+/** One header entry of a record store: the format's own preamble (an IFC
+ *  `FILE_DESCRIPTION`, a DXF header variable), tagged the way a record is. */
+export interface SealedHeaderEntry {
+    tag: string;
+    body: unknown;
+}
+/** What produced a stream's content: an importer's id and version. A reader
+ *  answers from the content whoever produced it; this is for deciding which
+ *  stored streams an importer fix should rebuild. */
+export interface SealedStoreBuiltBy {
+    id: string;
+    version: string;
+}
+/** A record store as triples, which is what a caller holding parsed records
+ *  hands the encoder without first building a map object from them. */
+export interface SealedStoreSource {
+    schemaVersion: string;
+    header: readonly SealedHeaderEntry[];
+    /** Absent for content nothing parsed (an app's own). */
+    builtBy?: SealedStoreBuiltBy;
+    /** `[key, tag, body]` triples in the order the store holds them. */
+    records: PackedRecord<unknown>[];
+}
+/** A record-store entry split into its tag and body: the tag of a value in
+ *  the record shape (`{ type, params }` and nothing else), or null for any
+ *  other value, which is the body whole. `recordValueOf` rebuilds the value. */
+export interface SealedRecord {
+    tag: string | null;
+    body: unknown;
+}
+/**
+ * One map root of frozen content, stored or held in memory.
+ *
+ * Opening one decodes nothing. A keyed read builds the record it asks for;
+ * `forEach` walks the records in stored order without keeping them. Values
+ * are the stored JSON values, built afresh on every read.
+ */
+export interface SealedMapReader {
+    /** Entries in the map. */
+    size(): number;
+    has(key: string): boolean;
+    get(key: string): unknown;
+    /** Every key, in stored order. */
+    keys(): string[];
+    /** Every entry, in stored order. */
+    forEach(visit: (key: string, value: unknown) => void): void;
+    /** Every entry, in stored order, decoded as the iteration reaches it: a
+     *  caller that stops early pays for the records it read. */
+    entries(): IterableIterator<[string, unknown]>;
+    /** The JSON text of every value, in bytes. Reads every value. */
+    valueBytes(): number;
+    /** The whole map as the object it was stored from. */
+    toJSON(): Record<string, unknown>;
+    /** Drop what keyed reads decoded and kept. */
+    releaseDecoded(): void;
+}
+/** A value split the way a record store reports it. */
+export declare function sealedRecordOf(value: unknown): SealedRecord;
+/** Whether a byte run opens as frozen content THIS reader can read. Cheap
+ *  enough to ask of any object, since it reads the first five bytes. */
+export declare function isSealedStore(bytes: Uint8Array): boolean;
+/** The frame version stamped on frozen content, or null for bytes that are
+ *  not frozen content. */
+export declare function frameVersion(bytes: Uint8Array): number | null;
+/** Frozen content that could not be read. The message names the content
+ *  rather than the field that failed, because every way this throws means the
+ *  bytes are not content this reader can open. */
+export declare class SealedStoreError extends Error {
+    /** The error the decoder raised, where this wraps one. */
+    readonly underlying?: unknown | undefined;
+    constructor(message?: string, 
+    /** The error the decoder raised, where this wraps one. */
+    underlying?: unknown | undefined);
+}
+/**
+ * Decoded frozen content: the frame read and every root located, or content
+ * held in memory (`fromJSON`, `fromRecords`) with the same roots, so a reader
+ * never asks which one it holds.
+ */
+export declare class SealedContent {
+    private readonly _bytes;
+    private readonly _roots;
+    private readonly _builtBy;
+    private constructor();
+    /** Read the frame. Throws `SealedStoreError` for bytes that are not frozen
+     *  content, or whose frame does not fit inside them. */
+    static decode(bytes: Uint8Array): SealedContent;
+    /**
+     * Content held in memory, as `decode` reads the same content stored.
+     * CONSUMES the map values, as `sealedTablesOfImport` does. Throws for a
+     * root that is not a map, a list or a string.
+     */
+    static fromJSON(content: SealedContentJson, builtBy?: SealedStoreBuiltBy): SealedContent;
+    /** A record store handed over as triples, held in memory. CONSUMES
+     *  `source.records`. */
+    static fromRecords(source: SealedStoreSource): SealedContent;
+    /** The content's own size, which is what it costs to hold and transfer. */
+    get byteLength(): number;
+    /** The importer that produced the content, or null for content that names
+     *  none. */
+    builtBy(): SealedStoreBuiltBy | null;
+    rootNames(): string[];
+    kindOf(name: string): SealedRootKind | undefined;
+    /** A map root as a lazy reader, or null when the content holds no such
+     *  map. */
+    mapRoot(name: string): SealedMapReader | null;
+    /** The map a list root is the key walk of (an ordered map's order list), or
+     *  null for a list stored with items of its own. */
+    keyWalkOf(name: string): string | null;
+    /** Every entry of a map root, in stored order, without building the
+     *  object. */
+    forEachMapEntry(name: string, visit: (key: string, value: unknown) => void): void;
+    /** A map root as an object, or null when the content holds no such map. */
+    map(name: string): Record<string, unknown> | null;
+    /** A list root's items, or null when the content holds no such list. */
+    list(name: string): unknown[] | null;
+    /** A text root, or null when the content holds no such text. */
+    text(name: string): string | null;
+    /** The whole content as the JSON it was encoded from. */
+    toJSON(): SealedContentJson;
+}
+/** What a frame-4 decode calls. Each decompressor refuses output past `max`. */
+export interface SealedCodec {
+    arrow: ArrowReader;
+    unzstd(bytes: Uint8Array, max: number): Uint8Array;
+    gunzip(bytes: Uint8Array, max: number): Uint8Array;
+    reader: typeof import('./sealed-arrow.js');
+}
+/**
+ * The most a frame-4 or staging-frame body expands to. The encoder refuses to
+ * write tables past it and the decoder refuses a body that would expand past
+ * it, so every stored line is one every reader decodes, and a body an
+ * uploader shaped to expand further is refused before it is decompressed.
+ * The densest import measured (2.85M IFC geometry records) expands to 68 MB,
+ * and a 128 MiB CSV of single-digit cells to about 285 MB.
+ */
+export declare const SEALED_INNER_MAX_BYTES: number;
+/** Content whose tables would expand past `SEALED_INNER_MAX_BYTES`. */
+export declare class SealedContentTooLargeError extends SealedStoreError {
+    constructor();
+}
+/**
+ * The most a ZSTD stream can write or allocate, read from its frame and block
+ * headers without decompressing it: per frame its window, and its declared
+ * content size, which a decoder holds the frame's output to. A frame that
+ * declares none is bounded by its blocks: each raw or RLE block's stated size
+ * plus the format's 128 KiB ceiling per compressed block, which overstates a
+ * level-19 frame (its blocks average a few KB). Both encoders here declare the
+ * size. Throws on a stream that is not ZSTD frames end to end.
+ */
+export declare function zstdOutputBound(bytes: Uint8Array): number;
+/** Whether decoding these bytes needs `loadSealedCodec` first. */
+export declare function needsSealedCodec(bytes: Uint8Array): boolean;
+/** Load what a frame-4 decode needs. Under a Node that carries zstd, the
+ *  built-in decompresses; anywhere else, `fzstd`. */
+export declare function loadSealedCodec(): Promise<void>;
+/** Decode frozen bytes, loading the frame-4 codec first when they need it.
+ *  A frame-4 decode awaits `pause` before each table it parses, so a large
+ *  decode leaves the page responsive. */
+export declare function decodeSealedContent(bytes: Uint8Array, pause?: () => Promise<void>): Promise<SealedContent>;
+/** A pause that hands the event loop back once `sliceMs` of work has run
+ *  since the last time it did. */
+export declare function slicedYield(sliceMs?: number): () => Promise<void>;
+/** Hands the event loop back for one turn: `scheduler.yield` where the
+ *  platform has it, else a message, which no timer clamp delays. */
+export declare function yieldToEventLoop(): Promise<void>;
+/** A frame-4 object around its ZSTD-compressed parts, or with
+ *  `VERSION_ARROW_STAGED`, the staging frame around its gzipped parts. */
+export declare function arrowFrameBytes(compressed: Uint8Array, version?: number): Uint8Array;
+/** A frame-4 or staging-frame object's compressed parts. */
+export declare function arrowFrameBody(bytes: Uint8Array): Uint8Array;
+/**
+ * A frame-4 or staging-frame object's parts, decompressed. Throws
+ * `SealedContentTooLargeError` for a body that expands past
+ * `SEALED_INNER_MAX_BYTES`, and needs `loadSealedCodec` first.
+ */
+export declare function arrowFrameInner(bytes: Uint8Array): Uint8Array;
+/** The manifest part's name; table parts are named by their position. */
+export declare const ARROW_MANIFEST_PART = "manifest";
+export type ArrowManifestRoot = ['map', string] | ['list', string, unknown[]] | ['list', string, null, string] | ['text', string, string];
+export type ArrowManifest = [[string, string] | null, ArrowManifestRoot[]];
+/**
+ * Frozen content read as a record store: the `instances` map, its order, the
+ * schema version and the header. Every server-side reader that walks records
+ * (an exporter, a view) reads through this, and it answers for any frozen
+ * content: a root the content does not hold reads as empty.
+ */
+export declare class SealedStore {
+    private readonly _content;
+    private readonly _records;
+    private constructor();
+    static decode(bytes: Uint8Array): SealedStore;
+    static of(content: SealedContent): SealedStore;
+    /** The general form this view reads. */
+    get content(): SealedContent;
+    get byteLength(): number;
+    /** The schema version, the `meta` root's one key. */
+    schemaVersion(): string;
+    /** The header entries in the record shape, in order. */
+    header(): SealedHeaderEntry[];
+    builtBy(): SealedStoreBuiltBy | null;
+    keys(): string[];
+    recordCount(): number;
+    has(key: string): boolean;
+    get(key: string): SealedRecord | undefined;
+    forEachRecord(visit: (key: string, tag: string | null, body: unknown) => void): void;
+    releaseDecoded(): void;
+}
+//# sourceMappingURL=sealed-store.d.ts.map

package/dist/sealed-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-store.d.ts","sourceRoot":"","sources":["../src/sealed-store.ts"],"names":[],"mappings":"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"}