@voltro/database 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1124,6 +1124,18 @@ export declare interface ColumnDefinition<TsType, Type extends ColumnType = Colu
     readonly __tsType?: TsType;
 }
 
+/**
+ * The per-column mapping, over a column DEFINITION — what `table.fields` holds.
+ *
+ * Not the builder `text()` returns: its `definition` is private, so a builder
+ * cannot be read from outside. Worth stating because the natural call is
+ * `columnSchema(timestamp())`, and an earlier version accepted it structurally,
+ * found no `type`, and fell through to `Schema.Unknown` — which passes every
+ * value through unchanged, so the mapping looked right in any test that only
+ * checked a round trip. Take definitions from `table.fields`.
+ */
+export declare const columnSchema: <TsType, C extends ColumnType>(def: ColumnDefinition<TsType, C>) => Schema.Schema.Any;
+
 export declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
 
 /**
@@ -1136,9 +1148,13 @@ export declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal'
  *   - A relation name in the eager tree isn't registered (corner case
  *     the walker would surface with a clearer error — better to fall
  *     back to it).
- *   - The dialect doesn't have a compiler module yet.
- *   - The compiler hits an explicitly-bailed feature (rare — listed
- *     in the per-dialect modules' comments).
+ *   - An `inferForeignKey` on the eager tree is ambiguous, so there is no
+ *     single key to correlate on (the walker raises the explanatory error).
+ *
+ * There is no feature the compiler declines on purpose. `junction: [...]`
+ * projection and the `one`-cardinality check — the two that used to be served
+ * by the walker for correctness reasons — are compiled per dialect and covered
+ * by walker-vs-JSON parity tests against every live engine.
  *
  * Callers (the dialect data stores) treat `null` as "fall back to the
  * walker". This keeps the optimization opt-out-by-failure rather than
@@ -1251,7 +1267,15 @@ export declare type DatabaseHandle<Tables extends Record<string, Table<string, R
 export declare const databaseHandle: <Tables extends Record<string, Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>>>(tables: Tables) => DatabaseHandle<Tables>;
 
 export declare interface DataStore {
-    /** Execute a typed query descriptor and return matching rows. */
+    /**
+     * Execute a typed query descriptor and return matching rows.
+     *
+     * Deliberately NOT generic: `DataStore` is the driver SPI, implemented by
+     * every dialect store and its transactional / namespace views. Threading a
+     * phantom row type through all of them would be pure churn — they genuinely
+     * do return untyped rows off the wire. The row type is re-applied one layer
+     * up, on `FluentStore.query`, which is what handlers actually call.
+     */
     query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
     /** Insert a row. Emits an insert ChangeEvent (deferred if inside `transactional()`). */
     insert(table: string, row: Row): Promise<Row>;
@@ -1748,6 +1772,22 @@ export declare const drainIdentifierWarnings: () => ReadonlyArray<string>;
  */
 export declare const dropped: () => ColumnBuilder<unknown, "text">;
 
+/**
+ * Raised when a relation declared `one` matches MORE than one row for the same
+ * parent key — the mis-declaration that silently hands the app an arbitrary
+ * child instead of the parent it asked for.
+ *
+ * It is its own class because BOTH eager paths raise it: the walker while
+ * bucketing, the single-query JSON path while decoding an over-fetched array.
+ * The stores' JSON-agg attempt falls back to the walker on any error; this one
+ * must NOT trigger that fallback — the walker would re-run the same query and
+ * raise the same message, costing a round trip to reach the identical outcome.
+ */
+export declare class EagerCardinalityError extends Error {
+    readonly _tag = "EagerCardinalityError";
+    constructor(message: string);
+}
+
 /**
  * Compiled JSON-aggregation plan: a `Statement.Statement` ready to
  * execute via `SqlClient.SqlClient`, plus a `decode()` that restores
@@ -1794,6 +1834,28 @@ export declare interface EagerLoadSpec {
     /** Per-parent offset. Only meaningful with `limit`. */
     readonly offset?: number;
     readonly with?: WithSpec;
+    /**
+     * Project the JUNCTION row's own columns into a `manyToMany` eager result.
+     *
+     * `true` takes every junction column; an array takes only those named. The
+     * values land under `_junction` on each target row:
+     *
+     *     projects.with({ teams: { junction: ['role', 'addedAt'] } })
+     *     // → team._junction.addedAt
+     *
+     * Nested rather than merged onto the target row, deliberately: a junction and
+     * its target routinely share column names (`createdAt` is the obvious one),
+     * and merging would silently overwrite real target data with membership data.
+     * A name collision that corrupts a row is worse than one extra level.
+     *
+     * Why this exists: junction tables carrying meaningful columns — a role, a
+     * joined-at stamp, a permission tier — are the rule rather than the
+     * exception, and without this an eager load could FILTER on them
+     * (`onJunction`) but never return them, so any relation with real membership
+     * data had to stay a hand-written join. The junction rows were already being
+     * fetched in full to resolve the target ids; this stops throwing them away.
+     */
+    readonly junction?: true | ReadonlyArray<string>;
     /**
      * Filter a `manyToMany` eager branch on the THROUGH-table's columns.
      * The predicate is evaluated against the junction row, not the target
@@ -1818,14 +1880,6 @@ export declare interface EagerLoadSpec {
  */
 export declare type EagerLookup = (descriptor: QueryDescriptor) => Promise<ReadonlyArray<Row_2>>;
 
-/**
- * The compiler walks `descriptor.eager` ONCE to build this tree —
- * each node has the relation's resolved kind, the resolved FK column
- * names (auto-inferred when not explicit), the target table's column
- * shape, and the resolved nested children. Dialects render this
- * structure into their JSON-agg dialect; the decoder walks it to
- * restore types.
- */
 export declare interface EagerRelationNode {
     readonly relationName: string;
     readonly relation: Relation;
@@ -1839,6 +1893,8 @@ export declare interface EagerRelationNode {
     readonly fkSide: 'source' | 'target';
     readonly branch: EagerLoadSpec;
     readonly children: ReadonlyArray<EagerRelationNode>;
+    /** Set only on `manyToMany` branches that asked for junction columns. */
+    readonly junction: JunctionProjection | undefined;
 }
 
 export declare interface EagerRootPlan {
@@ -2489,6 +2545,30 @@ export declare interface JsonIndexPath {
     readonly numeric: boolean;
 }
 
+/**
+ * The compiler walks `descriptor.eager` ONCE to build this tree —
+ * each node has the relation's resolved kind, the resolved FK column
+ * names (auto-inferred when not explicit), the target table's column
+ * shape, and the resolved nested children. Dialects render this
+ * structure into their JSON-agg dialect; the decoder walks it to
+ * restore types.
+ */
+/**
+ * A resolved `junction: [...]` / `junction: true` projection on a `manyToMany`
+ * branch. `requested` is what the caller asked for IN ORDER; `present` is the
+ * subset the through table actually has — the only columns SQL can select. The
+ * decoder re-materialises the difference as `undefined`, matching the walker,
+ * which reads a missing key off the junction row and gets `undefined` rather
+ * than raising.
+ */
+export declare interface JunctionProjection {
+    readonly through: TableLike;
+    readonly requested: ReadonlyArray<string>;
+    readonly present: ReadonlyArray<string>;
+    /** Present columns whose schema type needs ISO-string → Date restoration. */
+    readonly dateColumns: ReadonlyArray<string>;
+}
+
 export declare const lag: (column: string, offset?: number, alias?: string) => WindowBuilder;
 
 export declare const lead: (column: string, offset?: number, alias?: string) => WindowBuilder;
@@ -2801,6 +2881,19 @@ export declare const one: (target: TableRef, options?: {
     readonly sourceKey?: string;
 }) => OneRelation;
 
+/**
+ * The single source of the `one`-cardinality message. Both eager paths call it
+ * so a user comparing them can never be shown two different explanations of the
+ * same mistake.
+ */
+export declare const oneCardinalityMessage: (args: {
+    readonly relationName: string;
+    readonly sourceTableName: string;
+    readonly targetTableName: string;
+    readonly foreignKey: string;
+    readonly sourceKey: string;
+}) => string;
+
 /** 1:1 — the source table OR the target carries the FK. */
 export declare interface OneRelation {
     readonly kind: 'one';
@@ -2829,6 +2922,29 @@ export declare interface OrPredicate {
     readonly or: ReadonlyArray<Predicate>;
 }
 
+/**
+ * Keyset pagination on ANY orderable column — the general form of
+ * `paginateById`.
+ *
+ * `paginateById` hardcodes `id`, which is correct for a stable typeid/uuidv7
+ * key and useless for the case real feeds actually need: "the next page by
+ * `createdAt`". Apps hit that immediately and fell back to hand-rolled
+ * `limit + 1` / slice / `hasMore` triples — often on a timestamp cursor the
+ * helper could not express at all.
+ *
+ * The column MUST be unique, or monotonic enough that ties do not straddle a
+ * page boundary; otherwise a keyset cursor can skip or repeat rows at the seam.
+ * For a non-unique column (a timestamp with collisions) pass a composite order
+ * on the descriptor first — `.orderBy('createdAt').orderBy('id')` — and
+ * paginate by the tie-breaker.
+ *
+ * `direction` controls both the comparison and the ORDER BY, so a `desc` feed
+ * ("newest first") pages with `<` instead of `>`. Getting that pairing wrong is
+ * the classic keyset bug: an ascending comparison under a descending sort
+ * silently returns the same page forever.
+ */
+export declare const paginateBy: (descriptor: QueryDescriptor, column: string, cursor: string | number | Date | undefined, limit: number, direction?: "asc" | "desc") => QueryDescriptor;
+
 /**
  * Cursor pagination by primary key — `WHERE id > cursor ORDER BY id ASC LIMIT n`.
  *
@@ -2968,7 +3084,8 @@ export declare interface Query<RowOf, IxNames extends string = string,
 * `'alias.column'` → value type. Unjoined queries default to `{}`.
 */
 Joins extends JoinsMap = {}> {
-    readonly descriptor: QueryDescriptor;
+    /** Carries `RowOf` through to `store.query()` — see `QueryDescriptor<R>`. */
+    readonly descriptor: QueryDescriptor<RowOf>;
     /** Refine the predicate. Multiple `.where(...)` calls combine with AND. */
     where: (predicate: Predicate) => Query<RowOf, IxNames, Joins>;
     orderBy: <K extends keyof RowOf & string>(column: K, direction?: 'asc' | 'desc') => Query<RowOf, IxNames, Joins>;
@@ -3338,9 +3455,30 @@ Joins extends JoinsMap = {}> {
     }, IxNames, Joins>;
 }
 
-export declare interface QueryDescriptor {
+/**
+ * The runtime-facing materialized query — a plain bag of strings the store and
+ * the matcher consume.
+ *
+ * `R` is a PHANTOM row type. It exists so the row shape the typed builder
+ * already knows survives the trip through `.descriptor` into `store.query()`,
+ * which is where it used to be thrown away: `store.query(database.notes...)`
+ * returned `Row` (`Record<string, unknown>`), so every field read needed a
+ * hand-written cast. One downstream app wrote 2,032 of them. The type was
+ * always available — it was just dropped at this boundary.
+ *
+ * It is an OPTIONAL field, never set at runtime. That matters for two reasons:
+ * a plain object literal still satisfies `QueryDescriptor` (dispatcher, matcher
+ * and store code build and forward these structurally), and `R` stays
+ * covariant, so a `QueryDescriptor<Note>` is still assignable to the bare
+ * `QueryDescriptor` that generic infrastructure passes around. Defaulting to
+ * `Row` keeps every existing annotation meaning exactly what it meant before.
+ */
+export declare interface QueryDescriptor<R = Row> {
     readonly table: string;
     readonly predicate: Predicate | undefined;
+    /** Phantom — carries the row type through to `store.query()`. Never set at
+     *  runtime; erased entirely by the compiler. */
+    readonly __row?: R;
     /**
      * Opt OUT of the runtime's automatic `deletedAt IS NULL` scope on
      * `softDelete()` tables. Set by `.withDeleted()`. The query builder is
@@ -3987,6 +4125,19 @@ declare type Row_3 = Readonly<Record<string, unknown>>;
 
 export declare const rowNumber: (alias?: string) => WindowBuilder;
 
+/**
+ * Build a row schema for `table`.
+ *
+ * `omit` drops columns from the OUTPUT — the way to keep an `.encrypted()`
+ * token or an internal bookkeeping column off the wire. It is a convenience,
+ * not a security boundary: a column omitted here is simply absent from this
+ * schema, and a handler that returns it under a different schema still sends
+ * it.
+ */
+export declare const rowSchema: <T extends TableLike>(table: T, options?: {
+    readonly omit?: ReadonlyArray<string>;
+}) => Schema.Schema.Any;
+
 /**
  * Lower a tenant id to the safe identifier fragment used inside a
  * namespace name. ONLY `[a-z0-9_]` survive; every other character —
@@ -4884,6 +5035,33 @@ export declare const validateColumnName: (tableName: string, columnName: string)
  */
 export declare const validateIndexName: (tableName: string, indexName: string, isAuto: boolean, fields: ReadonlyArray<string>) => void;
 
+/**
+ * Validate every registered relation's key options against the real tables.
+ *
+ * Deliberately a BOOT SWEEP rather than a check inside `registerRelations`:
+ * a relation's target is a thunk precisely so circular declarations can be
+ * written (`one(() => teams, ...)`), and resolving it at registration time
+ * would force the declaration order the DSL exists to avoid. By boot every
+ * table and every spec is loaded, so the thunks are safe to call.
+ *
+ * Throws on the first bad relation, naming the option that would have been
+ * right — see `validateRelationConfig` for the bug that motivated it. A source
+ * table that is not in the table registry is SKIPPED rather than reported:
+ * that is a different failure with its own clearer message at query time, and
+ * turning it into a relations error here would misdirect.
+ */
+export declare const validateRegisteredRelations: () => void;
+
+/**
+ * Reject a relation whose explicit key options cannot possibly resolve.
+ * Pure: takes the already-resolved tables, so it is safe to call from a boot
+ * sweep AND from the join compiler.
+ *
+ * Throws with the corrected option named whenever the column exists on the
+ * OTHER side — that mix-up is the whole reason this function exists.
+ */
+export declare const validateRelationConfig: (source: TableLike, relationName: string, relation: Relation) => void;
+
 /**
  * Validate a table name supplied to `table('<name>', ...)`. Throws on
  * empty / invalid characters / > 63 bytes. Records a WARN above 50.