@ultimabase/postgres 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @ultimabase/postgres
+
+## 0.1.0
+
+### Minor Changes
+
+- 0e885c4: The first release: the kernel, its adapters, transports and plugins, the testing helpers and the starter.
+
+### Patch Changes
+
+- Updated dependencies [0e885c4]
+  - ultimabase@0.1.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/postgres
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The PostgreSQL adapter for UltimaBase, PostgreSQL 15 or later. In development, each start syncs the tables to the models; in production, migrations written as SQL files are applied by `ultimabase migrate deploy`.
+
+Documentation: [PostgreSQL](https://ultimabase.dev/docs/postgres).

package/dist/adapter.d.ts

@@ -0,0 +1,26 @@
+import type { LogEvent } from 'kysely';
+import type { Adapter } from 'ultimabase';
+export type Options = {
+    readonly url: string | undefined;
+    /** How many connections the pool opens at most (D-47). */
+    readonly connections?: number;
+    /** The milliseconds a query waits for a connection, or to open one. */
+    readonly wait?: number;
+    readonly log?: (event: LogEvent) => void;
+    /** The text search configuration of every `_search`, `'simple'` by default (D-148). */
+    readonly searchLanguage?: string;
+};
+/** What `postgres()` returns: an adapter that also runs raw SQL (D-137). */
+export type Postgres = Adapter & {
+    /**
+     * Runs one statement, in the open transaction if any, and returns its
+     * rows; each `${value}` is a parameter. No rule or hook runs.
+     */
+    readonly sql: <R extends object = Record<string, unknown>>(strings: TemplateStringsArray, ...values: readonly unknown[]) => Promise<R[]>;
+};
+/** Refuses a server below PostgreSQL 15 (D-50). */
+export declare function requireVersion(version: string | undefined): void;
+/** What a case-insensitive filter misses when `lower('É') <> 'é'` (D-140). */
+export declare function foldWarning(ctype: string): string;
+export declare function createAdapter(options: Options): Postgres;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,QAAQ,EAGR,MAAM,QAAQ,CAAA;AAKf,OAAO,KAAK,EACX,OAAO,EASP,MAAM,YAAY,CAAA;AAuBnB,MAAM,MAAM,OAAO,GAAG;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAA;IACxC,uFAAuF;IACvF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAChC,CAAA;AAED,4EAA4E;AAC5E,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG;IAChC;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxD,OAAO,EAAE,oBAAoB,EAC7B,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,KACzB,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;CACjB,CAAA;AAmED,mDAAmD;AACnD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIhE;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,CA2MxD"}

package/dist/adapter.js

@@ -0,0 +1,254 @@
+import { Kysely, PostgresDialect, sql } from 'kysely';
+import { Pool } from 'pg';
+import { CheckFailed, Refused } from 'ultimabase';
+import { joining, scratchable } from 'ultimabase/internal';
+import { aggregate } from './aggregate.js';
+import { decodeRows } from './decode.js';
+import { apply, remoteOf, reset, stored } from './migrations.js';
+import { Catalog } from './names.js';
+import { overflowed } from './numbers.js';
+import { fillsOf } from './fills.js';
+import { channelOf, listening } from './listen.js';
+import { plan } from './plan.js';
+import { pooled } from './pool.js';
+import { compileCount, compileFind } from './read.js';
+import { connecting, dropped, emptied, scratchName, trigrams, } from './scratch.js';
+import { parseSnapshot, snapshotOf } from './snapshot.js';
+import { compileWrite, translate } from './write.js';
+/** What the callback a rollback ends throws, which `rollback()` swallows. */
+const rolledBack = new Error('The transaction was rolled back.');
+/** `key` of a statement's first row, if it returned one. */
+function firstOf(rows, key) {
+    const [first] = rows;
+    if (typeof first !== 'object' || first === null)
+        return undefined;
+    const value = Reflect.get(first, key);
+    return value;
+}
+async function find(catalog, db, read) {
+    const { rows } = await compileFind(catalog, read).execute(db);
+    return decodeRows(catalog, read.model, firstOf(rows, 'rows'), read);
+}
+async function count(catalog, db, read) {
+    const { rows } = await compileCount(catalog, read).execute(db);
+    const value = firstOf(rows, 'count');
+    if (typeof value !== 'number')
+        throw new Error('The count is not a number.');
+    return value;
+}
+/** Runs a write's statements; the one that reads returns the rows. */
+async function run(catalog, db, given, statements) {
+    let rows;
+    try {
+        for (const statement of statements) {
+            const [first] = (await statement.sql.execute(db)).rows;
+            for (let at = 0; at < statement.checks; at += 1) {
+                if (first?.[`c${at}`] !== true)
+                    throw new CheckFailed(at);
+            }
+            if (first !== undefined && 'rows' in first)
+                rows = first['rows'];
+        }
+    }
+    catch (error) {
+        throw translate(catalog, overflowed(given, error));
+    }
+    const read = given.read;
+    // A `before` read of a model the write deletes nothing of reads none.
+    if (read === undefined || rows === undefined)
+        return [];
+    return decodeRows(catalog, read.model, rows, read);
+}
+async function write(catalog, db, given, channel) {
+    return run(catalog, db, given, compileWrite(catalog, given, channel));
+}
+/** Refuses a server below PostgreSQL 15 (D-50). */
+export function requireVersion(version) {
+    if (!(Number(version) >= 150000)) {
+        throw new Refused(`UltimaBase needs PostgreSQL 15 or later.`);
+    }
+}
+/** What a case-insensitive filter misses when `lower('É') <> 'é'` (D-140). */
+export function foldWarning(ctype) {
+    return `PostgreSQL folds case under its ${ctype} locale for ASCII only: a case-insensitive filter matches É and é in memory() but not here. Create the database with a UTF-8 locale, such as en_US.UTF-8.`;
+}
+export function createAdapter(options) {
+    const { url, connections = 10, wait = 10_000, searchLanguage } = options;
+    const remote = url ? remoteOf(url) : undefined;
+    let state;
+    /** A test file's schema, and whether a start created it. */
+    let scratch;
+    /** Each open transaction's own, for `sql` to join. */
+    const opens = new WeakMap();
+    const started = () => {
+        if (state === undefined)
+            throw new Error('postgres() is not started.');
+        return state;
+    };
+    const adapter = {
+        start: async (schema, logger, feed) => {
+            if (!url) {
+                throw new Refused('postgres() was given no url: is the variable it reads set?');
+            }
+            if (!Number.isInteger(connections) || connections < 1) {
+                throw new Refused(`postgres() takes connections as a whole number, 1 or more, not ${connections}.`);
+            }
+            const catalog = new Catalog(schema, searchLanguage);
+            // Refuses two things stored under one name before it connects.
+            const { tables } = snapshotOf(catalog);
+            const trigram = Object.values(tables).some((table) => Object.keys(table.trigrams).length > 0);
+            const extensions = scratch !== undefined && trigram ? [await trigrams(url)] : [];
+            const config = connecting(url, scratch?.name, extensions);
+            const pool = new Pool({
+                ...config,
+                max: connections,
+                connectionTimeoutMillis: wait,
+            });
+            // A connection the server ends would crash the process unheard. An
+            // idle one the pool drops, and the next query opens another; one a
+            // transaction holds fails its next statement, and the pool drops it
+            // once given back.
+            pool.on('error', () => undefined);
+            pool.on('connect', (client) => {
+                client.on('error', () => undefined);
+                // Compiling a nested read costs a hundred times more than running
+                // it; queued, this runs before the client's first query (D-47).
+                client.query('set jit = off').catch(() => undefined);
+            });
+            const dialect = new PostgresDialect({
+                pool: pooled(url, pool, connections, wait),
+            });
+            const db = new Kysely({
+                dialect,
+                ...(options.log === undefined ? {} : { log: options.log }),
+            });
+            try {
+                const { rows } = await sql `select current_setting('server_version_num') as version, current_schema() as schema,
+					lower('É') = 'é' as folds,
+					(select datctype from pg_database where datname = current_database()) as ctype,
+					exists (select from pg_ts_config as c join pg_namespace as n on n.oid = c.cfgnamespace where (c.cfgname = ${catalog.language} and pg_ts_config_is_visible(c.oid)) or n.nspname || '.' || c.cfgname = ${catalog.language}) as language`.execute(db);
+                const [server] = rows;
+                requireVersion(server?.version);
+                if (server?.language === false) {
+                    throw new Refused(`postgres() searches in '${catalog.language}', a text search configuration this server does not have.`);
+                }
+                if (server !== undefined && !server.folds) {
+                    logger.warn(foldWarning(server.ctype));
+                }
+                if (scratch !== undefined) {
+                    scratch.made = true;
+                    await emptied(db, scratch.name);
+                }
+                const channel = channelOf(scratch?.name ?? server?.schema ?? '');
+                state =
+                    feed === undefined
+                        ? { db, catalog }
+                        : {
+                            db,
+                            catalog,
+                            channel,
+                            listener: await listening(config, channel, feed, logger),
+                        };
+            }
+            catch (error) {
+                await db.destroy();
+                throw error;
+            }
+        },
+        stop: async () => {
+            const stopping = state;
+            state = undefined;
+            await stopping?.listener?.stop();
+            await stopping?.db.destroy();
+        },
+        find: async (read) => find(started().catalog, started().db, read),
+        count: async (read) => count(started().catalog, started().db, read),
+        aggregate: async (read) => aggregate(started().catalog, started().db, read),
+        write: async (given) => {
+            const { catalog, db, channel } = started();
+            const statements = compileWrite(catalog, given, channel);
+            // One statement is atomic alone: no BEGIN, no COMMIT (D-99).
+            if (statements.length <= 1)
+                return run(catalog, db, given, statements);
+            try {
+                return await db
+                    .transaction()
+                    .execute(async (trx) => run(catalog, trx, given, statements));
+            }
+            catch (error) {
+                // A deferred foreign key checks at the COMMIT (D-99).
+                throw translate(catalog, error);
+            }
+        },
+        migrations: {
+            snapshot: (schema) => snapshotOf(new Catalog(schema, searchLanguage)),
+            plan: (from, schema) => {
+                const catalog = new Catalog(schema, searchLanguage);
+                return plan(from === undefined ? undefined : parseSnapshot(from), snapshotOf(catalog), fillsOf(catalog));
+            },
+            stored: async () => stored(started().db),
+            apply: async (given) => apply(started().db, given),
+            reset: async () => reset(started().db),
+            ...(remote === undefined ? {} : { remote }),
+        },
+        begin: async () => {
+            const { catalog, db, channel } = started();
+            const opened = Promise.withResolvers();
+            const ending = Promise.withResolvers();
+            // Kysely gives the connection back however its transaction ends, a
+            // failed ROLLBACK included; a COMMIT that fails rolls back.
+            const ended = db.transaction().execute(async (trx) => {
+                opened.resolve(trx);
+                if (!(await ending.promise))
+                    throw rolledBack;
+            });
+            // A BEGIN that fails rejects `opened` too.
+            void ended.catch(opened.reject);
+            const trx = await opened.promise;
+            const end = async (commit) => {
+                ending.resolve(commit);
+                await ended;
+            };
+            const tx = {
+                find: async (read) => find(catalog, trx, read),
+                count: async (read) => count(catalog, trx, read),
+                aggregate: async (read) => aggregate(catalog, trx, read),
+                write: async (given) => write(catalog, trx, given, channel),
+                commit: async () => {
+                    try {
+                        await end(true);
+                    }
+                    catch (error) {
+                        throw translate(catalog, error);
+                    }
+                },
+                rollback: async () => {
+                    try {
+                        await end(false);
+                    }
+                    catch (error) {
+                        if (error !== rolledBack)
+                            throw error;
+                    }
+                },
+            };
+            opens.set(tx, trx);
+            return tx;
+        },
+        sql: async (strings, ...values) => joining(adapter, async (tx) => {
+            const db = (tx && opens.get(tx)) ?? started().db;
+            return (await sql(strings, ...values).execute(db)).rows;
+        }),
+    };
+    return scratchable(adapter, () => {
+        scratch = { name: scratchName(), made: false };
+        const own = scratch;
+        return {
+            drop: async () => {
+                scratch = undefined;
+                if (own.made && url)
+                    await dropped(url, own.name);
+            },
+        };
+    });
+}

package/dist/aggregate.d.ts

@@ -0,0 +1,8 @@
+import type { QueryExecutorProvider } from 'kysely';
+import type { AggregateRead } from 'ultimabase';
+import type { Sql } from './filter.ts';
+import type { Catalog } from './names.ts';
+export declare function compileAggregate(catalog: Catalog, read: AggregateRead): Sql;
+/** Each group's values, a date back as a `Date`. */
+export declare function aggregate(catalog: Catalog, db: QueryExecutorProvider, read: AggregateRead): Promise<unknown[][]>;
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAA;AAEnD,OAAO,KAAK,EAAa,aAAa,EAAoB,MAAM,YAAY,CAAA;AAC5E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,YAAY,CAAA;AAmDtD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,GAAG,CA8E3E;AAED,oDAAoD;AACpD,wBAAsB,SAAS,CAC9B,OAAO,EAAE,OAAO,EAChB,EAAE,EAAE,qBAAqB,EACzB,IAAI,EAAE,aAAa,GACjB,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAqBtB"}

package/dist/aggregate.js

@@ -0,0 +1,138 @@
+import { sql } from 'kysely';
+import { all, any, isFilters } from './filter.js';
+import { Compiler, sorted } from './read.js';
+/** A value as jsonb keeps it: a decimal as text, a date in UTC. */
+function shown(kind, item) {
+    if (kind === 'decimal')
+        return sql `cast(${item} as text)`;
+    return kind === 'dateTime' ? sql `(${item} at time zone 'UTC')` : item;
+}
+/** The aggregate of `column`, as PostgreSQL computes it. */
+function computed({ operation, field }, column) {
+    if (field === undefined)
+        return sql `count(*)`;
+    return sql `${sql.raw(operation)}(${column})`;
+}
+/** The aggregate as jsonb keeps it; a sum and an average as float8. */
+function value(kind, asked, column) {
+    const result = computed(asked, column);
+    const { operation, field } = asked;
+    if (field === undefined || operation === 'count')
+        return result;
+    if (kind === 'decimal' && operation !== 'avg')
+        return shown(kind, result);
+    if (operation === 'sum' || operation === 'avg') {
+        return sql `cast(${result} as float8)`;
+    }
+    return shown(kind, result);
+}
+/** The kind of a key's value: its field's, on the model `through` reaches. */
+function kindOf(catalog, table, key) {
+    let at = table;
+    for (const step of key.through ?? []) {
+        const field = at.fields.get(step.relation);
+        if (field === undefined || field.kind === 'scalar') {
+            throw new Error(`${at.model.name}.${step.relation} is not a relation.`);
+        }
+        at = catalog.table(field.target);
+    }
+    return catalog.kind(at, key.field);
+}
+/** Each aggregate's kind, `undefined` for a count of rows. */
+function kinds(catalog, table, read) {
+    return read.aggregates.map(({ field }) => field === undefined ? undefined : catalog.kind(table, field));
+}
+export function compileAggregate(catalog, read) {
+    const compiler = new Compiler(catalog);
+    const { filters } = compiler;
+    const alias = filters.alias();
+    const grouped = filters.alias();
+    const table = catalog.table(read.model);
+    const by = read.by ?? [];
+    const inner = [
+        ...by.map((key, at) => sql `${compiler.key(table, alias, key)} as ${sql.id(`k${at}`)}`),
+        ...read.aggregates.flatMap(({ field }, at) => field === undefined
+            ? []
+            : [sql `${filters.column(table, alias, field)} as ${sql.id(`c${at}`)}`]),
+    ];
+    const keys = by.map((_, at) => sql.id(grouped, `k${at}`));
+    const types = kinds(catalog, table, read);
+    const aggregates = read.aggregates.map((each, at) => {
+        const column = sql.id(grouped, `c${at}`);
+        return { kind: types[at], each, column };
+    });
+    const values = [
+        ...by.map((key, at) => shown(kindOf(catalog, table, key), sql.id(grouped, `k${at}`))),
+        ...aggregates.map(({ kind, each, column }) => value(kind, each, column)),
+    ];
+    // PostgreSQL takes at most 100 arguments per call.
+    const arrays = [];
+    for (let at = 0; at < values.length; at += 100) {
+        arrays.push(sql `jsonb_build_array(${sql.join(values.slice(at, at + 100))})`);
+    }
+    const where = filters.where(read.model, alias, read.where);
+    const rows = sql `(select ${sql.join([sql `1`, ...inner])} from ${sql.id(table.name)} as ${sql.id(alias)} where ${where}) as ${sql.id(grouped)}`;
+    const group = by.length === 0 ? sql `` : sql ` group by ${sql.join(keys)}`;
+    // A key or an aggregate, by its position.
+    const at = (index) => {
+        const found = aggregates[index - by.length];
+        const key = by[index];
+        if (found === undefined) {
+            if (key === undefined)
+                throw new Error(`No value at ${index}.`);
+            const kind = kindOf(catalog, table, key);
+            return { item: sql.id(grouped, `k${index}`), kind };
+        }
+        const { operation } = found.each;
+        const kind = operation === 'min' || operation === 'max'
+            ? (found.kind ?? 'number')
+            : operation === 'sum' && found.kind === 'decimal'
+                ? 'decimal'
+                : 'number';
+        return { item: computed(found.each, found.column), kind };
+    };
+    const kept = (filter) => all(Object.entries(filter).map(([key, part]) => condition(key, part)));
+    function condition(key, part) {
+        if (part === undefined)
+            return sql `true`;
+        if (!isFilters(part)) {
+            const { item, kind } = at(Number(key));
+            return filters.compare(item, kind, part);
+        }
+        const list = part.map((each) => kept(each));
+        if (key === 'AND')
+            return all(list);
+        if (key === 'OR')
+            return any(list);
+        return all(list.map((each) => sql `(not ${each})`));
+    }
+    const having = read.having === undefined ? sql `` : sql ` having ${kept(read.having)}`;
+    const sorts = (read.orderBy ?? []).map((each) => sorted(at(each.at).item, each));
+    const order = sorts.length === 0 ? sql `` : sql ` order by ${sql.join(sorts)}`;
+    const limit = read.take === undefined ? sql `` : sql ` limit ${read.take}`;
+    const offset = read.skip === undefined ? sql `` : sql ` offset ${read.skip}`;
+    return sql `select ${sql.join(arrays, sql ` || `)} as "values" from ${rows}${group}${having}${order}${limit}${offset}`;
+}
+/** Each group's values, a date back as a `Date`. */
+export async function aggregate(catalog, db, read) {
+    const { rows } = await compileAggregate(catalog, read).execute(db);
+    const table = catalog.table(read.model);
+    const by = read.by ?? [];
+    const types = [
+        ...by.map((key) => kindOf(catalog, table, key)),
+        ...kinds(catalog, table, read),
+    ];
+    return rows.map((row) => {
+        const values = typeof row === 'object' && row !== null
+            ? Reflect.get(row, 'values')
+            : undefined;
+        if (!Array.isArray(values))
+            throw new Error('The values are not a list.');
+        return types.map((kind, index) => {
+            const item = values[index];
+            return typeof item === 'string' && kind === 'dateTime'
+                ? new Date(`${item}Z`)
+                : item;
+        });
+    });
+}

package/dist/decode.d.ts

@@ -0,0 +1,5 @@
+import type { Nested, Row } from 'ultimabase';
+import type { Catalog } from './names.ts';
+/** The rows of a jsonb array of `model`, with the relations `nested` includes. */
+export declare function decodeRows(catalog: Catalog, model: string, value: unknown, nested: Nested): Row[];
+//# sourceMappingURL=decode.d.ts.map

package/dist/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../src/decode.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,YAAY,CAAA;AAE7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AA+BzC,kFAAkF;AAClF,wBAAgB,UAAU,CACzB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GACZ,GAAG,EAAE,CAIP"}

package/dist/decode.js

@@ -0,0 +1,30 @@
+import { isRow } from 'ultimabase/internal';
+const dates = new Set(['createdAt', 'updatedAt']);
+function decodeRow(catalog, model, value, nested) {
+    if (!isRow(value))
+        throw new Error(`A ${model} row has no id.`);
+    const table = catalog.table(model);
+    const row = { ...value };
+    for (const [name, item] of Object.entries(value)) {
+        const field = table.fields.get(name);
+        const inner = nested.include?.[name];
+        if (typeof item === 'string' &&
+            (dates.has(name) ||
+                (field?.kind === 'scalar' && field.type === 'dateTime'))) {
+            row[name] = new Date(`${item}Z`);
+        }
+        else if (inner !== undefined && field?.kind === 'many') {
+            row[name] = decodeRows(catalog, field.target, item, inner);
+        }
+        else if (inner !== undefined && field?.kind === 'one' && item !== null) {
+            row[name] = decodeRow(catalog, field.target, item, inner);
+        }
+    }
+    return row;
+}
+/** The rows of a jsonb array of `model`, with the relations `nested` includes. */
+export function decodeRows(catalog, model, value, nested) {
+    if (!Array.isArray(value))
+        throw new Error(`The ${model} rows are not a list.`);
+    return value.map((item) => decodeRow(catalog, model, item, nested));
+}

package/dist/fills.d.ts

@@ -0,0 +1,16 @@
+import type { Catalog } from './names.ts';
+export declare const literal: (value: string) => string;
+/** A fixed default as SQL, and as the log shows it: `'draft'`. */
+export type Fill = {
+    readonly sql: string;
+    readonly shown: string;
+};
+/** Each table's columns with a fixed default (D-105). */
+export type Fills = {
+    readonly [table: string]: {
+        readonly [column: string]: Fill;
+    };
+};
+/** The columns whose field has a fixed default, which rows take when added. */
+export declare function fillsOf(catalog: Catalog): Fills;
+//# sourceMappingURL=fills.d.ts.map

package/dist/fills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fills.d.ts","sourceRoot":"","sources":["../src/fills.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAQ,MAAM,YAAY,CAAA;AAE/C,eAAO,MAAM,OAAO,UAAW,MAAM,KAAG,MACL,CAAA;AAEnC,kEAAkE;AAClE,MAAM,MAAM,IAAI,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnE,yDAAyD;AACzD,MAAM,MAAM,KAAK,GAAG;IACnB,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;CAC7D,CAAA;AAsBD,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,KAAK,CAe/C"}

package/dist/fills.js

@@ -0,0 +1,37 @@
+export const literal = (value) => `'${value.replaceAll("'", "''")}'`;
+function fillOf(kind, value) {
+    if (kind.endsWith('[]') && Array.isArray(value)) {
+        const items = value.map((item) => `"${String(item).replaceAll(/[\\"]/g, '\\$&')}"`);
+        const text = literal(`{${items.join(',')}}`);
+        return { sql: `${text}::${kind}`, shown: text };
+    }
+    if (kind === 'json') {
+        const text = literal(JSON.stringify(value));
+        return { sql: `${text}::jsonb`, shown: text };
+    }
+    if (value instanceof Date) {
+        const text = literal(value.toISOString());
+        return { sql: `${text}::timestamptz`, shown: text };
+    }
+    const text = typeof value === 'string' ? literal(value) : String(value);
+    return { sql: text, shown: text };
+}
+/** The columns whose field has a fixed default, which rows take when added. */
+export function fillsOf(catalog) {
+    const fills = {};
+    for (const table of catalog.tables.values()) {
+        const columns = {};
+        for (const field of table.model.fields) {
+            if (field.kind !== 'scalar')
+                continue;
+            // A list's rows hold `[]` when nothing else is given (D-120).
+            const given = field.list ? (field.default ?? []) : field.default;
+            if (given === undefined)
+                continue;
+            const kind = catalog.kind(table, field.name);
+            columns[catalog.column(table, field.name)] = fillOf(kind, given);
+        }
+        fills[table.name] = columns;
+    }
+    return fills;
+}

package/dist/filter.d.ts

@@ -0,0 +1,50 @@
+import type { Condition, Filter, SchemaField } from 'ultimabase';
+import type { Sql } from './logic.ts';
+import type { Catalog, Kind, Table } from './names.ts';
+export type { Sql } from './logic.ts';
+export { all, any } from './logic.ts';
+type Relation = Extract<SchemaField, {
+    readonly kind: 'one' | 'many';
+}>;
+/** The rows a relation reaches: `from`, then what ties them to the row. */
+export type Reach = {
+    readonly from: Sql;
+    readonly on: Sql;
+};
+export declare const uuid: RegExp;
+/**
+ * A value as a parameter of its column's type. A date goes in UTC: `pg`
+ * writes it in local time to the minute, and a local offset of an old date
+ * has seconds, as Paris's +00:09:21 before 1911.
+ */
+export declare function value(kind: Kind, item: unknown): Sql;
+export declare function isFilters(item: Condition | readonly Filter[]): item is readonly Filter[];
+export declare class Filters {
+    readonly catalog: Catalog;
+    /** The tables the compiled conditions reach, besides their own. */
+    readonly tables: Set<string>;
+    /** A write's change index → the CTE of its delete, for `removedBy`. */
+    readonly removed: ReadonlyMap<number, string>;
+    private next;
+    constructor(catalog: Catalog, removed?: ReadonlyMap<number, string>);
+    /** A table alias no other part of the statement uses. */
+    alias(): string;
+    column(table: Table, alias: string, name: string): Sql;
+    where(model: string, alias: string, filter: Filter | undefined): Sql;
+    /** `text` as `websearch_to_tsquery` reads it, in the catalog's language (D-148). */
+    query(text: string): Sql;
+    /** The rows of `field`'s target, aliased `to`, that `alias`'s row reaches. */
+    reach(table: Table, alias: string, field: Relation, to: string): Reach;
+    private exists;
+    private relation;
+    private scalar;
+    /** A value of `kind`, a column or an aggregate (D-149), meets `condition`. */
+    compare(column: Sql, kind: Kind, condition: Condition): Sql;
+    /** A string that is not an id equals no id, as in `memory()` (D-98). */
+    private equal;
+    /** `in`: no item is false; an item no known value equals is dropped. */
+    private member;
+    /** `in` ignoring case: one `ilike` per item (D-140). */
+    private like;
+}
+//# sourceMappingURL=filter.d.ts.map

package/dist/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEhE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAA;AAErC,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEtD,YAAY,EAAE,GAAG,EAAE,MAAM,YAAY,CAAA;AACrC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,YAAY,CAAA;AAErC,KAAK,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAAA;CAAE,CAAC,CAAA;AAEvE,2EAA2E;AAC3E,MAAM,MAAM,KAAK,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAA;CAAE,CAAA;AAE5D,eAAO,MAAM,IAAI,EAAE,MAC8C,CAAA;AAEjE;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,GAAG,GAAG,CAQpD;AAED,wBAAgB,SAAS,CACxB,IAAI,EAAE,SAAS,GAAG,SAAS,MAAM,EAAE,GACjC,IAAI,IAAI,SAAS,MAAM,EAAE,CAE3B;AAED,qBAAa,OAAO;IACnB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAY;IACxC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7C,OAAO,CAAC,IAAI,CAAI;IAEhB,YACC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,EAIhD;IAED,yDAAyD;IACzD,KAAK,IAAI,MAAM,CAGd;IAED,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAErD;IAED,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,GAAG,CA6BnE;IAED,oFAAoF;IACpF,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAEvB;IAED,8EAA8E;IAC9E,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,KAAK,CAyBrE;IAED,OAAO,CAAC,MAAM;IAad,OAAO,CAAC,QAAQ;IA4ChB,OAAO,CAAC,MAAM;IAUd,8EAA8E;IAC9E,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,GAAG,GAAG,CAuE1D;IAED,wEAAwE;IACxE,OAAO,CAAC,KAAK;IAOb,wEAAwE;IACxE,OAAO,CAAC,MAAM;IAed,wDAAwD;IACxD,OAAO,CAAC,IAAI;CAQZ"}