db-model-router 1.0.0

package/docs/README.md

@@ -0,0 +1,208 @@
+# rest-router
+
+A database-agnostic REST API generator for Node.js. Works with Express or ultimate-express (a high-performance drop-in replacement). Define a model, get a full CRUD API with filtering, pagination, and bulk operations — backed by any of 9 supported databases.
+
+## Supported Adapters
+
+| Adapter                                  | Module Key    | Driver                   | Install                                                                |
+| ---------------------------------------- | ------------- | ------------------------ | ---------------------------------------------------------------------- |
+| [MySQL](#mysql-example)                  | `mysql`       | mysql2                   | `npm i db-model-router mysql2`                                         |
+| [PostgreSQL](./adapters/postgres.md)     | `postgres`    | pg                       | `npm i db-model-router pg`                                             |
+| [SQLite3](./adapters/sqlite3.md)         | `sqlite3`     | better-sqlite3           | `npm i db-model-router better-sqlite3`                                 |
+| [MongoDB](./adapters/mongodb.md)         | `mongodb`     | mongodb                  | `npm i db-model-router mongodb`                                        |
+| [MSSQL](./adapters/mssql.md)             | `mssql`       | mssql                    | `npm i db-model-router mssql`                                          |
+| [CockroachDB](./adapters/cockroachdb.md) | `cockroachdb` | pg                       | `npm i db-model-router pg`                                             |
+| [Oracle](./adapters/oracle.md)           | `oracle`      | oracledb                 | `npm i db-model-router oracledb`                                       |
+| [Redis](./adapters/redis.md)             | `redis`       | ioredis                  | `npm i db-model-router ioredis`                                        |
+| [DynamoDB](./adapters/dynamodb.md)       | `dynamodb`    | @aws-sdk/client-dynamodb | `npm i db-model-router @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb` |
+
+## Installation
+
+Install the core package, your preferred Express framework, and the driver for your database:
+
+```bash
+# Pick your Express framework (one of the two)
+npm install express
+# OR for ~6x faster performance:
+npm install ultimate-express
+
+# Then install db-model-router + your database driver
+npm install db-model-router <driver>
+```
+
+Both `express` and `ultimate-express` are optional peer dependencies — the library auto-detects which one is installed (preferring `ultimate-express` when both are present). All database drivers are also optional peer dependencies.
+
+## MySQL Example
+
+### 1. Connect
+
+```js
+const { init, db, model, route } = require("db-model-router");
+
+// Default adapter is mysql, so init() is optional
+db.connect({
+  host: "localhost",
+  port: 3306,
+  user: "root",
+  password: "password",
+  database: "my_app",
+  connectionLimit: 100,
+});
+```
+
+### 2. Define a Model
+
+```js
+const users = model(
+  db,
+  "users",
+  {
+    name: "required|string",
+    email: "required|string",
+    age: "required|integer",
+    meta: "object",
+  },
+  "id",
+  ["email"],
+  { safeDelete: "is_deleted" },
+);
+```
+
+Schema types: `string`, `integer`, `numeric`, `object`. Prefix with `required|` to enforce on insert/update.
+
+### 3. Mount REST Routes
+
+```js
+// Works with either express or ultimate-express
+const express = require("express"); // or require("ultimate-express")
+const app = express();
+app.use(express.json());
+app.use("/users", route(users));
+app.listen(3000);
+```
+
+This creates 9 endpoints:
+
+| Method | Path         | Description                     |
+| ------ | ------------ | ------------------------------- |
+| GET    | `/users/:id` | Get one record by PK            |
+| POST   | `/users/:id` | Insert a single record          |
+| PUT    | `/users/:id` | Update a single record          |
+| PATCH  | `/users/:id` | Partial update (changed fields) |
+| DELETE | `/users/:id` | Delete a single record          |
+| GET    | `/users/`    | List with pagination            |
+| POST   | `/users/`    | Bulk insert (`{ data: [...] }`) |
+| PUT    | `/users/`    | Bulk update (`{ data: [...] }`) |
+| DELETE | `/users/`    | Bulk delete                     |
+
+### 4. Payload Override
+
+Inject values from the request into every payload (useful for multi-tenant apps):
+
+```js
+app.use("/users", route(users, { user_id: "user.user_id" }));
+```
+
+## Model API
+
+All model methods are async.
+
+### insert / update / patch / upsert
+
+```js
+const user = await users.insert({ name: "Alice", email: "a@b.com", age: 30 });
+const bulk = await users.insert({ data: [{ ... }, { ... }] });
+const updated = await users.update({ id: 1, name: "Alice V2", email: "a@b.com", age: 31 });
+const patched = await users.patch({ id: 1, age: 35 }); // partial — only updates age
+```
+
+### byId / find / findOne / list
+
+```js
+await users.byId(1); // record or null
+await users.find({ name: "Alice" }); // { data: [...], count }
+await users.findOne({ email: "a@b.com" }); // record or false
+await users.list({ page: 0, size: 10, sort: ["-age"] }); // { data: [...], count }
+```
+
+### remove
+
+```js
+await users.remove(1);
+await users.remove({ name: "Bob" });
+```
+
+## Filter System
+
+Structure: `[OR_groups[AND_conditions[column, operator, value]]]`
+
+Operators: `=`, `like`, `not like`, `in`, `not in`, `<`, `>`, `<=`, `>=`, `!=`
+
+```js
+// Alice AND age 30
+await db.get("users", [
+  [
+    ["name", "=", "Alice"],
+    ["age", "=", 30],
+  ],
+]);
+
+// Alice OR age > 30
+await db.get("users", [[["name", "=", "Alice"]], [["age", ">", 30]]]);
+```
+
+## Switching Adapters
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("postgres"); // or "mongodb", "sqlite3", "mssql", etc.
+db.connect({
+  host: "localhost",
+  port: 5432,
+  user: "postgres",
+  password: "password",
+  database: "my_app",
+});
+```
+
+The model and route APIs remain identical across all adapters.
+
+## CLI Tools
+
+### generate-app
+
+Scaffolds a complete Express REST API from an existing database.
+
+```bash
+rest-router-generate-app --type mysql --env .env
+rest-router-generate-app --type sqlite3 --database ./myapp.db --output ./my-api
+rest-router-generate-app --type postgres --env .env --tables users,posts,posts.comments
+```
+
+Creates: `app.js`, `models/`, `routes/`, `middleware/logger.js`, `.env.example`, `openapi.json`
+
+### generate-model
+
+Introspects DB → generates model files with auto-detected PK, unique indexes, timestamps, soft-delete.
+
+```bash
+rest-router-generate-model --type mysql --env .env --output ./models [--tables users,posts]
+```
+
+### generate-route
+
+Generates route files + OpenAPI spec from models. Supports parent-child via dot notation.
+
+```bash
+rest-router-generate-route --models ./models --output ./routes [--tables posts,posts.comments]
+```
+
+`posts.comments` → nested route `posts/:post_id/comments` with FK scoping.
+
+## License
+
+Apache-2.0
+
+## LLM Skill Reference
+
+For AI/LLM integration, see the [Skill Reference](./SKILL.md).

package/docs/SKILL.md

@@ -0,0 +1,202 @@
+# db-model-router — LLM Skill Reference
+
+Database-agnostic REST API generator for Node.js/Express. Define model → get CRUD API + Express routes. 9 adapters, identical API.
+
+## Install
+
+```bash
+npm install db-model-router <driver>
+```
+
+Drivers: `mysql2`, `pg`, `better-sqlite3`, `mongodb`, `mssql`, `oracledb`, `ioredis`, `@aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb`
+
+## Init → Connect → Model → Route
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("postgres"); // mysql|postgres|sqlite3|mongodb|mssql|cockroachdb|oracle|redis|dynamodb
+db.connect({ host, port: 5432, user, password, database });
+
+const users = model(
+  db,
+  "users",
+  {
+    name: "required|string",
+    email: "required|string",
+    age: "integer",
+    meta: "object",
+  },
+  "id",
+  ["email"],
+  {
+    safeDelete: "is_deleted",
+    created_at: "created_at",
+    modified_at: "updated_at",
+  },
+);
+
+app.use("/users", route(users));
+```
+
+**Critical**: call `init()` before `db.connect()`. Default adapter is mysql. Do NOT destructure `db` before `init()`.
+
+## model(db, table, structure, pk, unique, option)
+
+| Param     | Type            | Description                                                                                                           |
+| --------- | --------------- | --------------------------------------------------------------------------------------------------------------------- |
+| structure | `{col: "rule"}` | Types: `string\|integer\|numeric\|object`. Prefix `required\|` for NOT NULL. Exclude PK, timestamps, soft-delete cols |
+| pk        | string          | Primary key column. Default `"id"`                                                                                    |
+| unique    | string[]        | Columns for upsert conflict resolution                                                                                |
+| option    | object          | `{ safeDelete, created_at, modified_at }` — column names or null                                                      |
+
+## Model Methods (all async)
+
+```js
+// INSERT — single returns record, bulk returns {rows, message, type}
+await m.insert({ name: "Alice", email: "a@b.com", age: 30 })        // → {id:1, name:"Alice", ...}
+await m.insert({ data: [{...}, {...}] })                              // → {rows:2, message, type:"success"}
+
+// UPDATE — PK required in payload
+await m.update({ id: 1, name: "Alice V2", email: "a@b.com", age: 31 })
+await m.update({ data: [{id:1,...}, {id:2,...}] })
+
+// PATCH — partial update, only sends changed fields, PK required
+await m.patch({ id: 1, age: 35 })                                    // → full merged record
+
+// UPSERT — PK optional, uses unique cols for conflict
+await m.upsert({ email: "new@b.com", name: "New", age: 20 })
+
+// READ
+await m.byId(1)                                                       // → record or null
+await m.find({ name: "Alice" })                                       // → {data:[], count}
+await m.findOne({ email: "a@b.com" })                                 // → record or false
+await m.list({ page: 0, size: 10, sort: ["-age"] })                   // → {data:[], count}
+
+// DELETE — with safeDelete: sets column=1; without: hard delete
+await m.remove(1)
+await m.remove({ name: "Bob" })
+```
+
+## Filter Syntax
+
+Structure: `[OR_groups[AND_conditions[col, op, val]]]`
+Ops: `= != < > <= >= like not like in not in`
+
+```js
+[
+  [
+    ["age", ">", 25],
+    ["type", "=", 1],
+  ],
+][([["name", "=", "A"]], [["name", "=", "B"]])][[["type", "in", [1, 2, 3]]]][ // AND // OR // IN
+  [["name", "like", "Ali"]]
+]; // LIKE %Ali%
+```
+
+## route(model, override?)
+
+Generates Express Router with 9 endpoints:
+
+| Method | Path   | Action                           |
+| ------ | ------ | -------------------------------- |
+| GET    | `/:pk` | Get by PK                        |
+| POST   | `/:id` | Insert single                    |
+| PUT    | `/:id` | Update single (PK from URL)      |
+| PATCH  | `/:id` | Partial update                   |
+| DELETE | `/:id` | Delete single                    |
+| GET    | `/`    | List (page, size, sort, filters) |
+| POST   | `/`    | Bulk insert `{data:[...]}`       |
+| PUT    | `/`    | Bulk update `{data:[...]}`       |
+| DELETE | `/`    | Bulk delete `{data:[...]}`       |
+
+**Payload override** (multi-tenancy): `route(m, { tenant_id: "user.tenant_id" })` — maps cols to `req` paths via lodash.get.
+
+**Query params**: `select_columns=name,email`, `output_content_type=csv|xml|json`, `sort=-age,name`
+
+## CLI Tools
+
+### generate-app (full scaffold)
+
+```bash
+rest-router-generate-app --type mysql --env .env [--output ./dir] [--tables users,posts,posts.comments]
+```
+
+Creates: `app.js`, `models/`, `routes/`, `middleware/logger.js`, `.env.example`, `.gitignore`, `migrations/`, `sessions/`, `openapi.json`
+
+### generate-model (DB introspection → model files)
+
+```bash
+rest-router-generate-model --type <db> --env .env [--output ./models] [--tables t1,t2] [--schema public]
+```
+
+Auto-detects: PK, unique indexes, DEFAULT→optional, timestamp cols, soft-delete cols.
+
+### generate-route (model files → route files + OpenAPI)
+
+```bash
+rest-router-generate-route --models ./models --output ./routes [--tables posts,posts.comments]
+```
+
+Dot notation `parent.child` creates nested routes: `parent/:parent_id/child` with FK scoping via `<parent_singular>_id`.
+
+## Connection Configs
+
+```js
+// MySQL (default)
+db.connect({
+  host,
+  port: 3306,
+  user,
+  password,
+  database,
+  connectionLimit: 100,
+});
+
+// PostgreSQL / CockroachDB
+init("postgres"); // cockroachdb port: 26257
+db.connect({ host, port: 5432, user, password, database });
+
+// SQLite3
+init("sqlite3");
+db.connect({ database: "./file.db" }); // or ":memory:"
+
+// MongoDB
+init("mongodb");
+db.connect({ host, port: 27017, username, password, database });
+// or: db.connect({ uri: "mongodb://user:pass@host:27017/db" })
+
+// MSSQL
+init("mssql");
+await db.connect({
+  server: host,
+  port: 1433,
+  user,
+  password,
+  database,
+  options: { encrypt: false, trustServerCertificate: true },
+});
+
+// Oracle
+init("oracle");
+db.connect({ host, port: 1521, user, password, database });
+
+// Redis
+init("redis");
+db.connect({ host, port: 6379, password });
+
+// DynamoDB
+init("dynamodb");
+db.connect({ region, endpoint, accessKeyId, secretAccessKey });
+```
+
+## Rules
+
+1. `init()` before `db.connect()`. Don't destructure `db` before `init()`.
+2. `modelStructure` excludes: PK col, timestamp cols, soft-delete cols.
+3. `update()`/`patch()` require PK in payload. `upsert()` PK is optional.
+4. `findOne()` returns `false` on no match. `byId()` returns `null`.
+5. Bulk ops wrap in `{ data: [...] }`. Single ops use flat object.
+6. Timestamps auto-stripped from payloads. DB handles defaults/triggers.
+7. `safeDelete` makes `remove()` soft-delete; all reads auto-filter deleted rows.
+8. `list()` defaults: page=0, size=30. `sort` array: `["-col"]` for DESC.
+9. CommonJS only (`require`). Use dynamic `import()` for ESM.

package/docs/adapters/cockroachdb.md

@@ -0,0 +1,49 @@
+# CockroachDB Adapter
+
+Uses the [pg](https://www.npmjs.com/package/pg) driver (CockroachDB is PostgreSQL wire-compatible).
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("cockroachdb");
+
+db.connect({
+  host: "localhost",
+  port: 26257,
+  database: "defaultdb",
+  user: "root",
+  password: "",
+});
+```
+
+## Environment Variables
+
+```env
+CRDB_HOST=localhost
+CRDB_PORT=26257
+CRDB_NAME=defaultdb
+CRDB_USER=root
+CRDB_PASS=
+```
+
+## Notes
+
+- `SERIAL` columns use CockroachDB's `unique_rowid()` which generates INT8 values
+- Large INT8 values that exceed `Number.MAX_SAFE_INTEGER` are kept as strings to preserve precision
+- Includes automatic retry logic for transient connection errors
+- Uses `ON CONFLICT` for upsert operations
+- Run with `--insecure` flag for local development (see docker-compose.yml)
+
+## 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/docs/adapters/dynamodb.md

@@ -0,0 +1,53 @@
+# DynamoDB Adapter
+
+Uses [@aws-sdk/client-dynamodb](https://www.npmjs.com/package/@aws-sdk/client-dynamodb) and [@aws-sdk/lib-dynamodb](https://www.npmjs.com/package/@aws-sdk/lib-dynamodb).
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("dynamodb");
+
+db.connect({
+  region: "us-east-1",
+  // For local development (DynamoDB Local):
+  endpoint: "http://localhost:8000",
+  accessKeyId: "fakeAccessKey",
+  secretAccessKey: "fakeSecretKey",
+  primaryKey: "id",
+});
+```
+
+## Environment Variables
+
+```env
+DYNAMODB_HOST=localhost
+DYNAMODB_PORT=8000
+DYNAMODB_REGION=us-east-1
+DYNAMODB_ACCESS_KEY=fakeAccessKey
+DYNAMODB_SECRET_KEY=fakeSecretKey
+```
+
+## Notes
+
+- Tables must be created beforehand (the adapter does not create tables)
+- Auto-generates UUID primary keys for records missing the PK field
+- Filter operators are mapped to DynamoDB FilterExpression syntax
+- `like` uses `contains()`, `in` uses `IN ()`
+- All filtering and pagination happen via `Scan` with in-memory post-processing
+- Batch writes are chunked into groups of 25 (DynamoDB limit)
+- `UpdateCommand` is used for upsert operations
+- Best suited for serverless / AWS-native architectures
+
+## Table Creation (AWS CLI)
+
+```bash
+aws dynamodb create-table \
+  --table-name users \
+  --attribute-definitions AttributeName=id,AttributeType=S \
+  --key-schema AttributeName=id,KeyType=HASH \
+  --billing-mode PAY_PER_REQUEST \
+  --endpoint-url http://localhost:8000
+```
+
+[← Back to main docs](../README.md)

package/docs/adapters/mongodb.md

@@ -0,0 +1,56 @@
+# MongoDB Adapter
+
+Uses the official [mongodb](https://www.npmjs.com/package/mongodb) Node.js driver.
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("mongodb");
+
+db.connect({
+  host: "localhost",
+  port: 27017,
+  database: "my_app",
+  // or with auth:
+  username: "admin",
+  password: "secret",
+  // or with a full URI:
+  uri: "mongodb://admin:secret@localhost:27017",
+});
+```
+
+## Environment Variables
+
+```env
+MONGO_HOST=localhost
+MONGO_PORT=27017
+MONGO_DB=test_db
+```
+
+## Notes
+
+- Primary key is `_id` (MongoDB's default ObjectId)
+- String `_id` values matching the 24-char hex format are auto-converted to `ObjectId`
+- Filter operators are mapped to MongoDB query operators (`$eq`, `$regex`, `$in`, etc.)
+- `like` uses `$regex` with case-insensitive matching
+- No schema/table creation needed — collections are created on first insert
+
+## 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/docs/adapters/mssql.md

@@ -0,0 +1,55 @@
+# MSSQL (SQL Server) Adapter
+
+Uses the [mssql](https://www.npmjs.com/package/mssql) driver with tedious.
+
+## Connection
+
+```js
+const { init, db, model, route } = require("db-model-router");
+init("mssql");
+
+await db.connect({
+  server: "localhost",
+  port: 1433,
+  database: "master",
+  user: "sa",
+  password: "Password123!",
+  options: {
+    encrypt: false,
+    trustServerCertificate: true,
+  },
+});
+```
+
+Note: `db.connect()` is async for MSSQL — use `await`.
+
+## Environment Variables
+
+```env
+MSSQL_HOST=localhost
+MSSQL_PORT=1433
+MSSQL_DB=master
+MSSQL_USER=sa
+MSSQL_PASSWORD=Password123!
+```
+
+## Notes
+
+- Column names are escaped with `[brackets]`
+- Uses `MERGE` statements for upsert operations
+- IDENTITY columns are auto-excluded from INSERT in MERGE statements
+- Pagination uses `OFFSET ... ROWS FETCH NEXT ... ROWS ONLY`
+- `OUTPUT INSERTED.*` is used to return inserted rows
+
+## Table Creation
+
+```sql
+CREATE TABLE users (
+  id INT IDENTITY(1,1) PRIMARY KEY,
+  name NVARCHAR(255),
+  email NVARCHAR(255),
+  age INT
+);
+```
+
+[← Back to main docs](../README.md)

package/docs/adapters/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)