@ultimabase/realtime 0.0.0-stage → 0.1.0

package/dist/window.d.ts

@@ -0,0 +1,43 @@
+import type { Order } from 'ultimabase';
+export type Entry = {
+    readonly id: string;
+    readonly keys: readonly unknown[];
+};
+/** What changed between two windows, in the order a client applies it. */
+export type Moves = {
+    readonly removed: readonly string[];
+    /** Each row placed again, after the row before it, `null` for the first. */
+    readonly placed: readonly {
+        readonly id: string;
+        readonly after: string | null;
+    }[];
+};
+export declare class Window {
+    #private;
+    /** Rows may follow the last entry. */
+    rest: boolean;
+    first: number;
+    constructor(orderBy: readonly Order[], first: number);
+    /** Starts noting changes: `moves` tells those since. */
+    mark(): void;
+    /** The rows a client shows. */
+    get entries(): readonly Entry[];
+    shown(): readonly Entry[];
+    hasMore(): boolean;
+    /** The ids of the entries, kept as they change. */
+    ids(): ReadonlySet<string>;
+    /** How many rows a read after the last entry must bring. */
+    missing(): number;
+    /** Adds the rows read after the last entry. */
+    fill(entries: readonly Entry[], rest: boolean): void;
+    remove(id: string): boolean;
+    /** Places a row that passes the filter, or leaves it outside. */
+    place(entry: Entry): void;
+    /**
+     * How the rows shown at the mark, none before the first, became those
+     * shown now. Only the rows changed since, and the one past the shown rows
+     * then and now, may have come or gone.
+     */
+    moves(again: ReadonlySet<string>): Moves;
+}
+//# sourceMappingURL=window.d.ts.map

package/dist/window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window.d.ts","sourceRoot":"","sources":["../src/window.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAGvC,MAAM,MAAM,KAAK,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,CAAA;AAE9E,0EAA0E;AAC1E,MAAM,MAAM,KAAK,GAAG;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,SAAS;QACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAC7B,EAAE,CAAA;CACH,CAAA;AAED,qBAAa,MAAM;;IAGlB,sCAAsC;IACtC,IAAI,UAAQ;IACZ,KAAK,EAAE,MAAM,CAAA;IAOb,YAAY,OAAO,EAAE,SAAS,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAGnD;IAED,wDAAwD;IACxD,IAAI,IAAI,IAAI,CAGX;IAOD,+BAA+B;IAC/B,IAAI,OAAO,IAAI,SAAS,KAAK,EAAE,CAE9B;IAED,KAAK,IAAI,SAAS,KAAK,EAAE,CAExB;IAED,OAAO,IAAI,OAAO,CAEjB;IAED,mDAAmD;IACnD,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAEzB;IAED,4DAA4D;IAC5D,OAAO,IAAI,MAAM,CAEhB;IAED,+CAA+C;IAC/C,IAAI,CAAC,OAAO,EAAE,SAAS,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAOnD;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAM1B;IAED,iEAAiE;IACjE,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAqBxB;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,KAAK,CAgCvC;CACD"}

package/dist/window.js

@@ -0,0 +1,125 @@
+import { compareKeys } from 'ultimabase/internal';
+export class Window {
+    #entries = [];
+    #ids = new Set();
+    /** Rows may follow the last entry. */
+    rest = false;
+    first;
+    #orderBy;
+    /** The rows changed since the mark, each with its keys then, if it was in. */
+    #was;
+    /** The row past those shown at the mark. */
+    #extra;
+    constructor(orderBy, first) {
+        this.#orderBy = orderBy;
+        this.first = first;
+    }
+    /** Starts noting changes: `moves` tells those since. */
+    mark() {
+        this.#was = new Map();
+        this.#extra = this.#entries[this.first]?.id;
+    }
+    #note(id, keys) {
+        const was = this.#was;
+        if (was !== undefined && !was.has(id))
+            was.set(id, keys);
+    }
+    /** The rows a client shows. */
+    get entries() {
+        return this.#entries;
+    }
+    shown() {
+        return this.#entries.slice(0, this.first);
+    }
+    hasMore() {
+        return this.#entries.length > this.first;
+    }
+    /** The ids of the entries, kept as they change. */
+    ids() {
+        return this.#ids;
+    }
+    /** How many rows a read after the last entry must bring. */
+    missing() {
+        return this.rest ? this.first + 1 - this.#entries.length : 0;
+    }
+    /** Adds the rows read after the last entry. */
+    fill(entries, rest) {
+        this.#entries.push(...entries);
+        for (const { id } of entries) {
+            this.#note(id, undefined);
+            this.#ids.add(id);
+        }
+        this.rest = rest;
+    }
+    remove(id) {
+        if (!this.#ids.delete(id))
+            return false;
+        const at = this.#entries.findIndex((entry) => entry.id === id);
+        this.#note(id, this.#entries[at]?.keys);
+        this.#entries.splice(at, 1);
+        return true;
+    }
+    /** Places a row that passes the filter, or leaves it outside. */
+    place(entry) {
+        this.remove(entry.id);
+        const entries = this.#entries;
+        let low = 0;
+        let high = entries.length;
+        while (low < high) {
+            const middle = (low + high) >> 1;
+            const keys = entries[middle]?.keys ?? [];
+            if (compareKeys(keys, entry.keys, this.#orderBy) < 0)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        if (low === entries.length && this.rest)
+            return;
+        this.#note(entry.id, undefined);
+        entries.splice(low, 0, entry);
+        this.#ids.add(entry.id);
+        const last = entries.length > this.first + 1 ? entries.pop() : undefined;
+        if (last !== undefined) {
+            this.#note(last.id, last.keys);
+            this.#ids.delete(last.id);
+            this.rest = true;
+        }
+    }
+    /**
+     * How the rows shown at the mark, none before the first, became those
+     * shown now. Only the rows changed since, and the one past the shown rows
+     * then and now, may have come or gone.
+     */
+    moves(again) {
+        const entries = this.#entries;
+        const after = (at) => ({
+            id: entries[at]?.id ?? '',
+            after: entries[at - 1]?.id ?? null,
+        });
+        const notes = this.#was;
+        if (notes === undefined) {
+            return { removed: [], placed: this.shown().map((_, at) => after(at)) };
+        }
+        const extra = entries[this.first]?.id;
+        const was = (id) => id !== this.#extra &&
+            (notes.has(id) ? notes.get(id) !== undefined : this.#ids.has(id));
+        const shown = (id) => id !== extra && this.#ids.has(id);
+        const ids = [
+            ...new Set([...notes.keys(), ...again, this.#extra, extra]),
+        ].filter((id) => id !== undefined);
+        const removed = ids.filter((id) => was(id) && !shown(id));
+        const placed = ids.flatMap((id) => {
+            if (!shown(id))
+                return [];
+            const at = entries.findIndex((entry) => entry.id === id);
+            const old = notes.get(id);
+            // The rows whose keys stayed keep their order among themselves.
+            const still = was(id) &&
+                !again.has(id) &&
+                (old === undefined ||
+                    compareKeys(old, entries[at]?.keys ?? [], this.#orderBy) === 0);
+            return still ? [] : [at];
+        });
+        return { removed, placed: placed.toSorted((a, b) => a - b).map(after) };
+    }
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@ultimabase/realtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Realtime for UltimaBase: live lists and live rows that follow every write, under the read rules.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ultimabase.dev/docs/realtime",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/realtime"
+  },
+  "engines": {
+    "node": ">=24.7.0"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist && yarn run -T tsc --project tsconfig.build.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "ultimabase": "^0.1.0"
+  },
+  "devDependencies": {
+    "@ultimabase/acl": "0.1.0",
+    "@ultimabase/roles": "0.1.0",
+    "@ultimabase/soft-delete": "0.1.0",
+    "@ultimabase/testing": "0.1.0",
+    "ultimabase": "0.1.0",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
 }

package/src/affected.ts

@@ -0,0 +1,118 @@
+// What a flush's changes do to one live read (D-154): the root rows to place
+// again, the window rows deleted or to send again, or a resync when the feed
+// does not say which rows changed.
+import type { Batch } from './changes.ts'
+import { listed, touched, unlisted } from './changes.ts'
+import type { Reach, Step } from './reach.ts'
+
+export type Affected = {
+	/** Root rows whose membership or order may have changed. */
+	readonly candidates: ReadonlySet<string>
+	/** Window rows deleted. */
+	readonly deleted: ReadonlySet<string>
+	/** A row past the window may have left the list. */
+	readonly beyond: boolean
+	/** Window rows to read and send again. */
+	readonly resend: ReadonlySet<string>
+}
+
+/**
+ * The root rows that reach one of `ids` through `steps`, among `within` when
+ * it is given.
+ */
+export type Finder = (
+	steps: readonly Step[],
+	ids: readonly string[],
+	within?: readonly string[],
+) => Promise<readonly string[]>
+
+/** The window rows each row a shown relation reached is shown under. */
+export type Tracked = ReadonlyMap<
+	string,
+	ReadonlyMap<string, ReadonlySet<string>>
+>
+
+export type Facing = {
+	readonly model: string
+	readonly reach: Reach
+	readonly window: ReadonlySet<string>
+	readonly tracked: Tracked
+	readonly find: Finder
+}
+
+/** What `batch` does to the live read `facing` describes. */
+export async function affected(
+	facing: Facing,
+	batch: Batch,
+): Promise<Affected | 'resync'> {
+	const { model, reach, window, find } = facing
+	const root = batch.get(model)
+	if (unlisted(root)) return 'resync'
+	const candidates = new Set(listed(root?.inserts))
+	const deleted = new Set<string>()
+	let beyond = false
+	for (const id of listed(root?.deletes)) {
+		if (window.has(id)) deleted.add(id)
+		else beyond = true
+	}
+	const updated = listed(root?.updates)
+	if (touched(root, reach.placing)) {
+		for (const id of updated) candidates.add(id)
+	}
+	const resend = new Set<string>()
+	if (touched(root, reach.showing)) {
+		for (const id of updated) if (window.has(id)) resend.add(id)
+	}
+	for (const level of reach.levels) {
+		const changes = batch.get(level.model)
+		const step = level.steps.at(-1)
+		if (step === undefined || changes === undefined) continue
+		if (unlisted(changes)) return 'resync'
+		const ids = [
+			...listed(changes.inserts),
+			...(touched(changes, level.fields) ? listed(changes.updates) : []),
+		]
+		if (ids.length > 0) {
+			for (const id of await find(level.steps, ids)) candidates.add(id)
+		}
+		// A link lost where it is stored: the rows that had it are unknown.
+		const lost =
+			changes.deletes !== undefined ||
+			(step.keyOnTarget && touched(changes, new Set([step.inverse])))
+		if (!lost) continue
+		if (level.negative) return 'resync'
+		for (const id of window) candidates.add(id)
+	}
+	const again = await shown(facing, batch)
+	for (const id of again === 'all' ? window : again) resend.add(id)
+	return { candidates, deleted, beyond, resend }
+}
+
+/** The window rows whose shown relations changed. */
+async function shown(
+	facing: Facing,
+	batch: Batch,
+): Promise<ReadonlySet<string> | 'all'> {
+	const { reach, window, tracked, find } = facing
+	for (const model of reach.deep) if (batch.has(model)) return 'all'
+	const resend = new Set<string>()
+	for (const relation of reach.shown) {
+		const changes = batch.get(relation.model)
+		if (changes === undefined) continue
+		if (unlisted(changes)) return 'all'
+		const updated = touched(changes, relation.fields)
+			? listed(changes.updates)
+			: []
+		if (relation.counted && changes.deletes !== undefined) return 'all'
+		const known = tracked.get(relation.path)
+		for (const id of [...updated, ...listed(changes.deletes)]) {
+			for (const root of known?.get(id) ?? []) resend.add(root)
+		}
+		const ids = [...listed(changes.inserts), ...updated]
+		if (ids.length === 0 || window.size === 0) continue
+		for (const id of await find(relation.steps, ids, [...window])) {
+			resend.add(id)
+		}
+	}
+	return resend
+}

package/src/changes.ts

@@ -0,0 +1,107 @@
+// One flush's changes (D-154), by model: the rows each kind of write reached
+// and the fields updates set. A list the feed left out is `'all'`, every row
+// or every field. A link or an unlink reads as an update of both sides,
+// under each side's relation, as a `one` key's change already does.
+import type { Changed, Schema } from 'ultimabase'
+
+/** Some rows by id, or every row when the feed did not list them. */
+export type Rows = ReadonlySet<string> | 'all'
+/** Some fields by name, or every field. */
+export type Fields = ReadonlySet<string> | 'all'
+
+export interface ModelChanges {
+	readonly inserts?: Rows
+	readonly updates?: Rows
+	readonly deletes?: Rows
+	/** The fields its updates set. */
+	readonly fields?: Fields
+}
+
+export type Batch = ReadonlyMap<string, ModelChanges>
+
+type Building = {
+	inserts?: Set<string> | 'all'
+	updates?: Set<string> | 'all'
+	deletes?: Set<string> | 'all'
+	fields?: Set<string> | 'all'
+}
+
+const merge = (
+	into: Set<string> | 'all' | undefined,
+	values: readonly string[] | undefined,
+): Set<string> | 'all' => {
+	if (into === 'all' || values === undefined) return 'all'
+	const set = into ?? new Set<string>()
+	for (const value of values) set.add(value)
+	return set
+}
+
+/** `changes` by model; a link's sides are found in `schema`. */
+export function batchOf(changes: readonly Changed[], schema: Schema): Batch {
+	const batch = new Map<string, Building>()
+	const of = (model: string): Building => {
+		const known = batch.get(model)
+		if (known !== undefined) return known
+		const created: Building = {}
+		batch.set(model, created)
+		return created
+	}
+	const updated = (
+		model: string,
+		ids: readonly string[] | undefined,
+		fields: readonly string[] | undefined,
+	): void => {
+		const building = of(model)
+		building.updates = merge(building.updates, ids)
+		building.fields = merge(building.fields, fields)
+	}
+	for (const change of changes) {
+		if (change.kind === 'link' || change.kind === 'unlink') {
+			const field = schema.models
+				.find(({ name }) => name === change.model)
+				?.fields.find(({ name }) => name === change.field)
+			const pairs = change.pairs
+			updated(
+				change.model,
+				pairs?.map(([id]) => id),
+				[change.field],
+			)
+			if (field?.kind === 'many') {
+				updated(
+					field.target,
+					pairs?.map(([, id]) => id),
+					[field.inverse],
+				)
+			}
+		} else if (change.kind === 'update') {
+			updated(change.model, change.ids, change.fields)
+		} else if (change.kind === 'insert' || change.kind === 'delete') {
+			const building = of(change.model)
+			const kind = change.kind === 'insert' ? 'inserts' : 'deletes'
+			building[kind] = merge(building[kind], change.ids)
+		}
+	}
+	return batch
+}
+
+/** Whether `changes` updated one of `fields`. */
+export function touched(
+	changes: ModelChanges | undefined,
+	fields: Fields,
+): boolean {
+	const set = changes?.fields
+	if (changes?.updates === undefined || set === undefined) return false
+	if (set === 'all' || fields === 'all') return true
+	for (const field of set) if (fields.has(field)) return true
+	return false
+}
+
+/** Whether a list of `changes` is unknown. */
+export const unlisted = (changes: ModelChanges | undefined): boolean =>
+	changes?.inserts === 'all' ||
+	changes?.updates === 'all' ||
+	changes?.deletes === 'all'
+
+/** The ids of `rows`, none when they are every row. */
+export const listed = (rows: Rows | undefined): readonly string[] =>
+	rows === undefined || rows === 'all' ? [] : [...rows]

package/src/checked.ts

@@ -0,0 +1,59 @@
+// What a live read may ask (D-154): its order sorts by the model's own
+// fields, and its selection reaches only live models, each nested list with a
+// take. A refusal names the argument it comes from.
+import type { ExposedModel } from 'ultimabase'
+import { PublicError } from 'ultimabase'
+import type { LivePlan } from 'ultimabase/internal'
+import { liveSchema } from 'ultimabase/internal'
+import { modelsOf, stepOf } from './reach.ts'
+
+export const invalid = (path: string, message: string): PublicError =>
+	new PublicError('VALIDATION_FAILED', message, {
+		details: { issues: [{ path: [path], message }] },
+	})
+
+/**
+ * Refuses an order that reads another row and a selection that reaches a
+ * model which is not live; returns the nested rows each root row follows.
+ */
+export function checked(
+	exposed: readonly ExposedModel[],
+	model: string,
+	plan: Omit<LivePlan, 'where' | 'filter' | 'rights'>,
+	path: string,
+): number {
+	for (const order of plan.orderBy) {
+		if (order.through ?? order.count ?? order.relevance) {
+			throw invalid(
+				'orderBy',
+				`A live list sorts by ${model}'s own fields: ${order.field} reads another row.`,
+			)
+		}
+	}
+	const models = modelsOf(liveSchema())
+	const live = (target: string, at: string): void => {
+		const used = exposed.find(({ schema }) => schema.name === target)
+		if (!used?.used) throw invalid(at, `${target} is not live.`)
+	}
+	let rows = 0
+	for (const [name, inner] of Object.entries(plan.include ?? {})) {
+		const step = stepOf(models, model, name)
+		if (step === undefined) continue
+		const at = `${path}.${name}`
+		live(step.target, at)
+		const below = checked(exposed, step.target, { ...inner, orderBy: [] }, at)
+		if (!step.many) {
+			rows += below
+			continue
+		}
+		if (inner.take === undefined) {
+			throw invalid(at, `A live ${name} list needs a take.`)
+		}
+		rows += Math.abs(inner.take) * (1 + below)
+	}
+	for (const name of Object.keys(plan.count ?? {})) {
+		const step = stepOf(models, model, name)
+		if (step !== undefined) live(step.target, `${path}._count.${name}`)
+	}
+	return rows
+}

package/src/computed.ts

@@ -0,0 +1,141 @@
+// A live function (D-154): its run as the subscriber, with the reads it made,
+// run again once a write may change one of them, after a quiet wait. Each new
+// result is sent whole; one equal to the last is not. A wake during a run
+// runs it once more after it, and an error closes it.
+import { isDeepStrictEqual } from 'node:util'
+import type { Caller } from 'ultimabase'
+import type { Recorded } from 'ultimabase/internal'
+import { recording } from 'ultimabase/internal'
+import type { Batch } from './changes.ts'
+import type { LiveMessage } from './messages.ts'
+import type { Loader } from './reads.ts'
+import { anyStale } from './stale.ts'
+
+/** The longest a run waits after the first wake, however many follow. */
+const longest = 1000
+
+export type ComputedOptions = {
+	/** The function's result for `caller`, shaped as its transport sends it. */
+	readonly compute: (caller: Caller) => Promise<unknown>
+	readonly send: (message: LiveMessage) => void
+	/** How long a wake waits for quiet, in milliseconds. */
+	readonly debounce: number
+	/** Runs once a run kept its reads and expiry. */
+	readonly onRun: () => void
+	/** Runs once an error closed it, after it sent so. */
+	readonly onFail: () => void
+}
+
+export class Computed {
+	readonly #options: ComputedOptions
+	#caller: Caller
+	/** What the last run read. */
+	reads: readonly Recorded[] = []
+	/** When the last run stops holding, as a caller that expires. */
+	expires: Date | undefined
+	#revision = 0
+	#last: unknown
+	#first: number | undefined
+	#timer: NodeJS.Timeout | undefined
+	#running: Promise<void> | undefined
+	#again = false
+	#closed = false
+
+	constructor(options: ComputedOptions, caller: Caller) {
+		this.#options = options
+		this.#caller = caller
+	}
+
+	/** Runs it a first time; an error is thrown, as a refused subscription. */
+	async start(): Promise<void> {
+		const ran = await recording(async () => this.#options.compute(this.#caller))
+		this.#kept(ran)
+	}
+
+	/** Wakes it when a write in `batch` may change what it read. */
+	async apply(batch: Batch, loader: Loader, missed: boolean): Promise<void> {
+		if (this.#closed) return
+		if (missed || (await anyStale(this.reads, batch, loader))) this.#wake()
+	}
+
+	/** Runs it again at once as `caller`, whose rights changed. */
+	async replan(caller: Caller): Promise<void> {
+		this.#caller = caller
+		return this.#rerun()
+	}
+
+	/** Sends the last result again, as after messages were dropped. */
+	resend(): void {
+		if (this.#closed) return
+		this.#revision += 1
+		const value = this.#last
+		this.#options.send({ kind: 'value', revision: this.#revision, value })
+	}
+
+	close(): void {
+		this.#closed = true
+		clearTimeout(this.#timer)
+		this.#timer = undefined
+	}
+
+	#wake(): void {
+		const now = Date.now()
+		this.#first ??= now
+		clearTimeout(this.#timer)
+		const wait = Math.min(this.#options.debounce, this.#first + longest - now)
+		this.#timer = setTimeout(
+			() => {
+				this.#rerun().catch(() => undefined)
+			},
+			Math.max(wait, 0),
+		)
+		this.#timer.unref()
+	}
+
+	async #rerun(): Promise<void> {
+		clearTimeout(this.#timer)
+		this.#timer = undefined
+		this.#first = undefined
+		if (this.#closed) return
+		if (this.#running !== undefined) {
+			this.#again = true
+			return this.#running
+		}
+		this.#running = this.#run()
+		try {
+			await this.#running
+		} finally {
+			this.#running = undefined
+		}
+		if (!this.#again) return
+		this.#again = false
+		return this.#rerun()
+	}
+
+	async #run(): Promise<void> {
+		let ran: Awaited<ReturnType<typeof recording<unknown>>>
+		try {
+			ran = await recording(async () => this.#options.compute(this.#caller))
+		} catch (error) {
+			if (this.#closed) return
+			this.close()
+			this.#options.send({ kind: 'closed', error })
+			return this.#options.onFail()
+		}
+		if (!this.#closed) this.#kept(ran)
+	}
+
+	/** Keeps a run's reads and sends its result, unless the last was equal. */
+	#kept(ran: Awaited<ReturnType<typeof recording<unknown>>>): void {
+		this.reads = ran.reads
+		this.expires = ran.expires
+		this.#options.onRun()
+		if (this.#revision > 0 && isDeepStrictEqual(ran.result, this.#last)) {
+			return
+		}
+		this.#last = ran.result
+		this.#revision += 1
+		const value = ran.result
+		this.#options.send({ kind: 'value', revision: this.#revision, value })
+	}
+}