@rljson/rljson 0.0.74 → 0.0.76

package/dist/sync/connector-payload.d.ts

@@ -0,0 +1,44 @@
+import { InsertHistoryTimeId } from '../insertHistory/insertHistory.ts';
+import { ClientId } from './client-id.ts';
+/**
+ * Wire-protocol payload transmitted between Connector and Server.
+ *
+ * The two required fields (`o`, `r`) provide backward-compatible
+ * self-echo filtering and ref identification. All other fields are
+ * optional and activate only when the corresponding `SyncConfig`
+ * flags are set.
+ *
+ * | Field   | Concept                | Purpose                                |
+ * |---------|------------------------|----------------------------------------|
+ * | `r`     | existing               | The ref being announced                |
+ * | `o`     | existing               | Ephemeral origin for self-echo filter  |
+ * | `c`     | Client identity        | Stable client id across reconnections  |
+ * | `t`     | Client identity        | Client-side wall-clock timestamp (ms)  |
+ * | `seq`   | Predecessor chain      | Monotonic counter per (client, route)  |
+ * | `p`     | Predecessor chain      | Causal predecessor timeIds             |
+ * | `cksum` | Acknowledgment         | Content checksum for ACK verification  |
+ */
+export type ConnectorPayload = {
+    /** The ref (InsertHistoryTimeId) being announced. */
+    r: string;
+    /** Ephemeral origin of the sending Connector (for self-echo filtering). */
+    o: string;
+    /** Stable client identity (survives reconnections). */
+    c?: ClientId;
+    /** Client-side wall-clock timestamp in milliseconds since epoch. */
+    t?: number;
+    /** Monotonic sequence number per (client, route) pair. */
+    seq?: number;
+    /** Causal predecessor InsertHistory timeIds. */
+    p?: InsertHistoryTimeId[];
+    /** Content checksum of the referenced data, for ACK verification. */
+    cksum?: string;
+};
+/**
+ * Returns a minimal example ConnectorPayload (backward-compatible format).
+ */
+export declare const connectorPayloadExample: () => ConnectorPayload;
+/**
+ * Returns a fully-populated example ConnectorPayload with all optional fields.
+ */
+export declare const connectorPayloadFullExample: () => ConnectorPayload;

package/dist/sync/gap-fill.d.ts

@@ -0,0 +1,41 @@
+import { InsertHistoryTimeId } from '../insertHistory/insertHistory.ts';
+import { ConnectorPayload } from './connector-payload.ts';
+/**
+ * Client → Server request for missing refs on a specific route.
+ *
+ * Sent on the `${route}:gapfill:req` event when a Connector detects
+ * a gap in the sequence numbers it has received from a peer.
+ */
+export type GapFillRequest = {
+    /** The route for which refs are missing. */
+    route: string;
+    /** The last sequence number the client has successfully processed. */
+    afterSeq: number;
+    /**
+     * Alternative / additional anchor: the last known InsertHistory timeId.
+     * The server may use this to determine the starting point if sequence
+     * numbers are unavailable.
+     */
+    afterTimeId?: InsertHistoryTimeId;
+};
+/**
+ * Server → Client response containing the missing refs.
+ *
+ * Sent on the `${route}:gapfill:res` event in response to a
+ * `GapFillRequest`. The `refs` array is ordered chronologically
+ * (oldest first).
+ */
+export type GapFillResponse = {
+    /** The route this response corresponds to. */
+    route: string;
+    /** Ordered list of missing payloads (oldest first). */
+    refs: ConnectorPayload[];
+};
+/**
+ * Returns an example GapFillRequest.
+ */
+export declare const gapFillRequestExample: () => GapFillRequest;
+/**
+ * Returns an example GapFillResponse with two missing refs.
+ */
+export declare const gapFillResponseExample: () => GapFillResponse;

package/dist/sync/sync-config.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Feature flags for hardened sync behavior.
+ *
+ * All flags default to `false` / `undefined`, so existing code that
+ * does not set a `SyncConfig` continues to work exactly as before.
+ *
+ * | Flag                    | Concept              | Effect when enabled                    |
+ * |-------------------------|----------------------|----------------------------------------|
+ * | `causalOrdering`        | Predecessor chain    | Attach `seq` + `p` to payloads;        |
+ * |                         |                      | detect gaps; request gap-fill          |
+ * | `requireAck`            | Acknowledgment       | Wait for server ACK after send         |
+ * | `ackTimeoutMs`          | Acknowledgment       | Timeout before treating ACK as failed  |
+ * | `includeClientIdentity` | Client identity      | Attach `c` + `t` to payloads           |
+ * | `maxDedupSetSize`       | Memory management    | Cap dedup sets; default 10 000         |
+ */
+export type SyncConfig = {
+    /**
+     * When `true`, the Connector attaches a monotonic `seq` number and
+     * causal predecessor timeIds (`p`) to every outgoing payload. Receiving
+     * Connectors detect sequence gaps and request gap-fill from the server.
+     */
+    causalOrdering?: boolean;
+    /**
+     * When `true`, the Connector awaits a server-side `AckPayload` after
+     * sending a ref. The `sendWithAck()` method becomes available.
+     */
+    requireAck?: boolean;
+    /**
+     * Timeout in milliseconds for awaiting an ACK from the server.
+     * Only meaningful when `requireAck` is `true`.
+     * Defaults to `10_000` (10 seconds) when not specified.
+     */
+    ackTimeoutMs?: number;
+    /**
+     * When `true`, the Connector attaches the stable `ClientId` (`c`) and
+     * a wall-clock timestamp (`t`) to every outgoing payload.
+     */
+    includeClientIdentity?: boolean;
+    /**
+     * Maximum number of entries per dedup set generation before rotation.
+     * The Connector uses two-generation eviction: when the current generation
+     * exceeds this limit, it becomes the previous generation and a new empty
+     * set is created. Lookups check both generations.
+     * Defaults to `10_000` when not specified.
+     */
+    maxDedupSetSize?: number;
+    /**
+     * Interval in milliseconds for the server to broadcast its latest ref
+     * to all connected clients as a heartbeat. This acts as a fallback
+     * in case the initial bootstrap message on connect was missed.
+     *
+     * When `undefined` or `0`, no periodic heartbeat is sent — only the
+     * immediate bootstrap on `addSocket()` is active.
+     *
+     * Recommended value: `30_000` (30 seconds) or higher.
+     */
+    bootstrapHeartbeatMs?: number;
+};
+/**
+ * Default SyncConfig — all features disabled (backward-compatible mode).
+ */
+export declare const syncConfigDefault: () => SyncConfig;
+/**
+ * Returns an example SyncConfig with all features enabled.
+ */
+export declare const syncConfigFullExample: () => SyncConfig;
+/**
+ * Returns an example SyncConfig with only causal ordering enabled.
+ */
+export declare const syncConfigCausalOnlyExample: () => SyncConfig;

package/dist/sync/sync-events.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The set of socket event names used by the sync protocol for a given route.
+ * Using this helper avoids hard-coding event name strings across layers
+ * and prevents typos.
+ * @example
+ * ```ts
+ * const events = syncEvents('/sharedTree');
+ * socket.on(events.ref, handleRef);
+ * socket.on(events.ack, handleAck);
+ * socket.emit(events.gapFillReq, request);
+ * ```
+ */
+export type SyncEventNames = {
+    /** Bidirectional: ref broadcast (existing event). */
+    ref: string;
+    /** Server → Client: delivery acknowledgment. */
+    ack: string;
+    /** Client → Server: individual client ACK of a received ref. */
+    ackClient: string;
+    /** Client → Server: request missing refs. */
+    gapFillReq: string;
+    /** Server → Client: supply missing refs. */
+    gapFillRes: string;
+    /** Server → Client: bootstrap latest ref on connect / heartbeat. */
+    bootstrap: string;
+};
+/**
+ * Creates typed, route-specific socket event names for the sync protocol.
+ * @param route - The route string (e.g. `"/sharedTree"`)
+ * @returns An object with all sync event names derived from the route
+ */
+export declare const syncEvents: (route: string) => SyncEventNames;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/rljson",
-  "version": "0.0.74",
+  "version": "0.0.76",
   "description": "The RLJSON data format specification",
   "homepage": "https://github.com/rljson/rljson",
   "bugs": "https://github.com/rljson/rljson/issues",
@@ -20,24 +20,24 @@
   ],
   "type": "module",
   "devDependencies": {
-    "@types/node": "^25.0.9",
-    "@typescript-eslint/eslint-plugin": "^8.53.1",
-    "@typescript-eslint/parser": "^8.53.1",
-    "@vitest/coverage-v8": "^4.0.17",
+    "@types/node": "^25.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.55.0",
+    "@typescript-eslint/parser": "^8.55.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "cross-env": "^10.1.0",
     "eslint": "^9.39.2",
-    "eslint-plugin-jsdoc": "^62.2.0",
+    "eslint-plugin-jsdoc": "^62.5.0",
     "eslint-plugin-tsdoc": "^0.5.0",
-    "globals": "^17.0.0",
+    "globals": "^17.3.0",
     "jsdoc": "^4.0.5",
-    "read-pkg": "^10.0.0",
+    "read-pkg": "^10.1.0",
     "typescript": "~5.9.3",
-    "typescript-eslint": "^8.53.1",
+    "typescript-eslint": "^8.55.0",
     "vite": "^7.3.1",
     "vite-node": "^5.3.0",
     "vite-plugin-dts": "^4.5.4",
-    "vite-tsconfig-paths": "^6.0.4",
-    "vitest": "^4.0.17",
+    "vite-tsconfig-paths": "^6.1.0",
+    "vitest": "^4.0.18",
     "vitest-dom": "^0.1.1"
   },
   "dependencies": {