@interncom/diplomatic 0.2.6 → 0.3.0

package/dist/web/client.d.ts

@@ -12,6 +12,11 @@ export declare class SyncClient<Handle extends HostHandle> implements IClient<Ha
     private transport;
     private crypto;
     private forceSkewHandlingByDefault;
+    /**
+     * When set (e.g. main-thread local writer next to a sync worker), called
+     * instead of running sync on this client. Use to hand off push to the worker.
+     */
+    private onScheduleSync?;
     connections: Map<string, DiplomaticClientAPI<Handle>>;
     /**
      * Serializes sync so doSync never overlaps, while coalescing stampedes:
@@ -19,6 +24,11 @@ export declare class SyncClient<Handle extends HostHandle> implements IClient<Ha
      * pass if more sync was requested mid-flight (see CoalesceTail).
      */
     private syncRuns;
+    /**
+     * Serializes application of archived msgs so concurrent apply /
+     * drainApplyQueue do not interleave markApplied (each job runs fully, in order).
+     */
+    private applyChain;
     clientState: IStateEmitter<IDiplomaticClientState>;
     xferState: IStateEmitter<IDiplomaticClientXferState>;
     /**
@@ -27,13 +37,56 @@ export declare class SyncClient<Handle extends HostHandle> implements IClient<Ha
      */
     maxPushBytes: number;
     maxPullBytes: number;
-    constructor(clock: IClock, state: IStateManager, store: IStore<Handle>, transport: (host: IHostConnectionInfo<Handle>) => ITransport, crypto: ICrypto, forceSkewHandlingByDefault?: boolean, maxPushBytes?: number, maxPullBytes?: number);
-    private readonly SYNC_DEBOUNCE_DELAY_MS;
-    private syncTimeout;
+    /**
+     * Peek progress stride in heads (see `defaultPeekProgressEvery`).
+     * Emits on head 1, every N heads, and the last head.
+     */
+    peekProgressEvery: number;
+    /** Latest progress; part of xferState for snapshot + subscribe. */
+    private lastProgress;
+    /**
+     * Debounced sync after local writes (when not handing off via onScheduleSync).
+     */
+    private scheduledSync;
+    constructor(clock: IClock, state: IStateManager, store: IStore<Handle>, transport: (host: IHostConnectionInfo<Handle>) => ITransport, crypto: ICrypto, forceSkewHandlingByDefault?: boolean, maxPushBytes?: number, maxPullBytes?: number, 
+    /**
+     * When set (e.g. main-thread local writer next to a sync worker), called
+     * instead of running sync on this client. Use to hand off push to the worker.
+     */
+    onScheduleSync?: (() => void) | undefined);
+    /** Record phase progress and notify xferState listeners. */
+    private emitProgress;
     setSeed(seed: MasterSeed): Promise<void>;
     private getClientState;
     private getXferState;
+    /**
+     * Persist msgs to the archive as unapplied (apld=false), apply via
+     * IStateManager, mark applied, then optionally enqueue upload.
+     *
+     * Order is intentional for crash safety:
+     * 1) durable archive  2) apply + apld=true  3) upload queue
+     * so we never upload something that never applied, and crash between
+     * 1–2 is recovered by drainApplyQueue.
+     */
     private apply;
+    private enqueueApplyJob;
+    /**
+     * Apply archived msgs that are still unapplied (crash recovery).
+     * Call after open / connect so a crash between store and apply is healed.
+     */
+    drainApplyQueue(): Promise<Status[]>;
+    private doDrainApplyQueue;
+    /** Apply specific archive keys via IStateManager and mark applied. */
+    private applyHashes;
+    /**
+     * Apply a batch of archived msgs via IStateManager and mark successes applied.
+     *
+     * TODO: may need to chunk large batches (memory / IDB / UI). Also test edge
+     * cases: state.apply returning stats.length !== msgs.length (short/long
+     * array, holes) — markApplied currently indexes stats[i] against stored[i]
+     * without validating length alignment.
+     */
+    private applyStored;
     insertRaw(bod: EncodedMessage): Promise<ValStat<IMessageHead>>;
     upsertRaw(eid: EntityID, bod: EncodedMessage | undefined, force?: boolean): Promise<ValStat<IMessageHead>>;
     insert<T = unknown>(op: IInsertParams<T>): Promise<ValStat<IMessageHead>>;
@@ -52,7 +105,13 @@ export declare class SyncClient<Handle extends HostHandle> implements IClient<Ha
     import: (file: File, options?: {
         onProgress?: (index: number, total: number, status: Status) => void;
     }) => Promise<Status>;
+    /**
+     * After local apply + upload enqueue: either hand off to a peer (worker via
+     * onScheduleSync — debounced there) or debounce sync on this client.
+     */
     private scheduleSync;
+    /** Encode the local message archive; used by worker path (main saves file). */
+    exportBytes(): Promise<ValStat<Uint8Array>>;
     export(filename: string): Promise<Status.Success | import("./shared/valstat").StatusNOK>;
     link(host: IHostConnectionInfo<Handle>, connect?: boolean): Promise<void>;
     unlink(label: string): Promise<void>;

package/dist/web/coalesce.d.ts

@@ -18,5 +18,35 @@ export declare class CoalesceTail<T> {
     private inflight;
     private again;
     run(work: () => Promise<T>): Promise<T>;
+    /** Wait for any in-flight drain to finish (does not request a new pass). */
+    flush(): Promise<void>;
     private drain;
 }
+/** Default quiet period before a scheduled sync after local writes. */
+export declare const defaultSyncDebounceMs = 100;
+/**
+ * Debounce async work: each `schedule()` resets a timer; when the quiet period
+ * elapses, `work` runs via {@link CoalesceTail} so stampeding fires do not
+ * overlap (trailing pass if more demand arrives mid-run).
+ *
+ * - `delayMs <= 0`: run on the next microtask path immediately (no timer).
+ * - `flush()`: cancel the timer, start work if a run was pending, await drain.
+ * - `cancel()`: drop the pending timer without running (in-flight continues).
+ */
+export declare class Debounced<T = void> {
+    private timer;
+    private readonly delayMs;
+    private readonly work;
+    private readonly tail;
+    constructor(delayMs: number, work: () => Promise<T>);
+    /** Request a run after the debounce quiet period (resets the timer). */
+    schedule(): void;
+    /**
+     * Run any pending debounced work now and wait until the drain finishes.
+     * No-op if nothing is pending or in flight.
+     */
+    flush(): Promise<void>;
+    /** Drop a pending timer without starting work. In-flight work is untouched. */
+    cancel(): void;
+    private fire;
+}

package/dist/web/index.d.ts

@@ -17,10 +17,16 @@ import { nullStateManager, StateManager } from "./state";
 import { IDBStore, openIDBStore } from "./stores/idb/store";
 import { MemoryStore } from "./stores/memory/store";
 import { SingletonStateManager } from "./shared/singleton";
-import type { Applier, IDiplomaticClientState, IStore, IStoredMessage, IStoredMessageData } from "./types";
+import type { Applier, IClient, IDiplomaticClientState, IStore, IStoredMessage, IStoredMessageData, IStoredMessageWrite } from "./types";
+import { isPendingApply, normalizeStoredMessageData } from "./types";
+import type { SyncProgressEvent } from "./progress";
+import { defaultPeekProgressEvery, idleProgress, shouldEmitItemProgress } from "./progress";
+import { openDiplomaticClient, type OpenDiplomaticClientMainOptions, type OpenDiplomaticClientOptions, type OpenDiplomaticClientWorkerOptions, type OpenedDiplomaticClient } from "./openClient";
+import { WorkerClient } from "./worker/client";
+import type { WorkerClientOptions } from "./worker/client";
 export declare function genWebClient(stateMgr: IStateManager, url: URL): Promise<{
     client: SyncClient<URL>;
     setSeed: (seedHex: string) => Promise<void>;
 }>;
-export { btoh, Clock, crypto, Decoder, eidCodec, Encoder, EntDBMemory, EntIDB, EntitiesQuery, EntityID, entStateManager, genSingletonEID, GroupID, hostHTTPTransport, htob, HTTPTransport, IDBStore, IEntDB, IEntity, IStore, MasterSeed, MemoryStore, nullEntDB, nullStateManager, openEntIDB, openIDBStore, SingletonStateManager, StateManager, Status, SyncClient, TypedEventEmitter, useClient, useClientState, useClientXferState, useStateWatcher, useStateWatcherSuspense, useSyncOnResume, };
-export type { Applier, HostHandle, ICrypto, IDiplomaticClientState, IHostConnectionInfo, IMessage, IMutateOp, IOp, IStateManager, IStoredMessage, IStoredMessageData, ITransport, };
+export { btoh, Clock, crypto, Decoder, defaultPeekProgressEvery, eidCodec, Encoder, EntDBMemory, EntIDB, EntitiesQuery, EntityID, entStateManager, genSingletonEID, GroupID, hostHTTPTransport, htob, HTTPTransport, IDBStore, idleProgress, IEntDB, IEntity, isPendingApply, IStore, MasterSeed, MemoryStore, normalizeStoredMessageData, nullEntDB, nullStateManager, openDiplomaticClient, openEntIDB, openIDBStore, shouldEmitItemProgress, SingletonStateManager, StateManager, Status, SyncClient, TypedEventEmitter, useClient, useClientState, useClientXferState, useStateWatcher, useStateWatcherSuspense, useSyncOnResume, WorkerClient, };
+export type { Applier, HostHandle, IClient, ICrypto, IDiplomaticClientState, IHostConnectionInfo, IMessage, IMutateOp, IOp, IStateManager, IStoredMessage, IStoredMessageData, IStoredMessageWrite, ITransport, OpenDiplomaticClientMainOptions, OpenDiplomaticClientOptions, OpenDiplomaticClientWorkerOptions, OpenedDiplomaticClient, SyncProgressEvent, WorkerClientOptions, };