zenorm

library4.6.1jsnpmunverified

ZenORM is a Node.js ORM framework that auto-generates TypeScript declarations from an existing MySQL database schema. Unlike traditional ORMs that create database structures, it works inversely by generating model code based on the actual table definitions, making it ideal for retrofitting ORM support into existing projects. It is designed with multi-tenant SAAS systems in mind, supporting multiple database servers and databases, but also works for monoliths. Version 4.6.1 is the latest stable release. Key differentiators include a powerful AB query tool for complex queries, decoration-based model relationships (Join, Many), and automatic TypeScript type generation. Requires mysql-easy-query for runtime and @zenorm/generate for code generation.

database

npm install zenorm

package ↗homepage ↗

INSTALL

IMPORT

SIG · ZENORM

zenorm

databasejavascriptv4.6.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Model

✓ import { Model } from 'zenorm'

✗ const Model = require('zenorm').Model

ESM-only package; use ES import syntax. TypeScript types are included.

Join

✓ import { Join } from 'zenorm'

✗ import { Join } from '@zenorm/generate'

Join is part of the runtime 'zenorm' package, not the generation tool.

Repositories

✓ import { Repositories } from './model'

✗ import { Repositories } from 'zenorm'

Repositories is generated by @zenorm/generate in your model directory, not from the zenorm package.

createPoolCompatible

✓ import { createPoolCompatible } from 'mysql-easy-query'

✗ import { createPool } from 'mysql'

Use mysql-easy-query's pool compatible function for ZenORM integration.

Shows complete setup: installing deps, generating models, configuring database pool, and performing CRUD operations (create, read, update, query, pagination).

// Generate model code first: run `npx zenorm-generate .dbgen.js` with config pointing to your database // Install dependencies: npm install zenorm mysql-easy-query import { createPoolCompatible } from 'mysql-easy-query'; import { Repositories } from './model/_tables'; // Initialize database pool const pool = createPoolCompatible({ pools: { MASTER: { host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'root', database: process.env.DB_NAME ?? 'test', password: process.env.DB_PASSWORD ?? '', }, }, }); // Bind pool to repositories Repositories.setPool(pool); // Example usage async function main() { // Import a generated model, e.g., User const { default: User } = await import('./model/user'); // Create a new user const id = await User.create({ name: 'John' }); console.log('Created user with id:', id); // Find by primary key const user = await User.findByPk(id); console.log('User:', user); // Update user.name = 'John Doe'; await User.save(user); // Query with conditions const users = await User.find({ name: { $like: '%John%' } }).all(); console.log('Matching users:', users); // Pagination const page = await User.find().page(1, 10); console.log('Page data:', page); } main().catch(console.error);

Debug

Known issues

gotchaZenORM does NOT create database tables; it only generates code based on existing schema. You must define tables manually via SQL or other migration tools.

fix

Ensure your MySQL database has the expected tables before generating models.

affects: >=4.0

gotchaThe @zenorm/generate tool uses a configuration file (.dbgen.js) for schema introspection, but runtime pools must be separately configured via mysql-easy-query. Do not use the generate config for runtime connections.

fix

Create separate pool configuration in your application entry point using createPoolCompatible.

affects: >=4.0

gotchaCircular model dependencies (e.g., User and Profile referencing each other) require special import syntax: use `import * as ProfileRef from './profile.js'` and reference the module object in @Join decorator.

fix

For circular refs: import the module as a namespace and use ProfileRef in the decorator, not the direct import.

affects: >=4.0

Errors

Common errors & fixes

Cannot find module 'zenorm' or its corresponding type declarations.

Missing zenorm runtime dependency in node_modules

fix

npm install zenorm

Cannot use decorators with this TypeScript version. Enable 'experimentalDecorators' and 'emitDecoratorMetadata' in tsconfig.

TypeScript requires experimentalDecorators to support decorators used in model definitions

fix

Add to tsconfig.json: "experimentalDecorators": true, "emitDecoratorMetadata": true

TypeError: Repositories.setPool is not a function

Repositories object is imported from wrong place or not generated yet

fix

Ensure you run 'npm run dbgen' first, then import from the generated './model' directory (e.g., import { Repositories } from './model').

Upgrade

Version history

4.6.1latest on npm

Audit

Dependencies

mysql-easy-queryrequiredRuntime dependency for database query execution

@zenorm/generateoptionalCode generation tool required in development to generate TypeScript types

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

packagezenorm ↗

homepagehttps://zenorm.node.ltd ↗