db-model-router 1.0.3 → 1.0.5

package/demo/dbmr.schema.json

@@ -0,0 +1,362 @@
+{
+  "adapter": "sqlite3",
+  "framework": "express",
+  "options": {
+    "rateLimiting": true,
+    "helmet": true,
+    "logger": true
+  },
+  "tables": {
+    "users": {
+      "columns": {
+        "user_id": "auto_increment",
+        "name": "required|string",
+        "email": "required|string",
+        "password_hash": "required|string",
+        "phone": "string",
+        "avatar_url": "string",
+        "role": "required|string",
+        "is_deleted": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "user_id",
+      "unique": [
+        "email"
+      ],
+      "softDelete": "is_deleted",
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "addresses": {
+      "columns": {
+        "address_id": "auto_increment",
+        "user_id": "required|integer",
+        "label": "string",
+        "line1": "required|string",
+        "line2": "string",
+        "city": "required|string",
+        "state": "required|string",
+        "postal_code": "required|string",
+        "country": "required|string",
+        "is_default": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "address_id",
+      "unique": [
+        "address_id"
+      ],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "categories": {
+      "columns": {
+        "category_id": "auto_increment",
+        "name": "required|string",
+        "slug": "required|string",
+        "description": "string",
+        "parent_category_id": "integer",
+        "image_url": "string",
+        "sort_order": "integer",
+        "is_active": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "category_id",
+      "unique": [
+        "slug"
+      ],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "products": {
+      "columns": {
+        "product_id": "auto_increment",
+        "category_id": "required|integer",
+        "name": "required|string",
+        "slug": "required|string",
+        "description": "string",
+        "short_description": "string",
+        "sku": "required|string",
+        "price": "required|numeric",
+        "compare_at_price": "numeric",
+        "cost_price": "numeric",
+        "currency": "required|string",
+        "stock_quantity": "required|integer",
+        "low_stock_threshold": "integer",
+        "weight": "numeric",
+        "weight_unit": "string",
+        "is_active": "boolean",
+        "is_featured": "boolean",
+        "is_deleted": "boolean",
+        "meta": "object",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "product_id",
+      "unique": [
+        "sku",
+        "slug"
+      ],
+      "softDelete": "is_deleted",
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "product_images": {
+      "columns": {
+        "product_image_id": "auto_increment",
+        "product_id": "required|integer",
+        "url": "required|string",
+        "alt_text": "string",
+        "sort_order": "integer",
+        "is_primary": "boolean",
+        "created_at": "datetime"
+      },
+      "pk": "product_image_id",
+      "unique": [
+        "product_image_id"
+      ],
+      "timestamps": {
+        "created_at": "created_at"
+      },
+      "parent": "products"
+    },
+    "product_variants": {
+      "columns": {
+        "variant_id": "auto_increment",
+        "product_id": "required|integer",
+        "name": "required|string",
+        "sku": "required|string",
+        "price": "required|numeric",
+        "stock_quantity": "required|integer",
+        "attributes": "object",
+        "is_active": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "variant_id",
+      "unique": [
+        "sku"
+      ],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": "products"
+    },
+    "product_reviews": {
+      "columns": {
+        "review_id": "auto_increment",
+        "product_id": "required|integer",
+        "user_id": "required|integer",
+        "rating": "required|integer",
+        "title": "string",
+        "body": "string",
+        "is_verified": "boolean",
+        "is_approved": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "review_id",
+      "unique": [
+        "review_id"
+      ],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": "products"
+    },
+    "carts": {
+      "columns": {
+        "cart_id": "auto_increment",
+        "user_id": "integer",
+        "session_id": "string",
+        "currency": "required|string",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "cart_id",
+      "unique": [
+        "cart_id"
+      ],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "cart_items": {
+      "columns": {
+        "cart_item_id": "auto_increment",
+        "cart_id": "required|integer",
+        "product_id": "required|integer",
+        "variant_id": "integer",
+        "quantity": "required|integer",
+        "unit_price": "required|numeric",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "cart_item_id",
+      "unique": [
+        "cart_item_id"
+      ],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": "carts"
+    },
+    "orders": {
+      "columns": {
+        "order_id": "auto_increment",
+        "user_id": "required|integer",
+        "order_number": "required|string",
+        "status": "required|string",
+        "subtotal": "required|numeric",
+        "tax_amount": "required|numeric",
+        "shipping_amount": "required|numeric",
+        "discount_amount": "numeric",
+        "total": "required|numeric",
+        "currency": "required|string",
+        "shipping_address_id": "integer",
+        "billing_address_id": "integer",
+        "notes": "string",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "order_id",
+      "unique": [
+        "order_number"
+      ],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "order_items": {
+      "columns": {
+        "order_item_id": "auto_increment",
+        "order_id": "required|integer",
+        "product_id": "required|integer",
+        "variant_id": "integer",
+        "product_name": "required|string",
+        "sku": "required|string",
+        "quantity": "required|integer",
+        "unit_price": "required|numeric",
+        "total_price": "required|numeric",
+        "created_at": "datetime"
+      },
+      "pk": "order_item_id",
+      "unique": [
+        "order_item_id"
+      ],
+      "timestamps": {
+        "created_at": "created_at"
+      },
+      "parent": "orders"
+    },
+    "payments": {
+      "columns": {
+        "payment_id": "auto_increment",
+        "order_id": "required|integer",
+        "method": "required|string",
+        "provider": "string",
+        "provider_transaction_id": "string",
+        "amount": "required|numeric",
+        "currency": "required|string",
+        "status": "required|string",
+        "paid_at": "datetime",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "payment_id",
+      "unique": [
+        "payment_id"
+      ],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": "orders"
+    },
+    "shipments": {
+      "columns": {
+        "shipment_id": "auto_increment",
+        "order_id": "required|integer",
+        "carrier": "required|string",
+        "tracking_number": "string",
+        "status": "required|string",
+        "shipped_at": "datetime",
+        "delivered_at": "datetime",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "shipment_id",
+      "unique": [
+        "shipment_id"
+      ],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": "orders"
+    },
+    "coupons": {
+      "columns": {
+        "coupon_id": "auto_increment",
+        "code": "required|string",
+        "description": "string",
+        "discount_type": "required|string",
+        "discount_value": "required|numeric",
+        "min_order_amount": "numeric",
+        "max_uses": "integer",
+        "used_count": "integer",
+        "starts_at": "datetime",
+        "expires_at": "datetime",
+        "is_active": "boolean",
+        "created_at": "datetime",
+        "updated_at": "datetime"
+      },
+      "pk": "coupon_id",
+      "unique": [
+        "code"
+      ],
+      "timestamps": {
+        "created_at": "created_at",
+        "modified_at": "updated_at"
+      },
+      "parent": null
+    },
+    "wishlists": {
+      "columns": {
+        "wishlist_id": "auto_increment",
+        "user_id": "required|integer",
+        "product_id": "required|integer",
+        "created_at": "datetime"
+      },
+      "pk": "wishlist_id",
+      "unique": [
+        "wishlist_id"
+      ],
+      "timestamps": {
+        "created_at": "created_at"
+      },
+      "parent": null
+    }
+  }
+}

package/demo/docs/llm.md

@@ -0,0 +1,197 @@
+# db-model-router — LLM Reference
+
+## Installation
+
+```bash
+npm install db-model-router
+```
+
+## Canonical Schema-Driven Workflow
+
+1. Create or inspect a `dbmr.schema.json` schema file
+2. Run `db-model-router generate --from dbmr.schema.json` to generate all artifacts
+3. Run `db-model-router doctor` to validate schema and check sync
+4. Run `db-model-router diff` to preview changes before regenerating
+5. Edit the schema file and repeat from step 2
+
+## Schema Definition
+
+The `dbmr.schema.json` file is the single source of truth for your project.
+
+```json
+{
+  "adapter": "<adapter>",
+  "framework": "<framework>",
+  "tables": {
+    "<table_name>": {
+      "columns": {
+        "<column_name>": "<column_rule>"
+      },
+      "pk": "<primary_key_column>",
+      "unique": [
+        "<column_name>"
+      ],
+      "softDelete": "<column_name>",
+      "timestamps": {
+        "created_at": "<column_name>",
+        "modified_at": "<column_name>"
+      }
+    }
+  },
+  "relationships": [
+    {
+      "parent": "<table>",
+      "child": "<table>",
+      "foreignKey": "<column>"
+    }
+  ],
+  "options": {}
+}
+```
+
+### Adapters
+
+| Adapter | Description |
+|---------|-------------|
+| mysql | mysql database adapter |
+| postgres | postgres database adapter |
+| sqlite3 | sqlite3 database adapter |
+| mongodb | mongodb database adapter |
+| mssql | mssql database adapter |
+| cockroachdb | cockroachdb database adapter |
+| oracle | oracle database adapter |
+| redis | redis database adapter |
+| dynamodb | dynamodb database adapter |
+
+### Frameworks
+
+| Framework | Description |
+|-----------|-------------|
+| express | express HTTP framework |
+| ultimate-express | ultimate-express HTTP framework |
+
+### Column Rules
+
+Column rules use pipe-delimited tokens: `(required|)?(string|integer|numeric|boolean|object)`
+
+Examples: `"required|string"`, `"integer"`, `"required|boolean"`, `"object"`
+
+## CLI Commands
+
+All commands support universal flags: `--yes`, `--json`, `--dry-run`, `--no-install`, `--help`
+
+### init
+
+Scaffold a new project from a schema file or interactively.
+
+```bash
+# From schema file, non-interactive
+db-model-router init --from dbmr.schema.json --yes --no-install
+
+# Interactive with defaults
+db-model-router init --framework express --database sqlite3 --yes
+
+# Dry run to preview
+db-model-router init --from dbmr.schema.json --dry-run
+```
+
+| Flag | Description |
+|------|-------------|
+| `--from <path>` | Read config from schema file |
+| `--framework <fw>` | Framework: express, ultimate-express |
+| `--database <db>` | Adapter name |
+
+### inspect
+
+Introspect a live database and produce a schema file.
+
+```bash
+db-model-router inspect --type postgres --env .env --out dbmr.schema.json
+db-model-router inspect --type sqlite3 --tables users,posts --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--type <adapter>` | Database adapter to use |
+| `--env <path>` | Path to .env file |
+| `--out <path>` | Output file (default: dbmr.schema.json) |
+| `--tables <list>` | Comma-separated table filter |
+
+### generate
+
+Generate code artifacts from the schema file.
+
+```bash
+# Generate all artifacts
+db-model-router generate --from dbmr.schema.json
+
+# Generate only models
+db-model-router generate --models
+
+# Generate only routes
+db-model-router generate --routes
+
+# Preview with dry-run
+db-model-router generate --dry-run --json
+
+# Generate LLM docs only
+db-model-router generate --llm-docs
+```
+
+| Flag | Description |
+|------|-------------|
+| `--from <path>` | Schema file (default: dbmr.schema.json) |
+| `--models` | Generate model files only |
+| `--routes` | Generate route files only |
+| `--openapi` | Generate OpenAPI spec only |
+| `--tests` | Generate test files only |
+| `--llm-docs` | Generate LLM documentation only |
+
+### doctor
+
+Validate schema, check dependencies, and verify generated files are in sync.
+
+```bash
+db-model-router doctor --from dbmr.schema.json
+db-model-router doctor --json
+```
+
+### diff
+
+Preview changes between the schema and currently generated files.
+
+```bash
+db-model-router diff --from dbmr.schema.json
+db-model-router diff --json
+```
+
+## Route Contract
+
+Each table generates 9 endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/<table>/` | List with pagination (page, size, sort, select_columns) |
+| POST | `/api/<table>/` | Bulk insert |
+| PUT | `/api/<table>/` | Bulk update |
+| DELETE | `/api/<table>/` | Bulk delete |
+| GET | `/api/<table>/:id` | Get single record by primary key |
+| POST | `/api/<table>/:id` | Insert single record |
+| PUT | `/api/<table>/:id` | Update single record |
+| PATCH | `/api/<table>/:id` | Partial update single record |
+| DELETE | `/api/<table>/:id` | Delete single record |
+
+## Adapter Capability Matrix
+
+| Adapter | SQL | Transactions | Migrations | Streaming |
+|---------|-----|--------------|------------|-----------|
+| mysql | Yes | Yes | Yes | No |
+| postgres | Yes | Yes | Yes | No |
+| sqlite3 | Yes | Yes | Yes | No |
+| mongodb | No | No | No | No |
+| mssql | Yes | Yes | Yes | No |
+| cockroachdb | Yes | Yes | Yes | No |
+| oracle | Yes | Yes | Yes | No |
+| redis | No | No | No | No |
+| dynamodb | No | No | No | No |
+

package/demo/llms.txt

@@ -0,0 +1,70 @@
+# db-model-router — LLM Quick Reference
+
+## Schema File: dbmr.schema.json
+{ "adapter": "<adapter>", "framework": "<framework>", "tables": { "<name>": { "columns": { "<col>": "<rule>" }, "pk": "<col>", "unique": ["<col>"], "softDelete": "<col>" } }, "relationships": [{ "parent": "<t>", "child": "<t>", "foreignKey": "<col>" }], "options": {} }
+
+Adapters: mysql, postgres, sqlite3, mongodb, mssql, cockroachdb, oracle, redis, dynamodb
+Frameworks: express, ultimate-express
+Column rules: (required|)?(string|integer|numeric|boolean|object) e.g. "required|string"
+
+## Universal Flags
+--yes  --json  --dry-run  --no-install  --help
+
+## Commands
+
+### init
+Scaffold a new project.
+  --from <schema>   Read config from schema file
+  --framework <fw>  Framework (express|ultimate-express)
+  --database <db>   Adapter name
+Example: db-model-router init --from dbmr.schema.json --yes --no-install
+
+### inspect
+Introspect a live database and produce a schema file.
+  --type <adapter>  Database adapter
+  --env <path>      Path to .env file
+  --out <path>      Output path (default: dbmr.schema.json)
+  --tables <list>   Comma-separated table filter
+Example: db-model-router inspect --type sqlite3 --env .env --out schema.json
+
+### generate
+Generate code artifacts from schema.
+  --from <schema>   Schema file (default: dbmr.schema.json)
+  --models          Generate model files only
+  --routes          Generate route files only
+  --openapi         Generate OpenAPI spec only
+  --tests           Generate test files only
+  --llm-docs        Generate LLM documentation only
+Example: db-model-router generate --from dbmr.schema.json
+Example: db-model-router generate --models --dry-run
+
+### doctor
+Validate schema, check dependencies, verify file sync.
+  --from <schema>   Schema file (default: dbmr.schema.json)
+Example: db-model-router doctor --from dbmr.schema.json --json
+
+### diff
+Preview changes between schema and generated files.
+  --from <schema>   Schema file (default: dbmr.schema.json)
+Example: db-model-router diff --from dbmr.schema.json
+
+## Route Contract (per table)
+GET    /api/<table>/        List (page, size, sort, select_columns)
+POST   /api/<table>/        Bulk insert
+PUT    /api/<table>/        Bulk update
+DELETE /api/<table>/        Bulk delete
+GET    /api/<table>/:id     Get by ID
+POST   /api/<table>/:id     Insert one
+PUT    /api/<table>/:id     Update one
+PATCH  /api/<table>/:id     Partial update one
+DELETE /api/<table>/:id     Delete one
+
+## Generated Files
+models/<table>.js           Model with CRUD operations
+routes/<table>.js           Express route handlers
+routes/<child>_child_of_<parent>.js  Child route
+routes/index.js             Route mounting index
+test/<table>.test.js        CRUD endpoint tests
+openapi.json                OpenAPI 3.0 spec
+llms.txt                    This file
+docs/llm.md                 Full LLM reference

package/demo/middleware/logger.js

@@ -0,0 +1,67 @@
+import winston from "winston";
+
+/**
+ * Winston logger with Console transport.
+ * If LOKI_HOST is set in .env, adds a Loki transport for Grafana visualization.
+ */
+const transports = [
+  new winston.transports.Console({
+    format: winston.format.combine(
+      winston.format.colorize(),
+      winston.format.printf(({ timestamp, level, message, ...meta }) => {
+        const metaStr = Object.keys(meta).length > 1
+          ? " " + JSON.stringify(meta)
+          : "";
+        return `[${timestamp}] [${level}] ${message}${metaStr}`;
+      }),
+    ),
+  }),
+];
+
+// Add Loki transport only when LOKI_HOST is configured
+if (process.env.LOKI_HOST) {
+  const { default: LokiTransport } = await import("winston-loki");
+  transports.push(
+    new LokiTransport({
+      host: process.env.LOKI_HOST,
+      labels: { app: process.env.APP_NAME || "app" },
+      json: true,
+      onConnectionError: (err) => console.error("Loki connection error:", err),
+    }),
+  );
+}
+
+const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || "info",
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.json(),
+  ),
+  defaultMeta: { service: process.env.APP_NAME || "app" },
+  transports,
+});
+
+/**
+ * Express middleware that logs every request/response.
+ */
+function requestLogger(req, res, next) {
+  const start = Date.now();
+
+  res.on("finish", () => {
+    const duration = Date.now() - start;
+    const level = res.statusCode >= 400 ? "warn" : "info";
+    logger.log({
+      level,
+      message: `${req.method} ${req.originalUrl} ${res.statusCode} ${duration}ms`,
+      method: req.method,
+      url: req.originalUrl,
+      status: res.statusCode,
+      duration,
+    });
+  });
+
+  next();
+}
+
+requestLogger.logger = logger;
+export default requestLogger;

package/demo/migrations/20260430155808_create_migrations_table.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS _migrations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  filename VARCHAR(255) NOT NULL UNIQUE,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  checksum VARCHAR(64) NOT NULL
+);