@tsnx/mikro-orm 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TSNX Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @tsnx/mikro-orm
 
-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.
+> MikroORM integration provider for TSNX Data, implementing EF Core-inspired DbContext, Scoped EntityManager forks, IDbContextFactory, and Optimistic Concurrency mapping.
+
+## Key Features
+
+- **`MikroDbContext`**: Integrates MikroORM's `EntityManager` into TSNX's `DbContext` and `IUnitOfWork` contracts.
+- **Scoped Identity Map**: Forked per HTTP request or background work scope (`MIKRO_ORM_EM`), preventing cross-request state pollution.
+- **`IDbContextFactory`**: Creates isolated `MikroDbContext` instances outside HTTP scopes for background workers and schedulers.
+- **Optimistic Concurrency**: Maps MikroORM's `OptimisticLockError` to `DbConcurrencyException` (HTTP 409 Conflict).
+- **`asNoTracking` Queries**: Maps `asNoTracking: true` directly to MikroORM's `disableIdentityMap` for high-performance read-only operations.
+- **Global Filters**: Ergonomic `enableFilter` and `addFilter` methods for multi-tenant and soft-delete workflows.
+
+## Installation
+
+```bash
+pnpm add @tsnx/data @tsnx/mikro-orm @mikro-orm/core @mikro-orm/sqlite
+```
+
+## Quick Start
+
+```typescript
+import { WebApplication } from '@tsnx/web';
+import { addMikroOrm, MikroDbContext } from '@tsnx/mikro-orm';
+import { defineConfig } from '@mikro-orm/sqlite';
+import { User } from './entities/User.js';
+
+const builder = WebApplication.createBuilder();
+
+// 1. Configure MikroORM and DbContext
+addMikroOrm(builder.services, defineConfig({
+  dbName: 'app.db',
+  entities: [User],
+}), {
+  autoMigrate: true,
+  ensureCreated: true,
+  enableSensitiveDataLogging: true,
+});
+
+const app = builder.build();
+
+// 2. Inject DbContext in route handlers (Scoped per request)
+app.mapGet('/users', async (db: MikroDbContext) => {
+  return await db.set(User).findMany({}, { asNoTracking: true });
+});
+
+await app.run();
+```

package/dist/context/mikro-database-facade.d.ts

@@ -0,0 +1,11 @@
+import type { IDatabaseFacade } from '@tsnx/data';
+import type { MikroORM } from '@mikro-orm/core';
+export declare class MikroDatabaseFacade implements IDatabaseFacade {
+    private readonly orm;
+    readonly providerName = "mikro-orm";
+    constructor(orm: MikroORM);
+    canConnect(_signal?: AbortSignal): Promise<boolean>;
+    ensureCreated(_signal?: AbortSignal): Promise<boolean>;
+    migrate(_signal?: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=mikro-database-facade.d.ts.map

package/dist/context/mikro-database-facade.js

@@ -0,0 +1,35 @@
+export class MikroDatabaseFacade {
+    orm;
+    providerName = 'mikro-orm';
+    constructor(orm) {
+        this.orm = orm;
+    }
+    async canConnect(_signal) {
+        try {
+            return await this.orm.isConnected();
+        }
+        catch {
+            return false;
+        }
+    }
+    async ensureCreated(_signal) {
+        const generator = this.orm.schema;
+        if (!generator)
+            return false;
+        try {
+            await generator.ensureDatabase();
+            await generator.updateSchema({ safe: true });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async migrate(_signal) {
+        const migrator = this.orm.migrator;
+        if (migrator) {
+            await migrator.up();
+        }
+    }
+}
+//# sourceMappingURL=mikro-database-facade.js.map

package/dist/context/mikro-db-context-factory.d.ts

@@ -0,0 +1,15 @@
+import type { IDbContextFactory } from '@tsnx/data';
+import type { Constructor } from '@tsnx/hosting-abstractions';
+import type { MikroORM } from '@mikro-orm/core';
+import type { MikroDbContext } from './mikro-db-context.js';
+/**
+ * Creates isolated MikroDbContext instances outside standard HTTP request scopes
+ * (e.g. background workers, queue consumers, CLI commands).
+ */
+export declare class MikroDbContextFactory<TContext extends MikroDbContext = MikroDbContext> implements IDbContextFactory<TContext> {
+    private readonly orm;
+    private readonly contextClass;
+    constructor(orm: MikroORM, contextClass: Constructor<TContext>);
+    createDbContext(): TContext;
+}
+//# sourceMappingURL=mikro-db-context-factory.d.ts.map

package/dist/context/mikro-db-context-factory.js

@@ -0,0 +1,17 @@
+/**
+ * Creates isolated MikroDbContext instances outside standard HTTP request scopes
+ * (e.g. background workers, queue consumers, CLI commands).
+ */
+export class MikroDbContextFactory {
+    orm;
+    contextClass;
+    constructor(orm, contextClass) {
+        this.orm = orm;
+        this.contextClass = contextClass;
+    }
+    createDbContext() {
+        const em = this.orm.em.fork();
+        return new this.contextClass(em, this.orm);
+    }
+}
+//# sourceMappingURL=mikro-db-context-factory.js.map

package/dist/context/mikro-db-context.d.ts

@@ -0,0 +1,35 @@
+import { DbContext, type IDbTransaction, type IDbSet, type EntityConstructor, type IDatabaseFacade } from '@tsnx/data';
+import { type EntityManager, type MikroORM } from '@mikro-orm/core';
+/**
+ * MikroORM-backed DbContext conforming to EF Core Unit of Work architecture.
+ */
+export declare class MikroDbContext extends DbContext {
+    readonly em: EntityManager;
+    readonly orm: MikroORM;
+    readonly database: IDatabaseFacade;
+    private _currentTransaction;
+    private _isDisposed;
+    constructor(em: EntityManager, orm: MikroORM);
+    get currentTransaction(): IDbTransaction | null;
+    get isDisposed(): boolean;
+    /**
+     * Persists all pending entity changes to the database.
+     * Automatically intercepts MikroORM's OptimisticLockError and rethrows as
+     * DbConcurrencyException (HTTP 409 Conflict).
+     */
+    saveChanges(_cancellationToken?: AbortSignal): Promise<number>;
+    /**
+     * Sets filter parameter values on this DbContext session (e.g. tenantId).
+     */
+    enableFilter(name: string, args?: Record<string, any>): this;
+    /**
+     * Registers a global filter onto this DbContext session.
+     */
+    addFilter(name: string, cond: Record<string, any> | ((args: Record<string, any>) => any), enabled?: boolean): this;
+    beginTransaction(isolationLevel?: string): Promise<IDbTransaction>;
+    executeInTransaction<T>(operation: (transaction: IDbTransaction) => Promise<T>, isolationLevel?: string): Promise<T>;
+    set<TEntity extends object, TId = unknown>(entityType: EntityConstructor<TEntity>): IDbSet<TEntity, TId>;
+    dispose(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=mikro-db-context.d.ts.map

package/dist/context/mikro-db-context.js

@@ -0,0 +1,105 @@
+import { DbContext, DbConcurrencyException, } from '@tsnx/data';
+import { OptimisticLockError, } from '@mikro-orm/core';
+import { MikroDatabaseFacade } from './mikro-database-facade.js';
+import { MikroDbTransaction } from './mikro-transaction.js';
+import { MikroDbSet } from '../repository/mikro-repository.js';
+/**
+ * MikroORM-backed DbContext conforming to EF Core Unit of Work architecture.
+ */
+export class MikroDbContext extends DbContext {
+    em;
+    orm;
+    database;
+    _currentTransaction = null;
+    _isDisposed = false;
+    constructor(em, orm) {
+        super();
+        this.em = em;
+        this.orm = orm;
+        this.database = new MikroDatabaseFacade(orm);
+    }
+    get currentTransaction() {
+        return this._currentTransaction;
+    }
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    /**
+     * Persists all pending entity changes to the database.
+     * Automatically intercepts MikroORM's OptimisticLockError and rethrows as
+     * DbConcurrencyException (HTTP 409 Conflict).
+     */
+    async saveChanges(_cancellationToken) {
+        if (this._isDisposed) {
+            throw new Error('Cannot save changes on a disposed DbContext.');
+        }
+        const uow = this.em.getUnitOfWork();
+        const count = uow.getPersistStack().size + uow.getRemoveStack().size;
+        try {
+            await this.em.flush();
+        }
+        catch (error) {
+            if (error instanceof OptimisticLockError ||
+                error?.name === 'OptimisticLockError' ||
+                error?.constructor?.name === 'OptimisticLockError') {
+                throw new DbConcurrencyException(error.message ?? 'A database concurrency conflict occurred. The entity was modified by another operation.', {
+                    entityName: error?.entity?.constructor?.name,
+                    entityId: error?.entity?.id,
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+        return count;
+    }
+    /**
+     * Sets filter parameter values on this DbContext session (e.g. tenantId).
+     */
+    enableFilter(name, args) {
+        this.em.setFilterParams(name, args ?? {});
+        return this;
+    }
+    /**
+     * Registers a global filter onto this DbContext session.
+     */
+    addFilter(name, cond, enabled = true) {
+        this.em.addFilter(name, cond, undefined, enabled);
+        return this;
+    }
+    async beginTransaction(isolationLevel) {
+        await this.em.begin({ isolationLevel: isolationLevel });
+        const tx = new MikroDbTransaction(this.em);
+        this._currentTransaction = tx;
+        return tx;
+    }
+    async executeInTransaction(operation, isolationLevel) {
+        const tx = await this.beginTransaction(isolationLevel);
+        try {
+            const result = await operation(tx);
+            await tx.commit();
+            return result;
+        }
+        catch (err) {
+            await tx.rollback();
+            throw err;
+        }
+        finally {
+            if (this._currentTransaction === tx) {
+                this._currentTransaction = null;
+            }
+        }
+    }
+    set(entityType) {
+        return new MikroDbSet(this.em, entityType);
+    }
+    dispose() {
+        if (this._isDisposed)
+            return;
+        this.em.clear();
+        this._isDisposed = true;
+    }
+    async [Symbol.asyncDispose]() {
+        this.dispose();
+    }
+}
+//# sourceMappingURL=mikro-db-context.js.map

package/dist/context/mikro-transaction.d.ts

@@ -0,0 +1,12 @@
+import type { IDbTransaction } from '@tsnx/data';
+import type { EntityManager } from '@mikro-orm/core';
+export declare class MikroDbTransaction implements IDbTransaction {
+    private readonly em;
+    readonly transactionId: string;
+    private _isCompleted;
+    constructor(em: EntityManager, transactionId?: string);
+    get isCompleted(): boolean;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}
+//# sourceMappingURL=mikro-transaction.d.ts.map

package/dist/context/mikro-transaction.js

@@ -0,0 +1,26 @@
+export class MikroDbTransaction {
+    em;
+    transactionId;
+    _isCompleted = false;
+    constructor(em, transactionId) {
+        this.em = em;
+        this.transactionId =
+            transactionId ?? `tx_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    }
+    get isCompleted() {
+        return this._isCompleted;
+    }
+    async commit() {
+        if (this._isCompleted)
+            return;
+        await this.em.commit();
+        this._isCompleted = true;
+    }
+    async rollback() {
+        if (this._isCompleted)
+            return;
+        await this.em.rollback();
+        this._isCompleted = true;
+    }
+}
+//# sourceMappingURL=mikro-transaction.js.map

package/dist/context/tokens.d.ts

@@ -0,0 +1,6 @@
+import { type ServiceToken } from '@tsnx/hosting-abstractions';
+import type { MikroORM, EntityManager, Options } from '@mikro-orm/core';
+export declare const MIKRO_ORM: ServiceToken<MikroORM>;
+export declare const MIKRO_ORM_EM: ServiceToken<EntityManager>;
+export declare const MIKRO_ORM_OPTIONS: ServiceToken<Options>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/context/tokens.js

@@ -0,0 +1,5 @@
+import { createToken } from '@tsnx/hosting-abstractions';
+export const MIKRO_ORM = createToken('MIKRO_ORM');
+export const MIKRO_ORM_EM = createToken('MIKRO_ORM_EM');
+export const MIKRO_ORM_OPTIONS = createToken('MIKRO_ORM_OPTIONS');
+//# sourceMappingURL=tokens.js.map

package/dist/converters/value-converter-type.d.ts

@@ -0,0 +1,9 @@
+import { Type } from '@mikro-orm/core';
+import type { IValueConverter } from '@tsnx/data';
+export type ValueConverterTypeConstructor<TModel, TProvider = string> = new () => Type<TModel, TProvider>;
+/**
+ * Creates a MikroORM custom Type class from a TSNX IValueConverter,
+ * enabling transparent mapping between domain Value Objects and database primitives.
+ */
+export declare function createValueConverterType<TModel, TProvider = string>(typeName: string, converter: IValueConverter<TModel, TProvider>, columnType?: string): ValueConverterTypeConstructor<TModel, TProvider>;
+//# sourceMappingURL=value-converter-type.d.ts.map

package/dist/converters/value-converter-type.js

@@ -0,0 +1,25 @@
+import { Type } from '@mikro-orm/core';
+/**
+ * Creates a MikroORM custom Type class from a TSNX IValueConverter,
+ * enabling transparent mapping between domain Value Objects and database primitives.
+ */
+export function createValueConverterType(typeName, converter, columnType = 'text') {
+    class ConvertedType extends Type {
+        convertToDatabaseValue(value) {
+            if (value === null || value === undefined)
+                return value;
+            return converter.convertToDatabase(value);
+        }
+        convertToJSValue(value) {
+            if (value === null || value === undefined)
+                return value;
+            return converter.convertToModel(value);
+        }
+        getColumnType() {
+            return columnType;
+        }
+    }
+    Object.defineProperty(ConvertedType, 'name', { value: typeName });
+    return ConvertedType;
+}
+//# sourceMappingURL=value-converter-type.js.map

package/dist/extensions/service-collection-extensions.d.ts

@@ -0,0 +1,29 @@
+import type { IServiceCollection, Constructor, InjectionToken } from '@tsnx/hosting-abstractions';
+import { type EntityConstructor, type IDbCommandInterceptor } from '@tsnx/data';
+import { MikroDbContext } from '../context/mikro-db-context.js';
+import { type MikroOrmSource } from '../lifetime/mikro-lifetime-service.js';
+import { MikroDbSet } from '../repository/mikro-repository.js';
+export interface AddMikroOrmOptions<TContext extends MikroDbContext = MikroDbContext> {
+    contextClass?: Constructor<TContext>;
+    autoMigrate?: boolean;
+    ensureCreated?: boolean;
+    enableLogging?: boolean;
+    enableSensitiveDataLogging?: boolean;
+    interceptors?: IDbCommandInterceptor[];
+    connectionString?: string;
+}
+/**
+ * Registers MikroORM integration into TSNX IServiceCollection modeled after EF Core's AddDbContext.
+ *
+ * - MIKRO_ORM: Singleton, manages connection pools and metadata
+ * - MIKRO_ORM_EM: Scoped, forked per scope/request for isolated Unit of Work
+ * - MikroDbContext / ContextClass: Scoped, EF Core-like unit of work session
+ * - IDbContextFactory: Singleton, creates isolated DbContext instances outside HTTP requests
+ * - Hosted Service: Transparently manages connection pooling and graceful shutdown
+ */
+export declare function addMikroOrm<TContext extends MikroDbContext = MikroDbContext>(services: IServiceCollection, source: MikroOrmSource, optionsOrContext?: Constructor<TContext> | AddMikroOrmOptions<TContext>): IServiceCollection;
+/**
+ * Registers an entity-specific repository or DbSet as Scoped in DI.
+ */
+export declare function addEntityRepository<TEntity extends object>(services: IServiceCollection, tokenOrEntity: InjectionToken<MikroDbSet<TEntity>> | EntityConstructor<TEntity>, entityType?: EntityConstructor<TEntity>): IServiceCollection;
+//# sourceMappingURL=service-collection-extensions.d.ts.map

package/dist/extensions/service-collection-extensions.js

@@ -0,0 +1,75 @@
+import { DB_CONTEXT, DB_UNIT_OF_WORK, DB_CONTEXT_OPTIONS, DB_CONTEXT_FACTORY, } from '@tsnx/data';
+import { MikroDbContext } from '../context/mikro-db-context.js';
+import { MikroDbContextFactory } from '../context/mikro-db-context-factory.js';
+import { MIKRO_ORM, MIKRO_ORM_EM } from '../context/tokens.js';
+import { MikroHostService, } from '../lifetime/mikro-lifetime-service.js';
+import { MikroDbSet } from '../repository/mikro-repository.js';
+/**
+ * Registers MikroORM integration into TSNX IServiceCollection modeled after EF Core's AddDbContext.
+ *
+ * - MIKRO_ORM: Singleton, manages connection pools and metadata
+ * - MIKRO_ORM_EM: Scoped, forked per scope/request for isolated Unit of Work
+ * - MikroDbContext / ContextClass: Scoped, EF Core-like unit of work session
+ * - IDbContextFactory: Singleton, creates isolated DbContext instances outside HTTP requests
+ * - Hosted Service: Transparently manages connection pooling and graceful shutdown
+ */
+export function addMikroOrm(services, source, optionsOrContext) {
+    let contextClass = MikroDbContext;
+    let dbOptions = { providerName: 'mikro-orm' };
+    if (typeof optionsOrContext === 'function') {
+        contextClass = optionsOrContext;
+    }
+    else if (optionsOrContext) {
+        if (optionsOrContext.contextClass) {
+            contextClass = optionsOrContext.contextClass;
+        }
+        dbOptions = {
+            providerName: 'mikro-orm',
+            autoMigrate: optionsOrContext.autoMigrate,
+            ensureCreated: optionsOrContext.ensureCreated,
+            enableLogging: optionsOrContext.enableLogging,
+            enableSensitiveDataLogging: optionsOrContext.enableSensitiveDataLogging,
+            interceptors: optionsOrContext.interceptors,
+            connectionString: optionsOrContext.connectionString,
+        };
+    }
+    // 1. Register DbContextOptions
+    services.addSingleton(DB_CONTEXT_OPTIONS, dbOptions);
+    // 2. Register Internal Host Service (Singleton)
+    const hostService = new MikroHostService(source, dbOptions);
+    services.addSingleton(MikroHostService, hostService);
+    // 3. Register Hosted Service for lifecycle start/stop
+    services.addHostedService().toFactory((sp) => sp.get(MikroHostService));
+    // 4. Register MIKRO_ORM singleton
+    services.addSingleton(MIKRO_ORM, (sp) => sp.get(MikroHostService).instance);
+    // 5. Register MIKRO_ORM_EM as Scoped (forked per scope / request)
+    services.addScoped(MIKRO_ORM_EM, (sp) => sp.get(MIKRO_ORM).em.fork());
+    // 6. Register DbContext class as Scoped
+    services.addScoped(contextClass, (sp) => {
+        const em = sp.get(MIKRO_ORM_EM);
+        const orm = sp.get(MIKRO_ORM);
+        return new contextClass(em, orm);
+    });
+    // 7. Bind IDbContext and IUnitOfWork tokens to the scoped DbContext
+    services.addScoped(DB_CONTEXT, (sp) => sp.get(contextClass));
+    services.addScoped(DB_UNIT_OF_WORK, (sp) => sp.get(contextClass));
+    // 8. Register IDbContextFactory singleton for background jobs / outside HTTP scopes
+    services.addSingleton(DB_CONTEXT_FACTORY, (sp) => {
+        const orm = sp.get(MIKRO_ORM);
+        return new MikroDbContextFactory(orm, contextClass);
+    });
+    return services;
+}
+/**
+ * Registers an entity-specific repository or DbSet as Scoped in DI.
+ */
+export function addEntityRepository(services, tokenOrEntity, entityType) {
+    const entity = entityType ?? tokenOrEntity;
+    const token = tokenOrEntity;
+    services.addScoped(token, (sp) => {
+        const em = sp.get(MIKRO_ORM_EM);
+        return new MikroDbSet(em, entity);
+    });
+    return services;
+}
+//# sourceMappingURL=service-collection-extensions.js.map

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './context/tokens.js';
+export * from './context/mikro-db-context.js';
+export * from './context/mikro-db-context-factory.js';
+export * from './context/mikro-database-facade.js';
+export * from './context/mikro-transaction.js';
+export * from './repository/mikro-repository.js';
+export * from './converters/value-converter-type.js';
+export * from './lifetime/mikro-lifetime-service.js';
+export * from './extensions/service-collection-extensions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,16 @@
+// Tokens
+export * from './context/tokens.js';
+// Context, Factory & Transactions
+export * from './context/mikro-db-context.js';
+export * from './context/mikro-db-context-factory.js';
+export * from './context/mikro-database-facade.js';
+export * from './context/mikro-transaction.js';
+// Repositories
+export * from './repository/mikro-repository.js';
+// Converters (ValueConverter)
+export * from './converters/value-converter-type.js';
+// Host Service & Types
+export * from './lifetime/mikro-lifetime-service.js';
+// DI Extensions
+export * from './extensions/service-collection-extensions.js';
+//# sourceMappingURL=index.js.map

package/dist/lifetime/mikro-lifetime-service.d.ts

@@ -0,0 +1,19 @@
+import type { DbContextOptions } from '@tsnx/data';
+import type { HostedService } from '@tsnx/hosting-abstractions';
+import { MikroORM, type Options } from '@mikro-orm/core';
+export type MikroOrmSource = MikroORM | Options | (() => Promise<MikroORM> | MikroORM);
+/**
+ * Internal hosted service managing MikroORM startup initialization and clean connection pool shutdown.
+ */
+export declare class MikroHostService implements HostedService {
+    private readonly source;
+    private readonly options?;
+    private _isReady;
+    private _orm;
+    constructor(source: MikroOrmSource, options?: DbContextOptions | undefined);
+    get isReady(): boolean;
+    get instance(): MikroORM;
+    start(signal: AbortSignal): Promise<void>;
+    stop(_signal: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=mikro-lifetime-service.d.ts.map

package/dist/lifetime/mikro-lifetime-service.js

@@ -0,0 +1,111 @@
+import { MikroORM } from '@mikro-orm/core';
+/**
+ * Internal hosted service managing MikroORM startup initialization and clean connection pool shutdown.
+ */
+export class MikroHostService {
+    source;
+    options;
+    _isReady = false;
+    _orm = null;
+    constructor(source, options) {
+        this.source = source;
+        this.options = options;
+        if (source instanceof MikroORM || (source && typeof source.isConnected === 'function')) {
+            this._orm = source;
+        }
+    }
+    get isReady() {
+        return this._isReady;
+    }
+    get instance() {
+        if (!this._orm) {
+            throw new Error('MikroORM instance is not yet initialized. Start the application host or supply an initialized MikroORM instance.');
+        }
+        return this._orm;
+    }
+    async start(signal) {
+        if (signal.aborted) {
+            throw new Error('Host startup aborted before database initialization.');
+        }
+        try {
+            // 1. Resolve or initialize MikroORM instance
+            if (!this._orm) {
+                if (typeof this.source === 'function') {
+                    this._orm = await this.source();
+                }
+                else {
+                    const config = { ...this.source };
+                    this._orm = await MikroORM.init(config);
+                }
+            }
+            // 2. Attach query interceptors & debug logging via ORM logger
+            if (this.options?.interceptors?.length) {
+                const interceptors = this.options.interceptors;
+                const logger = this._orm.config.getLogger();
+                if (typeof logger.setDebugMode === 'function') {
+                    logger.setDebugMode(true);
+                }
+                const originalWriter = typeof logger.writer === 'function' ? logger.writer : null;
+                logger.writer = (message) => {
+                    const context = { command: message, startTime: Date.now() };
+                    for (const interceptor of interceptors) {
+                        interceptor.afterExecute?.(context);
+                    }
+                    if (this.options?.enableLogging && originalWriter) {
+                        originalWriter(message);
+                    }
+                };
+            }
+            else if (this.options?.enableSensitiveDataLogging) {
+                const logger = this._orm.config.getLogger();
+                if (typeof logger.setDebugMode === 'function') {
+                    logger.setDebugMode(true);
+                }
+            }
+            else if (this.options?.enableLogging !== undefined) {
+                const logger = this._orm.config.getLogger();
+                if (typeof logger.setDebugMode === 'function') {
+                    logger.setDebugMode(Boolean(this.options.enableLogging));
+                }
+            }
+            // 3. Verify / ensure connection
+            const isConnected = await this._orm.isConnected();
+            if (!isConnected) {
+                await this._orm.connect();
+            }
+            // 4. Auto-migration or schema creation if configured
+            if (this.options?.autoMigrate && this._orm.migrator) {
+                await this._orm.migrator.up();
+            }
+            else if (this.options?.ensureCreated && this._orm.schema) {
+                await this._orm.schema.ensureDatabase();
+                await this._orm.schema.updateSchema({ safe: true });
+            }
+            this._isReady = true;
+        }
+        catch (error) {
+            // Rollback and cleanup partial resources within catch to prevent dangling pools
+            try {
+                if (this._orm && (await this._orm.isConnected())) {
+                    await this._orm.close(true);
+                }
+            }
+            catch {
+                // Suppress secondary cleanup error and rethrow the primary failure
+            }
+            this._isReady = false;
+            throw error;
+        }
+    }
+    async stop(_signal) {
+        try {
+            if (this._orm && (await this._orm.isConnected())) {
+                await this._orm.close(true);
+            }
+        }
+        finally {
+            this._isReady = false;
+        }
+    }
+}
+//# sourceMappingURL=mikro-lifetime-service.js.map

package/dist/repository/mikro-repository.d.ts

@@ -0,0 +1,26 @@
+import type { IDbSet, EntityConstructor, FilterQuery, FindOptions } from '@tsnx/data';
+import type { EntityManager } from '@mikro-orm/core';
+export declare class MikroDbSet<TEntity extends object, TId = unknown> implements IDbSet<TEntity, TId> {
+    private readonly em;
+    readonly entityType: EntityConstructor<TEntity>;
+    constructor(em: EntityManager, entityType: EntityConstructor<TEntity>);
+    findById(id: TId, _signal?: AbortSignal): Promise<TEntity | null>;
+    findOne(filter: FilterQuery<TEntity>, options?: FindOptions<TEntity>): Promise<TEntity | null>;
+    findMany(filter?: FilterQuery<TEntity>, options?: FindOptions<TEntity>): Promise<TEntity[]>;
+    count(filter?: FilterQuery<TEntity>, _signal?: AbortSignal): Promise<number>;
+    exists(filter: FilterQuery<TEntity>, _signal?: AbortSignal): Promise<boolean>;
+    add(entity: TEntity): void;
+    addMany(entities: TEntity[]): void;
+    remove(entity: TEntity): void;
+    removeMany(entities: TEntity[]): void;
+    /**
+     * Executes a bulk update directly in the database without loading entities into memory.
+     */
+    executeUpdate(filter: FilterQuery<TEntity>, data: Partial<TEntity> | Record<string, any>): Promise<number>;
+    /**
+     * Executes a bulk delete directly in the database without loading entities into memory.
+     */
+    executeDelete(filter: FilterQuery<TEntity>): Promise<number>;
+    private mapOptions;
+}
+//# sourceMappingURL=mikro-repository.d.ts.map

package/dist/repository/mikro-repository.js

@@ -0,0 +1,71 @@
+export class MikroDbSet {
+    em;
+    entityType;
+    constructor(em, entityType) {
+        this.em = em;
+        this.entityType = entityType;
+    }
+    async findById(id, _signal) {
+        return (await this.em.findOne(this.entityType, id));
+    }
+    async findOne(filter, options) {
+        return (await this.em.findOne(this.entityType, filter, this.mapOptions(options)));
+    }
+    async findMany(filter, options) {
+        return (await this.em.find(this.entityType, (filter ?? {}), this.mapOptions(options)));
+    }
+    async count(filter, _signal) {
+        return await this.em.count(this.entityType, (filter ?? {}));
+    }
+    async exists(filter, _signal) {
+        const c = await this.count(filter);
+        return c > 0;
+    }
+    add(entity) {
+        this.em.persist(entity);
+    }
+    addMany(entities) {
+        this.em.persist(entities);
+    }
+    remove(entity) {
+        this.em.remove(entity);
+    }
+    removeMany(entities) {
+        for (const entity of entities) {
+            this.em.remove(entity);
+        }
+    }
+    /**
+     * Executes a bulk update directly in the database without loading entities into memory.
+     */
+    async executeUpdate(filter, data) {
+        return await this.em.nativeUpdate(this.entityType, (filter ?? {}), data);
+    }
+    /**
+     * Executes a bulk delete directly in the database without loading entities into memory.
+     */
+    async executeDelete(filter) {
+        return await this.em.nativeDelete(this.entityType, (filter ?? {}));
+    }
+    mapOptions(options) {
+        if (!options)
+            return undefined;
+        const mapped = {};
+        if (options.skip !== undefined)
+            mapped.offset = options.skip;
+        if (options.take !== undefined)
+            mapped.limit = options.take;
+        if (options.orderBy)
+            mapped.orderBy = options.orderBy;
+        if (options.populate)
+            mapped.populate = options.populate;
+        if (options.fields)
+            mapped.fields = options.fields;
+        if (options.asNoTracking)
+            mapped.disableIdentityMap = true;
+        if (options.cache !== undefined)
+            mapped.cache = options.cache;
+        return mapped;
+    }
+}
+//# sourceMappingURL=mikro-repository.js.map

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@tsnx/mikro-orm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "description": "MikroORM provider adapter for TSNX Data - Scoped EntityManager, MikroDbContext, and Hosted Service integration",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tsnx/data": "1.2.0",
+    "@tsnx/hosting-abstractions": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": ">=6.0.0"
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^6.4.16",
+    "@mikro-orm/sqlite": "^6.4.16",
+    "@tsnx/hosting": "^1.1.0",
+    "@types/node": "^22.13.9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tsnxjs/data.git",
+    "directory": "packages/mikro-orm"
+  },
+  "bugs": "https://github.com/tsnxjs/data/issues",
+  "homepage": "https://github.com/tsnxjs/data#readme",
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "typecheck": "tsc -b --noEmit",
+    "test": "node --test dist/__tests__/**/*.test.js"
+  }
 }