kysely-rizzolver 0.0.2

package/dist/cjs/kysely-rizzolver.d.ts

@@ -0,0 +1,138 @@
+import { type FetchResultFactory } from './fetch-result-factory.js';
+import { type QueryBuilder } from './query-builder.js';
+import { type Selector } from './selector.js';
+import { type ModelCollection } from './model-collection.js';
+export interface KyselyRizzolverBase<DB, T extends Record<keyof DB & string, readonly string[]>> {
+    readonly fields: T;
+    readonly fetches: FetchResultFactory<DB>;
+}
+/**
+ * A {@link KyselyRizzolver} is a class that is used to define the structure of
+ * a database schema.
+ *
+ * It streamlines instatiating type-safe {@link QueryBuilder}s,
+ * {@link Selector}s, {@link ModelCollection}s and {@link FetchResult}s.
+ *
+ * Define a new {@link KyselyRizzolver} using the
+ * {@link KyselyRizzolver.builder|.builderForSchema()} or
+ * {@link KyselyRizzolver.builderNoSchema|.builderNoSchema()}.
+ */
+export declare class KyselyRizzolver<DB, T extends Record<keyof DB & string, readonly string[]>> implements KyselyRizzolverBase<DB, T> {
+    readonly fields: T;
+    readonly fetches: FetchResultFactory<DB>;
+    constructor(fields: T);
+    /**
+     * Intantiates a new {@link Selector} for the given table.
+     */
+    newSelector<Table extends keyof DB & string, Alias extends string>(table: Table, alias: Alias): Selector<this, Table, Alias, AllTableFields<this, Table>>;
+    /**
+     * Instantiates a new {@link QueryBuilder}.
+     */
+    newQueryBuilder(): QueryBuilder<this, {}>;
+    /**
+     * Instantiates a new {@link ModelCollection}.
+     */
+    newModelCollection(): ModelCollection<DB>;
+    /**
+     * Starts building a new {@link KyselyRizzolver} using a builder pattern for
+     * a schema.
+     *
+     * Call {@link KyselyRizzolverBuilderForSchema.table|.table()} for each
+     * table that exists on the `DB` type parameter with all of their column
+     * names as a const array. After all tables have been added, call
+     * {@link KyselyRizzolverBuilderForSchema.build|.build()} to get a new
+     * {@link KyselyRizzolver} instance.
+     *
+     * Example:
+     * ```
+     * const rizzolver = KyselyRizzolver.builderForSchema<DB>()
+     *   .table('user', ['id', 'name', 'email'] as const)
+     *   .table('post', ['id', 'title', 'content', 'authorId'] as const)
+     *   .build();
+     * ```
+     *
+     * Note: The `as const` assertion is necessary for correct type inference.
+     */
+    static builderForSchema<DB>(): KyselyRizzolverBuilderForSchema<DB, {}>;
+    /**
+     * Starts building a new {@link KyselyRizzolver} using a builder pattern
+     * without a schema.
+     *
+     * Call {@link KyselyRizzolverBuilderNoSchema.table|.table()} for each
+     * table with all of their column names as a const array.
+     *
+     * Example:
+     * ```
+     * const rizzolver = KyselyRizzolver.builder()
+     *     .table('user', ['id', 'name', 'email'] as const) // note `as const` is necessary
+     *     .table('post', ['id', 'title', 'content', 'authorId'] as const)
+     *     .build();
+     * ```
+     *
+     * Since this version of builder is schemaless, it cannot infer the value
+     * types for the columns. The `user` type will be `{ id: unknown, name:
+     * unknown, email: unknown }`.
+     *
+     * You may call
+     * {@link KyselyRizzolverBuilderNoSchema.asModel|.asModel\<M\>()}
+     * immediately after the .table() call to provide the types, where `M` is an
+     * type like `{ column1: type1, column2: type2, ... }`.
+     *
+     * Example:
+     * ```
+     * const rizzolver = KyselyRizzolver.builder()
+     *     .table('user', ['id', 'name', 'email'] as const)
+     *     .asModel<{id: number, name: string, email: string}>()
+     *     .table('post', ['id', 'title', 'content', 'authorId'] as const)
+     *     .asModel<{id: number, title: string, content: string, authorId: number}>()
+     *     .build();
+     * ```
+     *
+     * p.s. if your .table() and .asModel() columns differ, it will let you know
+     * at compile time ;)
+     *
+     * Once all tables have been added, call
+     * {@link KyselyRizzolverBuilderNoSchema.build|.build()} to get a new
+     * {@link KyselyRizzolver} instance.
+     */
+    static builderNoSchema(): KyselyRizzolverBuilderNoSchema<{}, null>;
+}
+export type KyselyRizzolverBuilderForSchema<DB, T extends Partial<Record<keyof DB & string, readonly string[]>>> = {
+    table<K extends Exclude<keyof DB & string, keyof T>, 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]>}`)): KyselyRizzolverBuilderForSchema<DB, T & {
+        [key in K]: U;
+    }>;
+    build(): T extends Record<keyof DB & string, readonly string[]> ? KyselyRizzolver<DB, T> : never;
+};
+export type KyselyRizzolverBuilderNoSchema<T extends Record<string, {
+    model: any;
+    columns: readonly string[];
+}>, Last extends keyof T | null> = {
+    table<K extends string, U extends readonly string[]>(name: K, fields: U): KyselyRizzolverBuilderNoSchema<T & {
+        [k in K]: {
+            model: Record<U[number], unknown>;
+            columns: U;
+        };
+    }, K>;
+    asModel<M>(): Last extends keyof T ? keyof M extends T[Last]['columns'][number] ? T[Last]['columns'][number] extends keyof M ? KyselyRizzolverBuilderNoSchema<T & {
+        [k in Last]: {
+            model: M;
+            columns: T[k]['columns'];
+        };
+    }, never> : `column '${Exclude<T[Last]['columns'][number], keyof M & string>}' defined in table() but missing from asModel()` : `column '${Exclude<keyof M & string, T[Last]['columns'][number]>}' defined in asModel() but missing from table()` : `asModel() must be called after table()`;
+    build(): KyselyRizzolver<{
+        [k in keyof T]: T[k]['model'];
+    }, {
+        [k in keyof T]: T[k]['columns'];
+    }>;
+};
+export type KyDB<KY extends KyselyRizzolverBase<any, any>> = KY extends KyselyRizzolverBase<infer DB, any> ? DB : never;
+export type TableName<T extends KyselyRizzolverBase<any, any>> = keyof KyDB<T> & string;
+/**
+ * A union of all the known fields of a table.
+ */
+export type AnyTableField<KY extends KyselyRizzolverBase<any, any>, Table extends TableName<KY>> = keyof KyDB<KY>[Table] & string;
+/**
+ * An array of all the known fields of a table, in a type that is compatible
+ * with that table's ${@link Selectable} type.
+ */
+export type AllTableFields<KY extends KyselyRizzolverBase<any, any>, Table extends TableName<KY>> = KY extends KyselyRizzolverBase<any, infer T> ? T[Table] extends infer U ? U extends readonly AnyTableField<KY, Table>[] ? U : never : never : never;

package/dist/cjs/kysely-rizzolver.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KyselyRizzolver = void 0;
+const fetch_result_factory_js_1 = require("./fetch-result-factory.js");
+const query_builder_js_1 = require("./query-builder.js");
+const selector_js_1 = require("./selector.js");
+const model_collection_js_1 = require("./model-collection.js");
+/**
+ * A {@link KyselyRizzolver} is a class that is used to define the structure of
+ * a database schema.
+ *
+ * It streamlines instatiating type-safe {@link QueryBuilder}s,
+ * {@link Selector}s, {@link ModelCollection}s and {@link FetchResult}s.
+ *
+ * Define a new {@link KyselyRizzolver} using the
+ * {@link KyselyRizzolver.builder|.builderForSchema()} or
+ * {@link KyselyRizzolver.builderNoSchema|.builderNoSchema()}.
+ */
+class KyselyRizzolver {
+    fields;
+    fetches;
+    constructor(fields) {
+        this.fields = fields;
+        this.fetches = (0, fetch_result_factory_js_1.newFetchResultFactory)();
+    }
+    /**
+     * Intantiates a new {@link Selector} for the given table.
+     */
+    newSelector(table, alias) {
+        return (0, selector_js_1.newSelector)(this, table, alias);
+    }
+    /**
+     * Instantiates a new {@link QueryBuilder}.
+     */
+    newQueryBuilder() {
+        return (0, query_builder_js_1.newQueryBuilder)(this);
+    }
+    /**
+     * Instantiates a new {@link ModelCollection}.
+     */
+    newModelCollection() {
+        return (0, model_collection_js_1.newModelCollection)();
+    }
+    /**
+     * Starts building a new {@link KyselyRizzolver} using a builder pattern for
+     * a schema.
+     *
+     * Call {@link KyselyRizzolverBuilderForSchema.table|.table()} for each
+     * table that exists on the `DB` type parameter with all of their column
+     * names as a const array. After all tables have been added, call
+     * {@link KyselyRizzolverBuilderForSchema.build|.build()} to get a new
+     * {@link KyselyRizzolver} instance.
+     *
+     * Example:
+     * ```
+     * const rizzolver = KyselyRizzolver.builderForSchema<DB>()
+     *   .table('user', ['id', 'name', 'email'] as const)
+     *   .table('post', ['id', 'title', 'content', 'authorId'] as const)
+     *   .build();
+     * ```
+     *
+     * Note: The `as const` assertion is necessary for correct type inference.
+     */
+    static builderForSchema() {
+        return _newKyselyRizzolverBuilderForSchema({});
+    }
+    /**
+     * Starts building a new {@link KyselyRizzolver} using a builder pattern
+     * without a schema.
+     *
+     * Call {@link KyselyRizzolverBuilderNoSchema.table|.table()} for each
+     * table with all of their column names as a const array.
+     *
+     * Example:
+     * ```
+     * const rizzolver = KyselyRizzolver.builder()
+     *     .table('user', ['id', 'name', 'email'] as const) // note `as const` is necessary
+     *     .table('post', ['id', 'title', 'content', 'authorId'] as const)
+     *     .build();
+     * ```
+     *
+     * Since this version of builder is schemaless, it cannot infer the value
+     * types for the columns. The `user` type will be `{ id: unknown, name:
+     * unknown, email: unknown }`.
+     *
+     * You may call
+     * {@link KyselyRizzolverBuilderNoSchema.asModel|.asModel\<M\>()}
+     * immediately after the .table() call to provide the types, where `M` is an
+     * type like `{ column1: type1, column2: type2, ... }`.
+     *
+     * Example:
+     * ```
+     * const rizzolver = KyselyRizzolver.builder()
+     *     .table('user', ['id', 'name', 'email'] as const)
+     *     .asModel<{id: number, name: string, email: string}>()
+     *     .table('post', ['id', 'title', 'content', 'authorId'] as const)
+     *     .asModel<{id: number, title: string, content: string, authorId: number}>()
+     *     .build();
+     * ```
+     *
+     * p.s. if your .table() and .asModel() columns differ, it will let you know
+     * at compile time ;)
+     *
+     * Once all tables have been added, call
+     * {@link KyselyRizzolverBuilderNoSchema.build|.build()} to get a new
+     * {@link KyselyRizzolver} instance.
+     */
+    static builderNoSchema() {
+        return _newKyselyRizzolverBuilderNoSchema({}, null);
+    }
+}
+exports.KyselyRizzolver = KyselyRizzolver;
+function _newKyselyRizzolverBuilderForSchema(fields) {
+    return {
+        table(tableName, tableFields) {
+            return _newKyselyRizzolverBuilderForSchema({
+                ...fields,
+                [tableName]: tableFields
+            });
+        },
+        build() {
+            return new KyselyRizzolver(fields);
+        }
+    };
+}
+function _newKyselyRizzolverBuilderNoSchema(fields, last) {
+    return {
+        table(tableName, tableFields) {
+            return _newKyselyRizzolverBuilderNoSchema({
+                ...fields,
+                [tableName]: {
+                    model: null,
+                    columns: tableFields
+                }
+            }, tableName);
+        },
+        asModel() {
+            if (!last) {
+                throw new Error('asModel() must be called after table()');
+            }
+            return _newKyselyRizzolverBuilderNoSchema(fields, null);
+        },
+        build() {
+            return new KyselyRizzolver(Object.fromEntries(Object.entries(fields).map((entry) => [entry[0], entry[1].columns])));
+        }
+    };
+}

package/dist/cjs/model-collection.d.ts

@@ -0,0 +1,26 @@
+import type { Selectable } from 'kysely';
+/**
+ * A {@link ModelCollection} is a collection of {@link Selectable} instances,
+ * grouped by their table name and keyed by their id.
+ *
+ * This type purposefully discards specific type information to make it simpler
+ * to create and pass it around without worrying about type compatibility and
+ * casting.
+ *
+ * It does not preserve information on which tables are present in the
+ * collection, or which fields on their {@link Selectable}s have been gathered.
+ *
+ * If you need to preserve this information, you should just pass the result of
+ * the {@link QueryBuilder.run} method where needed. However, doing this is not
+ * recommended, as your types can easily become too nested to the point where
+ * TypeScript can't infer them correctly.
+ */
+export type ModelCollection<DB> = {
+    add<Table extends keyof DB & string>(table: Table, selectable?: Selectable<DB[Table]>): ModelCollection<DB>;
+    get collection(): Data<DB>;
+};
+export declare function newModelCollection<DB>(init?: Data<DB>): ModelCollection<DB>;
+type Data<DB> = {
+    [M in keyof DB & string]?: Partial<Record<number, Selectable<DB[M]>>>;
+};
+export {};

package/dist/cjs/model-collection.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newModelCollection = newModelCollection;
+function newModelCollection(init = {}) {
+    const collection = { ...init };
+    return {
+        add(table, selectable) {
+            if (!selectable ||
+                !('id' in selectable) ||
+                !selectable.id ||
+                typeof selectable.id !== 'number') {
+                return this;
+            }
+            if (!(table in collection)) {
+                collection[table] = {};
+            }
+            collection[table][selectable.id] = selectable;
+            return this;
+        },
+        get collection() {
+            return collection;
+        }
+    };
+}

package/dist/cjs/query-builder.d.ts

@@ -0,0 +1,156 @@
+import { type FetchOneResult, type FetchOneXResult, type FetchSomeResult } from './fetch-result.js';
+import type { AllTableFields, AnyTableField, KyDB, KyselyRizzolverBase, TableName } from './kysely-rizzolver.js';
+import { type Selector, type SelectorResult } from './selector.js';
+import { type ModelCollection } from './model-collection.js';
+import type { UnionToTuple } from './type-helpers.js';
+/**
+ * {@link QueryBuilder} makes it easier to work with multiple tables in a query
+ * and parse the results into their respective Kysely {@link Selectable}
+ * instances in a type-safe way.
+ *
+ * It works by adding {@link Selector}s using the {@link QueryBuilder.add}
+ * method, followed by a call to {@link QueryBuilder.run} to parse the results
+ * of the query using a simple builder pattern.
+ */
+export interface QueryBuilder<KY extends KyselyRizzolverBase<any, any>, T extends Data<KY>> {
+    /**
+     * The record of {@link Selector} this query builder has, keyed by their alias.
+     */
+    selectors: T;
+    /**
+     * Given a {@link Selector} alias `k`, Gets a `"table as alias"` expression
+     * for that selector.
+     *
+     * This is a shorthand for `this.selectors[k].selectTable`
+     *
+     * Example:
+     * ```
+     * const qb = rizzolver
+     *     .newQueryBuilder()
+     *     .add('user', 'u');
+     *
+     * const userTable = qb.table('u'); // => 'user as u'
+     * ```
+     */
+    table<K extends keyof T>(tableAlias: K): T[K]['selectTable'];
+    /**
+     * Gets a const array of all the fields of all the {@link Selector}s this
+     * query builder has. The order is arbitrary and should not be relied upon.
+     */
+    allFields: FieldsOf<T, keyof T>;
+    /**
+     * Given one of more {@link Selector} aliases, gets an array of
+     * `"table.field as alias"` expressions for all of their fields.
+     *
+     * Example:
+     * ```
+     * const qb = rizzolver
+     *     .newQueryBuilder()
+     *     .add('user', 'u')
+     *     .add('address', 'a');
+     *
+     * const userFields = qb.fieldsOf('u');
+     *   // => ['u.id as _u_id', 'u.first_name as _u_first_name', 'u.last_name as _u_last_name']
+     * const addressFields = qb.fieldsOf('a');
+     *   // => ['a.id as _a_id', 'a.street as _a_street', 'a.city as _a_city']
+     * const allFields = qb.fieldsOf('u', 'a');
+     *   // equivalent to [...qb.fieldsOf('u'), ...qb.fieldsOf('a')]
+     *   // => ['u.id as _u_id', 'u.first_name as _u_first_name', 'u.last_name as _u_last_name', 'a.id as _a_id', 'a.street as _a_street', 'a.city as _a_city']
+     * ```
+     */
+    fieldsOf<K extends keyof T>(...tableAliases: K[]): FieldsOf<T, K>;
+    field<K extends keyof T & string, F extends T[K]['input']['tableFields']>(field: `${K}.${F}`): {
+        value: `_${K}_${F}`;
+        from<A extends string>(alias: A): `${A}._${K}_${F}`;
+    };
+    /**
+     * Adds a new {@link Selector} to the query builder.
+     */
+    add<Table extends TableName<KY>, Alias extends string, Keys extends readonly AnyTableField<KY, Table>[] = AllTableFields<KY, Table>>(selector: Selector<KY, Table, Alias, Keys>): MoreData<KY, T, Table, Alias, Keys>;
+    /**
+     * Adds a new {@link Selector} to the query builder.
+     */
+    add<Table extends TableName<KY>, Alias extends string, Keys extends readonly AnyTableField<KY, Table>[] = AllTableFields<KY, Table>>(table: Table, alias: Alias, keys?: Keys): MoreData<KY, T, Table, Alias, Keys>;
+    /**
+     * Parses the results of a query into the {@link Selectable} instances
+     * defined by the {@link Selector}s this query builder has.
+     *
+     * Example:
+     * ```
+     * const result = await rizzolver
+     *     .newQueryBuilder()
+     *     .add('user', 'u')
+     *     .add('address', 'a')
+     *     .run((qb) =>
+     *         db
+     *             .selectFrom(qb.table('u'))
+     *             .leftJoin(qb.table('a'), (join) => join.onRef('u.address_id', '=', 'a.id'))
+     *             .select(qb.allFields)
+     *             .execute()
+     *     );
+     *
+     * const parsedRows = result.rows;
+     *   // => [
+     *   //      {
+     *   //        row: { id: 1, first_name: 'John', last_name: 'Doe' },
+     *   //        selectors: {
+     *   //          u: { id: 1, first_name: 'John', last_name: 'Doe' },
+     *   //          a: { id: 10, street: '123 Main St', city: 'Springfield' }
+     *   //        }
+     *   //      },
+     *   //      {
+     *   //        row: { id: 2, first_name: 'Jane', last_name: 'Smith' },
+     *   //        selectors: {
+     *   //          u: { id: 2, first_name: 'Jane', last_name: 'Smith' },
+     *   //          a: undefined, // Jane has no address
+     *   //        }
+     *   //      },
+     *   //    ]
+     * ```
+     *
+     * To make it easier to consume the results, the query builder also provides
+     * methods to create {@link FetchOneResult}, {@link FetchOneXResult}, and
+     * {@link FetchSomeResult} instances for each selector by its alias:
+     * ```
+     * const result = await rizzolver
+     *     .newQueryBuilder()
+     *     .add('user', 'u')
+     *     .run(...)
+     *     .newFetchOneResult('u'); // => FetchOneResult<DB, 'user', Selectable<User>>
+     * ```
+     */
+    run<Row extends Record<string, unknown>>(rows: Row[]): DeferredResult<KY, T, Row>;
+    run<Row extends Record<string, unknown>>(callback: (qb: this) => Promise<Row[]>): DeferredResult<KY, T, Row>;
+}
+export declare function newQueryBuilder<KY extends KyselyRizzolverBase<any, any>>(rizzolver: KY): QueryBuilder<KY, {}>;
+type Data<KY extends KyselyRizzolverBase<any, any>> = {
+    [alias: string]: Selector<KY, any, string, any>;
+};
+type MoreData<KY extends KyselyRizzolverBase<any, any>, T extends Data<KY>, Table extends TableName<KY>, A extends string, K extends readonly AnyTableField<KY, Table>[] = AllTableFields<KY, Table>> = QueryBuilder<KY, T & {
+    [k in A]: Selector<KY, Table, A, K>;
+}>;
+interface DeferredResult<KY extends KyselyRizzolverBase<any, any>, T extends Data<KY>, Row extends Record<string, unknown>> extends Promise<Result<KY, T, Row>> {
+    newFetchOneResult<K extends keyof T>(selectorAlias: K): Promise<FetchOneResult<KyDB<KY>, T[K]['input']['table'], SelectorResult<KY, any, T[K]['input']['table'], T[K]['input']['tableFields']>[number]['model'] & {}>>;
+    newFetchOneXResult<K extends keyof T>(selectorAlias: K): Promise<FetchOneXResult<KyDB<KY>, T[K]['input']['table'], SelectorResult<KY, any, T[K]['input']['table'], T[K]['input']['tableFields']>[number]['model'] & {}>>;
+    newFetchSomeResult<K extends keyof T>(selectorAlias: K): Promise<FetchSomeResult<KyDB<KY>, T[K]['input']['table'], SelectorResult<KY, any, T[K]['input']['table'], T[K]['input']['tableFields']>[number]['model'] & {}>>;
+}
+type Result<KY extends KyselyRizzolverBase<any, any>, T extends Data<KY>, Row extends Record<string, unknown>> = {
+    first: {
+        row: Row;
+        selectors: {
+            [k in keyof T]: ReturnType<T[k]['select']>[number]['model'];
+        };
+    } | undefined;
+    rows: {
+        row: Row;
+        selectors: {
+            [k in keyof T]: ReturnType<T[k]['select']>[number]['model'];
+        };
+    }[];
+    models: ModelCollection<KyDB<KY>>;
+    newFetchOneResult<K extends keyof T>(selectorAlias: K): FetchOneResult<KyDB<KY>, T[K]['input']['table'], SelectorResult<KY, any, T[K]['input']['table'], T[K]['input']['tableFields']>[number]['model'] & {}>;
+    newFetchOneXResult<K extends keyof T>(selectorAlias: K): FetchOneXResult<KyDB<KY>, T[K]['input']['table'], SelectorResult<KY, any, T[K]['input']['table'], T[K]['input']['tableFields']>[number]['model'] & {}>;
+    newFetchSomeResult<K extends keyof T>(selectorAlias: K): FetchSomeResult<KyDB<KY>, T[K]['input']['table'], SelectorResult<KY, any, T[K]['input']['table'], T[K]['input']['tableFields']>[number]['model'] & {}>;
+};
+type FieldsOf<T, K extends keyof T> = UnionToTuple<Pick<T, K> extends infer U ? U[keyof U] extends infer S ? S extends Selector<infer KY, infer Table, infer Alias, infer Keys> ? Selector<KY, Table, Alias, Keys>['selectFields'][number] : never : never : never>;
+export {};

package/dist/cjs/query-builder.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newQueryBuilder = newQueryBuilder;
+const fetch_result_js_1 = require("./fetch-result.js");
+const selector_js_1 = require("./selector.js");
+const model_collection_js_1 = require("./model-collection.js");
+function newQueryBuilder(rizzolver) {
+    const selectors = {};
+    return {
+        selectors,
+        table(tableAlias) {
+            return selectors[tableAlias].selectTable;
+        },
+        allFields: Object.values(selectors)
+            .map((selector) => selector.selectFields)
+            .flat(),
+        fieldsOf(...tableAliases) {
+            return tableAliases.map((alias) => selectors[alias].selectFields).flat();
+        },
+        field(field) {
+            const [t, f] = field.split('.');
+            const alias = `_${t}_${f}`;
+            return {
+                value: alias,
+                from(a) {
+                    return `${a}.${alias}`;
+                }
+            };
+        },
+        add(selectorOrTable, alias, keys) {
+            let selector;
+            if (typeof selectorOrTable === 'string') {
+                if (!alias) {
+                    throw new Error('Must provide an alias when calling QueryBuilder.add with a table name');
+                }
+                selector = (0, selector_js_1.newSelector)(rizzolver, selectorOrTable, alias, (keys ?? rizzolver.fields[selectorOrTable]));
+            }
+            else {
+                if (alias || keys) {
+                    throw new Error('Must not provide an alias or keys when calling QueryBuilder.add with a selector');
+                }
+                selector = selectorOrTable;
+            }
+            selectors[selector.input.alias] = selector;
+            return this;
+        },
+        run(rowsOrCallback) {
+            const promise = (async () => {
+                const rows = Array.isArray(rowsOrCallback) ? rowsOrCallback : await rowsOrCallback(this);
+                const modelCollection = (0, model_collection_js_1.newModelCollection)();
+                const selectorResults = {};
+                for (const [alias, selector] of Object.entries(selectors)) {
+                    const selectorResult = selector.select(rows);
+                    for (const { model } of selectorResult) {
+                        if (!model) {
+                            continue;
+                        }
+                        modelCollection.add(selector.input.table, model);
+                    }
+                    selectorResults[alias] = selectorResult;
+                }
+                const result = [];
+                for (let i = 0; i < rows.length; i++) {
+                    const row = rows[i];
+                    const selectedModels = {};
+                    for (const [alias, selectorResult] of Object.entries(selectorResults)) {
+                        selectedModels[alias] = selectorResult[i].model;
+                    }
+                    result.push({ row, selectors: selectedModels });
+                }
+                return {
+                    first: result.length ? result[0] : undefined,
+                    rows: result,
+                    models: modelCollection,
+                    newFetchOneResult(selectorAlias) {
+                        return (0, fetch_result_js_1.newFetchOneResult)(selectors[selectorAlias].input.table, (result.length ? result[0] : undefined)?.selectors[selectorAlias], modelCollection);
+                    },
+                    newFetchOneXResult(selectorAlias) {
+                        return (0, fetch_result_js_1.newFetchOneXResult)(selectors[selectorAlias].input.table, (result.length ? result[0] : undefined)?.selectors[selectorAlias], modelCollection);
+                    },
+                    newFetchSomeResult(selectorAlias) {
+                        return (0, fetch_result_js_1.newFetchSomeResult)(selectors[selectorAlias].input.table, result.map((r) => r.selectors[selectorAlias]).filter((r) => !!r), modelCollection);
+                    }
+                };
+            })();
+            promise.newFetchOneResult = (selectorAlias) => promise.then((result) => result.newFetchOneResult(selectorAlias));
+            promise.newFetchOneXResult = (selectorAlias) => promise.then((result) => result.newFetchOneXResult(selectorAlias));
+            promise.newFetchSomeResult = (selectorAlias) => promise.then((result) => result.newFetchSomeResult(selectorAlias));
+            return promise;
+        }
+    };
+}

package/dist/cjs/selector.d.ts

@@ -0,0 +1,72 @@
+import type { Selectable } from 'kysely';
+import type { AllTableFields, AnyTableField, KyDB, KyselyRizzolverBase, TableName } from './kysely-rizzolver.js';
+/**
+ * A {@link Selector} makes it easier to build select expressions for a
+ * table in a type-safe way. It can process the results of queries into
+ * Kysely's {@link Selectable} instances.
+ *
+ * {@link Selector} is a low level utility that is used by
+ * {@link QueryBuilder} to work with multiple selectors.
+ */
+export type Selector<KY extends KyselyRizzolverBase<any, any>, Table extends TableName<KY>, Alias extends string, TableFields extends readonly AnyTableField<KY, Table>[] = AllTableFields<KY, Table>> = {
+    input: {
+        /**
+         * The table name that's being selected from.
+         */
+        table: Table;
+        /**
+         * The alias for the table.
+         */
+        alias: Alias;
+        /**
+         * An array of the fields to be selected from the table.
+         *
+         * This can be omitted, in which case it will default to all the fields of
+         * the table.
+         */
+        tableFields: TableFields;
+    };
+    /**
+     * A `"table as alias"` expression for using in select expressions.
+     */
+    selectTable: TableAlias<KY, Table, Alias>;
+    /**
+     * An array of `"table.field as alias"` expressions for using in select expressions.
+     */
+    selectFields: FieldsAsAliases<Alias, TableFields>;
+    /**
+     * A utility method that allows you to reference a specific field.
+     */
+    field<Field extends TableFields[number]>(field: Field): {
+        str: `_${Alias}_${Field}`;
+        /**
+         * A utility method that allows you to reference the field from a different table alias.
+         *
+         * This is useful if you need to reference the field from a subquery for example.
+         */
+        from<A extends string>(alias: A): `${A}.${FieldAlias<Alias, Field>}`;
+    };
+    /**
+     * Parses the results of a query into the model defined by this selector for each row.
+     *
+     * Example:
+     * ```
+     * const selector = newSelector('user', 'u');
+     * const data = await db.selectFrom(selector.tableAlias).selectAll().execute();
+     * const parsed = selector.select(data);
+     *   // => type would be { row: Row, model: Selectable<User> | undefined }[]
+     * ```
+     */
+    select<Row extends Record<string, unknown>>(rows: Row[]): SelectorResult<KY, Row, Table, TableFields>;
+};
+export declare function newSelector<KY extends KyselyRizzolverBase<any, any>, Table extends TableName<KY>, Alias extends string>(rizzolver: KY, tableName: Table, alias: Alias): Selector<KY, Table, Alias, AllTableFields<KY, Table>>;
+export declare function newSelector<KY extends KyselyRizzolverBase<any, any>, Table extends TableName<KY>, Alias extends string, Keys extends readonly AnyTableField<KY, Table>[]>(rizzolver: KY, tableName: Table, alias: Alias, keys?: Keys): Selector<KY, Table, Alias, Keys>;
+export type SelectorResult<KY extends KyselyRizzolverBase<any, any>, Row extends Record<string, unknown>, Table extends TableName<KY>, TableFields extends readonly AnyTableField<KY, Table>[] = AllTableFields<KY, Table>> = {
+    row: Row;
+    model: Selectable<Pick<KyDB<KY>[Table], TableFields[number]>> | undefined;
+}[];
+type TableAlias<KY extends KyselyRizzolverBase<any, any>, Table extends TableName<KY>, Alias extends string> = `${Table} as ${Alias}`;
+type FieldAlias<TableAlias extends string, TableField extends string> = `_${TableAlias}_${TableField}`;
+type FieldAsAlias<TableAlias extends string, TableField extends string> = `${TableAlias}.${TableField} as ${FieldAlias<TableAlias, TableField>}`;
+type FieldsAsAliases<TableAlias extends string, TableFields extends readonly string[]> = TableFields extends readonly [infer TableField extends string, ...infer Tail extends string[]] ? [FieldAsAlias<TableAlias, TableField>, ...FieldsAsAliases<TableAlias, Tail>] : [];
+export {};