@brass-build/client 0.1.0 → 0.2.0

package/dist/fetch-retry.js

@@ -14,11 +14,13 @@
 //
 // - A GET is idempotent, so replaying it is always safe: retry the whole
 //   transient 5xx / 429 set AND a thrown network error (`RETRY_READ`).
-// - A write is NOT idempotent, so only a 503 is safe to replay: the API
-//   gateway returns a 503 BEFORE the request reaches the handler (a transient
-//   throttle / scale-up / deploy-window blip), so the write never ran and
-//   a replay cannot double-apply it. A 502 / 504 / 429 or a network throw
-//   might mean the handler ran, so those stay hard failures (`RETRY_WRITE_503`).
+// - A write is NOT idempotent, so only a 503 is safe to replay, and only on
+//   a route where a 503 means the write did not land: the gateway's own 503
+//   (a transient throttle / scale-up / deploy-window blip) is returned before
+//   the request reaches the handler, and a handler that answers 503 does so
+//   for a write it refused rather than applied. A 502 / 504 / 429 or a network
+//   throw might mean the handler ran, so those stay hard failures
+//   (`RETRY_WRITE_503`).
 // - A 500 is never retried under either policy: an unhandled server error
 //   is usually deterministic, so a replay just doubles the cost without
 //   changing the outcome.
@@ -54,9 +56,11 @@ const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export async function fetchWithRetry(doFetch, options = {}) {
     const policy = options.policy ?? RETRY_READ;
     const maxAttempts = options.maxAttempts ?? 3;
+    const maxNetworkAttempts = options.maxNetworkAttempts ?? maxAttempts;
     const baseDelayMs = options.baseDelayMs ?? 300;
     const sleep = options.sleep ?? defaultSleep;
     let lastError;
+    let networkThrows = 0;
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
         let response;
         try {
@@ -68,6 +72,9 @@ export async function fetchWithRetry(doFetch, options = {}) {
             if (!policy.replayNetworkErrors)
                 throw err;
             lastError = err;
+            networkThrows += 1;
+            if (networkThrows >= maxNetworkAttempts)
+                throw err;
         }
         if (response && !policy.replayStatuses.has(response.status)) {
             return response;

package/dist/fetch-retry.js.map

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

package/dist/handle-types.d.ts

@@ -0,0 +1,150 @@
+export interface Change<T = unknown> {
+    readonly set: ReadonlyMap<string, T>;
+    readonly deleted: readonly string[];
+    readonly order?: readonly string[];
+}
+export type ChangeSource = 'local' | 'remote' | 'undo' | 'redo';
+export interface ChangeOrigin {
+    readonly source: ChangeSource;
+}
+export type MapSubscriber<T = unknown> = (change: Change<T>, origin?: ChangeOrigin) => void;
+export type InternalMapSubscriber<T> = (change: Change<T>, origin: ChangeOrigin | undefined, resync: boolean) => void;
+/**
+ * One positional edit, applied in the order the change carries them.
+ *
+ * `at` indexes the sequence as the preceding splices in the same change left
+ * it, so applying them in order to what you already hold leaves you current.
+ * That is the whole contract: a subscriber never has to ask what the list
+ * holds, because every fire says how to get from its last state to this one.
+ */
+export interface Splice<E> {
+    readonly at: number;
+    readonly removed: number;
+    readonly inserted: readonly E[];
+}
+/**
+ * What changed in a list. Fires once on registration carrying the whole list
+ * as a single splice, then on every change carrying only what moved.
+ *
+ * A registration fire and a resync are not special cases a subscriber has to
+ * recognise: both arrive as splices that replace what it was last told, so
+ * one apply loop is the entire subscriber.
+ */
+export interface ListChange<T> {
+    readonly splices: readonly Splice<T>[];
+}
+export type ListSubscriber<T = unknown> = (change: ListChange<T>) => void;
+export type InternalListSubscriber = (change: ListChange<unknown>, origin?: ChangeOrigin) => void;
+export type HandleUnsubscribe = () => void;
+export interface HandleOwner {
+    assertWritable(): void;
+    assertReadable(): void;
+    ensureLocalUpdatesSubscribed(): void;
+    commitMutate(): void;
+    originOf(event: unknown): ChangeSource;
+}
+export interface MapHandle<T = unknown> {
+    get(entryKey: string): T | undefined;
+    keys(): string[];
+    has(entryKey: string): boolean;
+    mutate(fn: (draft: Record<string, T>) => void): void;
+    subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
+    /**
+     * Report each time this container has been delivered whole: on
+     * registration, and again after a version checkout, a return to head or a
+     * hydrate replaces it.
+     *
+     * This is where the work that follows on the collection belongs rather than
+     * on any single change: frame the camera on what arrived, run the first pass
+     * over it. It repeats because that work is owed again each time the
+     * container is replaced.
+     *
+     * It reports that this peer holds what it had converged to when the delivery
+     * began, which is the only claim available: more always arrives afterwards.
+     */
+    onSettled(cb: () => void): HandleUnsubscribe;
+    map<U>(entryKey: string): MapHandle<U>;
+    list<U>(entryKey: string): ListHandle<U>;
+}
+/**
+ * The array a list `mutate` hands its callback: an ordinary `T[]` plus
+ * `move`.
+ *
+ * `move` is here because a plain array has no way to say "this entry is now
+ * at that position", and the difference matters once two people edit at once.
+ * Spelled as a removal and an insertion, a reposition merges with another
+ * peer's reposition of the SAME entry by keeping BOTH insertions, so the entry
+ * ends up in the list twice and a reader has to guess which position was
+ * meant. `move` states the reposition, and the two merge to one entry.
+ */
+export interface ListDraft<T> extends Array<T> {
+    /** Reposition the entry at `from` so it sits at `to`. Indices are clamped
+     *  to the list, and a `from` outside it does nothing. */
+    move(from: number, to: number): void;
+}
+export interface ListHandle<T = unknown> {
+    length(): number;
+    mutate(fn: (draft: ListDraft<T>) => void): void;
+    subscribe(cb: ListSubscriber<T>): HandleUnsubscribe;
+    /**
+     * Report each time this container has been delivered whole: on
+     * registration, and again after a version checkout, a return to head or a
+     * hydrate replaces it.
+     *
+     * This is where the work that follows on the collection belongs rather than
+     * on any single change: frame the camera on what arrived, run the first pass
+     * over it. It repeats because that work is owed again each time the
+     * container is replaced.
+     *
+     * It reports that this peer holds what it had converged to when the delivery
+     * began, which is the only claim available: more always arrives afterwards.
+     */
+    onSettled(cb: () => void): HandleUnsubscribe;
+}
+/**
+ * Where an ordered map puts a key.
+ *
+ * The two anchor forms name a neighbouring key, which is what a reader's
+ * gesture actually means (insert after the paragraph the caret is in, drop
+ * this step on that one) and what survives a peer editing the collection
+ * between the render and the write. `index` counts positions in `keys()`, for
+ * a surface that works in indices; anything at or past the end appends, and a
+ * negative index goes to the front.
+ *
+ * An anchor key the order list does not name puts the key at the end.
+ */
+export type OrderedMapPosition = {
+    before: string;
+} | {
+    after: string;
+} | {
+    index: number;
+};
+export interface OrderedMapHandle<T = unknown> {
+    get(entryKey: string): T | undefined;
+    has(entryKey: string): boolean;
+    keys(): string[];
+    ordered(): {
+        key: string;
+        value: T;
+    }[];
+    mutate(fn: (draft: Record<string, T>) => void): void;
+    insert(entryKey: string, value: T, at: OrderedMapPosition): void;
+    move(entryKey: string, to: OrderedMapPosition): void;
+    subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
+    /**
+     * Report each time this container has been delivered whole: on
+     * registration, and again after a version checkout, a return to head or a
+     * hydrate replaces it.
+     *
+     * This is where the work that follows on the collection belongs rather than
+     * on any single change: frame the camera on what arrived, run the first pass
+     * over it. It repeats because that work is owed again each time the
+     * container is replaced.
+     *
+     * It reports that this peer holds what it had converged to when the delivery
+     * began, which is the only claim available: more always arrives afterwards.
+     */
+    onSettled(cb: () => void): HandleUnsubscribe;
+}
+//# sourceMappingURL=handle-types.d.ts.map

package/dist/handle-types.d.ts.map

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

package/dist/handle-types.js

@@ -0,0 +1,8 @@
+// The handle surface's public types, kept apart from the `handles.ts` code
+// that implements them against Loro. Every type the package entry re-exports
+// pulls its declaring module into a consumer's typecheck graph, so declaring
+// them here is what makes the public surface engine-neutral all the way down
+// rather than only in the signatures an app calls.
+// `public-types-engine-free.test.ts` holds that line.
+export {};
+//# sourceMappingURL=handle-types.js.map

package/dist/handle-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-types.js","sourceRoot":"","sources":["../src/handle-types.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,6EAA6E;AAC7E,6EAA6E;AAC7E,6EAA6E;AAC7E,mDAAmD;AACnD,sDAAsD"}

package/dist/handles.d.ts

@@ -1,56 +1,56 @@
-import { LoroList, LoroMap } from 'loro-crdt';
+import { LoroMovableList, LoroMap } from 'loro-crdt';
 import { MutateBatcher } from './mutate-batching.js';
-export interface Change<T = unknown> {
-    readonly set: ReadonlyMap<string, T>;
-    readonly deleted: readonly string[];
-    readonly order?: readonly string[];
-}
-export type ChangeSource = 'local' | 'remote' | 'undo' | 'redo' | 'checkout';
-export interface ChangeOrigin {
-    readonly source: ChangeSource;
-}
-export type MapSubscriber<T = unknown> = (change: Change<T>, origin?: ChangeOrigin) => void;
-export type ListSubscriber = () => void;
-export type HandleUnsubscribe = () => void;
-export interface HandleOwner {
-    assertWritable(): void;
-    ensureLocalUpdatesSubscribed(): void;
-    commitMutate(): void;
-    originOf(event: unknown): ChangeSource;
-}
-export interface MapHandle<T = unknown> {
-    read(): Record<string, T>;
-    get(entryKey: string): T | undefined;
+import type { Change, ChangeOrigin, ChangeSource, HandleOwner, HandleUnsubscribe, ListDraft, ListHandle, ListSubscriber, MapHandle, MapSubscriber, OrderedMapHandle, OrderedMapPosition } from './handle-types.js';
+export type { Change, ChangeOrigin, ChangeSource, HandleOwner, ListDraft, HandleUnsubscribe, ListHandle, ListSubscriber, MapHandle, MapSubscriber, OrderedMapHandle, OrderedMapPosition, };
+/**
+ * Where a root map's ADDITIONS go once the map has paged itself part-way
+ * through a mutation.
+ *
+ * A mutation large enough to need paging usually starts against a map that
+ * is not yet paged, so the decision cannot be made once at the top. The
+ * proxy consults this on every assignment; while it declines, the mutation
+ * runs exactly as an unpaged one does.
+ */
+interface WriteDivert {
+    take(key: string, value: unknown): boolean;
+    holds(key: string): boolean;
+    peek(key: string): unknown;
+    drop(key: string): void;
     keys(): string[];
-    has(entryKey: string): boolean;
-    mutate(fn: (draft: Record<string, T>) => void): void;
-    subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
-    map<U>(entryKey: string): MapHandle<U>;
-    list<U>(entryKey: string): ListHandle<U>;
 }
-export interface ListHandle<T = unknown> {
-    read(): T[];
-    length(): number;
-    mutate(fn: (draft: T[]) => void): void;
-    subscribe(cb: ListSubscriber): HandleUnsubscribe;
-}
-export interface OrderedMapHandle<T = unknown> {
-    read(): Record<string, T>;
-    get(entryKey: string): T | undefined;
-    has(entryKey: string): boolean;
-    keys(): string[];
-    ordered(): {
-        key: string;
-        value: T;
-    }[];
-    mutate(fn: (draft: Record<string, T>) => void): void;
-    subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
+export declare function wrapLoroMapProxy(loroMap: LoroMap, batcher?: MutateBatcher, divert?: WriteDivert, guardKeys?: boolean): Record<string, unknown>;
+/**
+ * What a ROOT map handle needs from its owning Document to present a paged
+ * store. Bundled rather than passed one by one: every member is read off the
+ * ACTIVE source's `meta` at call time (a version checkout swaps the source),
+ * and a handle that can never be a paged root is given none of them.
+ */
+/**
+ * The document's version, as the freshness stamp a cached index checks.
+ *
+ * Loro's frontiers, which advance on every op whatever produced it: a local
+ * write, a remote import, an undo, a version checkout. A cached index cannot
+ * key on the map's SIZE instead, because a remote change and a local undo can
+ * leave the size they found it at while changing which keys are there, and the
+ * index then answers from keys the map no longer holds. Reading it costs about
+ * 2 us and does not close the open transaction, so a mutation still commits as
+ * one change.
+ */
+export type StateVersion = readonly {
+    peer: string;
+    counter: number;
+}[];
+export interface PagedRootHooks {
+    isPaged(): boolean;
+    page(): void;
+    sessionToken(): string;
+    stateVersion(): StateVersion;
 }
-export declare function wrapLoroMapProxy(loroMap: LoroMap, batcher?: MutateBatcher): Record<string, unknown>;
-export declare function createRootMapHandle<T>(root: LoroMap, owner: HandleOwner, pageCount?: () => number, pagingScheme?: () => number): MapHandle<T>;
-export declare function createRootListHandle<T>(root: LoroList, owner: HandleOwner): ListHandle<T>;
+export declare function createRootMapHandle<T>(root: LoroMap, owner: HandleOwner, paging?: PagedRootHooks): MapHandle<T>;
+export declare function createRootListHandle<T>(root: LoroMovableList, owner: HandleOwner): ListHandle<T>;
 export declare function rebindRootMapAnchor(handle: MapHandle<unknown>, next: LoroMap): void;
-export declare function rebindRootListAnchor(handle: ListHandle<unknown>, next: LoroList): void;
+export declare function rebindRootListAnchor(handle: ListHandle<unknown>, next: LoroMovableList): void;
+export declare function snapshotRootMapKeys(handle: MapHandle<unknown>): void;
 export declare function resyncRootHandle(handle: MapHandle<unknown> | ListHandle<unknown>): void;
 export declare function teardownRootHandle(handle: MapHandle<unknown> | ListHandle<unknown>): void;
 export declare function createOrderedMapHandle<T>(map: MapHandle<T>, order: ListHandle<string>, owner: HandleOwner): OrderedMapHandle<T>;

package/dist/handles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,eAAe,EACf,OAAO,EAIR,MAAM,WAAW,CAAC;AA8BnB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAGV,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,iBAAiB,EAGjB,SAAS,EACT,UAAU,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,kBAAkB,GACnB,CAAC;AAwSF;;;;;;;;GAQG;AACH,UAAU,WAAW;IAInB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAG3C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,IAAI,MAAM,EAAE,CAAC;CAClB;AAOD,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAKhB,OAAO,CAAC,EAAE,aAAa,EACvB,MAAM,CAAC,EAAE,WAAW,EAKpB,SAAS,UAAQ,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8FzB;AAmsED;;;;;GAKG;AACH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC;AAYxE,MAAM,WAAW,cAAc;IAE7B,OAAO,IAAI,OAAO,CAAC;IAGnB,IAAI,IAAI,IAAI,CAAC;IAEb,YAAY,IAAI,MAAM,CAAC;IAEvB,YAAY,IAAI,YAAY,CAAC;CAC9B;AAmiDD,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,WAAW,EAClB,MAAM,CAAC,EAAE,cAAc,GACtB,SAAS,CAAC,CAAC,CAAC,CAEd;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,WAAW,GACjB,UAAU,CAAC,CAAC,CAAC,CAEf;AAgBD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,EAC1B,IAAI,EAAE,OAAO,GACZ,IAAI,CAEN;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,EAC3B,IAAI,EAAE,eAAe,GACpB,IAAI,CAEN;AAcD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,CAEpE;AAMD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,GAC/C,IAAI,CAEN;AAOD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,GAC/C,IAAI,CAEN;AAKD,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,EACjB,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EACzB,KAAK,EAAE,WAAW,GACjB,gBAAgB,CAAC,CAAC,CAAC,CAMrB"}