Najm Database Plugin

1.1.8 verified Sat Apr 25 auth: no javascript

Community-maintained database plugin for the Najm API framework (v1.1.8). Provides decorator-based transaction management, automatic rollback, Drizzle ORM integration, and Zod schema validation. Requires najm-core, reflect-metadata, drizzle-orm >=0.36.0, and zod. Updated monthly. Differentiator: declarative @Transactional decorator with automatic commit/rollback tied to request lifecycle, reducing boilerplate for Najm-based APIs.

Common errors

error Reflect.getMetadata is not a function ↓

cause reflect-metadata polyfill not imported before decorator usage.

fix

Add import 'reflect-metadata' to the top of the entry file.

error Cannot find module 'najm-database' or its corresponding type declarations ↓

cause Missing peer dependency najm-core or incorrect Node.js version (requires ESM).

fix

Run npm install —legacy-peer-deps and ensure package.json has "type": "module".

error SyntaxError: Unexpected token 'export' ↓

cause CommonJS context (require) cannot handle ESM-only package.

fix

Convert project to ESM or use dynamic import: const { DatabasePlugin } = await import('najm-database').

error TypeError: Class constructor DatabasePlugin cannot be invoked without 'new' ↓

cause Using `DatabasePlugin()` instead of `new DatabasePlugin()`.

fix

Instantiate with new DatabasePlugin({ db }).

Warnings

breaking Version 1.0.0 removed CommonJS support. All imports must use ESM syntax. ↓

fix Replace require() with import statements. Use dynamic import if necessary.

deprecated The `DatabasePlugin` constructor now requires an options object with `db` property. Passing a direct Drizzle instance is deprecated. ↓

fix Use `new DatabasePlugin({ db: drizzleInstance })` instead of `new DatabasePlugin(drizzleInstance)`.

gotcha The @Transactional decorator only works on methods inside classes that are instantiated by the Najm framework container. Manually instantiated classes will not have transaction support. ↓

fix Ensure the class is registered as a service or component in Najm.

gotcha reflect-metadata must be imported at the application entry point before any decorator usage, otherwise @Transactional will throw 'Reflect.getMetadata is not a function'. ↓

fix Add `import 'reflect-metadata'` at the top of your main file.

Install

npm install najm-database

yarn add najm-database

pnpm add najm-database

Imports

DatabasePlugin

wrong

const DatabasePlugin = require('najm-database').DatabasePlugin

correct

import { DatabasePlugin } from 'najm-database'

ESM-only since v1.0.0. Named export.

Transactional

wrong

import Transactional from 'najm-database'

correct

import { Transactional } from 'najm-database'

Named export, not default. Used as @Transactional decorator.

DatabaseConfig

wrong

import { DatabaseConfig } from 'najm-database'

correct

import type { DatabaseConfig } from 'najm-database'

Type export. Should use `import type` in TypeScript to avoid runtime overhead.

default
wrong
```
import { NajmDatabase } from 'najm-database'
```
correct
```
import NajmDatabase from 'najm-database'
```
Default export is the main plugin class. Named export NajmDatabase does not exist.

Quickstart

Shows how to initialize the DatabasePlugin with a Drizzle ORM instance and use the @Transactional decorator on a method to wrap it in a database transaction.

import { DatabasePlugin, Transactional } from 'najm-database';
import { drizzle } from 'drizzle-orm/node-postgres';
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DB_URL ?? '' });
const db = drizzle(pool);

// Register plugin with Najm framework
import { Najm } from 'najm-core';
const app = new Najm();
app.use(DatabasePlugin, { db });

// Use @Transactional decorator in a service
class UserService {
  @Transactional()
  async createUser(data: { name: string }) {
    // This method runs inside a database transaction
    // Automatically commits on success, rolls back on error
    return await db.insert(users).values(data).returning();
  }
}