@afora/drizzle 0.0.0-stage → 0.0.3

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# @afora/drizzle
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A repository provider for [`@afora/core`](../../README.md) on [Drizzle ORM](https://orm.drizzle.team). It implements the provider v2 contract (queries with `where` equality and `in`, `orderBy`, `limit` / `offset`, `withDeleted`, `count`, unique keys, transactions) and passes the `providerContract` kit of `@afora/core/testing` on SQLite (`bun:sqlite`) and Postgres (PGlite). The contract and the kit are described in [docs/repositories.md](../../docs/repositories.md) and [Testing a provider](../../docs/repositories.md#testing-a-provider).
+
+```bash
+bun add @afora/core typebox drizzle-orm @afora/drizzle
+```
+
+`@afora/core` and `drizzle-orm` (`^0.45.4`) are peer dependencies. SQLite and Postgres databases are supported, with any Drizzle driver. MySQL is not (the provider relies on `RETURNING` and `NULLS FIRST/LAST`).
+
+## Example
+
+```ts
+// schema.ts
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+export const users = sqliteTable("users", {
+	id: text("id").primaryKey(),
+	createdAt: text("createdAt").notNull(),
+	updatedAt: text("updatedAt"),
+	deletedAt: text("deletedAt"),
+	name: text("name").notNull(),
+	email: text("email").notNull().unique(),
+	age: integer("age"),
+	address: text("address", { mode: "json" }),
+});
+export const tables = { User: users };
+
+// db.ts
+import { Database } from "bun:sqlite";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+export const db = drizzle(new Database("app.db"));
+
+// app.ts
+import {
+	applicationOf,
+	blueprintOf,
+	entityOf,
+	repositoryOf,
+} from "@afora/core";
+import { drizzleProvider } from "@afora/drizzle";
+import { db } from "./db";
+import { tables } from "./schema";
+
+class User extends entityOf(
+	blueprintOf((ctx) => ({
+		name: ctx.string,
+		email: ctx.email,
+		age: ctx.optionalOf(ctx.integer),
+		address: ctx.optionalOf(blueprintOf((c) => ({ city: c.string }))),
+	})),
+	{ unique: ["email"] },
+) {}
+
+const provider = drizzleProvider({ db, tables });
+export const Users = repositoryOf({
+	entity: User,
+	provider,
+	deletion: "soft",
+	actions: [
+		"create",
+		"findById",
+		"findByEmail",
+		"findMany",
+		"findPage",
+		"update",
+		"delete",
+	],
+});
+
+export const App = applicationOf({
+	name: "app",
+	provider,
+	repositories: [Users],
+});
+
+await Users.create(
+	new User({ name: "Ana", email: "ana@example.com", age: 30 }),
+);
+await Users.findPage({
+	where: { age: { in: [30, 31] } },
+	orderBy: [{ key: "name" }],
+	limit: 20,
+});
+```
+
+`tables` maps a repository to its Drizzle table: by the name of the repository (`UserRepository`, or `<name>Repository` for `repositoryOf({ name })`) and, failing that, by the name of the entity class (`User`). Create the schema with `drizzle-kit` or your own migrations; the provider never changes it.
+
+## Mapping rules
+
+- Column property names must equal the entity keys (`createdAt`, not `created_at`; the SQL name is free). The table needs an `id` column; `createdAt`, `updatedAt` and `deletedAt` are columns like the others, and `deletedAt` makes `withDeleted` and soft deletion work. A stored key with no column throws `InvalidRepositoryDeclaration`.
+- Missing values (`undefined`) are `NULL`, so make optional keys nullable. An update replaces the whole row.
+- Nested records and lists are stored in JSON columns (`text({ mode: "json" })` on SQLite, `jsonb` on Postgres; not `json`, which has no equality). Nested entities are stored by id and loaded through `relations`. Filtering a structure compares the serialized JSON, so key order matters on SQLite.
+- Dates and timestamps: a stored date is an ISO 8601 string. Use a `text` column, or a timestamp with `{ mode: "date" }` (converted both ways; on Postgres use `withTimezone: true`). A Postgres `timestamp` in `mode: "string"` returns a non-ISO string that the entity rejects.
+- Booleans and numbers use the driver's column types (`integer({ mode: "boolean" })` on SQLite).
+
+## Queries
+
+- `where`: equality (`eq`; `undefined`/`null` is `IS NULL`) and `{ in: [...] }`, ANDed across keys. An empty `in` matches nothing.
+- `orderBy`: ascending puts missing values first and descending last (`NULLS FIRST` / `NULLS LAST`). Strings compare by code point: SQLite's default `BINARY` collation does, and on Postgres the provider adds `COLLATE "C"` to `text`, `varchar` and `char` columns. Ties keep insertion order: by `rowid` on SQLite (the table must not be `WITHOUT ROWID`) and, on Postgres, which has no stable physical order, by `id`, which is creation order for UUID v7 ids (the default `Id`).
+- `limit` / `offset`, `withDeleted` (rows with `deletedAt IS NULL` unless true) and `count` (ignores order and pagination) as in the contract.
+
+## Unique keys
+
+`context.unique` (`id` and the entity's `unique` keys) is checked before every `insert` and `update` with a query, so a violation is reported as `RepositoryUniqueViolation` with `details.key` even without a unique index, and soft-deleted rows keep occupying their values. The check does not close the race between concurrent writers: also declare unique indexes. The provider translates the database's unique errors (SQLite `UNIQUE constraint failed`, Postgres `23505`, including a driver error's `cause`) into the same exception, naming the key from the column. `update` and `remove` of an unknown id throw `RepositoryEntityNotFound`.
+
+## Transactions
+
+`capabilities.transactions` is true. `provider.transaction(run)` uses `db.transaction`, and a nested one a savepoint. Synchronous SQLite drivers (`bun:sqlite`, `better-sqlite3`) cannot run an asynchronous `db.transaction` callback, so there the provider issues `BEGIN` / `SAVEPOINT` itself and makes the other operations wait for the transaction, since there is one connection. The scoped provider throws once its callback ends. Use it with `commandOf({ transaction: true })`.
+
+## Codegen and extraction
+
+The package exports the catalog entry for `@afora/codegen`:
+
+```ts
+export const providers = [
+	{ name: "drizzle", module: "@afora/drizzle", export: "drizzleProvider" },
+];
+```
+
+so `afora-codegen generate --providers @afora/drizzle` accepts
+
+```json
+{
+	"provider": {
+		"use": "drizzle",
+		"options": {
+			"db": { "import": "./db.ts#db" },
+			"tables": { "import": "./schema.ts#tables" }
+		}
+	}
+}
+```
+
+and generates `drizzleProvider({ db, tables })`. A Drizzle provider is an opaque provider: `db` and `tables` are not JSON, so `drizzleProvider` does not register a descriptor, and `extractSpec` needs an import mapping for it (`--import provider=./db.ts#provider`) instead of guessing options.
+
+## Tests
+
+`bun run test:drizzle` runs `providerContract` against in-memory `bun:sqlite` and PGlite, plus repository-level tests (relations, soft deletion, `findPage`, a command with a transaction).

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { DrizzleDatabase, DrizzleProviderOptions, DrizzleTable, } from "./provider.js";
+export { drizzleProvider } from "./provider.js";
+/** The provider catalog entries for `afora-codegen --providers`. */
+export declare const providers: readonly [{
+    readonly name: "drizzle";
+    readonly module: "@afora/drizzle";
+    readonly export: "drizzleProvider";
+}];

package/dist/index.js

@@ -0,0 +1,331 @@
+// src/provider.ts
+import {
+  InvalidRepositoryDeclaration,
+  InvalidRepositoryQuery,
+  RepositoryEntityNotFound,
+  RepositoryUniqueViolation
+} from "@afora/core";
+import {
+  and,
+  eq,
+  getTableColumns,
+  inArray,
+  isNull,
+  ne,
+  or,
+  sql
+} from "drizzle-orm";
+var SOURCE = "drizzle";
+var NO_LIMIT = Number.MAX_SAFE_INTEGER;
+function invalid(reason) {
+  throw new InvalidRepositoryDeclaration({
+    source: SOURCE,
+    details: { reason }
+  });
+}
+function badQuery(reason) {
+  throw new InvalidRepositoryQuery({ source: SOURCE, details: { reason } });
+}
+var mappings = new WeakMap;
+function mappingOf(tables, context) {
+  const table = tables[context.name] ?? tables[context.entity.name];
+  if (!table) {
+    return invalid(`No Drizzle table for "${context.name}" (or the entity "${context.entity.name}").`);
+  }
+  let mapping = mappings.get(table);
+  if (!mapping) {
+    const columns = getTableColumns(table);
+    if (!columns.id)
+      invalid(`The table of "${context.name}" has no "id" column.`);
+    mapping = {
+      table,
+      columns,
+      postgres: Object.values(columns).some((column) => column.columnType.startsWith("Pg"))
+    };
+    mappings.set(table, mapping);
+  }
+  return mapping;
+}
+function columnOf(mapping, key) {
+  const column = mapping.columns[key];
+  if (!column)
+    badQuery(`"${key}" is not a column of the table.`);
+  return column;
+}
+var isMissing = (value) => value === undefined || value === null;
+function toColumn(column, value) {
+  if (isMissing(value))
+    return null;
+  if (column.dataType === "date" && typeof value === "string")
+    return new Date(value);
+  return value;
+}
+function fromColumn(value) {
+  return value instanceof Date ? value.toISOString() : value;
+}
+function dataOf(mapping, data) {
+  for (const key of Object.keys(data)) {
+    if (data[key] !== undefined && !(key in mapping.columns))
+      invalid(`"${key}" has no column in the table.`);
+  }
+  const row = {};
+  for (const [key, column] of Object.entries(mapping.columns))
+    row[key] = toColumn(column, data[key]);
+  return row;
+}
+function dataFromRow(row) {
+  const data = {};
+  for (const [key, value] of Object.entries(row)) {
+    if (!isMissing(value))
+      data[key] = fromColumn(value);
+  }
+  return data;
+}
+var isIn = (condition) => typeof condition === "object" && condition !== null && !Array.isArray(condition) && Object.keys(condition).length === 1 && Array.isArray(condition.in);
+function equality(column, value) {
+  return isMissing(value) ? isNull(column) : eq(column, toColumn(column, value));
+}
+function conditionOf(column, condition) {
+  if (!isIn(condition))
+    return equality(column, condition);
+  const present = condition.in.filter((value) => !isMissing(value)).map((value) => toColumn(column, value));
+  const parts = [];
+  if (present.length > 0)
+    parts.push(inArray(column, present));
+  if (present.length < condition.in.length)
+    parts.push(isNull(column));
+  return or(...parts) ?? sql`1 = 0`;
+}
+function whereOf(mapping, query = {}) {
+  const parts = [];
+  for (const [key, condition] of Object.entries(query.where ?? {}))
+    parts.push(conditionOf(columnOf(mapping, key), condition));
+  const deleted = mapping.columns.deletedAt;
+  if (deleted && query.withDeleted !== true)
+    parts.push(isNull(deleted));
+  return and(...parts);
+}
+function collate(mapping, column) {
+  return mapping.postgres && /^Pg(Text|Varchar|Char)/.test(column.columnType) ? sql`${column} COLLATE "C"` : sql`${column}`;
+}
+function orderOf(mapping, query) {
+  const order = [];
+  for (const { key, direction = "asc" } of query.orderBy ?? []) {
+    const column = columnOf(mapping, key);
+    const collated = collate(mapping, column);
+    order.push(direction === "desc" ? sql`${collated} DESC NULLS LAST` : sql`${collated} ASC NULLS FIRST`);
+  }
+  order.push(mapping.postgres ? collate(mapping, columnOf(mapping, "id")) : sql`rowid`);
+  return order;
+}
+function causesOf(error) {
+  const causes = [];
+  let current = error;
+  for (let depth = 0;depth < 6 && current instanceof Error; depth++) {
+    const fields = current;
+    causes.push({
+      message: fields.message,
+      detail: typeof fields.detail === "string" ? fields.detail : "",
+      code: typeof fields.code === "string" ? fields.code : ""
+    });
+    current = current.cause;
+  }
+  return causes;
+}
+function violatedKey(error, mapping) {
+  const names = (column) => Object.entries(mapping.columns).find(([, c]) => c.name === column)?.[0] ?? column;
+  for (const { message, detail, code } of causesOf(error)) {
+    const sqlite = /UNIQUE constraint failed: ([^\n]+)/.exec(message);
+    if (sqlite?.[1]) {
+      const [first = ""] = sqlite[1].split(",");
+      return names(first.trim().split(".").pop() ?? first);
+    }
+    if (code === "23505" || /duplicate key value/.test(message)) {
+      const postgres = /Key \(([^)]+?)\)=/.exec(detail);
+      if (postgres?.[1])
+        return names(postgres[1].split(",")[0]?.trim() ?? "");
+      return "id";
+    }
+  }
+  return;
+}
+function providerOver(tables, exec, hooks) {
+  const select = async (context, query, one) => {
+    const mapping = mappingOf(tables, context);
+    const limit = one ? Math.min(query.limit ?? 1, 1) : query.limit;
+    if (limit === 0)
+      return [];
+    let builder = exec.select().from(mapping.table).where(whereOf(mapping, query)).orderBy(...orderOf(mapping, query));
+    if (limit !== undefined || query.offset)
+      builder = builder.limit(limit ?? NO_LIMIT);
+    if (query.offset)
+      builder = builder.offset(query.offset);
+    return (await builder).map(dataFromRow);
+  };
+  const assertUnique = async (context, mapping, data, own) => {
+    const id = columnOf(mapping, "id");
+    for (const key of context.unique) {
+      const value = data[key];
+      if (isMissing(value) || !(key in mapping.columns))
+        continue;
+      if (own && key === "id")
+        continue;
+      const column = columnOf(mapping, key);
+      const others = own ? ne(id, data.id) : undefined;
+      const [found] = await exec.select({ id }).from(mapping.table).where(and(eq(column, toColumn(column, value)), others)).limit(1);
+      if (found) {
+        throw new RepositoryUniqueViolation({
+          source: context.name,
+          details: { key }
+        });
+      }
+    }
+  };
+  const write = async (context, mapping, work) => {
+    try {
+      return await work();
+    } catch (error) {
+      const key = violatedKey(error, mapping);
+      if (key === undefined)
+        throw error;
+      throw new RepositoryUniqueViolation({
+        source: context.name,
+        details: { key }
+      });
+    }
+  };
+  const notFound = (context, id) => new RepositoryEntityNotFound({ source: context.name, details: { id } });
+  return {
+    capabilities: Object.freeze({ transactions: true }),
+    findOne: (context, query = {}) => hooks.guard(async () => (await select(context, query, true))[0]),
+    findMany: (context, query = {}) => hooks.guard(() => select(context, query, false)),
+    count: (context, query = {}) => hooks.guard(async () => {
+      const mapping = mappingOf(tables, context);
+      const [found] = await exec.select({ total: sql`count(*)` }).from(mapping.table).where(whereOf(mapping, { ...query, limit: undefined }));
+      return Number(found?.total ?? 0);
+    }),
+    insert: (context, data) => hooks.guard(async () => {
+      const mapping = mappingOf(tables, context);
+      const row = dataOf(mapping, data);
+      await assertUnique(context, mapping, data, false);
+      await write(context, mapping, () => exec.insert(mapping.table).values(row));
+    }),
+    update: (context, data) => hooks.guard(async () => {
+      const mapping = mappingOf(tables, context);
+      const row = dataOf(mapping, data);
+      const id = columnOf(mapping, "id");
+      const [existing] = await exec.select({ id }).from(mapping.table).where(eq(id, data.id)).limit(1);
+      if (!existing)
+        throw notFound(context, data.id);
+      await assertUnique(context, mapping, data, true);
+      await write(context, mapping, () => exec.update(mapping.table).set(row).where(eq(id, data.id)));
+    }),
+    remove: (context, id) => hooks.guard(async () => {
+      const mapping = mappingOf(tables, context);
+      const column = columnOf(mapping, "id");
+      const removed = await exec.delete(mapping.table).where(eq(column, id)).returning({ id: column });
+      if (removed.length === 0)
+        throw notFound(context, id);
+    }),
+    transaction: hooks.transaction
+  };
+}
+function whileAlive(alive) {
+  return async (work) => {
+    if (!alive())
+      invalid("The transaction has ended; its provider cannot be used.");
+    return work();
+  };
+}
+var savepoints = 0;
+function nestedTransactions(tables, exec) {
+  return (run) => exec.transaction(async (tx) => {
+    let alive = true;
+    try {
+      return await run(scoped(tables, tx, () => alive));
+    } finally {
+      alive = false;
+    }
+  });
+}
+function scoped(tables, tx, alive) {
+  return providerOver(tables, tx, {
+    guard: whileAlive(alive),
+    transaction: nestedTransactions(tables, tx)
+  });
+}
+function manualScope(tables, db, root, alive) {
+  const state = root ?? { held: undefined };
+  const guard = async (work) => {
+    if (!alive())
+      invalid("The transaction has ended; its provider cannot be used.");
+    if (root === undefined)
+      while (state.held)
+        await state.held;
+    return work();
+  };
+  return providerOver(tables, db, {
+    guard,
+    async transaction(run) {
+      if (root === undefined)
+        while (state.held)
+          await state.held;
+      if (!alive())
+        invalid("The transaction has ended; its provider cannot be used.");
+      let release = () => {};
+      if (root === undefined) {
+        state.held = new Promise((resolve) => {
+          release = resolve;
+        });
+      }
+      const name = `afora_sp_${++savepoints}`;
+      await db.run(root === undefined ? sql`BEGIN` : sql.raw(`SAVEPOINT ${name}`));
+      let open = true;
+      try {
+        const result = await run(manualScope(tables, db, state, () => open && alive()));
+        open = false;
+        await db.run(root === undefined ? sql`COMMIT` : sql.raw(`RELEASE ${name}`));
+        return result;
+      } catch (error) {
+        open = false;
+        if (root === undefined)
+          await db.run(sql`ROLLBACK`);
+        else {
+          await db.run(sql.raw(`ROLLBACK TO ${name}`));
+          await db.run(sql.raw(`RELEASE ${name}`));
+        }
+        throw error;
+      } finally {
+        open = false;
+        if (root === undefined) {
+          state.held = undefined;
+          release();
+        }
+      }
+    }
+  });
+}
+function isSyncSqlite(db) {
+  return db.resultKind === "sync";
+}
+function drizzleProvider(options) {
+  if (!options || typeof options !== "object" || !options.db || typeof options.tables !== "object" || options.tables === null)
+    invalid("Expected { db, tables } with a Drizzle database and its tables.");
+  const { db, tables } = options;
+  const alwaysAlive = () => true;
+  if (isSyncSqlite(db))
+    return manualScope(tables, db, undefined, alwaysAlive);
+  return providerOver(tables, db, {
+    guard: (work) => work(),
+    transaction: nestedTransactions(tables, db)
+  });
+}
+
+// src/index.ts
+var providers = [
+  { name: "drizzle", module: "@afora/drizzle", export: "drizzleProvider" }
+];
+export {
+  drizzleProvider,
+  providers
+};

package/dist/provider.d.ts

@@ -0,0 +1,27 @@
+import { type IRepositoryProvider } from "@afora/core";
+import type { PgDatabase } from "drizzle-orm/pg-core";
+import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
+/** The Drizzle databases the provider supports: SQLite (any driver) and Postgres (any driver). */
+export type DrizzleDatabase = BaseSQLiteDatabase<any, any, any, any> | PgDatabase<any, any, any>;
+/** A Drizzle table of either dialect. */
+export type DrizzleTable = any;
+export interface DrizzleProviderOptions {
+    /** The Drizzle database, or a transaction of it. */
+    readonly db: DrizzleDatabase;
+    /**
+     * The table of each repository: keyed by the name of the repository
+     * (`repositoryOf({ name })`, which defaults to the entity class name) or,
+     * failing that, by the name of the entity class.
+     */
+    readonly tables: Readonly<Record<string, DrizzleTable>>;
+}
+/**
+ * A repository provider over a Drizzle database (SQLite or Postgres) and the
+ * table of each repository. See the package README for the mapping rules.
+ *
+ * The provider is not made with `providerOf`: its `db` and `tables` are not
+ * JSON, so it is an opaque provider, and extracting an application that uses
+ * it needs an import mapping (`provider` / `repositories.<Name>.provider`) that
+ * generates `drizzleProvider({ db, tables })`.
+ */
+export declare function drizzleProvider(options: DrizzleProviderOptions): IRepositoryProvider;

package/package.json

@@ -1,6 +1,60 @@
 {
-  "name": "@afora/drizzle",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@afora/drizzle",
+	"version": "0.0.3",
+	"description": "A repository provider for @afora/core on Drizzle ORM (SQLite and Postgres).",
+	"keywords": [
+		"afora",
+		"drizzle",
+		"drizzle-orm",
+		"repository",
+		"provider",
+		"sqlite",
+		"postgres"
+	],
+	"author": "Alan Reis <alanreisanjo@gmail.com> (https://github.com/Hoyasumii)",
+	"license": "MIT",
+	"homepage": "https://github.com/afora-framework/core/tree/main/packages/drizzle#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/afora-framework/core.git",
+		"directory": "packages/drizzle"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"bun": ">=1.4.4",
+		"node": ">=22"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"typecheck": "bun check",
+		"build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --target node --format esm --packages external --tsconfig-override tsconfig.build.json && tsc -p tsconfig.build.json && bun ../../scripts/add-dts-extensions.ts dist",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@electric-sql/pglite": "0.4.6",
+		"@types/bun": "^1.4.4",
+		"drizzle-orm": "0.45.4",
+		"typebox": "^1.4.3"
+	},
+	"peerDependencies": {
+		"@afora/core": ">=0.0.1",
+		"drizzle-orm": "^0.45.4"
+	}
+}