@brass-build/client 0.1.0

package/dist/mutate-batching.js

@@ -0,0 +1,65 @@
+// Committing a very large mutation as it goes, so an app can write a
+// file's worth of records through the same `mutate` it uses for one.
+//
+// Encoding a commit costs more per record the more containers that commit
+// creates: 20,000 records in one commit take ~60s and produce an op too
+// large to store, where the same records committed every ~500 take under
+// 3s (`scripts/bench/`). Above the budget below, a mutation therefore
+// commits and continues.
+//
+// The consequence a caller can observe is that peers receive such a write
+// as several updates instead of one, so they can see it part-applied. It
+// converges normally and stays one undo step.
+// A batch closes once the values assigned since the last commit reach
+// roughly this much JSON, which keeps each op in the tens of KB: an
+// encoded op runs close to the JSON length of its values, and base64 adds
+// a third. Budgeting on size rather than on a record count is what keeps
+// that true for narrow and wide records alike, so where it splits depends
+// on width (measured: ~800 spreadsheet cells, ~200 wider rows).
+export const MUTATE_BATCH_JSON_BUDGET_CHARS = 48 * 1024;
+/** Rough size of one assigned value. Runs on every assignment, so it only
+ *  has to be proportional; an unserializable value counts as nominal
+ *  rather than throwing, since the assignment itself is where that error
+ *  belongs. */
+function approximateChars(value) {
+    if (value === null || value === undefined)
+        return 8;
+    const t = typeof value;
+    if (t === 'number' || t === 'boolean')
+        return 8;
+    if (t === 'string')
+        return value.length + 2;
+    try {
+        return JSON.stringify(value)?.length ?? 64;
+    }
+    catch {
+        return 64;
+    }
+}
+/**
+ * Decides when a mutation should commit. The caller supplies what a commit
+ * means, since an ordered map reconciles its order list first.
+ */
+export class MutateBatcher {
+    _flush;
+    _chars = 0;
+    constructor(_flush) {
+        this._flush = _flush;
+    }
+    /** Account for one assignment, from the proxy's set trap. */
+    record(value) {
+        const chars = approximateChars(value);
+        // Commit BEFORE adding, so one assignment larger than the whole budget
+        // lands in a batch of its own instead of dragging its neighbours over
+        // the line with it.
+        if (this._chars > 0 && this._chars + chars > MUTATE_BATCH_JSON_BUDGET_CHARS) {
+            this._flush();
+            this._chars = 0;
+        }
+        this._chars += chars;
+    }
+    recordDelete() {
+        this.record(null);
+    }
+}
+//# sourceMappingURL=mutate-batching.js.map

package/dist/mutate-batching.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutate-batching.js","sourceRoot":"","sources":["../src/mutate-batching.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,qEAAqE;AACrE,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,yEAAyE;AACzE,sEAAsE;AACtE,yBAAyB;AACzB,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,8CAA8C;AAE9C,sEAAsE;AACtE,oEAAoE;AACpE,0EAA0E;AAC1E,yEAAyE;AACzE,0EAA0E;AAC1E,gEAAgE;AAChE,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,GAAG,IAAI,CAAC;AAExD;;;eAGe;AACf,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,OAAO,KAAK,CAAC;IACvB,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK,QAAQ;QAAE,OAAQ,KAAgB,CAAC,MAAM,GAAG,CAAC,CAAC;IACxD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,EAAE,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,aAAa;IAGK;IAFrB,MAAM,GAAG,CAAC,CAAC;IAEnB,YAA6B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAEnD,6DAA6D;IAC7D,MAAM,CAAC,KAAc;QACnB,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;QACtC,uEAAuE;QACvE,sEAAsE;QACtE,oBAAoB;QACpB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK,GAAG,8BAA8B,EAAE,CAAC;YAC5E,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;IACvB,CAAC;IAED,YAAY;QACV,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;CACF"}

package/dist/open-document.d.ts

@@ -0,0 +1,127 @@
+import { Document, type BranchProvider, type DocumentOptions, type DocumentWorkStatus, type DocumentDriveTrackingState, type DriveMirrorDirection, type HostedUiProvider } from './documents.js';
+import type { WsTopicCallback } from './ws-client.js';
+export interface OpenDocumentByIdOptions {
+    documentOptions?: DocumentOptions;
+    /**
+     * Which stream of the document to open. The returned Document's own
+     * handles (`doc.map(...)`) read that stream, so an app that works in one
+     * part of a partitioned document downloads only that part. Defaults to
+     * `'default'`, the stream every document has.
+     */
+    stream?: string;
+}
+export interface CreateDocumentOptions {
+    name?: string;
+    app_metadata?: Record<string, unknown>;
+    documentOptions?: DocumentOptions;
+}
+export interface CreateDocumentArgs {
+    name?: string;
+    app_metadata?: Record<string, unknown>;
+    documentOptions?: DocumentOptions;
+    siblingOf?: string;
+    destination?: unknown;
+}
+export type CreateDocumentResult = {
+    kind: 'created';
+    docId: string;
+} | {
+    kind: 'needs-destination';
+} | {
+    kind: 'needs-organization';
+};
+export interface DocumentSnapshotResponse {
+    doc_id: string;
+    branch_id: string;
+    stream_branch_id?: string;
+    snapshot: {
+        kind: 'inline';
+        data_b64: string;
+    } | {
+        kind: 'presigned';
+        url: string;
+    } | null;
+    tail_ops: Array<{
+        seq: number;
+        op_blob_b64: string;
+    }>;
+    current_seq?: number;
+    snapshot_version_vector?: string;
+    status?: DocumentWorkStatus;
+    drive?: DocumentDriveSummaryWire;
+}
+export interface DocumentDriveSummaryWire {
+    drive_type: string;
+    drive_name: string;
+    item_name: string;
+    item_url: string;
+    tracking_state: DocumentDriveTrackingState;
+    tracking_ref: string;
+    tracking_ref_updated_at: string;
+    tracking_label: string | null;
+    tracking_detail: string | null;
+    broken: boolean;
+    push_replaces_remote: boolean;
+    mirror_direction: DriveMirrorDirection;
+    publishing?: boolean;
+}
+export interface DocumentAtVersionResponse {
+    effective_version: number;
+    requested_version: number;
+    branch_id: string;
+    snapshot: {
+        kind: 'inline';
+        data_b64: string;
+    } | {
+        kind: 'presigned';
+        url: string;
+    } | null;
+    tail_ops: Array<{
+        seq: number;
+        op_blob_b64: string;
+    }>;
+    current_seq: number;
+}
+export interface OpenDocumentWsClient {
+    subscribe(topic: string, callback: WsTopicCallback): () => void;
+    send(frame: unknown): void;
+}
+export interface OpenDocumentFactoryOptions {
+    appId: string;
+    apiBaseUrl: string;
+    getAccessToken: () => Promise<string | null>;
+    getAppAssertion?: () => Promise<string | null>;
+    wsClient?: OpenDocumentWsClient;
+    newClientOpId?: () => string;
+    branchProvider?: BranchProvider;
+    thumbnailUploader?: (doc: Document, image: Blob, width: number, height: number) => Promise<unknown>;
+    checkpointCreator?: (doc: Document) => Promise<import('./documents-namespace.js').DocumentCheckpoint>;
+    drivePusher?: (doc: Document, input: import('./documents-namespace.js').PushToDriveInput) => Promise<import('./documents-namespace.js').PushToDriveResult>;
+    sourceBlobFetcher?: (doc: Document) => Promise<import('./documents-namespace.js').DocumentSourceBlob>;
+    streamProvider?: {
+        list: (docId: string, branchId: string) => Promise<{
+            streams: import('./documents-namespace.js').DocumentStreamInfo[];
+        }>;
+        create: (docId: string, branchId: string, name: string) => Promise<import('./documents-namespace.js').DocumentStreamInfo>;
+    };
+    hostedUiProvider?: HostedUiProvider;
+    launchOrganizationId?: () => string | null;
+    reportError?: (err: Error) => void;
+}
+export type OpenedDocument = Document & {
+    readonly id: string;
+};
+export type OpenDocumentByIdFn = (docId: string, options?: OpenDocumentByIdOptions) => Promise<OpenedDocument>;
+export type OpenDocumentByLinkFn = (token: string, options?: OpenDocumentByIdOptions) => Promise<OpenedDocument>;
+export type CreateDocumentFn = (options?: CreateDocumentOptions) => Promise<OpenedDocument>;
+export interface DocumentFactory {
+    open: OpenDocumentByIdFn;
+    create: CreateDocumentFn;
+    createDocumentId: (args: CreateDocumentArgs) => Promise<CreateDocumentResult>;
+    openByLink: OpenDocumentByLinkFn;
+}
+export declare function createOpenDocument(opts: OpenDocumentFactoryOptions): DocumentFactory;
+export declare function _resetParkCacheForTesting(): void;
+export declare const PERIODIC_REVERIFY_INTERVAL_MS: number;
+export declare const MISSED_OP_RESYNC_DELAY_MS = 2000;
+//# sourceMappingURL=open-document.d.ts.map

package/dist/open-document.d.ts.map

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