@elysiumjs/drizzle 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @elysiumjs/drizzle
+
+## 0.1.0
+
+### Minor Changes
+
+- [#112](https://github.com/na2axl/elysiumjs/pull/112) [`72f76ff`](https://github.com/na2axl/elysiumjs/commit/72f76ff2f514aa15dce74d2bc29f0f8429cf5023) Thanks [@na2axl](https://github.com/na2axl)! - `@elysiumjs/drizzle` provides Drizzle ORM for `@elysiumjs/olympus`: database drivers (Bun SQL, postgres.js, node-postgres, Hyperdrive), models, repositories, migrations, tenancy, the moirai stores, the notification and file stores, `rulesToDrizzle()` for abilities as SQL conditions, and the `postgres` lock driver. `@elysiumjs/pino` provides the `pino` logger driver, with pretty output in development.
+
+### Patch Changes
+
+- Updated dependencies [[`72f76ff`](https://github.com/na2axl/elysiumjs/commit/72f76ff2f514aa15dce74d2bc29f0f8429cf5023), [`72f76ff`](https://github.com/na2axl/elysiumjs/commit/72f76ff2f514aa15dce74d2bc29f0f8429cf5023), [`72f76ff`](https://github.com/na2axl/elysiumjs/commit/72f76ff2f514aa15dce74d2bc29f0f8429cf5023)]:
+  - @elysiumjs/olympus@0.25.0
+  - @elysiumjs/workers@0.1.0

package/README.md

@@ -1,3 +1,253 @@
-# Temporary Holding Version
+# @elysiumjs/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.
+The Drizzle ORM backend of [Elysium.js](https://github.com/na2axl/elysiumjs): database connections and drivers for `@elysiumjs/olympus/mnemosyne` (`/bun-sql`, `/postgres-js`, `/node-postgres` and `/hyperdrive` subpaths), models, repositories, queries, migrations and tenancy, the Postgres stores of `@elysiumjs/olympus/moirai`, and the `postgres` driver of the `Lock` port.
+
+## Installation
+
+```bash
+bun add @elysiumjs/olympus @elysiumjs/drizzle
+```
+
+## Usage
+
+Add `DrizzleModule` to your application. It declares the connections as global services, registers the tenancy strategy and provides the `migration:generate` and `migration:run` commands.
+
+```ts
+import { DrizzleModule } from '@elysiumjs/drizzle';
+import { Application } from '@elysiumjs/olympus';
+
+@Application.register({
+	modules: [
+		DrizzleModule.with({
+			default: 'main',
+			connections: {
+				main: { connection: process.env.DATABASE_URL! }
+			}
+		})
+	]
+})
+export class App extends Application {}
+```
+
+`with()` also accepts a function, which is called when the module is booted: `DrizzleModule.with(() => ({ ... }))`. Set `tenancy` to switch between schema (default) and RLS tenancy.
+
+Define models with the enhanced `pgTable`:
+
+```ts
+import { DrizzleModel, pgTable } from '@elysiumjs/drizzle';
+import { Repository } from '@elysiumjs/olympus/mnemosyne';
+import { uuid, varchar } from 'drizzle-orm/pg-core';
+
+const users = pgTable('users', {
+	id: uuid().primaryKey().defaultRandom(),
+	name: varchar({ length: 255 }).notNull()
+});
+
+export class UserModel extends DrizzleModel(users, { supportTenancy: true }) {}
+export class UserRepository extends Repository(UserModel) {}
+```
+
+`Repository(Model)` comes from `@elysiumjs/olympus/mnemosyne` and runs on the Drizzle repository adapter for the models of `DrizzleModel()`: `this.db` is the Drizzle connection (or the transaction open on it), and the scope of `list()`, `count()`, `deleteWhere()` and `Pruner` is an SQL condition. Statements honour the tenant isolation of row-level security; a custom query that must too goes through `this.withConnection((db) => ...)`.
+
+The repository finds rows by the table's primary key. A table without an `id` column, or with a composite primary key, takes the key as an object; `key` names other columns to use instead:
+
+```ts
+export class MembershipRepository extends Repository(MembershipModel) {}
+await memberships.find({ teamId, userId });
+
+export class SessionRepository extends Repository(SessionModel, { key: ['token'] }) {}
+await sessions.find('abc123');
+```
+
+`list(query, scope)` and `count(query, scope)` take a condition the rows must also meet, on top of the filters of the query:
+
+```ts
+public listFor(userId: string, query: ParsedQuery<'cursor'>) {
+	return this.list(query, eq(posts.authorId, userId));
+}
+```
+
+`deleteWhere(scope, limit)` deletes at most `limit` rows of a scope in one statement, partitioned tables included, which is how `Pruner(Model)` jobs delete stale rows chunk by chunk.
+
+### Migration hooks
+
+`migration:run --tenant <name>` applies the pending migrations of a tenant in one transaction, under a lock per tenant. It works on the connection given by `--connection` (`default` when omitted), whose driver runs the migrations: `bun-sql`, `postgres-js` and `node-postgres` do, and `hyperdrive` hands them to the driver it wraps, which needs its binding. A custom driver runs them by implementing `migrations(connection)`, with `templateClientMigrations()` or `nodePostgresMigrations()` for clients like those.
+
+A migration hook runs SQL around the migrations, in the same transaction: when a hook fails, the whole run is rolled back. Register it with `@Migration.hook()` and list it in the `services` of a module. Every method is optional:
+
+```ts
+import type { MigrationHook, MigrationRun, MigrationStep } from '@elysiumjs/drizzle';
+
+import { Migration, sql } from '@elysiumjs/drizzle';
+
+@Migration.hook()
+export class DatabaseHook implements MigrationHook {
+	public async before({ db }: MigrationRun) {
+		await db.execute(sql`CREATE EXTENSION IF NOT EXISTS pgcrypto`);
+	}
+
+	public async beforeEach({ name }: MigrationStep) {}
+
+	public async afterEach({ db, name }: MigrationStep) {
+		const [{ count }] = await db.execute<{ count: number }>(
+			sql`SELECT count(*)::int AS count FROM pg_constraint WHERE ...`
+		);
+		if (count > 0) throw new Error(`${name} adds a foreign key across schemas`);
+	}
+
+	public async after({ db, tenant }: MigrationRun) {
+		await db.execute(sql`GRANT USAGE ON SCHEMA ${sql.identifier(tenant)} TO app`);
+	}
+}
+```
+
+- `before` runs once the tenant schema and the migrations table exist, and `after` at the end. Both also run when no migration is pending, so `after` fits what must stay in place, such as grants or partitions.
+- `beforeEach` runs before each migration, and `afterEach` once it is recorded.
+- A `MigrationRun` holds the transaction (`db`), the `tenant`, the `connection`, the `batch`, the `pending` migrations and the ones `applied` so far. A `MigrationStep` holds the transaction, the `name` and `path` of the migration, and its `run`.
+- `db.execute(query)` runs one statement written with the `sql` template of Drizzle and returns its rows. `db.script(text)` runs several statements without parameters.
+
+Hooks run for every tenant, in the order the modules register them: read `tenant` to act on some tenants only.
+
+### Table markers
+
+`DrizzleTable.define()` marks a table with what `migration:generate` adds to the migration that creates it. Later migrations are left as they are.
+
+```ts
+import { DrizzleTable } from '@elysiumjs/drizzle';
+import { pgSchema, primaryKey, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+
+const kernel = pgSchema('kernel');
+
+export const audit = DrizzleTable.define(
+	DrizzleTable.partitioned({ range: 'recorded_at' }),
+	DrizzleTable.afterCreate(
+		({ qualified }) =>
+			`CREATE TRIGGER audit_append_only BEFORE UPDATE OR DELETE ON ${qualified} FOR EACH ROW EXECUTE FUNCTION forbid_change()`
+	)
+)(
+	kernel.table(
+		'audit',
+		{
+			id: uuid('id').notNull().defaultRandom(),
+			action: text('action').notNull(),
+			recordedAt: timestamp('recorded_at').notNull().defaultNow()
+		},
+		(t) => [primaryKey({ columns: [t.id, t.recordedAt] })]
+	)
+);
+```
+
+- `DrizzleTable.partitioned({ range })` adds `PARTITION BY RANGE (...)` to the `CREATE TABLE`. `range` is a column name in the database, a function returning the column (`(t) => t.recordedAt`), or several of them. The primary key and unique constraints must include those columns.
+- `DrizzleTable.afterCreate(build)` adds SQL right after the table is created, as its own statement. `build` receives the `schema` (`undefined` for `public`), the `name` and the quoted, schema-qualified `qualified` name, and returns a string or a `sql` template.
+- `DrizzleTable.define()` returns the table it marks, so its type is unchanged. Marking a table again adds to its markers.
+
+## Moirai tables
+
+```ts
+import { moiraiTables } from '@elysiumjs/drizzle';
+
+// In the Drizzle schema, so that migration:generate creates them.
+export const billing = moiraiTables('billing');
+```
+
+`moiraiTables(schema?, options?)` builds the `idempotency_keys`, `outbox`, `inbox`, `events` and `projections` tables, in a Postgres schema when one is given (one set of tables per domain schema, for example).
+
+With `{ partitioned: true }`, `events` is partitioned by range of `occurred_at` and `outbox` by range of `created_at`. Their primary and unique keys then include that column, and `migration:generate` creates them with `PARTITION BY RANGE`. The partitions are up to the app: create them in a migration hook, or add them to the migration that creates the table with `DrizzleTable.afterCreate()` from `@elysiumjs/drizzle`:
+
+```ts
+import { DrizzleTable } from '@elysiumjs/drizzle';
+
+const tables = moiraiTables('billing', { partitioned: true });
+
+export const billing = {
+	...tables,
+	events: DrizzleTable.define(
+		DrizzleTable.afterCreate(
+			({ qualified }) => `CREATE TABLE "billing"."events_default" PARTITION OF ${qualified} DEFAULT`
+		)
+	)(tables.events)
+};
+```
+
+## Moirai stores
+
+```ts
+import {
+	DrizzleEventStore,
+	DrizzleIdempotencyStore,
+	DrizzleInboxStore,
+	DrizzleOutboxStore,
+	DrizzleProjectionStorage
+} from '@elysiumjs/drizzle';
+import { Lock } from '@elysiumjs/olympus';
+import { MoiraiModule } from '@elysiumjs/olympus/moirai';
+
+MoiraiModule.with({
+	idempotency: () => new DrizzleIdempotencyStore({ table: billing.idempotencyKeys }),
+	outbox: () => new DrizzleOutboxStore({ table: billing.outbox }),
+	inbox: () => new DrizzleInboxStore({ table: billing.inbox }),
+	lock: () => Lock.for('postgres'),
+	events: () => new DrizzleEventStore({ table: billing.events }),
+	projections: () => new DrizzleProjectionStorage({ table: billing.projections })
+});
+```
+
+- `DrizzleIdempotencyStore` keeps the response of an idempotent action per key.
+- `DrizzleOutboxStore` claims due rows with `FOR UPDATE SKIP LOCKED`, so that several relays never take the same row.
+- `DrizzleInboxStore` records the messages a consumer has processed.
+- `DrizzleEventStore` keeps the event streams of aggregates. An append locks each stream it writes with a transaction advisory lock and checks that the stream ends right before the first appended version, so a stale writer gets a `ConcurrencyConflictError` even when the unique key of the table spans more columns, such as a partition key. Postgres gives each event its `position` and the id of the transaction that wrote it (`transaction_id`).
+- `DrizzleProjectionStorage` resets the tables of the `models` of a projection (`DrizzleModel`s or Drizzle tables) with `DELETE` in the rebuild's transaction, so readers see the rows until it commits, and keeps the version each projection was built with.
+- `PgAdvisoryLock` is the `postgres` driver of the `Lock` port. It serializes the actions that share a `serializeBy` key with a transaction advisory lock, which ends with the transaction. Use it inside a unit of work only: outside a transaction the lock ends with its own statement, so it does not suit the scheduler of `HeraclesModule`.
+
+Each store takes `connection`, the name of a database connection, which defaults to `default`. A store's `table` needs the columns of the matching table in `moiraiTables`, and may add others: it can live in a domain's own `pgSchema` and have another primary key, such as a composite one. `StoreTable<T>` is the type it accepts.
+
+## Notification store
+
+`notificationsTable()` builds the table of the notification store of `@elysiumjs/olympus/hermes`, and `DrizzleNotificationStore` (the `drizzle` driver of `NotificationStore`) keeps the notifications of the `inbox` channel in it:
+
+```ts
+import { notificationsTable } from '@elysiumjs/drizzle';
+import { HermesModule, NotificationStore } from '@elysiumjs/olympus/hermes';
+
+export const notifications = notificationsTable(); // or notificationsTable('notifications', 'social')
+
+HermesModule.with({ store: () => NotificationStore.for('drizzle', { table: notifications }) });
+```
+
+The table keeps one row per delivery id, and has an index on the notifiable and the id, which pages use, and a partial index on unread notifications. Any table with the same columns works, given as `table`, with an optional `connection`.
+
+## File store
+
+`filesTable()` builds the table of the file store of `@elysiumjs/olympus/pithos`, and `DrizzleFileStore` (the `drizzle` driver of `FileStore`) keeps the file records in it:
+
+```ts
+import { filesTable } from '@elysiumjs/drizzle';
+import { FileStore, PithosModule } from '@elysiumjs/olympus/pithos';
+
+export const files = filesTable(); // or filesTable('files', 'media')
+
+PithosModule.with({ disks, files: { store: () => FileStore.for('drizzle', { table: files }) } });
+```
+
+Each change of a record is one conditional `UPDATE`, so only one of two racing requests wins. The table has an index on the owner, a partial index on pending uploads by uploader, which the cap on uploads in progress reads, and a partial index on the files whose time runs out (`pending`, `finishing` and `ready`), which pruning reads. Any table with the same columns works, given as `table`, with an optional `connection`.
+
+## Abilities as SQL
+
+`rulesToDrizzle(ability, action, subject, table)` turns the rules of an ability from `@elysiumjs/olympus/cerberus` into a condition over a table, so a list answers only the rows the same rules let the actor act on:
+
+```ts
+import { rulesToDrizzle } from '@elysiumjs/drizzle';
+import { Cerberus } from '@elysiumjs/olympus/cerberus';
+
+const ability = await Cerberus.ability();
+const editable = await db
+	.select()
+	.from(posts)
+	.where(rulesToDrizzle(ability, 'update', 'Post', posts)); // false without an ability
+```
+
+Rule fields are the properties of the table's columns. A `cannot` bounds every `can` before it. `$eq`, `$ne`, `$in` and `$nin` treat `NULL` as CASL does, and a `cannot` never refuses a row whose condition is unknown because of a `NULL`; `$lt`, `$lte`, `$gt`, `$gte` and `$exists` follow SQL, where `NULL` compares to nothing, so keep the columns they read `NOT NULL` or add an explicit condition. No ability, or no rule that allows the action: `false`; a rule without conditions: `true`. The operators are `$eq`, `$ne`, `$in`, `$nin`, `$lt`, `$lte`, `$gt`, `$gte`, `$exists`, `$and`, `$or` and `$not`; any other operator, or a field the table does not have, throws `UntranslatableRuleError`.
+
+## License
+
+This project is licensed under the Apache License, Version 2.0. See the [LICENSE](../../LICENSE) file for more info.

package/dist/bun-require.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The `require` of the module on Bun (`import.meta.require`), or `undefined` elsewhere. It is read
+ * by key: a bundler turns `import.meta.require` into `createRequire(import.meta.url)` at the top of
+ * the module, which throws on Workers, where `import.meta.url` is undefined.
+ * @internal
+ */
+export declare const bunRequire: () => NodeJS.Require | undefined;

package/dist/cache.d.ts

@@ -0,0 +1,60 @@
+import type { CacheConfig } from 'drizzle-orm/cache/core/types';
+import { Table } from 'drizzle-orm';
+import { Cache as DrizzleCache } from 'drizzle-orm/cache/core';
+/**
+ * Default time to live of cached query results, in seconds.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export declare const DEFAULT_CACHE_TTL = 60;
+/**
+ * Drizzle query cache backed by the framework's cache storage.
+ *
+ * - Results are cached per connection and tenant: every key starts with the configured prefix
+ *   (if any) and the connection name, result keys include the current tenant (or `public`), and
+ *   tags are invalidated for the current tenant. Each connection has its own transaction scope.
+ * - Invalidation works across application instances sharing the cache store: each table has a
+ *   version token in the store, every result records the versions it was read at, and a mutation
+ *   replaces the versions of the tables it touches. Table versions are shared by all tenants, as
+ *   a mutation made for one tenant can change rows other tenants read (shared tables, RLS
+ *   bypass). Every key is written with a TTL.
+ * - A result is only stored when the table versions are still the ones its query started at, and
+ *   every concurrent miss of the key read the same versions: Drizzle does not pair a `put` with its
+ *   `get`, so a result that may predate a mutation is never stored.
+ * - Inside a transaction, the cache is neither read nor written, since the transaction may read
+ *   its own uncommitted changes. Tables mutated in a transaction are invalidated once it commits,
+ *   and not at all when it rolls back.
+ *
+ * Remaining race: a mutation run outside a transaction is invalidated while its statement runs
+ * (Drizzle starts both together), so a read on another connection that completes between the
+ * invalidation and the commit can cache the previous rows until their TTL expires. Mutations run
+ * in a transaction (including RLS-scoped repository calls) are invalidated after the commit and
+ * are not affected.
+ *
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export declare class DrizzleDatabaseCache extends DrizzleCache {
+    #private;
+    /**
+     * @param cacheStrategy Whether queries are cached only when they opt in (`explicit`), or always.
+     * @param globalTtl The default time to live of cached results, in seconds.
+     * @param storageEngine The cache that holds the results: `memory`, or the name of a mnemosyne cache store.
+     * @param connectionName The name of the connection, which prefixes every key.
+     * @param prefix A prefix for every key, before the connection name (empty for none).
+     */
+    constructor(cacheStrategy?: 'explicit' | 'all', globalTtl?: number, storageEngine?: 'memory' | (string & {}), connectionName?: string, prefix?: string);
+    strategy(): 'explicit' | 'all';
+    /**
+     * Runs a transaction so that the cache is bypassed inside it, and the tables it mutates are
+     * invalidated once it commits.
+     * @author Axel Nana <ax.lnana@outlook.com>
+     * @param run Opens and runs the transaction.
+     * @returns The return value of `run`.
+     */
+    trackTransaction<T>(run: () => Promise<T>): Promise<T>;
+    get(key: string, tables?: string[], isTag?: boolean, autoInvalidate?: boolean): Promise<any[] | undefined>;
+    put(key: string, response: any, _tables: string[], isTag: boolean, config?: CacheConfig): Promise<void>;
+    onMutate(params: {
+        tags?: string | string[];
+        tables?: string | string[] | Table<any> | Table<any>[];
+    }): Promise<void>;
+}

package/dist/cerberus.d.ts

@@ -0,0 +1,36 @@
+import type { AnyAbility } from '@casl/ability';
+import type { SQL } from 'drizzle-orm';
+import type { PgTable } from 'drizzle-orm/pg-core';
+import { ElysiumError } from '@elysiumjs/olympus';
+/**
+ * Thrown by `rulesToDrizzle()` when a rule condition names a field the table does not have, or
+ * uses an operator that has no SQL form here.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export declare class UntranslatableRuleError extends ElysiumError {
+    constructor(detail: string);
+}
+/**
+ * The SQL condition that keeps the rows of `table` the ability allows `action` on, from its rules
+ * about `subject`: a list query then answers only what the same rules let the caller act on. CASL
+ * flattens the rules first, so a `cannot` bounds every `can` before it. Rule fields are the
+ * properties of the table's columns. No ability, or no rule that allows the action: `false`; a
+ * rule without conditions: `true`. `$eq`, `$ne`, `$in` and `$nin` treat NULL as CASL does;
+ * `$lt`, `$lte`, `$gt`, `$gte` and `$exists` follow SQL, where NULL compares to nothing.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @param ability The ability, or `undefined` for an actor without one.
+ * @param action The action, such as `update`.
+ * @param subject The subject the rules are about, such as `Post`.
+ * @param table The table of that subject.
+ * @throws {UntranslatableRuleError} When a condition names a field the table does not have, or
+ * uses an operator other than `$eq`, `$ne`, `$in`, `$nin`, `$lt`, `$lte`, `$gt`, `$gte`,
+ * `$exists`, `$and`, `$or` and `$not`.
+ * @example
+ * ```ts
+ * const editable = await db
+ * 	.select()
+ * 	.from(posts)
+ * 	.where(rulesToDrizzle(ability, 'update', 'Post', posts));
+ * ```
+ */
+export declare const rulesToDrizzle: (ability: AnyAbility | undefined, action: string, subject: string, table: PgTable) => SQL;

package/dist/commands/migration_generate.command.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@elysiumjs/olympus';
+/**
+ * Generates migration files, with the markers of `DrizzleTable.define()` applied to the migration that
+ * creates each marked table. The schema is the one of the app: every table, Postgres schema, enum,
+ * sequence, view, role and policy that the project files it loads export, directly or as a value
+ * of an exported object (like the tables `moiraiTables()` builds).
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export declare class MigrationGenerateCommand extends Command {
+    static readonly command: string;
+    static readonly description: string;
+    private name?;
+    run(): Promise<void>;
+}

package/dist/commands/migration_run.command.d.ts

@@ -0,0 +1,26 @@
+import { Command } from '@elysiumjs/olympus';
+/**
+ * Execute migration files.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export declare class MigrationRunCommand extends Command {
+    static readonly command: string;
+    static readonly description: string;
+    private tenant;
+    private connection;
+    private fresh;
+    private createSchema;
+    run(): Promise<void>;
+    /**
+     * Runs the pending migrations in one transaction.
+     * @param connection The migration connection.
+     */
+    private migrate;
+    /**
+     * Checks that the tenant schema exists, or that it may be created: with `--create-schema`, or
+     * when the user agrees. Without a terminal to ask, a missing schema is an error.
+     * @param db The migration connection.
+     * @returns `false` if the schema must not be created.
+     */
+    private ensureSchemaChoice;
+}

package/dist/commands/project.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Gets the root path of the Elysium.js project: the closest parent holding an `.elysiumrc`, or
+ * the current directory when there is none.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export declare const getProjectPath: () => string;
+/**
+ * Gets the directory holding the migrations of the Elysium.js project.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export declare const getMigrationsPath: () => string;

package/dist/commands/schema.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A schema object found in a project file: the export that holds it, and the keys that lead to it
+ * when the export is an object grouping several of them.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export type SchemaExport = {
+    /** The absolute path of the file. */
+    file: string;
+    /** The export name, then the keys inside it: `['tables', 'events']` for `tables.events`. */
+    path: string[];
+};
+/**
+ * Whether a value is something Drizzle Kit generates SQL for: a table, a Postgres schema, an
+ * enum, a sequence, a view, a role or a policy.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @param value The value to check.
+ */
+export declare const isSchemaObject: (value: unknown) => boolean;
+/**
+ * Finds the schema objects that the given modules export, each once: exported directly, or as a
+ * value of an exported plain object (the tables a function builds for a Postgres schema, for
+ * example).
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @param modules The exports of each file, by absolute path.
+ */
+export declare const findSchemaExports: (modules: Iterable<[file: string, exports: Record<string, unknown>]>) => SchemaExport[];
+/**
+ * Lists the source files of the project that the app has loaded, outside `node_modules`.
+ * Importing the app loads every model its modules use, whatever the file name; importing a loaded
+ * file again gives back its exports without running it.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @param projectPath The root of the project.
+ * @param loaded The paths of the loaded files, the keys of the module cache.
+ */
+export declare const loadedProjectFiles: (projectPath: string, loaded: Iterable<string>) => string[];
+/**
+ * Finds the schema objects of the app: the ones the project files it loaded export.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @param projectPath The root of the project.
+ */
+export declare const collectAppSchema: (projectPath: string) => Promise<SchemaExport[]>;
+/**
+ * Writes the source of a schema file that exports every given schema object at its top level,
+ * where Drizzle Kit looks for them.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @param exports The schema objects to export.
+ */
+export declare const renderSchemaEntry: (exports: SchemaExport[]) => string;

package/dist/database.d.ts

@@ -0,0 +1,137 @@
+import type { DatabaseCacheConfig, DatabaseDriver } from '@elysiumjs/olympus/mnemosyne';
+import type { DrizzleConfig } from 'drizzle-orm';
+import type { PgAsyncDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { DrizzleDriver } from './driver';
+import { ElysiumError } from '@elysiumjs/olympus';
+import { AbstractDatabase } from '@elysiumjs/olympus/mnemosyne';
+export { DEFAULT_CACHE_TTL, DrizzleDatabaseCache } from './cache';
+/**
+ * Connection configuration for Drizzle ORM.
+ *
+ * Extends `DrizzleConfig` with the driver and optional caching. Without `driver`, `connection`
+ * or `client` connect with Bun SQL, on Bun only.
+ *
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @template TSchema The Drizzle schema type.
+ */
+export type DrizzleConnectionProps<TSchema extends Record<string, unknown> = Record<string, never>> = Omit<DrizzleConfig<TSchema>, 'cache'> & ({
+    driver: DrizzleDriver;
+} | {
+    connection: string | ({
+        url?: string;
+    } & Record<string, unknown>);
+} | {
+    client: unknown;
+}) & {
+    cache?: true | DatabaseCacheConfig;
+};
+/**
+ * A Drizzle database connection, whatever its driver.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export type DrizzleConnection = PgAsyncDatabase<DrizzleQueryResultHKT, any> & {
+    $client: any;
+};
+/**
+ * The query results of a {@link DrizzleConnection}: rows, for `returning()` and selects. What
+ * `execute()` resolves to depends on the driver.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export interface DrizzleQueryResultHKT extends PgQueryResultHKT {
+    type: this['row'][];
+}
+/**
+ * The driver of a connection.
+ * @internal
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @param connection The connection.
+ */
+export declare const getConnectionDriver: (connection: DrizzleConnection) => DrizzleDriver | undefined;
+/**
+ * Closes the client of a connection through its driver.
+ * @internal
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @param connection The connection.
+ */
+export declare const closeConnection: (connection: DrizzleConnection) => Promise<void>;
+/**
+ * Thrown in RLS mode when work for one tenant would join a transaction bound to another.
+ *
+ * A transaction is bound to the tenant set when it is opened, for its whole life. Work for another
+ * tenant must run outside the transaction, or in its own `withRLS()` before the transaction opens.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export declare class TenantMismatchError extends ElysiumError {
+    readonly transactionTenant: string | null;
+    readonly tenant: string;
+    /**
+     * @param transactionTenant The tenant the open transaction is bound to, or `null` if none.
+     * @param tenant The tenant of the work that tried to join it.
+     */
+    constructor(transactionTenant: string | null, tenant: string);
+}
+/**
+ * Binds a transaction to a tenant: sets the RLS tenant variable for the rest of the transaction.
+ * @internal
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @param tx The transaction, just opened.
+ * @param tenant The tenant identifier.
+ */
+export declare const bindTransactionTenant: (tx: DrizzleConnection, tenant: string) => Promise<void>;
+/**
+ * Checks that work for a tenant may join an open transaction: it must be bound to that tenant.
+ * @internal
+ * @author Axel Nana <ax.lnana@outlook.com>
+ * @param tx The open transaction.
+ * @param tenant The tenant of the work.
+ * @throws {TenantMismatchError} If the transaction is bound to another tenant, or to none.
+ */
+export declare const assertTransactionTenant: (tx: DrizzleConnection, tenant: string) => void;
+/**
+ * Drizzle-specific database manager.
+ *
+ * Implements the abstract database class with a driver that creates
+ * Drizzle connections through the {@link DrizzleDriver} of each connection.
+ *
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+declare class DrizzleDatabase extends AbstractDatabase<DrizzleConnection, DrizzleConnectionProps> {
+    /**
+     * Retrieves the connection with the given name, or the transaction open on it.
+     *
+     * In RLS mode, an open transaction bound to a tenant is only returned to work for that tenant,
+     * the current one (or `public`).
+     * @author Axel Nana <ax.lnana@outlook.com>
+     * @param name The connection name.
+     * @returns The connection, or its open transaction.
+     * @throws {TenantMismatchError} If the open transaction is bound to another tenant.
+     */
+    getConnection(name?: string): DrizzleConnection;
+    /**
+     * Runs a callback in a transaction, joining the one open on the connection if any.
+     *
+     * In RLS mode, a new transaction is bound to the current tenant (or `public`), and an open one
+     * is only joined when it is bound to the current tenant.
+     * @author Axel Nana <ax.lnana@outlook.com>
+     * @param callback The function to run with the transaction.
+     * @param name The connection name.
+     * @returns The return value of the callback.
+     * @throws {TenantMismatchError} If the open transaction is bound to another tenant.
+     */
+    transaction<T>(callback: (tx: DrizzleConnection) => Promise<T>, name?: string): Promise<T>;
+    /**
+     * Creates a Drizzle connection from its properties. Used by the `DrizzleModule` to build
+     * the `db.connection.{name}` services.
+     * @author Axel Nana <ax.lnana@outlook.com>
+     * @param props The connection properties.
+     * @param name The name of the connection, which scopes its query cache.
+     * @returns A new connection.
+     */
+    createConnection(props: DrizzleConnectionProps, name?: string): DrizzleConnection;
+    protected driver: DatabaseDriver<DrizzleConnection, DrizzleConnectionProps>;
+}
+/**
+ * Singleton Drizzle database manager.
+ * @author Axel Nana <ax.lnana@outlook.com>
+ */
+export declare const Database: DrizzleDatabase;