lemon-model 1.2.3 → 1.2.4

package/dist/sync/client.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `sync/client.ts`
+ * - L3 socket client runtime: envelope encode/decode, mid-based request/response tracking, type-based routing.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { NetworkSupportable } from '../socket';
+import { SocketClientIdentityProvider, SocketClientOptions, SocketClientSupportable } from './types';
+/**
+ * create a mid generator with its own counter and an instance-unique prefix.
+ * without the unique prefix, two bundled copies of lemon-model sharing one socket would both
+ * count from `sync-1` and settle each other's pendings on mid collision.
+ */
+export declare const createSocketClientIdentityProvider: (prefix?: string) => SocketClientIdentityProvider;
+/** create the L3 socket client runtime over a shared network */
+export declare const createSocketClient: (network: NetworkSupportable, options?: SocketClientOptions) => SocketClientSupportable;

package/dist/sync/client.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSocketClient = exports.createSocketClientIdentityProvider = void 0;
+/**
+ * `sync/client.ts`
+ * - L3 socket client runtime: envelope encode/decode, mid-based request/response tracking, type-based routing.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+const socket_1 = require("../socket");
+const DEFAULT_TIMEOUT_MS = 15000;
+/**
+ * create a mid generator with its own counter and an instance-unique prefix.
+ * without the unique prefix, two bundled copies of lemon-model sharing one socket would both
+ * count from `sync-1` and settle each other's pendings on mid collision.
+ */
+const createSocketClientIdentityProvider = (prefix) => {
+    let midNo = 0;
+    const midPrefix = prefix !== null && prefix !== void 0 ? prefix : `sync-${Math.random().toString(36).slice(2, 8)}`;
+    return { nextMid: () => `${midPrefix}-${++midNo}` };
+};
+exports.createSocketClientIdentityProvider = createSocketClientIdentityProvider;
+/** create the L3 socket client runtime over a shared network */
+const createSocketClient = (network, options) => new SocketClient(network, options);
+exports.createSocketClient = createSocketClient;
+/** L3 runtime: request/response tracking (with timeout) + type routing over one `NetworkSupportable` */
+class SocketClient {
+    constructor(source, options) {
+        var _a, _b;
+        this.pending = new Map();
+        this.typeListeners = new Map();
+        this.messageListeners = new Set();
+        this.errorListeners = new Set();
+        this.closed = false;
+        this.network = (options === null || options === void 0 ? void 0 : options.filter) ? (0, socket_1.createFilteredNetwork)(source, options.filter) : source;
+        this.timeoutMs = (_a = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _a !== void 0 ? _a : DEFAULT_TIMEOUT_MS;
+        this.maxPending = options === null || options === void 0 ? void 0 : options.maxPending;
+        this.identity = (_b = options === null || options === void 0 ? void 0 : options.identity) !== null && _b !== void 0 ? _b : (0, exports.createSocketClientIdentityProvider)();
+        this.unsubscribeNetworkMessage = this.network.onMessage(raw => this.receive(raw));
+        this.unsubscribeNetworkError = this.network.onError((error, context) => this.emitError(error, context));
+    }
+    /** number of requests awaiting a response */
+    get pendingCount() {
+        return this.pending.size;
+    }
+    /** delegate network ready */
+    ready() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.network).ready) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : Promise.resolve();
+    }
+    /** send a request and wait for the result/error of the same mid */
+    request(type, data, options) {
+        return new Promise((resolve, reject) => {
+            var _a;
+            if (this.closed) {
+                reject(new Error(`@socketClient is closed - socketClient.request(${type})`));
+                return;
+            }
+            if (this.maxPending != null && this.pending.size >= this.maxPending) {
+                reject(new Error(`@pending[${this.pending.size}] exceeds maxPending[${this.maxPending}] - socketClient.request(${type})`));
+                return;
+            }
+            const mid = this.identity.nextMid();
+            const timeoutMs = (_a = options === null || options === void 0 ? void 0 : options.timeoutMs) !== null && _a !== void 0 ? _a : this.timeoutMs;
+            const timer = timeoutMs > 0
+                ? setTimeout(() => {
+                    this.pending.delete(mid);
+                    const error = new Error(`@request[${type}:${mid}] timeout(${timeoutMs}ms) - socketClient.request`);
+                    this.emitError(error, { scope: 'socketClient.request.timeout', mid });
+                    reject(error);
+                }, timeoutMs)
+                : undefined;
+            this.pending.set(mid, { type, resolve, reject, timer });
+            try {
+                this.network.send(JSON.stringify({ type, data, mid }));
+            }
+            catch (e) {
+                this.pending.delete(mid);
+                if (timer)
+                    clearTimeout(timer);
+                reject(e);
+            }
+        });
+    }
+    /** one-way send without waiting for a response */
+    post(type, data) {
+        if (this.closed)
+            throw new Error(`@socketClient is closed - socketClient.post(${type})`);
+        const mid = this.identity.nextMid();
+        try {
+            this.network.send(JSON.stringify({ type, data, mid }));
+        }
+        catch (e) {
+            this.emitError(e, { scope: 'socketClient.post', mid });
+        }
+    }
+    /** subscribe to events of a specific type */
+    onType(type, handler) {
+        let listeners = this.typeListeners.get(type);
+        if (!listeners) {
+            listeners = new Set();
+            this.typeListeners.set(type, listeners);
+        }
+        const set = listeners;
+        set.add(handler);
+        return () => set.delete(handler);
+    }
+    /** subscribe to inbound envelopes not matched to a pending request */
+    onMessage(handler) {
+        this.messageListeners.add(handler);
+        return () => this.messageListeners.delete(handler);
+    }
+    /** observe asynchronous errors (timeout, send failure, network error) */
+    onError(handler) {
+        this.errorListeners.add(handler);
+        return () => this.errorListeners.delete(handler);
+    }
+    /** reject all pending + detach listeners. does not close network (socket is shared) */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.unsubscribeNetworkMessage();
+        this.unsubscribeNetworkError();
+        for (const [mid, request] of this.pending) {
+            if (request.timer)
+                clearTimeout(request.timer);
+            request.reject(new Error(`@socketClient is closed - socketClient.close(${mid})`));
+        }
+        this.pending.clear();
+        this.typeListeners.clear();
+        this.messageListeners.clear();
+        this.errorListeners.clear();
+    }
+    receive(raw) {
+        let message;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object' || typeof parsed.type !== 'string')
+                return;
+            message = parsed;
+        }
+        catch (_a) {
+            return; // not our envelope shape (e.g. json:* packet, progress string); ignore quietly
+        }
+        if (message.type === 'result' || message.type === 'error') {
+            const pending = this.pending.get(message.mid);
+            if (!pending)
+                return; // unmatched result/error: late response, drop silently
+            this.pending.delete(message.mid);
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            if (message.type === 'result')
+                pending.resolve(message.data);
+            else
+                pending.reject(message.data);
+            return;
+        }
+        for (const listener of [...this.messageListeners])
+            listener(message);
+        const typeListeners = this.typeListeners.get(message.type);
+        if (typeListeners)
+            for (const listener of [...typeListeners])
+                listener(message.data, message);
+    }
+    emitError(error, context) {
+        for (const listener of [...this.errorListeners])
+            listener(error, Object.assign(Object.assign({}, context), { network: this.network }));
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/sync/client.js.map

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

package/dist/sync/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `sync/index.ts`
+ * - model sync client: L3 socket client runtime + L4 sync machine.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * from './types';
+export * from './client';
+export * from './machine';
+export * from './ticker';

package/dist/sync/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `sync/index.ts`
+ * - model sync client: L3 socket client runtime + L4 sync machine.
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+__exportStar(require("./types"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./machine"), exports);
+__exportStar(require("./ticker"), exports);
+//! NOTE: the `Peer` test bridge (`./testing`) is intentionally NOT re-exported here.
+//! It is a test-only utility — import it via `lemon-model/sync/testing`-style relative paths
+//! within specs so production bundles do not pull in the simulator runtime.
+//# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;GAKG;AACH,0CAAwB;AACxB,2CAAyB;AACzB,4CAA0B;AAC1B,2CAAyB;AAEzB,qFAAqF;AACrF,6FAA6F;AAC7F,4EAA4E"}

package/dist/sync/machine.d.ts

@@ -0,0 +1,3 @@
+import { SocketClientSupportable, SyncMachineSupportable } from './types';
+/** create the L4 sync machine over an L3 socket client */
+export declare const createSyncMachine: (client: SocketClientSupportable) => SyncMachineSupportable;

package/dist/sync/machine.js

@@ -0,0 +1,185 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSyncMachine = void 0;
+/** envelope types the machine never treats as a domain event, even if `Peer`/L3 forward them */
+const NON_EVENT_TYPES = new Set(['result', 'error', 'ping', 'pong']);
+/** create the L4 sync machine over an L3 socket client */
+const createSyncMachine = (client) => new SyncMachine(client);
+exports.createSyncMachine = createSyncMachine;
+/** L4 machine: registry of per-type handles + one shared event fan-out subscription */
+class SyncMachine {
+    constructor(client) {
+        this.client = client;
+        this.handles = new Map();
+        this.closed = false;
+        this.unsubscribe = client.onMessage(message => this.dispatchEvent(message));
+    }
+    /** register a domain model type. re-registering the same type returns the existing handle and ignores the new options */
+    register(type, options) {
+        var _a;
+        if (!type)
+            throw new Error(`@type (string) is required - syncMachine.register`);
+        if (this.closed)
+            throw new Error(`@syncMachine is closed - syncMachine.register(${type})`);
+        const existing = this.handles.get(type);
+        if (existing)
+            return existing;
+        const handle = new ModelSyncHandle(type, this.client, options.adapter, () => this.handles.delete(type));
+        this.handles.set(type, handle);
+        if ((_a = options.initialPull) !== null && _a !== void 0 ? _a : true)
+            handle.pull().catch(() => undefined);
+        return handle;
+    }
+    /** pull every registered type once. a type whose pull is already in flight is skipped, not nested */
+    tick() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield Promise.all([...this.handles.values()].map(handle => handle.pull().catch(() => undefined)));
+        });
+    }
+    /** detach everything */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.unsubscribe();
+        for (const handle of [...this.handles.values()])
+            handle.close();
+        this.handles.clear();
+    }
+    dispatchEvent(message) {
+        if (NON_EVENT_TYPES.has(message.type))
+            return;
+        for (const handle of [...this.handles.values()])
+            handle.applyEvent(message);
+    }
+}
+/** sync handle for a single model type: local store, watermark, freshness judgement */
+class ModelSyncHandle {
+    constructor(type, client, adapter, onClose) {
+        var _a;
+        this.client = client;
+        this.adapter = adapter;
+        this.onClose = onClose;
+        this.store = new Map();
+        this.changeListeners = new Set();
+        this.watermark = 0;
+        this.closed = false;
+        this.type = type;
+        this.versionOf = (_a = adapter.versionOf) !== null && _a !== void 0 ? _a : (model => model.updatedAt);
+    }
+    /** read-only local state lookup */
+    get(id) {
+        return this.store.get(id);
+    }
+    list() {
+        return [...this.store.values()];
+    }
+    /** pull changes since the watermark and apply them. loops the cursor until parseReply.next is absent */
+    pull() {
+        if (this.closed)
+            return Promise.reject(new Error(`@handle[${this.type}] is closed - modelSync.pull`));
+        if (this.pulling)
+            return this.pulling; // already in flight: join it instead of nesting a new pull
+        const promise = this.doPull().finally(() => {
+            if (this.pulling === promise)
+                this.pulling = undefined;
+        });
+        this.pulling = promise;
+        return promise;
+    }
+    /** subscribe to change notifications */
+    onChange(handler) {
+        this.changeListeners.add(handler);
+        return () => this.changeListeners.delete(handler);
+    }
+    /** detach this type's subscriptions/listeners */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.changeListeners.clear();
+        this.onClose();
+    }
+    /** apply a server-sent event owned by this type (called by the machine's fan-out) */
+    applyEvent(message) {
+        if (this.closed)
+            return;
+        const models = this.adapter.parseEvent(message);
+        if (!models)
+            return; // not owned by this type
+        const changed = this.applyModels(models);
+        if (changed.length)
+            this.emitChange('event', changed);
+    }
+    doPull() {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const since = this.watermark || undefined;
+            let cursor;
+            const applied = [];
+            for (;;) {
+                const { type, data } = this.adapter.buildPull(since, cursor);
+                const reply = yield this.client.request(type, data);
+                const page = this.adapter.parseReply(reply);
+                const appliedPage = this.applyModels((_a = page.models) !== null && _a !== void 0 ? _a : []);
+                //! watermark advances from pull-applied models ONLY — an event-advanced watermark would
+                //! let a lost event skip the pulled backfill of models updated in between (safety-net hole).
+                for (const model of appliedPage)
+                    this.watermark = Math.max(this.watermark, (_b = this.versionOf(model)) !== null && _b !== void 0 ? _b : 0);
+                //! emit per page so applied pages are notified even if a later page request fails.
+                if (appliedPage.length)
+                    this.emitChange('pull', appliedPage);
+                applied.push(...appliedPage);
+                cursor = page.next;
+                if (!cursor)
+                    break;
+            }
+            return applied;
+        });
+    }
+    /** apply the versionOf freshness rule to each incoming model; returns the ones actually applied/removed */
+    applyModels(models) {
+        const changed = [];
+        for (const model of models) {
+            if (this.applyOne(model))
+                changed.push(model);
+        }
+        return changed;
+    }
+    applyOne(incoming) {
+        if ((incoming === null || incoming === void 0 ? void 0 : incoming.id) == null)
+            return false; // no id: ignore
+        const version = this.versionOf(incoming);
+        if (version == null)
+            return false; // no version: ignore
+        const local = this.store.get(incoming.id);
+        if (!local && incoming.deletedAt)
+            return false; // delete of something already absent: ignore
+        if (local) {
+            const localVersion = this.versionOf(local);
+            if (localVersion != null && version <= localVersion)
+                return false; // stale or same value: ignore
+            // local version == null: local is stale by definition, fall through and overwrite
+        }
+        if (incoming.deletedAt)
+            this.store.delete(incoming.id);
+        else
+            this.store.set(incoming.id, incoming);
+        return true;
+    }
+    emitChange(cause, models) {
+        const event = { cause, models };
+        for (const listener of [...this.changeListeners])
+            listener(event);
+    }
+}
+//# sourceMappingURL=machine.js.map

package/dist/sync/machine.js.map

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

package/dist/sync/network.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `sync/network.ts`
+ * - L1 network decorators: reconnect-on-death wrapper and raw wire translator.
+ * - additive to `src/socket`; free to compose with `createFilteredNetwork` (translated -> filtered -> L3).
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { NetworkSupportable, SocketUnsubscribe } from '../socket';
+export interface ReconnectOptions {
+    /** first retry delay (default 1_000ms) */
+    baseMs?: number;
+    /** exponential backoff multiplier (default 2) */
+    factor?: number;
+    /** retry delay cap (default 30_000ms) */
+    maxMs?: number;
+    /** retry count cap (default unlimited). onError notified then permanently closed once reached */
+    maxRetries?: number;
+    /** force a reconnect when nothing has been received for this long (default off) */
+    idleTimeoutMs?: number;
+    /** readyState watchdog cadence (default 1_000ms). fallback for networks that close without notifying */
+    watchdogMs?: number;
+}
+export interface ReconnectingNetworkSupportable extends NetworkSupportable {
+    /** notified on every successful reconnect (initial connect excluded). the service catches up here with machine.tick() */
+    onReconnect(handler: () => void): SocketUnsubscribe;
+    /** internal network generation (0 initially, +1 per reconnect) */
+    readonly generation: number;
+}
+/** create the L1 reconnect decorator: swaps the internal network on death, keeping instance identity for L3 */
+export declare const createReconnectingNetwork: (factory: () => NetworkSupportable, options?: ReconnectOptions) => ReconnectingNetworkSupportable;
+export interface WireTranslator {
+    /** outbound raw transform (default passthrough) */
+    outbound?: (raw: string) => string;
+    /** inbound raw transform. returning undefined drops the raw (default passthrough) */
+    inbound?: (raw: string) => string | undefined;
+}
+/** create the L1 wire translator decorator over a raw string, same slot as `createFilteredNetwork` */
+export declare const createTranslatedNetwork: (source: NetworkSupportable, translator: WireTranslator) => NetworkSupportable;