@stratal/framework 0.0.26 → 0.1.0

package/dist/index-e_u1SRyd.d.mts

@@ -0,0 +1,921 @@
+import { a as InferAnySchema, n as DeclaredMembers, o as InferConnectionExtensions, r as DefaultConnectionName, s as InferConnectionSchema, t as ConnectionName } from "./types-B35g-lXi.mjs";
+import { AsyncModuleOptions, DynamicModule, ModuleContext, OnInitialize, OnShutdown } from "stratal/module";
+import { ApplicationError, HttpException } from "stratal/errors";
+import { Command } from "stratal/quarry";
+import { AggregateArgs, AllCrudOperations, AnyPlugin, ClientContract, ClientOptions, ComputedFieldsOptions, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, EntityMutationHooksDef, FindFirstArgs, FindManyArgs, FindUniqueArgs, GroupByArgs, ModelResult, QueryOptions, RuntimePlugin, SelectSubset, SimplifiedPlainResult, TransactionClientContract, TransactionIsolationLevel, UpdateArgs, UpdateManyArgs, UpsertArgs } from "@zenstackhq/orm";
+import { SchemaDef } from "@zenstackhq/schema";
+import { GetModels, SchemaDef as SchemaDef$1 } from "@zenstackhq/orm/schema";
+import { IEventRegistry } from "stratal/events";
+//#region src/database/database.module.d.ts
+interface DatabaseConnectionConfig<Schema extends SchemaDef = SchemaDef, Name extends ConnectionName = ConnectionName> {
+  name: Name;
+  schema: Schema;
+  dialect: () => ClientOptions<SchemaDef>['dialect'];
+  plugins?: AnyPlugin[];
+  /**
+   * Schema-level @computed field implementations. Required when the schema
+   * declares any `@computed` fields. Keyed by uncapitalized model name; values
+   * map field name to a Kysely-expression compute callback.
+   */
+  computedFields?: ComputedFieldsOptions<Schema>;
+}
+interface DatabaseModuleConfig {
+  default: DefaultConnectionName;
+  connections: DatabaseConnectionConfig[];
+}
+declare class DatabaseModule implements OnInitialize, OnShutdown {
+  private readonly services;
+  static forRoot(config: DatabaseModuleConfig): DynamicModule;
+  static forRootAsync(options: AsyncModuleOptions<DatabaseModuleConfig>): DynamicModule;
+  onInitialize(context: ModuleContext): Promise<void>;
+  onShutdown(context: ModuleContext): Promise<void>;
+}
+//#endregion
+//#region src/database/pagination/cursor.d.ts
+/**
+ * Reading rows from a position in an ordering.
+ *
+ * A primitive on its own terms, not a variant of anything: it answers "the N
+ * rows after this row", and that is the whole contract. There are no page
+ * numbers, no total, and no last page, because a cursor names a row rather than
+ * an offset into a result set. It requires an ordering — a total one — which is
+ * the price of addressing a row at all.
+ *
+ * What that buys: rows inserted or deleted around the reader do not move the
+ * position. `LIMIT/OFFSET` addresses a place in a result set, so a row added
+ * above the window shifts everything under it and the reader silently skips one
+ * or sees one twice. Nothing here shifts.
+ *
+ * Knows nothing of HTTP or Inertia. A route can return the result as JSON, a
+ * client can walk it, and `ctx.scroll()` can read it — none of which this file
+ * is aware of.
+ */
+/** Sort direction for one ordering column. */
+type CursorSortOrder = 'asc' | 'desc';
+/**
+ * One ordering column. Several are combined left to right, as in SQL.
+ *
+ * Values may be `undefined` so an array of clause literals keeps its ordinary
+ * inferred type — TypeScript widens `[{ updatedAt: 'desc' }, { id: 'desc' }]`
+ * to a union whose members carry the other's key as `undefined`. A direction
+ * that really is `undefined` at runtime still raises `CursorOrderingError`.
+ */
+type CursorOrderBy = Record<string, CursorSortOrder | undefined>;
+interface CursorPageArgs {
+  /**
+   * The cursor to read from, or `null` to start at the beginning of the
+   * ordering. Opaque: it is minted by a previous result and passed back
+   * verbatim. Never construct one.
+   */
+  cursor?: string | null;
+  /** Rows per page. The last page may hold fewer. */
+  take: number;
+  /**
+   * Ordering, applied left to right. Required — a cursor addresses a row's
+   * position in an ordering, so without one there is no position to address.
+   * The set must include {@link CursorPageArgs.uniqueBy}.
+   */
+  orderBy: CursorOrderBy | CursorOrderBy[];
+  /**
+   * The ordering column that makes the ordering total. Defaults to `id`.
+   *
+   * Ordering on a non-unique column alone leaves ties, and a cursor cannot
+   * address a position inside a tie — which reintroduces exactly the skipping
+   * that cursors exist to prevent. `updatedAt desc` needs an `id desc` after it.
+   */
+  uniqueBy?: string;
+  /** Filter, combined with the cursor's own condition. */
+  where?: Record<string, unknown>;
+  /**
+   * Relations to load, field selection, and fields to drop — handed to the
+   * delegate untouched. `select` and `omit` must not drop an ordering column,
+   * because the cursor is built from those.
+   *
+   * Deliberately not mutually exclusive here, unlike on `db.$cursor`, because
+   * the delegate decides what they mean: a model delegate already refuses the
+   * combination itself (`"select" and "omit" cannot be used together`), and a
+   * hand-written one owns its `findMany` and may honour any combination.
+   */
+  include?: Record<string, unknown>;
+  select?: Record<string, unknown>;
+  omit?: Record<string, unknown>;
+  /** Query parameter name a caller should send the cursor under. Defaults to `cursor`. */
+  cursorName?: string;
+}
+/**
+ * One page of rows read by cursor.
+ *
+ * Carries no `path` or page URLs, unlike Laravel's `CursorPaginator`. Building
+ * a URL is a routing decision — which route, which of the current query
+ * parameters to keep, whether a trailing slash is canonical — and a paginator
+ * holds none of that. A route that wants links builds them from its own route
+ * helper plus `nextCursor` / `prevCursor`.
+ */
+interface CursorPageResult<TRow> {
+  /** The rows for this page, in display order. */
+  data: TRow[];
+  /** Rows requested per page. The last page may hold fewer. */
+  perPage: number;
+  /** Query parameter name the cursor travels under. */
+  cursorName: string;
+  /**
+   * The cursor this page was read from, or `null` on the first page.
+   *
+   * Laravel's `CursorPaginator::toArray()` omits both this and the cursor name
+   * because it recovers them from the request. A result object has no request,
+   * so it carries them.
+   */
+  cursor: string | null;
+  /** Cursor for the following page, or `null` when this is the last. */
+  nextCursor: string | null;
+  /** Cursor for the preceding page, or `null` when this is the first. */
+  prevCursor: string | null;
+}
+/** Whether a cursor points forward (the next rows) or backward (the previous ones). */
+type CursorDirection = 'next' | 'prev';
+interface DecodedCursor {
+  /** The ordering column values of the row the cursor addresses. */
+  values: Record<string, unknown>;
+  direction: CursorDirection;
+}
+/**
+ * The query {@link readCursorPage} builds — the single declaration of it, used
+ * both as the delegate's parameter type and as the type of the object handed to
+ * `findMany`.
+ *
+ * Every key here must also be a key of a ZenStack `findMany` arg, because that
+ * is what makes a model delegate satisfy {@link CursorPageDelegate}: ZenStack
+ * types `findMany` as `<T extends FindManyArgs>(args?: SelectSubset<T, …>)`,
+ * and `SelectSubset` maps each key of `T` to `never` unless the model's own
+ * args declare it. A widened stand-in — `Record<string, unknown>` — infers `T`
+ * to itself, collapses the whole parameter to `{ [x: string]: never }`, and no
+ * delegate can satisfy it in either direction.
+ */
+interface CursorFindManyArgs {
+  where?: Record<string, unknown>;
+  orderBy?: CursorOrderBy[];
+  take?: number;
+  include?: Record<string, unknown>;
+  select?: Record<string, unknown>;
+  omit?: Record<string, unknown>;
+}
+/**
+ * The minimum a model delegate has to offer.
+ *
+ * A ZenStack model delegate satisfies this structurally — `db.thread` is passed
+ * as-is — and so does a hand-written `findMany`, which is how a query the ORM
+ * cannot express (a `UNION`, a raw statement) is paged by the same primitive.
+ */
+interface CursorPageDelegate<TRow> {
+  findMany(args: CursorFindManyArgs): PromiseLike<TRow[]>;
+}
+/**
+ * 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.
+ */
+declare function encodeCursor(values: Record<string, unknown>, direction: CursorDirection): string;
+/** Reads a cursor minted by {@link encodeCursor}. Throws on anything else. */
+declare function decodeCursor(cursor: string): DecodedCursor;
+//#endregion
+//#region src/database/pagination/cursor-reader.d.ts
+/**
+ * Per-model cursor reading: `db.$cursor.thread.findMany({ … })`.
+ *
+ * A namespace of its own rather than an argument on the model's own `findMany`,
+ * because ZenStack already has a `cursor` there and it means something else. Its
+ * `cursor` takes a `WhereUniqueInput` and resolves the row's ordering values by
+ * subquery at query time, so the row must still exist, still pass the query's
+ * own `where`, and still hold the ordering values it held when the cursor was
+ * minted. Two arguments spelled `cursor` on one call, one of which answers an
+ * empty page when its row is deleted, is not a distinction a caller should have
+ * to hold. In here there is exactly one: {@link CursorReaderArgs} omits
+ * ZenStack's `cursor` and the `skip` that goes with it.
+ */
+/**
+ * The query-relevant options the result and argument types read.
+ *
+ * `QueryOptions` is what ZenStack's own `SimplifiedPlainResult` and `FindManyArgs` default this
+ * slot to. Narrowing `ClientOptions` to the keys they share yields that same type, but reaches
+ * it through `keyof ClientOptions`, which instantiates the client-only `computedFields` map
+ * across every model and field in the schema for a result that never reads it.
+ */
+type Options<Schema extends SchemaDef$1> = QueryOptions<Schema>;
+/** The client keys that address a model — `Post` in the schema is `post` here. */
+type CursorModelKey<Schema extends SchemaDef$1> = Uncapitalize<GetModels<Schema>>;
+/** The schema model a client key addresses. */
+type ModelOf<Schema extends SchemaDef$1, Key extends CursorModelKey<Schema>> = Extract<GetModels<Schema>, { [M in GetModels<Schema>]: Uncapitalize<M> extends Key ? M : never; }[GetModels<Schema>]>;
+/** One row of a model, before `select`/`include` narrow it. */
+type PlainRow<Schema extends SchemaDef$1, Key extends CursorModelKey<Schema>> = SimplifiedPlainResult<Schema, ModelOf<Schema, Key>, {}, Options<Schema>>;
+/**
+ * The ordering, restricted to the model's own scalar columns.
+ *
+ * Narrower than ZenStack's `orderBy` on purpose: a cursor is built from the
+ * ordering values of a row, so an ordering that reaches through a relation or
+ * sorts on a computed relevance score has no value to carry. Those are
+ * unrepresentable here rather than accepted and failed on at runtime.
+ */
+type CursorOrderByOf<Schema extends SchemaDef$1, Key extends CursorModelKey<Schema>> = Partial<Record<keyof PlainRow<Schema, Key> & string, CursorSortOrder>>;
+/**
+ * A model's `findMany` arguments, with cursor paging in place of offset paging.
+ *
+ * `skip` goes with ZenStack's `cursor` and addresses a place in a result set,
+ * which is the thing a cursor exists not to do. `distinct` changes which row
+ * represents a group, so no row has a stable position to address.
+ *
+ * Dropping an argument here only stops it being declared; what refuses it at a
+ * call site is {@link CursorModelReader.findMany} passing this through
+ * ZenStack's `SelectSubset`.
+ */
+type CursorReaderArgs<Schema extends SchemaDef$1, Key extends CursorModelKey<Schema>> = Omit<FindManyArgs<Schema, ModelOf<Schema, Key>, Options<Schema>>, 'cursor' | 'skip' | 'take' | 'orderBy' | 'distinct'> & {
+  /**
+   * The cursor to read from, or `null`/absent to start at the beginning of
+   * the ordering. Opaque: it is minted by a previous result and passed back
+   * verbatim. Never construct one.
+   */
+  cursor?: string | null;
+  /** Rows per page. The last page may hold fewer. */
+  take: number;
+  /**
+   * Ordering, applied left to right. Required, and must end in a unique
+   * column — a cursor addresses a row's position in an ordering, and a
+   * position inside a tie cannot be addressed.
+   */
+  orderBy: CursorOrderByOf<Schema, Key> | CursorOrderByOf<Schema, Key>[];
+  /** The ordering column that makes the ordering total. Defaults to `id`. */
+  uniqueBy?: keyof PlainRow<Schema, Key> & string;
+  /** Query parameter name a caller should send the cursor under. Defaults to `cursor`. */
+  cursorName?: string;
+};
+/**
+ * One model's cursor reader.
+ *
+ * The argument goes through ZenStack's own `SelectSubset`, which is what a
+ * model's `findMany` uses and is the whole of the refusal machinery here. It
+ * maps any key the arguments do not declare to `never` — restoring the
+ * excess-property refusal a bare type parameter switches off, so `skip`,
+ * `distinct` and the native `cursor` are rejected — and it carries ZenStack's
+ * conditional messages for `select` with `include` and `select` with `omit`.
+ * Restating those exclusions by hand would answer the same mistake with a worse
+ * message; rebuilding the argument type without it drops them silently, which
+ * is what an earlier revision of this file did.
+ *
+ * `Args` is still inferred from the call, so `select` narrows the row type.
+ */
+interface CursorModelReader<Schema extends SchemaDef$1, Key extends CursorModelKey<Schema>> {
+  findMany<Args extends CursorReaderArgs<Schema, Key>>(args: SelectSubset<Args, CursorReaderArgs<Schema, Key>>): Promise<CursorPageResult<SimplifiedPlainResult<Schema, ModelOf<Schema, Key>, Args, Options<Schema>>>>;
+}
+/**
+ * Arguments for a page read from a caller-supplied `findMany`.
+ *
+ * The row type comes from the delegate — the framework has no schema for a
+ * `UNION` — and the ordering is keyed to it, so ordering on a column the query
+ * does not return is a compile error instead of the `CursorOrderingError` it
+ * would raise once the first row came back.
+ *
+ * No `select`, `include` or `omit`. They are ZenStack model arguments; a
+ * caller-written `findMany` decides for itself what to return, and the framework
+ * can neither type them against the row nor make the delegate honour them — an
+ * option that may be silently ignored is worse than one that is absent. A
+ * caller that wants fewer columns selects fewer inside its own `findMany`.
+ *
+ * `where` stays, and is not a passthrough: the paginator combines it with the
+ * keyset condition it builds, so it is how the page is positioned at all. It
+ * cannot be typed here because its shape is the delegate's own filter language.
+ */
+interface CursorSourceArgs<TRow> {
+  /**
+   * The cursor to read from, or `null`/absent to start at the beginning of the
+   * ordering. Opaque: it is minted by a previous result and passed back
+   * verbatim. Never construct one.
+   */
+  cursor?: string | null;
+  /** Rows per page. The last page may hold fewer. */
+  take: number;
+  /**
+   * Ordering, applied left to right. Required, and must end in a unique column
+   * — a cursor addresses a row's position in an ordering, and a position inside
+   * a tie cannot be addressed.
+   */
+  orderBy: CursorSourceOrderBy<TRow> | CursorSourceOrderBy<TRow>[];
+  /** The ordering column that makes the ordering total. Defaults to `id`. */
+  uniqueBy?: CursorSourceColumn<TRow>;
+  /** Filter, combined with the cursor's own condition and handed to the delegate. */
+  where?: Record<string, unknown>;
+  /** Query parameter name a caller should send the cursor under. Defaults to `cursor`. */
+  cursorName?: string;
+}
+/**
+ * A column of the delegate's row.
+ *
+ * `DeclaredMembers` strips the index signature that {@link CursorPageDelegate}'s
+ * row constraint obliges a caller to write (`interface Row extends
+ * Record<string, unknown>`). Without it `keyof` is `string` and every name
+ * typechecks, which is the whole of the guarantee here.
+ */
+type CursorSourceColumn<TRow> = keyof DeclaredMembers<TRow> & string;
+/** An ordering clause over the delegate's own columns. */
+type CursorSourceOrderBy<TRow> = Partial<Record<CursorSourceColumn<TRow>, CursorSortOrder>>;
+/**
+ * Reads a page from something that is not a model — a `UNION`, a raw statement —
+ * by supplying the `findMany` yourself.
+ *
+ * Sits beside the model keys rather than in a separate export because it is the
+ * same operation on a different source, and because a free function has no
+ * client to belong to: on a transaction client, `tx.$cursor.$from(…)` reads
+ * inside the transaction, which an imported function could not do.
+ *
+ * The `$` prefix is what keeps it from colliding with a model: a client key is
+ * an uncapitalized model name, and ZenStack reserves the prefix for members of
+ * the client itself.
+ */
+interface CursorSourceReader {
+  $from<TRow extends Record<string, unknown>>(delegate: CursorPageDelegate<TRow>, args: CursorSourceArgs<NoInfer<TRow>>): Promise<CursorPageResult<TRow>>;
+}
+/** `db.$cursor` — one reader per model in the schema, plus `$from` for anything else. */
+type CursorReader<Schema extends SchemaDef$1> = { [Key in CursorModelKey<Schema>]: CursorModelReader<Schema, Key>; } & CursorSourceReader;
+/** The client members {@link createCursorReader} contributes. */
+interface CursorClientMembers<Schema extends SchemaDef$1> {
+  /**
+   * Reads one page of a model's rows by cursor, for a list that changes while
+   * it is read.
+   *
+   * @example
+   * ```typescript
+   * const page = await db.$cursor.thread.findMany({
+   *   cursor: ctx.query('cursor'),
+   *   take: 20,
+   *   orderBy: [{ updatedAt: 'desc' }, { id: 'desc' }],
+   *   where: { boardId },
+   * })
+   * ```
+   */
+  $cursor: CursorReader<Schema>;
+}
+/**
+ * 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.
+ */
+declare function createCursorReader<Schema extends SchemaDef$1>(client: unknown, schema: Schema): CursorReader<Schema>;
+//#endregion
+//#region src/database/database.service.d.ts
+/**
+ * Client members every connection carries, because `createDatabaseService`
+ * defines them on every client it builds — the base client and the transaction
+ * client alike.
+ *
+ * Intersected onto the client from outside rather than passed as its
+ * `ExtClientMembers` argument: that slot is constrained to
+ * `Record<string, unknown>`, and the index signature it forces survives
+ * `$transaction`'s `Omit` and collapses every model delegate on a transaction
+ * client to `unknown`.
+ */
+type BuiltInClientMembers<K extends ConnectionName> = CursorClientMembers<InferConnectionSchema<K>>;
+/** The ZenStack client for a connection, before the built-in members are added. */
+type ConnectionClient<K extends ConnectionName> = ClientContract<InferConnectionSchema<K>, ClientOptions<InferConnectionSchema<K>>, InferConnectionExtensions<K>['extQueryArgs'], InferConnectionExtensions<K>['extClientMembers'], InferConnectionExtensions<K>['extResult']>;
+/** The client a `$transaction` callback receives, carrying the same built-in members. */
+type TransactionService<K extends ConnectionName = DefaultConnectionName> = TransactionClientContract<InferConnectionSchema<K>, ClientOptions<InferConnectionSchema<K>>, InferConnectionExtensions<K>['extQueryArgs'], InferConnectionExtensions<K>['extClientMembers'], InferConnectionExtensions<K>['extResult']> & BuiltInClientMembers<K>;
+/** `{ [I]: Awaited<P[I]> }`, matching what the sequential form of `$transaction` resolves to. */
+type UnwrapPromises<P extends readonly unknown[]> = { [I in keyof P]: Awaited<P[I]>; };
+/**
+ * `$transaction`, restated so the interactive form hands back a client carrying
+ * the built-in members. ZenStack types its callback with its own
+ * `TransactionClientContract`, which knows nothing of them.
+ *
+ * Intersected ahead of the client rather than replacing its `$transaction`,
+ * because overload resolution across an intersection tries the constituents in
+ * order and these have to be reached first. `Omit`ing the original is not the
+ * alternative it looks like: with an unresolved `SchemaDef` the client's model
+ * delegates are an index signature, so `keyof` is `string`, `Omit` collapses
+ * every named member into it, and `$queryRawUnsafe` starts resolving to a model
+ * delegate.
+ *
+ * The sequential form is restated unchanged — it is only here because an
+ * overload set has to be declared together.
+ */
+interface TransactionWithBuiltIns<K extends ConnectionName> {
+  $transaction<T>(callback: (tx: TransactionService<K>) => Promise<T>, options?: {
+    isolationLevel?: TransactionIsolationLevel;
+  }): Promise<T>;
+  $transaction<P extends readonly PromiseLike<unknown>[]>(arg: [...P], options?: {
+    isolationLevel?: TransactionIsolationLevel;
+  }): Promise<UnwrapPromises<P>>;
+}
+/**
+ * DatabaseService type
+ *
+ * Each connection has its own schema and plugin extensions.
+ * Plugin extension types are automatically inferred from `StratalDatabase.plugins`.
+ *
+ * @example
+ * ```typescript
+ * // Typed to default connection (includes plugin extensions)
+ * constructor(@inject(DI_TOKENS.Database) private db: DatabaseService) {}
+ *
+ * // Typed to a specific named connection
+ * constructor(@InjectDB('analytics') private analytics: DatabaseService<'analytics'>) {}
+ * ```
+ */
+type DatabaseService<K extends ConnectionName = DefaultConnectionName> = TransactionWithBuiltIns<K> & ConnectionClient<K> & BuiltInClientMembers<K>;
+//#endregion
+//#region src/database/database.tokens.d.ts
+declare const DATABASE_TOKENS: {
+  readonly Options: symbol;
+  readonly Services: symbol;
+};
+declare function connectionSymbol(name: ConnectionName): symbol;
+//#endregion
+//#region src/database/pool.d.ts
+/**
+ * Env binding the framework reads to decide DB connection topology. Set by
+ * `@stratal/testing` (the test harness runs against a DIRECT Postgres with no
+ * Hyperdrive in front); never set in dev / staging / production.
+ */
+declare const DB_SHARED_POOL_ENV = "STRATAL_DB_SHARED_POOL";
+/**
+ * Build the lazy pool factory a consumer hands to its ZenStack dialect,
+ * choosing the connection topology from the environment instead of hard-coding
+ * one. The consumer writes `dialect: () => new PostgresDialect({ pool })` where
+ * `pool = createPoolFactory(env, () => new Pool(poolConfig))` — so the prod-vs-
+ * test decision lives here, in the framework, not as an `IS_TEST` branch in app
+ * config.
+ *
+ * - **Default (dev / staging / production):** returns a FRESH pool on every
+ *   call. The dialect is rebuilt per request resolution, so each request owns
+ *   its own pool/socket — mandatory on workerd, where a pool opened in one
+ *   request's I/O context cannot be reused by another (the cross-request I/O is
+ *   cancelled and the request hangs forever). Hyperdrive fronts these pools and
+ *   multiplexes the real server connections, so they never accumulate.
+ * - **Shared (`DB_SHARED_POOL_ENV === 'true'`):** memoizes ONE pool per
+ *   connection, reused across every resolution. `@stratal/testing` sets this
+ *   because the test harness hits a direct Postgres with no Hyperdrive — a fresh
+ *   pool per resolution would exhaust `max_connections` across parallel test
+ *   files. One shared pool per connection mirrors what Hyperdrive does in prod.
+ *
+ *   This single pool is forced **persistent** ({@link withPersistentConnection}):
+ *   its idle reaper is disabled regardless of the config `makePool` passed. A pool
+ *   reused for the whole worker run must never idle-close — a non-zero
+ *   `idleTimeoutMillis` reaps its connection between operations, and under real
+ *   network latency (a CI Postgres service, not a local socket) that eviction
+ *   races in-flight and subsequent queries → "Connection terminated unexpectedly",
+ *   cascading into half-applied writes and cross-test row leakage. It passes on a
+ *   fast local socket and only surfaces under latency, so consumers can't be
+ *   trusted to configure it right — the shared branch enforces it. The consumer's
+ *   own idle settings still apply to the fresh-per-resolution prod pools (below).
+ *
+ * Either way the pool is created LAZILY: `makePool` is invoked by Kysely on the
+ * first query, inside the request's I/O context — never at module-eval / global
+ * scope, which workerd forbids ("Disallowed operation within global scope").
+ */
+declare function createPoolFactory<TPool>(env: object, makePool: () => TPool): () => Promise<TPool>;
+//#endregion
+//#region src/database/decorators/inject-db.decorator.d.ts
+declare function InjectDB(name: ConnectionName): ParameterDecorator;
+//#endregion
+//#region src/database/errors/cursor-model-unavailable.error.d.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.
+ */
+declare class CursorModelUnavailableError extends ApplicationError {
+  readonly model: string;
+  constructor(model: string);
+  reportContext(): Record<string, unknown> | undefined;
+}
+//#endregion
+//#region src/database/errors/cursor-ordering.error.d.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.
+ */
+declare class CursorOrderingError extends ApplicationError {
+  readonly field?: string | undefined;
+  constructor(message: string, field?: string | undefined);
+  reportContext(): Record<string, unknown> | undefined;
+}
+//#endregion
+//#region src/database/errors/malformed-cursor.error.d.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.
+ */
+declare class MalformedCursorError extends HttpException {
+  constructor(cause?: unknown);
+}
+//#endregion
+//#region src/database/errors/record-not-found.error.d.ts
+declare class RecordNotFoundError extends HttpException {
+  readonly details?: string | undefined;
+  constructor(details?: string | undefined, cause?: unknown);
+}
+//#endregion
+//#region src/database/errors/unique-constraint.error.d.ts
+declare class UniqueConstraintError extends HttpException {
+  readonly fields?: string[] | undefined;
+  constructor(fields?: string[] | undefined, cause?: unknown);
+}
+//#endregion
+//#region src/database/errors/from-zenstack-error.d.ts
+declare function fromZenStackError(error: unknown): ApplicationError;
+//#endregion
+//#region src/database/event-types.d.ts
+/**
+ * Event phase: before or after operation
+ */
+type EventPhase = 'before' | 'after';
+/**
+ * All database operations that can trigger events
+ */
+type DatabaseOperation = AllCrudOperations;
+/**
+ * Distributive helper — extracts model names from each schema member individually.
+ * Using a naked type parameter ensures TypeScript distributes over unions:
+ * `_ExtractModelNames<A | B>` = `_ExtractModelNames<A> | _ExtractModelNames<B>`
+ */
+type _ExtractModelNames<S> = S extends {
+  models: infer M;
+} ? Extract<keyof M, string> : never;
+/**
+ * Model names derived from the shared database schema.
+ * Distributes over all schema types so models from every connection are included.
+ */
+type ModelName = _ExtractModelNames<InferAnySchema>;
+/**
+ * Database event names with all supported patterns.
+ */
+type DatabaseEventName = `${EventPhase}.${ModelName}.${DatabaseOperation}` | `${EventPhase}.${ModelName}` | `${EventPhase}.${DatabaseOperation}` | EventPhase;
+/**
+ * Map operation name to ZenStack Args type for a given schema and model
+ */
+type OperationArgsMap<S extends SchemaDef, M extends Extract<keyof S['models'], string>, O extends DatabaseOperation> = O extends 'create' ? CreateArgs<S, M> : O extends 'createMany' ? CreateManyArgs<S, M> : O extends 'update' ? UpdateArgs<S, M> : O extends 'updateMany' ? UpdateManyArgs<S, M> : O extends 'delete' ? DeleteArgs<S, M> : O extends 'deleteMany' ? DeleteManyArgs<S, M> : O extends 'findUnique' ? FindUniqueArgs<S, M> : O extends 'findFirst' ? FindFirstArgs<S, M> : O extends 'findMany' ? FindManyArgs<S, M> : O extends 'upsert' ? UpsertArgs<S, M> : O extends 'count' ? CountArgs<S, M> : O extends 'aggregate' ? AggregateArgs<S, M> : O extends 'groupBy' ? GroupByArgs<S, M> : never;
+/**
+ * Distributive helper — resolves data/where args for a model against each schema individually.
+ */
+type _ExtractData<S, M extends string, O extends DatabaseOperation> = S extends SchemaDef ? M extends Extract<keyof S['models'], string> ? OperationArgsMap<S, M, O> extends {
+  data: infer D;
+} ? D : OperationArgsMap<S, M, O> extends {
+  where: infer W;
+} ? W : OperationArgsMap<S, M, O> : never : never;
+/**
+ * Extract the data/where property from operation args.
+ * Distributes over all schemas to find the matching model.
+ */
+type GetData<M extends ModelName, O extends DatabaseOperation> = _ExtractData<InferAnySchema, M, O> extends never ? unknown : _ExtractData<InferAnySchema, M, O>;
+/**
+ * Distributive helper — resolves result type for a model against each schema individually.
+ */
+type _ExtractResult<S, M extends string, O extends DatabaseOperation> = S extends SchemaDef ? M extends Extract<keyof S['models'], string> ? O extends 'findMany' | 'createMany' | 'updateMany' | 'deleteMany' ? ModelResult<S, M>[] : O extends 'count' ? number : ModelResult<S, M> : never : never;
+/**
+ * Extract result type for a model operation.
+ * Distributes over all schemas to find the matching model.
+ */
+type GetResult<M extends ModelName, O extends DatabaseOperation> = _ExtractResult<InferAnySchema, M, O> extends never ? unknown : _ExtractResult<InferAnySchema, M, O>;
+/**
+ * Verb suffix for entity-mutation events (`entity.{Model}.{verb}`).
+ */
+type EntityMutationVerb = 'created' | 'updated' | 'deleted';
+/**
+ * Entity-mutation event names with all supported patterns.
+ *
+ * Unlike `before.*`/`after.*` (raw query args/result), entity events carry
+ * full entity snapshots: `created` has `after`, `updated` has `before` and
+ * `after`, `deleted` has `before`. The pre-mutation snapshot is loaded inside
+ * the mutation's transaction, and only when a listener matches — a wildcard
+ * subscription (`entity`) makes every model pay that pre-read, so subscribe
+ * per model when cost matters.
+ */
+type EntityEventName = `entity.${ModelName}.${EntityMutationVerb}` | `entity.${ModelName}` | `entity.${EntityMutationVerb}` | 'entity';
+/**
+ * Distributive helper — resolves the full entity shape for a model.
+ */
+type _ExtractEntity<S, M extends string> = S extends SchemaDef ? M extends Extract<keyof S['models'], string> ? ModelResult<S, M> : never : never;
+/**
+ * Full entity snapshot type for a model, across all connections' schemas.
+ */
+type GetEntity<M extends ModelName> = _ExtractEntity<InferAnySchema, M> extends never ? unknown : _ExtractEntity<InferAnySchema, M>;
+interface EntityCreatedEventContext<M extends ModelName> {
+  model: M;
+  action: 'created';
+  before: undefined;
+  after: GetEntity<M>;
+}
+interface EntityUpdatedEventContext<M extends ModelName> {
+  model: M;
+  action: 'updated';
+  before: GetEntity<M>;
+  after: GetEntity<M>;
+}
+interface EntityDeletedEventContext<M extends ModelName> {
+  model: M;
+  action: 'deleted';
+  before: GetEntity<M>;
+  after: undefined;
+}
+/** Context for model wildcard subscriptions (e.g. "entity.User") */
+interface EntityModelWildcardContext<M extends ModelName> {
+  model: M;
+  action: EntityMutationVerb;
+  before: GetEntity<M> | undefined;
+  after: GetEntity<M> | undefined;
+}
+/** Context for verb wildcard subscriptions (e.g. "entity.updated") */
+interface EntityVerbWildcardContext<V extends EntityMutationVerb> {
+  model: ModelName;
+  action: V;
+  before: V extends 'created' ? undefined : unknown;
+  after: V extends 'deleted' ? undefined : unknown;
+}
+/** Context for the global wildcard subscription ("entity") */
+interface EntityWildcardContext {
+  model: ModelName;
+  action: EntityMutationVerb;
+  before: unknown;
+  after: unknown;
+}
+type EntityEventContext<E extends string> = E extends `entity.${infer M extends ModelName}.created` ? EntityCreatedEventContext<M> : E extends `entity.${infer M extends ModelName}.updated` ? EntityUpdatedEventContext<M> : E extends `entity.${infer M extends ModelName}.deleted` ? EntityDeletedEventContext<M> : E extends `entity.${infer M extends ModelName}` ? EntityModelWildcardContext<M> : E extends `entity.${infer V extends EntityMutationVerb}` ? EntityVerbWildcardContext<V> : EntityWildcardContext;
+/**
+ * Mapped type producing all entity-mutation event name → context pairs.
+ */
+type EntityEvents = { [E in EntityEventName]: EntityEventContext<E>; };
+/**
+ * Parse event string into structured type for discriminated unions
+ */
+type ParseEvent<E extends string> = E extends `${infer Phase extends EventPhase}.${infer Model extends ModelName}.${infer Op extends DatabaseOperation}` ? {
+  phase: Phase;
+  model: Model;
+  operation: Op;
+  type: 'exact';
+} : E extends `${infer Phase extends EventPhase}.${infer Second}` ? Second extends ModelName ? {
+  phase: Phase;
+  model: Second;
+  type: 'model-wildcard';
+} : Second extends DatabaseOperation ? {
+  phase: Phase;
+  operation: Second;
+  type: 'operation-wildcard';
+} : never : E extends EventPhase ? {
+  phase: E;
+  type: 'phase-wildcard';
+} : never;
+/** Base context fields present in all events */
+interface BaseEventContext {}
+/** Context for exact database events (e.g., "after.User.create") */
+interface ExactDatabaseEventContext<M extends ModelName, O extends DatabaseOperation, Phase extends EventPhase> extends BaseEventContext {
+  data: Phase extends 'before' ? GetData<M, O> : Readonly<GetData<M, O>>;
+  result: Phase extends 'after' ? GetResult<M, O> : undefined;
+}
+/** Context for model wildcard events (e.g., "after.User") */
+interface ModelWildcardEventContext<Phase extends EventPhase> extends BaseEventContext {
+  operation: DatabaseOperation;
+  data: Phase extends 'before' ? unknown : Readonly<unknown>;
+  result: Phase extends 'after' ? unknown : undefined;
+}
+/** Context for operation wildcard events (e.g., "after.create") */
+interface OperationWildcardEventContext<Phase extends EventPhase> extends BaseEventContext {
+  model: ModelName;
+  data: Phase extends 'before' ? unknown : Readonly<unknown>;
+  result: Phase extends 'after' ? unknown : undefined;
+}
+/** Context for phase wildcard events (e.g., "after" or "before") */
+interface PhaseWildcardEventContext<Phase extends EventPhase> extends BaseEventContext {
+  model: ModelName;
+  operation: DatabaseOperation;
+  data: Phase extends 'before' ? unknown : Readonly<unknown>;
+  result: Phase extends 'after' ? unknown : undefined;
+}
+/**
+ * Type-safe event context with discriminated unions.
+ */
+type DatabaseEventContext<E extends string> = ParseEvent<E> extends {
+  phase: infer P extends EventPhase;
+  model: infer M extends ModelName;
+  operation: infer O extends DatabaseOperation;
+  type: 'exact';
+} ? ExactDatabaseEventContext<M, O, P> : ParseEvent<E> extends {
+  phase: infer P extends EventPhase;
+  model: infer _M extends ModelName;
+  type: 'model-wildcard';
+} ? ModelWildcardEventContext<P> : ParseEvent<E> extends {
+  phase: infer P extends EventPhase;
+  operation: infer _O extends DatabaseOperation;
+  type: 'operation-wildcard';
+} ? OperationWildcardEventContext<P> : ParseEvent<E> extends {
+  phase: infer P extends EventPhase;
+  type: 'phase-wildcard';
+} ? PhaseWildcardEventContext<P> : BaseEventContext;
+/**
+ * Mapped type that produces all database event name to context pairs.
+ *
+ * Used to augment core's `CustomEventRegistry`:
+ *
+ * @example
+ * ```typescript
+ * declare module 'stratal/events' {
+ *   interface CustomEventRegistry extends DatabaseEvents {}
+ * }
+ * ```
+ */
+type DatabaseEvents = { [E in DatabaseEventName]: DatabaseEventContext<E>; };
+declare module 'stratal/events' {
+  interface CustomEventRegistry extends DatabaseEvents, EntityEvents {}
+}
+//#endregion
+//#region src/database/i18n/en.d.ts
+declare const databaseMessages: {
+  readonly en: {
+    readonly connectionNameRequired: 'Connection name is required';
+    readonly defaultConnectionRequired: 'Default connection name is required';
+    readonly connectionRequired: 'At least one connection is required';
+    readonly duplicateConnections: 'Duplicate connection names found';
+    readonly defaultConnectionNotFound: 'Default connection not found in connections';
+  };
+};
+declare module 'stratal/i18n' {
+  interface AppMessageNamespaces {
+    database: typeof databaseMessages['en'];
+  }
+}
+//#endregion
+//#region src/database/plugins/error-handler.plugin.d.ts
+/**
+ * ZenStack runtime plugin that transforms ORM errors into ApplicationError instances.
+ *
+ * @example
+ * ```typescript
+ * super(schema, {
+ *   dialect: new PostgresDialect({ pool }),
+ *   plugins: [new ErrorHandlerPlugin()]
+ * })
+ * ```
+ */
+declare class ErrorHandlerPlugin implements RuntimePlugin<SchemaDef$1, Record<string, unknown>, Record<string, unknown>, {}> {
+  readonly id = "error-handler";
+  onQuery: ({ args, proceed }: {
+    args: Record<string, unknown> | undefined;
+    proceed: (args: Record<string, unknown> | undefined) => Promise<unknown>;
+  }) => Promise<unknown>;
+}
+//#endregion
+//#region src/database/plugins/event-emitter.plugin.d.ts
+interface EventEmitterPluginOptions {
+  eventRegistry: IEventRegistry;
+}
+/**
+ * ZenStack runtime plugin that emits before/after events for database operations.
+ *
+ * Emits events in the format:
+ * - `before.{Model}.{operation}` - Before the database operation
+ * - `after.{Model}.{operation}` - After the database operation
+ *
+ * Additionally emits entity-mutation events carrying full entity snapshots:
+ * - `entity.{Model}.created` - `{ after }`
+ * - `entity.{Model}.updated` - `{ before, after }`
+ * - `entity.{Model}.deleted` - `{ before }`
+ *
+ * Entity events are listener-driven: the pre-mutation snapshot is only
+ * loaded (inside the mutation's transaction) when `hasListeners()` reports
+ * a matching subscription, so models nobody observes pay no cost. Note that
+ * a wildcard subscription (`entity`) therefore makes every model pay the
+ * pre-read — subscribe per model when cost matters.
+ *
+ * @example
+ * ```typescript
+ * super(schema, {
+ *   dialect: new PostgresDialect({ pool }),
+ *   plugins: [
+ *     new EventEmitterPlugin({
+ *       eventRegistry,
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+declare class EventEmitterPlugin implements RuntimePlugin<SchemaDef$1, Record<string, unknown>, Record<string, unknown>, {}> {
+  private options;
+  readonly id = "event-emitter";
+  constructor(options: EventEmitterPluginOptions);
+  onEntityMutation: EntityMutationHooksDef<SchemaDef$1>;
+  onQuery: ({ model, operation, args, proceed }: {
+    model: string;
+    operation: string;
+    args: Record<string, unknown> | undefined;
+    proceed: (args: Record<string, unknown> | undefined) => Promise<unknown>;
+  }) => Promise<unknown>;
+}
+//#endregion
+//#region src/database/plugins/schema-switcher.d.ts
+/**
+ * Switches the active schema on a ZenStack/Kysely database client by mutating
+ * `$schema.provider.defaultSchema`. This causes ZenStack's QueryNameMapper to
+ * generate fully-qualified table references (e.g. `"tenant_123"."User"`).
+ *
+ * Must be called BEFORE any queries are made on the client.
+ *
+ * Note: The ZenStack RuntimePlugin `onQuery` hook fires after table names are
+ * already resolved, so a plugin-based approach cannot set the schema prefix.
+ * Direct client mutation is the only supported method.
+ */
+declare class SchemaSwitcher {
+  static apply<T>(client: T, schemaName: string): T;
+}
+//#endregion
+//#region src/database/commands/zenstack.command.d.ts
+/**
+ * Base command for ZenStack CLI wrappers.
+ * Uses execFileSync with array arguments to prevent shell injection.
+ */
+declare abstract class ZenStackCommand extends Command {
+  protected zenstack(args: string[]): Promise<number>;
+}
+//#endregion
+//#region src/database/commands/db-generate.command.d.ts
+declare class DbGenerateCommand extends ZenStackCommand {
+  static command: string;
+  static description: string;
+  handle(): Promise<number>;
+}
+//#endregion
+//#region src/database/commands/db-pull.command.d.ts
+declare class DbPullCommand extends ZenStackCommand {
+  static command: string;
+  static description: string;
+  handle(): Promise<number>;
+}
+//#endregion
+//#region src/database/commands/db-push.command.d.ts
+declare class DbPushCommand extends ZenStackCommand {
+  static command: string;
+  static description: string;
+  handle(): Promise<number>;
+}
+//#endregion
+//#region src/database/commands/migrate-deploy.command.d.ts
+declare class MigrateDeployCommand extends ZenStackCommand {
+  static command: string;
+  static description: string;
+  handle(): Promise<number>;
+}
+//#endregion
+//#region src/database/commands/migrate-dev.command.d.ts
+declare class MigrateDevCommand extends ZenStackCommand {
+  static command: string;
+  static description: string;
+  handle(): Promise<number>;
+}
+//#endregion
+//#region src/database/commands/migrate-reset.command.d.ts
+declare class MigrateResetCommand extends ZenStackCommand {
+  static command: string;
+  static description: string;
+  handle(): Promise<number>;
+}
+//#endregion
+//#region src/database/commands/migrate-status.command.d.ts
+declare class MigrateStatusCommand extends ZenStackCommand {
+  static command: string;
+  static description: string;
+  handle(): Promise<number>;
+}
+//#endregion
+export { CursorPageDelegate as $, CursorOrderingError as A, CursorModelKey as B, GetResult as C, UniqueConstraintError as D, fromZenStackError as E, DATABASE_TOKENS as F, CursorSourceArgs as G, CursorOrderByOf as H, connectionSymbol as I, CursorSourceReader as J, CursorSourceColumn as K, DatabaseService as L, InjectDB as M, DB_SHARED_POOL_ENV as N, RecordNotFoundError as O, createPoolFactory as P, CursorPageArgs as Q, TransactionService as R, GetEntity as S, ParseEvent as T, CursorReader as U, CursorModelReader as V, CursorReaderArgs as W, CursorFindManyArgs as X, createCursorReader as Y, CursorOrderBy as Z, EntityEventName as _, DbPushCommand as a, DatabaseModule as at, EventPhase as b, ZenStackCommand as c, EventEmitterPluginOptions as d, CursorPageResult as et, ErrorHandlerPlugin as f, DatabaseOperation as g, DatabaseEvents as h, MigrateDeployCommand as i, DatabaseConnectionConfig as it, CursorModelUnavailableError as j, MalformedCursorError as k, SchemaSwitcher as l, DatabaseEventName as m, MigrateResetCommand as n, decodeCursor as nt, DbPullCommand as o, DatabaseModuleConfig as ot, databaseMessages as p, CursorSourceOrderBy as q, MigrateDevCommand as r, encodeCursor as rt, DbGenerateCommand as s, MigrateStatusCommand as t, CursorSortOrder as tt, EventEmitterPlugin as u, EntityEvents as v, ModelName as w, GetData as x, EntityMutationVerb as y, CursorClientMembers as z };
+//# sourceMappingURL=index-e_u1SRyd.d.mts.map