@elysiumjs/mnemosyne-drizzle 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # @elysiumjs/mnemosyne-drizzle
 
+## 0.4.0
+
+### Minor Changes
+
+- [#15](https://github.com/na2axl/elysiumjs/pull/15) [`fbcc7da`](https://github.com/na2axl/elysiumjs/commit/fbcc7dad127db29da42e7a4a5c2124966731cd88) Thanks [@na2axl](https://github.com/na2axl)! - Resources, queries, units of work and rate limits.
+
+  Breaking:
+
+  - A route with a `response` schema serializes its handler result through it: fields the schema does not declare are dropped, a `Date` becomes an ISO string (`YYYY-MM-DD` for `format: 'date'`), and an object with `toJSON()` becomes what it returns. Set `serialize: false` on a route to send the result as it is.
+
+  Added:
+
+  - `Resource.hidden(schema)` marks a field that never reaches responses nor the OpenAPI document. `Resource.serialize()` and `Resource.project()` are exported for use outside routes.
+  - Sparse fieldsets: `?fields=id,title` keeps only those fields of an object, of each item of an array, or of each item of a `data` array. An unknown or hidden field answers a 400 problem.
+  - Rate limits with `@RateLimit({ window, max, key?, store?, name? })` on routes and controllers (`@RateLimit(false)` turns one off), and a default limit and store in the app's `rateLimit` option, with fixed windows. Responses carry `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`; a client over the limit gets a 429 problem with `Retry-After`. Counts are kept by a `RateLimitStore`: `MemoryRateLimitStore` (core), `RedisRateLimitStore` (`@elysiumjs/redis`) or `WorkersRateLimitStore` over a Cloudflare rate limiting binding (`@elysiumjs/runtime-workers`), which only decides whether a hit is over the limit, so its responses carry no `RateLimit-Reset`.
+  - `ModelResource(model, { hidden, pick, omit, extend })` (`@elysiumjs/mnemosyne`) builds a response schema from a model.
+  - `Query.define(model, spec)` declares the filters (`filter[field][op]=value`), sorts, page size and cursor a list accepts; `Query.schema()` gives its query schema, `Query.parse()` turns a request query into a `ParsedQuery` and answers a 400 problem with a pointer per mistake, and `Query.page()` / `Query.pageSchema()` build cursor pages (`{ data, nextCursor }`).
+  - `DrizzleRepository.list(query)` and `count(query)` run a `ParsedQuery` with keyset pagination (`@elysiumjs/mnemosyne-drizzle`), and `compileQuery()` gives its `where` and `orderBy`.
+  - Units of work: `UnitOfWork.run()` and the `@Transactional()` method decorator run work in one transaction, and `UnitOfWork.afterCommit()` / `afterRollback()` defer work, such as sending a message, until the outermost transaction has ended. `transactional` routes open a unit of work too.
+
+- [#16](https://github.com/na2axl/elysiumjs/pull/16) [`ac96e55`](https://github.com/na2axl/elysiumjs/commit/ac96e55874b0ffe350b287c4278cd85afecb7576) Thanks [@na2axl](https://github.com/na2axl)! - Redis, databases, logs, jobs and builds on Bun, Node.js and Cloudflare Workers.
+
+  Breaking:
+
+  - The level shortcuts of `InteractsWithConsole` (`info`, `success`, `warning`, `error` and `debug`) write a tag (`[I]`, `[S]`, `[W]`, `[E]` and `[D]`, in color) before the message, which `InteractsWithConsole.useTags()` changes. `trace()` writes to stderr.
+  - Outside Bun, a Drizzle connection needs a `driver`. Without one, the `connection` and `client` props are a Bun SQL connection, which is only available on Bun; elsewhere the connection throws `MissingDriverError`, which names the drivers.
+
+  Added:
+
+  - Redis adapters (`@elysiumjs/redis`): `ioredis(create)` plugs an ioredis client into the Redis port on Node.js, and `upstash({ token, url?, fetch? })` talks to Upstash over its REST API, for Workers (no pub/sub). `bunRedis` explains which adapter to use when it runs outside Bun.
+  - Drizzle drivers (`@elysiumjs/mnemosyne-drizzle`): a `DrizzleDriver` port set with the `driver` prop of a connection, and drivers on subpaths so that only the chosen database client is imported: `/bun-sql` (`bunSql()`), `/postgres-js` (`postgresJs()`), `/node-postgres` (`nodePostgres()`) and `/hyperdrive` (`hyperdrive({ binding, driver })`, a client per Worker invocation over a Cloudflare Hyperdrive binding). `DrizzleModule` closes connections through their driver, and `migration:run` runs on any driver.
+  - `InteractsWithConsole.write()` and `Runtime.write()` take the level of the line (`OutputLevel`), which the level shortcuts pass. On Cloudflare Workers, a line is written with the console method of its level, so Workers Logs keep it.
+  - `JsonConsoleLogger` (`@elysiumjs/hermes`): JSON lines through the console of the runtime (warnings and errors on stderr), with levels, error serialization and `child()`. `HermesModule.with({ transport: 'console' | 'pino' })` picks it, and it is the default on Workers. `RequestLogInterceptor` writes one structured line per request: method, route, status, duration, client address and request id.
+  - Scheduled jobs (`@elysiumjs/heracles`): `@Schedule(cron, { timezone, args })` on a job class, a five-field cron parser (`Cron`, with lists, ranges, steps and names), and a `Scheduler` that dispatches the jobs on time on Bun and Node.js, taking a Redis lock per tick when a Redis connection is set. The `heracles:schedule` command runs it.
+  - `@elysiumjs/heracles-workers`: `CloudflareQueueTransport` sends jobs to a Cloudflare Queue (dispatch delays become `delaySeconds`), and `HeraclesWorkersModule` consumes them in the Worker's `queue` handler (ack on success, retry with a delay up to the job's retries) and dispatches the `@Schedule()` jobs whose expression is the cron of a trigger.
+  - Queue handlers (`@elysiumjs/runtime-workers`) can settle a message themselves with `ack()` or `retry({ delaySeconds })`; the messages they leave are acked when no handler failed on them.
+  - `styx build --target node` (`@elysiumjs/hephaestus`) bundles the app into one ES module for Node.js, with decorator metadata emitted at build time, run with `node dist/server.js serve`. `styx build --target workers` runs from the CLI, resolves packages to their browser entry, and leaves Node.js modules imported by bare names to workerd (`nodejs_compat`).
+  - `styx create` (`@elysiumjs/styx`) takes `--runtime bun|node|workers`, `--database`, `--cache` and `--package-manager bun|npm|pnpm`. Each runtime gets its entry, tsconfig types, scripts and drivers: postgres.js and ioredis on Node.js; Hyperdrive, Upstash, console logs and a `wrangler.jsonc` on Workers.
+
+### Patch Changes
+
+- [#11](https://github.com/na2axl/elysiumjs/pull/11) [`632d77b`](https://github.com/na2axl/elysiumjs/commit/632d77b561fc43ade605fb69b06ac1b9b9a2ffc4) Thanks [@na2axl](https://github.com/na2axl)! - Services are identified by their class, or by the name given to `@Service.register({ name })`. Class names are never used as identifiers, so services resolve the same way in minified builds; `bun run check:minified` in core bundles a minified app and checks that every service resolves. `@Service.inject()` without an argument injects the class of the parameter type, and throws when the type is unknown. Factory services in a module's `services` take a class or a name in `name`.
+
+  `ServiceScope.REQUEST` gives one instance per HTTP request, shared by the request's middlewares, controller and handler. `Service.runInRequestScope(fn)` opens a request scope outside a route. Resolving a request-scoped service outside a request throws `OutsideRequestScopeError`, and a singleton (or a server-scoped controller) depending on one throws `ScopeMismatchError`.
+
+  `HermesModule` registers the logger by the `HermesLogger` class and as `logger`.
+
+- Updated dependencies [[`6bc48fe`](https://github.com/na2axl/elysiumjs/commit/6bc48febd51f7090c582e73f349eaeff7261241c), [`e9c3d98`](https://github.com/na2axl/elysiumjs/commit/e9c3d98dd2714b69100215f7c8a80046da463148), [`557a3ca`](https://github.com/na2axl/elysiumjs/commit/557a3cab7af8053a8bab9944e492e5022d91aa82), [`ccc3f5b`](https://github.com/na2axl/elysiumjs/commit/ccc3f5bb904d1bf52d8c72ebf7ea8d10f617a8c4), [`6789879`](https://github.com/na2axl/elysiumjs/commit/678987976ecfd46b534b65276e0de3f448977562), [`87299fd`](https://github.com/na2axl/elysiumjs/commit/87299fd9da82d1a408ced1891c0c3d42991444e5), [`bee66bd`](https://github.com/na2axl/elysiumjs/commit/bee66bdc874b8f23fea356f7d3adf7555a48ca64), [`0057b67`](https://github.com/na2axl/elysiumjs/commit/0057b67df0e3abecab8a9accff6b55a6a64c21df), [`1738567`](https://github.com/na2axl/elysiumjs/commit/17385674c14991f0ddb27eb6ee967afbcebcc307), [`632d77b`](https://github.com/na2axl/elysiumjs/commit/632d77b561fc43ade605fb69b06ac1b9b9a2ffc4), [`1ea417e`](https://github.com/na2axl/elysiumjs/commit/1ea417e3583250bc2f975d795f398b7ff736115d), [`0956186`](https://github.com/na2axl/elysiumjs/commit/0956186db0ca5a83c0a6636aeb2a4c81a0033de4), [`fbcc7da`](https://github.com/na2axl/elysiumjs/commit/fbcc7dad127db29da42e7a4a5c2124966731cd88), [`ac96e55`](https://github.com/na2axl/elysiumjs/commit/ac96e55874b0ffe350b287c4278cd85afecb7576), [`98a16aa`](https://github.com/na2axl/elysiumjs/commit/98a16aae889d46f7a9fb5573188f4cbe3629dd3b)]:
+  - @elysiumjs/core@0.11.0
+  - @elysiumjs/runtime-workers@0.1.0
+  - @elysiumjs/mnemosyne@0.4.0
+
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies [[`68a0cdd`](https://github.com/na2axl/elysiumjs/commit/68a0cdd8b2e4a003d6e0af2d78985623cae40428), [`2c49acd`](https://github.com/na2axl/elysiumjs/commit/2c49acd3b552aa43765d70339fa216961499e1b5), [`76ba0ff`](https://github.com/na2axl/elysiumjs/commit/76ba0ff18f3c196cebc2189426328f67cb699f46), [`4ebf029`](https://github.com/na2axl/elysiumjs/commit/4ebf029611e6d753a4f1bfdbe247a75d954d9ded), [`bacce71`](https://github.com/na2axl/elysiumjs/commit/bacce7146f667a1a46bf474dc0344fb0111ae12a)]:
+  - @elysiumjs/core@0.10.0
+  - @elysiumjs/mnemosyne@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- [`5fef4a7`](https://github.com/na2axl/elysiumjs/commit/5fef4a7199f502fc4fe035299e7670739459a108) Thanks [@na2axl](https://github.com/na2axl)! - Fix tenant isolation, transactions and query caching in the database layer.
+
+  Breaking changes:
+
+  - `TenantMiddleware.validateTenant()` now rejects every tenant unless you override it, and tenant identifiers must match `TENANT_ID_PATTERN` (1 to 63 ASCII letters, digits, `_` or `-`, not starting with `pg_` and other than `information_schema`, in any case) before it is called. Requests that send any other tenant now fail with `Invalid tenant`. Requests without a tenant still resolve to `public` on `SimpleTenantMiddleware`. To migrate, check the tenant against your own data:
+
+    ```ts
+    class OrganizationMiddleware extends SimpleTenantMiddleware {
+    	protected async validateTenant(tenant: string): Promise<boolean> {
+    		return Organization.exists(tenant);
+    	}
+    }
+    ```
+
+  - `getTenantSchema()`, `registerTenantSchema()` and `wrapTenantSchema()` throw on tenant identifiers that do not match `TENANT_ID_PATTERN`.
+  - `setConnectionTenant()` is removed. It set the tenant on a pooled connection for the whole session, so the tenant leaked to other requests. Use `withRLS()`, or `Database.transaction()` in RLS mode, which scope the tenant to a transaction.
+  - `RepositoryInterface.update()` and `delete()`, and the `DrizzleRepository` implementations, return `null` when no row has the id. They returned `undefined` while typed as a row. `DrizzleRepository` also requires a model whose table has an `id` column.
+  - `@transactional` handlers run through the `db.transaction` service that `DrizzleModule` provides (its name is exported by `@elysiumjs/core` as `DATABASE_TRANSACTION_SERVICE`, and still re-exported by `@elysiumjs/mnemosyne`). A transactional handler without a database module now fails with an error naming the service.
+  - `@transactional` generator handlers commit only when the whole stream was sent. A stream closed early, or whose client disconnects (even while the handler is waiting), rolls back.
+  - In RLS mode, a transaction is bound to one tenant for its whole life: the tenant set (with a transaction-local `set_config`) when `Database.transaction()`, a `@transactional` handler, `withRLS()` or `withIsolation()` opens it, from the explicit tenant or the current one (`public` when there is none). Work that finds a transaction open on its connection (`withRLS()`, `withIsolation()`, `Database.transaction()`, repository calls) joins it only when its tenant is the transaction's tenant, and throws `TenantMismatchError` otherwise, without running anything: the tenant of an open transaction never changes. Inside a transaction, `Database.getConnection()` only returns it to work for its tenant (the current tenant, or `public`), and throws `TenantMismatchError` otherwise, so raw queries never run for another tenant; queries on the `tx` handle a callback received run as the transaction's tenant. Work for several tenants, such as an admin fan-out, must use one `withRLS()` per tenant outside any transaction, not nested in one.
+  - In RLS mode, each repository call made outside a transaction runs in its own transaction bound to the current tenant: `BEGIN`, `set_config` of the tenant, the query, `COMMIT`. These calls do not use the query cache, since the cache is bypassed inside transactions. Group calls in `Database.transaction()` or `withRLS()` to share one transaction.
+  - In RLS mode, code running without a tenant in context (background jobs, CLI commands, scripts) is scoped to the `public` tenant. Set the tenant with `withTenant(tenant, () => ...)` around the work (repository calls and `Database.transaction()` then use it), or with `withRLS(tenant, (tx) => ...)`.
+  - `migration:run` validates `--tenant` against `TENANT_ID_PATTERN`. Without a terminal it no longer creates a missing schema: pass `--create-schema` (which also skips the question in a terminal), or it fails.
+  - Query cache keys start with the connection name, and each connection has its own cache transaction scope. When several applications or environments share one cache store and use the same connection names for different databases, set `cache: { prefix }` on each connection: the prefix comes before the connection name in every key (empty by default).
+  - `DrizzleDatabaseCache` keys and values changed: entries written by earlier versions are ignored. The default TTL of cached queries (including with `cache: true`) is now 60 seconds instead of 1 second, and is set with `cache: { ttl }` in seconds.
+  - `Cache.memory` keeps a separate LRU per tag namespace, so `lruSize` applies to each namespace.
+
+  Fixes and additions:
+
+  - In RLS mode, repository operations outside a transaction run in one bound to the current tenant, through the strategy's `withIsolation()`. Transactions opened with `Database.transaction()` or by `@transactional` handlers set the tenant variable when they open. `withIsolation()` and `withRLS()` expose their transaction to repositories and `Database.getConnection()`. `TenantMismatchError` is exported.
+  - `Database.transaction(callback, connection?)` opens a transaction and registers it for the callback. When a transaction is already open on the same connection, the callback joins it (no savepoint: an error rolls back the whole transaction); in RLS mode only if the current tenant is the transaction's tenant (see above). Transactions are tracked by connection, so every name of a connection (`default` and the name it aliases) sees them, and named connections take part in transactions. `Database.getBaseConnection()`, `Database.inTransaction()` and `Database.runInTransaction()` are added. The `db:tx` context entry is still set for the default connection.
+  - `@transactional` generator handlers keep their transaction open until the stream ends, then commit (or roll back if the handler throws). They previously committed before running and failed with `generator.next is not a function`. Generator handlers also see the request context (`tenant`, `http:context`).
+  - The query cache is scoped to the connection and the current tenant, is shared correctly by several app instances (table versions stored in the cache), is not read or written inside transactions, and invalidates the tables a transaction changed once it commits. A result is only stored when no mutation happened since its query started, including when concurrent queries of the same key finish out of order. Cached queries honour Drizzle's `ex`, `px`, `exat`, `pxat` and `keepTtl` options.
+  - Cache namespaces (`Cache.redis.tags(...)`, `Cache.memory.tags(...)`) no longer overwrite each other: reads, deletes and `clear()` stay within their namespace.
+  - `getSessionTenant()` reads the Bun SQL result correctly, and `getCurrentTenant()` works without an application instance (for example under `Application.testing`).
+  - `migration:run` takes an advisory lock per tenant, adds a unique index on `elysium_migrations.name` (also to existing tables), finds the migrations from the project root (`.elysiumrc`), sets the `search_path` for the transaction only, asks before opening the transaction whether to create a missing schema, and always closes its client. Existing duplicate migration names must be removed before the unique index can be created.
+  - `migration:generate` only removes `"public".` qualifiers from the migration it generates, and leaves string literals, comments and dollar-quoted bodies (`DO` blocks, functions) untouched.
+  - `DatabaseDriver.createConnection()` receives the connection name as an optional second argument.
+  - `KeyvRedis` deletes with a single `UNLINK` (or `DEL`) per call or batch and reports failed deletes in `clear()` as `error` events.
+
+### Patch Changes
+
+- [`ea419db`](https://github.com/na2axl/elysiumjs/commit/ea419db) Thanks [@na2axl](https://github.com/na2axl)! - `DrizzleModel()` accepts tables made with `pgTable()` again. Under TypeScript 7 it rejected every concrete table, so models and repositories over them did not typecheck.
+- [`3987671`](https://github.com/na2axl/elysiumjs/commit/3987671) Thanks [@na2axl](https://github.com/na2axl)! - The package only contains its build output, README and changelog. It no longer ships sources, tests or local tool state.
+- Updated dependencies [[`5fef4a7`](https://github.com/na2axl/elysiumjs/commit/5fef4a7199f502fc4fe035299e7670739459a108)]:
+  - @elysiumjs/core@0.9.0
+  - @elysiumjs/mnemosyne@0.3.0
+
 ## 0.2.0
 
 ### Minor Changes

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 <axel.nana@workbud.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 <axel.nana@workbud.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 storage to use.
+     * @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?: 'redis' | 'memory', 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 <axel.nana@workbud.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/commands/migration_run.command.d.ts

@@ -9,5 +9,18 @@ export declare class MigrationRunCommand extends Command {
     private tenant;
     private connection;
     private fresh;
+    private createSchema;
     run(): Promise<void>;
+    /**
+     * Runs the pending migrations in one transaction.
+     * @param sql The client.
+     */
+    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 sql The client.
+     * @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 <axel.nana@workbud.com>
+ */
+export declare const getProjectPath: () => string;
+/**
+ * Gets the directory holding the migrations of the Elysium.js project.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare const getMigrationsPath: () => string;

package/dist/database.d.ts

@@ -1,74 +1,126 @@
 import type { DatabaseCacheConfig, DatabaseDriver } from '@elysiumjs/mnemosyne';
 import type { DrizzleConfig } from 'drizzle-orm';
-import type { BunSQLDatabase } from 'drizzle-orm/bun-sql/postgres';
-import type { CacheConfig } from 'drizzle-orm/cache/core/types';
+import type { PgAsyncDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { DrizzleDriver } from './driver';
+import { ElysiumError } from '@elysiumjs/core';
 import { AbstractDatabase } from '@elysiumjs/mnemosyne';
-import { Table } from 'drizzle-orm';
-import { Cache as DrizzleCache } from 'drizzle-orm/cache/core';
+export { DEFAULT_CACHE_TTL, DrizzleDatabaseCache } from './cache';
 /**
  * Connection configuration for Drizzle ORM.
  *
- * Extends `DrizzleConfig` with connection details and optional caching.
+ * Extends `DrizzleConfig` with the driver and optional caching. Without `driver`, `connection`
+ * or `client` connect with Bun SQL, on Bun only.
  *
  * @author Axel Nana <axel.nana@workbud.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;
-    } & Bun.SQLOptions);
+    } & Record<string, unknown>);
 } | {
-    client: Bun.SQL;
+    client: unknown;
 }) & {
     cache?: true | DatabaseCacheConfig;
 };
 /**
- * A Drizzle database connection backed by Bun's SQL driver.
+ * A Drizzle database connection, whatever its driver.
  * @author Axel Nana <axel.nana@workbud.com>
  */
-export type DrizzleConnection = BunSQLDatabase<Record<string, never>> & {
-    $client: Bun.SQL;
+export type DrizzleConnection = PgAsyncDatabase<DrizzleQueryResultHKT, any> & {
+    $client: any;
 };
 /**
- * Drizzle query cache backed by the framework's cache storage.
- *
- * Extends the Drizzle `Cache` base class and implements the
- * framework's `DatabaseCacheStrategy` interface so that query
- * results can be transparently cached and invalidated.
+ * The query results of a {@link DrizzleConnection}: rows, for `returning()` and selects. What
+ * `execute()` resolves to depends on the driver.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface DrizzleQueryResultHKT extends PgQueryResultHKT {
+    type: this['row'][];
+}
+/**
+ * Closes the client of a connection through its driver.
+ * @internal
+ * @author Axel Nana <axel.nana@workbud.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 <axel.nana@workbud.com>
  */
-export declare class DrizzleDatabaseCache extends DrizzleCache {
-    #private;
-    private readonly cacheStrategy;
-    private readonly globalTtl;
-    private usedTablesPerKey;
-    constructor(cacheStrategy?: 'explicit' | 'all', globalTtl?: number, storageEngine?: 'redis' | 'memory');
-    strategy(): 'explicit' | 'all';
-    get(key: string): 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>;
+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 <axel.nana@workbud.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 <axel.nana@workbud.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 using Bun's built-in SQL client.
+ * Drizzle connections through the {@link DrizzleDriver} of each connection.
  *
  * @author Axel Nana <axel.nana@workbud.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 <axel.nana@workbud.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 <axel.nana@workbud.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 <axel.nana@workbud.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): DrizzleConnection;
+    createConnection(props: DrizzleConnectionProps, name?: string): DrizzleConnection;
     protected driver: DatabaseDriver<DrizzleConnection, DrizzleConnectionProps>;
 }
 /**
@@ -76,4 +128,3 @@ declare class DrizzleDatabase extends AbstractDatabase<DrizzleConnection, Drizzl
  * @author Axel Nana <axel.nana@workbud.com>
  */
 export declare const Database: DrizzleDatabase;
-export {};

package/dist/driver.d.ts

@@ -0,0 +1,39 @@
+import type { DrizzleConfig } from 'drizzle-orm';
+import type { DrizzleDatabaseCache } from './cache';
+import type { DrizzleConnection } from './database';
+import { ElysiumError } from '@elysiumjs/core';
+/**
+ * What a driver connects with: the Drizzle options of the connection and its query cache.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type DrizzleDriverConfig = Omit<DrizzleConfig<Record<string, unknown>>, 'cache'> & {
+    cache?: DrizzleDatabaseCache;
+};
+/**
+ * Connects Drizzle to PostgreSQL through a client: Bun SQL (`/bun-sql`), postgres.js
+ * (`/postgres-js`), node-postgres (`/node-postgres`) or Cloudflare Hyperdrive (`/hyperdrive`).
+ * Implement it to plug in another client.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export interface DrizzleDriver {
+    /** The name of the driver, for errors and logs. */
+    readonly name: string;
+    /**
+     * Creates the Drizzle database of a connection.
+     * @param config The Drizzle options and the query cache.
+     */
+    connect(config: DrizzleDriverConfig): DrizzleConnection;
+    /**
+     * Closes the client of a database the driver created.
+     * @param connection The database.
+     */
+    close(connection: DrizzleConnection): Promise<void> | void;
+}
+/**
+ * Raised when a connection sets no driver outside Bun, where the default Bun SQL driver is not
+ * available.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare class MissingDriverError extends ElysiumError {
+    constructor(name: string);
+}

package/dist/drivers/bun-sql.d.ts

@@ -0,0 +1,25 @@
+import type { SQL } from 'bun';
+import type { DrizzleDriver } from '../driver';
+/**
+ * Options of {@link bunSql}: a connection URL or options, or a client.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type BunSqlDriverOptions = {
+    connection: string | ({
+        url?: string;
+    } & SQL.Options);
+} | {
+    client: SQL;
+};
+/**
+ * Connects with Bun's built-in SQL client. Runs on Bun only.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param options The connection URL or options, or a client.
+ * @example
+ * ```ts
+ * import { bunSql } from '@elysiumjs/mnemosyne-drizzle/bun-sql';
+ *
+ * DrizzleModule.with({ connections: { default: { driver: bunSql({ connection: url }) } } });
+ * ```
+ */
+export declare const bunSql: (options: BunSqlDriverOptions) => DrizzleDriver;

package/dist/drivers/bun-sql.js

@@ -0,0 +1 @@
+import{drizzle}from"drizzle-orm/bun-sql";var bunSql=(options)=>({name:"bun-sql",connect:(config)=>drizzle({...config,...options}),close:async(connection)=>{await connection.$client.close()}});export{bunSql};

package/dist/drivers/hyperdrive.d.ts

@@ -0,0 +1,46 @@
+import type { DrizzleDriver } from '../driver';
+/**
+ * A Hyperdrive binding, as Cloudflare Workers pass it.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type HyperdriveBinding = {
+    readonly connectionString: string;
+};
+/**
+ * Options of {@link hyperdrive}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type HyperdriveDriverOptions = {
+    /** The name of the Hyperdrive binding, as declared in the wrangler config. */
+    binding: string;
+    /**
+     * The driver that connects to the connection string of the binding, such as
+     * `(url) => postgresJs({ connection: { url, max: 5, fetch_types: false } })`.
+     */
+    driver: (connectionString: string) => DrizzleDriver;
+};
+/**
+ * Connects through a Cloudflare Hyperdrive binding. A Worker cannot reuse a socket opened in
+ * another invocation, so the database opens a client per invocation (request, queue batch or
+ * scheduled event) on first use. The runtime closes its sockets when the invocation ends, and
+ * Hyperdrive pools the connections to the database.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param options The binding name and the client driver.
+ * @example
+ * ```ts
+ * import { hyperdrive } from '@elysiumjs/mnemosyne-drizzle/hyperdrive';
+ * import { postgresJs } from '@elysiumjs/mnemosyne-drizzle/postgres-js';
+ *
+ * DrizzleModule.with({
+ * 	connections: {
+ * 		default: {
+ * 			driver: hyperdrive({
+ * 				binding: 'HYPERDRIVE',
+ * 				driver: (url) => postgresJs({ connection: { url, max: 5, fetch_types: false } })
+ * 			})
+ * 		}
+ * 	}
+ * });
+ * ```
+ */
+export declare const hyperdrive: (options: HyperdriveDriverOptions) => DrizzleDriver;

package/dist/drivers/hyperdrive.js

@@ -0,0 +1 @@
+import{Workers}from"@elysiumjs/runtime-workers";var hyperdrive=(options)=>({name:"hyperdrive",connect:(config)=>invocationDatabase(options,config),close:()=>{}}),invocationDatabase=(options,config)=>{let databases=new WeakMap,current=()=>{let context=Workers.context(),database=databases.get(context);if(!database){let{connectionString}=Workers.binding(options.binding);database=options.driver(connectionString).connect(config),databases.set(context,database)}return database};return new Proxy({},{get(target,property){if(Object.hasOwn(target,property))return Reflect.get(target,property);let database=current(),value=Reflect.get(database,property,database);return typeof value==="function"?value.bind(database):value},has(target,property){return Object.hasOwn(target,property)||property in current()},getPrototypeOf(){return Object.getPrototypeOf(current())}})};export{hyperdrive};

package/dist/drivers/node-postgres.d.ts

@@ -0,0 +1,23 @@
+import type { Pool, PoolConfig } from 'pg';
+import type { DrizzleDriver } from '../driver';
+/**
+ * Options of {@link nodePostgres}: a connection URL or pool options, or a pool.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type NodePostgresDriverOptions = {
+    connection: string | PoolConfig;
+} | {
+    client: Pool;
+};
+/**
+ * Connects with node-postgres (`pg`), on Node.js and Bun.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param options The connection URL or pool options, or a pool.
+ * @example
+ * ```ts
+ * import { nodePostgres } from '@elysiumjs/mnemosyne-drizzle/node-postgres';
+ *
+ * DrizzleModule.with({ connections: { default: { driver: nodePostgres({ connection: url }) } } });
+ * ```
+ */
+export declare const nodePostgres: (options: NodePostgresDriverOptions) => DrizzleDriver;

package/dist/drivers/node-postgres.js

@@ -0,0 +1 @@
+import{drizzle}from"drizzle-orm/node-postgres";var nodePostgres=(options)=>({name:"node-postgres",connect:(config)=>drizzle({...config,...options}),close:async(connection)=>{await connection.$client.end()}});export{nodePostgres};

package/dist/drivers/postgres-js.d.ts

@@ -0,0 +1,25 @@
+import type { Options, PostgresType, Sql } from 'postgres';
+import type { DrizzleDriver } from '../driver';
+/**
+ * Options of {@link postgresJs}: a connection URL or options, or a client.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type PostgresJsDriverOptions = {
+    connection: string | ({
+        url?: string;
+    } & Options<Record<string, PostgresType>>);
+} | {
+    client: Sql;
+};
+/**
+ * Connects with postgres.js (`postgres`), on Node.js, Bun and Cloudflare Workers.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @param options The connection URL or options, or a client.
+ * @example
+ * ```ts
+ * import { postgresJs } from '@elysiumjs/mnemosyne-drizzle/postgres-js';
+ *
+ * DrizzleModule.with({ connections: { default: { driver: postgresJs({ connection: url }) } } });
+ * ```
+ */
+export declare const postgresJs: (options: PostgresJsDriverOptions) => DrizzleDriver;

package/dist/drivers/postgres-js.js

@@ -0,0 +1 @@
+import{drizzle}from"drizzle-orm/postgres-js";var postgresJs=(options)=>({name:"postgres-js",connect:(config)=>drizzle({...config,...options}),close:async(connection)=>{await connection.$client.end()}});export{postgresJs};

package/dist/drizzle.module.d.ts

@@ -16,7 +16,7 @@ declare const DrizzleModule_base: (abstract new () => {
     readonly config: DrizzleModuleConfig;
     onInit(): Promise<void> | void;
     onDestroy(): Promise<void> | void;
-    onServe(_app: import("elysia").default<any>): Promise<void> | void;
+    onServe(_app: import("elysia").Elysia<any>): Promise<void> | void;
 }) & {
     readonly config: string;
     with(config: Partial<DrizzleModuleConfig> | (() => Partial<DrizzleModuleConfig> | Promise<Partial<DrizzleModuleConfig>>)): import("@elysiumjs/core").ConfiguredModule<DrizzleModuleConfig>;
@@ -29,8 +29,8 @@ declare const DrizzleModule_base: (abstract new () => {
 };
 /**
  * Declares Drizzle connections as global services named `db.connection.{name}`, plus
- * `db.connection.default` aliasing the configured default, and registers the tenancy config
- * and strategy. Connections are created on first use. Also provides the migration commands.
+ * `db.connection.default` aliasing the configured default, `db.transaction` (used by
+ * `@transactional` handlers), and registers the tenancy config and strategy. Connections are created on first use. Also provides the migration commands.
  * @author Axel Nana <axel.nana@workbud.com>
  */
 export declare class DrizzleModule extends DrizzleModule_base {

package/dist/index.d.ts

@@ -2,9 +2,11 @@ export * from 'drizzle-orm';
 export * from 'drizzle-orm/pg-core';
 export type { SelectedFields, SelectedFieldsFlat, SelectedFieldsOrdered, TableConfig } from 'drizzle-orm/pg-core';
 export { pgTable, getTableBuilders } from './table';
-export { Database, DrizzleDatabaseCache } from './database';
-export type { DrizzleConnectionProps, DrizzleConnection } from './database';
+export { Database, DEFAULT_CACHE_TTL, DrizzleDatabaseCache, TenantMismatchError } from './database';
+export type { DrizzleConnectionProps, DrizzleConnection, DrizzleQueryResultHKT } from './database';
+export { type DrizzleDriver, type DrizzleDriverConfig, MissingDriverError } from './driver';
 export { DrizzleModel, createSchemaFromDrizzle, drizzleAdapter, type DrizzleModelOptions } from './model';
 export { DrizzleModule, type DrizzleModuleConfig } from './drizzle.module';
+export { compileAfter, compileFilter, compileQuery } from './query';
 export { DrizzleRepository } from './repository';
-export { DrizzleSchemaTenancy, DrizzleRLSTenancy, wrapTenantSchema, registerTenantSchema, getTenantSchema, withRLS, setConnectionTenant, getSessionTenant, createRLSPolicy } from './tenancy';
+export { DrizzleSchemaTenancy, DrizzleRLSTenancy, wrapTenantSchema, registerTenantSchema, getTenantSchema, withRLS, getSessionTenant, createRLSPolicy } from './tenancy';