@snolla/data 0.0.0-stage → 1.0.7

package/dist/freeze.d.ts

@@ -0,0 +1,29 @@
+import type { Kysely } from 'kysely';
+import type { Database } from './schema/generated/kysely-types.ts';
+type Db = Kysely<Database>;
+/**
+ * The freeze flag of one site. `null` means the site is not registered in *this*
+ * database — a different answer from "false", and one a cutover has to see.
+ */
+export declare const readWritable: (db: Db, siteId: string) => Promise<boolean | null>;
+/**
+ * Freezes or unfreezes one site and reports what it was, so a runbook can log a
+ * transition instead of an assumption. Idempotent: freezing an already frozen
+ * site is a no-op that still tells the truth.
+ */
+export declare const setWritable: (db: Db, siteId: string, writable: boolean) => Promise<{
+    ref: string;
+    previous: boolean;
+    writable: boolean;
+}>;
+/**
+ * A guarded handle for one site whose freeze state comes from the database rather
+ * than from the caller (the cell's path: authenticate, read the flag, send the
+ * handle up). The write grant is the caller's, and deny-by-default: without
+ * `{ writable: true }` the handle reads and cannot write (task:3865).
+ */
+export declare const siteGuard: (db: Db, siteId: string, { writable, frozen }?: {
+    writable?: boolean;
+    frozen?: boolean;
+}) => Promise<Kysely<Database>>;
+export {};

package/dist/freeze.js

@@ -0,0 +1,69 @@
+import { tenantGuard } from "./guard.js";
+const REGISTRY = 'Sites';
+const asBool = (value) => {
+    if (value === true || value === 1 || value === '1' || value === 1n)
+        return true;
+    if (value === false || value === 0 || value === '0' || value === 0n)
+        return false;
+    // neither driver form: guessing here would either freeze a site nobody froze or
+    // unfreeze one that was, and both are worse than a refused read
+    throw new Error(`freeze: unexpected Writable value ${JSON.stringify(value)} — the canon declares a boolean`);
+};
+const requireSiteId = (siteId) => {
+    if (typeof siteId !== 'string' || !siteId)
+        throw new Error('freeze: a site id is required');
+    return siteId;
+};
+/**
+ * The freeze flag of one site. `null` means the site is not registered in *this*
+ * database — a different answer from "false", and one a cutover has to see.
+ */
+export const readWritable = async (db, siteId) => {
+    const row = await db
+        .selectFrom(REGISTRY)
+        .select('Writable')
+        .where('SiteId', '=', requireSiteId(siteId))
+        .executeTakeFirst();
+    if (!row)
+        return null;
+    return asBool(row.Writable);
+};
+/**
+ * Freezes or unfreezes one site and reports what it was, so a runbook can log a
+ * transition instead of an assumption. Idempotent: freezing an already frozen
+ * site is a no-op that still tells the truth.
+ */
+export const setWritable = async (db, siteId, writable) => {
+    const ref = requireSiteId(siteId);
+    if (typeof writable !== 'boolean')
+        throw new Error('freeze: writable must be a boolean');
+    const previous = await readWritable(db, ref);
+    if (previous === null)
+        throw new Error(`freeze: site ${ref} is not registered in this database`);
+    if (previous !== writable) {
+        await db.updateTable(REGISTRY).set({ Writable: writable }).where('SiteId', '=', ref).execute();
+    }
+    // the report is read back, not assumed: if something else changed the flag under
+    // us, the caller sees the database's answer, not the intention
+    const actual = await readWritable(db, ref);
+    return { ref, previous, writable: actual === true };
+};
+/**
+ * A guarded handle for one site whose freeze state comes from the database rather
+ * than from the caller (the cell's path: authenticate, read the flag, send the
+ * handle up). The write grant is the caller's, and deny-by-default: without
+ * `{ writable: true }` the handle reads and cannot write (task:3865).
+ */
+export const siteGuard = async (db, siteId, { writable = false, frozen } = {}) => {
+    // `db` is meant to be the cell's own unguarded handle: a guard stacked on a guard
+    // is not additive — the inner one sees the statement first and its refusals stand —
+    // so passing an already-guarded handle here buys nothing but confusion.
+    const ref = requireSiteId(siteId);
+    // An explicit `frozen` skips the read: the caller asks the flag per request instead
+    // (admin-api's cell, task:3913) and uses this handle for the write grant only — a
+    // boot-time flag inside a long-lived handle goes stale in both directions.
+    const flag = frozen === undefined ? await readWritable(db, ref) : !frozen;
+    if (flag === null)
+        throw new Error(`freeze: site ${ref} is not registered in this database`);
+    return db.withPlugin(tenantGuard({ kind: 'site', siteId: ref, frozen: !flag, writable }));
+};

package/dist/guard.d.ts

@@ -0,0 +1,53 @@
+import type { KyselyPlugin } from 'kysely';
+/** Where the tenant key comes from: the session/cell config, never the request. */
+export type GuardMode = {
+    kind: 'site';
+    siteId: string;
+    /**
+     * Cutover freeze (task:3828, plan:50 Q6): a frozen site accepts reads and
+     * refuses every write. Required, not optional, on purpose — a guard that
+     * silently defaulted to "writable" would make the freeze a promise instead
+     * of a mechanism. Whoever builds a site handle states the flag, and the one
+     * path that reads it from the database is `siteGuard` (freeze.ts), which the
+     * cell is meant to use: `Sites.Writable` in, guard mode out.
+     */
+    frozen: boolean;
+    /**
+     * The write grant (task:3865): `frozen` says what the site is
+     * (`Sites.Writable`), `writable` says what this handle may do. Optional and
+     * deny-by-default — a reader does not state it, a writer must: writes go
+     * through only when `writable === true && !frozen`, and a missing grant is
+     * `SITE_READ_ONLY` rather than a silent write.
+     */
+    writable?: boolean;
+} | {
+    kind: 'control';
+}
+/**
+ * Declared transfer (task:3816): the only way a row changes tenant. Both
+ * ends are pinned by the context — the source predicate and the target key
+ * — so the payload still cannot name a tenant.
+ *
+ * A transfer writes (it rewrites the tenant key on the source's rows), so the
+ * write grant and the freeze answer for it exactly as they do for a site
+ * handle (task:3868) — EXCEPT on the system path: the janitor draining the
+ * system-owned bucket moves rows that never belonged to a customer and has no
+ * cutover window to respect. That is stated (`system: true`), never inferred.
+ */
+ | {
+    kind: 'transfer';
+    fromSiteId: string;
+    toSiteId: string;
+    /** The system path (janitor out of the sentinel bucket): not gated. */
+    system?: boolean;
+    /** The write grant, as on a site handle: a user-facing transfer needs it. */
+    writable?: boolean;
+    /** The SOURCE's state (`Sites.Writable`): a frozen source refuses a user transfer. */
+    frozen?: boolean;
+};
+export type TenantViolationCode = 'NO_SITE_CONTEXT' | 'FOREIGN_SITE_ID' | 'UNSAFE_RAW_SQL' | 'UNSUPPORTED_STATEMENT' | 'SITE_READ_ONLY' | 'SITE_FROZEN' | 'TABLE_OUTSIDE_CANON';
+export declare class TenantViolation extends Error {
+    readonly code: TenantViolationCode;
+    constructor(code: TenantViolationCode, message: string);
+}
+export declare const tenantGuard: (mode: GuardMode) => KyselyPlugin;

package/dist/guard.js

@@ -0,0 +1,397 @@
+// Tenant guard — the access-layer mechanism that keeps tenants apart
+// (task:3813; decisions: plan:48 R1-Q1/R1-Q2/R1-Q4, plan:49 Q4).
+//
+// Why a plugin and not RLS: row-level security exists only in Postgres, so
+// building isolation on it would make correctness dialect-specific and break
+// R2 ([[requirements:65]]). One Kysely plugin behaves the same on every
+// dialect; on Postgres a policy may be added later as a second belt.
+//
+// The tenant key never comes from the query. A `site`-mode guard carries the
+// site id it was built with, a `control`-mode guard carries none — and then it
+// may not touch site-scoped tables at all (deny-by-default).
+//
+// Deny-by-default reaches the write path too (task:3865): a site handle is
+// read-only unless its builder grants writes explicitly (`writable: true`). A
+// forgotten grant costs a refused write, never a write nobody intended — and the
+// freeze (`frozen`, task:3828) remains a second, independent stop.
+import { canonicalSchema, isSiteScoped } from "./schema/index.js";
+/** Tables that live in a site database, i.e. that must never be read unscoped. */
+const SITE_TABLES = new Set(canonicalSchema.tables.filter(isSiteScoped).map((t) => t.name));
+/**
+ * Every table the canon knows, site-scoped or not. The canon is the contract: a table it does
+ * not describe has no tenant key, no owner and no invariants — so the guard cannot scope it and
+ * must not pretend it did (task:3993: `LogEvents` fell out of the canon and its route kept
+ * reading every tenant, silently, because "not a site table" used to mean "not my business").
+ */
+const CANON_TABLES = new Set(canonicalSchema.tables.map((t) => t.name));
+export class TenantViolation extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TenantViolation';
+        this.code = code;
+    }
+}
+// ---------------------------------------------------------------------------
+// minimal operation-node builders (Kysely does not expose parseExpression)
+// ---------------------------------------------------------------------------
+const ident = (name) => ({ kind: 'IdentifierNode', name });
+const tableRef = (name) => ({ kind: 'TableNode', table: ident(name) });
+const columnRef = (qualifier, column) => ({
+    kind: 'ReferenceNode',
+    column: { kind: 'ColumnNode', column: ident(column) },
+    table: tableRef(qualifier),
+});
+const operator = (op) => ({ kind: 'OperatorNode', operator: op, op });
+const value = (v) => ({ kind: 'ValueNode', value: v });
+const equals = (left, right) => ({
+    kind: 'BinaryOperationNode',
+    leftOperand: left,
+    operator: operator('='),
+    rightOperand: right,
+});
+const and = (left, right) => ({
+    kind: 'BinaryOperationNode',
+    leftOperand: left,
+    operator: operator('and'),
+    rightOperand: right,
+});
+const parens = (node) => ({ kind: 'ParensNode', node });
+const isNode = (x) => typeof x === 'object' && x !== null && typeof x.kind === 'string';
+const tableNameOf = (node) => {
+    if (!isNode(node))
+        return null;
+    if (node.kind === 'AliasNode') {
+        // AliasNode: { node: TableNode, alias: IdentifierNode }
+        const inner = tableNameOf(node.node);
+        const alias = node.alias?.name;
+        if (inner && alias)
+            return { table: inner.table, qualifier: alias };
+        return inner;
+    }
+    if (node.kind === 'TableNode') {
+        const table = node.table;
+        const identNode = (table?.kind === 'SchemableIdentifierNode' ? table.identifier : table);
+        const name = identNode?.name;
+        return name ? { table: name, qualifier: name } : null;
+    }
+    return null;
+};
+const columnNameOf = (node) => {
+    if (!isNode(node))
+        return null;
+    if (node.kind === 'ColumnNode')
+        return (node.column?.name) ?? null;
+    if (node.kind === 'ReferenceNode')
+        return columnNameOf(node.column);
+    return null;
+};
+/** Tables referenced by a statement's own FROM/JOIN/target clause — every one of them. */
+const directTableRefs = (node) => {
+    const refs = [];
+    const push = (n) => {
+        const t = tableNameOf(n);
+        if (t)
+            refs.push(t);
+    };
+    const from = node.from;
+    for (const f of from?.froms ?? [])
+        push(f);
+    if (from?.from)
+        push(from.from);
+    for (const join of node.joins ?? [])
+        push(join.table);
+    if (node.into)
+        push(node.into);
+    if ((node.kind === 'UpdateQueryNode' || node.kind === 'DeleteQueryNode') && node.table)
+        push(node.table);
+    return refs;
+};
+/** Site tables referenced by a statement's own FROM/JOIN/target clause. */
+const directSiteRefs = (node) => directTableRefs(node)
+    .filter((ref) => SITE_TABLES.has(ref.table))
+    .map((ref) => ({ qualifier: ref.qualifier }));
+/**
+ * Identifiers inside a raw fragment. Raw SQL cannot be rewritten, so the scan
+ * has to answer one question without guessing: does this fragment name a
+ * site-scoped table? A substring test answers it wrongly in both directions —
+ * `where "Title" = 'Pages'` is not a table reference, and a name inside a
+ * comment is not code — so the fragment is tokenised: quoted identifiers
+ * (`"Pages"`, `` `Pages` ``) and bare words are identifiers, string literals,
+ * dollar-quoted bodies (`$$…$$`, `$tag$…$tag$`) and comments are not. Doubled
+ * quotes are the standard escape; a backslash-escaped literal (MySQL) should be
+ * parameterised instead of written raw.
+ */
+const sqlIdentifiers = (sql) => {
+    const tokens = [];
+    let i = 0;
+    while (i < sql.length) {
+        const ch = sql[i];
+        // the loop condition already bounded `i`; narrowing it once keeps the tokenizer
+        // readable under `noUncheckedIndexedAccess`
+        if (ch === undefined)
+            break;
+        if (ch === "'") {
+            i += 1;
+            while (i < sql.length) {
+                if (sql[i] !== "'") {
+                    i += 1;
+                }
+                else if (sql[i + 1] === "'") {
+                    i += 2;
+                }
+                else {
+                    i += 1;
+                    break;
+                }
+            }
+            continue;
+        }
+        if (ch === '-' && sql[i + 1] === '-') {
+            const end = sql.indexOf('\n', i + 2);
+            i = end === -1 ? sql.length : end + 1;
+            continue;
+        }
+        if (ch === '/' && sql[i + 1] === '*') {
+            const end = sql.indexOf('*/', i + 2);
+            i = end === -1 ? sql.length : end + 2;
+            continue;
+        }
+        if (ch === '"' || ch === '`') {
+            const quote = ch;
+            let name = '';
+            i += 1;
+            while (i < sql.length) {
+                if (sql[i] !== quote) {
+                    name += sql[i];
+                    i += 1;
+                }
+                else if (sql[i + 1] === quote) {
+                    name += quote;
+                    i += 2;
+                }
+                else {
+                    i += 1;
+                    break;
+                }
+            }
+            tokens.push(name);
+            continue;
+        }
+        if (ch === '$') {
+            // Postgres dollar-quoting: `$$…$$` or `$tag$…$tag$` is one literal;
+            // a lone `$1` parameter is not a quote and falls through to a word.
+            const opening = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql.slice(i));
+            if (opening) {
+                const closeAt = sql.indexOf(opening[0], i + opening[0].length);
+                i = closeAt === -1 ? sql.length : closeAt + opening[0].length;
+                continue;
+            }
+            i += 1;
+            continue;
+        }
+        if (/[A-Za-z_]/.test(ch)) {
+            const start = i;
+            while (i < sql.length && /[A-Za-z0-9_$]/.test(sql[i] ?? ''))
+                i += 1;
+            tokens.push(sql.slice(start, i));
+            continue;
+        }
+        i += 1;
+    }
+    return tokens;
+};
+/** Any site-scoped table name used as an identifier in a raw fragment. */
+const rawMentionsSiteTable = (fragments) => {
+    for (const fragment of fragments) {
+        if (typeof fragment !== 'string')
+            continue;
+        for (const token of sqlIdentifiers(fragment)) {
+            if (SITE_TABLES.has(token))
+                return token;
+        }
+    }
+    return null;
+};
+/** Statements that change rows — what a freeze has to stop. */
+const MUTATION_KINDS = new Set(['InsertQueryNode', 'UpdateQueryNode', 'DeleteQueryNode']);
+// What the grant and the freeze cover, stated so it is not assumed (review of
+// task:3865): the three typed DML builders above, and raw SQL that names a
+// site-scoped table (refused by the token scan, whichever statement it is).
+// Kysely has no builder for TRUNCATE, MERGE or DDL, so a site handle cannot reach
+// them through the typed API — through `sql` they are refused by name.
+// The declared transfer mode (`kind: 'transfer'`) used to be exempt from both;
+// task:3868 closed that: it is a write to the source, so it takes the same grant
+// and the same freeze — the system path says so explicitly with `system: true`.
+// ---------------------------------------------------------------------------
+// rewrite
+// ---------------------------------------------------------------------------
+const rewrite = (node, mode, seenSiteRefs) => {
+    if (Array.isArray(node))
+        return node.map((n) => rewrite(n, mode, seenSiteRefs));
+    if (!isNode(node))
+        return node;
+    if (node.kind === 'RawNode') {
+        const mentioned = rawMentionsSiteTable(node.sqlFragments ?? []);
+        if (mentioned) {
+            throw new TenantViolation('UNSAFE_RAW_SQL', `raw SQL mentions the site-scoped table "${mentioned}" and cannot be rewritten safely`);
+        }
+        return node;
+    }
+    // children first: subqueries are guarded on their own level
+    const next = { ...node };
+    for (const [key, child] of Object.entries(node)) {
+        if (isNode(child) || Array.isArray(child))
+            next[key] = rewrite(child, mode, seenSiteRefs);
+    }
+    const refs = directSiteRefs(next);
+    if (refs.length)
+        seenSiteRefs.push(...refs);
+    // before anything else asks what a table means, ask whether the canon knows it at all: an
+    // unknown table has no tenant key to force and no scope to respect, so the honest answer is
+    // a refusal naming the table, not a query that reads every tenant (task:3993)
+    const outside = directTableRefs(next).find((ref) => !CANON_TABLES.has(ref.table));
+    if (outside) {
+        throw new TenantViolation('TABLE_OUTSIDE_CANON', `the query reads "${outside.table}", which the canon does not describe — bring it into the canon ` +
+            '(schema/index.ts) if it belongs to the product, or read it through a handle without the tenant guard ' +
+            'if it does not: a table outside the canon has no tenant key, so no scoped read of it can be honest');
+    }
+    // the write grant is checked before the statement is rewritten, and without
+    // asking which table it happens to touch: a read-only handle has no legitimate
+    // write shape, and a granted one is still stopped by the freeze. The grant is
+    // the handle's authority (task:3865), the freeze the site's state (task:3828).
+    // The transfer answers to both (task:3868): it rewrites the tenant key of the
+    // source's rows — unless it declares itself the system path.
+    const gated = mode.kind === 'site' || (mode.kind === 'transfer' && mode.system !== true);
+    if (gated && MUTATION_KINDS.has(String(next.kind))) {
+        const who = mode.kind === 'site'
+            ? `site ${mode.siteId}`
+            : `transfer ${mode.fromSiteId} → ${mode.toSiteId}`;
+        if (mode.writable !== true) {
+            throw new TenantViolation('SITE_READ_ONLY', `${who}: this handle was not granted writes — build it with { writable: true } ` +
+                '(the writer path does; a reader needs no grant). Deny-by-default: a forgotten grant must not write');
+        }
+        if (mode.frozen === true) {
+            throw new TenantViolation('SITE_FROZEN', `${who} is frozen (Sites.Writable = false): writes are refused until the cutover window ends (plan:50 Q6)`);
+        }
+    }
+    switch (next.kind) {
+        case 'SelectQueryNode':
+        case 'DeleteQueryNode':
+            return applyWhere(next, refs, mode);
+        case 'UpdateQueryNode': {
+            const siteIdWrites = (next.updates ?? []).filter((u) => columnNameOf(u.column) === 'SiteId');
+            if (mode.kind === 'transfer') {
+                for (const write of siteIdWrites) {
+                    if (write.value?.kind !== 'ValueNode' || write.value.value !== mode.toSiteId) {
+                        throw new TenantViolation('FOREIGN_SITE_ID', `a transfer writes only its declared target (${mode.toSiteId}); the payload named another tenant`);
+                    }
+                }
+                if (!siteIdWrites.length) {
+                    next.updates = [
+                        ...(next.updates ?? []),
+                        {
+                            kind: 'ColumnUpdateNode',
+                            column: { kind: 'ColumnNode', column: ident('SiteId') },
+                            value: value(mode.toSiteId),
+                        },
+                    ];
+                }
+                return applyWhere(next, refs, mode);
+            }
+            if (siteIdWrites.length) {
+                throw new TenantViolation('FOREIGN_SITE_ID', 'the payload moves the row between tenants; SiteId is owned by the access layer');
+            }
+            return applyWhere(next, refs, mode);
+        }
+        case 'InsertQueryNode':
+            return applyInsert(next, refs, mode);
+        default:
+            return next;
+    }
+};
+const requireSiteId = (mode, table) => {
+    if (mode.kind === 'site')
+        return mode.siteId;
+    if (mode.kind === 'transfer')
+        return mode.fromSiteId;
+    throw new TenantViolation('NO_SITE_CONTEXT', `the query touches "${table ?? 'an unnamed table'}" but no site context is present (deny-by-default)`);
+};
+const applyWhere = (node, refs, mode) => {
+    if (!refs.length)
+        return node;
+    let predicate = null;
+    for (const ref of refs) {
+        const siteId = requireSiteId(mode, ref.qualifier);
+        const term = equals(columnRef(ref.qualifier, 'SiteId'), value(siteId));
+        predicate = predicate ? and(predicate, term) : term;
+    }
+    const existing = node.where;
+    const where = existing?.where
+        ? { kind: 'WhereNode', where: and(parens(existing.where), predicate) }
+        : { kind: 'WhereNode', where: predicate };
+    return { ...node, where };
+};
+const applyInsert = (node, refs, mode) => {
+    if (!refs.length)
+        return node;
+    if (mode.kind === 'transfer') {
+        throw new TenantViolation('UNSUPPORTED_STATEMENT', 'a transfer moves existing rows; it never inserts a tenant key');
+    }
+    const siteId = requireSiteId(mode, refs[0]?.qualifier);
+    const columns = node.columns ?? [];
+    if (columns.some((c) => columnNameOf(c) === 'SiteId')) {
+        throw new TenantViolation('FOREIGN_SITE_ID', 'the payload sets SiteId explicitly; the tenant key comes from the session context');
+    }
+    // `onConflict().doUpdateSet()` is a second write path inside one statement: the
+    // insert's column list says nothing about what the SET clause carries, so the
+    // tenant key is checked there too (review of task:3865)
+    const conflictUpdates = ((node.onConflict?.updates) ?? []);
+    if (conflictUpdates.some((update) => columnNameOf(update.column) === 'SiteId')) {
+        throw new TenantViolation('FOREIGN_SITE_ID', 'an upsert writes SiteId in its conflict payload; the tenant key is owned by the access layer');
+    }
+    const values = node.values;
+    if (!values || values.kind !== 'ValuesNode') {
+        throw new TenantViolation('UNSUPPORTED_STATEMENT', 'insert without a literal VALUES list cannot be scoped automatically');
+    }
+    const rows = (values.values ?? []).map((row) => {
+        if (!isNode(row))
+            throw new TenantViolation('UNSUPPORTED_STATEMENT', 'unsupported VALUES row');
+        if (row.kind === 'PrimitiveValueListNode')
+            return { ...row, values: [...row.values, siteId] };
+        if (row.kind === 'ValueListNode')
+            return { ...row, values: [...row.values, value(siteId)] };
+        throw new TenantViolation('UNSUPPORTED_STATEMENT', `unsupported VALUES row ${String(row.kind)}`);
+    });
+    return {
+        ...node,
+        columns: [...columns, { kind: 'ColumnNode', column: ident('SiteId') }],
+        values: { ...values, values: rows },
+    };
+};
+// ---------------------------------------------------------------------------
+// plugin
+// ---------------------------------------------------------------------------
+export const tenantGuard = (mode) => {
+    // the freeze is only as good as the handle that states it: a site guard built
+    // without an answer (a forgotten field in JS) is refused here, not at the first
+    // write, so a read-only handle cannot pass for a freeze-aware one
+    if (mode.kind === 'site' && typeof mode.frozen !== 'boolean') {
+        throw new Error('tenant-guard: a site guard must state `frozen` — read Sites.Writable (freeze.ts `readWritable`/`siteGuard`) instead of leaving it out');
+    }
+    // `writable` is deliberately NOT required: deny-by-default means a forgotten
+    // grant is read-only, so nothing has to be remembered to stay safe (task:3865)
+    return {
+        transformQuery(args) {
+            const seen = [];
+            const rewritten = rewrite(args.node, mode, seen);
+            if (mode.kind === 'control' && seen.length) {
+                throw new TenantViolation('NO_SITE_CONTEXT', `a control-plane instance may not touch site-scoped tables (${seen.map((r) => r.qualifier).join(', ')})`);
+            }
+            return rewritten;
+        },
+        async transformResult(_args) {
+            return _args.result;
+        },
+    };
+};

package/dist/insert.d.ts

@@ -0,0 +1,9 @@
+import type { Kysely } from 'kysely';
+/**
+ * Insert `values` into `table` and answer with the written row.
+ *
+ * `key` is the primary-key column: the dialect that cannot return the row reads it back by
+ * that key, so a caller on such a dialect must supply it — the canon's MariaDB DDL has no
+ * server-side id default, and inventing one here would hide that.
+ */
+export declare const insertAndReturn: (db: Kysely<any>, table: string, key: string, values: Record<string, unknown>) => Promise<any>;

package/dist/insert.js

@@ -0,0 +1,44 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/** The rows a driver answered with, whichever envelope it used (`output inserted` nests them). */
+const rowsOf = (answer) => Array.isArray(answer) ? answer : Array.isArray(answer?.rows) ? answer.rows : [];
+const readBack = async (db, table, key, id) => {
+    const row = await db.selectFrom(table).selectAll().where(key, '=', id).executeTakeFirst();
+    if (!row)
+        throw new Error(`${table}: the inserted row could not be read back`);
+    return row;
+};
+/**
+ * Insert `values` into `table` and answer with the written row.
+ *
+ * `key` is the primary-key column: the dialect that cannot return the row reads it back by
+ * that key, so a caller on such a dialect must supply it — the canon's MariaDB DDL has no
+ * server-side id default, and inventing one here would hide that.
+ */
+export const insertAndReturn = async (db, table, key, values) => {
+    const adapter = db.getExecutor?.().adapter;
+    const keyValue = values[key];
+    const noKey = () => new Error(`${table}: this dialect cannot return an inserted row — supply "${key}"`);
+    const readBackByKey = async () => {
+        if (keyValue === undefined)
+            throw noKey();
+        return readBack(db, table, key, keyValue);
+    };
+    let query = db.insertInto(table).values(values);
+    if (adapter?.supportsReturning)
+        query = query.returningAll();
+    else if (adapter?.supportsOutput)
+        query = query.outputAll('inserted');
+    else {
+        // Refuse before writing anything: an insert nobody can name is worse than no insert.
+        if (keyValue === undefined)
+            throw noKey();
+        await query.execute();
+        return readBackByKey();
+    }
+    // MariaDB declares `supportsReturning` and still answers `InsertResult` to
+    // `INSERT … RETURNING` through the mysql2 driver: the statement is portable, the row is
+    // not delivered. Read it back by the caller's key instead of answering a row-shaped
+    // hole (task:3913 — MariaDB is a cell target, not a curiosity).
+    const row = rowsOf(await query.execute())[0];
+    return row ?? (await readBackByKey());
+};