kysely-rizzolver 0.0.2

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

@@ -0,0 +1,111 @@
+import type { Selectable } from 'kysely';
+import type { ModelCollection } from './model-collection.js';
+/**
+ * A {@link FetchResult} is a result of a fetch operation. It can be one of
+ * three types:
+ * - {@link FetchOneResult} - A result of a fetch operation that is expected to
+ *   return up to one row,
+ * - {@link FetchOneXResult} - A result of a fetch operation that is expected to
+ *   return exactly one row,
+ * - {@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>;
+/**
+ * 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> = {
+    fetchType: 'fetchOne';
+    table: T;
+    result: R | undefined;
+    models?: ModelCollection<DB>;
+    /**
+     * Returns this result as a {@link FetchOneXResult}.
+     *
+     * @throws If the result is null or undefined.
+     */
+    asFetchOneX(): FetchOneXResult<DB, T, R & {}>;
+};
+/**
+ * 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]>>> = {
+    fetchType: 'fetchOne';
+    table: T;
+    result: R;
+    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}.
+     */
+    asFetchOneX(): FetchOneXResult<DB, T, R>;
+};
+/**
+ * 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]>>> = {
+    fetchType: 'fetchSome';
+    table: T;
+    result: R[];
+    models?: ModelCollection<DB>;
+};
+/**
+ * Used to type juggle between {@link FetchResult} and its subtypes.
+ */
+export type AsFetchOneResult<T extends FetchResult<any, string, Selectable<any>>> = T extends FetchResult<infer DB, infer T, infer R> ? FetchOneResult<DB, T, R> : never;
+/**
+ * Used to type juggle between {@link FetchResult} and its subtypes.
+ */
+export type AsFetchOneXResult<T extends FetchResult<any, string, Selectable<any>>> = T extends FetchResult<infer DB, infer T, infer R> ? FetchOneXResult<DB, T, R> : never;
+/**
+ * Used to type juggle between {@link FetchResult} and its subtypes.
+ */
+export type AsFetchSomeResult<T extends FetchResult<any, string, Selectable<any>>> = T extends FetchResult<infer DB, infer T, infer R> ? FetchSomeResult<DB, T, R> : never;
+/**
+ * Creates a new {@link FetchOneResult} instance.
+ */
+export declare function newFetchOneResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>>>(table: T, result: R | undefined, models?: ModelCollection<DB>): FetchOneResult<DB, T, R>;
+/**
+ * Creates a new {@link FetchOneXResult} 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 newFetchOneXResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>>>(table: T, result: R | undefined, models?: ModelCollection<DB>): FetchOneXResult<DB, T, R>;
+/**
+ * Creates a new {@link FetchSomeResult} instance.
+ */
+export declare function newFetchSomeResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>>>(table: T, result: R[], models?: ModelCollection<DB>): FetchSomeResult<DB, T, R>;
+export declare function isFetchResult(result: unknown): result is FetchResult<any, any, any>;
+/**
+ * Checks if `value` is a {@link FetchOneResult}.
+ */
+export declare function isFetchOneResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>>>(value: FetchOneResult<DB, T, R> | FetchOneXResult<DB, T, R>): value is typeof value;
+export declare function isFetchOneResult(value: unknown): value is FetchOneResult<any, string, Selectable<any>>;
+/**
+ * Checks if `value` is a {@link FetchOneXResult}.
+ */
+export declare function isFetchOneXResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>>>(value: FetchOneResult<DB, T, R>): value is FetchOneXResult<DB, T, R>;
+export declare function isFetchOneXResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>>>(value: FetchOneXResult<DB, T, R>): value is typeof value;
+export declare function isFetchOneXResult(value: unknown): value is FetchOneXResult<any, string, Selectable<any>>;
+/**
+ * Checks if `value` is a {@link FetchSomeResult}.
+ */
+export declare function isFetchSomeResult<DB, T extends keyof DB & string, R extends Partial<Selectable<DB[T]>>>(value: FetchSomeResult<DB, T, R>): value is typeof value;
+export declare function isFetchSomeResult(value: unknown): value is FetchSomeResult<any, string, Selectable<any>>;
+/**
+ * Asserts that `value` is a {@link FetchOneResult}.
+ */
+export declare function assertIsFetchOneResult(value: unknown): asserts value is FetchOneResult<any, string, Selectable<any>>;
+/**
+ * Asserts that `value` is a {@link FetchOneXResult}.
+ */
+export declare function assertIsFetchOneXResult(value: unknown): asserts value is FetchOneXResult<any, string, Selectable<any>>;
+/**
+ * Asserts that `value` is a {@link FetchSomeResult}.
+ */
+export declare function assertIsFetchSomeResult(value: unknown): asserts value is FetchSomeResult<any, string, Selectable<any>>;

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+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 { AsFetchOneResult, AsFetchOneXResult, AsFetchSomeResult, FetchOneResult, FetchOneXResult, FetchResult, FetchSomeResult } from './fetch-result.js';
+export { newSelector } from './selector.js';
+export type { Selector } from './selector.js';
+export { newQueryBuilder } from './query-builder.js';
+export type { QueryBuilder } from './query-builder.js';
+export { newModelCollection } from './model-collection.js';
+export type { ModelCollection } from './model-collection.js';

package/dist/types/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/types/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/types/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/types/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 {};

package/dist/types/type-helpers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * I can't explain this.
+ *
+ * I badgered ChatGPT until it worked. it probably just referenced type-fest.
+ */
+type LastInUnion<U> = (U extends any ? () => U : never) extends infer F ? (F extends any ? (k: F) => void : never) extends (k: infer I) => void ? I extends () => infer R ? R : never : never : never;
+/**
+ * Recursively converts a union type to a tuple by splitting it into its head and tail.
+ */
+export type UnionToTuple<U, Last = LastInUnion<U>> = [U] extends [never] ? [] : [...UnionToTuple<Exclude<U, Last>>, Last];
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "kysely-rizzolver",
+	"version": "0.0.2",
+	"description": "Complex Kysely queries, maximum rizz, type-safe every time.",
+	"author": "YLivay",
+	"repository": {
+		"type": "git",
+		"url": "git://github.com/YLivay/kysely-rizzolver.git"
+	},
+	"license": "MIT",
+	"main": "dist/cjs/index.js",
+	"module": "dist/esm/index.js",
+	"exports": {
+		".": {
+			"import": "./dist/esm/index.js",
+			"require": "./dist/cjs/index.js",
+			"default": "./dist/cjs/index.js"
+		}
+	},
+	"scripts": {
+		"clean": "rm -rf dist",
+		"build": "npm run clean && (npm run build:esm & npm run build:cjs)",
+		"build:esm": "tsc -p tsconfig.json && echo '{\"type\": \"module\"}' > dist/esm/package.json",
+		"build:cjs": "tsc -p tsconfig-cjs.json"
+	},
+	"peerDependencies": {
+		"kysely": "^0.27.5"
+	},
+	"devDependencies": {
+		"typescript": "^5.7.3"
+	}
+}