Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DatabasePlugin
✓ import { DatabasePlugin } from 'najm-database'
✗ const DatabasePlugin = require('najm-database').DatabasePlugin
ESM-only since v1.0.0. Named export.
Transactional
✓ import { Transactional } from 'najm-database'
✗ import Transactional from 'najm-database'
Named export, not default. Used as @Transactional decorator.
DatabaseConfig
✓ import type { DatabaseConfig } from 'najm-database'
✗ import { DatabaseConfig } from 'najm-database'
Type export. Should use `import type` in TypeScript to avoid runtime overhead.
default
✓ import NajmDatabase from 'najm-database'
✗ import { NajmDatabase } from 'najm-database'
Default export is the main plugin class. Named export NajmDatabase does not exist.
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();
}
}
Errors
Common errors & fixes
Reflect.getMetadata is not a function
reflect-metadata polyfill not imported before decorator usage.
fixAdd `import 'reflect-metadata'` to the top of the entry file.
Cannot find module 'najm-database' or its corresponding type declarations
Missing peer dependency najm-core or incorrect Node.js version (requires ESM).
fixRun `npm install —legacy-peer-deps` and ensure package.json has `"type": "module"`.
SyntaxError: Unexpected token 'export'
CommonJS context (require) cannot handle ESM-only package.
fixConvert project to ESM or use dynamic import: `const { DatabasePlugin } = await import('najm-database')`. TypeError: Class constructor DatabasePlugin cannot be invoked without 'new'
Using `DatabasePlugin()` instead of `new DatabasePlugin()`.
fixInstantiate with `new DatabasePlugin({ db })`. Audit
Dependencies
najm-coreoptionalcore framework dependency
reflect-metadatarequiredrequired for decorator functionality
drizzle-ormoptionalpeer dependency for database operations
zodoptionalpeer dependency for schema validation