@rljson/rljson 0.0.75 → 0.0.76

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.75",
+  "version": "0.0.76",
   "description": "The RLJSON data format specification",
   "homepage": "https://github.com/rljson/rljson",
   "bugs": "https://github.com/rljson/rljson/issues",
@@ -20,23 +20,23 @@
   ],
   "type": "module",
   "devDependencies": {
-    "@types/node": "^25.1.0",
-    "@typescript-eslint/eslint-plugin": "^8.54.0",
-    "@typescript-eslint/parser": "^8.54.0",
+    "@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.5.0",
     "eslint-plugin-tsdoc": "^0.5.0",
-    "globals": "^17.2.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.54.0",
+    "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.5",
+    "vite-tsconfig-paths": "^6.1.0",
     "vitest": "^4.0.18",
     "vitest-dom": "^0.1.1"
   },