@carno.js/live 1.8.0

package/dist/http/etag.d.ts

@@ -0,0 +1,41 @@
+import type { CarnoClosure, CarnoMiddleware, Context } from '@carno.js/core';
+import type { LiveInputs, LiveScope } from '../resource/types';
+export interface LiveRoutePath {
+    method: string;
+    path: string;
+    resourceId?: string;
+}
+export interface LivePollingRequest {
+    resourceId: string;
+    inputs: LiveInputs;
+    request: Request;
+}
+export type LivePollingGuard = (request: LivePollingRequest) => LiveScope | null | Promise<LiveScope | null>;
+/** `/cards/:id` matches `/cards/42` and nothing deeper. */
+export declare function pathMatcher(pattern: string): RegExp;
+/**
+ * Content-hash `ETag` on live GET routes, and `304` when the client already
+ * holds that content.
+ *
+ * This is the bottom rung of §8.4: a client with neither WebSocket nor SSE
+ * polls the same route the SPA calls, and pays for a body only when something
+ * changed. The hash is the canonical one -- the same function the engine uses
+ * to decide whether a recompute produced a patch -- so reordered JSON keys are
+ * the same content, not a change.
+ *
+ * Scoped to live routes on purpose. Putting an `ETag` on every GET in the
+ * application would change the behaviour of routes that asked for none of this.
+ */
+export declare class LiveETagMiddleware implements CarnoMiddleware {
+    private readonly options;
+    private matchers;
+    private pollingGuard;
+    constructor(paths: LiveRoutePath[], options?: {
+        enabled?: boolean;
+    });
+    /** The plugin knows the live routes only after bootstrap. */
+    setPaths(paths: LiveRoutePath[]): void;
+    setPollingGuard(guard: LivePollingGuard): void;
+    handle(ctx: Context, next: CarnoClosure): Promise<Response | void>;
+    private routeFor;
+}

package/dist/http/etag.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveETagMiddleware = void 0;
+exports.pathMatcher = pathMatcher;
+const canonical_1 = require("../shared/canonical");
+const hash_1 = require("../shared/hash");
+const protocol_1 = require("../shared/protocol");
+/** `/cards/:id` matches `/cards/42` and nothing deeper. */
+function pathMatcher(pattern) {
+    const source = pattern
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/:[A-Za-z_][A-Za-z0-9_]*/g, '[^/]+');
+    return new RegExp(`^${source}$`);
+}
+/**
+ * Content-hash `ETag` on live GET routes, and `304` when the client already
+ * holds that content.
+ *
+ * This is the bottom rung of §8.4: a client with neither WebSocket nor SSE
+ * polls the same route the SPA calls, and pays for a body only when something
+ * changed. The hash is the canonical one -- the same function the engine uses
+ * to decide whether a recompute produced a patch -- so reordered JSON keys are
+ * the same content, not a change.
+ *
+ * Scoped to live routes on purpose. Putting an `ETag` on every GET in the
+ * application would change the behaviour of routes that asked for none of this.
+ */
+class LiveETagMiddleware {
+    constructor(paths, options = {}) {
+        this.options = options;
+        this.matchers = [];
+        this.pollingGuard = null;
+        this.setPaths(paths);
+    }
+    /** The plugin knows the live routes only after bootstrap. */
+    setPaths(paths) {
+        this.matchers = paths
+            .filter(entry => entry.method.toUpperCase() === 'GET')
+            .map(entry => ({ matcher: pathMatcher(entry.path), resourceId: entry.resourceId }));
+    }
+    setPollingGuard(guard) {
+        this.pollingGuard = guard;
+    }
+    async handle(ctx, next) {
+        const polling = ctx.req.headers.get(protocol_1.LIVE_POLL_HEADER) === '1';
+        const requestedResource = polling
+            ? ctx.req.headers.get(protocol_1.LIVE_RESOURCE_HEADER) ?? undefined
+            : undefined;
+        const route = ctx.method.toUpperCase() === 'GET'
+            ? this.routeFor(ctx.path, requestedResource)
+            : undefined;
+        if (polling && (!requestedResource || !route)) {
+            return new Response('Forbidden', { status: 403 });
+        }
+        if (!route) {
+            return next();
+        }
+        if (ctx.req.headers.get(protocol_1.LIVE_POLL_HEADER) === '1') {
+            const resourceId = route.resourceId;
+            const scope = resourceId && this.pollingGuard
+                ? await this.pollingGuard({
+                    resourceId,
+                    inputs: { params: ctx.params, query: ctx.query },
+                    request: ctx.req
+                })
+                : null;
+            if (!scope) {
+                return new Response('Forbidden', { status: 403 });
+            }
+            if (scope.headers) {
+                const headers = new Headers(ctx.req.headers);
+                new Headers(scope.headers).forEach((value, key) => headers.set(key, value));
+                ctx.req = new Request(ctx.req, { headers });
+            }
+        }
+        if (this.options.enabled === false) {
+            return next();
+        }
+        const response = await next();
+        if (response.status !== 200) {
+            return response;
+        }
+        const contentType = response.headers.get('Content-Type') ?? '';
+        if (!contentType.includes('application/json')) {
+            return response;
+        }
+        // Reading the body consumes the stream, so everything below hands the
+        // caller a rebuilt response rather than the one it just drained.
+        const body = await response.clone().text();
+        let tag;
+        try {
+            tag = `"${(0, hash_1.fnv1a64)((0, canonical_1.canonical)(JSON.parse(body)))}"`;
+        }
+        catch {
+            // Content-Type said JSON and it is not. Not our problem to fix.
+            return response;
+        }
+        if (ctx.req.headers.get('If-None-Match') === tag) {
+            return new Response(null, { status: 304, headers: { ETag: tag } });
+        }
+        const headers = new Headers(response.headers);
+        headers.set('ETag', tag);
+        return new Response(body, { status: 200, headers });
+    }
+    routeFor(path, resourceId) {
+        return this.matchers.find(route => route.matcher.test(path) && (resourceId === undefined || route.resourceId === resourceId));
+    }
+}
+exports.LiveETagMiddleware = LiveETagMiddleware;

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import 'reflect-metadata';
+export { Live } from './decorators/Live';
+export { LIVE_META } from './metadata';
+export type { LiveMeta, LiveOptions, LiveShared } from './metadata';
+export { LivePlugin } from './LivePlugin';
+export type { LivePluginOptions } from './LivePlugin';
+export { closeLiveRuntime } from './runtime';
+export { LiveService } from './LiveService';
+export { LiveEngine } from './LiveEngine';
+export type { LiveTransport, LiveStats } from './LiveEngine';
+export { LiveMetrics } from './observability';
+export type { MetricSink } from './observability';
+export { DEFAULT_LIVE_CONFIG, resolveLiveConfig } from './config';
+export type { LiveConfig } from './config';
+export { ConnectionScopeResolver } from './transport/scope-resolver';
+export type { LiveHandshake, LiveScopeResolver } from './transport/scope-resolver';
+export type { LiveExecutionContext, LiveInputs, LiveResourceExecutor, LiveScope } from './resource/types';
+export { AllowAllAuthorizer, authKeysOf, isAuthKey } from './auth/authorizer';
+export type { LiveAuthorizationRequest, LiveAuthorizer } from './auth/authorizer';
+export { InProcessBus } from './bus/InProcessBus';
+export type { InvalidationBus, InvalidationHandler } from './bus/InvalidationBus';
+export type { Dependency, InvalidationEvent } from './graph/types';
+export { ancestorsOf, rowKey, tableKey } from './graph/dep-key';
+export type { DepKey } from './graph/dep-key';
+export { WriteDuringComputeError } from './emitters/AppEmitter';
+export { PgNotifyBus, chunkEvents } from './bus/PgNotifyBus';
+export type { PgNotifyBusOptions } from './bus/PgNotifyBus';
+export { PgNotifyEmitter, eventsFromPayload } from './emitters/pg-notify-emitter';
+export type { PgNotifyEmitterOptions, PgNotifyTable } from './emitters/pg-notify-emitter';
+export { PgListener } from './emitters/pg-listener';
+export type { ListenableSql, PgListenerOptions } from './emitters/pg-listener';
+export { tableOfKey } from './graph/dep-key';
+export * from './shared/protocol';
+export type { PatchOp, PathSegment } from './patch/types';
+export { PatchEngine } from './patch/PatchEngine';
+export { canonical, NonSerializableInputError } from './shared/canonical';
+export { fnv1a64 } from './shared/hash';
+export { normalizeLiveInputs, resourceIdOf } from './shared/descriptor';
+export type { LiveDataOf, LiveDescriptor, LiveInputsOf } from './shared/descriptor';
+export type { OptimisticEntry, OptimisticList } from './client/optimistic';
+export { liveStore, liveStoreOf, liveIdentity, LiveSlot } from './client/vanilla';
+export type { LiveHandle } from './client/vanilla';
+export { WebSocketTransport, LadderTransport, PollingTransport, SseClientTransport, routeIndex } from './client/transport';
+export type { ClientTransport, TransportHandlers, EventSourceLike, RoutePath } from './client/transport';
+export { FanTransport } from './transport/FanTransport';
+export type { OwnedTransport } from './transport/FanTransport';
+export { SseTransport } from './transport/SseTransport';
+export type { SseTransportOptions } from './transport/SseTransport';
+export { createSseRoutes } from './transport/sse-routes';
+export type { SseRouteOptions } from './transport/sse-routes';
+export { LiveETagMiddleware, pathMatcher } from './http/etag';
+export type { LivePollingGuard, LivePollingRequest, LiveRoutePath } from './http/etag';
+export { prefetchLive } from './resource/prefetch';
+export type { LivePayload } from './resource/prefetch';
+export { LiveRouteExecutionError } from './resource/route-executor';
+export { hydrationKey, toHydrateMap, readHydrationPayload, HYDRATION_ATTRIBUTE } from './client/hydrate';

package/dist/index.js

@@ -0,0 +1,111 @@
+"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 });
+exports.HYDRATION_ATTRIBUTE = exports.readHydrationPayload = exports.toHydrateMap = exports.hydrationKey = exports.LiveRouteExecutionError = exports.prefetchLive = exports.pathMatcher = exports.LiveETagMiddleware = exports.createSseRoutes = exports.SseTransport = exports.FanTransport = exports.routeIndex = exports.SseClientTransport = exports.PollingTransport = exports.LadderTransport = exports.WebSocketTransport = exports.LiveSlot = exports.liveIdentity = exports.liveStoreOf = exports.liveStore = exports.resourceIdOf = exports.normalizeLiveInputs = exports.fnv1a64 = exports.NonSerializableInputError = exports.canonical = exports.PatchEngine = exports.tableOfKey = exports.PgListener = exports.eventsFromPayload = exports.PgNotifyEmitter = exports.chunkEvents = exports.PgNotifyBus = exports.WriteDuringComputeError = exports.tableKey = exports.rowKey = exports.ancestorsOf = exports.InProcessBus = exports.isAuthKey = exports.authKeysOf = exports.AllowAllAuthorizer = exports.ConnectionScopeResolver = exports.resolveLiveConfig = exports.DEFAULT_LIVE_CONFIG = exports.LiveMetrics = exports.LiveEngine = exports.LiveService = exports.closeLiveRuntime = exports.LivePlugin = exports.LIVE_META = exports.Live = void 0;
+require("reflect-metadata");
+// Decorator and metadata
+var Live_1 = require("./decorators/Live");
+Object.defineProperty(exports, "Live", { enumerable: true, get: function () { return Live_1.Live; } });
+var metadata_1 = require("./metadata");
+Object.defineProperty(exports, "LIVE_META", { enumerable: true, get: function () { return metadata_1.LIVE_META; } });
+// Plugin and services
+var LivePlugin_1 = require("./LivePlugin");
+Object.defineProperty(exports, "LivePlugin", { enumerable: true, get: function () { return LivePlugin_1.LivePlugin; } });
+var runtime_1 = require("./runtime");
+Object.defineProperty(exports, "closeLiveRuntime", { enumerable: true, get: function () { return runtime_1.closeLiveRuntime; } });
+var LiveService_1 = require("./LiveService");
+Object.defineProperty(exports, "LiveService", { enumerable: true, get: function () { return LiveService_1.LiveService; } });
+var LiveEngine_1 = require("./LiveEngine");
+Object.defineProperty(exports, "LiveEngine", { enumerable: true, get: function () { return LiveEngine_1.LiveEngine; } });
+// Metrics
+var observability_1 = require("./observability");
+Object.defineProperty(exports, "LiveMetrics", { enumerable: true, get: function () { return observability_1.LiveMetrics; } });
+// Configuration
+var config_1 = require("./config");
+Object.defineProperty(exports, "DEFAULT_LIVE_CONFIG", { enumerable: true, get: function () { return config_1.DEFAULT_LIVE_CONFIG; } });
+Object.defineProperty(exports, "resolveLiveConfig", { enumerable: true, get: function () { return config_1.resolveLiveConfig; } });
+// Scope
+var scope_resolver_1 = require("./transport/scope-resolver");
+Object.defineProperty(exports, "ConnectionScopeResolver", { enumerable: true, get: function () { return scope_resolver_1.ConnectionScopeResolver; } });
+// Authorization
+var authorizer_1 = require("./auth/authorizer");
+Object.defineProperty(exports, "AllowAllAuthorizer", { enumerable: true, get: function () { return authorizer_1.AllowAllAuthorizer; } });
+Object.defineProperty(exports, "authKeysOf", { enumerable: true, get: function () { return authorizer_1.authKeysOf; } });
+Object.defineProperty(exports, "isAuthKey", { enumerable: true, get: function () { return authorizer_1.isAuthKey; } });
+// Invalidation
+var InProcessBus_1 = require("./bus/InProcessBus");
+Object.defineProperty(exports, "InProcessBus", { enumerable: true, get: function () { return InProcessBus_1.InProcessBus; } });
+var dep_key_1 = require("./graph/dep-key");
+Object.defineProperty(exports, "ancestorsOf", { enumerable: true, get: function () { return dep_key_1.ancestorsOf; } });
+Object.defineProperty(exports, "rowKey", { enumerable: true, get: function () { return dep_key_1.rowKey; } });
+Object.defineProperty(exports, "tableKey", { enumerable: true, get: function () { return dep_key_1.tableKey; } });
+var AppEmitter_1 = require("./emitters/AppEmitter");
+Object.defineProperty(exports, "WriteDuringComputeError", { enumerable: true, get: function () { return AppEmitter_1.WriteDuringComputeError; } });
+var PgNotifyBus_1 = require("./bus/PgNotifyBus");
+Object.defineProperty(exports, "PgNotifyBus", { enumerable: true, get: function () { return PgNotifyBus_1.PgNotifyBus; } });
+Object.defineProperty(exports, "chunkEvents", { enumerable: true, get: function () { return PgNotifyBus_1.chunkEvents; } });
+var pg_notify_emitter_1 = require("./emitters/pg-notify-emitter");
+Object.defineProperty(exports, "PgNotifyEmitter", { enumerable: true, get: function () { return pg_notify_emitter_1.PgNotifyEmitter; } });
+Object.defineProperty(exports, "eventsFromPayload", { enumerable: true, get: function () { return pg_notify_emitter_1.eventsFromPayload; } });
+var pg_listener_1 = require("./emitters/pg-listener");
+Object.defineProperty(exports, "PgListener", { enumerable: true, get: function () { return pg_listener_1.PgListener; } });
+var dep_key_2 = require("./graph/dep-key");
+Object.defineProperty(exports, "tableOfKey", { enumerable: true, get: function () { return dep_key_2.tableOfKey; } });
+// Protocol and patches, shared with the client
+__exportStar(require("./shared/protocol"), exports);
+var PatchEngine_1 = require("./patch/PatchEngine");
+Object.defineProperty(exports, "PatchEngine", { enumerable: true, get: function () { return PatchEngine_1.PatchEngine; } });
+var canonical_1 = require("./shared/canonical");
+Object.defineProperty(exports, "canonical", { enumerable: true, get: function () { return canonical_1.canonical; } });
+Object.defineProperty(exports, "NonSerializableInputError", { enumerable: true, get: function () { return canonical_1.NonSerializableInputError; } });
+var hash_1 = require("./shared/hash");
+Object.defineProperty(exports, "fnv1a64", { enumerable: true, get: function () { return hash_1.fnv1a64; } });
+var descriptor_1 = require("./shared/descriptor");
+Object.defineProperty(exports, "normalizeLiveInputs", { enumerable: true, get: function () { return descriptor_1.normalizeLiveInputs; } });
+Object.defineProperty(exports, "resourceIdOf", { enumerable: true, get: function () { return descriptor_1.resourceIdOf; } });
+// Framework-free client adapter
+var vanilla_1 = require("./client/vanilla");
+Object.defineProperty(exports, "liveStore", { enumerable: true, get: function () { return vanilla_1.liveStore; } });
+Object.defineProperty(exports, "liveStoreOf", { enumerable: true, get: function () { return vanilla_1.liveStoreOf; } });
+Object.defineProperty(exports, "liveIdentity", { enumerable: true, get: function () { return vanilla_1.liveIdentity; } });
+Object.defineProperty(exports, "LiveSlot", { enumerable: true, get: function () { return vanilla_1.LiveSlot; } });
+var transport_1 = require("./client/transport");
+Object.defineProperty(exports, "WebSocketTransport", { enumerable: true, get: function () { return transport_1.WebSocketTransport; } });
+Object.defineProperty(exports, "LadderTransport", { enumerable: true, get: function () { return transport_1.LadderTransport; } });
+Object.defineProperty(exports, "PollingTransport", { enumerable: true, get: function () { return transport_1.PollingTransport; } });
+Object.defineProperty(exports, "SseClientTransport", { enumerable: true, get: function () { return transport_1.SseClientTransport; } });
+Object.defineProperty(exports, "routeIndex", { enumerable: true, get: function () { return transport_1.routeIndex; } });
+// Transports
+var FanTransport_1 = require("./transport/FanTransport");
+Object.defineProperty(exports, "FanTransport", { enumerable: true, get: function () { return FanTransport_1.FanTransport; } });
+var SseTransport_1 = require("./transport/SseTransport");
+Object.defineProperty(exports, "SseTransport", { enumerable: true, get: function () { return SseTransport_1.SseTransport; } });
+var sse_routes_1 = require("./transport/sse-routes");
+Object.defineProperty(exports, "createSseRoutes", { enumerable: true, get: function () { return sse_routes_1.createSseRoutes; } });
+// Conditional GET
+var etag_1 = require("./http/etag");
+Object.defineProperty(exports, "LiveETagMiddleware", { enumerable: true, get: function () { return etag_1.LiveETagMiddleware; } });
+Object.defineProperty(exports, "pathMatcher", { enumerable: true, get: function () { return etag_1.pathMatcher; } });
+// First paint
+var prefetch_1 = require("./resource/prefetch");
+Object.defineProperty(exports, "prefetchLive", { enumerable: true, get: function () { return prefetch_1.prefetchLive; } });
+var route_executor_1 = require("./resource/route-executor");
+Object.defineProperty(exports, "LiveRouteExecutionError", { enumerable: true, get: function () { return route_executor_1.LiveRouteExecutionError; } });
+var hydrate_1 = require("./client/hydrate");
+Object.defineProperty(exports, "hydrationKey", { enumerable: true, get: function () { return hydrate_1.hydrationKey; } });
+Object.defineProperty(exports, "toHydrateMap", { enumerable: true, get: function () { return hydrate_1.toHydrateMap; } });
+Object.defineProperty(exports, "readHydrationPayload", { enumerable: true, get: function () { return hydrate_1.readHydrationPayload; } });
+Object.defineProperty(exports, "HYDRATION_ATTRIBUTE", { enumerable: true, get: function () { return hydrate_1.HYDRATION_ATTRIBUTE; } });

package/dist/metadata.d.ts

@@ -0,0 +1,16 @@
+export declare const LIVE_META: unique symbol;
+export type LiveShared = 'private' | 'tenant' | 'public';
+export interface LiveOptions {
+    /** Field that identifies a row of a returned collection. */
+    key?: string;
+    /** Who may share one computed instance. */
+    shared?: LiveShared;
+    /** Manual dependency keys for data the ORM cannot observe. */
+    dependsOn?: string[];
+}
+export interface LiveMeta {
+    key?: string;
+    shared: LiveShared;
+    dependsOn: string[];
+    handlerName: string;
+}

package/dist/metadata.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIVE_META = void 0;
+exports.LIVE_META = Symbol('carno:live');

package/dist/observability.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The slice of `ObservabilityService` the live package needs.
+ *
+ * Declared structurally rather than imported so `@carno.js/core` stays an
+ * ordinary peer here and the metrics path is testable without one.
+ */
+export interface MetricSink {
+    onMetric(name: string, value: number, tags?: Record<string, string | number | boolean>): void;
+}
+/**
+ * Names the engine publishes, and the guard that keeps a broken metrics
+ * backend from breaking the engine.
+ *
+ * The engine calls this unconditionally; `none()` is what makes that safe when
+ * no observability plugin is installed, which is the default.
+ */
+export declare class LiveMetrics {
+    private readonly sink;
+    constructor(sink: MetricSink | null);
+    static none(): LiveMetrics;
+    recompute(resource: string, producedPatch: boolean, ops: number, durationMs: number): void;
+    invalidation(keys: number, fanout: number): void;
+    instances(count: number): void;
+    private publish;
+}

package/dist/observability.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveMetrics = void 0;
+/**
+ * Names the engine publishes, and the guard that keeps a broken metrics
+ * backend from breaking the engine.
+ *
+ * The engine calls this unconditionally; `none()` is what makes that safe when
+ * no observability plugin is installed, which is the default.
+ */
+class LiveMetrics {
+    constructor(sink) {
+        this.sink = sink;
+    }
+    static none() {
+        return new LiveMetrics(null);
+    }
+    recompute(resource, producedPatch, ops, durationMs) {
+        this.publish('live.recompute', 1, { resource, patched: producedPatch });
+        this.publish('live.recompute.ms', durationMs, { resource });
+        if (producedPatch) {
+            this.publish('live.patch.ops', ops, { resource });
+        }
+    }
+    invalidation(keys, fanout) {
+        this.publish('live.invalidation.keys', keys);
+        this.publish('live.invalidation.fanout', fanout);
+    }
+    instances(count) {
+        this.publish('live.instances', count);
+    }
+    publish(name, value, tags) {
+        if (!this.sink) {
+            return;
+        }
+        try {
+            this.sink.onMetric(name, value, tags);
+        }
+        catch {
+            // Losing a number is acceptable. Losing a recompute is not.
+        }
+    }
+}
+exports.LiveMetrics = LiveMetrics;

package/dist/patch/PatchEngine.d.ts

@@ -0,0 +1,20 @@
+import type { PatchOp } from './types';
+/**
+ * Snapshot → snapshot diffing, and patch application with structural sharing.
+ * Structural sharing keeps useSyncExternalStore snapshots referentially stable
+ * and lets framework memoization skip untouched branches.
+ */
+export declare class PatchEngine {
+    private readonly keyField?;
+    constructor(keyField?: string);
+    diff(prev: unknown, next: unknown): PatchOp[];
+    apply(prev: unknown, ops: PatchOp[]): unknown;
+    private diffValue;
+    private diffKeyedArray;
+    private isKeyed;
+    private keyOf;
+    private indexByKey;
+    private applyOne;
+    /** Rebuild only the containers along `path`, preserving all other refs. */
+    private replaceAt;
+}

package/dist/patch/PatchEngine.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PatchEngine = void 0;
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function deepEqual(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (Array.isArray(left) && Array.isArray(right)) {
+        return left.length === right.length && left.every((item, i) => deepEqual(item, right[i]));
+    }
+    if (isPlainObject(left) && isPlainObject(right)) {
+        const leftKeys = Object.keys(left);
+        if (leftKeys.length !== Object.keys(right).length) {
+            return false;
+        }
+        return leftKeys.every(key => Object.prototype.hasOwnProperty.call(right, key) && deepEqual(left[key], right[key]));
+    }
+    return false;
+}
+/**
+ * Snapshot → snapshot diffing, and patch application with structural sharing.
+ * Structural sharing keeps useSyncExternalStore snapshots referentially stable
+ * and lets framework memoization skip untouched branches.
+ */
+class PatchEngine {
+    constructor(keyField) {
+        this.keyField = keyField;
+    }
+    diff(prev, next) {
+        const ops = [];
+        this.diffValue(prev, next, [], ops);
+        return ops;
+    }
+    apply(prev, ops) {
+        if (ops.length === 0) {
+            return prev;
+        }
+        let root = prev;
+        for (const op of ops) {
+            root = this.applyOne(root, op);
+        }
+        return root;
+    }
+    diffValue(prev, next, path, ops) {
+        if (prev === next) {
+            return;
+        }
+        if (Array.isArray(prev) && Array.isArray(next)) {
+            if (this.isKeyed(prev) && this.isKeyed(next)) {
+                this.diffKeyedArray(prev, next, path, ops);
+                return;
+            }
+            if (!deepEqual(prev, next)) {
+                ops.push({ op: 'set', path, value: next });
+            }
+            return;
+        }
+        if (isPlainObject(prev) && isPlainObject(next)) {
+            for (const key of Object.keys(prev)) {
+                if (!Object.prototype.hasOwnProperty.call(next, key)) {
+                    ops.push({ op: 'unset', path: [...path, key] });
+                }
+            }
+            for (const key of Object.keys(next)) {
+                if (!Object.prototype.hasOwnProperty.call(prev, key)) {
+                    ops.push({ op: 'set', path: [...path, key], value: next[key] });
+                    continue;
+                }
+                this.diffValue(prev[key], next[key], [...path, key], ops);
+            }
+            return;
+        }
+        if (!deepEqual(prev, next)) {
+            ops.push({ op: 'set', path, value: next });
+        }
+    }
+    diffKeyedArray(prev, next, path, ops) {
+        const prevByKey = this.indexByKey(prev);
+        const nextByKey = this.indexByKey(next);
+        for (const key of prevByKey.keys()) {
+            if (!nextByKey.has(key)) {
+                ops.push({ op: 'remove', path, key });
+            }
+        }
+        next.forEach((row, index) => {
+            const key = this.keyOf(row);
+            const before = prevByKey.get(key);
+            if (before === undefined || !deepEqual(before, row)) {
+                ops.push({ op: 'upsert', path, key, index, value: row });
+            }
+        });
+        const survivingPrevKeys = [...prevByKey.keys()].filter(key => nextByKey.has(key));
+        const nextKeys = [...nextByKey.keys()];
+        const orderChanged = survivingPrevKeys.length !== nextKeys.length ||
+            survivingPrevKeys.some((key, i) => key !== nextKeys[i]);
+        if (orderChanged) {
+            ops.push({ op: 'order', path, keys: nextKeys });
+        }
+    }
+    isKeyed(value) {
+        if (!this.keyField) {
+            return false;
+        }
+        return value.every(item => this.keyOf(item) !== undefined);
+    }
+    keyOf(row) {
+        if (!this.keyField || !isPlainObject(row)) {
+            return undefined;
+        }
+        const value = row[this.keyField];
+        return typeof value === 'string' || typeof value === 'number' ? value : undefined;
+    }
+    indexByKey(rows) {
+        const index = new Map();
+        for (const row of rows) {
+            index.set(this.keyOf(row), row);
+        }
+        return index;
+    }
+    applyOne(root, op) {
+        if (op.op === 'set') {
+            return this.replaceAt(root, op.path, () => op.value);
+        }
+        if (op.op === 'unset') {
+            const parentPath = op.path.slice(0, -1);
+            const key = op.path[op.path.length - 1];
+            return this.replaceAt(root, parentPath, current => {
+                if (!isPlainObject(current)) {
+                    return current;
+                }
+                const clone = { ...current };
+                delete clone[String(key)];
+                return clone;
+            });
+        }
+        return this.replaceAt(root, op.path, current => {
+            const rows = Array.isArray(current) ? current : [];
+            if (op.op === 'remove') {
+                return rows.filter(row => this.keyOf(row) !== op.key);
+            }
+            if (op.op === 'upsert') {
+                const index = rows.findIndex(row => this.keyOf(row) === op.key);
+                if (index === -1) {
+                    const clone = rows.slice();
+                    clone.splice(Math.min(op.index, clone.length), 0, op.value);
+                    return clone;
+                }
+                const clone = rows.slice();
+                clone[index] = op.value;
+                return clone;
+            }
+            const byKey = new Map(rows.map(row => [this.keyOf(row), row]));
+            return op.keys.map(key => byKey.get(key)).filter(row => row !== undefined);
+        });
+    }
+    /** Rebuild only the containers along `path`, preserving all other refs. */
+    replaceAt(root, path, update) {
+        if (path.length === 0) {
+            return update(root);
+        }
+        const [head, ...rest] = path;
+        if (Array.isArray(root)) {
+            const index = Number(head);
+            const clone = root.slice();
+            clone[index] = this.replaceAt(root[index], rest, update);
+            return clone;
+        }
+        const base = isPlainObject(root) ? root : {};
+        const key = String(head);
+        return { ...base, [key]: this.replaceAt(base[key], rest, update) };
+    }
+}
+exports.PatchEngine = PatchEngine;

package/dist/patch/types.d.ts

@@ -0,0 +1,33 @@
+export type PathSegment = string | number;
+/** Replace the value at `path`. */
+export interface SetOp {
+    op: 'set';
+    path: PathSegment[];
+    value: unknown;
+}
+/** Delete the property at `path`. */
+export interface UnsetOp {
+    op: 'unset';
+    path: PathSegment[];
+}
+/** Insert or replace one row of a keyed array at `path`. */
+export interface UpsertOp {
+    op: 'upsert';
+    path: PathSegment[];
+    key: string | number;
+    index: number;
+    value: unknown;
+}
+/** Remove one row, by key, from a keyed array at `path`. */
+export interface RemoveOp {
+    op: 'remove';
+    path: PathSegment[];
+    key: string | number;
+}
+/** Final key order of a keyed array at `path`. */
+export interface OrderOp {
+    op: 'order';
+    path: PathSegment[];
+    keys: (string | number)[];
+}
+export type PatchOp = SetOp | UnsetOp | UpsertOp | RemoveOp | OrderOp;

package/dist/patch/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });