@adobe/data-sync 0.9.90

package/dist/create-sync-server.js

@@ -0,0 +1,156 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Creates a sync server that accepts client proposals, assigns canonical
+ * commit timestamps, and broadcasts committed envelopes to all connected
+ * clients.
+ *
+ * The server is intentionally minimal:
+ * - It does **not** maintain a database — it is a pure ordering service.
+ * - Proposals are accepted in FIFO order (first-come-first-served).
+ * - No authentication or validation is performed here; layer those on top via
+ *   a middleware pattern (intercept `propose` messages before passing to
+ *   `SyncServer`).
+ *
+ * @example
+ * ```ts
+ * const server = createSyncServer();
+ * // When a WebSocket opens:
+ * const disconnect = server.connect(webSocketServerTransport);
+ * // When the WebSocket closes:
+ * disconnect();
+ * ```
+ */
+const generateId = () => typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+    ? crypto.randomUUID()
+    : Math.random().toString(36).slice(2) + Date.now().toString(36);
+export const createSyncServer = (options = {}) => {
+    const { livenessTimeoutMs = 25_000, logger } = options;
+    const log = logger ?? (() => undefined);
+    const sessionId = generateId();
+    log(`session ${sessionId} starting`);
+    const clients = new Set();
+    const unsubscribers = new Map();
+    const lastInboundAt = new Map();
+    // Ordered log of every committed envelope. Replayed to new clients on
+    // connect so they can reconstruct the current committed state without a
+    // separate snapshot mechanism.
+    const committedLog = [];
+    let nextTime = 1;
+    const handleMessage = (origin, msg) => {
+        // Record liveness for any inbound message — pings are explicit, but a
+        // chatty client that's actively sending proposals also counts as alive.
+        lastInboundAt.set(origin, Date.now());
+        if (msg.kind === "ping") {
+            origin.send({ kind: "pong" });
+            return;
+        }
+        if (msg.kind === "hello") {
+            const clientSessionId = msg.sessionId;
+            const lastAppliedTime = msg.lastAppliedTime;
+            const maxServerTime = committedLog.length > 0 ? committedLog[committedLog.length - 1].time : 0;
+            // A fresh client (no prior session id) always gets the full log with
+            // resetRequired:false — its database is empty so no reset is needed.
+            // A returning client with a mismatched session or a watermark ahead
+            // of the server must reset and replay from scratch.
+            const sessionMismatch = clientSessionId !== undefined && clientSessionId !== sessionId;
+            const clientAhead = lastAppliedTime > maxServerTime;
+            const resetRequired = sessionMismatch || clientAhead;
+            const replayCount = committedLog.filter(e => e.time > (resetRequired ? 0 : lastAppliedTime)).length;
+            log(`hello in (priorSession=${clientSessionId ?? "<fresh>"}, watermark=${lastAppliedTime}) → welcome (resetRequired=${resetRequired}, replaying=${replayCount})`);
+            origin.send({ kind: "welcome", sessionId, resetRequired });
+            // Replay the tail the client is missing (or the full log if reset needed).
+            const fromTime = resetRequired ? 0 : lastAppliedTime;
+            for (const envelope of committedLog) {
+                if (envelope.time > fromTime) {
+                    origin.send({ kind: "committed", envelope });
+                }
+            }
+        }
+        else if (msg.kind === "propose") {
+            const committed = {
+                ...msg.envelope,
+                time: nextTime++,
+            };
+            committedLog.push(committed);
+            log(`propose in (id=${msg.envelope.id}, name=${msg.envelope.name}) → committed at time=${committed.time}, broadcast to ${clients.size}`);
+            // Echo to ALL clients (including proposer, which promotes its transient).
+            for (const c of clients) {
+                c.send({ kind: "committed", envelope: committed });
+            }
+        }
+        else if (msg.kind === "cancel") {
+            log(`cancel in (id=${msg.id}) → broadcast to ${clients.size}`);
+            for (const c of clients) {
+                c.send({ kind: "cancelled", id: msg.id });
+            }
+        }
+        else if (msg.kind === "intermediate") {
+            // Speculative intermediate — relay to peers, never logged.
+            for (const c of clients) {
+                if (c !== origin)
+                    c.send({ kind: "committed", envelope: { ...msg.envelope } });
+            }
+        }
+    };
+    const connect = (transport) => {
+        // Add to the live set immediately so live commits during the replay
+        // window are forwarded to this client too.
+        clients.add(transport);
+        lastInboundAt.set(transport, Date.now());
+        log(`client connected (now ${clients.size} client${clients.size === 1 ? "" : "s"})`);
+        // Do NOT replay history here — wait for the client's `hello` which
+        // tells us what tail (if any) it already has.
+        const unsub = transport.onMessage(msg => handleMessage(transport, msg));
+        unsubscribers.set(transport, [unsub]);
+        return () => {
+            for (const fn of unsubscribers.get(transport) ?? [])
+                fn();
+            unsubscribers.delete(transport);
+            clients.delete(transport);
+            lastInboundAt.delete(transport);
+            transport.close();
+        };
+    };
+    // Per-client liveness sweep. We close transports that haven't sent any
+    // inbound traffic for longer than livenessTimeoutMs; closing fires the
+    // host-side onClose listeners so the negotiation layer can drive its
+    // disconnect/reconnect flow.
+    let livenessTimer;
+    if (livenessTimeoutMs > 0) {
+        const checkInterval = Math.max(50, Math.floor(livenessTimeoutMs / 4));
+        livenessTimer = setInterval(() => {
+            const now = Date.now();
+            for (const transport of clients) {
+                const last = lastInboundAt.get(transport) ?? now;
+                if (now - last > livenessTimeoutMs) {
+                    log(`client liveness timeout — disconnecting (${now - last}ms silent)`);
+                    // close() triggers our own onClose paths via the transport
+                    // adapter, but we also clean the local maps eagerly.
+                    clients.delete(transport);
+                    lastInboundAt.delete(transport);
+                    for (const fn of unsubscribers.get(transport) ?? [])
+                        fn();
+                    unsubscribers.delete(transport);
+                    transport.close();
+                }
+            }
+        }, checkInterval);
+    }
+    const dispose = () => {
+        log(`dispose (${clients.size} client${clients.size === 1 ? "" : "s"})`);
+        if (livenessTimer !== undefined) {
+            clearInterval(livenessTimer);
+            livenessTimer = undefined;
+        }
+        for (const transport of clients) {
+            for (const fn of unsubscribers.get(transport) ?? [])
+                fn();
+            transport.close();
+        }
+        clients.clear();
+        unsubscribers.clear();
+        lastInboundAt.clear();
+    };
+    return { sessionId, connect, dispose };
+};
+//# sourceMappingURL=create-sync-server.js.map

package/dist/create-sync-server.js.map

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

package/dist/create-sync-service.d.ts

@@ -0,0 +1,120 @@
+import { type Database } from "@adobe/data/ecs";
+import type { ClientTransport } from "./transport.js";
+/**
+ * Options for {@link createSyncService}.
+ */
+export interface SyncServiceOptions {
+    /**
+     * The database to wire into the sync layer. Must have been created with
+     * `createRebaseReplayConcurrency(userId)` as its concurrency strategy,
+     * where `userId` is unique per peer — the reconciler's transient queue
+     * uses `(userId, id)` as its compound key to keep concurrent peers from
+     * colliding, and the deferred-commit semantics are required for cross-peer
+     * entity-id determinism.
+     */
+    readonly database: Database<any, any, any, any>;
+    /** Transport connecting this peer to the sync server. */
+    readonly transport: ClientTransport;
+    /**
+     * Maximum `"intermediate"` messages forwarded per second. Intermediate
+     * samples beyond this rate are silently dropped. Commits and cancels
+     * are always forwarded immediately.
+     *
+     * Defaults to 20 (one per ~50 ms).
+     */
+    readonly maxIntermediatesPerSecond?: number;
+    /**
+     * Session id received from a previous connection's `welcome` message.
+     * Omit (or pass `undefined`) for a fresh client. If the server echoes back
+     * the same id in `welcome`, it replays only the tail; otherwise it signals
+     * a full reset and replay.
+     */
+    readonly priorSessionId?: string;
+    /**
+     * Highest committed `time` already applied to `database` from a previous
+     * connection. The server uses this as the replay start point when the
+     * session matches. Defaults to `0` (full replay).
+     */
+    readonly initialWatermark?: number;
+    /**
+     * Called once when the server's `welcome` message arrives, before any
+     * replay envelopes are applied. Use this to call `database.reset()` when
+     * `resetRequired` is true. Because it runs before the replay buffer is
+     * flushed, it is safe to reset the database inside this callback.
+     */
+    readonly onWelcome?: (msg: {
+        sessionId: string;
+        resetRequired: boolean;
+    }) => void;
+    /**
+     * Interval between outbound `ping` keep-alives, in milliseconds. Pings
+     * keep intermediate NAT mappings warm and let the peer detect a silent
+     * drop faster than the underlying transport's own heartbeat. Pass `0` to
+     * disable ping sending (the service will still observe inbound traffic
+     * for liveness if `livenessTimeoutMs > 0`). Defaults to `10_000`.
+     */
+    readonly pingIntervalMs?: number;
+    /**
+     * Maximum gap between inbound messages before the transport is considered
+     * dead. When exceeded the service calls `transport.close()`, which fires
+     * the transport's `onClose` listeners — application code typically wires
+     * those to a reconnect flow. Pass `0` to disable liveness checking.
+     * Defaults to `25_000`.
+     */
+    readonly livenessTimeoutMs?: number;
+    /**
+     * Optional sink for human-readable lifecycle messages — handshake,
+     * commits, cancels, liveness events, dispose. Pings/pongs are
+     * intentionally not logged (too noisy). The library itself never imports
+     * `console`, so consumers that want visibility wire one up explicitly:
+     *
+     *     logger: (m) => console.log(`[sync] ${m}`)
+     */
+    readonly logger?: (msg: string) => void;
+}
+/**
+ * Background service returned by {@link createSyncService}. It owns no public
+ * mutation surface — all mutations flow through `db.transactions.X(args)`.
+ */
+export interface SyncService {
+    /** Stop forwarding, unsubscribe from the transport, and close it. */
+    readonly dispose: () => void;
+    /** The highest committed `time` applied to the database so far. */
+    readonly lastAppliedTime: () => number;
+    /** The session id received from the server's `welcome` message, or `undefined` if not yet connected. */
+    readonly sessionId: () => string | undefined;
+}
+/**
+ * Wires a {@link Database} to a {@link ClientTransport} so that every
+ * locally-initiated transaction is automatically replicated to peers, and
+ * every server-broadcast envelope is automatically applied to the local DB.
+ *
+ * The service is a pure subscriber — application code only ever calls
+ * `db.transactions.X(args)`. It mirrors the shape of
+ * `createStoragePersistenceService`: side-effect lifecycle attached to a DB.
+ *
+ * Forwarding rules:
+ * - `db.observe.envelopes` fires once per locally-initiated envelope (the
+ *   wrapper notifies it after `applyEnvelope` returns). Replays inside the
+ *   reconciler and inbound `db.apply()` calls do NOT fire it, so there is
+ *   no bounce-back to filter.
+ * - Envelopes whose `TransactionResult.persistent === false` (i.e. they only
+ *   touched non-persistent resources/entities) are skipped. UI-only state lives
+ *   inside the same database without ever reaching the wire.
+ * - `time > 0` → `kind: "propose"` (reliable).
+ * - `time < 0` → `kind: "intermediate"` (rate-limited, lossy).
+ * - `time === 0` → `kind: "cancel"` (reliable).
+ *
+ * @example
+ * ```ts
+ * const db = Database.create(myPlugin, {
+ *     concurrency: createRebaseReplayConcurrency(crypto.randomUUID()),
+ * });
+ * const sync = createSyncService({ database: db, transport: ws });
+ *
+ * db.transactions.spawnUnit({ x: 0, y: 0, hp: 100 });
+ *
+ * sync.dispose();
+ * ```
+ */
+export declare const createSyncService: (options: SyncServiceOptions) => SyncService;

package/dist/create-sync-service.js

@@ -0,0 +1,192 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity } from "@adobe/data/ecs";
+/**
+ * Wires a {@link Database} to a {@link ClientTransport} so that every
+ * locally-initiated transaction is automatically replicated to peers, and
+ * every server-broadcast envelope is automatically applied to the local DB.
+ *
+ * The service is a pure subscriber — application code only ever calls
+ * `db.transactions.X(args)`. It mirrors the shape of
+ * `createStoragePersistenceService`: side-effect lifecycle attached to a DB.
+ *
+ * Forwarding rules:
+ * - `db.observe.envelopes` fires once per locally-initiated envelope (the
+ *   wrapper notifies it after `applyEnvelope` returns). Replays inside the
+ *   reconciler and inbound `db.apply()` calls do NOT fire it, so there is
+ *   no bounce-back to filter.
+ * - Envelopes whose `TransactionResult.persistent === false` (i.e. they only
+ *   touched non-persistent resources/entities) are skipped. UI-only state lives
+ *   inside the same database without ever reaching the wire.
+ * - `time > 0` → `kind: "propose"` (reliable).
+ * - `time < 0` → `kind: "intermediate"` (rate-limited, lossy).
+ * - `time === 0` → `kind: "cancel"` (reliable).
+ *
+ * @example
+ * ```ts
+ * const db = Database.create(myPlugin, {
+ *     concurrency: createRebaseReplayConcurrency(crypto.randomUUID()),
+ * });
+ * const sync = createSyncService({ database: db, transport: ws });
+ *
+ * db.transactions.spawnUnit({ x: 0, y: 0, hp: 100 });
+ *
+ * sync.dispose();
+ * ```
+ */
+export const createSyncService = (options) => {
+    const { database, transport, maxIntermediatesPerSecond = 20, priorSessionId, initialWatermark = 0, onWelcome, pingIntervalMs = 10_000, livenessTimeoutMs = 25_000, logger, } = options;
+    const log = logger ?? (() => undefined);
+    if (!database.concurrency.deferredCommit || database.concurrency.userId === undefined) {
+        throw new Error("createSyncService: database must use createRebaseReplayConcurrency(userId) as its concurrency strategy.");
+    }
+    const minIntervalMs = 1000 / maxIntermediatesPerSecond;
+    let lastIntermediateSentAt = 0;
+    let lastAppliedTime = initialWatermark;
+    let serverSessionId;
+    let lastInboundAt = Date.now();
+    let pingTimer;
+    let livenessTimer;
+    const stopHeartbeat = () => {
+        if (pingTimer !== undefined) {
+            clearInterval(pingTimer);
+            pingTimer = undefined;
+        }
+        if (livenessTimer !== undefined) {
+            clearInterval(livenessTimer);
+            livenessTimer = undefined;
+        }
+    };
+    // Buffer inbound committed/cancelled envelopes that arrive before the
+    // welcome handler runs. This lets onWelcome call database.reset()
+    // synchronously before any replayed envelopes are applied.
+    let bufferedInbound = [];
+    const flushBuffered = () => {
+        if (bufferedInbound === null)
+            return;
+        const msgs = bufferedInbound;
+        bufferedInbound = null;
+        for (const msg of msgs)
+            applyInbound(msg);
+    };
+    const applyInbound = (msg) => {
+        if (msg.kind === "committed") {
+            log(`committed in (time=${msg.envelope.time}, name=${msg.envelope.name})`);
+            database.apply(msg.envelope);
+            if (msg.envelope.time > lastAppliedTime) {
+                lastAppliedTime = msg.envelope.time;
+            }
+        }
+        else if (msg.kind === "cancelled") {
+            log(`cancelled in (id=${msg.id})`);
+            database.cancel(msg.id);
+        }
+    };
+    const unsubscribeInbound = transport.onMessage((msg) => {
+        // Any inbound traffic — committed envelope, welcome, pong, anything —
+        // proves the peer is still alive. Refresh the liveness deadline first
+        // so we don't trip over slow callbacks below.
+        lastInboundAt = Date.now();
+        if (msg.kind === "pong")
+            return;
+        if (msg.kind === "welcome") {
+            log(`welcome in (sessionId=${msg.sessionId}, resetRequired=${msg.resetRequired})`);
+            serverSessionId = msg.sessionId;
+            // Invoke the welcome handler synchronously (it may call database.reset()).
+            onWelcome?.({ sessionId: msg.sessionId, resetRequired: msg.resetRequired });
+            // After the handler returns, flush buffered replay envelopes.
+            flushBuffered();
+        }
+        else if (bufferedInbound !== null) {
+            bufferedInbound.push(msg);
+        }
+        else {
+            applyInbound(msg);
+        }
+    });
+    // A component whose SCHEMA is marked nonShared is local to this client.
+    const isNonSharedComponent = (component) => database.componentSchemas[component]?.nonShared === true;
+    // Whether a transaction has any effect that must reach peers: it changed a
+    // shared entity through a shared (not nonShared) component. A transaction
+    // whose effects are entirely non-shared — only non-shared entities, or only
+    // nonShared components — stays local. NOTE: peers replay the WHOLE
+    // transaction, so a mixed shared/non-shared transaction cannot be partially
+    // stripped; keep non-shared mutations in their own transactions to keep them
+    // off the wire.
+    const hasSharedEffect = (result) => {
+        let sharedEntity = false;
+        for (const entity of result.changedEntities.keys()) {
+            if (Entity.isShared(entity)) {
+                sharedEntity = true;
+                break;
+            }
+        }
+        if (!sharedEntity)
+            return false;
+        for (const component of result.changedComponents) {
+            if (!isNonSharedComponent(component))
+                return true;
+        }
+        return false;
+    };
+    const unsubscribeOutbound = database.observe.envelopes(({ envelope, result, intent }) => {
+        // Skip envelopes whose only effect was on non-persistent entities/
+        // resources, or entirely on non-shared (client-local) entities/components.
+        if (result !== undefined && (!result.persistent || !hasSharedEffect(result)))
+            return;
+        if (intent === "commit") {
+            log(`propose out (id=${envelope.id}, name=${envelope.name})`);
+            transport.send({ kind: "propose", envelope });
+        }
+        else if (intent === "intermediate") {
+            const now = Date.now();
+            if (now - lastIntermediateSentAt < minIntervalMs)
+                return;
+            lastIntermediateSentAt = now;
+            transport.send({ kind: "intermediate", envelope });
+        }
+        else {
+            log(`cancel out (id=${envelope.id})`);
+            transport.send({ kind: "cancel", id: envelope.id });
+        }
+    });
+    // Send hello immediately — the onWelcome option is already registered, so
+    // the welcome response can be processed synchronously even on loopback.
+    log(`hello out (priorSessionId=${priorSessionId ?? "<fresh>"}, watermark=${initialWatermark})`);
+    transport.send({ kind: "hello", sessionId: priorSessionId, lastAppliedTime: initialWatermark });
+    // Keep-alive timers. The transport's own onClose listener clears them as
+    // a safety net so a leaked service doesn't keep the event loop alive.
+    if (pingIntervalMs > 0) {
+        pingTimer = setInterval(() => {
+            transport.send({ kind: "ping" });
+        }, pingIntervalMs);
+    }
+    if (livenessTimeoutMs > 0) {
+        // Check at a fraction of the timeout so we detect a drop within
+        // ~timeout + checkInterval and tests can use small timeouts.
+        const checkInterval = Math.max(50, Math.floor(livenessTimeoutMs / 4));
+        livenessTimer = setInterval(() => {
+            if (Date.now() - lastInboundAt > livenessTimeoutMs) {
+                log(`liveness timeout — closing transport`);
+                stopHeartbeat();
+                transport.close();
+            }
+        }, checkInterval);
+    }
+    const unsubscribeClose = transport.onClose(() => {
+        log(`transport closed`);
+        stopHeartbeat();
+    });
+    return {
+        dispose: () => {
+            log(`dispose`);
+            stopHeartbeat();
+            unsubscribeClose();
+            unsubscribeOutbound();
+            unsubscribeInbound();
+            transport.close();
+        },
+        lastAppliedTime: () => lastAppliedTime,
+        sessionId: () => serverSessionId,
+    };
+};
+//# sourceMappingURL=create-sync-service.js.map

package/dist/create-sync-service.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { SyncTransport, ClientTransport, ServerTransport, ServerMessage, ClientMessage, } from "./transport.js";
+export { createLoopbackTransport } from "./loopback-transport.js";
+export type { SyncServer, SyncServerOptions } from "./create-sync-server.js";
+export { createSyncServer } from "./create-sync-server.js";
+export type { SyncService, SyncServiceOptions } from "./create-sync-service.js";
+export { createSyncService } from "./create-sync-service.js";
+export type { WebSocketClientTransportOptions, WebSocketLike, } from "./websocket-transport.js";
+export { createWebSocketClientTransport, createWebSocketServerTransport, } from "./websocket-transport.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+export { createLoopbackTransport } from "./loopback-transport.js";
+export { createSyncServer } from "./create-sync-server.js";
+export { createSyncService } from "./create-sync-service.js";
+export { createWebSocketClientTransport, createWebSocketServerTransport, } from "./websocket-transport.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAUvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAM7D,OAAO,EACH,8BAA8B,EAC9B,8BAA8B,GACjC,MAAM,0BAA0B,CAAC"}

package/dist/keepalive.test.d.ts

@@ -0,0 +1 @@
+export {};