@assemora/data 0.1.0

package/dist/query.js

@@ -0,0 +1,307 @@
+/**
+ * Query builder (SPEC.md §19, §20, §30).
+ *
+ * Every call returns a new builder, so a query is safe to share and to derive from.
+ * The builder produces a Query AST and never touches an adapter's own query API.
+ */
+import { AssemoraError, currentContext } from '@assemora/core';
+import { comparison, group, jsonContains, jsonEquals, jsonLike, orComparison, UNSPECIFIED_LOCALE, } from '@assemora/database';
+import { execute } from './runtime.js';
+/**
+ * A pattern match needs a key to match against: matching a whole document as text is
+ * meaningless, and the adapters would disagree about what it even means.
+ */
+const jsonPath = (field, path) => {
+    if (path === '') {
+        throw new AssemoraError('INVALID_QUERY', `A pattern match on "${field}" needs a key inside the document`, { status: 400 });
+    }
+    return path.split('.');
+};
+/**
+ * A row count has to be a whole number that is not negative.
+ *
+ * Passed through unchecked, a `NaN` reaches the adapter, which drops the clause
+ * entirely — the query then returns every row instead of the page that was asked for.
+ */
+const countable = (method, count) => {
+    if (!Number.isInteger(count) || count < 0) {
+        throw new AssemoraError('INVALID_QUERY', `${method}() needs a whole number of rows`, {
+            status: 400,
+        });
+    }
+    return count;
+};
+const parsePath = (path) => {
+    const [head, ...rest] = path.split('.');
+    return {
+        relation: head ?? path,
+        nested: rest.length > 0 ? [parsePath(rest.join('.'))] : [],
+    };
+};
+const mergeLoads = (existing, addition) => {
+    const found = existing.find((load) => load.relation === addition.relation);
+    if (found === undefined)
+        return [...existing, addition];
+    return existing.map((load) => load.relation === addition.relation
+        ? {
+            relation: load.relation,
+            nested: addition.nested.reduce(mergeLoads, load.nested),
+        }
+        : load);
+};
+export const createQuery = (state, runtime) => {
+    const derive = (next) => createQuery({ ...state, ...next }, runtime);
+    const withCondition = (condition) => derive({ where: [...state.where, condition] });
+    /**
+     * The language this query reads in, or `undefined` for "every language".
+     *
+     * `undefined` is also what an application in one language answers, and what a query
+     * outside any context answers — a migration, a script, a test. Both mean the same
+     * thing here: no language filter, which is exactly what those reads did before §131.
+     */
+    const readsIn = () => {
+        if (!state.table().translatable)
+            return undefined;
+        if (state.locale === 'all')
+            return undefined;
+        if (state.locale !== 'context')
+            return state.locale.code;
+        return currentContext()?.locale;
+    };
+    /**
+     * Reading one language, and what counts as being written in it.
+     *
+     * The default language matches rows marked with it *and* rows marked with nothing:
+     * a row written before the deployment named any languages is in the language it was
+     * written in, which is the default. Without that, adding `locales` to a project that
+     * already had content would make all of it vanish (`UNSPECIFIED_LOCALE`).
+     */
+    const localeCondition = () => {
+        const code = readsIn();
+        if (code === undefined)
+            return [];
+        return code === currentContext()?.locales?.defaultLocale
+            ? [comparison('locale', 'in', [code, UNSPECIFIED_LOCALE])]
+            : [comparison('locale', '=', code)];
+    };
+    /**
+     * The state a `where(query => …)` group is built in.
+     *
+     * Empty conditions, and neither of the two the query adds by itself: a group is the
+     * caller's own parentheses and nothing else. `toAst()` is what the group is taken
+     * from, and it puts the soft-delete and language filters at the front — so a nested
+     * `orWhere` produced `(deletedAt is null AND a) OR b`, which is not the parentheses
+     * anybody wrote. It was invisible while the outer query repeated both conditions
+     * anyway; the fallback rewrites the language one, and then it is not invisible.
+     *
+     * Expressed as `trashed: 'with'` and `locale: 'all'` rather than as a third flag,
+     * because those are exactly what "add neither" already means.
+     */
+    const nestedState = () => ({
+        ...state,
+        where: [],
+        trashed: 'with',
+        locale: 'all',
+    });
+    const softDeleteCondition = () => {
+        const column = state.table().softDeleteColumn;
+        if (column === undefined || state.trashed === 'with')
+            return [];
+        if (state.trashed === 'only')
+            return [comparison(column, 'is not null')];
+        return [comparison(column, 'is null')];
+    };
+    /**
+     * The shorthand's default column, or a message that names the problem.
+     *
+     * Without this the query reached the adapter and came back as "No column is mapped
+     * for createdAt", which says nothing about `latest()` having filled it in.
+     */
+    const timeColumn = (field) => {
+        if (field !== undefined)
+            return field;
+        const table = state.table();
+        if (!table.columns.some((column) => column.name === 'createdAt')) {
+            throw new AssemoraError('INVALID_QUERY', `"${table.name}" has no createdAt column, so latest() and oldest() need one named: latest('publishedAt')`, { status: 400 });
+        }
+        return 'createdAt';
+    };
+    const toAst = () => ({
+        model: state.table().name,
+        operation: 'select',
+        where: [...softDeleteCondition(), ...localeCondition(), ...state.where],
+        order: state.order,
+        with: state.load,
+        ...(state.limit === undefined ? {} : { limit: state.limit }),
+        ...(state.offset === undefined ? {} : { offset: state.offset }),
+    });
+    /**
+     * The query that actually runs, with the fallback folded into it (SPEC.md §131).
+     *
+     * One query and not two, because `order`, `limit` and `offset` decide what a page
+     * *is*: two result sets appended would put every untranslated row after every
+     * translated one, and page two of a menu would be a different menu.
+     *
+     * It costs one extra read to build. The rows already written in this language are
+     * fetched first — under the caller's own `where`, with no order and no limit — and
+     * what comes back is the set of *groups* that need no fallback. The query then asks
+     * for those rows, plus the default-language row of every group not among them.
+     *
+     * The alternative is `distinct on` or a window function, which is a change to the
+     * Query AST every adapter would have to implement, and ADR-0013 is why that is not a
+     * thing to do lightly. This uses `in` and `not in`, which every adapter already
+     * agrees about.
+     */
+    const astToRun = async () => {
+        const base = toAst();
+        const code = readsIn();
+        const fallbackTo = currentContext()?.locales?.defaultLocale;
+        if (!state.fallback ||
+            code === undefined ||
+            fallbackTo === undefined ||
+            // The default language is where a fallback would come *from*. Nothing to do.
+            code === fallbackTo) {
+            return base;
+        }
+        const key = state.table().primaryKey;
+        // Deliberately without the caller's `order`, `limit` and `offset`: this asks which
+        // groups are already written in this language, and a page of that answer would
+        // leave the rest of them falling back when they should not.
+        const { limit: _limit, offset: _offset, ...whole } = base;
+        const written = await execute({ ...whole, order: [], with: [] }, { table: state.table(), related: runtime.related() });
+        /**
+         * What each row translates, or itself where it translates nothing.
+         *
+         * A row written directly in a language, with no original behind it, is its own
+         * group — otherwise an article first written in Russian would be answered twice.
+         */
+        const covered = written.map((row) => row.translationOf ?? row[key]);
+        return {
+            ...base,
+            where: [
+                ...softDeleteCondition(),
+                ...state.where,
+                /**
+                 * A combinator says how a condition joins the one before it, not how its own
+                 * children join each other — which is why `orComparison` exists at all. So the
+                 * outer group joins the caller's `where` with `and`, and the inner group joins
+                 * its sibling with `or`.
+                 */
+                group([
+                    comparison('locale', '=', code),
+                    group([
+                        // The same rule as `localeCondition`: the default language is also where
+                        // the rows that name no language belong.
+                        comparison('locale', 'in', [fallbackTo, UNSPECIFIED_LOCALE]),
+                        ...(covered.length === 0 ? [] : [comparison(key, 'not in', covered)]),
+                    ], 'or'),
+                ], 'and'),
+            ],
+        };
+    };
+    const run = async () => {
+        const rows = await execute(await astToRun(), {
+            table: state.table(),
+            related: runtime.related(),
+        });
+        return rows.map(runtime.hydrate);
+    };
+    const query = {
+        where(first, second, third) {
+            if (typeof first === 'function') {
+                const nested = first(createQuery(nestedState(), runtime));
+                return withCondition(group(nested.toAst().where));
+            }
+            if (typeof first === 'object' && first !== null) {
+                return Object.entries(first).reduce((accumulated, [field, value]) => accumulated.where(field, value), createQuery(state, runtime));
+            }
+            return third === undefined
+                ? withCondition(comparison(String(first), '=', second))
+                : withCondition(comparison(String(first), second, third));
+        },
+        orWhere(first, second, third) {
+            if (typeof first === 'function') {
+                const nested = first(createQuery(nestedState(), runtime));
+                return withCondition(group(nested.toAst().where, 'or'));
+            }
+            return third === undefined
+                ? withCondition(orComparison(String(first), '=', second))
+                : withCondition(orComparison(String(first), second, third));
+        },
+        whereIn: (field, values) => withCondition(comparison(field, 'in', values)),
+        whereNotIn: (field, values) => withCondition(comparison(field, 'not in', values)),
+        whereNull: (field) => withCondition(comparison(field, 'is null')),
+        whereNotNull: (field) => withCondition(comparison(field, 'is not null')),
+        whereBetween: (field, range) => withCondition(comparison(field, 'between', range)),
+        whereLike: (field, pattern) => withCondition(comparison(field, 'like', pattern)),
+        whereJson: (field, path, value) => withCondition(jsonEquals(field, path === '' ? [] : path.split('.'), value)),
+        whereJsonContains: (field, fragment) => withCondition(jsonContains(field, fragment)),
+        whereJsonLike: (field, path, pattern) => withCondition(jsonLike(field, jsonPath(field, path), pattern)),
+        orWhereJsonLike: (field, path, pattern) => withCondition(jsonLike(field, jsonPath(field, path), pattern, 'or')),
+        orderBy: (field, direction = 'asc') => derive({ order: [...state.order, { field, direction }] }),
+        latest: (field) => derive({ order: [...state.order, { field: timeColumn(field), direction: 'desc' }] }),
+        oldest: (field) => derive({ order: [...state.order, { field: timeColumn(field), direction: 'asc' }] }),
+        limit: (count) => derive({ limit: countable('limit', count) }),
+        offset: (count) => derive({ offset: countable('offset', count) }),
+        take: (count) => derive({ limit: countable('take', count) }),
+        with: (...relations) => derive({ load: relations.map(parsePath).reduce(mergeLoads, state.load) }),
+        withTrashed: () => derive({ trashed: 'with' }),
+        onlyTrashed: () => derive({ trashed: 'only' }),
+        inLocale: (code) => derive({ locale: { code } }),
+        allLocales: () => derive({ locale: 'all' }),
+        withoutFallback: () => derive({ fallback: false }),
+        get: run,
+        async first() {
+            const rows = await createQuery({ ...state, limit: 1 }, runtime).get();
+            return rows[0] ?? null;
+        },
+        async firstOrFail() {
+            const row = await query.first();
+            if (row === null) {
+                const { NotFoundError } = await import('@assemora/core');
+                throw new NotFoundError(state.table().name);
+            }
+            return row;
+        },
+        async count() {
+            return execute({ ...(await astToRun()), operation: 'count', order: [], with: [] }, { table: state.table() });
+        },
+        async exists() {
+            return (await query.count()) > 0;
+        },
+        async paginate(page = 1, perPage = 20) {
+            const total = await query.count();
+            const data = await createQuery({ ...state, limit: perPage, offset: (page - 1) * perPage }, runtime).get();
+            return { data, total, page, perPage, lastPage: Math.max(1, Math.ceil(total / perPage)) };
+        },
+        async cursorPaginate(perPage = 20, after) {
+            const key = state.table().primaryKey;
+            const page = createQuery({
+                ...state,
+                where: after === undefined ? state.where : [...state.where, comparison(key, '>', after)],
+                order: [{ field: key, direction: 'asc' }],
+                limit: perPage + 1,
+            }, runtime);
+            const rows = await page.get();
+            const data = rows.slice(0, perPage);
+            const last = data.at(-1);
+            return {
+                data,
+                nextCursor: rows.length > perPage && last !== undefined ? last[key] : null,
+            };
+        },
+        toAst,
+        // biome-ignore lint/suspicious/noThenProperty: SPEC.md §20 asks a query to be awaitable without a terminal method — that is what PromiseLike means
+        then(onFulfilled, onRejected) {
+            return run().then(onFulfilled, onRejected);
+        },
+    };
+    for (const [name, scope] of Object.entries(runtime.scopes)) {
+        Object.defineProperty(query, name, {
+            enumerable: false,
+            value: () => scope(query),
+        });
+    }
+    return query;
+};
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/dist/relations.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Relations (SPEC.md §23, §24).
+ *
+ * A relation names the other side through a thunk, so two models may reference each
+ * other without either declaration depending on the other's type.
+ */
+import type { RelationKind } from '@assemora/database';
+/** The minimum a relation needs to know about its target. */
+export type RelatedModel = {
+    readonly table: string;
+    readonly primaryKey: string;
+};
+export type RelationOptions = {
+    /** The column that holds the reference. Derived from the names when omitted. */
+    readonly foreignKey?: string;
+    /** The column it points at. The target's primary key when omitted. */
+    readonly ownerKey?: string;
+    /** The join table, for `belongsToMany` only. Named after both tables when omitted. */
+    readonly through?: string;
+    /**
+     * The join table column holding this model's key, for `belongsToMany` only.
+     * Derived from this model's table name when omitted — `users` gives `userId`.
+     *
+     * A model linked to itself has to name both: `userId` twice is not a link.
+     */
+    readonly foreignPivotKey?: string;
+    /** The join table column holding the target's key, for `belongsToMany` only. */
+    readonly relatedPivotKey?: string;
+};
+/**
+ * The kind is carried as a literal so a declaration can be told apart by it: only a
+ * `belongsToMany` has pivot verbs, and `PivotFields` decides that from the type alone
+ * (SPEC.md §24). Defaulted, so `Relation` still names any of them.
+ */
+export type Relation<K extends RelationKind = RelationKind> = RelationOptions & {
+    readonly node: 'relation';
+    readonly kind: K;
+    readonly target: () => RelatedModel;
+};
+/**
+ * A thunk returning the model on the other side: `() => Post`.
+ *
+ * Declared as `unknown` on purpose. Two models normally reference each other, and
+ * any structural parameter type — `() => RelatedModel`, even `() => unknown` —
+ * makes TypeScript resolve the target while the declaration that needs it is still
+ * being computed, which is the circular-reference error that would force every
+ * mutual relation to be annotated by hand. Erasing the type at this one boundary
+ * keeps the API of SPEC.md §9 and §23 working; what the thunk returns is checked at
+ * runtime instead, with a clear error (see ADR-0010).
+ */
+export type RelationTarget = unknown;
+/** This model holds the foreign key. */
+export declare const belongsTo: (target: RelationTarget, options?: RelationOptions) => Relation<'belongsTo'>;
+/** The other model holds the foreign key, and there is at most one row. */
+export declare const hasOne: (target: RelationTarget, options?: RelationOptions) => Relation<'hasOne'>;
+/** The other model holds the foreign key, and there may be many rows. */
+export declare const hasMany: (target: RelationTarget, options?: RelationOptions) => Relation<'hasMany'>;
+/**
+ * Both sides are linked through a join table, and the instance carries the verbs that
+ * write to it: `user.roles.attach(id)` (SPEC.md §24).
+ */
+export declare const belongsToMany: (target: RelationTarget, options?: RelationOptions) => Relation<'belongsToMany'>;
+export declare const isRelation: (value: unknown) => value is Relation;
+//# sourceMappingURL=relations.d.ts.map

package/dist/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../src/relations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,6DAA6D;AAC7D,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,gFAAgF;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI,eAAe,GAAG;IAC9E,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;IAChB,QAAQ,CAAC,MAAM,EAAE,MAAM,YAAY,CAAA;CACpC,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAA;AA0BpC,wCAAwC;AACxC,eAAO,MAAM,SAAS,WACZ,cAAc,YACZ,eAAe,KACxB,QAAQ,CAAC,WAAW,CAA2C,CAAA;AAElE,2EAA2E;AAC3E,eAAO,MAAM,MAAM,WAAY,cAAc,YAAY,eAAe,KAAG,QAAQ,CAAC,QAAQ,CACvD,CAAA;AAErC,yEAAyE;AACzE,eAAO,MAAM,OAAO,WAAY,cAAc,YAAY,eAAe,KAAG,QAAQ,CAAC,SAAS,CACxD,CAAA;AAEtC;;;GAGG;AACH,eAAO,MAAM,aAAa,WAChB,cAAc,YACZ,eAAe,KACxB,QAAQ,CAAC,eAAe,CAA+C,CAAA;AAE1E,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,QAC4C,CAAA"}

package/dist/relations.js

@@ -0,0 +1,26 @@
+const asRelatedModel = (target) => {
+    if (typeof target !== 'function') {
+        throw new TypeError('A relation target must be a function returning the related model');
+    }
+    const resolved = target();
+    if (typeof resolved !== 'object' ||
+        resolved === null ||
+        typeof resolved.table !== 'string') {
+        throw new TypeError('A relation target must be a function returning the related model');
+    }
+    return resolved;
+};
+const relation = (kind, target, options = {}) => ({ node: 'relation', kind, target: () => asRelatedModel(target), ...options });
+/** This model holds the foreign key. */
+export const belongsTo = (target, options) => relation('belongsTo', target, options);
+/** The other model holds the foreign key, and there is at most one row. */
+export const hasOne = (target, options) => relation('hasOne', target, options);
+/** The other model holds the foreign key, and there may be many rows. */
+export const hasMany = (target, options) => relation('hasMany', target, options);
+/**
+ * Both sides are linked through a join table, and the instance carries the verbs that
+ * write to it: `user.roles.attach(id)` (SPEC.md §24).
+ */
+export const belongsToMany = (target, options) => relation('belongsToMany', target, options);
+export const isRelation = (value) => typeof value === 'object' && value !== null && value.node === 'relation';
+//# sourceMappingURL=relations.js.map

package/dist/relations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.js","sourceRoot":"","sources":["../src/relations.ts"],"names":[],"mappings":"AAwDA,MAAM,cAAc,GAAG,CAAC,MAAsB,EAAgB,EAAE;IAC9D,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CAAC,kEAAkE,CAAC,CAAA;IACzF,CAAC;IAED,MAAM,QAAQ,GAAI,MAAwB,EAAE,CAAA;IAE5C,IACE,OAAO,QAAQ,KAAK,QAAQ;QAC5B,QAAQ,KAAK,IAAI;QACjB,OAAQ,QAAyB,CAAC,KAAK,KAAK,QAAQ,EACpD,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,kEAAkE,CAAC,CAAA;IACzF,CAAC;IAED,OAAO,QAAwB,CAAA;AACjC,CAAC,CAAA;AAED,MAAM,QAAQ,GAAG,CACf,IAAO,EACP,MAAsB,EACtB,OAAO,GAAoB,EAAE,EAChB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;AAEhG,wCAAwC;AACxC,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,MAAsB,EACtB,OAAyB,EACF,EAAE,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;AAElE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAsB,EAAE,OAAyB,EAAsB,EAAE,CAC9F,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;AAErC,yEAAyE;AACzE,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,MAAsB,EAAE,OAAyB,EAAuB,EAAE,CAChG,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;AAEtC;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,MAAsB,EACtB,OAAyB,EACE,EAAE,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;AAE1E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAc,EAAqB,EAAE,CAC9D,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAA2B,CAAC,IAAI,KAAK,UAAU,CAAA"}

package/dist/runtime.d.ts

@@ -0,0 +1,28 @@
+import { type TransactionPort } from '@assemora/core';
+import type { DatabaseAdapter, DatabaseContext, QueryAst } from '@assemora/database';
+/** Binds the adapter every model will use. Called once, when the application boots. */
+export declare const useAdapter: (adapter: DatabaseAdapter) => void;
+export declare const clearAdapter: () => void;
+export declare const currentAdapter: () => DatabaseAdapter;
+/**
+ * Every statement the data layer runs (SPEC.md §88).
+ *
+ * The query builder, a model's `find()`, an instance's writes and the pivot verbs all
+ * reach the adapter through here rather than through `currentAdapter().execute`, so
+ * there is one place that knows how long a query took — and one place that would have
+ * to be edited again for anything else the data layer ever wants to measure.
+ *
+ * A function, and deliberately not a wrapped adapter. `currentAdapter()` hands the
+ * real adapter to the CLI and to `applySchema()`, which reach for methods only the
+ * PostgreSQL one has; a wrapper would either lose them, taking `db:migrate` with them,
+ * or forward them, and be a second definition of a contract that already has one
+ * (SPEC.md §31, ADR-0013).
+ */
+export declare const execute: <T>(query: QueryAst, context: DatabaseContext) => Promise<T>;
+/**
+ * Runs an operation inside a transaction. Everything the operation awaits sees the
+ * transactional adapter without being told about it.
+ */
+export declare const transaction: <T>(operation: () => Promise<T>) => Promise<T>;
+export declare const dataTransactions: () => TransactionPort;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAUA,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAQpF,uFAAuF;AACvF,eAAO,MAAM,UAAU,YAAa,eAAe,KAAG,IAErD,CAAA;AAED,eAAO,MAAM,YAAY,QAAO,IAE/B,CAAA;AAED,eAAO,MAAM,cAAc,QAAO,eAUjC,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,OAAO,GAAU,CAAC,SAAS,QAAQ,WAAW,eAAe,KAAG,OAAO,CAAC,CAAC,CAiBrF,CAAA;AAyBD;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,aAAa,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAkBrE,CAAA;AAwDD,eAAO,MAAM,gBAAgB,QAAO,eAIlC,CAAA"}

package/dist/runtime.js

@@ -0,0 +1,149 @@
+/**
+ * Where the data layer finds its adapter, and how it reaches it (SPEC.md §33, §88).
+ *
+ * The current adapter and the current transaction travel through AsyncLocalStorage,
+ * so a developer never passes `tx` by hand. `execute()` below is the one seam every
+ * query in this package runs through, which is what makes a query measurable without
+ * anything having to wrap the adapter itself.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ConfigurationError } from '@assemora/core';
+import { recordQuery } from './slow-queries.js';
+let ambient;
+const scoped = new AsyncLocalStorage();
+/** Binds the adapter every model will use. Called once, when the application boots. */
+export const useAdapter = (adapter) => {
+    ambient = adapter;
+};
+export const clearAdapter = () => {
+    ambient = undefined;
+};
+export const currentAdapter = () => {
+    const adapter = scoped.getStore() ?? ambient;
+    if (adapter === undefined) {
+        throw new ConfigurationError('No database adapter is registered. Call useAdapter() before querying.');
+    }
+    return adapter;
+};
+/**
+ * Every statement the data layer runs (SPEC.md §88).
+ *
+ * The query builder, a model's `find()`, an instance's writes and the pivot verbs all
+ * reach the adapter through here rather than through `currentAdapter().execute`, so
+ * there is one place that knows how long a query took — and one place that would have
+ * to be edited again for anything else the data layer ever wants to measure.
+ *
+ * A function, and deliberately not a wrapped adapter. `currentAdapter()` hands the
+ * real adapter to the CLI and to `applySchema()`, which reach for methods only the
+ * PostgreSQL one has; a wrapper would either lose them, taking `db:migrate` with them,
+ * or forward them, and be a second definition of a contract that already has one
+ * (SPEC.md §31, ADR-0013).
+ */
+export const execute = async (query, context) => {
+    const startedAt = performance.now();
+    try {
+        const answer = await currentAdapter().execute(query, context);
+        recordQuery(query, performance.now() - startedAt, answer);
+        return answer;
+    }
+    catch (error) {
+        // Timed either way. A query that ran for four seconds and then failed is the one
+        // most worth knowing about, and a log that goes quiet exactly when the database
+        // starts refusing is the wrong log.
+        recordQuery(query, performance.now() - startedAt);
+        throw error;
+    }
+};
+/**
+ * Work waiting for the OUTERMOST transaction to commit (ADR-0023).
+ *
+ * The store is the list itself, and a nested `transaction()` never replaces it — so
+ * every layer inside registers against the one commit that actually makes rows
+ * durable. A savepoint is not that commit: everything written under it is still the
+ * caller's to undo.
+ */
+const waiting = new AsyncLocalStorage();
+const drain = async (work) => {
+    for (const item of work) {
+        try {
+            await item();
+        }
+        catch {
+            // Swallowed on purpose, and documented on `TransactionPort.afterCommit`: this
+            // runs after the commit, so there is no caller left to reject to, and one
+            // registration's failure must not cancel the next one's. Whoever registers
+            // reports its own failure — the command bus logs the job it could not queue.
+        }
+    }
+};
+/**
+ * Runs an operation inside a transaction. Everything the operation awaits sees the
+ * transactional adapter without being told about it.
+ */
+export const transaction = (operation) => {
+    const adapter = currentAdapter();
+    const run = () => adapter.transaction(() => scoped.run(adapter, operation));
+    // Nested: the caller owns the commit, so anything registered inside keeps waiting
+    // for theirs.
+    if (waiting.getStore() !== undefined)
+        return run();
+    const work = [];
+    // `.then` is attached outside `waiting.run`, so the work drains with no transaction
+    // in scope — a job dispatched by after-commit work has nothing left to wait for,
+    // and would otherwise be appended to a list that is already being read.
+    return waiting.run(work, run).then(async (value) => {
+        await drain(work);
+        return value;
+    });
+};
+/**
+ * Holds `work` until the outermost transaction commits, and drops it if that
+ * transaction is undone. With none open, "after commit" is "now".
+ */
+const afterCommit = (work) => {
+    const pending = waiting.getStore();
+    if (pending === undefined)
+        return work();
+    pending.push(work);
+    return Promise.resolve();
+};
+/**
+ * The transaction stage of the command pipeline (SPEC.md §14, ADR-0008).
+ *
+ * `core` declares the port and cannot reach a database; this is the implementation
+ * the data layer registers, so a handler that writes several rows either commits all
+ * of them or none.
+ */
+/** Nothing else can be thrown by accident, so nothing else can be mistaken for it. */
+const ROLLBACK = Symbol('assemora.rollback');
+/**
+ * Runs the operation inside a transaction that is always undone, and still answers
+ * with what it returned (SPEC.md §73).
+ *
+ * Rejecting is the only way to make an adapter roll back — that is how both of them
+ * implement it — so the value is carried out past the rejection rather than through
+ * it. A real failure inside the operation is rethrown untouched.
+ */
+const rollingBack = async (operation) => {
+    const carried = [];
+    try {
+        await transaction(async () => {
+            carried.push(await operation());
+            throw ROLLBACK;
+        });
+    }
+    catch (error) {
+        if (error !== ROLLBACK)
+            throw error;
+    }
+    const [value] = carried;
+    if (carried.length === 0) {
+        throw new ConfigurationError('The transaction was undone before the operation answered');
+    }
+    return value;
+};
+export const dataTransactions = () => ({
+    run: (operation, options) => options?.rollback === true ? rollingBack(operation) : transaction(operation),
+    afterCommit,
+});
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}