refactor(full): full rewrite

Removed the nitro plugin in favor of util functions, intended for use in custom Nitro plugins.

Author: boenrobot

.husky/commit-msg

@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+yarn commitlint --edit $1

README.md

@@ -13,17 +13,25 @@ Install the module to your Nuxt application with one command:
 npx nuxi module add nuxt-mikro-orm-module
 ```
 
-After that, a plugin needs to be created, which calls the "mikroOrm:create" hook.
-If multiple MikroORM instances are required, this hook may be called multiple times, with different names.
-The plugin should ideally call this hook before the server is ready.
+After that, ideally in a Nitro plugin, call initOrm() with the instance's config.
 
-The hook "mikroOrm:init" will be called for every new instance.
+Call useEntityManager() in a request context to get a forked EntityManager you can immediately use.
+If you are working in a different context, such as a cron job, you may call useOrm(), and manually call `fork()` to get a locally scoped EntityManager.
 
-## Helper functions
+## API
 
-- `getEntityManager(name?: string)` - Get an entity manager with the current request context. Intended for use in server components.
-- `useOrm(name?: string)` - Get the MikroORM instance. Intended for use in server components.
+- `initOrm<T extends MikroOrmInstance = MikroOrmInstance>(config: ReturnType<typeof defineConfig>, name: string = 'default', forkOptionsFactory?: (event: H3Event<EventHandlerRequest>, name: string) => ForkOptions|undefined): Promise<T>` - Initialize a MikroORM instance with the given config. Optionally provide a name and fork options callback (called on each request where EntityManager is used; must not be async). Returns a promise that resolves with the initialized MikroORM instance.
+- `useEntityManager<T extends EntityManager = EntityManager>(event: H3Event<EventHandlerRequest>, name: string = 'default'): T` - Get an entity manager with the current request context.
+- `useOrm<T extends MikroOrmInstance = MikroOrmInstance>(name: string = 'default'): T` - Get the MikroORM instance.
+- `closeOrm(name: string = 'default', force: boolean = false)` - Close an existing MikroORM instance. The name also becomes available for reuse after close.
 
+## Module options / Runtime options
+
+This module's options are used as defaults for runtime options, under the `mikroOrm` key.
+
+Available options:
+
+- `forkOptions` - Default fork options when calling initOrm() without a `forkOptionsFactory`, or when the `forkOptionsFactory` function returns undefined.
 
 ## Contribution
 

commitlint.config.js

@@ -0,0 +1 @@
+export default { extends: ['@commitlint/config-conventional'] };

package.json

@@ -25,7 +25,8 @@
     "lint": "eslint .",
     "test": "vitest run",
     "test:watch": "vitest watch",
-    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
+    "prepare": "husky"
   },
   "dependencies": {
     "@nuxt/kit": "^3.11.2",
@@ -37,6 +38,8 @@
     "nitropack": "^2.9.6"
   },
   "devDependencies": {
+    "@commitlint/cli": "^19.3.0",
+    "@commitlint/config-conventional": "^19.2.2",
     "@mikro-orm/core": "*",
     "@mikro-orm/mysql": "*",
     "@nuxt/devtools": "^1.3.1",
@@ -48,6 +51,7 @@
     "changelogen": "^0.5.5",
     "cross-env": "^7.0.3",
     "eslint": "^8.57.0",
+    "husky": "^9.0.11",
     "nuxi": "^3.11.1",
     "nuxt": "^3.11.2",
     "typescript": "latest",

playground/components/DbLog.server.vue

@@ -5,8 +5,9 @@
 </template>
 
 <script setup lang="ts">
-import {type EntityManager} from "@mikro-orm/mysql";
+import { type EntityManager } from "@mikro-orm/mysql";
 
-const em: EntityManager = useEntityManager();
+const event = useRequestEvent()!;
+const em = useEntityManager<EntityManager>(event);
 const productName = (await em.execute<[{name: string}]>('SELECT name FROM products LIMIT 1'))[0].name;
 </script>

playground/server/plugins/00.mikroOrmConfigProvider.ts

@@ -1,40 +1,36 @@
-import {defineConfig, type EntityManager} from "@mikro-orm/mysql";
+import { initOrm } from "#imports";
+import { defineConfig, type EntityManager, type MikroORM } from "@mikro-orm/mysql";
 
-export default defineNitroPlugin((nitro) => {
-  nitro.hooks.callHook('mikroOrm:create', {
-    config: defineConfig({
-      host: '127.0.0.1',
-      user: 'root',
-      password: '',
-      dbName: 'test',
-      port: 3309,
-      discovery: {
-        warnWhenNoEntities: false,
-      }
-    })
-  });
-
-  nitro.hooks.hook('mikroOrm:init', async (orm) => {
+export default defineNitroPlugin(async (_nitro) => {
+  const orm = await initOrm<MikroORM>(defineConfig({
+    host: '127.0.0.1',
+    user: 'root',
+    password: '',
+    dbName: 'test',
+    port: 3309,
+    discovery: {
+      warnWhenNoEntities: false,
+    }
+  }));
 
-    await orm.schema.ensureDatabase({create: true});
-    const em = orm.em as EntityManager;
-    await em.execute(`
-  CREATE TABLE IF NOT EXISTS \`products\`
-  (
-    \`product_id\` INT UNSIGNED NOT NULL AUTO_INCREMENT,
-    \`name\`       VARCHAR(255) NOT NULL,
-    PRIMARY KEY (\`product_id\`),
-    UNIQUE INDEX \`name_UNIQUE\` (\`name\` ASC) VISIBLE
-  )
-    ENGINE = InnoDB
+  await orm.schema.ensureDatabase({create: true});
+  const em = orm.em as EntityManager;
+  await em.execute(`
+CREATE TABLE IF NOT EXISTS \`products\`
+(
+  \`product_id\` INT UNSIGNED NOT NULL AUTO_INCREMENT,
+  \`name\`       VARCHAR(255) NOT NULL,
+  PRIMARY KEY (\`product_id\`),
+  UNIQUE INDEX \`name_UNIQUE\` (\`name\` ASC) VISIBLE
+)
+  ENGINE = InnoDB
 `);
-    const productCount = (await em.execute<[{count: number}]>('SELECT COUNT(*) AS count FROM `products`'))[0].count;
-    if (productCount === 0) {
-      await em.execute(`
+  const productCount = (await em.execute<[{count: number}]>('SELECT COUNT(*) AS count FROM `products`'))[0].count;
+  if (productCount === 0) {
+    await em.execute(`
 INSERT INTO products SET name = 'product 1'
 `);      await em.execute(`
 INSERT INTO products SET name = 'product 2'
 `);
-    }
-  });
+  }
 });

src/module.ts

@@ -1,26 +1,20 @@
-import {defineNuxtModule, createResolver, addServerPlugin, addServerImportsDir, logger, addImportsDir} from '@nuxt/kit';
-import {type defineConfig, type ForkOptions, type MikroORM, type EntityManager} from "@mikro-orm/core";
+import { defineNuxtModule, createResolver, addServerImportsDir, logger } from '@nuxt/kit';
+import { type ForkOptions, type EntityManager } from "@mikro-orm/core";
 import { defu } from 'defu';
-import type {H3Event} from "h3";
+import type { EventHandlerRequest, H3Event } from "h3";
+
+export type ForkOptionsFactory = (event: H3Event<EventHandlerRequest>, name: string) => ForkOptions|undefined;
 
 export interface ModuleOptions {
   /**
    * Default fork options.
    *
-   * Used for every request.
-   *
    * Key is the instance for which the fork options apply.
    * The default instance's key is "default".
-   */
-  forkOptions?: Map<string, ForkOptions>;
-  /**
-   * Whether to enable fork options hook.
    *
-   * If enabled, the default fork options are copied for each request,
-   * and registered hook handlers for "mikroOrm:fork" are given the opportunity to modify those options
-   * on a per-request basis by modifying the input args.
+   * If an instance's options are left undefined, "{}" is used.
    */
-  enableForkHook?: boolean;
+  forkOptions?: Map<string, ForkOptions>;
 }
 
 declare module '@nuxt/schema' {
@@ -29,48 +23,9 @@ declare module '@nuxt/schema' {
   }
 }
 
-export interface CreateHookArg {
-  config: ReturnType<typeof defineConfig>;
-  name?: string;
-}
-
-declare module 'nitropack' {
-  export interface NitroRuntimeHooks {
-    /**
-     * MikroORM create hook.
-     *
-     * User plugins must call this hook to create a new
-     * instance with the given config.
-     *
-     * @param out
-     */
-    'mikroOrm:create': (out: CreateHookArg) => void;
-
-    /**
-     * MikroORM init hook.
-     *
-     * Called by this module after each ORM instance creation.
-     */
-    'mikroOrm:init': (orm: MikroORM, name: string) => void;
-
-    /**
-     * Called before a fork of MikroORM's EntityManager, at the request context.
-     *
-     * Only registered if the "enableForkHook" option is set to `true`.
-     *
-     * User plugins may register for this hook, to provide different fork options for each request.
-     *
-     * @param event Event at which the fork is happening.
-     * @param forkOptions Options for the particular fork.
-     * @param name Name of the instance being forked.
-     */
-    'mikroOrm:fork': (event: H3Event, forkOptions: ForkOptions, name: string) => void;
-  }
-}
-
 declare module 'h3' {
   interface H3EventContext {
-    em?: Map<string, EntityManager>;
+    mikroOrmEntityManagers?: Map<string, EntityManager>;
   }
 }
 
@@ -85,9 +40,7 @@ export default defineNuxtModule<ModuleOptions>({
     nuxt.options.runtimeConfig.mikroOrm = defu(nuxt.options.runtimeConfig.mikroOrm, options);
 
     addServerImportsDir(resolve('./runtime/server/utils'));
-    addServerPlugin(resolve('./runtime/server/plugins/mikro-orm'));
-    addImportsDir(resolve('./runtime/composables'));
 
-    logger.info('MikroORM module is initialized');
+    logger.debug('MikroORM module is initialized');
   },
 })