@casekit/orm 0.0.1-alpha.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@casekit/orm",
+  "version": "0.0.1-alpha.0",
+  "description": "A simple ORM",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.js",
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@anatine/zod-mock": "^3.13.4",
+    "@casekit/unindent": "^1.0.3",
+    "@faker-js/faker": "^8.4.1",
+    "@fast-check/vitest": "^0.1.0",
+    "@trivago/prettier-plugin-sort-imports": "^4.3.0",
+    "@types/lodash-es": "^4.17.12",
+    "@types/object-hash": "^3.0.6",
+    "@types/pg": "^8.11.5",
+    "@types/pg-format": "^1.0.5",
+    "@types/pluralize": "^0.0.33",
+    "@types/uuid": "^9.0.8",
+    "@typescript-eslint/eslint-plugin": "^7.6.0",
+    "@vitest/coverage-istanbul": "^1.4.0",
+    "@vitest/coverage-v8": "^1.4.0",
+    "@vitest/ui": "^1.4.0",
+    "dotenv": "^16.4.5",
+    "eslint-import-resolver-typescript": "^3.6.1",
+    "eslint-plugin-import": "^2.29.1",
+    "fast-check": "^3.17.1",
+    "typescript": "^5.4.5",
+    "vite-tsconfig-paths": "^4.3.2",
+    "vitest": "^1.4.0"
+  },
+  "dependencies": {
+    "lodash-es": "^4.17.21",
+    "object-hash": "^3.0.0",
+    "pg": "^8.11.5",
+    "pg-format": "^1.0.4",
+    "pino": "^8.20.0",
+    "pluralize": "^8.0.0",
+    "prettier": "^3.2.5",
+    "ts-toolbelt": "^9.6.0",
+    "uuid": "^9.0.1",
+    "zod": "^3.22.4"
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc",
+    "check:all": "CI=true pnpm test && CI=true pnpm lint && CI=true pnpm prettier && CI=true pnpm typecheck",
+    "lint": "eslint --ignore-path .gitignore --cache --cache-location ./node_modules/.cache/eslint .",
+    "prettier": "prettier -c src",
+    "prettier:write": "prettier -w src",
+    "release": "pnpm build && pnpm version --prerelease --preid=snapshot && pnpm publish --access private",
+    "test": "vitest --typecheck",
+    "test:coverage": "vitest --typecheck --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/Connection.ts

@@ -0,0 +1,65 @@
+import pg, { QueryResultRow } from "pg";
+import pgfmt from "pg-format";
+import * as uuid from "uuid";
+
+import { SQLStatement } from "./sql";
+
+export class Connection {
+    constructor(
+        private pool: pg.Pool,
+        private client?: pg.PoolClient,
+    ) {}
+
+    public query = async <T extends QueryResultRow>(query: SQLStatement) => {
+        if (this.client) {
+            return this.client.query<T>(query);
+        } else {
+            return this.pool.query(query);
+        }
+    };
+
+    public transact = async <T>(
+        fn: (conn: Connection) => Promise<T>,
+        { rollback = false }: { rollback?: boolean } = {},
+    ) => {
+        if (this.client) {
+            const savepoint = uuid.v4();
+            try {
+                await this.client.query(pgfmt("SAVEPOINT %I", savepoint));
+                const result = await fn(this);
+                if (rollback) {
+                    await this.client.query(
+                        pgfmt("ROLLBACK TO SAVEPOINT %I", savepoint),
+                    );
+                } else {
+                    await this.client.query(
+                        pgfmt("RELEASE SAVEPOINT %I", savepoint),
+                    );
+                }
+                return result;
+            } catch (e) {
+                await this.client.query(
+                    pgfmt("ROLLBACK TO SAVEPOINT %I", savepoint),
+                );
+                throw e;
+            }
+        } else {
+            const client = await this.pool.connect();
+            try {
+                await client.query("BEGIN");
+                const result = await fn(new Connection(this.pool, client));
+                if (rollback) {
+                    await client.query("ROLLBACK");
+                } else {
+                    await client.query("COMMIT");
+                }
+                return result;
+            } catch (e) {
+                await client.query("ROLLBACK");
+                throw e;
+            } finally {
+                client.release();
+            }
+        }
+    };
+}

package/src/errors.ts

@@ -0,0 +1,18 @@
+import { BaseModel } from "./schema/types/base/BaseModel";
+
+type OrmErrorMeta = {
+    model?: [string, BaseModel];
+    data?: Record<string, unknown>;
+};
+
+export class OrmError extends Error {
+    meta: OrmErrorMeta | undefined;
+
+    constructor(message: string, meta?: OrmErrorMeta) {
+        super();
+        this.message = message;
+        this.meta = meta;
+    }
+}
+
+export class InvalidModelDefinitionError extends OrmError {}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { OrmError } from "./errors";
+export { migrator, type Migrator } from "./migrate";
+export { Orm, orm } from "./orm";
+export { pull } from "./pull";
+export * from "./queries/clauses/where/operators";
+export { type Middleware } from "./queries/middleware/Middleware";
+/**
+ * TODO find a way to use the strict definitions here
+ * without destroying VS Code autocomplete performance
+ */
+export { type LooseModelDefinition as ModelDefinition } from "./schema/types/loose/LooseModelDefinition";
+export { type LooseRelationsDefinition as RelationsDefinition } from "./schema/types/loose/LooseRelationsDefinition";
+export { SQLStatement, sql } from "./sql";
+export type { ColumnName } from "./types/ColumnName";
+export type { ColumnType } from "./types/ColumnType";
+export type { ModelType } from "./types/ModelType";

package/src/logger.ts

@@ -0,0 +1,3 @@
+import pino from "pino";
+
+export const logger = pino({ enabled: process.env.NODE_ENV !== "test" });

package/src/migrate/commands/implode.ts

@@ -0,0 +1,46 @@
+import { BaseOrm } from "../../schema/types/base/BaseOrm";
+import { SQLStatement } from "../../sql";
+import { createExtensionsSql } from "../sql/createExtensionsSql";
+import { createForeignKeyConstraintSql } from "../sql/createForeignKeyConstraintSql";
+import { createSchemasSql } from "../sql/createSchemasSql";
+import { createTableSql } from "../sql/createTableSql";
+import { createUniqueConstraintSql } from "../sql/createUniqueConstraintSql";
+import { dropSchemasSql } from "../sql/dropSchemasSql";
+
+export const implode = async (
+    db: BaseOrm,
+    { dryRun, output }: { dryRun: boolean; output: boolean },
+) => {
+    const statement = new SQLStatement();
+
+    statement.push(dropSchemasSql(db), "\n");
+    statement.push(createSchemasSql(db), "\n");
+    statement.push(createExtensionsSql(db), "\n");
+
+    for (const model of Object.values(db.models)) {
+        statement.push(createTableSql(model), "\n");
+        for (const constraint of model.uniqueConstraints) {
+            statement.push(createUniqueConstraintSql(model, constraint), "\n");
+        }
+    }
+
+    for (const model of Object.values(db.models)) {
+        for (const foreignKey of model.foreignKeys) {
+            statement.push(
+                createForeignKeyConstraintSql(model, foreignKey),
+                "\n",
+            );
+        }
+    }
+
+    if (output) console.log(statement.text);
+
+    if (!dryRun) {
+        try {
+            await db.connection.query(statement);
+        } catch (e) {
+            console.log(e);
+            throw e;
+        }
+    }
+};

package/src/migrate/index.ts

@@ -0,0 +1 @@
+export { type Migrator, migrator } from "./migrator";

package/src/migrate/migrator.ts

@@ -0,0 +1,24 @@
+import { Orm } from "..";
+import { BaseOrm } from "../schema/types/base/BaseOrm";
+import { LooseModelDefinitions } from "../schema/types/loose/LooseModelDefinitions";
+import { LooseRelationsDefinitions } from "../schema/types/loose/LooseRelationsDefinitions";
+import { implode } from "./commands/implode";
+
+export class Migrator {
+    public db: BaseOrm;
+
+    constructor(db: BaseOrm) {
+        this.db = db;
+    }
+
+    public async implode(opts = { dryRun: true, output: true }) {
+        await implode(this.db, opts);
+    }
+}
+
+export const migrator = <
+    Models extends LooseModelDefinitions,
+    Relations extends LooseRelationsDefinitions<Models>,
+>(
+    db: Orm<Models, Relations>,
+) => new Migrator(db as BaseOrm);

package/src/migrate/sql/createExtensionsSql.test.ts

@@ -0,0 +1,26 @@
+import { unindent } from "@casekit/unindent";
+
+import pg from "pg";
+import { describe, expect, test } from "vitest";
+
+import { orm } from "../../orm";
+import { createExtensionsSql } from "./createExtensionsSql";
+
+describe("createExtensionsSql", () => {
+    test("it generates a CREATE EXTENSION command for each extension", () => {
+        const db = orm({
+            extensions: ["uuid-ossp", "postgis"],
+            models: {},
+            pool: new pg.Pool(),
+        });
+        expect(createExtensionsSql(db)?.text).toEqual(unindent`
+            CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+            CREATE EXTENSION IF NOT EXISTS postgis;
+        `);
+    });
+
+    test("if no extensions are specified, it returns null", () => {
+        const db = orm({ models: {}, pool: new pg.Pool() });
+        expect(createExtensionsSql(db)).toEqual(null);
+    });
+});

package/src/migrate/sql/createExtensionsSql.ts

@@ -0,0 +1,16 @@
+import pgfmt from "pg-format";
+
+import { BaseOrm } from "../../schema/types/base/BaseOrm";
+import { SQLStatement } from "../../sql";
+
+export const createExtensionsSql = (db: BaseOrm): SQLStatement | null => {
+    if (db.config.extensions?.length === 0) return null;
+
+    return (
+        new SQLStatement(
+            db.config.extensions
+                ?.map((e) => pgfmt("CREATE EXTENSION IF NOT EXISTS %I;", e))
+                .join("\n"),
+        ) ?? null
+    );
+};

package/src/migrate/sql/createForeignKeyConstraintSql.test.ts

@@ -0,0 +1,50 @@
+import { unindent } from "@casekit/unindent";
+
+import pg from "pg";
+import { describe, expect, test } from "vitest";
+
+import { ModelDefinition, orm, sql } from "../../";
+import { createForeignKeyConstraintSql } from "./createForeignKeyConstraintSql";
+
+describe("createForeignKeyConstraintSql", () => {
+    test("it generates an ALTER TABLE command for the specified foreign key constraint", () => {
+        const foo = {
+            schema: "casekit",
+            columns: {
+                id: { type: "uuid" },
+                barId: {
+                    name: "bar_id",
+                    type: "uuid",
+                    references: { table: "bar", column: "id" },
+                },
+                bazId: {
+                    name: "baz_id",
+                    type: "uuid",
+                    references: { table: "baz", column: "id" },
+                },
+            },
+            foreignKeys: [
+                {
+                    columns: ["bar_id", "baz_id"],
+                    references: {
+                        table: "quux",
+                        columns: ["bar_id", "baz_id"],
+                    },
+                    onUpdate: sql`CASCADE`,
+                },
+            ],
+        } as const satisfies ModelDefinition;
+
+        const db = orm({ models: { foo }, pool: new pg.Pool() });
+
+        const result = db.models.foo.foreignKeys
+            .map((fk) => createForeignKeyConstraintSql(db.models.foo, fk).text)
+            .join("\n");
+
+        expect(result).toEqual(unindent`
+             ALTER TABLE casekit.foo ADD CONSTRAINT foo_bar_id_baz_id_fkey FOREIGN KEY (bar_id, baz_id) REFERENCES casekit.quux (bar_id, baz_id) ON UPDATE CASCADE;
+             ALTER TABLE casekit.foo ADD CONSTRAINT foo_bar_id_fkey FOREIGN KEY (bar_id) REFERENCES casekit.bar (id);
+             ALTER TABLE casekit.foo ADD CONSTRAINT foo_baz_id_fkey FOREIGN KEY (baz_id) REFERENCES casekit.baz (id);
+        `);
+    });
+});

package/src/migrate/sql/createForeignKeyConstraintSql.ts

@@ -0,0 +1,44 @@
+import pgfmt from "pg-format";
+
+import { SQLStatement } from "../..";
+import { BaseModel } from "../../schema/types/base/BaseModel";
+import { ForeignKey } from "../../schema/types/constraints/ForeignKey";
+
+export const createForeignKeyConstraintSql = (
+    model: BaseModel,
+    constraint: ForeignKey,
+) => {
+    const statement = new SQLStatement();
+    statement.push(
+        pgfmt(`ALTER TABLE %I.%I ADD CONSTRAINT `, model.schema, model.table),
+    );
+
+    statement.push(
+        pgfmt("%I", [model.table, ...constraint.columns, "fkey"].join("_")),
+    );
+
+    statement.push(pgfmt(` FOREIGN KEY (`, model.schema, model.table));
+    statement.push(constraint.columns.map((c) => pgfmt("%I", c)).join(", "));
+    statement.push(")");
+    statement.push(
+        pgfmt(
+            ` REFERENCES %I.%I (`,
+            constraint.references.schema,
+            constraint.references.table,
+        ),
+    );
+    statement.push(
+        constraint.references.columns.map((c) => pgfmt("%I", c)).join(", "),
+    );
+    statement.push(")");
+    if (constraint.onDelete) {
+        statement.push(` ON DELETE `);
+        statement.push(constraint.onDelete);
+    }
+    if (constraint.onUpdate) {
+        statement.push(` ON UPDATE `);
+        statement.push(constraint.onUpdate);
+    }
+    statement.push(";");
+    return statement;
+};

package/src/migrate/sql/createSchemasSql.test.ts

@@ -0,0 +1,81 @@
+import { unindent } from "@casekit/unindent";
+
+import pg from "pg";
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+
+import { ModelDefinition, orm } from "../../";
+import { createSchemasSql } from "./createSchemasSql";
+
+describe("createSchemaSql", () => {
+    test("it generates a CREATE SCHEMA command for each unique schema used", () => {
+        const a = {
+            schema: "foo",
+            columns: {
+                id: { type: "uuid", zodSchema: z.string() },
+            },
+        } as const satisfies ModelDefinition;
+
+        const b = {
+            schema: "bar",
+            columns: {
+                id: { type: "uuid", zodSchema: z.string() },
+            },
+        } as const satisfies ModelDefinition;
+
+        const db = orm({ models: { a, b }, pool: new pg.Pool() });
+        expect(createSchemasSql(db).text).toEqual(unindent`
+            CREATE SCHEMA IF NOT EXISTS foo;
+            CREATE SCHEMA IF NOT EXISTS bar;
+        `);
+    });
+
+    test("it pulls schema from the config if not specified on the model", () => {
+        const a = {
+            columns: {
+                id: { type: "uuid", zodSchema: z.string() },
+            },
+        } as const satisfies ModelDefinition;
+
+        const b = {
+            schema: "bar",
+            columns: {
+                id: { type: "uuid", zodSchema: z.string() },
+            },
+        } as const satisfies ModelDefinition;
+
+        const db = orm({
+            schema: "foo",
+            models: { a, b },
+            pool: new pg.Pool(),
+        });
+        expect(createSchemasSql(db).text).toEqual(unindent`
+            CREATE SCHEMA IF NOT EXISTS foo;
+            CREATE SCHEMA IF NOT EXISTS bar;
+        `);
+    });
+
+    test("if no schema is specified at all, it tries to create the public schema", () => {
+        const a = {
+            columns: {
+                id: { type: "uuid", zodSchema: z.string() },
+            },
+        } as const satisfies ModelDefinition;
+
+        const b = {
+            schema: "bar",
+            columns: {
+                id: { type: "uuid", zodSchema: z.string() },
+            },
+        } as const satisfies ModelDefinition;
+
+        const db = orm({
+            models: { a, b },
+            pool: new pg.Pool(),
+        });
+        expect(createSchemasSql(db).text).toEqual(unindent`
+            CREATE SCHEMA IF NOT EXISTS public;
+            CREATE SCHEMA IF NOT EXISTS bar;
+        `);
+    });
+});

package/src/migrate/sql/createSchemasSql.ts

@@ -0,0 +1,15 @@
+import { uniq } from "lodash-es";
+import pgfmt from "pg-format";
+
+import { BaseOrm } from "../../schema/types/base/BaseOrm";
+import { SQLStatement } from "../../sql";
+
+export const createSchemasSql = (db: BaseOrm): SQLStatement => {
+    const schemas = uniq(Object.values(db.models).map((m) => m.schema));
+
+    return new SQLStatement(
+        schemas
+            .map((s) => pgfmt("CREATE SCHEMA IF NOT EXISTS %I;", s))
+            .join("\n"),
+    );
+};

package/src/migrate/sql/createTableSql.properties.ts

@@ -0,0 +1,38 @@
+import { test } from "@fast-check/vitest";
+import { isEqual } from "lodash-es";
+import pg from "pg";
+import pgfmt from "pg-format";
+
+import { orm } from "../..";
+import * as gen from "../../test/gen";
+import { withRollback } from "../../test/util/withRollback";
+import { createSchemasSql } from "./createSchemasSql";
+import { createTableSql } from "./createTableSql";
+
+test.prop([gen.model()])("should generate valid DDL", async (model) => {
+    return await withRollback(async (client) => {
+        const db = orm({
+            models: { model },
+            relations: { model: {} },
+
+            pool: new pg.Pool(),
+        });
+
+        // create the schema
+        await client.query(createSchemasSql(db));
+
+        // create the table
+        await client.query(createTableSql(db.models.model));
+
+        // select from the newly created table so we can check it's there
+        const result = await client.query(
+            pgfmt("select * from %I.%I", model.schema, model.table),
+        );
+
+        // the selected fields should match the ones defined in the model
+        return isEqual(
+            result.fields.map((f) => f.name),
+            Object.values(model.columns).map((c) => c.name),
+        );
+    });
+});

package/src/migrate/sql/createTableSql.test.ts

@@ -0,0 +1,73 @@
+import { unindent } from "@casekit/unindent";
+
+import { snakeCase, uniqueId } from "lodash-es";
+import pg from "pg";
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+
+import { ModelDefinition, orm } from "../..";
+import { sql } from "../../sql";
+import { db } from "../../test/db";
+import { createTableSql } from "./createTableSql";
+
+describe("createTableSql", () => {
+    test("it generates a CREATE TABLE command", () => {
+        expect(createTableSql(db.models.user).text).toEqual(unindent`
+            CREATE TABLE casekit."user" (
+                id uuid NOT NULL DEFAULT uuid_generate_v4(),
+                username text NOT NULL,
+                created_at timestamp,
+                updated_at timestamp,
+                deleted_at timestamp,
+                PRIMARY KEY (id)
+            );
+        `);
+    });
+
+    test("the generated DDL successfully creates a table", async () => {
+        const table = uniqueId("table-");
+        const post = {
+            table,
+            columns: {
+                id: {
+                    zodSchema: z.string().uuid(),
+                    type: "uuid",
+                    default: sql`uuid_generate_v4()`,
+                },
+                title: {
+                    zodSchema: z.string(),
+                    type: "text",
+                    default: "My first post",
+                },
+                content: { zodSchema: z.string(), type: "text" },
+                publishedAt: {
+                    zodSchema: z.date(),
+                    type: "timestamp",
+                    nullable: true,
+                },
+            },
+        } as const satisfies ModelDefinition;
+        await orm({
+            models: { post },
+            relations: { post: {} },
+            naming: { column: snakeCase },
+            pool: new pg.Pool(),
+        }).transact(
+            async (db) => {
+                await db.connection.query(createTableSql(db.models.post));
+
+                const result = await db.connection.query(
+                    sql`select * from public.%I`.withIdentifiers(table),
+                );
+
+                expect(result.fields.map((f) => f.name)).toEqual([
+                    "id",
+                    "title",
+                    "content",
+                    "published_at",
+                ]);
+            },
+            { rollback: true },
+        );
+    });
+});

package/src/migrate/sql/createTableSql.ts

@@ -0,0 +1,53 @@
+import pgfmt from "pg-format";
+
+import { BaseModel } from "../../schema/types/base/BaseModel";
+import { SQLStatement } from "../../sql";
+import { interleave } from "../../util/interleave";
+
+export const createTableSql = (model: BaseModel): SQLStatement => {
+    const columns = Object.values(model.columns);
+    const primaryKey = model.primaryKey;
+
+    const statement = new SQLStatement();
+
+    statement.push(
+        pgfmt("CREATE TABLE %I.%I (\n", model.schema ?? "public", model.table),
+    );
+
+    statement.push(
+        ...interleave(
+            columns.map((column) => {
+                const definition = new SQLStatement(
+                    pgfmt(`    %I %s`, column.name, column.type),
+                );
+
+                if (!column.nullable) definition.push(pgfmt(" NOT NULL"));
+
+                if (column.default instanceof SQLStatement) {
+                    definition.push(" DEFAULT ");
+                    definition.push(column.default);
+                } else if (
+                    column.default !== null &&
+                    column.default !== undefined
+                ) {
+                    definition.push(pgfmt(" DEFAULT %L", column.default));
+                }
+                return definition;
+            }),
+            ",\n",
+        ),
+    );
+
+    if (primaryKey.length > 0) {
+        statement.push(
+            pgfmt(
+                `,\n    PRIMARY KEY (${primaryKey.map(() => "%I").join(", ")})`,
+                ...primaryKey,
+            ),
+        );
+    }
+
+    statement.push(pgfmt("\n);"));
+
+    return statement;
+};

package/src/migrate/sql/createUniqueConstraintSql.ts

@@ -0,0 +1,27 @@
+import pgfmt from "pg-format";
+
+import { SQLStatement } from "../..";
+import { BaseModel } from "../../schema/types/base/BaseModel";
+import { UniqueConstraint } from "../../schema/types/constraints/UniqueConstraint";
+
+export const createUniqueConstraintSql = (
+    model: BaseModel,
+    constraint: UniqueConstraint,
+) => {
+    const statement = new SQLStatement();
+    statement.push(
+        pgfmt(`CREATE UNIQUE INDEX ON %I.%I (`, model.schema, model.table),
+    );
+    statement.push(constraint.columns.map((c) => pgfmt("%I", c)).join(", "));
+    statement.push(")");
+    if (constraint.nullsNotDistinct) {
+        statement.push(" NULLS NOT DISTINCT");
+    }
+    if (constraint.where) {
+        statement.push(" WHERE (");
+        statement.push(constraint.where);
+        statement.push(")");
+    }
+    statement.push(";");
+    return statement;
+};