db-model-router 1.0.4 → 1.0.5

package/skill/references/oracle.md

@@ -0,0 +1,52 @@
+# Oracle Adapter
+
+Uses [oracledb](https://www.npmjs.com/package/oracledb) (Oracle Instant Client required).
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("oracle");
+
+db.connect({
+  host: "localhost",
+  port: 1521,
+  database: "XEPDB1",
+  user: "system",
+  password: "oracle",
+});
+```
+
+## Environment Variables
+
+```env
+ORACLE_HOST=localhost
+ORACLE_PORT=1521
+ORACLE_DB=XEPDB1
+ORACLE_USER=system
+ORACLE_PASSWORD=oracle
+```
+
+## Notes
+
+- Requires Oracle Instant Client installed on the host
+- Uses connection pooling with session callbacks for NLS date format
+- MySQL-style `?` placeholders are auto-translated to `:1, :2, ...`
+- Includes a SQL translator that converts MySQL DDL/DML to Oracle syntax
+- `MERGE INTO ... USING DUAL` is used for upsert operations
+- `RETURNING ... INTO :pk_out` is used to retrieve auto-generated IDs
+- Oracle reserved words in column names are auto-quoted
+- `CLOB` values are fetched as strings
+
+## Table Creation
+
+```sql
+CREATE TABLE users (
+  id NUMBER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  name VARCHAR2(255) NOT NULL,
+  email VARCHAR2(255) NOT NULL,
+  age NUMBER NOT NULL
+);
+```
+
+[← Back to main docs](../../README.md)

package/skill/references/postgres.md

@@ -0,0 +1,50 @@
+# PostgreSQL Adapter
+
+Uses the [pg](https://www.npmjs.com/package/pg) driver with connection pooling.
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("postgres");
+
+db.connect({
+  host: "localhost",
+  port: 5432,
+  user: "postgres",
+  password: "password",
+  database: "my_app",
+  connectionLimit: 50, // pool max
+  dateStrings: false, // set true to return dates as strings
+});
+```
+
+## Environment Variables
+
+```env
+PG_HOST=localhost
+PG_PORT=5432
+PG_USER=postgres
+PG_PASSWORD=password
+PG_DB=test_db
+```
+
+## Notes
+
+- Supports MySQL-style `?` placeholders in raw `db.query()` calls — they are auto-translated to `$1, $2, ...`
+- `SERIAL` / `BIGSERIAL` primary keys are auto-detected via `pg_index`
+- `ON CONFLICT` is used for upsert operations
+- Includes a SQL translator layer that converts common MySQL DDL/DML to PostgreSQL syntax
+
+## Table Creation
+
+```sql
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR NOT NULL,
+  email VARCHAR NOT NULL,
+  age INTEGER NOT NULL
+);
+```
+
+[← Back to main docs](../../README.md)

package/skill/references/redis.md

@@ -0,0 +1,53 @@
+# Redis Adapter
+
+Uses [ioredis](https://www.npmjs.com/package/ioredis). Records are stored as Redis hashes with key pattern `{table}:{id}`.
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("redis");
+
+db.connect({
+  host: "localhost",
+  port: 6379,
+  password: "", // optional
+  db: 0, // Redis DB index, optional
+  primaryKey: "id", // field used as the hash key suffix
+});
+```
+
+## Environment Variables
+
+```env
+REDIS_HOST=localhost
+REDIS_PORT=6379
+```
+
+## Notes
+
+- Each record is a Redis hash at key `{table}:{primaryKey}`
+- Auto-incrementing IDs use `INCR {table}:__seq`
+- All filtering, sorting, and pagination happen in-memory (full SCAN)
+- Redis stores all values as strings — numeric coercion is applied on read
+- Nested objects are JSON-serialized into hash fields
+- Best suited for small-to-medium datasets where Redis is already in the stack
+
+## Model Definition
+
+```js
+const users = model(
+  db,
+  "users",
+  {
+    id: "string",
+    name: "required|string",
+    email: "required|string",
+    age: "required|integer",
+  },
+  "id",
+  ["id"],
+);
+```
+
+[← Back to main docs](../../README.md)

package/skill/references/sqlite3.md

@@ -0,0 +1,43 @@
+# SQLite3 Adapter
+
+Uses [better-sqlite3](https://www.npmjs.com/package/better-sqlite3) for synchronous, high-performance SQLite access.
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("sqlite3");
+
+db.connect({ database: "./data.db" });
+// or in-memory:
+db.connect({ database: ":memory:" });
+```
+
+## Options
+
+| Option          | Description                 |
+| --------------- | --------------------------- |
+| `database`      | File path or `:memory:`     |
+| `readonly`      | Open in read-only mode      |
+| `fileMustExist` | Throw if file doesn't exist |
+
+## Notes
+
+- All operations are synchronous (wrapped to match the async model API)
+- WAL journal mode is enabled by default for better concurrency
+- Uses `INSERT OR IGNORE` for conflict handling
+- `ON CONFLICT ... DO UPDATE SET` for upsert
+- No Docker container needed — runs in-process
+
+## Table Creation
+
+```sql
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  email TEXT NOT NULL,
+  age INTEGER NOT NULL
+);
+```
+
+[← Back to main docs](../../README.md)

package/src/cli/commands/generate.js

@@ -14,21 +14,26 @@ const {
 } = require("../generate-route");
 const { generateOpenAPISpec } = require("../generate-openapi");
 const { generateLlmsTxt, generateLlmMd } = require("./generate-llm-docs");
+const { generateMigrationFiles } = require("../generate-migration");
+const { generateDocsRoute } = require("../generate-docs-route");
+const { migrationTimestamp } = require("../init/generators");
 
 /**
  * Generate command handler for the unified CLI.
  *
  * Reads a schema file, converts to ModelMeta[], and generates
- * models, routes, tests, and OpenAPI spec files.
+ * models, routes, tests, OpenAPI spec, migrations, and docs route.
  *
  * Supported flags:
- *   --from      Path to schema file (default: dbmr.schema.json)
- *   --models    Generate only model files
- *   --routes    Generate only route files (including child routes and index)
- *   --openapi   Generate only OpenAPI spec
- *   --tests     Generate only test files
- *   --dry-run   Report planned files without writing
- *   --json      Output JSON result via ctx
+ *   --from        Path to schema file (default: dbmr.schema.json)
+ *   --models      Generate only model files
+ *   --routes      Generate only route files (including child routes and index)
+ *   --openapi     Generate only OpenAPI spec + docs route
+ *   --tests       Generate only test files
+ *   --migrations  Generate only migration files
+ *   --llm-docs    Generate only LLM documentation
+ *   --dry-run     Report planned files without writing
+ *   --json        Output JSON result via ctx
  *
  * When no artifact flags are provided, all artifact types are generated.
  *
@@ -80,12 +85,14 @@ async function generate(args, flags, ctx) {
     args.routes === true ||
     args.openapi === true ||
     args.tests === true ||
+    args.migrations === true ||
     args["llm-docs"] === true;
 
   const genModels = !hasArtifactFlag || args.models === true;
   const genRoutes = !hasArtifactFlag || args.routes === true;
   const genOpenapi = !hasArtifactFlag || args.openapi === true;
   const genTests = !hasArtifactFlag || args.tests === true;
+  const genMigrations = !hasArtifactFlag || args.migrations === true;
   const genLlmDocs = !hasArtifactFlag || args["llm-docs"] === true;
 
   const modelsRelPath = "../models";
@@ -106,57 +113,91 @@ async function generate(args, flags, ctx) {
 
   // --- Route files ---
   if (genRoutes) {
-    // One route per table
+    // Collect child tables to skip generating top-level route files for them
+    const nestedChildren = new Set();
+    for (const rel of relationships) {
+      nestedChildren.add(rel.child);
+    }
+
+    // One route per top-level table (skip children)
     for (const m of meta) {
+      if (nestedChildren.has(m.table)) continue;
       planned.push({
         relPath: `routes/${m.table}.js`,
         content: generateRouteFile(m.table, modelsRelPath),
       });
     }
 
-    // Child route files (one per relationship)
+    // Child route files in subfolders: routes/<parent>/<child>.js
     for (const rel of relationships) {
       planned.push({
-        relPath: `routes/${rel.child}_child_of_${rel.parent}.js`,
+        relPath: `routes/${rel.parent}/${rel.child}.js`,
         content: generateChildRouteFile(
           rel.child,
           rel.parent,
           rel.foreignKey,
-          modelsRelPath,
+          `../../models`,
         ),
       });
     }
 
-    // Routes index file
+    // Routes index file (include docs route when openapi is being generated)
     planned.push({
       relPath: "routes/index.js",
-      content: generateRoutesIndexFile(tableNames, relationships),
+      content: generateRoutesIndexFile(tableNames, relationships, {
+        includeDocs: genOpenapi,
+      }),
     });
   }
 
-  // --- OpenAPI spec ---
+  // --- OpenAPI spec + docs route ---
   if (genOpenapi) {
     planned.push({
       relPath: "openapi.json",
       content: JSON.stringify(generateOpenAPISpec(meta), null, 2) + "\n",
     });
+
+    // Generate Swagger UI docs route
+    planned.push({
+      relPath: "routes/docs.js",
+      content: generateDocsRoute(),
+    });
+  }
+
+  // --- Migration files ---
+  if (genMigrations) {
+    const migrationFiles = generateMigrationFiles(schema);
+    const ts = migrationTimestamp(new Date());
+    for (const mf of migrationFiles) {
+      planned.push({
+        relPath: `migrations/${ts}_${mf.filename}`,
+        content: mf.content,
+      });
+    }
   }
 
   // --- Test files ---
   if (genTests) {
+    // Collect child tables to skip generating top-level test files for them
+    const nestedChildrenForTests = new Set();
+    for (const rel of relationships) {
+      nestedChildrenForTests.add(rel.child);
+    }
+
     for (const m of meta) {
+      if (nestedChildrenForTests.has(m.table)) continue;
       planned.push({
         relPath: `test/${m.table}.test.js`,
         content: generateTestFile(m.table, m.primary_key),
       });
     }
 
-    // Child test files (one per relationship)
+    // Child test files in subfolders: test/<parent>/<child>.test.js
     for (const rel of relationships) {
       const childMeta = meta.find((m) => m.table === rel.child);
       const pk = childMeta ? childMeta.primary_key : "id";
       planned.push({
-        relPath: `test/${rel.child}_child_of_${rel.parent}.test.js`,
+        relPath: `test/${rel.parent}/${rel.child}.test.js`,
         content: generateChildTestFile(
           rel.child,
           rel.parent,

package/src/cli/commands/help.js

@@ -8,7 +8,7 @@ const COMMAND_HELP = {
   init: `Usage: db-model-router init [options]
 
 Scaffold a new project from a schema file or interactively.
-Creates app.js, .env, commons/, route/, middleware/, and migrations/.
+Creates app.js, .env, commons/, routes/, middleware/, and migrations/.
 
 Options:
   --from <path>          Read adapter, framework, and options from a schema file
@@ -18,7 +18,7 @@ Options:
   --db <name>            Alias for --database
   --session <type>       Session store: memory, redis, database
   --output <dir>         Directory for backend source files (relative to cwd).
-                         package.json and app.js stay in root; commons/, route/,
+                         package.json and app.js stay in root; commons/, routes/,
                          middleware/, and migrations/ go inside this folder.
   --rateLimiting         Enable rate limiting (default: yes)
   --helmet               Enable Helmet security headers (default: yes)
@@ -39,8 +39,8 @@ Generated files:
   <output>/commons/add_migration.js   Migration creation helper (also runs as script)
   <output>/commons/security.js        Helmet, rate limiting, custom headers
   <output>/middleware/logger.js        Winston + Loki request logger
-  <output>/route/index.js             Central route mounting
-  <output>/route/health.js            GET /health endpoint
+  <output>/routes/index.js             Central route mounting
+  <output>/routes/health.js            GET /health endpoint
   <output>/migrations/                Initial migration files
 
 Examples:
@@ -79,8 +79,9 @@ Options:
   --from <path>          Path to schema file (default: dbmr.schema.json)
   --models               Generate only model files
   --routes               Generate only route files (including child routes and index)
-  --openapi              Generate only OpenAPI spec
+  --openapi              Generate only OpenAPI spec + Swagger UI docs route
   --tests                Generate only test files
+  --migrations           Generate only database migration files
   --llm-docs             Generate only LLM documentation (llms.txt + docs/llm.md)
   --yes                  Accept all defaults without prompting
   --json                 Output machine-readable JSON
@@ -90,8 +91,11 @@ Options:
 Generated files:
   models/<table>.js                        Model with CRUD operations
   routes/<table>.js                        Express route handlers
-  routes/<child>_child_of_<parent>.js      Child route (scoped by FK)
+  routes/<parent>/<child>.js               Child route (scoped by FK)
+  routes/docs.js                           Swagger UI at /docs
   routes/index.js                          Route mounting index
+  migrations/<timestamp>_create_tables.sql Database migration (SQL adapters)
+  migrations/<timestamp>_create_<t>.js     Database migration (NoSQL adapters)
   test/<table>.test.js                     CRUD endpoint tests
   openapi.json                             OpenAPI 3.0 spec
   llms.txt                                 LLM quick reference
@@ -101,6 +105,7 @@ Examples:
   db-model-router generate --from dbmr.schema.json
   db-model-router generate --models --dry-run
   db-model-router generate --routes --tests
+  db-model-router generate --migrations
   db-model-router generate --from dbmr.schema.json --json`,
 
   doctor: `Usage: db-model-router doctor [options]

package/src/cli/commands/init.js

@@ -165,8 +165,8 @@ function planFiles(answers, outputDir) {
     `${prefix}commons/add_migration.js`,
     `${prefix}commons/security.js`,
     `${prefix}commons/db.js`,
-    `${prefix}route/health.js`,
-    `${prefix}route/index.js`,
+    `${prefix}routes/health.js`,
+    `${prefix}routes/index.js`,
     `${prefix}migrations/<timestamp>_create_migrations_table` +
       (isSql(answers.database) ? ".sql" : ".js"),
   );

package/src/cli/commands/inspect.js

@@ -79,6 +79,7 @@ function modelMetaToSchema(adapter, framework, models) {
       unique,
       softDelete,
       timestamps,
+      parent: null,
     };
   }
 

package/src/cli/diff-engine.js

@@ -11,6 +11,7 @@ const {
   generateChildTestFile,
 } = require("./generate-route.js");
 const { generateOpenAPISpec } = require("./generate-openapi.js");
+const { generateDocsRoute } = require("./generate-docs-route.js");
 
 /**
  * Simple line-by-line diff between two strings.
@@ -52,54 +53,63 @@ function buildExpectedFiles(meta, relationships) {
   const modelsRelPath = "../models";
   const tableNames = meta.map((m) => m.table).sort();
 
+  // Collect child tables
+  const nestedChildren = new Set();
+  for (const rel of relationships) {
+    nestedChildren.add(rel.child);
+  }
+
   // Model files
   for (const m of meta) {
     expected.set(`models/${m.table}.js`, generateModelFile(m));
   }
 
-  // Route files (one per table)
+  // Route files (top-level only, skip children)
   for (const m of meta) {
+    if (nestedChildren.has(m.table)) continue;
     expected.set(
       `routes/${m.table}.js`,
       generateRouteFile(m.table, modelsRelPath),
     );
   }
 
-  // Child route files (one per relationship)
+  // Child route files in subfolders: routes/<parent>/<child>.js
   for (const rel of relationships) {
-    const childMeta = meta.find((m) => m.table === rel.child);
-    const pk = childMeta ? childMeta.primary_key : "id";
     expected.set(
-      `routes/${rel.child}_child_of_${rel.parent}.js`,
+      `routes/${rel.parent}/${rel.child}.js`,
       generateChildRouteFile(
         rel.child,
         rel.parent,
         rel.foreignKey,
-        modelsRelPath,
+        `../../models`,
       ),
     );
   }
 
-  // Routes index file
+  // Routes index file (with docs route)
   expected.set(
     "routes/index.js",
-    generateRoutesIndexFile(tableNames, relationships),
+    generateRoutesIndexFile(tableNames, relationships, { includeDocs: true }),
   );
 
-  // Test files (one per table)
+  // Docs route (Swagger UI)
+  expected.set("routes/docs.js", generateDocsRoute());
+
+  // Test files (top-level only, skip children)
   for (const m of meta) {
+    if (nestedChildren.has(m.table)) continue;
     expected.set(
       `test/${m.table}.test.js`,
       generateTestFile(m.table, m.primary_key),
     );
   }
 
-  // Child test files (one per relationship)
+  // Child test files in subfolders: test/<parent>/<child>.test.js
   for (const rel of relationships) {
     const childMeta = meta.find((m) => m.table === rel.child);
     const pk = childMeta ? childMeta.primary_key : "id";
     expected.set(
-      `test/${rel.child}_child_of_${rel.parent}.test.js`,
+      `test/${rel.parent}/${rel.child}.test.js`,
       generateChildTestFile(rel.child, rel.parent, rel.foreignKey, pk),
     );
   }
@@ -115,7 +125,7 @@ function buildExpectedFiles(meta, relationships) {
 
 /**
  * Scan known artifact directories on disk and return a set of relative paths
- * that exist.
+ * that exist. Recursively scans subdirectories.
  *
  * @param {string} baseDir
  * @returns {Set<string>}
@@ -123,22 +133,42 @@ function buildExpectedFiles(meta, relationships) {
 function scanDiskFiles(baseDir) {
   const files = new Set();
 
-  const dirs = [
-    { dir: "models", ext: ".js" },
-    { dir: "routes", ext: ".js" },
-    { dir: "test", ext: ".test.js" },
-  ];
+  function scanDir(dir, prefix) {
+    const fullDir = path.join(baseDir, dir);
+    if (!fs.existsSync(fullDir)) return;
+    for (const entry of fs.readdirSync(fullDir, { withFileTypes: true })) {
+      const relPath = prefix
+        ? `${prefix}/${entry.name}`
+        : `${dir}/${entry.name}`;
+      if (entry.isDirectory()) {
+        scanDir(path.join(dir, entry.name), relPath);
+      } else if (entry.name.endsWith(".js")) {
+        files.add(relPath);
+      }
+    }
+  }
+
+  scanDir("models");
+  scanDir("routes");
 
-  for (const { dir, ext } of dirs) {
+  // For test dir, only include .test.js files
+  function scanTestDir(dir, prefix) {
     const fullDir = path.join(baseDir, dir);
-    if (!fs.existsSync(fullDir)) continue;
-    for (const file of fs.readdirSync(fullDir)) {
-      if (file.endsWith(ext)) {
-        files.add(`${dir}/${file}`);
+    if (!fs.existsSync(fullDir)) return;
+    for (const entry of fs.readdirSync(fullDir, { withFileTypes: true })) {
+      const relPath = prefix
+        ? `${prefix}/${entry.name}`
+        : `${dir}/${entry.name}`;
+      if (entry.isDirectory()) {
+        scanTestDir(path.join(dir, entry.name), relPath);
+      } else if (entry.name.endsWith(".test.js")) {
+        files.add(relPath);
       }
     }
   }
 
+  scanTestDir("test");
+
   // Check for openapi.json at root
   const openapiPath = path.join(baseDir, "openapi.json");
   if (fs.existsSync(openapiPath)) {

package/src/cli/generate-docs-route.js

@@ -0,0 +1,31 @@
+"use strict";
+
+/**
+ * Generate a routes/docs.js file that serves Swagger UI for the OpenAPI spec.
+ * Uses swagger-ui-express to mount at /docs.
+ *
+ * @returns {string}
+ */
+function generateDocsRoute() {
+  return `import express from "express";
+import swaggerUi from "swagger-ui-express";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const spec = JSON.parse(readFileSync(join(__dirname, "../openapi.json"), "utf8"));
+
+const router = express.Router();
+
+router.use("/", swaggerUi.serve);
+router.get("/", swaggerUi.setup(spec, {
+  customSiteTitle: "API Documentation",
+  customCss: ".swagger-ui .topbar { display: none }",
+}));
+
+export default router;
+`;
+}
+
+module.exports = { generateDocsRoute };