kysely-rizzolver 0.0.2

package/dist/cjs/selector.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newSelector = newSelector;
+function newSelector(rizzolver, tableName, alias, keys) {
+    const effectiveKeys = (keys ?? rizzolver.fields[tableName]);
+    const tableAlias = `${tableName} as ${alias}`;
+    const fields = effectiveKeys.map((field) => `${alias}.${field} as _${alias}_${field}`);
+    function _rowToModel(result) {
+        if (!result || !result[`_${alias}_id`]) {
+            return undefined;
+        }
+        const model = {};
+        for (const field of effectiveKeys) {
+            const aliasedField = `_${alias}_${field}`;
+            model[field] = result[aliasedField] ?? undefined;
+        }
+        return model;
+    }
+    const selector = {
+        input: {
+            table: tableName,
+            alias,
+            tableFields: effectiveKeys
+        },
+        selectTable: tableAlias,
+        selectFields: fields,
+        field(field) {
+            return {
+                str: `_${alias}_${field}`,
+                from(table) {
+                    return `${table}._${alias}_${field}`;
+                }
+            };
+        },
+        select(rows) {
+            const data = [];
+            for (const row of rows) {
+                const model = _rowToModel(row);
+                data.push({ row, model });
+            }
+            return data;
+        }
+    };
+    return selector;
+}

package/dist/cjs/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/dist/cjs/type-helpers.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/fetch-result-factory.js

@@ -0,0 +1,85 @@
+import { assertIsFetchOneResult, assertIsFetchOneXResult, assertIsFetchSomeResult, isFetchOneResult, isFetchOneXResult, isFetchSomeResult, newFetchOneResult, newFetchOneXResult, newFetchSomeResult } from './fetch-result.js';
+import { newModelCollection } from './model-collection.js';
+export function newFetchResultFactory() {
+    return {
+        /**
+         * Creates a new {@link FetchOneResult} instance.
+         */
+        newFetchOne(table, result, models) {
+            models ??= newModelCollection();
+            if (result) {
+                models.add(table, result);
+            }
+            return newFetchOneResult(table, result, models);
+        },
+        /**
+         * 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.
+         */
+        newFetchOneX(table, result, models) {
+            models ??= newModelCollection();
+            if (result) {
+                models.add(table, result);
+            }
+            return newFetchOneXResult(table, result, models);
+        },
+        /**
+         * Creates a new {@link FetchSomeResult} instance.
+         */
+        newFetchSome(table, result, models) {
+            models ??= newModelCollection();
+            for (const item of result) {
+                models.add(table, item);
+            }
+            return newFetchSomeResult(table, result, models);
+        },
+        /**
+         * Checks if a {@link FetchResult} is a {@link FetchOneResult}.
+         */
+        isFetchOne(table, result) {
+            return isFetchOneResult(result) && result.table === table;
+        },
+        /**
+         * Checks if a {@link FetchResult} is a {@link FetchOneXResult}.
+         */
+        isFetchOneX(table, result) {
+            return isFetchOneXResult(result) && result.table === table;
+        },
+        /**
+         * Checks if a {@link FetchResult} is a {@link FetchSomeResult}.
+         */
+        isFetchSome(table, result) {
+            return isFetchSomeResult(result) && result.table === table;
+        },
+        /**
+         * Asserts that a {@link FetchResult} is a {@link FetchOneResult}.
+         */
+        assertIsFetchOne(table, result) {
+            assertIsFetchOneResult(result);
+            if (result.table !== table) {
+                throw new Error(`Expected a fetchOne result for table ${table}`);
+            }
+        },
+        /**
+         * Asserts that a {@link FetchResult} is a {@link FetchOneXResult}.
+         */
+        assertIsFetchOneX(table, result) {
+            assertIsFetchOneXResult(result);
+            if (result.table !== table) {
+                throw new Error(`Expected a fetchOne result with a non-null non for table ${table}`);
+            }
+        },
+        /**
+         * Asserts that a {@link FetchResult} is a {@link FetchSomeResult}.
+         */
+        assertIsFetchSome(table, result) {
+            assertIsFetchSomeResult(result);
+            if (result.table !== table) {
+                throw new Error(`Expected a fetchSome result for table ${table}`);
+            }
+        }
+    };
+}

package/dist/esm/fetch-result.js

@@ -0,0 +1,105 @@
+/**
+ * Creates a new {@link FetchOneResult} instance.
+ */
+export function newFetchOneResult(table, result, models) {
+    const ref = { value: null };
+    const me = {
+        fetchType: 'fetchOne',
+        table,
+        result,
+        models,
+        asFetchOneX() {
+            if (!me.result) {
+                throw new Error('Expected a fetchOneX result');
+            }
+            return ref.value;
+        }
+    };
+    ref.value = me;
+    return me;
+}
+/**
+ * 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 function newFetchOneXResult(table, result, models) {
+    if (!result) {
+        throw new Error('Expected a fetchOneX result');
+    }
+    const ref = { value: null };
+    const me = {
+        fetchType: 'fetchOne',
+        table,
+        result,
+        models,
+        asFetchOneX() {
+            return ref.value;
+        }
+    };
+    ref.value = me;
+    return me;
+}
+/**
+ * Creates a new {@link FetchSomeResult} instance.
+ */
+export function newFetchSomeResult(table, result, models) {
+    return {
+        fetchType: 'fetchSome',
+        table,
+        result,
+        models
+    };
+}
+export function isFetchResult(result) {
+    return (!!result &&
+        typeof result === 'object' &&
+        'fetchType' in result &&
+        !!result.fetchType &&
+        typeof result.fetchType === 'string' &&
+        'table' in result &&
+        !!result.table &&
+        typeof result.table === 'string' &&
+        'result' in result &&
+        (result.result === undefined ||
+            typeof result.result === 'object' ||
+            (Array.isArray(result.result) && result.result.every((r) => !!r && typeof r === 'object'))));
+}
+export function isFetchOneResult(value) {
+    return isFetchResult(value) && value.fetchType === 'fetchOne' && !Array.isArray(value.result);
+}
+export function isFetchOneXResult(value) {
+    return (isFetchResult(value) &&
+        value.fetchType === 'fetchOne' &&
+        !Array.isArray(value.result) &&
+        !!value.result);
+}
+export function isFetchSomeResult(value) {
+    return isFetchResult(value) && value.fetchType === 'fetchSome' && Array.isArray(value.result);
+}
+/**
+ * Asserts that `value` is a {@link FetchOneResult}.
+ */
+export function assertIsFetchOneResult(value) {
+    if (!isFetchOneResult(value)) {
+        throw new Error('Expected a fetchOne result');
+    }
+}
+/**
+ * Asserts that `value` is a {@link FetchOneXResult}.
+ */
+export function assertIsFetchOneXResult(value) {
+    if (!isFetchOneXResult(value)) {
+        throw new Error('Expected a fetchOne result with a non-null, non undefined result');
+    }
+}
+/**
+ * Asserts that `value` is a {@link FetchSomeResult}.
+ */
+export function assertIsFetchSomeResult(value) {
+    if (!isFetchSomeResult(value)) {
+        throw new Error('Expected a fetchSome result');
+    }
+}

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { KyselyRizzolver } from './kysely-rizzolver.js';
+export { assertIsFetchOneResult, assertIsFetchOneXResult, assertIsFetchSomeResult, isFetchOneResult, isFetchOneXResult, isFetchSomeResult, newFetchOneResult, newFetchOneXResult, newFetchSomeResult } from './fetch-result.js';
+export { newSelector } from './selector.js';
+export { newQueryBuilder } from './query-builder.js';
+export { newModelCollection } from './model-collection.js';

package/dist/esm/kysely-rizzolver.js

@@ -0,0 +1,143 @@
+import { newFetchResultFactory } from './fetch-result-factory.js';
+import { newQueryBuilder as kyNewQueryBuilder } from './query-builder.js';
+import { newSelector as kyNewSelector } from './selector.js';
+import { newModelCollection as kyNewModelCollection } from './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()}.
+ */
+export class KyselyRizzolver {
+    fields;
+    fetches;
+    constructor(fields) {
+        this.fields = fields;
+        this.fetches = newFetchResultFactory();
+    }
+    /**
+     * Intantiates a new {@link Selector} for the given table.
+     */
+    newSelector(table, alias) {
+        return kyNewSelector(this, table, alias);
+    }
+    /**
+     * Instantiates a new {@link QueryBuilder}.
+     */
+    newQueryBuilder() {
+        return kyNewQueryBuilder(this);
+    }
+    /**
+     * Instantiates a new {@link ModelCollection}.
+     */
+    newModelCollection() {
+        return kyNewModelCollection();
+    }
+    /**
+     * 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);
+    }
+}
+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/esm/model-collection.js

@@ -0,0 +1,21 @@
+export 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/esm/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/dist/esm/query-builder.js

@@ -0,0 +1,89 @@
+import { newFetchOneResult, newFetchOneXResult, newFetchSomeResult } from './fetch-result.js';
+import { newSelector } from './selector.js';
+import { newModelCollection } from './model-collection.js';
+export 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 = 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 = 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 newFetchOneResult(selectors[selectorAlias].input.table, (result.length ? result[0] : undefined)?.selectors[selectorAlias], modelCollection);
+                    },
+                    newFetchOneXResult(selectorAlias) {
+                        return newFetchOneXResult(selectors[selectorAlias].input.table, (result.length ? result[0] : undefined)?.selectors[selectorAlias], modelCollection);
+                    },
+                    newFetchSomeResult(selectorAlias) {
+                        return 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/esm/selector.js

@@ -0,0 +1,42 @@
+export function newSelector(rizzolver, tableName, alias, keys) {
+    const effectiveKeys = (keys ?? rizzolver.fields[tableName]);
+    const tableAlias = `${tableName} as ${alias}`;
+    const fields = effectiveKeys.map((field) => `${alias}.${field} as _${alias}_${field}`);
+    function _rowToModel(result) {
+        if (!result || !result[`_${alias}_id`]) {
+            return undefined;
+        }
+        const model = {};
+        for (const field of effectiveKeys) {
+            const aliasedField = `_${alias}_${field}`;
+            model[field] = result[aliasedField] ?? undefined;
+        }
+        return model;
+    }
+    const selector = {
+        input: {
+            table: tableName,
+            alias,
+            tableFields: effectiveKeys
+        },
+        selectTable: tableAlias,
+        selectFields: fields,
+        field(field) {
+            return {
+                str: `_${alias}_${field}`,
+                from(table) {
+                    return `${table}._${alias}_${field}`;
+                }
+            };
+        },
+        select(rows) {
+            const data = [];
+            for (const row of rows) {
+                const model = _rowToModel(row);
+                data.push({ row, model });
+            }
+            return data;
+        }
+    };
+    return selector;
+}

package/dist/esm/type-helpers.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,52 @@
+import type { Selectable } from 'kysely';
+import { type FetchOneResult, type FetchOneXResult, type FetchSomeResult } from './fetch-result.js';
+import { type ModelCollection } from './model-collection.js';
+/**
+ * A {@link FetchResultFactory} exposes variants of fetch-related functions, but
+ * with the `DB` type parameter already set.
+ *
+ * This makes it less verbose to work with fetch results in a type-safe way.
+ */
+export type FetchResultFactory<DB> = ReturnType<typeof newFetchResultFactory<DB>>;
+export declare function newFetchResultFactory<DB>(): {
+    /**
+     * Creates a new {@link FetchOneResult} instance.
+     */
+    newFetchOne<K extends keyof DB & string>(table: K, result: Selectable<DB[K]> | undefined, models?: ModelCollection<DB>): FetchOneResult<DB, K, Selectable<DB[K]>>;
+    /**
+     * 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.
+     */
+    newFetchOneX<K extends keyof DB & string>(table: K, result: Selectable<DB[K]> | undefined, models?: ModelCollection<DB>): FetchOneXResult<DB, K, Selectable<DB[K]>>;
+    /**
+     * Creates a new {@link FetchSomeResult} instance.
+     */
+    newFetchSome<K extends keyof DB & string>(table: K, result: Selectable<DB[K]>[], models?: ModelCollection<DB>): FetchSomeResult<DB, K, Selectable<DB[K]>>;
+    /**
+     * Checks if a {@link FetchResult} is a {@link FetchOneResult}.
+     */
+    isFetchOne<K extends keyof DB & string>(table: K, result: unknown): result is FetchOneResult<DB, K, Selectable<DB[K]>>;
+    /**
+     * Checks if a {@link FetchResult} is a {@link FetchOneXResult}.
+     */
+    isFetchOneX<K extends keyof DB & string>(table: K, result: unknown): result is FetchOneXResult<DB, K, Selectable<DB[K]>>;
+    /**
+     * Checks if a {@link FetchResult} is a {@link FetchSomeResult}.
+     */
+    isFetchSome<K extends keyof DB & string>(table: K, result: unknown): result is FetchSomeResult<DB, K, Selectable<DB[K]>>;
+    /**
+     * Asserts that a {@link FetchResult} is a {@link FetchOneResult}.
+     */
+    assertIsFetchOne<K extends keyof DB & string>(table: K, result: unknown): asserts result is FetchOneResult<DB, K, Selectable<DB[K]>>;
+    /**
+     * Asserts that a {@link FetchResult} is a {@link FetchOneXResult}.
+     */
+    assertIsFetchOneX<K extends keyof DB & string>(table: K, result: unknown): asserts result is FetchOneXResult<DB, K, Selectable<DB[K]>>;
+    /**
+     * Asserts that a {@link FetchResult} is a {@link FetchSomeResult}.
+     */
+    assertIsFetchSome<K extends keyof DB & string>(table: K, result: unknown): asserts result is FetchSomeResult<DB, K, Selectable<DB[K]>>;
+};