@interncom/diplomatic 0.3.2 → 0.3.4

package/dist/web/openClient.d.ts

@@ -13,6 +13,16 @@ import type { IClient, IStore } from "./types";
  * (built as `worker.mjs` in the published package). It must run as a
  * **module** worker (`type: "module"`).
  *
+ * ## Handshake (race-safe)
+ *
+ * The worker posts an unsolicited `{ kind: "ready" }` after init. Apps often
+ * construct the Worker at module load (or before `openDiplomaticClient` finishes
+ * opening IndexedDB), so that event can fire before the library sets
+ * `onmessage`. **That is fine:** connect also probes with a request/response
+ * `ping`. The worker holds commands until init completes, so the probe succeeds
+ * even if `ready` was dropped. Do **not** reimplement message buffering in the
+ * app unless you need it for other reasons.
+ *
  * ## Vite (recommended for SPA templates)
  *
  * ```ts
@@ -23,6 +33,7 @@ import type { IClient, IStore } from "./types";
  *
  * `?worker` makes Vite emit a real worker asset and a constructor. Create the
  * instance once (module scope or `useMemo`/`useRef`) — not on every render.
+ * Early construction is supported; the handshake recovers if `ready` is missed.
  *
  * ## webpack / Rollup / esbuild / Parcel (`new URL` + import.meta.url)
  *

package/dist/web/react/useClient.d.ts

@@ -19,11 +19,16 @@ type UseClientBase = {
  *   import DiplomaticWorker from "@interncom/diplomatic/worker?worker";
  *   const syncWorker = new DiplomaticWorker();
  *   useClient({ worker: syncWorker, seed, host });
+ *
+ * Handshake is race-safe (ready event and/or probe ping). See
+ * `openDiplomaticClient` for bundler recipes and handshake notes.
  */
 export type UseClientWorkerOptions = UseClientBase & {
     /**
      * App-constructed sync Worker. Create once (module scope or useMemo/useRef),
-     * not each render. See `openDiplomaticClient` for instantiation recipes.
+     * not each render. Early construction before `useClient` opens IDB is OK —
+     * the library does not require catching the unsolicited `ready` event.
+     * See `openDiplomaticClient` for instantiation recipes.
      */
     worker: Worker;
     store?: never;

package/dist/web/stores/idb/store.d.ts

@@ -10,7 +10,10 @@ export declare const HOSTS_TABLE = "hosts";
 export declare const UPLOAD_QUEUE_TABLE = "uploadQueue";
 export declare const DOWNLOAD_QUEUE_TABLE = "downloadQueue";
 export declare const MESSAGES_TABLE = "messages";
-/** Index on messages.apld — pending apply is apld === false. */
+/**
+ * Index on messages.apld. Values are "f" (pending) / "t" (applied) —
+ * booleans are not valid IndexedDB keys; single-char strings keep keys compact.
+ */
 export declare const MESSAGES_APLD_INDEX = "apld";
 /** Schema version: v3 adds messages.apld index for the apply queue. */
 export declare const DIPLOMATIC_STORE_DB_VERSION = 3;

package/dist/web/types.d.ts

@@ -77,15 +77,17 @@ export interface IStoredMessageFields {
     body?: EncodedMessage;
 }
 /**
- * What may come back from IDB (pre-apld rows can omit the field).
+ * What may come back from storage (pre-apld rows can omit the field).
+ * IDB stores "t"|"f" (booleans are not valid IndexedDB index keys).
  * Prefer {@link normalizeStoredMessageData} before use.
  */
 export interface IStoredMessageData extends IStoredMessageFields {
-    apld?: boolean;
+    apld?: boolean | "t" | "f";
 }
 /**
- * Required shape for every put into the message archive.
+ * Required shape for every put into the message archive (app/API layer).
  * Callers must set `apld` (false until applied, then true).
+ * The IDB adapter persists this as "t"|"f" for indexing.
  */
 export type IStoredMessageWrite = IStoredMessageFields & {
     apld: boolean;
@@ -100,7 +102,12 @@ export interface IStoredMessage {
     body?: EncodedMessage;
     applied: boolean;
 }
-/** Coerce legacy rows missing `apld` to pending (`false`). */
+/**
+ * Coerce stored `apld` to boolean.
+ * Applied: true | "t". Pending: false | "f" | missing.
+ */
+export declare function apldFromStored(v: unknown): boolean;
+/** Coerce storage rows to the write shape with boolean apld. */
 export declare function normalizeStoredMessageData(data: IStoredMessageData): IStoredMessageWrite;
 /** Pending apply when not yet marked applied. */
 export declare function isPendingApply(data: IStoredMessageData): boolean;

package/dist/web/worker/client.d.ts

@@ -8,11 +8,19 @@ import type { IClient, IDiplomaticClientState, IDiplomaticClientXferState, IHost
  *
  * Provide a live `Worker` — the library never constructs one. See
  * `openDiplomaticClient` for bundler/CDN instantiation recipes.
+ *
+ * Handshake is race-safe: the worker posts unsolicited `{ kind: "ready" }`, but
+ * connect also probes with `ping`. Early construction (module scope) is fine even
+ * if `ready` fired before `onmessage` was set — the ping still succeeds once the
+ * worker has finished init (cmds are held until then on the worker side).
  */
 export type WorkerClientOptions = {
     /** Already-constructed module Worker running `@interncom/diplomatic/worker`. */
     worker: Worker;
-    /** Max wait for worker `ready` (default 15s). Failures throw; no fallback. */
+    /**
+     * Max wait for handshake (`ready` event or probe ping; default 15s).
+     * Failures throw; no fallback.
+     */
     readyTimeoutMs?: number;
     clock?: IClock;
     /**
@@ -48,8 +56,19 @@ export declare class WorkerClient implements IClient<URL> {
      * Attach to an app-provided Worker. `store` is the shared protocol IDB (main
      * connection) used for local msg writes; worker opens its own connection.
      * Throws if the worker never becomes ready — does not fall back to main thread.
+     *
+     * Handshake: wait for unsolicited `ready` **or** a successful probe `ping`.
+     * The probe covers the common case where the app started the Worker early and
+     * `ready` was dropped before this thread set `onmessage`.
      */
     static connect(state: IStateManager, store: IStore<URL>, opts: WorkerClientOptions): Promise<WorkerClient>;
+    /** Resolve the ready barrier (idempotent). */
+    private markReady;
+    /**
+     * Active handshake: post ping without waiting for the ready event.
+     * On pong, mark ready so connect can proceed even if `ready` was missed.
+     */
+    private probeReady;
     /** Lightweight RPC check after connect. */
     ping(): Promise<void>;
     /** Terminate the worker (drops protocol DB connection in that thread). */

package/dist/web/worker/runtime.d.ts

@@ -4,8 +4,14 @@ export type PostFn = (msg: WorkerEvent, transfer?: Transferable[]) => void;
 export declare class WorkerRuntime {
     private client;
     private post;
+    /** Resolves when init finishes (success or failure). Cmds wait on this. */
+    private whenReady;
+    private resolveReady;
+    private rejectReady;
     constructor(post: PostFn);
     init(): Promise<void>;
+    private markReady;
+    private failReady;
     private requireClient;
     private emitClientState;
     private emitXferState;