@stratal/framework 0.0.0-canary-ccb3f17 → 0.0.0-canary-e5681b8

package/dist/database/index.mjs

@@ -1,7 +1,7 @@
-import { t as __decorate } from "../decorate-ZDdbRmsv.mjs";
-import { DI_TOKENS, Transient, inject, lazy } from "stratal/di";
+import { t as __decorate } from "../decorate-RQD1h28J.mjs";
+import { DI_TOKENS, Request, inject, lazy } from "stratal/di";
 import { Module } from "stratal/module";
-import { DatabaseError, HttpException } from "stratal/errors";
+import { ApplicationError, DatabaseError, HttpException } from "stratal/errors";
 import { I18nModule } from "stratal/i18n";
 import { Command } from "stratal/quarry";
 import { ORMError, ORMErrorReason, ZenStackClient } from "@zenstackhq/orm";
@@ -124,6 +124,259 @@ var MigrateStatusCommand = class extends ZenStackCommand {
 	}
 };
 //#endregion
+//#region src/database/errors/cursor-model-unavailable.error.ts
+/**
+* Raised when `db.$cursor.<model>` cannot reach a model delegate on the client
+* it was built for — the schema declares the model, the client does not answer
+* for it.
+*
+* This is a **programming error**, not bad input: the reader is built from the
+* schema's own model list, so reaching it means the client and the schema it was
+* given have come apart — a model sliced out of the client's options, or a
+* hand-assembled client. No request recovers from it and no retry helps. It
+* deliberately carries no HTTP status, so it is never mistaken for something the
+* client sent wrong.
+*
+* `model` names the client key at fault, and is reported to observability so the
+* raise site stays distinguishable without matching on message text.
+*/
+var CursorModelUnavailableError = class extends ApplicationError {
+	model;
+	constructor(model) {
+		super(`[stratal:database] $cursor cannot reach the "${model}" model on this client. The schema declares it, so the client was built with a different schema or with this model sliced out.`);
+		this.model = model;
+	}
+	reportContext() {
+		return { model: this.model };
+	}
+};
+//#endregion
+//#region src/database/errors/cursor-ordering.error.ts
+/**
+* Raised when a `$cursor` read is asked for an ordering it cannot address a row
+* in: no `orderBy`, a clause with no `asc`/`desc` direction, an ordering
+* without the unique column that breaks ties, or an ordering column that is
+* absent from the returned row or null on it.
+*
+* This is a **programming error**, not bad input — no request can recover from
+* it and no retry helps, because the query as written cannot produce a stable
+* position. Handlers should let it surface as a `500` and report it; the fix is
+* always in the caller's `orderBy`, `uniqueBy` or `select`. It deliberately
+* carries no HTTP status, so it is never mistaken for something the client sent
+* wrong.
+*
+* `field` names the ordering column at fault where one is identifiable, and is
+* reported to observability so the raise sites stay distinguishable without
+* matching on message text.
+*/
+var CursorOrderingError = class extends ApplicationError {
+	field;
+	constructor(message, field) {
+		super(message);
+		this.field = field;
+	}
+	reportContext() {
+		return this.field === void 0 ? void 0 : { field: this.field };
+	}
+};
+//#endregion
+//#region src/database/errors/malformed-cursor.error.ts
+/**
+* Raised when a pagination cursor cannot be read: it is not the base64url
+* payload `$cursor` mints, or it decodes to something that is not a cursor.
+*
+* This is **bad input**, not a broken query. A cursor travels in a query string,
+* so a truncated link, a hand-edited URL, or one minted by an older build all
+* land here, and the request itself is still answerable. It carries its own
+* `400`, so a handler lets it surface rather than catching it to serve the
+* first page — the same refusal any other damaged parameter gets.
+*/
+var MalformedCursorError = class extends HttpException {
+	constructor(cause) {
+		super(400, "[stratal:database] Malformed pagination cursor.", cause);
+	}
+};
+//#endregion
+//#region src/database/pagination/cursor.ts
+const CURSOR_DIRECTION_KEY = "_next";
+/**
+* base64url, so a cursor survives a query string without escaping.
+*
+* The UTF-8 round trip is load-bearing, not ceremony: `btoa` accepts only
+* Latin-1, and `JSON.stringify` leaves non-ASCII characters as they are. An
+* ordering column is whatever the caller ordered by — a `title`, a `name`, a
+* `slug` — so one row whose value carries CJK, Cyrillic or an emoji would throw
+* `DOMException` while every ASCII row encoded fine. The first page would still
+* answer, because it mints no cursor; the 500 would land on the follow-up.
+*/
+function base64UrlEncode(input) {
+	const bytes = new TextEncoder().encode(input);
+	const binary = Array.from(bytes, (byte) => String.fromCharCode(byte)).join("");
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(input) {
+	const padded = input.replace(/-/g, "+").replace(/_/g, "/");
+	const binary = atob(padded.padEnd(padded.length + (4 - padded.length % 4) % 4, "="));
+	return new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+}
+/**
+* Encodes the ordering values of a row plus the direction it points.
+*
+* The whole ordering tuple travels, not a row id, so the cursor still resolves
+* after the row it was built from is deleted — which is the case cursors are
+* for. The direction rides along because a caller sends every cursor under one
+* query parameter name and nothing else distinguishes forward from backward.
+*/
+function encodeCursor(values, direction) {
+	return base64UrlEncode(JSON.stringify({
+		...values,
+		[CURSOR_DIRECTION_KEY]: direction === "next"
+	}));
+}
+/** Reads a cursor minted by {@link encodeCursor}. Throws on anything else. */
+function decodeCursor(cursor) {
+	let parsed;
+	try {
+		parsed = JSON.parse(base64UrlDecode(cursor));
+	} catch (cause) {
+		throw new MalformedCursorError(cause);
+	}
+	if (typeof parsed !== "object" || parsed === null || !(CURSOR_DIRECTION_KEY in parsed)) throw new MalformedCursorError();
+	const { [CURSOR_DIRECTION_KEY]: pointsToNext, ...values } = parsed;
+	return {
+		values,
+		direction: pointsToNext ? "next" : "prev"
+	};
+}
+function normalizeOrderBy(orderBy) {
+	return (Array.isArray(orderBy) ? orderBy : [orderBy]).flatMap((clause) => Object.entries(clause)).map(([field, direction]) => {
+		if (direction !== "asc" && direction !== "desc") throw new CursorOrderingError(`[stratal:database] $cursor needs a direction for "${field}"; got ${JSON.stringify(direction)}.`, field);
+		return [field, direction];
+	});
+}
+/**
+* Builds the keyset condition for "the rows after (or before) this position".
+*
+* For `updatedAt desc, id desc` this is
+* `updatedAt < :updatedAt OR (updatedAt = :updatedAt AND id < :id)` — one
+* disjunct per ordering column, each pinning the columns to its left to
+* equality. Reading backwards flips every comparison.
+*/
+function buildKeysetCondition(order, values, direction) {
+	const disjuncts = [];
+	for (let i = 0; i < order.length; i++) {
+		const conjunct = {};
+		for (let j = 0; j < i; j++) {
+			const [field] = order[j];
+			conjunct[field] = values[field];
+		}
+		const [field, sort] = order[i];
+		conjunct[field] = { [sort === "desc" === (direction === "next") ? "lt" : "gt"]: values[field] };
+		disjuncts.push(conjunct);
+	}
+	return { OR: disjuncts };
+}
+/** The ordering values of a row, which is what a cursor is made of. */
+function cursorValuesOf(row, order) {
+	const values = {};
+	for (const [field] of order) {
+		if (!(field in row)) throw new CursorOrderingError(`[stratal:database] Cannot build a cursor: the ordering column "${field}" is not on the returned row. Either it is not a field of this model, or a \`select\` dropped it.`, field);
+		const value = row[field];
+		if (value === null || value === void 0) throw new CursorOrderingError(`[stratal:database] Cannot build a cursor: the ordering column "${field}" is null. \$cursor cannot order on a nullable column — null has no position in an ordering.`, field);
+		values[field] = value;
+	}
+	return values;
+}
+/**
+* Reads one page of rows by cursor.
+*
+* Fetches one row more than asked for, which is how the next page is known to
+* exist without a `COUNT` — and a count is what a growing list cannot give a
+* stable answer to anyway.
+*
+* @example
+* ```typescript
+* const page = await db.$cursor.$from(threadUnion, {
+*   cursor: ctx.query('cursor'),
+*   take: 20,
+*   orderBy: [{ updatedAt: 'desc' }, { id: 'desc' }],
+*   where: { boardId },
+* })
+* ```
+*/
+async function readCursorPage(delegate, args) {
+	const order = normalizeOrderBy(args.orderBy);
+	if (order.length === 0) throw new CursorOrderingError("[stratal:database] $cursor requires `orderBy`. A cursor addresses a row's position in an ordering, so there is no position to address without one.");
+	const uniqueBy = args.uniqueBy ?? "id";
+	if (!order.some(([field]) => field === uniqueBy)) throw new CursorOrderingError(`[stratal:database] $cursor requires the ordering to include the unique column "${uniqueBy}", otherwise tied rows share a position and paging over them skips or repeats. Add it last — e.g. \`orderBy: [{ ${order[0][0]}: '${order[0][1]}' }, { ${uniqueBy}: '${order[0][1]}' }]\` — or name a different unique column with \`uniqueBy\`.`);
+	const decoded = args.cursor ? decodeCursor(args.cursor) : null;
+	const readingBackwards = decoded?.direction === "prev";
+	const queryOrder = readingBackwards ? order.map(([field, sort]) => [field, sort === "asc" ? "desc" : "asc"]) : order;
+	const conditions = [];
+	if (args.where) conditions.push(args.where);
+	if (decoded) conditions.push(buildKeysetCondition(order, decoded.values, decoded.direction));
+	const query = {
+		...conditions.length > 0 ? { where: conditions.length === 1 ? conditions[0] : { AND: conditions } } : {},
+		orderBy: queryOrder.map(([field, sort]) => ({ [field]: sort })),
+		take: args.take + 1,
+		...args.include ? { include: args.include } : {},
+		...args.select ? { select: args.select } : {},
+		...args.omit ? { omit: args.omit } : {}
+	};
+	const rows = await delegate.findMany(query);
+	const hasExtraRow = rows.length > args.take;
+	const page = hasExtraRow ? rows.slice(0, args.take) : rows;
+	const data = readingBackwards ? [...page].reverse() : page;
+	const first = data[0];
+	const last = data[data.length - 1];
+	const nextCursor = last === void 0 ? null : readingBackwards ? encodeCursor(cursorValuesOf(last, order), "next") : hasExtraRow ? encodeCursor(cursorValuesOf(last, order), "next") : null;
+	const prevCursor = first === void 0 ? null : readingBackwards ? hasExtraRow ? encodeCursor(cursorValuesOf(first, order), "prev") : null : decoded ? encodeCursor(cursorValuesOf(first, order), "prev") : null;
+	return {
+		data,
+		perPage: args.take,
+		cursorName: args.cursorName ?? "cursor",
+		cursor: args.cursor ?? null,
+		nextCursor,
+		prevCursor
+	};
+}
+//#endregion
+//#region src/database/pagination/cursor-reader.ts
+/**
+* Builds the reader eagerly, one entry per model the schema declares.
+*
+* A plain object rather than a `Proxy`: the model list is known here, and a
+* proxy would answer every property — `then`, `constructor`, an inspector's
+* probe — with something that looks like a reader.
+*
+* The delegate is resolved per call, not captured: ZenStack builds a fresh CRUD
+* handler on each model access, and holding one would pin it for the life of
+* the client.
+*/
+function createCursorReader(client, schema) {
+	const source = client;
+	const modelEntries = Object.keys(schema.models ?? {}).map((model) => {
+		const key = model.charAt(0).toLowerCase() + model.slice(1);
+		return [key, { findMany: (args) => {
+			const delegate = source[key];
+			if (!delegate) throw new CursorModelUnavailableError(key);
+			const { cursor, take, orderBy, uniqueBy, cursorName, where, include, select, omit } = args;
+			return readCursorPage(delegate, {
+				cursor,
+				take,
+				orderBy,
+				uniqueBy,
+				cursorName,
+				where,
+				include,
+				select,
+				omit
+			});
+		} }];
+	});
+	return Object.assign(Object.fromEntries(modelEntries), { $from: (delegate, args) => readCursorPage(delegate, args) });
+}
+//#endregion
 //#region src/database/errors/record-not-found.error.ts
 var RecordNotFoundError = class extends HttpException {
 	details;
@@ -352,6 +605,23 @@ object({
 	return new Set(names).size === names.length;
 }, withZodI18n("database.duplicateConnections")), refine((config) => config.connections.some((c) => c.name === config.default), withZodI18n("database.defaultConnectionNotFound")));
 /**
+* Puts `$cursor` on a client, base or transaction.
+*
+* Defined on the client rather than contributed as a ZenStack plugin because
+* the client proxy hands a plugin's member back unbound, and this one has to
+* reach the client's own model delegates. Non-enumerable so it stays out of
+* enumeration of the client, and skipped when already present — a reentrant
+* `$transaction` hands back a client that has been through here.
+*/
+function defineCursorReader(client, schema) {
+	if ("$cursor" in client) return;
+	Object.defineProperty(client, "$cursor", {
+		value: createCursorReader(client, schema),
+		enumerable: false,
+		configurable: true
+	});
+}
+/**
 * Wrap a ZenStack client so `$transaction` is reentrant: when a transaction is
 * already open on this connection (tracked per-connection via
 * {@link AsyncLocalStorage}), nested calls run within the active transaction's
@@ -367,8 +637,13 @@ object({
 *
 * ZenStackClient's constructor returns a Proxy (for dynamic model accessors), so
 * a subclass method override is shadowed — hence the proxy wrapper here.
+*
+* `prepareTransactionClient` runs against every transaction client before the
+* callback sees it, which is how the built-in members reach it. ZenStack builds
+* that client itself and types it with its own contract, so there is no other
+* point at which it passes through this package.
 */
-function makeReentrantTransaction(client, activeTransaction) {
+function makeReentrantTransaction(client, activeTransaction, prepareTransactionClient) {
 	return new Proxy(client, { get(target, prop, receiver) {
 		if (prop === Symbol.asyncDispose) return () => target.$disconnect();
 		if (prop !== "$transaction") return Reflect.get(target, prop, receiver);
@@ -377,7 +652,10 @@ function makeReentrantTransaction(client, activeTransaction) {
 			const active = activeTransaction.getStore();
 			if (active) return typeof input === "function" ? input(active) : active.$transaction(input, options);
 			if (typeof input !== "function") return transaction.call(target, input, options);
-			return transaction.call(target, (tx) => activeTransaction.run(tx, () => input(tx)), options);
+			return transaction.call(target, (tx) => {
+				prepareTransactionClient?.(tx);
+				return activeTransaction.run(tx, () => input(tx));
+			}, options);
 		};
 	} });
 }
@@ -397,7 +675,8 @@ function createDatabaseService(conn, eventRegistry) {
 				plugins,
 				computedFields: conn.computedFields
 			});
-			const client = makeReentrantTransaction(this, activeTransaction);
+			defineCursorReader(this, conn.schema);
+			const client = makeReentrantTransaction(this, activeTransaction, (tx) => defineCursorReader(tx, conn.schema));
 			for (const ref of instances) if (ref.deref() === void 0) instances.delete(ref);
 			instances.add(new WeakRef(client));
 			return client;
@@ -416,7 +695,7 @@ function createDatabaseService(conn, eventRegistry) {
 			}));
 		}
 	};
-	DatabaseClient = __decorate([Transient()], DatabaseClient);
+	DatabaseClient = __decorate([Request()], DatabaseClient);
 	return DatabaseClient;
 }
 //#endregion
@@ -462,7 +741,7 @@ let DatabaseModule = _DatabaseModule = class DatabaseModule {
 		};
 	}
 	async onInitialize(context) {
-		const config = context.container.resolve(DATABASE_TOKENS.Options);
+		const config = await context.container.resolve(DATABASE_TOKENS.Options);
 		const eventRegistry = (await context.container.resolve(DI_TOKENS.LazyModuleLoader).load(() => import("stratal/events").then((m) => m.EventsModule))).get(DI_TOKENS.EventRegistry);
 		for (const conn of config.connections) {
 			const Service = createDatabaseService(conn, eventRegistry);
@@ -583,6 +862,6 @@ function InjectDB(name) {
 	return inject(connectionSymbol(name));
 }
 //#endregion
-export { DATABASE_TOKENS, DB_SHARED_POOL_ENV, DatabaseModule, DbGenerateCommand, DbPullCommand, DbPushCommand, ErrorHandlerPlugin, EventEmitterPlugin, InjectDB, MigrateDeployCommand, MigrateDevCommand, MigrateResetCommand, MigrateStatusCommand, RecordNotFoundError, SchemaSwitcher, UniqueConstraintError, ZenStackCommand, connectionSymbol, createPoolFactory, databaseMessages, fromZenStackError };
+export { CursorModelUnavailableError, CursorOrderingError, DATABASE_TOKENS, DB_SHARED_POOL_ENV, DatabaseModule, DbGenerateCommand, DbPullCommand, DbPushCommand, ErrorHandlerPlugin, EventEmitterPlugin, InjectDB, MalformedCursorError, MigrateDeployCommand, MigrateDevCommand, MigrateResetCommand, MigrateStatusCommand, RecordNotFoundError, SchemaSwitcher, UniqueConstraintError, ZenStackCommand, connectionSymbol, createCursorReader, createPoolFactory, databaseMessages, decodeCursor, encodeCursor, fromZenStackError };
 
 //# sourceMappingURL=index.mjs.map