@carno.js/live 1.8.0

package/src/emitters/pg-trigger-sql.ts

@@ -0,0 +1,111 @@
+/**
+ * The SQL the Postgres emitter installs.
+ *
+ * It lives in its own module with no I/O so it can be asserted on without a
+ * database, and so the one place that concatenates identifiers into SQL is one
+ * short file you can read end to end.
+ */
+
+const BARE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export class UnsafeIdentifierError extends Error {
+    constructor(kind: string, value: string) {
+        super(
+            `Refusing to build SQL with an unsafe ${kind}: ${JSON.stringify(value)}. ` +
+            `Only bare names matching [A-Za-z_][A-Za-z0-9_]* are accepted.`
+        );
+        this.name = 'UnsafeIdentifierError';
+    }
+}
+
+/** Every identifier interpolated into the DDL below passes through here. */
+export function assertIdentifier(kind: string, value: string): string {
+    if (!BARE_IDENTIFIER.test(value)) {
+        throw new UnsafeIdentifierError(kind, value);
+    }
+
+    return value;
+}
+
+export const TRIGGER_FUNCTION_NAME = 'carno_live_notify';
+
+export function triggerNameOf(table: string): string {
+    return `carno_live_${assertIdentifier('table', table)}`;
+}
+
+/**
+ * The shared trigger function. Installed once; every table's trigger passes it
+ * the primary key column and the channel as arguments.
+ *
+ * Two decisions are baked in here rather than on the JavaScript side:
+ * an UPDATE whose jsonb diff is empty does not notify at all, because a write
+ * that changed nothing must not wake a single subscriber; and a payload over
+ * the ceiling degrades to the whole table instead of being truncated into
+ * something that would parse as a different row.
+ */
+export function createFunctionSql(maxPayloadBytes: number): string {
+    if (!Number.isInteger(maxPayloadBytes) || maxPayloadBytes <= 0) {
+        throw new Error(`maxPayloadBytes must be a positive integer, got ${maxPayloadBytes}.`);
+    }
+
+    return `
+CREATE OR REPLACE FUNCTION ${TRIGGER_FUNCTION_NAME}() RETURNS trigger AS $carno$
+DECLARE
+  pk_column text := TG_ARGV[0];
+  channel text := TG_ARGV[1];
+  new_row jsonb;
+  old_row jsonb;
+  changed text[];
+  row_id text;
+  payload text;
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    new_row := to_jsonb(OLD);
+  ELSE
+    new_row := to_jsonb(NEW);
+  END IF;
+
+  row_id := new_row ->> pk_column;
+
+  IF TG_OP = 'UPDATE' THEN
+    old_row := to_jsonb(OLD);
+
+    SELECT array_agg(entry.key ORDER BY entry.key) INTO changed
+    FROM jsonb_each(new_row) AS entry
+    WHERE entry.value IS DISTINCT FROM (old_row -> entry.key);
+
+    IF changed IS NULL THEN
+      RETURN NULL;
+    END IF;
+  END IF;
+
+  payload := json_build_object('t', TG_TABLE_NAME, 'i', row_id, 'c', changed)::text;
+
+  IF octet_length(payload) > ${maxPayloadBytes} THEN
+    payload := json_build_object('t', TG_TABLE_NAME, 'i', NULL, 'c', NULL)::text;
+  END IF;
+
+  PERFORM pg_notify(channel, payload);
+  RETURN NULL;
+END;
+$carno$ LANGUAGE plpgsql;
+`.trim();
+}
+
+export function createTriggerSql(table: string, primaryKey: string, channel: string): string {
+    const safeTable = assertIdentifier('table', table);
+    const safeKey = assertIdentifier('primary key column', primaryKey);
+    const safeChannel = assertIdentifier('channel', channel);
+    const trigger = triggerNameOf(safeTable);
+
+    return `
+DROP TRIGGER IF EXISTS ${trigger} ON ${safeTable};
+CREATE TRIGGER ${trigger}
+AFTER INSERT OR UPDATE OR DELETE ON ${safeTable}
+FOR EACH ROW EXECUTE FUNCTION ${TRIGGER_FUNCTION_NAME}('${safeKey}', '${safeChannel}');
+`.trim();
+}
+
+export function dropTriggerSql(table: string): string {
+    return `DROP TRIGGER IF EXISTS ${triggerNameOf(table)} ON ${assertIdentifier('table', table)};`;
+}

package/src/emitters/statement-keys.ts

@@ -0,0 +1,229 @@
+import type { Statement } from '@carno.js/orm';
+import { rowKey, tableKey } from '../graph/dep-key';
+import type { Dependency, InvalidationEvent } from '../graph/types';
+
+const WRITE_STATEMENTS = new Set(['insert', 'update', 'delete']);
+const READ_STATEMENTS = new Set(['select', 'count']);
+
+/**
+ * Turn the column list the ORM generated into bare column names.
+ * Returns null when the list is absent or contains an expression/star.
+ */
+export function normalizeColumns(columns: string[] | undefined): string[] | null {
+    if (!columns || columns.length === 0) {
+        return null;
+    }
+
+    const names = new Set<string>();
+
+    for (const raw of columns) {
+        const beforeAlias = raw.split(/\s+as\s+/i)[0].trim();
+        const lastDot = beforeAlias.lastIndexOf('.');
+        const bare = (lastDot === -1 ? beforeAlias : beforeAlias.slice(lastDot + 1))
+            .replace(/["`\[\]]/g, '')
+            .trim();
+
+        if (bare === '' || bare === '*' || bare.includes('(')) {
+            return null;
+        }
+
+        names.add(bare);
+    }
+
+    return [...names].sort();
+}
+
+function unquote(value: string): string {
+    return value.replace(/["`\[\]]/g, '');
+}
+
+/** SQL statements carry a qualified and quoted table; keys use the table only. */
+function tableNameOf(table: string): string {
+    const lastPart = table.trim().split('.').pop() ?? table;
+    return unquote(lastPart.trim());
+}
+
+function parseLiteral(raw: string): string | number {
+    const trimmed = raw.trim();
+
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1);
+    }
+
+    return Number(trimmed);
+}
+
+function escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function unwrapOuterParentheses(value: string): string {
+    let current = value.trim();
+
+    while (current.startsWith('(') && current.endsWith(')')) {
+        let depth = 0;
+        let enclosesWholeExpression = true;
+
+        for (let index = 0; index < current.length; index++) {
+            if (current[index] === '(') {
+                depth++;
+            } else if (current[index] === ')') {
+                depth--;
+
+                if (depth === 0 && index !== current.length - 1) {
+                    enclosesWholeExpression = false;
+                    break;
+                }
+            }
+        }
+
+        if (!enclosesWholeExpression || depth !== 0) {
+            break;
+        }
+
+        current = current.slice(1, -1).trim();
+    }
+
+    return current;
+}
+
+/**
+ * Extract primary-key values only when the WHERE clause is exactly a primary
+ * key equality or a primary-key IN list. Anything else degrades to the table.
+ */
+export function extractRowIds(
+    where: string | undefined,
+    primaryKeyColumn: string | undefined
+): (string | number)[] | null {
+    if (!where || !primaryKeyColumn) {
+        return null;
+    }
+
+    const trimmed = unwrapOuterParentheses(where.trim());
+    const column = `(?:[\\w"\`\\[\\]]+\\.)?["\`\\[]?${escapeRegExp(primaryKeyColumn)}["\`\\]]?`;
+
+    const equality = new RegExp(`^${column}\\s*=\\s*(\\d+|'[^']*')$`, 'i').exec(trimmed);
+    if (equality) {
+        return [parseLiteral(equality[1])];
+    }
+
+    const inList = new RegExp(`^${column}\\s+IN\\s*\\(([^()]*)\\)$`, 'i').exec(trimmed);
+    if (inList) {
+        const items = inList[1].split(',').map(item => item.trim()).filter(item => item !== '');
+
+        if (items.length === 0 || items.some(item => !/^(\d+|'[^']*')$/.test(item))) {
+            return null;
+        }
+
+        return items.map(parseLiteral);
+    }
+
+    return null;
+}
+
+/** Dependencies registered by one read. Empty for writes. */
+export function readDependencies(statement: Statement<any>, maxKeysPerRead: number): Dependency[] {
+    if (!READ_STATEMENTS.has(statement.statement ?? '') || !statement.table) {
+        return [];
+    }
+
+    const table = tableNameOf(statement.table);
+    const columns = normalizeColumns(statement.columns);
+    const ids = extractRowIds(statement.where, statement.primaryKeyColumnName);
+    const deps: Dependency[] = [];
+
+    if (ids && ids.length <= maxKeysPerRead) {
+        for (const id of ids) {
+            deps.push({ key: rowKey(table, id), columns });
+        }
+    } else {
+        deps.push({ key: tableKey(table), columns });
+    }
+
+    // A joined read depends on every joined table too. We cannot attribute the
+    // selected columns per table, so joins are wildcard.
+    for (const join of statement.join ?? []) {
+        if (join.joinTable) {
+            deps.push({ key: tableKey(tableNameOf(join.joinTable)), columns: null });
+        }
+    }
+
+    // Select-strategy relations execute these child statements directly via
+    // SqlJoinManager, so they never pass through the ORM's root observer hook.
+    // Their filters depend on the root rows and are not stable primary-key
+    // predicates; track each child table as a wildcard instead.
+    for (const selectJoin of statement.selectJoin ?? []) {
+        if (selectJoin.table) {
+            deps.push({ key: tableKey(tableNameOf(selectJoin.table)), columns: null });
+        }
+    }
+
+    return deps;
+}
+
+function writtenColumns(statement: Statement<any>): string[] | null {
+    if (statement.statement === 'delete') {
+        return null;
+    }
+
+    const values = statement.values;
+
+    if (!values) {
+        return null;
+    }
+
+    const rows: Record<string, unknown>[] = Array.isArray(values) ? values : [values];
+    const names = new Set<string>();
+
+    for (const row of rows) {
+        for (const name of Object.keys(row)) {
+            names.add(unquote(name));
+        }
+    }
+
+    return names.size === 0 ? null : [...names].sort();
+}
+
+function insertedIds(statement: Statement<any>): (string | number)[] | null {
+    const pk = statement.primaryKeyColumnName;
+
+    if (!pk || !statement.values) {
+        return null;
+    }
+
+    const rows: Record<string, unknown>[] = Array.isArray(statement.values)
+        ? statement.values
+        : [statement.values];
+    const ids: (string | number)[] = [];
+
+    for (const row of rows) {
+        const value = row[pk];
+
+        if (typeof value !== 'string' && typeof value !== 'number') {
+            return null;
+        }
+
+        ids.push(value);
+    }
+
+    return ids.length === 0 ? null : ids;
+}
+
+/** Invalidation events announced by one write. Empty for reads. */
+export function writeEvents(statement: Statement<any>, maxKeysPerRead: number): InvalidationEvent[] {
+    if (!WRITE_STATEMENTS.has(statement.statement ?? '') || !statement.table) {
+        return [];
+    }
+
+    const table = tableNameOf(statement.table);
+    const columns = writtenColumns(statement);
+    const ids = statement.statement === 'insert'
+        ? insertedIds(statement)
+        : extractRowIds(statement.where, statement.primaryKeyColumnName);
+
+    if (ids && ids.length <= maxKeysPerRead) {
+        return ids.map(id => ({ key: rowKey(table, id), columns }));
+    }
+
+    return [{ key: tableKey(table), columns }];
+}

package/src/graph/DependencyGraph.ts

@@ -0,0 +1,147 @@
+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;
+}

package/src/graph/SubscriptionRegistry.ts

@@ -0,0 +1,109 @@
+/**
+ * Instance ↔ connection index with per-pair refcounting.
+ *
+ * The refcount is per (connection, instance) pair because one page can mount
+ * two components bound to the same resource with the same inputs: unmounting
+ * one must not unsubscribe the other.
+ */
+export class SubscriptionRegistry {
+    private readonly byInstance = new Map<string, Map<string, number>>();
+    private readonly byConnection = new Map<string, Set<string>>();
+
+    /** Returns the connection's refcount on this instance after the call. */
+    subscribe(connectionId: string, instanceId: string): number {
+        let holders = this.byInstance.get(instanceId);
+        if (!holders) {
+            holders = new Map<string, number>();
+            this.byInstance.set(instanceId, holders);
+        }
+
+        const next = (holders.get(connectionId) ?? 0) + 1;
+        holders.set(connectionId, next);
+
+        let owned = this.byConnection.get(connectionId);
+        if (!owned) {
+            owned = new Set<string>();
+            this.byConnection.set(connectionId, owned);
+        }
+        owned.add(instanceId);
+
+        return next;
+    }
+
+    /** Returns the connection's refcount on this instance after the call. */
+    unsubscribe(connectionId: string, instanceId: string): number {
+        const holders = this.byInstance.get(instanceId);
+        const current = holders?.get(connectionId) ?? 0;
+
+        if (!holders || current === 0) {
+            return 0;
+        }
+
+        const next = current - 1;
+
+        if (next === 0) {
+            holders.delete(connectionId);
+            const owned = this.byConnection.get(connectionId);
+            owned?.delete(instanceId);
+
+            if (owned?.size === 0) {
+                this.byConnection.delete(connectionId);
+            }
+
+            if (holders.size === 0) {
+                this.byInstance.delete(instanceId);
+            }
+        } else {
+            holders.set(connectionId, next);
+        }
+
+        return next;
+    }
+
+    /** Drop the connection; returns instances now left with no subscriber. */
+    dropConnection(connectionId: string): string[] {
+        const owned = this.byConnection.get(connectionId);
+
+        if (!owned) {
+            return [];
+        }
+
+        const orphaned: string[] = [];
+
+        for (const instanceId of owned) {
+            const holders = this.byInstance.get(instanceId);
+
+            if (!holders) {
+                continue;
+            }
+
+            holders.delete(connectionId);
+
+            if (holders.size === 0) {
+                this.byInstance.delete(instanceId);
+                orphaned.push(instanceId);
+            }
+        }
+
+        this.byConnection.delete(connectionId);
+
+        return orphaned;
+    }
+
+    connectionsOf(instanceId: string): string[] {
+        return [...(this.byInstance.get(instanceId)?.keys() ?? [])];
+    }
+
+    hasSubscribers(instanceId: string): boolean {
+        return this.byInstance.has(instanceId);
+    }
+
+    /** Distinct instances held by the connection — the per-connection ceiling. */
+    countForConnection(connectionId: string): number {
+        return this.byConnection.get(connectionId)?.size ?? 0;
+    }
+
+    instanceCount(): number {
+        return this.byInstance.size;
+    }
+}

package/src/graph/dep-key.ts

@@ -0,0 +1,41 @@
+export type DepKey = string;
+
+const ROW_SEPARATOR = '#';
+
+/** Key naming a whole table: every row and every column of it. */
+export function tableKey(table: string): DepKey {
+    return `orm:${table}`;
+}
+
+/** Key naming one row by primary key. */
+export function rowKey(table: string, id: string | number): DepKey {
+    return `orm:${table}${ROW_SEPARATOR}${id}`;
+}
+
+/**
+ * The key itself plus every key that contains it.
+ *
+ * The hierarchy is exactly two levels deep and the only separator is `#`:
+ * `orm:users#42` is contained by `orm:users`. Colons are not hierarchical.
+ */
+export function ancestorsOf(key: DepKey): DepKey[] {
+    const index = key.indexOf(ROW_SEPARATOR);
+
+    if (index === -1) {
+        return [key];
+    }
+
+    return [key, key.slice(0, index)];
+}
+
+/** The table an ORM key names, or null for a key from another namespace. */
+export function tableOfKey(key: DepKey): string | null {
+    if (!key.startsWith('orm:')) {
+        return null;
+    }
+
+    const rest = key.slice('orm:'.length);
+    const separator = rest.indexOf(ROW_SEPARATOR);
+
+    return separator === -1 ? rest : rest.slice(0, separator);
+}

package/src/graph/types.ts

@@ -0,0 +1,15 @@
+import type { DepKey } from './dep-key';
+
+/** A read registered by one resource compute. */
+export interface Dependency {
+    key: DepKey;
+    /** Null is a wildcard for an unenumerated column set. */
+    columns: string[] | null;
+}
+
+/** A write announced by an invalidation emitter. */
+export interface InvalidationEvent {
+    key: DepKey;
+    /** Null is a wildcard for a whole-row write. */
+    columns: string[] | null;
+}