@lyku/para-sync 0.0.1-pre.0 → 0.0.1-pre.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyku/para-sync",
-  "version": "0.0.1-pre.0",
+  "version": "0.0.1-pre.1",
   "description": "synced<T> distributed object sync for the para:* suite — server-authoritative records with live, version-reconciled client replicas. Pre-release: API may change before 0.1.0. Currently provides the pluggable SyncTransport interface and the InProcessTransport implementation (monolith/edge/no-bus deployments); NatsTransport and the synced<T> primitive land on top.",
   "publishConfig": {
     "access": "public"
@@ -8,8 +8,12 @@
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
   },
   "dependencies": {
     "@lyku/para-signals": "^0.0.1-pre.0"

package/src/client.d.ts

@@ -0,0 +1,124 @@
+/** @typedef {import('./transport.js').SyncEnvelope} SyncEnvelope */
+/** @typedef {import('./transport.js').SyncTransport} SyncTransport */
+/**
+ * A schema's parse result — matches para-schema's Result<T, string>.
+ * @typedef {{ tag: 'Ok', value: any } | { tag: 'Err', error: string }} Result
+ */
+/**
+ * Anything with a `parse` returning {@link Result}. In production this is a
+ * para-schema `SchemaValue`; in tests it can be a hand-rolled gate. The replica
+ * depends only on this shape, never on para-schema directly — which is also why
+ * the client gates branch on `.tag` instead of using the throw-on-Err `::`
+ * convention (a malformed delta must trigger recovery, not crash the apply).
+ * @typedef {{ parse(v: unknown): Result }} SyncSchema
+ */
+/**
+ * A minimal reactive value cell: get / peek / set. A para-signals `signal()`
+ * satisfies it exactly and is the default. Injectable for testing and for the
+ * fork-backed cell on the para-svelte side.
+ * @typedef {{ get(): any, peek(): any, set(v: any): void }} Cell
+ */
+/**
+ * @typedef {'ok' | 'stale' | 'skew' | 'refetching'} ReplicaStatus
+ *  - ok          last apply succeeded; replica is current
+ *  - stale       uninitialized, or a refetch failed / none available
+ *  - skew        an inbound value failed `parse` (malformed or schema-skew)
+ *  - refetching  a recovery refetch is in flight
+ */
+/**
+ * @typedef {object} ReplicaMeta
+ * @property {string | null} schemaVersion  schema version of the applied value
+ * @property {number} sequence              sequence of the applied value (-1 if uninitialized)
+ * @property {ReplicaStatus} status
+ */
+/**
+ * Create a client replica for one synced key.
+ *
+ * @param {object} opts
+ * @param {string} opts.key                              synced key, e.g. "user:123"
+ * @param {SyncSchema} opts.schema                       the `parse` gate
+ * @param {SyncTransport} opts.transport                 change-envelope source
+ * @param {SyncEnvelope} [opts.seed]                     SSR-embedded initial envelope
+ * @param {() => Promise<SyncEnvelope>} [opts.refetch]   Err/skew/gap fallback: fetch the
+ *        current authoritative snapshot. Omit → no recovery (status goes 'stale').
+ * @param {Cell} [opts.cell]                             reactive cell (default: a para signal)
+ */
+export function createClientReplica({ key, schema, transport, seed, refetch, cell }: {
+    key: string;
+    schema: SyncSchema;
+    transport: SyncTransport;
+    seed?: SyncEnvelope;
+    refetch?: () => Promise<SyncEnvelope>;
+    cell?: Cell;
+}): {
+    /** current value (tracked read) */
+    get: () => any;
+    /** current value (untracked) */
+    peek: () => any;
+    /** reconcile metadata (tracked): { schemaVersion, sequence, status } */
+    meta: () => any;
+    /** reconcile metadata (untracked) */
+    peekMeta: () => any;
+    /** observability counters — read directly */
+    stats: {
+        applied: number;
+        ignoredStale: number;
+        gaps: number;
+        parseErrors: number;
+        refetches: number;
+    };
+    /** resolves when no recovery refetch is in flight (test/await aid) */
+    whenIdle: () => Promise<void>;
+    /** stop listening; idempotent */
+    dispose: () => void;
+};
+export type SyncEnvelope = import("./transport.js").SyncEnvelope;
+export type SyncTransport = import("./transport.js").SyncTransport;
+/**
+ * A schema's parse result — matches para-schema's Result<T, string>.
+ */
+export type Result = {
+    tag: "Ok";
+    value: any;
+} | {
+    tag: "Err";
+    error: string;
+};
+/**
+ * Anything with a `parse` returning {@link Result}. In production this is a
+ * para-schema `SchemaValue`; in tests it can be a hand-rolled gate. The replica
+ * depends only on this shape, never on para-schema directly — which is also why
+ * the client gates branch on `.tag` instead of using the throw-on-Err `::`
+ * convention (a malformed delta must trigger recovery, not crash the apply).
+ */
+export type SyncSchema = {
+    parse(v: unknown): Result;
+};
+/**
+ * A minimal reactive value cell: get / peek / set. A para-signals `signal()`
+ * satisfies it exactly and is the default. Injectable for testing and for the
+ * fork-backed cell on the para-svelte side.
+ */
+export type Cell = {
+    get(): any;
+    peek(): any;
+    set(v: any): void;
+};
+/**
+ * - ok          last apply succeeded; replica is current
+ * - stale       uninitialized, or a refetch failed / none available
+ * - skew        an inbound value failed `parse` (malformed or schema-skew)
+ * - refetching  a recovery refetch is in flight
+ */
+export type ReplicaStatus = "ok" | "stale" | "skew" | "refetching";
+export type ReplicaMeta = {
+    /**
+     * schema version of the applied value
+     */
+    schemaVersion: string | null;
+    /**
+     * sequence of the applied value (-1 if uninitialized)
+     */
+    sequence: number;
+    status: ReplicaStatus;
+};

package/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./transport.js";
+export * from "./client.js";

package/src/transport.d.ts

@@ -0,0 +1,226 @@
+/**
+ * The change envelope. Delta/full-object model: the new value travels with
+ * the reconcile key, so steady-state replication is deliver → parse → apply,
+ * with no refetch round-trip (refetch is the Err/gap/skew fallback only).
+ *
+ * @typedef {object} SyncEnvelope
+ * @property {unknown} value          The full changed object. NOT validated by
+ *                                    the transport — `parse` gating is the
+ *                                    consumer's job at the apply boundary.
+ * @property {string} schema_version  Reconcile key, part 1: the model's schema
+ *                                    version (e.g. "3.1"). Distinguishes a
+ *                                    compatible-but-behind replica from a
+ *                                    different/breaking shape.
+ * @property {number} sequence        Reconcile key, part 2: the object's
+ *                                    monotonic Postgres-authoritative sequence.
+ *                                    Sole job is ordering + gap detection.
+ */
+/**
+ * A listener for a key's change envelopes.
+ * @callback SyncHandler
+ * @param {SyncEnvelope} envelope
+ * @returns {void}
+ */
+/**
+ * Returned by subscribe(); calling it removes the subscription. Idempotent.
+ * @callback Unsub
+ * @returns {void}
+ */
+/**
+ * The pluggable transport contract. `synced<T>` depends ONLY on this shape, not
+ * on any concrete transport — that decoupling is what lets the same primitive
+ * run on a single box (InProcessTransport) or across services (NatsTransport).
+ *
+ * Contract notes that every implementation must honor:
+ *   - publish(key, envelope) delivers `envelope` to every current subscriber of
+ *     `key`. Publishing to a key with no subscribers is a no-op (never throws).
+ *   - The transport is a dumb pipe: it does NOT retain the latest value, does
+ *     NOT validate the envelope, and does NOT dedupe by sequence. A subscriber
+ *     receives only publishes that happen AFTER it subscribes — initial state
+ *     arrives via the SSR seed, not the transport.
+ *   - subscribe(key, handler) returns an idempotent Unsub.
+ *
+ * @typedef {object} SyncTransport
+ * @property {(key: string, envelope: SyncEnvelope) => void} publish
+ * @property {(key: string, handler: SyncHandler) => Unsub} subscribe
+ */
+/**
+ * In-process implementation of {@link SyncTransport}. A keyed pub/sub emitter:
+ * `Map<key, Set<handler>>`. No bus, no network, no serialization — the write
+ * and the listen happen in the same process, so delivery is a synchronous call.
+ *
+ * Why a plain emitter and not a para-signal per key: the transport contract is
+ * notification semantics ("deliver future publishes to this handler"), not
+ * value-cell semantics ("hand me the current value on subscribe, then deltas").
+ * Initial state is the SSR seed's job; the transport only carries changes. A
+ * keyed emitter models that exactly, without the current-value-on-subscribe and
+ * Object.is-dedupe behavior a signal would impose.
+ *
+ * @implements {SyncTransport}
+ */
+export class InProcessTransport implements SyncTransport {
+    /**
+     * key → set of handlers. A key is present iff it has ≥1 live subscriber;
+     * the entry is deleted when its last subscriber unsubscribes (no key leak).
+     * @type {Map<string, Set<SyncHandler>>}
+     */
+    _subs: Map<string, Set<SyncHandler>>;
+    /**
+     * Deliver `envelope` to every current subscriber of `key`, in subscription
+     * order. No-op if `key` has no subscribers.
+     * @param {string} key
+     * @param {SyncEnvelope} envelope
+     */
+    publish(key: string, envelope: SyncEnvelope): void;
+    /**
+     * Subscribe `handler` to `key`'s change envelopes. Returns an idempotent
+     * Unsub; calling it more than once is safe and will not remove a handler that
+     * was re-subscribed in between.
+     * @param {string} key
+     * @param {SyncHandler} handler
+     * @returns {Unsub}
+     */
+    subscribe(key: string, handler: SyncHandler): Unsub;
+    /**
+     * Diagnostic: number of keys with at least one live subscriber. Useful for
+     * leak checks (a healthy server returns to a steady key count as sessions
+     * come and go).
+     * @returns {number}
+     */
+    keyCount(): number;
+}
+/**
+ * NATS implementation of {@link SyncTransport}, for multi-service deployments
+ * where a write in the writer's service must reach listeners in other services.
+ * Matches Lyku's existing full-object-over-NATS convention.
+ *
+ * Honors the same contract as InProcessTransport (deliver to current
+ * subscribers, no retention, dumb pipe, idempotent unsub). On top it adds:
+ *   - subject mapping (key → NATS subject),
+ *   - the wire codec (encode on publish, decode on receipt),
+ *   - LOCAL FANOUT: N local subscribers to one key share ONE bus subscription,
+ *     and that bus subscription is torn down when the last local subscriber
+ *     leaves (the cross-service analog of subscriber-set GC).
+ *
+ * @implements {SyncTransport}
+ */
+export class NatsTransport implements SyncTransport {
+    /**
+     * @param {object} opts
+     * @param {SyncNatsConnection} opts.connection
+     * @param {SyncCodec} [opts.codec]                     default: identity (tests only)
+     * @param {(key: string) => string} [opts.subjectOf]   default: `synced.${key}`
+     */
+    constructor({ connection, codec, subjectOf }: {
+        connection: SyncNatsConnection;
+        codec?: SyncCodec;
+        subjectOf?: (key: string) => string;
+    });
+    _nc: SyncNatsConnection;
+    _codec: SyncCodec;
+    _subjectOf: (key: string) => string;
+    /**
+     * key → { natsUnsub, handlers } — present iff the key has ≥1 local
+     * subscriber (and therefore one live bus subscription).
+     * @type {Map<string, { natsUnsub: () => void, handlers: Set<SyncHandler> }>}
+     */
+    _keys: Map<string, {
+        natsUnsub: () => void;
+        handlers: Set<SyncHandler>;
+    }>;
+    /**
+     * @param {string} key
+     * @param {SyncEnvelope} envelope
+     */
+    publish(key: string, envelope: SyncEnvelope): void;
+    /**
+     * @param {string} key
+     * @param {SyncHandler} handler
+     * @returns {Unsub}
+     */
+    subscribe(key: string, handler: SyncHandler): Unsub;
+    /**
+     * Diagnostic: number of keys with a live bus subscription.
+     * @returns {number}
+     */
+    keyCount(): number;
+}
+/**
+ * The change envelope. Delta/full-object model: the new value travels with
+ * the reconcile key, so steady-state replication is deliver → parse → apply,
+ * with no refetch round-trip (refetch is the Err/gap/skew fallback only).
+ */
+export type SyncEnvelope = {
+    /**
+     * The full changed object. NOT validated by
+     * the transport — `parse` gating is the
+     * consumer's job at the apply boundary.
+     */
+    value: unknown;
+    /**
+     * Reconcile key, part 1: the model's schema
+     * version (e.g. "3.1"). Distinguishes a
+     * compatible-but-behind replica from a
+     * different/breaking shape.
+     */
+    schema_version: string;
+    /**
+     * Reconcile key, part 2: the object's
+     * monotonic Postgres-authoritative sequence.
+     * Sole job is ordering + gap detection.
+     */
+    sequence: number;
+};
+/**
+ * A listener for a key's change envelopes.
+ */
+export type SyncHandler = (envelope: SyncEnvelope) => void;
+/**
+ * Returned by subscribe(); calling it removes the subscription. Idempotent.
+ */
+export type Unsub = () => void;
+/**
+ * The pluggable transport contract. `synced<T>` depends ONLY on this shape, not
+ * on any concrete transport — that decoupling is what lets the same primitive
+ * run on a single box (InProcessTransport) or across services (NatsTransport).
+ *
+ * Contract notes that every implementation must honor:
+ *   - publish(key, envelope) delivers `envelope` to every current subscriber of
+ *     `key`. Publishing to a key with no subscribers is a no-op (never throws).
+ *   - The transport is a dumb pipe: it does NOT retain the latest value, does
+ *     NOT validate the envelope, and does NOT dedupe by sequence. A subscriber
+ *     receives only publishes that happen AFTER it subscribes — initial state
+ *     arrives via the SSR seed, not the transport.
+ *   - subscribe(key, handler) returns an idempotent Unsub.
+ */
+export type SyncTransport = {
+    publish: (key: string, envelope: SyncEnvelope) => void;
+    subscribe: (key: string, handler: SyncHandler) => Unsub;
+};
+/**
+ * A NATS connection, callback-adapted. NatsTransport expects delivery as a
+ * callback + an unsubscribe, NOT nats.js's raw async-iterable subscription —
+ * the iterable→callback adaptation is a 3-line caller concern that Lyku already
+ * does (`const sub = nc.subscribe(subj); (async () => { for await (const m of
+ * sub) onMessage(m.data); })(); return () => sub.unsubscribe();`). Keeping that
+ * out of the transport makes delivery synchronous and deterministic to test.
+ */
+export type SyncNatsConnection = {
+    publish: (subject: string, payload: Uint8Array) => void;
+    /**
+     *   subscribe to `subject`; `onMessage` is called per message with the raw
+     *   payload; returns an unsubscribe function.
+     */
+    subscribe: (subject: string, onMessage: (payload: Uint8Array) => void) => (() => void);
+};
+/**
+ * Wire codec: envelope ⇄ bytes. NATS payloads are `Uint8Array`. In production
+ * inject a BON or msgpackr codec (envelopes carry bigint IDs, which JSON cannot
+ * represent — BON is the SSR/wire serializer for exactly this reason). Defaults
+ * to identity (object passthrough), which works for in-memory fakes/tests but
+ * NOT a real NATS connection.
+ */
+export type SyncCodec = {
+    encode: (envelope: SyncEnvelope) => any;
+    decode: (payload: any) => SyncEnvelope;
+};