@cqrs-ddd/mikro-orm 0.2.0

package/README.md

@@ -0,0 +1,299 @@
+# @cqrs-ddd/mikro-orm
+
+[![npm version](https://img.shields.io/npm/v/@cqrs-ddd/mikro-orm.svg)](https://www.npmjs.com/package/@cqrs-ddd/mikro-orm)
+[![License](https://img.shields.io/npm/l/@cqrs-ddd/mikro-orm.svg)](https://www.npmjs.com/package/@cqrs-ddd/mikro-orm)
+
+MikroORM 7 adapters for [`@cqrs-ddd/core`](https://www.npmjs.com/package/@cqrs-ddd/core):
+authoritative aggregate loading, version-conditioned writes, the persistence dialect
+that maps unique violations and transient failures, a revision-fenced cache stored in
+the database, and the `EntitySchema` mapping of `RootEntity`.
+
+`@cqrs-ddd/core` depends on no ORM; this package is where MikroORM enters. It depends
+on no framework: it works in a plain Node service and in a NestJS application.
+
+## Contents
+
+- [Installation](#installation)
+- [Entity manager source](#entity-manager-source)
+- [Multi-tenant store](#multi-tenant-store)
+- [Loading aggregates](#loading-aggregates)
+- [Version-conditioned writes](#version-conditioned-writes)
+- [Persistence errors](#persistence-errors)
+- [Mapping a root entity](#mapping-a-root-entity)
+- [The database cache](#the-database-cache)
+- [SQL identifiers](#sql-identifiers)
+- [License](#license)
+
+## Installation
+
+```bash
+pnpm add @cqrs-ddd/mikro-orm @cqrs-ddd/core @mikro-orm/core
+```
+
+Requires Node.js 22 or later. `@cqrs-ddd/core` and `@mikro-orm/core` 7 are peer
+dependencies; add the MikroORM driver you use, such as `@mikro-orm/postgresql`.
+
+## Entity manager source
+
+The adapters take an `IEntityManagerSource`, an object with an `em` property, and read
+`em` on every operation. A multi-tenant store can therefore hand out the current
+tenant's manager; a single-database setup can pass `{ em: orm.em.fork() }`.
+
+## Multi-tenant store
+
+`TenantStore` is that source for a multi-tenant application. `em` and `transactional()`
+act on the active tenant, which `tenant()` supplies; `orm(tenant)` returns the initialized
+ORM holding its data. Both throw when there is no tenant or it is unknown: the store never
+falls back to one.
+
+```typescript
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { setPersistenceDialect } from '@cqrs-ddd/core/persistence';
+import { CacheEntrySchema, MikroOrmDialect, TenantStore } from '@cqrs-ddd/mikro-orm';
+import { MikroORM } from '@mikro-orm/core';
+
+const requestTenant = new AsyncLocalStorage<string>();
+const orms = new Map<string, MikroORM>();
+for (const tenant of ['tenant_a', 'tenant_b']) {
+  orms.set(tenant, await MikroORM.init({ ...tenantOptions(tenant), entities: [UserSchema, CacheEntrySchema] }));
+}
+
+const store = new TenantStore({
+  tenant: () => {
+    const tenant = requestTenant.getStore();
+    if (!tenant) throw new Error('No tenant in scope.');
+    return tenant;
+  },
+  orm: (tenant) => {
+    const orm = orms.get(tenant);
+    if (!orm) throw new Error(`Unknown tenant ${tenant}.`);
+    return orm;
+  },
+  isolation: 'database', // one ORM and database per tenant; 'schema': one ORM, a schema per tenant
+});
+
+const [first] = orms.values();
+if (first) setPersistenceDialect(new MikroOrmDialect(first));
+
+await requestTenant.run('tenant_a', () => store.em.findOne(User, { id }));
+await requestTenant.run('tenant_a', () =>
+  store.transactional((em) => em.nativeDelete(CacheEntry, { key })),
+);
+```
+
+With `'schema'` isolation, `orm` returns the same ORM for every tenant and each manager is
+forked with `schema: tenant`; validate the tenant against a known list before it reaches
+the store, for example with `isSqlIdentifier`.
+
+- `em` reuses the contextual manager (a MikroORM `RequestContext` or an active
+  transaction) only when it belongs to the tenant's ORM, configuration, driver and schema,
+  and no other tenant used it first. Otherwise it forks one, with the tenant's schema under
+  `'schema'` isolation.
+- `transactional()` always runs on a fork of its own; a missing or unknown tenant rejects
+  it.
+- The tenant of each manager it hands out is kept in a `WeakMap`: MikroORM objects are
+  never modified.
+
+## Loading aggregates
+
+A command that mutates an aggregate loads it through core's
+`IWriteSideAggregateRepository<TEntity>.findById(id)`. `AggregateRepository` implements
+it: `findById()` reads with `{ refresh: true }`, never touches the cache, rehydrates
+through the `hydrateFn` you pass, and translates driver failures with
+`mapPersistenceError`.
+
+```typescript
+import type { ICache } from '@cqrs-ddd/core/application';
+import { cacheKey, PersistedWrite } from '@cqrs-ddd/core/persistence';
+import { AggregateRepository, type IEntityManagerSource, optimisticUpdate } from '@cqrs-ddd/mikro-orm';
+
+export class UpdateUserRepository extends AggregateRepository<UserSnapshot, User, UserSnapshot> {
+  constructor(cache: ICache<UserSnapshot>, store: IEntityManagerSource) {
+    super(cache, store, User, User.aggregateName, User.fromJSON);
+  }
+
+  @PersistedWrite<User>({
+    cache: { setKey: (user) => cacheKey(User.aggregateName, { id: user.id }) },
+  })
+  async save(user: User): Promise<UserSnapshot> {
+    const snapshot = user.toJSON();
+    await optimisticUpdate(
+      this.store.em,
+      User,
+      user,
+      { username: snapshot.username, updatedAt: snapshot.updatedAt },
+      'User',
+    );
+    return snapshot;
+  }
+}
+
+const users = new UpdateUserRepository(cache, store);
+const user = await users.findById(id); // always the database row, never the cache
+```
+
+## Version-conditioned writes
+
+`optimisticUpdate` and `optimisticDelete` write `WHERE id = ? AND version = expected`,
+check the affected rows, and raise core's `EntityNotFoundException` or
+`ConcurrencyConflictError`. They, and every write whose success triggers acknowledgment
+or cache work, call `assertAutocommit(em, operation)` first: a write inside an outer
+transaction is rejected before any statement runs, because its success would not mean
+durable persistence.
+
+```typescript
+import { ConcurrencyConflictError } from '@cqrs-ddd/core/domain';
+import { optimisticDelete, optimisticUpdate } from '@cqrs-ddd/mikro-orm';
+
+// UPDATE users SET department = ?, updated_at = ?, version = <user.version>
+//   WHERE id = <user.id> AND version = <user.getExpectedVersion()>
+await optimisticUpdate(store.em, User, user, { department: 'Research', updatedAt: user.updatedAt }, 'User');
+
+try {
+  await optimisticDelete(store.em, User, staleUser, 'User');
+} catch (error) {
+  if (error instanceof ConcurrencyConflictError) {
+    // error.expectedVersion is the version staleUser was loaded at; reload and retry
+  }
+  throw error;
+}
+
+await store.em.transactional((em) => optimisticUpdate(em, User, user, fields, 'User')); // rejected
+```
+
+- `data` holds the columns to write; `version` is set from `entity.version`, so a caller
+  lists every other changed column, `updatedAt` included.
+- No matching row: a refreshed read tells a missing row (`EntityNotFoundException`) from a
+  diverged version (`ConcurrencyConflictError`). More than one matching row throws an
+  `Error`.
+- Neither function touches the cache, acknowledges the aggregate or publishes events;
+  `@PersistedWrite`, `@Cache` and `CommandBaseHandler` do that.
+
+## Persistence errors
+
+`MikroOrmDialect` implements core's `IPersistenceDialect`. Register it once the ORM is
+initialized, and `@MapPersistenceErrors` / `@PersistedWrite` map unique violations by
+entity property:
+
+```typescript
+import { setPersistenceDialect } from '@cqrs-ddd/core/persistence';
+import { MikroOrmDialect } from '@cqrs-ddd/mikro-orm';
+
+const orm = await MikroORM.init(options);
+setPersistenceDialect(new MikroOrmDialect(orm));
+
+// in a repository
+@PersistedWrite<User>({ unique: { email: (user) => new UniqueEmailException(user) } })
+async save(user: User): Promise<UserSnapshot> {
+  const snapshot = user.toJSON();
+  await optimisticUpdate(this.store.em, User, user, { email: snapshot.email }, 'User');
+  return snapshot;
+}
+```
+
+A multi-property constraint is keyed by its declared name, passed as the constraint type:
+
+```typescript
+const ROLE_NAME = 'roles_tenant_name_unique';
+// schema: uniques: [{ name: ROLE_NAME, properties: ['tenantId', 'name'] }]
+
+@PersistedWrite<Role, typeof ROLE_NAME>({
+  unique: { [ROLE_NAME]: (role) => new DuplicateRoleNameException(role) },
+})
+```
+
+It reads each entity's unique constraints from the ORM metadata: `unique: true` or
+`unique: 'name'` on a property, and `uniques: [{ name?, properties }]` on the schema. A
+single-property constraint is keyed by that property; a multi-property one by its
+`name`, which it must declare. For a `UniqueConstraintViolationException`, PostgreSQL's
+reported constraint name is matched against the declared name, or the naming strategy's
+`indexName` when none is declared, and SQLite's reported `table.column` list against the
+constraint's columns. Anything else yields no match and the original error is rethrown.
+Construction fails when two constraints of one entity cover the same columns, because
+SQLite could not tell them apart. Declare constraint names in the mapping, never in a
+repository.
+
+`mapPersistenceError(error, operation)` is the `otherwise` translator for transient
+failures: `isTransientPersistenceError` recognizes retryable PostgreSQL SQLSTATEs
+(`40001`, `40P01`, `55P03`, `57P01`–`57P03`, classes `08` and `53`), Node network errors,
+`SQLITE_BUSY`/`SQLITE_LOCKED` and timeouts, through the `cause` chain, and wraps them in
+core's `TransientOperationError`. Any other error is returned unchanged.
+
+## Mapping a root entity
+
+`rootEntityProperties(columns?)` and `versionProperty(column?)` give the `EntitySchema`
+properties every `RootEntity` needs, with timestamps stored as epoch milliseconds
+through `UnixTimestampType`. That type throws a `TypeError` for a value with no valid
+time instead of storing `NaN`. The properties use `accessor: true`, so MikroORM reads
+and writes them through the entity's getters and private setters, and queries use the
+public names.
+
+```typescript
+export const UserSchema = new EntitySchema<User, AggregateRoot>({
+  class: User as any,
+  tableName: 'users',
+  properties: {
+    ...rootEntityProperties(),
+    version: versionProperty(),
+    username: { type: 'string', length: 255, accessor: true },
+    department: { type: 'string', length: 255, nullable: true, accessor: true },
+    email: { type: 'string', length: 320, unique: true },
+  },
+});
+```
+
+`rootEntityProperties({ createdAt: 'created', updatedAt: 'modified' })` renames the
+columns; the defaults are `id`, `created_at` and `updated_at`.
+
+Map a subclass's fields the same way. An entity written without version checks has no
+version column; map its inherited `version` as `{ type: 'number', persist: false }`.
+
+## The database cache
+
+`MikroOrmCache(store, { defaultTtlMs?, logger? })` implements core's `IVersionedCache`
+with one database row per key; every write is a compare-and-set in its own transaction.
+`store` provides `em` and `transactional(work)`. Register `CacheEntrySchema` (or
+`createCacheEntrySchema(table)`) with the ORM, and create the table in a migration with
+`createCacheTableSql(table?)`, which covers PostgreSQL and SQLite.
+
+```typescript
+import { CACHE_TOKEN } from '@cqrs-ddd/core/persistence';
+import { createCacheTableSql, MikroOrmCache } from '@cqrs-ddd/mikro-orm';
+
+// once, in a migration
+await orm.em.getConnection().execute(createCacheTableSql());
+
+const cache = new MikroOrmCache<UserSnapshot>(store, {
+  defaultTtlMs: 5 * 60_000, // 0 never expires
+  logger: { warn: (message) => console.warn(message) },
+});
+const users = new UpdateUserRepository(cache, store);
+const reads = new GetUserRepository(cache, store);
+
+// NestJS
+{
+  provide: CACHE_TOKEN,
+  useFactory: (store: TenantStore) => new MikroOrmCache(store, { logger: new Logger('MikroOrmCache') }),
+  inject: [STORE],
+}
+```
+
+- `store.transactional(work)` must run `work` on a manager of its own, never the caller's
+  request or transaction manager; `TenantStore` does, and so does
+  `{ em: orm.em, transactional: (work) => orm.em.fork().transactional(work) }`.
+- With a `TenantStore`, each tenant's cache rows live in that tenant's database or schema.
+- Reads bypass the identity map, a reader never deletes an expired row, and a corrupted
+  payload throws instead of reading as a miss.
+- `set` and `invalidate` throw when their compare-and-set cannot settle after 16 attempts.
+
+## SQL identifiers
+
+`isSqlIdentifier(name, { qualified? })` accepts an unquoted SQL identifier, optionally
+schema-qualified. Use it before interpolating a name, such as a tenant schema, into SQL
+text, where it cannot be passed as a parameter.
+
+## License
+
+Dual-licensed under **AGPL-3.0-or-later** or a **Commercial License**. See
+[`LICENSE`](https://github.com/aristoteliss/nestjs-pipeline/blob/master/LICENSE) and [`COMMERCIAL_LICENSE.txt`](https://github.com/aristoteliss/nestjs-pipeline/blob/master/COMMERCIAL_LICENSE.txt)
+at the repository root.

package/dist/cache/cache-entry.d.ts

@@ -0,0 +1,43 @@
+import { EntitySchema } from '@mikro-orm/core';
+/**
+ * One row of the {@link MikroOrmCache} table.
+ *
+ * `value` holds the JSON-serialized snapshot, or `''` after an invalidation;
+ * `expiresAt` is epoch milliseconds, or `null` for no expiry; `revision` is the
+ * decimal revision token that fences concurrent fills.
+ */
+export declare class CacheEntry {
+    key: string;
+    value: string;
+    expiresAt: number | null;
+    revision: string;
+}
+/**
+ * SQL that creates the {@link MikroOrmCache} table and its expiry index, for
+ * PostgreSQL and SQLite. Run it once in a migration. It matches
+ * {@link createCacheEntrySchema} for the same `table`.
+ *
+ * It returns two statements, separated by `;`. The table name is validated as a
+ * plain SQL identifier, because it is interpolated, not parameterized.
+ *
+ * @param table - Table name, optionally schema-qualified. Default `'cache'`.
+ *
+ * @example
+ * ```ts
+ * await orm.em.getConnection().execute(createCacheTableSql());
+ * ```
+ */
+export declare function createCacheTableSql(table?: string): string;
+/**
+ * MikroORM entity schema for {@link CacheEntry}. Register it with the ORM that
+ * backs {@link MikroOrmCache}; pass `table` when the table is not named `cache`.
+ *
+ * `expires_at` is a `bigint` column, because epoch milliseconds overflow a
+ * 32-bit integer.
+ *
+ * @param table - Table name, optionally schema-qualified. Default `'cache'`.
+ */
+export declare function createCacheEntrySchema(table?: string): EntitySchema<CacheEntry>;
+/** {@link createCacheEntrySchema} for the default `cache` table. */
+export declare const CacheEntrySchema: EntitySchema<CacheEntry, never, import("@mikro-orm/core").EntityCtor<CacheEntry>>;
+//# sourceMappingURL=cache-entry.d.ts.map

package/dist/cache/cache-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-entry.d.ts","sourceRoot":"","sources":["../../src/cache/cache-entry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB,GAAG,EAAG,MAAM,CAAC;IACb,KAAK,EAAG,MAAM,CAAC;IACf,SAAS,EAAG,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAG,MAAM,CAAC;CACnB;AAYD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,SAAU,GAAG,MAAM,CAU3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,SAAU,GACd,YAAY,CAAC,UAAU,CAAC,CAwB1B;AAED,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,mFAA2B,CAAC"}

package/dist/cache/cache-entry.js

@@ -0,0 +1,92 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheEntrySchema = exports.CacheEntry = void 0;
+exports.createCacheTableSql = createCacheTableSql;
+exports.createCacheEntrySchema = createCacheEntrySchema;
+const core_1 = require("@mikro-orm/core");
+const sql_identifier_1 = require("../helpers/sql-identifier");
+/**
+ * One row of the {@link MikroOrmCache} table.
+ *
+ * `value` holds the JSON-serialized snapshot, or `''` after an invalidation;
+ * `expiresAt` is epoch milliseconds, or `null` for no expiry; `revision` is the
+ * decimal revision token that fences concurrent fills.
+ */
+class CacheEntry {
+    key;
+    value;
+    expiresAt;
+    revision;
+}
+exports.CacheEntry = CacheEntry;
+function assertSafeTable(table) {
+    if (!(0, sql_identifier_1.isSqlIdentifier)(table, { qualified: true })) {
+        throw new Error(`Invalid cache table name "${table}". ` +
+            'Use an unquoted identifier like "cache" or "schema.cache".');
+    }
+    return table;
+}
+/**
+ * SQL that creates the {@link MikroOrmCache} table and its expiry index, for
+ * PostgreSQL and SQLite. Run it once in a migration. It matches
+ * {@link createCacheEntrySchema} for the same `table`.
+ *
+ * It returns two statements, separated by `;`. The table name is validated as a
+ * plain SQL identifier, because it is interpolated, not parameterized.
+ *
+ * @param table - Table name, optionally schema-qualified. Default `'cache'`.
+ *
+ * @example
+ * ```ts
+ * await orm.em.getConnection().execute(createCacheTableSql());
+ * ```
+ */
+function createCacheTableSql(table = 'cache') {
+    const name = assertSafeTable(table);
+    const index = `${name.slice(name.lastIndexOf('.') + 1)}_expires_at_idx`;
+    return `CREATE TABLE IF NOT EXISTS ${name} (
+  key         VARCHAR(255) NOT NULL PRIMARY KEY,
+  value       TEXT         NOT NULL,
+  expires_at  BIGINT,
+  revision    BIGINT       NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS ${index} ON ${name} (expires_at);`;
+}
+/**
+ * MikroORM entity schema for {@link CacheEntry}. Register it with the ORM that
+ * backs {@link MikroOrmCache}; pass `table` when the table is not named `cache`.
+ *
+ * `expires_at` is a `bigint` column, because epoch milliseconds overflow a
+ * 32-bit integer.
+ *
+ * @param table - Table name, optionally schema-qualified. Default `'cache'`.
+ */
+function createCacheEntrySchema(table = 'cache') {
+    const safe = assertSafeTable(table);
+    const index = `${safe.slice(safe.lastIndexOf('.') + 1)}_expires_at_idx`;
+    return new core_1.EntitySchema({
+        class: CacheEntry,
+        tableName: safe,
+        properties: {
+            key: { type: 'string', length: 255, primary: true },
+            value: { type: 'text' },
+            expiresAt: {
+                type: 'number',
+                columnType: 'bigint',
+                fieldName: 'expires_at',
+                nullable: true,
+            },
+            revision: { type: 'bigint', fieldName: 'revision', default: 0 },
+        },
+        indexes: [
+            {
+                name: index,
+                properties: ['expiresAt'],
+            },
+        ],
+    });
+}
+/** {@link createCacheEntrySchema} for the default `cache` table. */
+exports.CacheEntrySchema = createCacheEntrySchema();
+//# sourceMappingURL=cache-entry.js.map

package/dist/cache/cache-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-entry.js","sourceRoot":"","sources":["../../src/cache/cache-entry.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AA4CtE,kDAUC;AAWD,wDA0BC;AAzFD,0CAA+C;AAC/C,8DAA4D;AAE5D;;;;;;GAMG;AACH,MAAa,UAAU;IACrB,GAAG,CAAU;IACb,KAAK,CAAU;IACf,SAAS,CAAiB;IAC1B,QAAQ,CAAU;CACnB;AALD,gCAKC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,IAAI,CAAC,IAAA,gCAAe,EAAC,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CACb,6BAA6B,KAAK,KAAK;YACrC,4DAA4D,CAC/D,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,mBAAmB,CAAC,KAAK,GAAG,OAAO;IACjD,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC;IACxE,OAAO,8BAA8B,IAAI;;;;;;6BAMd,KAAK,OAAO,IAAI,gBAAgB,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,sBAAsB,CACpC,KAAK,GAAG,OAAO;IAEf,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC;IACxE,OAAO,IAAI,mBAAY,CAAa;QAClC,KAAK,EAAE,UAAU;QACjB,SAAS,EAAE,IAAI;QACf,UAAU,EAAE;YACV,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;YACnD,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;YACvB,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,QAAQ;gBACpB,SAAS,EAAE,YAAY;gBACvB,QAAQ,EAAE,IAAI;aACf;YACD,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE;SAChE;QACD,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,KAAK;gBACX,UAAU,EAAE,CAAC,WAAW,CAAC;aAC1B;SACF;KACF,CAAC,CAAC;AACL,CAAC;AAED,oEAAoE;AACvD,QAAA,gBAAgB,GAAG,sBAAsB,EAAE,CAAC"}

package/dist/cache/mikro-orm.cache.d.ts

@@ -0,0 +1,82 @@
+import { type CacheFillOptions, type CacheSetOptions, type CacheStateEntry, type IVersionedCache } from '@cqrs-ddd/core/application';
+import type { ICacheLogger } from '@cqrs-ddd/core/persistence';
+import type { EntityManager } from '@mikro-orm/core';
+import type { IEntityManagerSource } from '../interfaces/entity-manager-source';
+/**
+ * An {@link IEntityManagerSource} that can also run work in a transaction.
+ *
+ * `transactional` must run `work` on a manager dedicated to that call, never on
+ * the caller's request or transaction manager, so the cache's compare-and-set
+ * steps commit on their own and never join a surrounding unit of work.
+ * `em.fork().transactional(work)` satisfies it.
+ */
+export interface ITransactionalEntityManagerSource extends IEntityManagerSource {
+    transactional<T>(work: (em: EntityManager) => Promise<T>): Promise<T>;
+}
+/** Options for {@link MikroOrmCache}. */
+export interface MikroOrmCacheOptions {
+    /** Time to live in milliseconds when a write passes none; `0` never expires. Default 60,000. */
+    readonly defaultTtlMs?: number;
+    /**
+     * Receives cache-maintenance warnings. Defaults to `console.warn` with a
+     * `[MikroOrmCache]` prefix. See {@link ICacheLogger}.
+     */
+    readonly logger?: ICacheLogger;
+}
+/**
+ * MikroORM-backed {@link IVersionedCache}: one row per key in the table mapped by
+ * {@link CacheEntrySchema} (or {@link createCacheEntrySchema}).
+ *
+ * Implements {@link IVersionedCache} with revision-fenced atomic coordination,
+ * bypassing the identity map across all read and mutation operations. Reads use
+ * `store.em`; every write runs in `store.transactional(...)`.
+ *
+ * A plain class with no framework dependency. In a NestJS application, register
+ * it with a factory:
+ *
+ * @example
+ * ```ts
+ * {
+ *   provide: CACHE_TOKEN,
+ *   useFactory: (store: AppStore) =>
+ *     new MikroOrmCache(store, { logger: new Logger('MikroOrmCache') }),
+ *   inject: [STORE],
+ * }
+ * ```
+ */
+export declare class MikroOrmCache<T> implements IVersionedCache<T> {
+    private readonly store;
+    readonly isVersioned: true;
+    private readonly logger;
+    private readonly defaultTtlMs;
+    constructor(store: ITransactionalEntityManagerSource, options?: MikroOrmCacheOptions);
+    /**
+     * Observes the current key state and its revision token.
+     * Reads bypass the identity map to guarantee authoritative persistence visibility.
+     */
+    readState(key: string): Promise<CacheStateEntry<T>>;
+    /**
+     * Atomically advances the revision for `key` and evicts the payload value.
+     * Retains the entry to prevent ABA races during concurrent fills.
+     */
+    invalidate(key: string): Promise<string>;
+    /**
+     * Atomically checks that current revision matches `observedRevision`, writes
+     * value, and advances revision on match.
+     */
+    tryFill(key: string, observedRevision: string, value: T, options?: CacheFillOptions): Promise<boolean>;
+    /**
+     * Get a value from the cache by key. Handles TTL expiry and returns detached clone.
+     */
+    get(key: string): Promise<T | undefined>;
+    /**
+     * Stores a value in the relational cache table with transactional CAS concurrency safety.
+     */
+    set(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    /**
+     * Removes the value and advances the key's revision, as invalidate() does; the
+     * row is kept.
+     */
+    delete(key: string): Promise<void>;
+}
+//# sourceMappingURL=mikro-orm.cache.d.ts.map

package/dist/cache/mikro-orm.cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mikro-orm.cache.d.ts","sourceRoot":"","sources":["../../src/cache/mikro-orm.cache.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAehF;;;;;;;GAOG;AACH,MAAM,WAAW,iCACf,SAAQ,oBAAoB;IAC5B,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACvE;AAED,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,gGAAgG;IAChG,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAmBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,aAAa,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAOvD,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB,QAAQ,CAAC,WAAW,EAAG,IAAI,CAAU;IAErC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGnB,KAAK,EAAE,iCAAiC,EACzD,OAAO,CAAC,EAAE,oBAAoB;IAMhC;;;OAGG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IA4BzD;;;OAGG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAyC9C;;;OAGG;IACG,OAAO,CACX,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,EACxB,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC;IAqDnB;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAK9C;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAwD1E;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzC"}