@casekit/orm2 0.0.0-20250322230249

package/build/builders/buildFind.test.js

@@ -0,0 +1,263 @@
+import { describe, expect, test } from "vitest";
+import { createTestDB } from "../tests/util/db.js";
+import { buildFind } from "./buildFind.js";
+describe("buildFind", () => {
+    const { db } = createTestDB();
+    test("builds query with N:1 relation include", () => {
+        const result = buildFind(db.config, "post", {
+            select: ["id", "title"],
+            include: {
+                author: {
+                    select: ["name", "id"],
+                },
+            },
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "post",
+                alias: "a",
+                model: "post",
+            },
+            columns: [
+                {
+                    table: "a",
+                    name: "id",
+                    alias: "a_0",
+                    path: ["id"],
+                },
+                {
+                    table: "a",
+                    name: "title",
+                    alias: "a_1",
+                    path: ["title"],
+                },
+                {
+                    table: "b",
+                    name: "name",
+                    alias: "b_0",
+                    path: ["author", "name"],
+                },
+                {
+                    table: "b",
+                    name: "id",
+                    alias: "b_1",
+                    path: ["author", "id"],
+                },
+            ],
+            joins: [
+                {
+                    path: ["author"],
+                    relation: "author",
+                    orderBy: [],
+                    type: "INNER",
+                    table: {
+                        schema: "orm",
+                        name: "user",
+                        alias: "b",
+                        model: "user",
+                    },
+                    where: null,
+                    columns: [
+                        {
+                            from: {
+                                table: "a",
+                                name: "author_id",
+                            },
+                            to: {
+                                table: "b",
+                                name: "id",
+                            },
+                        },
+                    ],
+                },
+            ],
+            where: null,
+            orderBy: [],
+            limit: undefined,
+            offset: undefined,
+            tableIndex: 2,
+        });
+    });
+    test("builds query with optional N:1 relation include", () => {
+        const { db } = createTestDB();
+        const result = buildFind(db.config, "post", {
+            select: ["id"],
+            include: {
+                backgroundColor: {
+                    select: ["name"],
+                },
+            },
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "post",
+                alias: "a",
+                model: "post",
+            },
+            columns: [
+                {
+                    table: "a",
+                    name: "id",
+                    alias: "a_0",
+                    path: ["id"],
+                },
+                {
+                    table: "b",
+                    name: "name",
+                    alias: "b_0",
+                    path: ["backgroundColor", "name"],
+                },
+                {
+                    table: "b",
+                    name: "hex",
+                    alias: "b_1",
+                    path: ["backgroundColor", "hex"],
+                },
+            ],
+            joins: [
+                {
+                    path: ["backgroundColor"],
+                    relation: "backgroundColor",
+                    orderBy: [],
+                    type: "LEFT",
+                    table: {
+                        schema: "orm",
+                        name: "color",
+                        alias: "b",
+                        model: "color",
+                    },
+                    where: null,
+                    columns: [
+                        {
+                            from: {
+                                table: "a",
+                                name: "background_color_value",
+                            },
+                            to: {
+                                table: "b",
+                                name: "hex",
+                            },
+                        },
+                    ],
+                },
+            ],
+            where: null,
+            orderBy: [],
+            limit: undefined,
+            offset: undefined,
+            tableIndex: 2,
+        });
+    });
+    test("automatically joins relations referenced in orderBy", () => {
+        const { db } = createTestDB();
+        const result = buildFind(db.config, "post", {
+            select: ["id", "title"],
+            orderBy: ["author.name"],
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "post",
+                alias: "a",
+                model: "post",
+            },
+            columns: [
+                {
+                    table: "a",
+                    name: "id",
+                    alias: "a_0",
+                    path: ["id"],
+                },
+                {
+                    table: "a",
+                    name: "title",
+                    alias: "a_1",
+                    path: ["title"],
+                },
+                {
+                    table: "b",
+                    name: "id",
+                    alias: "b_0",
+                    path: ["author", "id"],
+                },
+            ],
+            joins: [
+                {
+                    relation: "author",
+                    path: ["author"],
+                    orderBy: [],
+                    type: "INNER",
+                    table: {
+                        schema: "orm",
+                        name: "user",
+                        alias: "b",
+                        model: "user",
+                    },
+                    where: null,
+                    columns: [
+                        {
+                            from: {
+                                table: "a",
+                                name: "author_id",
+                            },
+                            to: {
+                                table: "b",
+                                name: "id",
+                            },
+                        },
+                    ],
+                },
+            ],
+            where: null,
+            orderBy: [
+                {
+                    column: {
+                        table: "b",
+                        name: "name",
+                    },
+                    direction: "ASC",
+                },
+            ],
+            limit: undefined,
+            offset: undefined,
+            tableIndex: 2,
+        });
+    });
+    test("combines ordering, limits and offsets from nested queries", () => {
+        const { db } = createTestDB();
+        const result = buildFind(db.config, "post", {
+            select: ["id"],
+            limit: 10,
+            offset: 5,
+            orderBy: ["author.id"],
+            include: {
+                author: {
+                    select: ["id"],
+                    limit: 5,
+                    offset: 10,
+                    orderBy: [["name", "desc"]],
+                },
+            },
+        });
+        expect(result.limit).toBe(5); // Takes minimum of limits
+        expect(result.offset).toBe(10); // Takes maximum of offsets
+        expect(result.orderBy).toEqual([
+            {
+                column: {
+                    table: "b",
+                    name: "id",
+                },
+                direction: "ASC",
+            },
+            {
+                column: {
+                    table: "b",
+                    name: "name",
+                },
+                direction: "DESC",
+            },
+        ]);
+    });
+});

package/build/builders/buildUpdate.d.ts

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

package/build/builders/buildUpdate.js

@@ -0,0 +1,34 @@
+import { getField } from "@casekit/orm2-config";
+import { makeTableAlias } from "#util/makeTableAlias.js";
+import { hasClauses } from "../util/hasClauses.js";
+import { buildWhere } from "./buildWhere.js";
+export const buildUpdate = (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,
+    };
+    const set = Object.entries(query.set).map(([field, value]) => [
+        getField(model, field).column,
+        value,
+    ]);
+    if (!hasClauses(query.where)) {
+        throw new Error("Update 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,
+        set,
+        where,
+        returning,
+    };
+};

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

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

package/build/builders/buildUpdate.test.js

@@ -0,0 +1,130 @@
+import { describe, expect, test } from "vitest";
+import { SQLStatement, sql } from "@casekit/sql";
+import { unindent } from "@casekit/unindent";
+import { $like } from "#operators.js";
+import { createTestDB } from "../tests/util/db.js";
+import { buildUpdate } from "./buildUpdate.js";
+describe("buildUpdate", () => {
+    const { db } = createTestDB();
+    test("builds basic update query", () => {
+        const result = buildUpdate(db.config, "user", {
+            set: { name: "John", email: "john@example.com" },
+            where: { id: 1 },
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "user",
+                alias: "a",
+                model: "user",
+            },
+            set: [
+                ["name", "John"],
+                ["email", "john@example.com"],
+            ],
+            where: sql `"a"."id" = ${1}`,
+            returning: [],
+        });
+    });
+    test("builds update query with returning clause", () => {
+        const result = buildUpdate(db.config, "user", {
+            set: { name: "John" },
+            where: { id: 1 },
+            returning: ["id", "name"],
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "user",
+                alias: "a",
+                model: "user",
+            },
+            set: [["name", "John"]],
+            where: sql `"a"."id" = ${1}`,
+            returning: [
+                {
+                    name: "id",
+                    alias: "a_0",
+                    path: ["id"],
+                },
+                {
+                    name: "name",
+                    alias: "a_1",
+                    path: ["name"],
+                },
+            ],
+        });
+    });
+    test("throws error for nonexistent model", () => {
+        expect(() => buildUpdate(db.config, "nonexistent", {
+            set: { name: "John" },
+            where: { id: 1 },
+        })).toThrow('Model "nonexistent" not found');
+    });
+    test("throws error when where clause is empty", () => {
+        expect(() => buildUpdate(db.config, "user", {
+            set: { name: "John" },
+            where: {},
+        })).toThrow("Update queries must have a where clause");
+    });
+    test("throws error when where clause is undefined", () => {
+        expect(() => buildUpdate(db.config, "user", {
+            set: { name: "John" },
+            // @ts-expect-error testing runtime behavior
+            where: undefined,
+        })).toThrow("Update queries must have a where clause");
+    });
+    test("handles nested paths in returning clause", () => {
+        const result = buildUpdate(db.config, "user", {
+            set: { name: "John" },
+            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", () => {
+        const result = buildUpdate(db.config, "user", {
+            set: { name: "John" },
+            where: { id: 1 },
+        }, [], 5);
+        expect(result.table.alias).toBe("f");
+    });
+    test("handles complex where clauses", () => {
+        const result = buildUpdate(db.config, "user", {
+            set: { name: "John" },
+            where: {
+                id: 1,
+                name: "test",
+                email: { [$like]: "%@example.com" },
+            },
+        });
+        expect(result).toEqual({
+            table: {
+                schema: "orm",
+                name: "user",
+                alias: "a",
+                model: "user",
+            },
+            set: [["name", "John"]],
+            where: expect.any(SQLStatement),
+            returning: [],
+        });
+        expect(result.where?.pretty).toEqual(unindent `
+            "a"."id" = $1
+            AND "a"."name" = $2
+            AND "a"."email" LIKE $3
+        `);
+        expect(result.where?.values).toEqual([1, "test", "%@example.com"]);
+    });
+});

package/build/builders/buildWhere.d.ts

@@ -0,0 +1,6 @@
+import { NormalizedConfig } from "@casekit/orm2-config";
+import { ModelDefinitions, ModelName, OperatorDefinitions } from "@casekit/orm2-schema";
+import { SQLStatement } from "@casekit/sql";
+import { WhereClause } from "../types/WhereClause.js";
+import { Table } from "./types.js";
+export declare const buildWhere: (config: NormalizedConfig, table: Table, where: WhereClause<ModelDefinitions, OperatorDefinitions, ModelName<ModelDefinitions>>) => SQLStatement;

package/build/builders/buildWhere.js

@@ -0,0 +1,63 @@
+import { sql } from "@casekit/sql";
+import { $and, $not, $or, defaultOperators } from "../operators.js";
+export const buildWhere = (config, table, where) => {
+    // NB. Object.entries does not iterate over the symbol keys
+    // of an object, so this is a neat way for us to get just the
+    // clauses that relate to specific fields, and not logic operators
+    // like $and, $or, $not.
+    const clauses = Object.entries(where).map(([field, value]) => {
+        const tableAlias = table.alias;
+        const column = config.models[table.model]?.fields[field]?.column;
+        if (!column)
+            throw new Error("Unrecognised field: " + field);
+        // either null or undefined counts as null, to avoid surprises
+        if (value === null || value === undefined) {
+            return sql `${sql.ident(tableAlias)}.${sql.ident(column)} IS NULL`;
+        }
+        if (value === true) {
+            return sql `${sql.ident(tableAlias)}.${sql.ident(column)} IS TRUE`;
+        }
+        if (value === false) {
+            return sql `${sql.ident(tableAlias)}.${sql.ident(column)} IS FALSE`;
+        }
+        // value types
+        if (typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean" ||
+            value instanceof Date ||
+            Object.getOwnPropertySymbols(value).length === 0) {
+            return sql `${sql.ident(tableAlias)}.${sql.ident(column)} = ${sql.value(value)}`;
+        }
+        //operator clauses - more than one can be specified
+        const subclauses = Object.getOwnPropertySymbols(value).map((op) => {
+            const opValue = value[op];
+            const operator = op in config.operators.where
+                ? config.operators.where[op]
+                : op in defaultOperators
+                    ? defaultOperators[op]
+                    : null;
+            if (!operator) {
+                throw new Error(`Unrecognised query operator or value: ${JSON.stringify(opValue)}`);
+            }
+            return operator({
+                table: sql.ident(tableAlias),
+                column: sql.ident(column),
+            }, opValue ?? null);
+        });
+        return sql.join(subclauses, " AND ");
+    });
+    // logical operators
+    if (where[$and]) {
+        const subclauses = where[$and].map((clause) => buildWhere(config, table, clause));
+        clauses.push(sql `(${sql.join(subclauses, " AND ")})`);
+    }
+    if (where[$or]) {
+        const subclauses = where[$or].map((clause) => buildWhere(config, table, clause));
+        clauses.push(sql `(${sql.join(subclauses, " OR ")})`);
+    }
+    if (where[$not]) {
+        const subclause = buildWhere(config, table, where[$not]);
+        clauses.push(sql `NOT ${subclause}`);
+    }
+    return sql.join(clauses, " AND ");
+};

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

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

package/build/builders/buildWhere.test.js

@@ -0,0 +1,154 @@
+import { describe, expect, test } from "vitest";
+import { $and, $eq, $gt, $gte, $ilike, $in, $is, $like, $lt, $lte, $ne, $not, $or, } from "../operators.js";
+import { orm } from "../orm.js";
+import { buildWhere } from "./buildWhere.js";
+describe("buildWhere", () => {
+    const db = orm({
+        models: {
+            user: {
+                fields: {
+                    id: { column: "id", type: "integer", primaryKey: true },
+                    name: { column: "name", type: "text" },
+                    active: { column: "active", type: "boolean" },
+                    createdAt: { column: "created_at", type: "timestamp" },
+                },
+            },
+        },
+        operators: { where: {} },
+    });
+    const table = {
+        schema: "public",
+        model: "user",
+        alias: "u",
+        name: "user",
+    };
+    test("builds simple equality clause", () => {
+        const where = { id: 1 };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."id" = $1');
+        expect(result.values).toEqual([1]);
+    });
+    test("builds IS NULL clause", () => {
+        const where = { name: null };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."name" IS NULL');
+    });
+    test("builds boolean clauses", () => {
+        const whereTrue = { active: true };
+        const whereFalse = { active: false };
+        expect(buildWhere(db.config, table, whereTrue).text).toBe('"u"."active" IS TRUE');
+        expect(buildWhere(db.config, table, whereFalse).text).toBe('"u"."active" IS FALSE');
+    });
+    test("builds AND clause", () => {
+        const where = { [$and]: [{ id: 1 }, { name: "test" }] };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('("u"."id" = $1 AND "u"."name" = $2)');
+        expect(result.values).toEqual([1, "test"]);
+    });
+    test("builds OR clause", () => {
+        const where = { [$or]: [{ id: 1 }, { name: "test" }] };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('("u"."id" = $1 OR "u"."name" = $2)');
+        expect(result.values).toEqual([1, "test"]);
+    });
+    test("builds NOT clause", () => {
+        const where = { [$not]: { active: true } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('NOT "u"."active" IS TRUE');
+    });
+    test("throws error for unrecognized field", () => {
+        const where = { unknownField: 1 };
+        expect(() => buildWhere(db.config, table, where)).toThrow("Unrecognised field");
+    });
+    test("handles Date objects", () => {
+        const date = new Date("2023-01-01");
+        const where = { createdAt: date };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."created_at" = $1');
+        expect(result.values).toEqual([date]);
+    });
+    test("builds $eq operator clause", () => {
+        const where = { id: { [$eq]: 1 } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."id" = $1');
+        expect(result.values).toEqual([1]);
+    });
+    test("builds $gt operator clause", () => {
+        const where = { id: { [$gt]: 1 } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."id" > $1');
+        expect(result.values).toEqual([1]);
+    });
+    test("builds $gte operator clause", () => {
+        const where = { id: { [$gte]: 1 } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."id" >= $1');
+        expect(result.values).toEqual([1]);
+    });
+    test("builds $ilike operator clause", () => {
+        const where = { name: { [$ilike]: "%test%" } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."name" ILIKE $1');
+        expect(result.values).toEqual(["%test%"]);
+    });
+    test("builds $is operator clause", () => {
+        const where = { name: { [$is]: null } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."name" IS NULL');
+        expect(result.values).toEqual([]);
+    });
+    test("builds $not operator clause", () => {
+        const where = { name: { [$not]: null } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."name" IS NOT NULL');
+        expect(result.values).toEqual([]);
+    });
+    test("builds $like operator clause", () => {
+        const where = { name: { [$like]: "%test%" } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."name" LIKE $1');
+        expect(result.values).toEqual(["%test%"]);
+    });
+    test("builds $lt operator clause", () => {
+        const where = { id: { [$lt]: 1 } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."id" < $1');
+        expect(result.values).toEqual([1]);
+    });
+    test("builds $lte operator clause", () => {
+        const where = { id: { [$lte]: 1 } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."id" <= $1');
+        expect(result.values).toEqual([1]);
+    });
+    test("builds $ne operator clause", () => {
+        const where = { id: { [$ne]: 1 } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."id" != $1');
+        expect(result.values).toEqual([1]);
+    });
+    test("builds $not operator clause with null", () => {
+        const where = { name: { [$not]: null } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."name" IS NOT NULL');
+    });
+    test("throws error when $not operator receives non-null or boolean value", () => {
+        const where = { name: { [$not]: "test" } };
+        expect(() => buildWhere(db.config, table, where)).toThrow("Invalid value passed to $not operator");
+    });
+    test("builds $in operator clause", () => {
+        const where = { id: { [$in]: [1, 2, 3] } };
+        const result = buildWhere(db.config, table, where);
+        expect(result.text).toBe('"u"."id" IN ($1, $2, $3)');
+        expect(result.values).toEqual([1, 2, 3]);
+    });
+    test("throws error when $in operator receives non-array value", () => {
+        const where = { id: { [$in]: 1 } };
+        expect(() => buildWhere(db.config, table, where)).toThrow("Non-array passed to IN clause");
+    });
+    test("throws error for unrecognised operator", () => {
+        const unknownSymbol = Symbol("unknown");
+        const where = { id: { [unknownSymbol]: 1 } };
+        expect(() => buildWhere(db.config, table, where)).toThrow("Unrecognised query operator or value");
+    });
+});