kysely-rizzolver 0.0.2 → 0.0.3

package/dist/esm/query-builder.js

@@ -5,12 +5,17 @@ export function newQueryBuilder(rizzolver) {
     const selectors = {};
     return {
         selectors,
+        get numSelectors() {
+            return Object.keys(selectors).length;
+        },
         table(tableAlias) {
             return selectors[tableAlias].selectTable;
         },
-        allFields: Object.values(selectors)
-            .map((selector) => selector.selectFields)
-            .flat(),
+        allFields() {
+            return Object.values(selectors)
+                .map((selector) => selector.selectFields)
+                .flat();
+        },
         fieldsOf(...tableAliases) {
             return tableAliases.map((alias) => selectors[alias].selectFields).flat();
         },
@@ -30,7 +35,7 @@ export function newQueryBuilder(rizzolver) {
                 if (!alias) {
                     throw new Error('Must provide an alias when calling QueryBuilder.add with a table name');
                 }
-                selector = newSelector(rizzolver, selectorOrTable, alias, (keys ?? rizzolver.fields[selectorOrTable]));
+                selector = newSelector(rizzolver, selectorOrTable, alias, (keys ?? rizzolver._types.fields[selectorOrTable]));
             }
             else {
                 if (alias || keys) {
@@ -87,3 +92,4 @@ export function newQueryBuilder(rizzolver) {
         }
     };
 }
+//# sourceMappingURL=query-builder.js.map

package/dist/esm/query-builder.js.map

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

package/dist/esm/selector.js

@@ -1,5 +1,5 @@
 export function newSelector(rizzolver, tableName, alias, keys) {
-    const effectiveKeys = (keys ?? rizzolver.fields[tableName]);
+    const effectiveKeys = (keys ?? rizzolver._types.fields[tableName]);
     const tableAlias = `${tableName} as ${alias}`;
     const fields = effectiveKeys.map((field) => `${alias}.${field} as _${alias}_${field}`);
     function _rowToModel(result) {
@@ -40,3 +40,4 @@ export function newSelector(rizzolver, tableName, alias, keys) {
     };
     return selector;
 }
+//# sourceMappingURL=selector.js.map

package/dist/esm/selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.js","sourceRoot":"","sources":["../../src/selector.ts"],"names":[],"mappings":"AAsKA,MAAM,UAAU,WAAW,CAKzB,SAAa,EAAE,SAAgB,EAAE,KAAY,EAAE,IAAW;IAC3D,MAAM,aAAa,GAAG,CAAC,IAAI,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAS,CAAC;IAG3E,MAAM,UAAU,GAAG,GAAG,SAAS,OAAO,KAAK,EAAW,CAAC;IACvD,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAC/B,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,KAAK,QAAQ,KAAK,IAAI,KAAK,EAAW,CAC7B,CAAC;IAElC,SAAS,WAAW,CAAC,MAA2C;QAC/D,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YACxC,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,MAAM,KAAK,GAAG,EAAS,CAAC;QACxB,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;YACnC,MAAM,YAAY,GAAG,IAAI,KAAK,IAAI,KAAK,EAAW,CAAC;YACnD,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC;QAClD,CAAC;QACD,OAAO,KAAK,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAqC;QAClD,KAAK,EAAE;YACN,KAAK,EAAE,SAAS;YAChB,KAAK;YACL,WAAW,EAAE,aAAa;SAC1B;QACD,WAAW,EAAE,UAAU;QACvB,YAAY,EAAE,MAAM;QACpB,KAAK,CAA6B,KAAY;YAC7C,OAAO;gBACN,GAAG,EAAE,IAAI,KAAK,IAAI,KAAK,EAAE;gBACzB,IAAI,CAAmB,KAAQ;oBAC9B,OAAO,GAAG,KAAK,KAAK,KAAK,IAAI,KAAK,EAAE,CAAC;gBACtC,CAAC;aACQ,CAAC;QACZ,CAAC;QAED,MAAM,CAAsC,IAAW;YACtD,MAAM,IAAI,GAAoD,EAAE,CAAC;YAEjE,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACxB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;gBAC/B,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;YAC3B,CAAC;YAED,OAAO,IAAI,CAAC;QACb,CAAC;KACQ,CAAC;IAEX,OAAO,QAAQ,CAAC;AACjB,CAAC"}

package/dist/esm/type-helpers.js

@@ -1 +1,2 @@
 export {};
+//# sourceMappingURL=type-helpers.js.map

package/dist/esm/type-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-helpers.js","sourceRoot":"","sources":["../../src/type-helpers.ts"],"names":[],"mappings":""}

package/dist/types/fetch-result.d.ts

@@ -1,5 +1,5 @@
 import type { Selectable } from 'kysely';
-import type { ModelCollection } from './model-collection.js';
+import { type ModelCollection } from './model-collection.js';
 /**
  * A {@link FetchResult} is a result of a fetch operation. It can be one of
  * three types:
@@ -10,16 +10,19 @@ import type { ModelCollection } from './model-collection.js';
  * - {@link FetchSomeResult} - A result of a fetch operation that is expected to
  *   return any number of rows.
  */
-export type FetchResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>>> = FetchOneResult<DB, T, R> | FetchOneXResult<DB, T, R> | FetchSomeResult<DB, T, R>;
+export type FetchResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>> = Selectable<DB[T]>> = FetchOneResult<DB, T, R> | FetchOneXResult<DB, T, R> | FetchSomeResult<DB, T, R>;
 /**
  * A {@link FetchOneResult} is a result of a fetch operation that is expected to
  * return up to one row.
  */
-export type FetchOneResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>> | undefined> = {
+export type FetchOneResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>> = Selectable<DB[T]>> = {
     fetchType: 'fetchOne';
     table: T;
     result: R | undefined;
-    models?: ModelCollection<DB>;
+    /**
+     * The {@link ModelCollection} that contains the fetched models.
+     */
+    models: ModelCollection<DB>;
     /**
      * Returns this result as a {@link FetchOneXResult}.
      *
@@ -31,11 +34,11 @@ export type FetchOneResult<DB, T extends keyof DB & string, R extends Partial<Se
  * A {@link FetchOneXResult} is a result of a fetch operation that is expected
  * to return exactly one row.
  */
-export type FetchOneXResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>>> = {
+export type FetchOneXResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>> = Selectable<DB[T]>> = {
     fetchType: 'fetchOne';
     table: T;
     result: R;
-    models?: ModelCollection<DB>;
+    models: ModelCollection<DB>;
     /**
      * Returns self. This is a no-op, but it's here to make it possible to
      * cast this object back to a {@link FetchOneXResult}.
@@ -46,11 +49,11 @@ export type FetchOneXResult<DB, T extends keyof DB & string, R extends Partial<S
  * A {@link FetchSomeResult} is a result of a fetch operation that is expected
  * to return any number of rows.
  */
-export type FetchSomeResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>>> = {
+export type FetchSomeResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>> = Selectable<DB[T]>> = {
     fetchType: 'fetchSome';
     table: T;
     result: R[];
-    models?: ModelCollection<DB>;
+    models: ModelCollection<DB>;
 };
 /**
  * Used to type juggle between {@link FetchResult} and its subtypes.

package/dist/types/fk-gather-result-factory.d.ts

@@ -0,0 +1,69 @@
+import { type FkGatherOneResult, type FkGatherOneXResult, type FkGatherSomeResult } from './fk-gather-result.js';
+import type { DBWithFk, ModelFkExtractSelectable, ModelFkInstance, ValidFkDepth } from './fks.js';
+import type { KyselyRizzolverFKs } from './kysely-rizzolver.js';
+import { type ModelCollection } from './model-collection.js';
+/**
+ * A {@link FkGatherResultFactory} exposes variants of gather-related functions, but
+ * with the `DB` type parameter already set.
+ *
+ * This makes it less verbose to work with gather results in a type-safe way.
+ */
+export type FkGatherResultFactory<DB, FKDefs extends KyselyRizzolverFKs<DB>> = ReturnType<typeof newFkGatherResultFactory<DB, FKDefs>>;
+export declare function newFkGatherResultFactory<DB, FKDefs extends KyselyRizzolverFKs<DB>>(): {
+    /**
+     * Creates a new {@link GatherOneResult} instance.
+     */
+    newGatherOne<K extends (keyof DB & string) & string, Depth extends ValidFkDepth>(table: K, depth: Depth, result: ModelFkInstance<DBWithFk<DB, FKDefs>, K, Depth> | undefined, models?: ModelCollection<DB>): FkGatherOneResult<DBWithFk<DB, FKDefs>, K, Depth>;
+    /**
+     * Creates a new {@link GatherOneXResult} instance.
+     *
+     * Note: it may be counterintuitive, but this function accepts `undefined` as
+     * input. I found it is way more convenient to assert the type once in this
+     * funciton rather than in every caller.
+     */
+    newGatherOneX<K extends (keyof DB & string) & string, Depth extends ValidFkDepth>(table: K, depth: Depth, result: ModelFkInstance<DBWithFk<DB, FKDefs>, K, Depth> | undefined, models?: ModelCollection<DB>): FkGatherOneXResult<DBWithFk<DB, FKDefs>, K, Depth>;
+    /**
+     * Creates a new {@link GatherSomeResult} instance.
+     */
+    newGatherSome<K extends (keyof DB & string) & string, Depth extends ValidFkDepth>(table: K, depth: Depth, result: ModelFkInstance<DBWithFk<DB, FKDefs>, K, Depth>[], models?: ModelCollection<DB>): FkGatherSomeResult<DBWithFk<DB, FKDefs>, K, Depth>;
+    /**
+     * Checks if a {@link GatherResult} is a {@link GatherOneResult}.
+     */
+    isGatherOne<K extends (keyof DB & string) & string, Depth extends ValidFkDepth>(table: K, depth: Depth, result: unknown): result is FkGatherOneResult<DBWithFk<DB, FKDefs>, K, Depth>;
+    /**
+     * Checks if a {@link GatherResult} is a {@link GatherOneXResult}.
+     */
+    isGatherOneX<K extends (keyof DB & string) & string, Depth extends ValidFkDepth>(table: K, depth: Depth, result: unknown): result is FkGatherOneXResult<DBWithFk<DB, FKDefs>, K, Depth>;
+    /**
+     * Checks if a {@link GatherResult} is a {@link GatherSomeResult}.
+     */
+    isGatherSome<K extends (keyof DB & string) & string, Depth extends ValidFkDepth>(table: K, depth: Depth, result: unknown): result is FkGatherSomeResult<DBWithFk<DB, FKDefs>, K, Depth>;
+    /**
+     * Asserts that a {@link GatherResult} is a {@link GatherOneResult}.
+     */
+    assertIsGatherOne<K extends (keyof DB & string) & string, Depth extends ValidFkDepth>(table: K, depth: Depth, result: unknown): asserts result is FkGatherOneResult<DBWithFk<DB, FKDefs>, K, Depth>;
+    /**
+     * Asserts that a {@link GatherResult} is a {@link GatherOneXResult}.
+     */
+    assertIsGatherOneX<K extends (keyof DB & string) & string, Depth extends ValidFkDepth>(table: K, depth: Depth, result: unknown): asserts result is FkGatherOneXResult<DBWithFk<DB, FKDefs>, K, Depth>;
+    /**
+     * Asserts that a {@link GatherResult} is a {@link GatherSomeResult}.
+     */
+    assertIsGatherSome<K extends (keyof DB & string) & string, Depth extends ValidFkDepth>(table: K, depth: Depth, result: unknown): asserts result is FkGatherSomeResult<DBWithFk<DB, FKDefs>, K, Depth>;
+    /**
+     * Extracts a Kysely {@link Selectable} instance from a gathered model.
+     *
+     * This is useful because Selectables are the lowest common denominators
+     * for any representation of a DB model, so this allows you to convert
+     * any gather result to anything else that might build upon Kysely.
+     *
+     * For example, to convert a gather result to a fetch result:
+     * ```
+     * const userGather: FkGatherOneXResult<DB, 'user'>;
+     * const userModel = userGather.result;
+     * const userSelectable = rizzolver.gatherObjs.toSelectable(userModel);
+     * ```
+     *
+     */
+    toSelectable<Model>(model: Model): ModelFkExtractSelectable<DB, Model>;
+};

package/dist/types/fk-gather-result.d.ts

@@ -0,0 +1,115 @@
+import type { DBWithoutFk, ModelFkInstance, ValidFkDepth } from './fks.js';
+import { MAX_FK_GATHER_DEPTH } from './fks.js';
+import type { ModelCollection } from './model-collection.js';
+/**
+ * A {@link FkGatherResult} is a result of a gather operation. It can be one of
+ * three types:
+ * - {@link FkGatherOneResult} - A result of a gather operation that is expected to
+ *   return up to one row,
+ * - {@link FkGatherOneXResult} - A result of a gather operation that is expected to
+ *   return exactly one row,
+ * - {@link FkGatherSomeResult} - A result of a gather operation that is expected to
+ *   return any number of rows.
+ */
+export type FkGatherResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth = typeof MAX_FK_GATHER_DEPTH> = FkGatherOneResult<DBFk, Table, Depth> | FkGatherOneXResult<DBFk, Table, Depth> | FkGatherSomeResult<DBFk, Table, Depth>;
+/**
+ * A {@link FkGatherOneResult} is a result of a gather operation that is expected to
+ * return up to one row.
+ */
+export type FkGatherOneResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth = typeof MAX_FK_GATHER_DEPTH> = {
+    gatherType: 'gatherOne';
+    table: Table;
+    depth: Depth;
+    result: ModelFkInstance<DBFk, Table, Depth> | undefined;
+    models?: ModelCollection<DBWithoutFk<DBFk>>;
+    /**
+     * Returns this result as a {@link FkGatherOneXResult}.
+     *
+     * @throws If the result is null or undefined.
+     */
+    asGatherOneX(): FkGatherOneXResult<DBFk, Table, Depth>;
+};
+/**
+ * A {@link FkGatherOneXResult} is a result of a gather operation that is expected
+ * to return exactly one row.
+ */
+export type FkGatherOneXResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth = typeof MAX_FK_GATHER_DEPTH> = {
+    gatherType: 'gatherOne';
+    table: Table;
+    depth: Depth;
+    result: ModelFkInstance<DBFk, Table, Depth>;
+    models?: ModelCollection<DBWithoutFk<DBFk>>;
+    /**
+     * Returns self. This is a no-op, but it's here to make it possible to
+     * cast this object back to a {@link FkGatherOneXResult}.
+     */
+    asGatherOneX(): FkGatherOneXResult<DBFk, Table, Depth>;
+};
+/**
+ * A {@link FkGatherSomeResult} is a result of a gather operation that is expected
+ * to return any number of rows.
+ */
+export type FkGatherSomeResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth = typeof MAX_FK_GATHER_DEPTH> = {
+    gatherType: 'gatherSome';
+    table: Table;
+    depth: Depth;
+    result: ModelFkInstance<DBFk, Table, Depth>[];
+    models?: ModelCollection<DBWithoutFk<DBFk>>;
+};
+/**
+ * Used to type juggle between {@link FkGatherResult} and its subtypes.
+ */
+export type AsGatherOneResult<T extends FkGatherResult<any, string, ValidFkDepth>> = T extends FkGatherResult<infer DBFk, infer Table, infer D> ? FkGatherOneResult<DBFk, Table, D> : never;
+/**
+ * Used to type juggle between {@link FkGatherResult} and its subtypes.
+ */
+export type AsGatherOneXResult<T extends FkGatherResult<any, string, ValidFkDepth>> = T extends FkGatherResult<infer DBFk, infer Table, infer D> ? FkGatherOneXResult<DBFk, Table, D> : never;
+/**
+ * Used to type juggle between {@link FkGatherResult} and its subtypes.
+ */
+export type AsGatherSomeResult<T extends FkGatherResult<any, string, ValidFkDepth>> = T extends FkGatherResult<infer DBFk, infer Table, infer D> ? FkGatherSomeResult<DBFk, Table, D> : never;
+/**
+ * Creates a new {@link FkGatherOneResult} instance.
+ */
+export declare function newGatherOneResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth>(table: Table, depth: Depth, result: ModelFkInstance<DBFk, Table, Depth> | undefined, models?: ModelCollection<DBWithoutFk<DBFk>>): FkGatherOneResult<DBFk, Table, Depth>;
+/**
+ * Creates a new {@link FkGatherOneXResult} instance.
+ *
+ * Note: it may be counterintuitive, but this function accepts `undefined` as
+ * input. I found it is way more convenient to assert the type once in this
+ * funciton rather than in every caller.
+ */
+export declare function newGatherOneXResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth>(table: Table, depth: Depth, result: ModelFkInstance<DBFk, Table, Depth> | undefined, models?: ModelCollection<DBWithoutFk<DBFk>>): FkGatherOneXResult<DBFk, Table, Depth>;
+/**
+ * Creates a new {@link FkGatherSomeResult} instance.
+ */
+export declare function newGatherSomeResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth>(table: Table, depth: Depth, result: ModelFkInstance<DBFk, Table, Depth>[], models?: ModelCollection<DBWithoutFk<DBFk>>): FkGatherSomeResult<DBFk, Table, Depth>;
+export declare function isGatherResult(result: unknown): result is FkGatherResult<any, any, ValidFkDepth>;
+/**
+ * Checks if `value` is a {@link FkGatherOneResult}.
+ */
+export declare function isGatherOneResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth>(value: FkGatherOneResult<DBFk, Table, Depth> | FkGatherOneXResult<DBFk, Table, Depth>): value is typeof value;
+export declare function isGatherOneResult(value: unknown): value is FkGatherOneResult<any, any, ValidFkDepth>;
+/**
+ * Checks if `value` is a {@link FkGatherOneXResult}.
+ */
+export declare function isGatherOneXResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth>(value: FkGatherOneResult<DBFk, Table, Depth>): value is FkGatherOneXResult<DBFk, Table, Depth>;
+export declare function isGatherOneXResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth>(value: FkGatherOneXResult<DBFk, Table, Depth>): value is typeof value;
+export declare function isGatherOneXResult(value: unknown): value is FkGatherOneXResult<any, any, ValidFkDepth>;
+/**
+ * Checks if `value` is a {@link FkGatherSomeResult}.
+ */
+export declare function isGatherSomeResult<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth>(value: FkGatherSomeResult<DBFk, Table, Depth>): value is typeof value;
+export declare function isGatherSomeResult(value: unknown): value is FkGatherSomeResult<any, any, ValidFkDepth>;
+/**
+ * Asserts that `value` is a {@link FkGatherOneResult}.
+ */
+export declare function assertIsGatherOneResult(value: unknown): asserts value is FkGatherOneResult<any, any, ValidFkDepth>;
+/**
+ * Asserts that `value` is a {@link FkGatherOneXResult}.
+ */
+export declare function assertIsGatherOneXResult(value: unknown): asserts value is FkGatherOneXResult<any, any, ValidFkDepth>;
+/**
+ * Asserts that `value` is a {@link FkGatherSomeResult}.
+ */
+export declare function assertIsGatherSomeResult(value: unknown): asserts value is FkGatherSomeResult<any, any, ValidFkDepth>;

package/dist/types/fks.d.ts

@@ -0,0 +1,111 @@
+import type { ExpressionBuilder, Kysely, OperandExpression, Selectable, SelectType } from 'kysely';
+import type { FKDefsEntry } from './kysely-rizzolver-fk-builder.js';
+import { type KyselyRizzolverBase, type KyselyRizzolverFKs } from './kysely-rizzolver.js';
+import type { ModelCollection } from './model-collection.js';
+import type { OmitByValue } from './type-helpers.js';
+/**
+ * The maximum depth to gather FKs in a single gather operation.
+ *
+ * If you change this, you must also change {@link NextDepth}.
+ */
+export declare const MAX_FK_GATHER_DEPTH = 3;
+/**
+ * For each supported gather depth, assigns the value depth - 1. This is used to recursively construct the types for {@link ModelFkInstance}.
+ *
+ * If you change this, you must also change {@link MAX_FK_GATHER_DEPTH}.
+ */
+type NextDepth = {
+    3: 2;
+    2: 1;
+    1: 0;
+};
+/**
+ * The depth at which FKs can be gathered.
+ *
+ * A depth of 0 = bare model only. This is equivalent to a fetch without gathers.
+ */
+export type ValidFkDepth = (keyof NextDepth & number) | 0;
+type Fk<DB, Referencing extends keyof DB & string, Referenced extends keyof DB & string, IsNullable extends boolean> = {
+    myTable: Referencing;
+    myField: string;
+    otherTable: Referenced;
+    otherField: string;
+    isNullable: IsNullable;
+};
+/**
+ * Omit FK properties from `T`.
+ */
+export type OmitFks<T> = OmitByValue<T, Fk<any, any, any, any>>;
+export declare class ModelFkGatherError extends Error {
+    constructor(table: string, id: number, reason: string);
+}
+/**
+ * A model whose FK fields have not been gathered.
+ */
+export type ModelFkBare<DBFk, Table extends keyof DBFk & string> = {
+    __fkDepth: 0;
+    __table: Table;
+} & Selectable<OmitFks<DBFk[Table]>>;
+/**
+ * A model whose FKs fields have been gathered up to a specific depth.
+ */
+export type ModelFkGathered<DBFk, Table extends keyof DBFk & string, Depth extends Exclude<ValidFkDepth, 0>> = {
+    __fkDepth: Depth;
+    __table: Table;
+} & {
+    [k in keyof DBFk[Table]]: DBFk[Table][k] extends infer U ? U extends Fk<any, any, infer UU, infer NN> ? MaybeNullable<ModelFkInstance<DBFk, UU & keyof DBFk, NextDepth[Depth]>, NN> : SelectType<U> : never;
+};
+export type ModelFkInstance<DBFk, Table extends keyof DBFk & string, Depth extends ValidFkDepth> = Depth extends 0 ? ModelFkBare<DBFk, Table> : ModelFkGathered<DBFk, Table, Exclude<Depth, 0>>;
+type MaybeNullable<T, Nullable extends boolean> = Nullable extends true ? T | null : T;
+export type ModelFkExtractSelectable<DB, Model> = Model extends ModelFkInstance<any, infer Table, any> ? Table extends keyof DB & string ? Selectable<DB[Table]> : never : Model extends undefined ? undefined : Model extends null ? null : never;
+/**
+ * A database schema `DB` with FK fields populated according to `FKDefs`.
+ *
+ * `FKDefs` is of type {@link KyselyRizzolverFKs}.
+ */
+export type DBWithFk<DB, FKDefs extends KyselyRizzolverFKs<DB>> = {
+    [K in keyof DB & string]: DB[K] & {
+        [F in keyof FKDefs[K] & string]: FKDefs[K][F] extends infer U ? U extends FKDefsEntry<DB, any, any, any, any> ? Fk<DB, K, U['otherTable'], U['isNullable']> : never : never;
+    };
+};
+/**
+ * Given a database schema with FKs `DBFK`, returns a database schema without
+ * FKs.
+ */
+export type DBWithoutFk<DBFK> = {
+    [k in keyof DBFK & string]: OmitFks<DBFK[k]>;
+};
+export type GatherOpts<DB, Depth extends ValidFkDepth> = {
+    /**
+     * The depth to gather FKs to. Default: {@link MAX_FK_GATHER_DEPTH}.
+     */
+    depth?: Depth;
+    /**
+     * When an invalid model is found, the gather function can either:
+     * - `throw` - throws a {@link ModelFkGatherError}.
+     * - `omit` - omits the model from the result array.
+     * - `null` - puts `null` values in the result array. This is useful if you
+     *   want to match the input array to the output array by index while still
+     *   indicating that a model is invalid.
+     * - `keep` - keeps the invalid model in the result array.
+     *
+     * An invalid model is a model that has an FK field that is unexpectedly
+     * missing.
+     *
+     * For example, if the model has a `user_id` field whose value is 3 but
+     * there is no user with ID 3 in the database, the model is invalid.
+     *
+     * Default: `omit`
+     */
+    onInvalidModel?: 'omit' | 'throw' | 'null' | 'keep';
+    /**
+     * If provided, will populate this collection with the gathered models.
+     */
+    modelCollection?: ModelCollection<DB>;
+};
+export type NoNullGatherOpts<DB, Depth extends ValidFkDepth> = Omit<GatherOpts<DB, Depth>, 'onInvalidModel'> & {
+    onInvalidModel?: 'omit' | 'throw' | 'keep';
+};
+export type GatherWhereExpression<DB, Table extends keyof DB & string> = (eb: ExpressionBuilder<Pick<DB, Table>, Table>) => OperandExpression<any>;
+export declare function gatherModelFks<DB, FKDefs extends KyselyRizzolverFKs<DB>, KY extends KyselyRizzolverBase<DB, Record<keyof DB & string, any>, FKDefs>, Table extends keyof DB & string, Depth extends ValidFkDepth = typeof MAX_FK_GATHER_DEPTH>(rizzolver: KY, dbInstance: Kysely<DB>, table: Table, where: GatherWhereExpression<DB, Table>, opts?: GatherOpts<DB, Depth>): Promise<(ModelFkInstance<DBWithFk<DB, FKDefs>, Table, Depth> | null)[]>;
+export {};

package/dist/types/index.d.ts

@@ -1,10 +1,16 @@
 export { KyselyRizzolver } from './kysely-rizzolver.js';
-export type { AllTableFields, AnyTableField, KyselyRizzolverBuilderForSchema, KyselyRizzolverBuilderNoSchema, KyDB as RizzolverDB, TableName } from './kysely-rizzolver.js';
-export { assertIsFetchOneResult, assertIsFetchOneXResult, assertIsFetchSomeResult, isFetchOneResult, isFetchOneXResult, isFetchSomeResult, newFetchOneResult, newFetchOneXResult, newFetchSomeResult } from './fetch-result.js';
+export type { KyAllTableFields as AllTableFields, KyAnyTableField as AnyTableField, KyDB as RizzolverDB, KyTableName as TableName } from './kysely-rizzolver.js';
+export { assertIsFetchOneResult, assertIsFetchOneXResult, assertIsFetchSomeResult, isFetchOneResult, isFetchOneXResult, isFetchResult, isFetchSomeResult, newFetchOneResult, newFetchOneXResult, newFetchSomeResult } from './fetch-result.js';
 export type { AsFetchOneResult, AsFetchOneXResult, AsFetchSomeResult, FetchOneResult, FetchOneXResult, FetchResult, FetchSomeResult } from './fetch-result.js';
+export { assertIsGatherOneResult, assertIsGatherOneXResult, assertIsGatherSomeResult, isGatherOneResult, isGatherOneXResult, isGatherResult, isGatherSomeResult, newGatherOneResult, newGatherOneXResult, newGatherSomeResult } from './fk-gather-result.js';
+export type { AsGatherOneResult, AsGatherOneXResult, AsGatherSomeResult, FkGatherOneResult, FkGatherOneXResult, FkGatherResult, FkGatherSomeResult } from './fk-gather-result.js';
+export { MAX_FK_GATHER_DEPTH, ModelFkGatherError } from './fks.js';
+export type { ModelFkBare, ModelFkGathered, ModelFkInstance, ValidFkDepth, GatherWhereExpression } from './fks.js';
+export type { KyselyRizzolverBuilder } from './kysely-rizzolver-builder.js';
+export type { KyselyRizzolverFkBuilder } from './kysely-rizzolver-fk-builder.js';
 export { newSelector } from './selector.js';
-export type { Selector } from './selector.js';
+export type { AnySelector, Selector } from './selector.js';
 export { newQueryBuilder } from './query-builder.js';
-export type { QueryBuilder } from './query-builder.js';
+export type { AnyQueryBuilder, QueryBuilder } from './query-builder.js';
 export { newModelCollection } from './model-collection.js';
 export type { ModelCollection } from './model-collection.js';

package/dist/types/kysely-rizzolver-builder.d.ts

@@ -0,0 +1,17 @@
+import type { Simplify } from 'kysely';
+import { MAX_FK_GATHER_DEPTH, type ValidFkDepth } from './fks.js';
+import { type FkDefsBuilderCallback } from './kysely-rizzolver-fk-builder.js';
+import { KyselyRizzolver, type KyselyRizzolverFKs } from './kysely-rizzolver.js';
+export type KyselyRizzolverBuilder<DB, T extends Partial<Record<keyof DB & string, readonly string[]>>, DefaultGatherDepth extends ValidFkDepth = typeof MAX_FK_GATHER_DEPTH> = T extends Record<keyof DB & string, readonly string[]> ? _KyselyRizzolverBuilder_Valid<DB, T, DefaultGatherDepth> : _KyselyRizzolverBuilder_InProgress<DB, T, DefaultGatherDepth>;
+type _KyselyRizzolverBuilder_Valid<DB, T extends Record<keyof DB & string, readonly string[]>, DefaultGatherDepth extends ValidFkDepth = typeof MAX_FK_GATHER_DEPTH> = {
+    defaultGatherDepth<NewDepth extends ValidFkDepth>(depth: NewDepth): _KyselyRizzolverBuilder_Valid<DB, T, NewDepth>;
+    build<FKDefs extends KyselyRizzolverFKs<DB>>(fkBuilderCb: FkDefsBuilderCallback<DB, FKDefs>): KyselyRizzolver<DB, T, Simplify<FKDefs>, DefaultGatherDepth>;
+    build(): KyselyRizzolver<DB, T, {}, DefaultGatherDepth>;
+};
+type _KyselyRizzolverBuilder_InProgress<DB, T extends Partial<Record<keyof DB & string, readonly string[]>>, DefaultGatherDepth extends ValidFkDepth = typeof MAX_FK_GATHER_DEPTH> = {
+    table<K extends keyof DB & string, U extends readonly (keyof DB[K])[]>(name: K, fields: U & ([keyof DB[K]] extends [U[number]] ? unknown : `Missing key: ${Exclude<keyof DB[K] & string, U[number]>}`)): KyselyRizzolverBuilder<DB, T & {
+        [key in K]: U;
+    }, DefaultGatherDepth>;
+};
+export declare function newKyselyRizzolverBuilder<DB, T extends Partial<Record<keyof DB & string, readonly string[]>>, DefaultGatherDepth extends ValidFkDepth = typeof MAX_FK_GATHER_DEPTH>(fields: T, defaultGatherDepth?: DefaultGatherDepth): KyselyRizzolverBuilder<DB, T>;
+export {};

package/dist/types/kysely-rizzolver-fk-builder.d.ts

@@ -0,0 +1,20 @@
+import { KyselyRizzolverFKs } from './kysely-rizzolver.js';
+import { NumericFields } from './type-helpers.js';
+export type FkDefsBuilderCallback<DB, T> = (builder: KyselyRizzolverFkBuilder<DB, {}>) => T;
+export type KyselyRizzolverFkBuilder<DB, FKDefs extends KyselyRizzolverFKs<DB> = {}> = {
+    add<FromTable extends keyof DB & string, FromField extends Exclude<NumericFields<DB[FromTable]> & string, 'id'>, ToTable extends keyof DB & string, ToField extends NumericFields<DB[ToTable]> & string, FkName extends string, Nullable extends boolean = false>(fromTable: FromTable, fromField: FromField, toTable: ToTable, toField: ToField, fkName: FkName, nullable?: Nullable): KyselyRizzolverFkBuilder<DB, FKDefsAddEntry<DB, FKDefs, FromTable, FromField, ToTable, ToField, FkName, Nullable>>;
+    build(): FKDefs;
+};
+type FKDefsAddEntry<DB, FKDefs extends KyselyRizzolverFKs<DB>, FromTable extends keyof DB & string, FromField extends string, ToTable extends keyof DB & string, ToField extends string, FkName extends string, Nullable extends boolean> = FKDefs & {
+    [K in FromTable]: {
+        [N in FkName]: FKDefsEntry<DB, FromField, ToTable, ToField, Nullable>;
+    };
+};
+export type FKDefsEntry<DB, FromField extends string, ToTable extends keyof DB & string, ToField extends string, Nullable extends boolean> = {
+    myField: FromField;
+    otherTable: ToTable;
+    otherField: ToField;
+    isNullable: Nullable;
+};
+export declare function newKyselyRizzolverFkBuilder<DB, FKDefs extends KyselyRizzolverFKs<DB> = {}>(fkDefs: FKDefs): KyselyRizzolverFkBuilder<DB, FKDefs>;
+export {};