@casekit/orm 0.0.1-alpha.0

package/src/schema/types/loose/LooseModelDefinition.ts

@@ -0,0 +1,47 @@
+import { ForeignKey } from "../constraints/ForeignKey";
+import { UniqueConstraint } from "../constraints/UniqueConstraint";
+import { LooseColumnDefinition } from "./LooseColumnDefinition";
+
+/**
+ * Configuration object for a database model.
+ */
+export type LooseModelDefinition = {
+    /**
+     * The name of the model's table. If not specified, the table name will be
+     * derived from the model name, with any transform function specified in
+     * config applied.
+     */
+    table?: string;
+
+    /**
+     * The schema in which the model sits. If not specified, will use the
+     * schema specified in the global config; if no schema is specified in
+     * the global config, will be set to `public`.
+     */
+    schema?: string;
+
+    /**
+     * The model's column configuration - a map of field name to column
+     * definitions. The keys of this map will be used in generated functions
+     * and object fields, so must be valid Javascript identifiers.
+     */
+    columns: Record<string, LooseColumnDefinition>;
+
+    /**
+     * If the table's primary key contains multiple columns, specify them here.
+     * If the primary key is on a single column, you can specify it here or in the column definition.
+     */
+    primaryKey?: string[];
+
+    /**
+     * If the table has unique constraints that span multiple columns, you must specify them here.
+     * If the unique constraint is on a single column, you can specify it here or in the column definition.
+     */
+    uniqueConstraints?: UniqueConstraint[];
+
+    /**
+     * If the table has foreign keys, you must specify them here. If the foreign key is on a single column,
+     * you can specify it here or in the column definition.
+     */
+    foreignKeys?: ForeignKey[];
+};

package/src/schema/types/loose/LooseModelDefinitions.ts

@@ -0,0 +1,3 @@
+import { LooseModelDefinition } from "./LooseModelDefinition";
+
+export type LooseModelDefinitions = Record<string, LooseModelDefinition>;

package/src/schema/types/loose/LooseRelationDefinition.ts

@@ -0,0 +1,10 @@
+export type LooseRelationDefinition =
+    | { model: string; type: "1:N"; foreignKey: string }
+    | { model: string; type: "N:1"; foreignKey: string }
+    | {
+          model: string;
+          type: "N:N";
+          through: string;
+          foreignKey: string;
+          otherKey: string;
+      };

package/src/schema/types/loose/LooseRelationsDefinition.ts

@@ -0,0 +1,3 @@
+import { LooseRelationDefinition } from "./LooseRelationDefinition";
+
+export type LooseRelationsDefinition = Record<string, LooseRelationDefinition>;

package/src/schema/types/loose/LooseRelationsDefinitions.ts

@@ -0,0 +1,7 @@
+import { ModelName } from "../helpers/ModelName";
+import { LooseModelDefinitions } from "./LooseModelDefinitions";
+import { LooseRelationsDefinition } from "./LooseRelationsDefinition";
+
+export type LooseRelationsDefinitions<Models extends LooseModelDefinitions> = {
+    [M in ModelName<Models>]?: LooseRelationsDefinition;
+};

package/src/schema/types/postgres/DataType.ts

@@ -0,0 +1,65 @@
+export type ScalarDataType =
+    | "bigint"
+    | "bigserial"
+    | `bit(${number})`
+    | `bit varying(${number})`
+    | "boolean"
+    | "box"
+    | "bytea"
+    | `character(${number})`
+    | `character varying(${number})`
+    | "cidr"
+    | "circle"
+    | "date"
+    | "double precision"
+    | "inet"
+    | "integer"
+    | "interval"
+    | "json"
+    | "jsonb"
+    | "line"
+    | "lseg"
+    | "macaddr"
+    | "macaddr8"
+    | "money"
+    | `numeric(${number}, ${number})`
+    | "path"
+    | "pg_lsn"
+    | "pg_snapshot"
+    | "point"
+    | "polygon"
+    | "real"
+    | "smallint"
+    | "smallserial"
+    | "serial"
+    | "text"
+    | "time"
+    | `time (${number})`
+    | `time (${number}) without time zone`
+    | `time with time zone`
+    | `time without time zone`
+    | `time (${number}) with time zone`
+    | "timestamp"
+    | `timestamp (${number})`
+    | `timestamp (${number}) without time zone`
+    | `timestamp with time zone`
+    | `timestamp without time zone`
+    | `timestamp (${number}) with time zone`
+    | "tsquery"
+    | "tsvector"
+    | "txid_snapshot"
+    | "uuid"
+    | "xml";
+
+export type ArrayDataType =
+    | `${ScalarDataType}[${number | ""}]`
+    | `${ScalarDataType}[${number | ""}][${number | ""}]`
+    | `${ScalarDataType}[${number | ""}][${number | ""}][${number | ""}]`
+    | `${ScalarDataType}[${number | ""}][${number | ""}][${number | ""}][${
+          | number
+          | ""}]`
+    | `${ScalarDataType}[${number | ""}][${number | ""}][${number | ""}][${
+          | number
+          | ""}][${number | ""}]`;
+
+export type DataType = ScalarDataType | ArrayDataType;

package/src/schema/types/relations/ManyToManyRelation.ts

@@ -0,0 +1,15 @@
+import { ColumnName } from "../helpers/ColumnName";
+import { ModelName } from "../helpers/ModelName";
+import { LooseModelDefinitions } from "../loose/LooseModelDefinitions";
+
+export type ManyToManyRelation<Models extends LooseModelDefinitions> = {
+    [M2 in ModelName<Models>]: {
+        [J in ModelName<Models>]: {
+            model: M2;
+            through: J;
+            type: "N:N";
+            foreignKey: ColumnName<Models, J> | ColumnName<Models, J>[];
+            otherKey: ColumnName<Models, J> | ColumnName<Models, J>[];
+        };
+    };
+}[ModelName<Models>][ModelName<Models>];

package/src/schema/types/relations/ManyToOneRelation.ts

@@ -0,0 +1,14 @@
+import { ColumnName } from "../helpers/ColumnName";
+import { ModelName } from "../helpers/ModelName";
+import { LooseModelDefinitions } from "../loose/LooseModelDefinitions";
+
+export type ManyToOneRelation<
+    Models extends LooseModelDefinitions,
+    M extends ModelName<Models>,
+> = {
+    [M2 in ModelName<Models>]: {
+        model: M2;
+        type: "N:1";
+        foreignKey: ColumnName<Models, M> | ColumnName<Models, M>[];
+    };
+}[ModelName<Models>];

package/src/schema/types/relations/OneToManyRelation.ts

@@ -0,0 +1,11 @@
+import { ColumnName } from "../helpers/ColumnName";
+import { ModelName } from "../helpers/ModelName";
+import { LooseModelDefinitions } from "../loose/LooseModelDefinitions";
+
+export type OneToManyRelation<Models extends LooseModelDefinitions> = {
+    [M2 in ModelName<Models>]: {
+        model: M2;
+        type: "1:N";
+        foreignKey: ColumnName<Models, M2> | ColumnName<Models, M2>[];
+    };
+}[ModelName<Models>];

package/src/schema/types/strict/ColumnDefinition.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+
+import { SQLStatement } from "../../../sql";
+import { DataType } from "../postgres/DataType";
+
+export type ColumnDefinition<ColumnType = unknown> = {
+    /**
+     * The postgresql datatype of the column.
+     */
+    type: DataType;
+
+    /**
+     * The name of the column in the database. If not specified,
+     * it will be inferred based on the model's field name,
+     * with any column naming function (e.g. `snakeCase`) specified
+     * in the config applied.
+     */
+    name?: string;
+
+    /**
+     * A Zod schema used to infer the type of the column and to
+     * validate/transform data coming from the database.
+     * If not specified, a basic schema will be inferred based on the
+     * postgresql data type of the column. Specifying it
+     * allows to you configure more sophisticated parsing, validation,
+     * and transformations.
+     */
+    zodSchema?: z.ZodType<ColumnType>;
+
+    /**
+     * Are null values allowed in this column?
+     */
+    nullable?: boolean;
+
+    /**
+     * Does this column have a default value? This can be either a value such as a number or string,
+     * or if you want to specify a SQL function for the default, you can use the `sql` tagged
+     * template literal. So examples would include:
+     *
+     * default: 3,
+     *
+     * or
+     *
+     * default: "foo",
+     *
+     * or
+     *
+     * default: sql`uuid_generate_v4()`,
+     */
+    default?: ColumnType | SQLStatement | null;
+
+    /**
+     * Is this column unique? If so, you can specify a where clause to
+     * specify a partial unique index, and whether nulls should be considered
+     * distinct.
+     */
+    unique?: boolean | { where?: SQLStatement; nullsNotDistinct?: boolean };
+
+    /**
+     * Is this column a single-column primary key?
+     */
+    primaryKey?: boolean;
+
+    /**
+     * Is this column a foreign key? If so, you can specify the table and column it references,
+     * and what should happen on update or delete.
+     */
+    references?: {
+        schema?: string;
+        table: string;
+        column: string;
+        onUpdate?: SQLStatement;
+        onDelete?: SQLStatement;
+    };
+};

package/src/schema/types/strict/ModelDefinition.ts

@@ -0,0 +1,47 @@
+import { ForeignKey } from "../constraints/ForeignKey";
+import { UniqueConstraint } from "../constraints/UniqueConstraint";
+import { ColumnDefinition } from "./ColumnDefinition";
+
+/**
+ * Configuration object for a database model.
+ */
+export type ModelDefinition = {
+    /**
+     * The name of the model's table. If not specified, the table name will be
+     * derived from the model name, with any transform function specified in
+     * config applied.
+     */
+    table?: string;
+
+    /**
+     * The schema in which the model sits. If not specified, will use the
+     * schema specified in the global config; if no schema is specified in
+     * the global config, will be set to `public`.
+     */
+    schema?: string;
+
+    /**
+     * The model's column configuration - a map of field name to column
+     * definitions. The keys of this map will be used in generated functions
+     * and object fields, so must be valid Javascript identifiers.
+     */
+    columns: Record<string, ColumnDefinition>;
+
+    /**
+     * If the table's primary key contains multiple columns, specify them here.
+     * If the primary key is on a single column, you can specify it here or in the column definition.
+     */
+    primaryKey?: string[];
+
+    /**
+     * If the table has unique constraints that span multiple columns, you must specify them here.
+     * If the unique constraint is on a single column, you can specify it here or in the column definition.
+     */
+    uniqueConstraints?: UniqueConstraint[];
+
+    /**
+     * If the table has foreign keys, you must specify them here. If the foreign key is on a single column,
+     * you can specify it here or in the column definition.
+     */
+    foreignKeys?: ForeignKey[];
+};

package/src/schema/types/strict/ModelDefinitions.ts

@@ -0,0 +1,3 @@
+import { ModelDefinition } from "./ModelDefinition";
+
+export type ModelDefinitions = Record<string, ModelDefinition>;

package/src/schema/types/strict/RelationDefinition.ts

@@ -0,0 +1,13 @@
+import { ModelName } from "../helpers/ModelName";
+import { ManyToManyRelation } from "../relations/ManyToManyRelation";
+import { ManyToOneRelation } from "../relations/ManyToOneRelation";
+import { OneToManyRelation } from "../relations/OneToManyRelation";
+import { ModelDefinitions } from "./ModelDefinitions";
+
+export type RelationDefinition<
+    Models extends ModelDefinitions,
+    M extends ModelName<Models>,
+> =
+    | OneToManyRelation<Models>
+    | ManyToOneRelation<Models, M>
+    | ManyToManyRelation<Models>;

package/src/schema/types/strict/RelationsDefinition.ts

@@ -0,0 +1,8 @@
+import { ModelName } from "../helpers/ModelName";
+import { ModelDefinitions } from "./ModelDefinitions";
+import { RelationDefinition } from "./RelationDefinition";
+
+export type RelationsDefinition<
+    Models extends ModelDefinitions,
+    M extends ModelName<Models>,
+> = Record<string, RelationDefinition<Models, M>>;

package/src/schema/types/strict/RelationsDefinitions.ts

@@ -0,0 +1,7 @@
+import { ModelName } from "../helpers/ModelName";
+import { ModelDefinitions } from "./ModelDefinitions";
+import { RelationsDefinition } from "./RelationsDefinition";
+
+export type RelationsDefinitions<Models extends ModelDefinitions> = {
+    [M in ModelName<Models>]?: RelationsDefinition<Models, M>;
+};

package/src/schema/validate/validateConfiguration.ts

@@ -0,0 +1,9 @@
+import { BaseConfiguration } from "src/schema/types/base/BaseConfiguration";
+
+import { validateModel } from "./validateModel";
+
+export const validateConfiguration = (config: BaseConfiguration) => {
+    for (const [name, model] of Object.entries(config.models)) {
+        validateModel(config, name, model);
+    }
+};

package/src/schema/validate/validateModel.ts

@@ -0,0 +1,32 @@
+import { uniq } from "lodash-es";
+import { BaseConfiguration } from "src/schema/types/base/BaseConfiguration";
+import { BaseModel } from "src/schema/types/base/BaseModel";
+
+import { InvalidModelDefinitionError } from "../../errors";
+
+export const validateModel = (
+    _config: BaseConfiguration,
+    name: string,
+    model: BaseModel,
+) => {
+    const columns = Object.values(model.columns);
+
+    if (model.table === "") {
+        throw new InvalidModelDefinitionError("Model has empty table name", {
+            model: [name, model],
+        });
+    }
+
+    if (columns.length === 0) {
+        throw new InvalidModelDefinitionError("Model has no columns", {
+            model: [name, model],
+        });
+    }
+
+    if (uniq(columns.map((c) => c.name)).length < columns.length) {
+        throw new InvalidModelDefinitionError(
+            "Model has two columns with the same name",
+            { model: [name, model] },
+        );
+    }
+};

package/src/sql/SQLStatement.test.ts

@@ -0,0 +1,112 @@
+import { unindent } from "@casekit/unindent";
+
+import { describe, expect, test } from "vitest";
+
+import { SQLStatement } from "./SQLStatement";
+import { sql } from "./sql";
+
+describe("SQLStatement", () => {
+    test("It can be created using the `sql` tagged template literal", () => {
+        const title = "my first post";
+        const statement = sql`select * from casekit.post where title = ${title}`;
+        expect(statement).toBeInstanceOf(SQLStatement);
+        expect(statement.text).toEqual(unindent`
+            select * from casekit.post where title = $1
+        `);
+        expect(statement.values).toEqual(["my first post"]);
+    });
+
+    test("Other statement and SQL strings can be appended to it", () => {
+        const title = "my first post";
+        const content = "%cats%";
+        const statement = sql`select *\n`;
+        statement.push(
+            "from casekit.post\n",
+            sql`where title = ${title}\n`,
+            "and 1 = 1\n",
+            sql`and content ilike ${content}\n`,
+            `limit 1`,
+        );
+        expect(statement).toBeInstanceOf(SQLStatement);
+        expect(statement.text).toEqual(unindent`
+            select *
+            from casekit.post
+            where title = $1
+            and 1 = 1
+            and content ilike $2
+            limit 1
+        `);
+        expect(statement.values).toEqual(["my first post", "%cats%"]);
+    });
+
+    test("Interpolated fragments always end with a string even if a variable comes last", () => {
+        const title = "my first post";
+        const content = "%cats%";
+        const statement = sql`select *\n`;
+        statement.push(
+            "from casekit.post\n",
+            sql`where title = ${title}\n`,
+            "and 1 = 1\n",
+            sql`and content ilike ${content}`,
+        );
+        expect(statement).toBeInstanceOf(SQLStatement);
+        expect(statement.text).toEqual(unindent`
+            select *
+            from casekit.post
+            where title = $1
+            and 1 = 1
+            and content ilike $2
+        `);
+        expect(statement.fragments[statement.fragments.length - 1]).toEqual("");
+    });
+
+    test("Identifiers can be interpolated into the SQL string with the .withIdentifiers method", () => {
+        const statement =
+            sql`select * from %I.%I as %I where %I.%I = ${3}`.withIdentifiers(
+                "casekit",
+                "foo",
+                "f",
+                "f",
+                "bar",
+            );
+        expect(statement.text).toEqual(
+            `select * from casekit.foo as f where f.bar = $1`,
+        );
+    });
+
+    test("Identifiers can be interpolated before and after parameters are included", () => {
+        const statement =
+            sql`select * from %I.%I as %I where %I.%I = ${3} and %I.%I = ${"baz"} and %I.%I in (${sql.splat(["quux", "zyzzy"])})`.withIdentifiers(
+                "casekit",
+                "foo",
+                "f",
+                "f",
+                "bar",
+                "f",
+                "baz",
+                "f",
+                "quux",
+            );
+        expect(statement.text).toEqual(
+            `select * from casekit.foo as f where f.bar = $1 and f.baz = $2 and f.quux in ($3, $4)`,
+        );
+        expect(statement.values).toEqual([3, "baz", "quux", "zyzzy"]);
+    });
+
+    test("Empty SQL statements can be interpolated inside SQLStatements", () => {
+        const statement = sql`select * from (${sql`select * from casekit.foo where bar = ${3} and baz = ${"baz"}`}) zyzzy where quux in (${sql``})`;
+        expect(statement.text).toEqual(
+            `select * from (select * from casekit.foo where bar = $1 and baz = $2) zyzzy where quux in ()`,
+        );
+        expect(statement.values).toEqual([3, "baz"]);
+    });
+
+    test("sql.splat allows specifying a separator", () => {
+        const clauses = [sql`foo = ${3}`, sql`bar = ${"baz"}`];
+        const statement = sql`select * from casekit.foo where ${sql.splat(clauses, " and ")}`;
+        expect(statement.text).toEqual(
+            `select * from casekit.foo where foo = $1 and bar = $2`,
+        );
+        expect(statement.values).toEqual([3, "baz"]);
+    });
+});

package/src/sql/SQLStatement.ts

@@ -0,0 +1,86 @@
+/**
+ * This file is heavily inspired by felixfbecker/node-sql-template-strings,
+ * which has the following licence:
+ *
+ * ISC License
+ * Copyright (c) 2016, Felix Frederick Becker
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+import pgfmt from "pg-format";
+
+export class SQLStatement {
+    public fragments: string[];
+    public values: unknown[];
+
+    constructor(
+        sql: readonly string[] | string = [],
+        values: readonly unknown[] = [],
+    ) {
+        this.fragments = typeof sql === "string" ? [sql] : [...sql];
+        this.values = [...values];
+    }
+
+    get text() {
+        return this.fragments.reduce((prev, curr, i) => prev + "$" + i + curr);
+    }
+
+    public push(...args: (SQLStatement | string | null)[]): SQLStatement {
+        for (const arg of args) {
+            if (arg === null) {
+                // do nothing - this case is here as a convenience
+                // for when using functions that might not have any
+                // SQL to return
+            } else if (typeof arg === "string") {
+                if (this.fragments.length === 0) {
+                    this.fragments.push(arg);
+                } else {
+                    this.fragments[this.fragments.length - 1] += arg;
+                }
+            } else {
+                if (arg.fragments.length === 0) {
+                    // do nothing - statement is empty
+                } else if (this.fragments.length === 0) {
+                    this.fragments.push(...arg.fragments);
+                    this.values.push(...arg.values);
+                } else {
+                    this.fragments[this.fragments.length - 1] +=
+                        arg.fragments[0];
+                    this.fragments.push(...arg.fragments.slice(1));
+                    this.values.push(...arg.values);
+                }
+            }
+        }
+        return this;
+    }
+
+    public withIdentifiers(...identifiers: string[]) {
+        const remainingIdentifiers = [...identifiers];
+        for (const index of this.fragments.keys()) {
+            const countPlaceholders =
+                this.fragments[index].match(/%I/g)?.length ?? 0;
+            if (countPlaceholders > 0) {
+                const interpolated = pgfmt(
+                    this.fragments[index],
+                    ...remainingIdentifiers.splice(0, countPlaceholders),
+                );
+                this.fragments[index] = interpolated;
+                if (remainingIdentifiers.length === 0) {
+                    break;
+                }
+            }
+        }
+
+        return this;
+    }
+}

package/src/sql/index.ts

@@ -0,0 +1,2 @@
+export { sql } from "./sql";
+export { SQLStatement } from "./SQLStatement";

package/src/sql/sql.ts

@@ -0,0 +1,47 @@
+import { interleave } from "../util/interleave";
+import { SQLStatement } from "./SQLStatement";
+
+export const sql = (
+    fragments: TemplateStringsArray,
+    ...variables: readonly unknown[]
+) => {
+    /**
+     * This complicated mess allows us to interpolate a SQLStatement
+     * inside a SQLStatement, which is v helpful in eloquently
+     * building up complex statements.
+     */
+    const expandedFragments: string[] = [];
+    const expandedVariables: unknown[] = [];
+    const remainingFragments = [...fragments];
+    const remainingVariables = [...variables];
+    let index = 0;
+
+    while (remainingFragments.length > 0) {
+        const fragment = remainingFragments.shift();
+        const variable = remainingVariables.shift();
+        expandedFragments[index] = (expandedFragments[index] ?? "") + fragment;
+        if (remainingFragments.length > 0) {
+            if (variable instanceof SQLStatement) {
+                if (variable.fragments.length > 0) {
+                    expandedFragments[index] += variable.fragments[0];
+                    expandedFragments.push(...variable.fragments.slice(1));
+                    expandedVariables.push(...variable.values);
+                    index += variable.fragments.length - 1;
+                }
+            } else {
+                expandedVariables.push(variable);
+                index += 1;
+            }
+        }
+    }
+
+    return new SQLStatement(expandedFragments, expandedVariables);
+};
+
+sql.splat = <T>(values: T[], separator = `, `) =>
+    new SQLStatement().push(
+        ...interleave(
+            values.map((v) => sql`${v}`),
+            separator,
+        ),
+    );

package/src/test/db/index.ts

@@ -0,0 +1,27 @@
+import { snakeCase } from "lodash-es";
+import pg from "pg";
+
+import { orm } from "../..";
+import { FindManyParams } from "../../queries/find/types/FindManyParams";
+import { ModelName } from "../../schema/types/helpers/ModelName";
+import { Models, models } from "./models";
+import { Relations, relations } from "./relations";
+
+export const db = orm({
+    models,
+    relations,
+    extensions: ["uuid-ossp"],
+    naming: { column: snakeCase },
+    schema: "casekit",
+    pool: new pg.Pool(),
+});
+
+export type FindMany<M extends ModelName<Models>> = FindManyParams<
+    Models,
+    Relations,
+    M
+>;
+
+export { models, relations };
+export type { Models, Relations };
+export type DB = typeof db;