@carno.js/live 1.8.0 → 1.8.1

package/src/config.ts

@@ -1,49 +1,61 @@
-/**
- * Tunables from §10.1 of the design. These are starting points to calibrate
- * against the recompute-without-patch metric, not measured values.
- */
-export interface LiveConfig {
-    /** Window in ms over which invalidations for one instance are grouped. */
-    coalesceMs: number;
-    /** Above this many row keys, one read collapses to its table key. */
-    maxKeysPerRead: number;
-    /** Ceiling on the canonicalized inputs of a single subscription. */
-    maxInputBytes: number;
-    /** Grace period before dropping an instance whose refcount hit zero. */
-    unsubGraceMs: number;
-    /** Consecutive back-pressured sends before collapsing to a snapshot. */
-    maxPendingPatches: number;
-    /** Above this fan-out, recompute is queued instead of run inline. */
-    fanoutQueueThreshold: number;
-    /** Ceiling on live instances held by a single connection. */
-    maxInstancesPerConnection: number;
-    /** Ceiling on live instances held by this process. */
-    maxInstancesPerNode: number;
-    /** Path of the SSE downstream, when the SSE transport is on. */
-    ssePath: string;
-    /** Path client messages are posted to, when the SSE transport is on. */
-    sseControlPath: string;
-    /** Comment frame interval that keeps idle-timeout proxies from reaping. */
-    sseHeartbeatMs: number;
-    /** Ceiling on concurrent SSE streams held by this process. */
-    sseMaxConnections: number;
-}
-
-export const DEFAULT_LIVE_CONFIG: LiveConfig = {
-    coalesceMs: 16,
-    maxKeysPerRead: 64,
-    maxInputBytes: 8192,
-    unsubGraceMs: 5000,
-    maxPendingPatches: 32,
-    fanoutQueueThreshold: 500,
-    maxInstancesPerConnection: 64,
-    maxInstancesPerNode: 50000,
-    ssePath: '/live/sse',
-    sseControlPath: '/live/control',
-    sseHeartbeatMs: 15000,
-    sseMaxConnections: 10000
-};
-
-export function resolveLiveConfig(overrides: Partial<LiveConfig> = {}): LiveConfig {
-    return { ...DEFAULT_LIVE_CONFIG, ...overrides };
-}
+/**
+ * Tunables from §10.1 of the design. These are starting points to calibrate
+ * against the recompute-without-patch metric, not measured values.
+ */
+export interface LiveConfig {
+    /** Window in ms over which invalidations for one instance are grouped. */
+    coalesceMs: number;
+    /** Above this many row keys, one read collapses to its table key. */
+    maxKeysPerRead: number;
+    /** Ceiling on the canonicalized inputs of a single subscription. */
+    maxInputBytes: number;
+    /** Grace period before dropping an instance whose refcount hit zero. */
+    unsubGraceMs: number;
+    /** Consecutive back-pressured sends before collapsing to a snapshot. */
+    maxPendingPatches: number;
+    /** Recomputes finished in one run before the loop is yielded back. */
+    fanoutQueueThreshold: number;
+    /**
+     * Recomputes allowed to run at once, across every path.
+     *
+     * Each one executes the resource's route, and so its queries. Raising it
+     * past the database pool buys no parallelism -- the driver queues the
+     * excess either way -- it only puts live queries in front of the ordinary
+     * HTTP requests competing for the same connections. The default sits well
+     * under Bun's pool default of 10; raise it with the pool, not with the
+     * fan-out.
+     */
+    maxConcurrentRecomputes: number;
+    /** Ceiling on live instances held by a single connection. */
+    maxInstancesPerConnection: number;
+    /** Ceiling on live instances held by this process. */
+    maxInstancesPerNode: number;
+    /** Path of the SSE downstream, when the SSE transport is on. */
+    ssePath: string;
+    /** Path client messages are posted to, when the SSE transport is on. */
+    sseControlPath: string;
+    /** Comment frame interval that keeps idle-timeout proxies from reaping. */
+    sseHeartbeatMs: number;
+    /** Ceiling on concurrent SSE streams held by this process. */
+    sseMaxConnections: number;
+}
+
+export const DEFAULT_LIVE_CONFIG: LiveConfig = {
+    coalesceMs: 16,
+    maxKeysPerRead: 64,
+    maxInputBytes: 8192,
+    unsubGraceMs: 5000,
+    maxPendingPatches: 32,
+    fanoutQueueThreshold: 500,
+    maxConcurrentRecomputes: 4,
+    maxInstancesPerConnection: 64,
+    maxInstancesPerNode: 50000,
+    ssePath: '/live/sse',
+    sseControlPath: '/live/control',
+    sseHeartbeatMs: 15000,
+    sseMaxConnections: 10000
+};
+
+export function resolveLiveConfig(overrides: Partial<LiveConfig> = {}): LiveConfig {
+    return { ...DEFAULT_LIVE_CONFIG, ...overrides };
+}

package/src/graph/DependencyGraph.ts

@@ -1,147 +1,223 @@
-import { ancestorsOf, type DepKey } from './dep-key';
-import type { Dependency, InvalidationEvent } from './types';
-
-/** Column sets registered per instance under one key. null means wildcard. */
-type ColumnSet = Set<string> | null;
-
-/**
- * Key ↔ instance index with ancestor resolution and column filtering.
- *
- * Knows nothing about WebSocket, the ORM, or resources — it is a pure data
- * structure, which is why the hard part of invalidation is testable without
- * a server, a database or a socket.
- */
-export class DependencyGraph {
-    private readonly byKey = new Map<DepKey, Map<string, ColumnSet>>();
-    private readonly byInstance = new Map<string, Set<DepKey>>();
-
-    /** Replace every dependency held by this instance. */
-    setDependencies(instanceId: string, deps: Dependency[]): void {
-        this.remove(instanceId);
-
-        if (deps.length === 0) {
-            return;
-        }
-
-        const keys = new Set<DepKey>();
-
-        for (const dep of deps) {
-            keys.add(dep.key);
-
-            let holders = this.byKey.get(dep.key);
-            if (!holders) {
-                holders = new Map<string, ColumnSet>();
-                this.byKey.set(dep.key, holders);
-            }
-
-            if (!holders.has(instanceId)) {
-                holders.set(instanceId, dep.columns === null ? null : new Set(dep.columns));
-                continue;
-            }
-
-            const existing = holders.get(instanceId)!;
-
-            if (existing === null) {
-                continue;
-            }
-
-            if (dep.columns === null) {
-                holders.set(instanceId, null);
-                continue;
-            }
-
-            for (const column of dep.columns) {
-                existing.add(column);
-            }
-        }
-
-        this.byInstance.set(instanceId, keys);
-    }
-
-    /** Forget the instance entirely. */
-    remove(instanceId: string): void {
-        const keys = this.byInstance.get(instanceId);
-
-        if (!keys) {
-            return;
-        }
-
-        for (const key of keys) {
-            const holders = this.byKey.get(key);
-
-            if (!holders) {
-                continue;
-            }
-
-            holders.delete(instanceId);
-
-            if (holders.size === 0) {
-                this.byKey.delete(key);
-            }
-        }
-
-        this.byInstance.delete(instanceId);
-    }
-
-    /**
-     * Instances concerned by this write.
-     *
-     * Both directions of the hierarchy matter. A row write wakes table
-     * subscribers, while a table write wakes row subscribers because a
-     * predicate write may have touched that row.
-     */
-    resolve(event: InvalidationEvent): string[] {
-        const matched = new Set<string>();
-
-        for (const key of ancestorsOf(event.key)) {
-            this.collect(key, event.columns, matched);
-        }
-
-        const descendantPrefix = `${event.key}#`;
-        if (!event.key.includes('#')) {
-            for (const key of this.byKey.keys()) {
-                if (key.startsWith(descendantPrefix)) {
-                    this.collect(key, event.columns, matched);
-                }
-            }
-        }
-
-        return [...matched];
-    }
-
-    keyCount(): number {
-        return this.byKey.size;
-    }
-
-    instanceCount(): number {
-        return this.byInstance.size;
-    }
-
-    private collect(key: DepKey, writtenColumns: string[] | null, into: Set<string>): void {
-        const holders = this.byKey.get(key);
-
-        if (!holders) {
-            return;
-        }
-
-        for (const [instanceId, readColumns] of holders) {
-            if (intersects(readColumns, writtenColumns)) {
-                into.add(instanceId);
-            }
-        }
-    }
-}
-
-function intersects(readColumns: Set<string> | null, writtenColumns: string[] | null): boolean {
-    if (readColumns === null || writtenColumns === null) {
-        return true;
-    }
-
-    for (const column of writtenColumns) {
-        if (readColumns.has(column)) {
-            return true;
-        }
-    }
-
-    return false;
-}
+import { ancestorsOf, type DepKey } from './dep-key';
+import type { Dependency, InvalidationEvent } from './types';
+
+/** Column sets registered per instance under one key. null means wildcard. */
+type ColumnSet = Set<string> | null;
+
+/**
+ * Key ↔ instance index with ancestor resolution and column filtering.
+ *
+ * Knows nothing about WebSocket, the ORM, or resources — it is a pure data
+ * structure, which is why the hard part of invalidation is testable without
+ * a server, a database or a socket.
+ */
+export class DependencyGraph {
+    private readonly byKey = new Map<DepKey, Map<string, ColumnSet>>();
+    private readonly byInstance = new Map<string, Set<DepKey>>();
+    /**
+     * Registered row keys grouped by the key that contains them, so a write
+     * that names a whole table finds its rows instead of being searched for.
+     *
+     * Without it, resolving a table event means walking every key in the
+     * graph: at the configured `maxInstancesPerNode` that is a five-millisecond
+     * scan, run synchronously once per event of the batch, with every HTTP
+     * request in the process waiting behind it. Table events are not the rare
+     * case either -- a write degrades to its table key unless its WHERE clause
+     * is a literal primary-key match.
+     */
+    private readonly byParent = new Map<DepKey, Set<Map<string, ColumnSet>>>();
+
+    /** Replace every dependency held by this instance. */
+    setDependencies(instanceId: string, deps: Dependency[]): void {
+        this.remove(instanceId);
+
+        if (deps.length === 0) {
+            return;
+        }
+
+        const keys = new Set<DepKey>();
+
+        for (const dep of deps) {
+            keys.add(dep.key);
+
+            let holders = this.byKey.get(dep.key);
+            if (!holders) {
+                holders = new Map<string, ColumnSet>();
+                this.byKey.set(dep.key, holders);
+                this.index(dep.key, holders);
+            }
+
+            if (!holders.has(instanceId)) {
+                holders.set(instanceId, dep.columns === null ? null : new Set(dep.columns));
+                continue;
+            }
+
+            const existing = holders.get(instanceId)!;
+
+            if (existing === null) {
+                continue;
+            }
+
+            if (dep.columns === null) {
+                holders.set(instanceId, null);
+                continue;
+            }
+
+            for (const column of dep.columns) {
+                existing.add(column);
+            }
+        }
+
+        this.byInstance.set(instanceId, keys);
+    }
+
+    /** Forget the instance entirely. */
+    remove(instanceId: string): void {
+        const keys = this.byInstance.get(instanceId);
+
+        if (!keys) {
+            return;
+        }
+
+        for (const key of keys) {
+            const holders = this.byKey.get(key);
+
+            if (!holders) {
+                continue;
+            }
+
+            holders.delete(instanceId);
+
+            if (holders.size === 0) {
+                this.byKey.delete(key);
+                this.unindex(key, holders);
+            }
+        }
+
+        this.byInstance.delete(instanceId);
+    }
+
+    /**
+     * Instances concerned by this write.
+     *
+     * Both directions of the hierarchy matter. A row write wakes table
+     * subscribers, while a table write wakes row subscribers because a
+     * predicate write may have touched that row.
+     */
+    resolve(event: InvalidationEvent): string[] {
+        const matched = new Set<string>();
+
+        for (const key of ancestorsOf(event.key)) {
+            this.collect(key, event.columns, matched);
+        }
+
+        // A key with a `#` is already a row: it has no descendants, and the
+        // ancestor pass above has covered its table.
+        if (!event.key.includes('#')) {
+            const rows = this.byParent.get(event.key);
+
+            if (rows) {
+                // Holder maps, not keys: the key would only be looked up again.
+                for (const holders of rows) {
+                    this.collectFrom(holders, event.columns, matched);
+                }
+            }
+        }
+
+        return [...matched];
+    }
+
+    keyCount(): number {
+        return this.byKey.size;
+    }
+
+    instanceCount(): number {
+        return this.byInstance.size;
+    }
+
+    /** Keys that currently hold indexed rows. Zero when the graph is empty. */
+    parentCount(): number {
+        return this.byParent.size;
+    }
+
+    /**
+     * Record a row key's holders under the key that contains it.
+     *
+     * A table key has no separator and so no parent; it is reached directly.
+     * The holder map is stored rather than the key because it is what
+     * `resolve` actually needs, and because its identity is stable: it is
+     * created once in `setDependencies` and dropped only in `remove`.
+     */
+    private index(key: DepKey, holders: Map<string, ColumnSet>): void {
+        const separator = key.indexOf('#');
+
+        if (separator === -1) {
+            return;
+        }
+
+        const parent = key.slice(0, separator);
+        let rows = this.byParent.get(parent);
+
+        if (!rows) {
+            rows = new Set<Map<string, ColumnSet>>();
+            this.byParent.set(parent, rows);
+        }
+
+        rows.add(holders);
+    }
+
+    private unindex(key: DepKey, holders: Map<string, ColumnSet>): void {
+        const separator = key.indexOf('#');
+
+        if (separator === -1) {
+            return;
+        }
+
+        const parent = key.slice(0, separator);
+        const rows = this.byParent.get(parent);
+
+        if (!rows) {
+            return;
+        }
+
+        rows.delete(holders);
+
+        if (rows.size === 0) {
+            this.byParent.delete(parent);
+        }
+    }
+
+    private collect(key: DepKey, writtenColumns: string[] | null, into: Set<string>): void {
+        const holders = this.byKey.get(key);
+
+        if (holders) {
+            this.collectFrom(holders, writtenColumns, into);
+        }
+    }
+
+    private collectFrom(
+        holders: Map<string, ColumnSet>,
+        writtenColumns: string[] | null,
+        into: Set<string>
+    ): void {
+        for (const [instanceId, readColumns] of holders) {
+            if (intersects(readColumns, writtenColumns)) {
+                into.add(instanceId);
+            }
+        }
+    }
+}
+
+function intersects(readColumns: Set<string> | null, writtenColumns: string[] | null): boolean {
+    if (readColumns === null || writtenColumns === null) {
+        return true;
+    }
+
+    for (const column of writtenColumns) {
+        if (readColumns.has(column)) {
+            return true;
+        }
+    }
+
+    return false;
+}

package/src/index.ts

@@ -1,81 +1,83 @@
-import 'reflect-metadata';
-
-// Decorator and metadata
-export { Live } from './decorators/Live';
-export { LIVE_META } from './metadata';
-export type { LiveMeta, LiveOptions, LiveShared } from './metadata';
-
-// Plugin and services
-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';
-
-// Metrics
-export { LiveMetrics } from './observability';
-export type { MetricSink } from './observability';
-
-// Configuration
-export { DEFAULT_LIVE_CONFIG, resolveLiveConfig } from './config';
-export type { LiveConfig } from './config';
-
-// Scope
-export { ConnectionScopeResolver } from './transport/scope-resolver';
-export type { LiveHandshake, LiveScopeResolver } from './transport/scope-resolver';
-export type { LiveExecutionContext, LiveInputs, LiveResourceExecutor, LiveScope } from './resource/types';
-
-// Authorization
-export { AllowAllAuthorizer, authKeysOf, isAuthKey } from './auth/authorizer';
-export type { LiveAuthorizationRequest, LiveAuthorizer } from './auth/authorizer';
-
-// Invalidation
-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';
-
-// Protocol and patches, shared with the client
-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';
-
-// Framework-free client adapter
-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';
-
-// Transports
-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';
-
-// Conditional GET
-export { LiveETagMiddleware, pathMatcher } from './http/etag';
-export type { LivePollingGuard, LivePollingRequest, LiveRoutePath } from './http/etag';
-
-// First paint
-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';
+import 'reflect-metadata';
+
+// Decorator and metadata
+export { Live } from './decorators/Live';
+export { LIVE_META } from './metadata';
+export type { LiveMeta, LiveOptions, LiveShared } from './metadata';
+
+// Plugin and services
+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';
+
+// Metrics
+export { LiveMetrics } from './observability';
+export type { MetricSink } from './observability';
+
+// Configuration
+export { DEFAULT_LIVE_CONFIG, resolveLiveConfig } from './config';
+export type { LiveConfig } from './config';
+
+// Scope
+export { ConnectionScopeResolver } from './transport/scope-resolver';
+export type { LiveHandshake, LiveScopeResolver } from './transport/scope-resolver';
+export type { LiveExecutionContext, LiveInputs, LiveResourceExecutor, LiveScope } from './resource/types';
+export { defaultScopeWarning } from './scope-warning';
+export type { DefaultScopeWarningInput } from './scope-warning';
+
+// Authorization
+export { AllowAllAuthorizer, authKeysOf, isAuthKey } from './auth/authorizer';
+export type { LiveAuthorizationRequest, LiveAuthorizer } from './auth/authorizer';
+
+// Invalidation
+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';
+
+// Protocol and patches, shared with the client
+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';
+
+// Framework-free client adapter
+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';
+
+// Transports
+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';
+
+// Conditional GET
+export { LiveETagMiddleware, pathMatcher } from './http/etag';
+export type { LivePollingGuard, LivePollingRequest, LiveRoutePath } from './http/etag';
+
+// First paint
+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';