ultimabase 0.0.0-stage → 0.1.0

package/src/memory-json.ts

@@ -0,0 +1,91 @@
+// How `memory()` tests a json value at a path (D-149), as PostgreSQL's
+// `#>`, `@>` and jsonb comparisons do (D-94).
+import type { Condition } from './adapter.ts'
+import { compareValues, lower, same, text } from './memory-values.ts'
+import { isObject } from './query-where.ts'
+
+type Truth = boolean | null
+
+/** An array's index as PostgreSQL's `strtoint` reads it; `undefined` when not one. */
+function indexOf(key: string, length: number): number | undefined {
+	if (!/^[\t\n\v\f\r ]*[+-]?\d+$/.test(key)) return undefined
+	const index = Number(key)
+	if (index < -2_147_483_647 || index > 2_147_483_647) return undefined
+	return index < 0 ? length + index : index
+}
+
+/** The value at `path`, `undefined` where the value lacks it. */
+function at(value: unknown, path: readonly string[]): unknown {
+	let current = value
+	for (const key of path) {
+		if (Array.isArray(current)) {
+			const index = indexOf(key, current.length)
+			current = index === undefined || index < 0 ? undefined : current[index]
+		} else if (isObject(current) && Object.hasOwn(current, key)) {
+			current = current[key]
+		} else return undefined
+	}
+	return current
+}
+
+/** `@>`: a nested value is held only by a value of its own JSON type. */
+function holds(container: unknown, item: unknown): boolean {
+	if (Array.isArray(container) && Array.isArray(item)) {
+		return item.every((each) => container.some((one) => holds(one, each)))
+	}
+	if (isObject(container) && isObject(item)) {
+		return Object.entries(item).every(
+			([key, each]) =>
+				Object.hasOwn(container, key) && holds(container[key], each),
+		)
+	}
+	return (
+		!Array.isArray(container) && !isObject(container) && same(container, item)
+	)
+}
+
+const typeOf = (value: unknown): string =>
+	Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value
+
+/** A json condition with `path`: unknown where the value lacks the path. */
+export function jsonPath(stored: unknown, condition: Condition): Truth {
+	const value = stored === null ? undefined : at(stored, condition.path ?? [])
+	if (value === undefined) return null
+	const fold =
+		condition.mode === 'insensitive' ? lower : (item: unknown) => item
+	const strings = (test: (a: string, b: string) => boolean, operand: unknown) =>
+		text(fold(value), fold(operand), test)
+	const items: readonly unknown[] = Array.isArray(value) ? value : []
+	const truths: boolean[] = []
+	for (const [operator, operand] of Object.entries(condition)) {
+		if (operand === undefined || operator === 'mode' || operator === 'path')
+			continue
+		if (operator === 'equals') truths.push(same(value, operand))
+		else if (operator === 'not') truths.push(!same(value, operand))
+		else if (operator === 'stringContains') {
+			truths.push(strings((a, b) => a.includes(b), operand))
+		} else if (operator === 'stringStartsWith') {
+			truths.push(strings((a, b) => a.startsWith(b), operand))
+		} else if (operator === 'stringEndsWith') {
+			truths.push(strings((a, b) => a.endsWith(b), operand))
+		} else if (operator === 'arrayContains') {
+			truths.push(Array.isArray(value) && holds(value, operand))
+		} else if (operator === 'arrayStartsWith') {
+			truths.push(items.length > 0 && same(items[0], operand))
+		} else if (operator === 'arrayEndsWith') {
+			truths.push(items.length > 0 && same(items.at(-1), operand))
+		} else {
+			const order = compareValues(value, operand)
+			const kept =
+				operator === 'lt'
+					? order < 0
+					: operator === 'lte'
+						? order <= 0
+						: operator === 'gt'
+							? order > 0
+							: order >= 0
+			truths.push(typeOf(value) === typeOf(operand) && kept)
+		}
+	}
+	return !truths.includes(false)
+}

package/src/memory-read.ts

@@ -0,0 +1,311 @@
+// How `memory()` reads: filters with SQL's three-valued logic, so that a
+// `null` compares as PostgreSQL would, then order, cursor and page.
+import type {
+	Condition,
+	Filter,
+	Nested,
+	Order,
+	Row,
+	SchemaField,
+	Step,
+} from './adapter.ts'
+import type { Truth } from './memory-conditions.ts'
+import { and, isFilters, not, or, scalar } from './memory-conditions.ts'
+import { compareKeys, copy, sortable } from './memory-values.ts'
+import { relevance, searches } from './memory-search.ts'
+import { modelOf } from './query-where.ts'
+
+/** A stored row; a stored `one` key is the target's id or `null`. */
+export type StoredRow = {
+	readonly id: string
+	readonly [field: string]: unknown
+}
+
+export type Store = {
+	readonly tables: Map<string, Map<string, StoredRow>>
+	/** `Model.field` → id → the linked ids, kept on both sides (D-64). */
+	readonly joins: Map<string, Map<string, Set<string>>>
+}
+
+/** A copy of the store, which a write changes and keeps once whole. */
+export function clone(store: Store): Store {
+	return {
+		tables: new Map(
+			[...store.tables].map(([name, table]) => [name, new Map(table)]),
+		),
+		joins: new Map(
+			[...store.joins].map(([key, side]) => [
+				key,
+				new Map([...side].map(([id, ids]) => [id, new Set(ids)])),
+			]),
+		),
+	}
+}
+
+/** Each model's fields by name. */
+export type Fields = ReadonlyMap<string, ReadonlyMap<string, SchemaField>>
+
+export class Reader {
+	readonly store: Store
+	readonly fields: Fields
+	/** A write's change index → the ids its delete removed, for `removedBy`. */
+	readonly removed: Map<number, ReadonlySet<string>> = new Map()
+
+	constructor(store: Store, fields: Fields) {
+		this.store = store
+		this.fields = fields
+	}
+
+	table(model: string): Map<string, StoredRow> {
+		return modelOf(this.store.tables, model)
+	}
+
+	field(model: string, name: string): SchemaField | undefined {
+		return this.fields.get(model)?.get(name)
+	}
+
+	/** The rows a relation of `row` points to. */
+	related(model: string, field: SchemaField, row: StoredRow): StoredRow[] {
+		if (field.kind === 'scalar') return []
+		const target = this.table(field.target)
+		if (field.kind === 'one' && field.stored) {
+			const key = row[field.name]
+			const found = typeof key === 'string' ? target.get(key) : undefined
+			return found === undefined ? [] : [found]
+		}
+		if (field.kind === 'many' && field.join) {
+			// A view reads the join of its relation (D-151).
+			const name = `${model}.${field.from ?? field.name}`
+			const ids = this.store.joins.get(name)?.get(row.id)
+			return [...(ids ?? [])].flatMap((id) => target.get(id) ?? [])
+		}
+		return [...target.values()].filter(
+			(other) => other[field.inverse] === row.id,
+		)
+	}
+
+	matches(model: string, row: StoredRow, filter: Filter | undefined): Truth {
+		if (filter === undefined) return true
+		const truths: Truth[] = []
+		for (const [key, value] of Object.entries(filter)) {
+			if (value === undefined) continue
+			if (key === 'AND' || key === 'OR' || key === 'NOT') {
+				const parts = (filter[key] ?? []).map((part) =>
+					this.matches(model, row, part),
+				)
+				if (key === 'AND') truths.push(and(parts))
+				else if (key === 'OR') truths.push(or(parts))
+				else truths.push(and(parts.map(not)))
+			} else if (isFilters(value)) {
+				throw new Error(`${model}.${key} takes a condition, not a list.`)
+			} else {
+				truths.push(this.condition(model, row, key, value))
+			}
+		}
+		return and(truths)
+	}
+
+	private condition(
+		model: string,
+		row: StoredRow,
+		name: string,
+		condition: Condition,
+	): Truth {
+		if (condition.search !== undefined) {
+			return searches(this.fields.get(model), row, condition.search)
+		}
+		const field = this.field(model, name)
+		if (field === undefined || field.kind === 'scalar') {
+			return scalar(row[name] ?? null, condition, (value) =>
+				sortable(value, field),
+			)
+		}
+		const rows = this.related(model, field, row)
+		const test = (filter: Filter): Truth[] =>
+			rows.map((other) => this.matches(field.target, other, filter))
+		const truths: Truth[] = []
+		if (condition.is !== undefined) {
+			truths.push(
+				condition.is === null
+					? rows.length === 0
+					: test(condition.is).includes(true),
+			)
+		}
+		if (condition.isNot !== undefined) {
+			truths.push(
+				condition.isNot === null
+					? rows.length > 0
+					: !test(condition.isNot).includes(true),
+			)
+		}
+		if (condition.some !== undefined) {
+			truths.push(test(condition.some).includes(true))
+		}
+		if (condition.every !== undefined) {
+			truths.push(!test(condition.every).includes(false))
+		}
+		if (condition.none !== undefined) {
+			truths.push(!test(condition.none).includes(true))
+		}
+		if (condition.removedBy !== undefined) {
+			// The key names a row an earlier delete of the write removed.
+			const removed = this.removed.get(condition.removedBy)
+			if (removed === undefined) throw new Error('No such delete.')
+			const key = row[field.name]
+			truths.push(typeof key === 'string' && removed.has(key))
+		}
+		return and(truths)
+	}
+
+	/** The row `through` reaches from `row`, and its model, if one (D-134). */
+	reach(
+		model: string,
+		row: StoredRow,
+		through: readonly Step[] = [],
+	): { readonly model: string; readonly row: StoredRow } | undefined {
+		let at: StoredRow | undefined = row
+		let on = model
+		for (const step of through) {
+			const field = this.field(on, step.relation)
+			if (field === undefined || field.kind === 'scalar') return undefined
+			const [next] = this.related(on, field, at)
+			at =
+				next !== undefined &&
+				this.matches(field.target, next, step.where) === true
+					? next
+					: undefined
+			if (at === undefined) return undefined
+			on = field.target
+		}
+		return { model: on, row: at }
+	}
+
+	/** A row's sort key: a field, through `one` relations, a count (D-134), a relevance (D-148). */
+	private key(model: string, row: StoredRow, order: Order): unknown {
+		if (order.relevance !== undefined) {
+			return relevance(this.fields.get(model), row, order.relevance)
+		}
+		const reached = this.reach(model, row, order.through)
+		if (reached === undefined) return null
+		const { model: on, row: at } = reached
+		if (order.count === undefined) {
+			return sortable(at[order.field] ?? null, this.field(on, order.field))
+		}
+		return this.count(on, at, order.field, order.count)
+	}
+
+	/** The rows of a `many` relation of `row` that `where` selects. */
+	private count(
+		model: string,
+		row: StoredRow,
+		name: string,
+		where: Filter,
+	): number {
+		const field = this.field(model, name)
+		if (field === undefined || field.kind === 'scalar') return 0
+		return this.related(model, field, row).filter(
+			(other) => this.matches(field.target, other, where) === true,
+		).length
+	}
+
+	/** Each row with its sort keys. */
+	private keyed(
+		model: string,
+		rows: readonly StoredRow[],
+		order: readonly Order[],
+	) {
+		return rows.map((row) => ({
+			row,
+			keys: order.map((each) => this.key(model, row, each)),
+		}))
+	}
+
+	/** Filters, orders and pages rows of `model`, as `read` asks. */
+	select(model: string, rows: StoredRow[], read: Nested): StoredRow[] {
+		const order = read.orderBy ?? [{ field: 'id', direction: 'asc' }]
+		const compare = (a: Keyed, b: Keyed) => compareKeys(a.keys, b.keys, order)
+		const found = this.keyed(
+			model,
+			rows.filter((row) => this.matches(model, row, read.where) === true),
+			order,
+		).toSorted(compare)
+		const skip = read.skip ?? 0
+		const take = read.take
+		if (take === 0) return []
+		let start = 0
+		let end = found.length
+		if (read.cursor !== undefined) {
+			const row = [...this.table(model).values()].find(
+				(each) => this.matches(model, each, read.cursor) === true,
+			)
+			if (row === undefined) return []
+			const [cursor] = this.keyed(model, [row], order)
+			if (cursor === undefined) return []
+			if (take === undefined || take > 0) {
+				const index = found.findIndex((each) => compare(each, cursor) >= 0)
+				start = index === -1 ? found.length : index
+			} else {
+				end = found.findLastIndex((each) => compare(each, cursor) <= 0)
+				end += 1
+			}
+		}
+		const sorted = found.map((each) => each.row)
+		if (take === undefined || take > 0) {
+			start += skip
+			return sorted.slice(start, take === undefined ? end : start + take)
+		}
+		end -= skip
+		return end <= 0 ? [] : sorted.slice(Math.max(start, end + take), end)
+	}
+
+	/** A row as the adapter returns it, with the relations `read` includes. */
+	output(model: string, row: StoredRow, read: Nested): Row {
+		const result: { id: string; [field: string]: unknown } = { id: row.id }
+		const fields = read.fields === undefined ? undefined : new Set(read.fields)
+		const reads = (name: string) => fields?.has(name) ?? true
+		for (const [key, value] of Object.entries(row)) {
+			const field = this.field(model, key)
+			if (!reads(key)) continue
+			if (field?.kind === 'one') {
+				result[key] = typeof value === 'string' ? { id: value } : null
+			} else {
+				result[key] = copy(value)
+			}
+		}
+		for (const field of this.fields.get(model)?.values() ?? []) {
+			if (field.kind === 'one' && !field.stored && reads(field.name)) {
+				const [other] = this.related(model, field, row)
+				result[field.name] = other === undefined ? null : { id: other.id }
+			}
+		}
+		for (const [name, nested] of Object.entries(read.include ?? {})) {
+			const field = this.field(model, name)
+			if (field === undefined || field.kind === 'scalar') continue
+			const rows = this.related(model, field, row)
+			if (field.kind === 'one') {
+				const [other] = rows
+				result[name] =
+					other !== undefined &&
+					this.matches(field.target, other, nested.where) === true
+						? this.output(field.target, other, nested)
+						: null
+			} else {
+				result[name] = this.select(field.target, rows, nested).map((other) =>
+					this.output(field.target, other, nested),
+				)
+			}
+		}
+		const counts = Object.entries(read.count ?? {})
+		if (counts.length > 0) {
+			result['_count'] = Object.fromEntries(
+				counts.map(([name, where]) => [
+					name,
+					this.count(model, row, name, where),
+				]),
+			)
+		}
+		return result
+	}
+}
+
+type Keyed = { readonly row: StoredRow; readonly keys: readonly unknown[] }

package/src/memory-search.ts

@@ -0,0 +1,149 @@
+// `memory()`'s full-text search (D-148), close to PostgreSQL's 'simple'
+// configuration: a word is a run of letters and digits, lowered, with no
+// stop words and no stems; the relevance follows `ts_rank`'s formulas.
+import type { SchemaField } from './adapter.ts'
+import { searchedFields } from './query-search.ts'
+
+/** A word or a phrase, each `-` before it negating it. */
+type Term = { readonly words: readonly string[]; readonly minus: number }
+
+/** Each word of a document and its positions, from 1. */
+type Document = ReadonlyMap<string, readonly number[]>
+
+type Fields = ReadonlyMap<string, SchemaField> | undefined
+
+const words = (text: string): string[] =>
+	text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []
+
+/** A quoted phrase, a `-`, an `or`, or a word and what follows it to a space. */
+const tokens = /"([^"]*)"?|-|or(?![\p{L}\p{N}])|[\p{L}\p{N}][^\s"]*/giu
+
+/**
+ * `websearch_to_tsquery`'s groups of terms: an `or` between two terms
+ * separates them, another is a word. A word of several words, `l'arbre`,
+ * is a phrase.
+ */
+function parse(text: string): Term[][] {
+	const groups: Term[][] = [[]]
+	let minus = 0
+	let operand = false
+	for (const { 0: token, 1: quoted, index } of text.matchAll(tokens)) {
+		if (token === '-') {
+			minus += 1
+			operand = false
+			continue
+		}
+		const rest = text.slice(index + token.length)
+		if (
+			quoted === undefined &&
+			token.toLowerCase() === 'or' &&
+			operand &&
+			/\S/u.test(rest)
+		) {
+			groups.push([])
+			operand = false
+			continue
+		}
+		const found = words(quoted ?? token)
+		if (found.length > 0) groups.at(-1)?.push({ words: found, minus })
+		minus = 0
+		operand = true
+	}
+	return groups.filter((group) => group.length > 0)
+}
+
+/** The searched fields of `row`, in declaration order, as one document. */
+function documentOf(
+	fields: Fields,
+	row: { readonly [field: string]: unknown },
+): Document {
+	const texts = searchedFields(fields?.values() ?? []).map((name) => row[name])
+	const result = new Map<string, number[]>()
+	const all = texts.filter((text) => typeof text === 'string').join(' ')
+	for (const [at, word] of words(all).entries()) {
+		result.set(word, [...(result.get(word) ?? []), at + 1])
+	}
+	return result
+}
+
+/** Whether the words of a phrase follow each other in `found`. */
+function has(found: Document, [first = '', ...rest]: readonly string[]) {
+	return (found.get(first) ?? []).some((at) =>
+		rest.every((word, index) => found.get(word)?.includes(at + index + 1)),
+	)
+}
+
+/** Whether `row` matches the search `text`; a text with no words matches none. */
+export function searches(
+	fields: Fields,
+	row: { readonly [field: string]: unknown },
+	text: string,
+): boolean {
+	const found = documentOf(fields, row)
+	return parse(text).some((group) =>
+		group.every((term) => has(found, term.words) === (term.minus % 2 === 0)),
+	)
+}
+
+/** An unweighted word's weight in `ts_rank`. */
+const weight = 0.1
+
+/** `ts_rank`'s `calc_rank_or`: each word found, by its occurrences. */
+function rankOr(found: Document, items: readonly string[]): number {
+	let sum = 0
+	for (const item of items) {
+		const positions = found.get(item) ?? []
+		if (positions.length === 0) continue
+		let occurrences = 0
+		for (const at of positions.keys()) occurrences += weight / (at + 1) ** 2
+		// The sum of 1/i² tends to π²/6.
+		sum += occurrences / 1.64493406685
+	}
+	return sum / items.length
+}
+
+/** How near two positions are in `calc_rank_and`. */
+const nearness = (distance: number): number =>
+	distance > 100 ? 1e-30 : 1 / (1.005 + 0.05 * Math.exp(distance / 1.5 - 2))
+
+/** `ts_rank`'s `calc_rank_and`: each pair of words found, by their distance. */
+function rankAnd(found: Document, items: readonly string[]): number {
+	let rank = -1
+	const lists = items.map((item) => found.get(item) ?? [])
+	for (const [index, mine] of lists.entries()) {
+		for (const theirs of lists.slice(0, index)) {
+			for (const a of mine) {
+				for (const b of theirs) {
+					if (a === b) continue
+					const near = Math.sqrt(weight * weight * nearness(Math.abs(a - b)))
+					rank = rank < 0 ? near : 1 - (1 - rank) * (1 - near)
+				}
+			}
+		}
+	}
+	return rank
+}
+
+/**
+ * How well `row` matches `text`, as `ts_rank` computes it in a `real`: an
+ * `and` of words or a phrase ranks their nearness, any other query its
+ * words' occurrences.
+ */
+export function relevance(
+	fields: Fields,
+	row: { readonly [field: string]: unknown },
+	text: string,
+): number {
+	const found = documentOf(fields, row)
+	const groups = parse(text)
+	const terms = groups.flat()
+	if (found.size === 0 || terms.length === 0) return 0
+	const items = [...new Set(terms.flatMap((term) => term.words))]
+	const [only] = terms
+	const and =
+		groups.length === 1 &&
+		(terms.length > 1 || (only?.minus === 0 && only.words.length > 1))
+	const rank =
+		and && items.length > 1 ? rankAnd(found, items) : rankOr(found, items)
+	return Math.fround(rank < 0 ? 1e-20 : rank)
+}

package/src/memory-values.ts

@@ -0,0 +1,106 @@
+// How `memory()` compares and copies values, as PostgreSQL would (D-94).
+import type { SchemaField, Sort } from './adapter.ts'
+import { unitsOf } from './decimal.ts'
+import { isObject } from './query-where.ts'
+
+/** Equality as PostgreSQL's: `-0` is `0`, json keys come in any order. */
+export function same(a: unknown, b: unknown): boolean {
+	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime()
+	if (Array.isArray(a) && Array.isArray(b))
+		return (
+			a.length === b.length && a.every((item, index) => same(item, b[index]))
+		)
+	if (isObject(a) && isObject(b)) {
+		const keys = Object.keys(a)
+		return (
+			keys.length === Object.keys(b).length &&
+			keys.every((key) => Object.hasOwn(b, key) && same(a[key], b[key]))
+		)
+	}
+	return a === b
+}
+
+/** A surrogate sorts above U+FFFF, as the code point it is part of. */
+const weight = (unit: number): number => {
+	if (unit >= 0xd8_00 && unit <= 0xdf_ff) return unit + 0x20_00
+	return unit >= 0xe0_00 ? unit - 0x8_00 : unit
+}
+
+/** A value as it sorts: a decimal as its units, by value (D-145). */
+export const sortable = (
+	value: unknown,
+	field: SchemaField | undefined,
+): unknown =>
+	field?.kind === 'scalar' &&
+	field.type === 'decimal' &&
+	typeof value === 'string'
+		? unitsOf(value, field.scale ?? 0)
+		: value
+
+/**
+ * Strings compare by code point, as PostgreSQL's `C` collation (D-94);
+ * dates, numbers and booleans by their number, a decimal's units exactly.
+ * Json values are not sorted.
+ */
+export function compareValues(a: unknown, b: unknown): number {
+	if (typeof a === 'bigint' && typeof b === 'bigint') {
+		return a < b ? -1 : a > b ? 1 : 0
+	}
+	if (typeof a === 'string' && typeof b === 'string') {
+		for (let index = 0; index < Math.min(a.length, b.length); index++) {
+			const order = weight(a.charCodeAt(index)) - weight(b.charCodeAt(index))
+			if (order !== 0) return order
+		}
+		return a.length - b.length
+	}
+	return Number(a) - Number(b)
+}
+
+/**
+ * `null` sorts as `nulls` says, by default last ascending and first
+ * descending, as in PostgreSQL (D-149).
+ */
+export function compareKeys(
+	a: readonly unknown[],
+	b: readonly unknown[],
+	order: readonly Sort[],
+): number {
+	for (const [at, { direction, nulls }] of order.entries()) {
+		const left = a[at] ?? null
+		const right = b[at] ?? null
+		if (left === null || right === null) {
+			if (left === right) continue
+			const last =
+				(nulls ?? (direction === 'asc' ? 'last' : 'first')) === 'last'
+			return (left === null) === last ? 1 : -1
+		}
+		const result = compareValues(left, right)
+		if (result !== 0) return direction === 'asc' ? result : -result
+	}
+	return 0
+}
+
+/** A stored value the caller may change without changing the store. */
+export function copy(value: unknown): unknown {
+	if (value instanceof Date) return new Date(value.getTime())
+	return typeof value === 'object' && value !== null
+		? structuredClone(value)
+		: value
+}
+
+/** A text operator; the `where` check lets only strings reach it. */
+export function text(
+	value: unknown,
+	operand: unknown,
+	test: (value: string, operand: string) => boolean,
+): boolean {
+	return (
+		typeof value === 'string' &&
+		typeof operand === 'string' &&
+		test(value, operand)
+	)
+}
+
+/** A string lowered for `mode: 'insensitive'` (D-140), any other value as is. */
+export const lower = (value: unknown): unknown =>
+	typeof value === 'string' ? value.toLowerCase() : value