@casekit/orm2 0.0.0-20250322230249

package/build/builders/buildCount.d.ts

@@ -0,0 +1,23 @@
+/**
+ * NB. Lots of ! in this file which maybe isn't great but I think for these
+ * builders, where we can be fairly confident due to the type-checking at the edges
+ * that things are defined, it's better than the alternative of loads of
+ * redundant checks for undefined. We've done all the checks we need at the
+ * stage of normalizing the model, we can now assume everything is wired up
+ * correctly.
+ *
+ * Also this is a file in which there's a lot of mutation and dependency
+ * on the order in which things are done, which is not ideal but is what
+ * it is. Refactor and/or add to/change with care.
+ */
+import { NormalizedConfig } from "@casekit/orm2-config";
+import { ModelDefinitions, OperatorDefinitions } from "@casekit/orm2-schema";
+import { WhereClause } from "../types/WhereClause.js";
+import { CountBuilder } from "./types.js";
+type BaseCountParams = {
+    where?: WhereClause<ModelDefinitions, OperatorDefinitions, string>;
+    include?: Record<string, BaseCountParams>;
+    for?: "update" | "no key update" | "share" | "key share";
+};
+export declare const buildCount: (config: NormalizedConfig, modelName: string, query: BaseCountParams, path?: string[], tableIndex?: number) => CountBuilder;
+export {};

package/build/builders/buildCount.js

@@ -0,0 +1,63 @@
+import { hasClauses } from "#util/hasClauses.js";
+import { makeTableAlias } from "#util/makeTableAlias.js";
+import { buildWhere } from "./buildWhere.js";
+/**
+ * Builds a base CountBuilder, with only columns from the main table.
+ * Joins will be added later.
+ */
+const buildBaseCount = (config, m, query, tableIndex = 0) => {
+    const model = config.models[m];
+    if (!model)
+        throw new Error(`Model "${m}" not found`);
+    const table = {
+        schema: model.schema,
+        name: model.table,
+        alias: makeTableAlias(tableIndex++),
+        model: m,
+    };
+    const where = hasClauses(query.where)
+        ? buildWhere(config, table, query.where)
+        : null;
+    return {
+        table,
+        where,
+        joins: [],
+        for: query.for,
+        tableIndex,
+    };
+};
+export const buildCount = (config, modelName, query, path = [], tableIndex = 0) => {
+    const model = config.models[modelName];
+    if (!model)
+        throw new Error(`Model "${modelName}" not found`);
+    const builder = buildBaseCount(config, modelName, query, tableIndex);
+    for (const [r, subquery] of Object.entries(query.include ?? {})) {
+        const relation = model.relations[r];
+        if (relation.type !== "N:1") {
+            continue;
+        }
+        const joinBuilder = buildCount(config, relation.model, subquery, [...path, r], builder.tableIndex);
+        builder.joins.push({
+            path: [...path, r],
+            relation: r,
+            table: joinBuilder.table,
+            where: joinBuilder.where,
+            type: "INNER",
+            columns: relation.from.columns.map((fk, i) => ({
+                from: {
+                    table: builder.table.alias,
+                    name: fk,
+                },
+                to: {
+                    table: joinBuilder.table.alias,
+                    name: relation.to.columns[i],
+                },
+            })),
+        });
+        // update the parent builder's tableIndex with the one from the
+        // joinBuilder, so that we don't have overlapping table indices
+        builder.tableIndex = joinBuilder.tableIndex;
+        builder.joins.push(...joinBuilder.joins);
+    }
+    return builder;
+};

package/build/builders/buildCount.test.d.ts

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

package/build/builders/buildCount.test.js

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "vitest";
+import { sql } from "@casekit/sql";
+import { createTestDB } from "../tests/util/db.js";
+import { buildCount } from "./buildCount.js";
+describe("buildCount", () => {
+    const { db } = createTestDB();
+    test("builds basic count query", () => {
+        const result = buildCount(db.config, "post", {});
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "post",
+                alias: "a",
+                model: "post",
+            },
+            where: null,
+            joins: [],
+            for: undefined,
+            tableIndex: 1,
+        });
+    });
+    test("builds count query with N:1 relation include", () => {
+        const result = buildCount(db.config, "post", {
+            where: { id: 1 },
+            include: {
+                author: {
+                    where: {},
+                },
+            },
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "post",
+                alias: "a",
+                model: "post",
+            },
+            where: sql `"a"."id" = ${1}`,
+            joins: [
+                {
+                    relation: "author",
+                    table: {
+                        schema: "orm",
+                        name: "user",
+                        alias: "b",
+                        model: "user",
+                    },
+                    where: null,
+                    type: "INNER",
+                    path: ["author"],
+                    columns: [
+                        {
+                            from: { table: "a", name: "author_id" },
+                            to: { table: "b", name: "id" },
+                        },
+                    ],
+                },
+            ],
+            for: undefined,
+            tableIndex: 2,
+        });
+    });
+    test("builds count query with where clause", () => {
+        const result = buildCount(db.config, "post", {
+            where: {
+                title: "Test Post",
+            },
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "post",
+                alias: "a",
+                model: "post",
+            },
+            where: sql `"a"."title" = ${"Test Post"}`,
+            joins: [],
+            for: undefined,
+            tableIndex: 1,
+        });
+    });
+    test("builds count query with nested includes and where clauses", () => {
+        const result = buildCount(db.config, "post", {
+            where: {
+                title: "Test Post",
+            },
+            include: {
+                author: {
+                    where: {
+                        name: "John",
+                    },
+                },
+            },
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "post",
+                alias: "a",
+                model: "post",
+            },
+            where: sql `"a"."title" = ${"Test Post"}`,
+            joins: [
+                {
+                    relation: "author",
+                    table: {
+                        schema: "orm",
+                        name: "user",
+                        alias: "b",
+                        model: "user",
+                    },
+                    where: sql `"b"."name" = ${"John"}`,
+                    type: "INNER",
+                    path: ["author"],
+                    columns: [
+                        {
+                            from: { table: "a", name: "author_id" },
+                            to: { table: "b", name: "id" },
+                        },
+                    ],
+                },
+            ],
+            for: undefined,
+            tableIndex: 2,
+        });
+    });
+    test("builds count query with for parameter", () => {
+        const result = buildCount(db.config, "post", {
+            for: "update",
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "post",
+                alias: "a",
+                model: "post",
+            },
+            where: null,
+            joins: [],
+            for: "update",
+            tableIndex: 1,
+        });
+    });
+});

package/build/builders/buildCreate.d.ts

@@ -0,0 +1,5 @@
+import { NormalizedConfig } from "@casekit/orm2-config";
+import { ModelDefinitions, ModelName } from "@casekit/orm2-schema";
+import { CreateManyParams } from "#types/CreateManyParams.js";
+import { CreateBuilder } from "./types.js";
+export declare const buildCreate: (config: NormalizedConfig, modelName: string, query: CreateManyParams<ModelDefinitions, ModelName<ModelDefinitions>>, path?: string[], tableIndex?: number) => CreateBuilder;

package/build/builders/buildCreate.js

@@ -0,0 +1,28 @@
+import { uniq } from "es-toolkit";
+import { makeTableAlias } from "#util/makeTableAlias.js";
+export const buildCreate = (config, modelName, query, path = [], tableIndex = 0) => {
+    const model = config.models[modelName];
+    if (!model)
+        throw new Error(`Model "${modelName}" not found`);
+    const fields = uniq(query.values.flatMap(Object.keys));
+    const table = {
+        schema: model.schema,
+        name: model.table,
+        alias: makeTableAlias(tableIndex++),
+        model: modelName,
+    };
+    const columns = fields.map((f) => model.fields[f].column);
+    const values = query.values.map((v) => fields.map((f) => v[f] ?? null));
+    const returning = query.returning?.map((f, index) => ({
+        name: model.fields[f].column,
+        alias: `${table.alias}_${index}`,
+        path: [...path, f],
+    })) ?? [];
+    return {
+        table,
+        columns,
+        values,
+        returning,
+        onConflict: query.onConflict,
+    };
+};

package/build/builders/buildCreate.test.d.ts

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

package/build/builders/buildCreate.test.js

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "vitest";
+import { createTestDB } from "../tests/util/db.js";
+import { buildCreate } from "./buildCreate.js";
+describe("buildCreate", () => {
+    const { db } = createTestDB();
+    test("should build a create query", () => {
+        const result = buildCreate(db.config, "user", {
+            values: [{ id: 1, name: "John Doe", email: "john@example.com" }],
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "user",
+                alias: "a",
+                model: "user",
+            },
+            columns: ["id", "name", "email"],
+            values: [[1, "John Doe", "john@example.com"]],
+            returning: [],
+            onConflict: undefined,
+        });
+    });
+    test("should throw an error if model is not found", () => {
+        expect(() => buildCreate(db.config, "NonExistentModel", {
+            values: [
+                { id: 1, name: "John Doe", email: "john@example.com" },
+            ],
+        })).toThrow('Model "NonExistentModel" not found');
+    });
+    test("should handle returning fields", () => {
+        const result = buildCreate(db.config, "user", {
+            values: [{ id: 1, name: "John Doe", email: "john@example.com" }],
+            returning: ["id", "name"],
+        });
+        expect(result.returning).toEqual([
+            { name: "id", alias: "a_0", path: ["id"] },
+            { name: "name", alias: "a_1", path: ["name"] },
+        ]);
+    });
+    test("should handle onConflict", () => {
+        const result = buildCreate(db.config, "user", {
+            values: [{ id: 1, name: "John Doe", email: "john@example.com" }],
+            onConflict: { do: "nothing" },
+        });
+        expect(result.onConflict).toEqual({ do: "nothing" });
+    });
+});

package/build/builders/buildDelete.d.ts

@@ -0,0 +1,5 @@
+import { NormalizedConfig } from "@casekit/orm2-config";
+import { ModelDefinitions, ModelName, OperatorDefinitions } from "@casekit/orm2-schema";
+import { DeleteParams } from "#types/DeleteParams.js";
+import { DeleteBuilder } from "./types.js";
+export declare const buildDelete: (config: NormalizedConfig, modelName: string, query: DeleteParams<ModelDefinitions, OperatorDefinitions, ModelName<ModelDefinitions>>, path?: string[], tableIndex?: number) => DeleteBuilder;

package/build/builders/buildDelete.js

@@ -0,0 +1,28 @@
+import { makeTableAlias } from "#util/makeTableAlias.js";
+import { hasClauses } from "../util/hasClauses.js";
+import { buildWhere } from "./buildWhere.js";
+export const buildDelete = (config, modelName, query, path = [], tableIndex = 0) => {
+    const model = config.models[modelName];
+    if (!model)
+        throw new Error(`Model "${modelName}" not found`);
+    const table = {
+        schema: model.schema,
+        name: model.table,
+        alias: makeTableAlias(tableIndex++),
+        model: modelName,
+    };
+    if (!hasClauses(query.where)) {
+        throw new Error("Delete queries must have a where clause");
+    }
+    const where = buildWhere(config, table, query.where);
+    const returning = query.returning?.map((f, index) => ({
+        name: model.fields[f].column,
+        alias: `${table.alias}_${index}`,
+        path: [...path, f],
+    })) ?? [];
+    return {
+        table,
+        where,
+        returning,
+    };
+};

package/build/builders/buildDelete.test.d.ts

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

package/build/builders/buildDelete.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "vitest";
+import { sql } from "@casekit/sql";
+import { createTestDB } from "../tests/util/db.js";
+import { buildDelete } from "./buildDelete.js";
+describe("buildDelete", () => {
+    const { db } = createTestDB();
+    test("builds basic delete query with where clause", () => {
+        const result = buildDelete(db.config, "user", {
+            where: { id: 1 },
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "user",
+                alias: "a",
+                model: "user",
+            },
+            where: sql `"a"."id" = ${1}`,
+            returning: [],
+        });
+    });
+    test("builds delete query with returning clause", () => {
+        const result = buildDelete(db.config, "user", {
+            where: { id: 1 },
+            returning: ["id", "name"],
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "user",
+                alias: "a",
+                model: "user",
+            },
+            where: sql `"a"."id" = ${1}`,
+            returning: [
+                {
+                    name: "id",
+                    alias: "a_0",
+                    path: ["id"],
+                },
+                {
+                    name: "name",
+                    alias: "a_1",
+                    path: ["name"],
+                },
+            ],
+        });
+    });
+    test("throws error when model not found", () => {
+        expect(() => buildDelete(db.config, "nonexistentModel", {
+            where: { id: 1 },
+        })).toThrow('Model "nonexistentModel" not found');
+    });
+    test("throws error when where clause is empty", () => {
+        expect(() => buildDelete(db.config, "user", {
+            where: {},
+        })).toThrow("Delete queries must have a where clause");
+    });
+    test("throws error when where clause is undefined", () => {
+        expect(() => buildDelete(db.config, "user", {
+            // @ts-expect-error testing runtime behavior with invalid input
+            where: undefined,
+        })).toThrow("Delete queries must have a where clause");
+    });
+    test("handles complex where clauses", () => {
+        const result = buildDelete(db.config, "user", {
+            where: {
+                id: 1,
+                name: "test",
+                email: { $like: "%@example.com" },
+            },
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "user",
+                alias: "a",
+                model: "user",
+            },
+            where: expect.any(Object), // SQL statement object
+            returning: [],
+        });
+    });
+    test("uses correct path for nested fields in returning clause", () => {
+        const result = buildDelete(db.config, "user", {
+            where: { id: 1 },
+            returning: ["id", "name"],
+        }, ["parent"]);
+        expect(result.returning).toEqual([
+            {
+                name: "id",
+                alias: "a_0",
+                path: ["parent", "id"],
+            },
+            {
+                name: "name",
+                alias: "a_1",
+                path: ["parent", "name"],
+            },
+        ]);
+    });
+    test("uses provided table index for alias generation", () => {
+        const result = buildDelete(db.config, "user", {
+            where: { id: 1 },
+        }, [], 5);
+        expect(result.table.alias).toBe("f");
+    });
+});

package/build/builders/buildFind.d.ts

@@ -0,0 +1,8 @@
+import { NormalizedConfig } from "@casekit/orm2-config";
+import { ModelDefinition, OperatorDefinitions } from "@casekit/orm2-schema";
+import { FindParams } from "#types/FindParams.js";
+import { FindBuilder } from "./types.js";
+export declare const buildFind: (config: NormalizedConfig, modelName: string, query: FindParams<Record<string, Required<ModelDefinition>>, OperatorDefinitions, string>, lateralBy?: {
+    field: string;
+    values: unknown[];
+}[], path?: string[], tableIndex?: number) => FindBuilder;

package/build/builders/buildFind.js

@@ -0,0 +1,185 @@
+/**
+ * NB. Lots of ! in this file which maybe isn't great but I think for these
+ * builders, where we can be fairly confident due to the type-checking at the edges
+ * that things are defined, it's better than the alternative of loads of
+ * redundant checks for undefined. We've done all the checks we need at the
+ * stage of normalizing the model, we can now assume everything is wired up
+ * correctly.
+ *
+ * Also this is a file in which there's a lot of mutation and dependency
+ * on the order in which things are done, which is not ideal but is what
+ * it is. Refactor and/or add to/change with care.
+ */
+import { pickBy, uniq } from "es-toolkit";
+import { max, min } from "es-toolkit/compat";
+import { getField, } from "@casekit/orm2-config";
+import { hasClauses } from "#util/hasClauses.js";
+import { makeTableAlias } from "#util/makeTableAlias.js";
+import { buildWhere } from "./buildWhere.js";
+/**
+ * Builds a base FindBuilder, with only columns from the main table.
+ * Joins will be added later.
+ */
+const buildBaseFind = (config, m, query, lateralBy = [], path = [], tableIndex = 0) => {
+    const model = config.models[m];
+    if (!model)
+        throw new Error(`Model "${m}" not found`);
+    let colIndex = 0;
+    const table = {
+        schema: model.schema,
+        name: model.table,
+        alias: makeTableAlias(tableIndex++),
+        model: m,
+    };
+    const columns = uniq([
+        ...query.select,
+        // we always select the primary key even if it's not explicitly
+        // requested so we can use it for wiring up relationships
+        ...model.primaryKey.map((pk) => pk.field),
+        // we also select any foreign keys we're doing a lateral join on
+        ...lateralBy.map((l) => l.field),
+    ]).map((f) => {
+        const field = getField(model, f);
+        return {
+            table: table.alias,
+            name: field.column,
+            alias: `${table.alias}_${colIndex++}`,
+            path: [...path, f],
+        };
+    });
+    const where = hasClauses(query.where)
+        ? buildWhere(config, table, query.where)
+        : null;
+    return {
+        table,
+        columns,
+        where,
+        joins: [],
+        for: query.for,
+        orderBy: [],
+        offset: query.offset,
+        limit: query.limit,
+        tableIndex,
+    };
+};
+const collectManyToOneQueries = (model, query) => {
+    // this slightly complex chain gets all the N:1 relations
+    // we're querying.  as well as the contents of the include
+    // key, we make sure to include a join to any relations
+    // we're ordering by (we'll use them later).
+    // relations we're ordering by are identified by being a
+    // model name and field name separated by a dot.
+    // this is a tiny bit brittle in the case where people
+    // create a model or field name that contains a dot,
+    // but that would be a v weird thing to do as they are
+    // both javascript identifiers so would be a real pain
+    // to write in code. so i think it's probably fine to
+    // not support it.
+    return pickBy({
+        ...query.include,
+        ...query.orderBy
+            // deal with the fact that an order by column
+            //can be a single value or an array with a direction
+            ?.map((ob) => (typeof ob === "string" ? ob : ob[0]))
+            // get only the order by columns that are on relation tables
+            .filter((ob) => ob.includes("."))
+            // get the relation model name
+            .map((ob) => ob.split(".")[0])
+            // check it's not already something we're joining to
+            .filter((f) => !(f in (query.include ?? {})))
+            // if not, add a query to it with an empty select
+            // (ok because we always select the primary key)
+            .reduce((acc, f) => ({ ...acc, [f]: { select: [] } }), {}),
+    }, 
+    // finally select only N:1 relations as these
+    // are the only kind we join to directly
+    (_query, relation) => model.relations[relation].type === "N:1");
+};
+const buildOrderBy = (config, model, query, builder) => {
+    return (query.orderBy?.map((ob) => {
+        const field = typeof ob === "string" ? ob : ob[0];
+        const direction = typeof ob === "string" ? "ASC" : ob[1];
+        if (field.includes(".")) {
+            const [relation, relationField] = field.split(".");
+            const join = builder.joins.find((j) => j.relation === relation);
+            const joinedModel = config.models[model.relations[join.relation].model];
+            return {
+                column: {
+                    table: join.table.alias,
+                    name: joinedModel.fields[relationField].column,
+                },
+                direction: direction.toUpperCase() === "DESC" ? "DESC" : "ASC",
+            };
+        }
+        else {
+            return {
+                column: {
+                    table: builder.table.alias,
+                    name: getField(model, field).column,
+                },
+                direction: direction.toUpperCase() === "DESC" ? "DESC" : "ASC",
+            };
+        }
+    }) ?? []);
+};
+export const buildFind = (config, modelName, query, lateralBy = [], path = [], tableIndex = 0) => {
+    const model = config.models[modelName];
+    if (!model)
+        throw new Error(`Model "${modelName}" not found`);
+    const builder = buildBaseFind(config, modelName, query, lateralBy, path, tableIndex);
+    const manyToOneQueries = collectManyToOneQueries(model, query);
+    for (const [r, subquery] of Object.entries(manyToOneQueries)) {
+        const relation = model.relations[r];
+        if (relation.type !== "N:1") {
+            throw new Error(`Unexpected relation type: ${relation.type}. Should be N:1`);
+        }
+        const joinBuilder = buildFind(config, relation.model, subquery, [], [...path, r], builder.tableIndex);
+        builder.joins.push({
+            relation: r,
+            path: [...path, r],
+            type: relation.optional && !subquery.where ? "LEFT" : "INNER",
+            table: joinBuilder.table,
+            where: joinBuilder.where,
+            orderBy: joinBuilder.orderBy,
+            columns: relation.from.columns.map((fk, i) => ({
+                from: {
+                    table: builder.table.alias,
+                    name: fk,
+                },
+                to: {
+                    table: joinBuilder.table.alias,
+                    name: relation.to.columns[i],
+                },
+            })),
+        });
+        // update the parent builder's tableIndex with the one from the
+        // joinBuilder, so that we don't have overlapping table indices
+        builder.tableIndex = joinBuilder.tableIndex;
+        builder.columns.push(...joinBuilder.columns);
+        builder.joins.push(...joinBuilder.joins);
+        // this is admittedly a bit weird,
+        // we wouldn't expect N:1 relations to specify
+        // ordering, skipping, and limiting, and typescript
+        // prevents users from doing this, but
+        // we rely on them being present as part of the N:N
+        // implementation
+        builder.limit = min([builder.limit, joinBuilder.limit]);
+        builder.offset = max([builder.offset, joinBuilder.offset]);
+    }
+    if (lateralBy.length > 0) {
+        builder.lateralBy = {
+            outerAlias: makeTableAlias(builder.tableIndex++),
+            innerAlias: makeTableAlias(builder.tableIndex++),
+            primaryKeys: lateralBy.map(({ field, values }) => ({
+                column: getField(model, field).column,
+                type: getField(model, field).type,
+                values,
+            })),
+        };
+    }
+    builder.orderBy = [
+        ...buildOrderBy(config, model, query, builder),
+        ...builder.joins.flatMap((j) => j.orderBy ?? []),
+    ];
+    return builder;
+};

package/build/builders/buildFind.test.d.ts

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