db-model-router 1.0.4 → 1.0.5

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
+);

package/demo/migrations/20260430155809_create_tables.sql

@@ -0,0 +1,207 @@
+CREATE TABLE IF NOT EXISTS addresses (
+  address_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  label VARCHAR(255),
+  line1 VARCHAR(255) NOT NULL,
+  line2 VARCHAR(255),
+  city VARCHAR(255) NOT NULL,
+  state VARCHAR(255) NOT NULL,
+  postal_code VARCHAR(255) NOT NULL,
+  country VARCHAR(255) NOT NULL,
+  is_default BOOLEAN,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS cart_items (
+  cart_item_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  cart_id INTEGER NOT NULL,
+  product_id INTEGER NOT NULL,
+  variant_id INTEGER,
+  quantity INTEGER NOT NULL,
+  unit_price DECIMAL(12,2) NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS carts (
+  cart_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER,
+  session_id VARCHAR(255),
+  currency VARCHAR(255) NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS categories (
+  category_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name VARCHAR(255) NOT NULL,
+  slug VARCHAR(255) NOT NULL,
+  description VARCHAR(255),
+  parent_category_id INTEGER,
+  image_url VARCHAR(255),
+  sort_order INTEGER,
+  is_active BOOLEAN,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (slug)
+);
+
+CREATE TABLE IF NOT EXISTS coupons (
+  coupon_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  code VARCHAR(255) NOT NULL,
+  description VARCHAR(255),
+  discount_type VARCHAR(255) NOT NULL,
+  discount_value DECIMAL(12,2) NOT NULL,
+  min_order_amount DECIMAL(12,2),
+  max_uses INTEGER,
+  used_count INTEGER,
+  starts_at TIMESTAMP,
+  expires_at TIMESTAMP,
+  is_active BOOLEAN,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (code)
+);
+
+CREATE TABLE IF NOT EXISTS order_items (
+  order_item_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  order_id INTEGER NOT NULL,
+  product_id INTEGER NOT NULL,
+  variant_id INTEGER,
+  product_name VARCHAR(255) NOT NULL,
+  sku VARCHAR(255) NOT NULL,
+  quantity INTEGER NOT NULL,
+  unit_price DECIMAL(12,2) NOT NULL,
+  total_price DECIMAL(12,2) NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS orders (
+  order_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  order_number VARCHAR(255) NOT NULL,
+  status VARCHAR(255) NOT NULL,
+  subtotal DECIMAL(12,2) NOT NULL,
+  tax_amount DECIMAL(12,2) NOT NULL,
+  shipping_amount DECIMAL(12,2) NOT NULL,
+  discount_amount DECIMAL(12,2),
+  total DECIMAL(12,2) NOT NULL,
+  currency VARCHAR(255) NOT NULL,
+  shipping_address_id INTEGER,
+  billing_address_id INTEGER,
+  notes VARCHAR(255),
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (order_number)
+);
+
+CREATE TABLE IF NOT EXISTS payments (
+  payment_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  order_id INTEGER NOT NULL,
+  method VARCHAR(255) NOT NULL,
+  provider VARCHAR(255),
+  provider_transaction_id VARCHAR(255),
+  amount DECIMAL(12,2) NOT NULL,
+  currency VARCHAR(255) NOT NULL,
+  status VARCHAR(255) NOT NULL,
+  paid_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS product_images (
+  product_image_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  product_id INTEGER NOT NULL,
+  url VARCHAR(255) NOT NULL,
+  alt_text VARCHAR(255),
+  sort_order INTEGER,
+  is_primary BOOLEAN,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS product_reviews (
+  review_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  product_id INTEGER NOT NULL,
+  user_id INTEGER NOT NULL,
+  rating INTEGER NOT NULL,
+  title VARCHAR(255),
+  body VARCHAR(255),
+  is_verified BOOLEAN,
+  is_approved BOOLEAN,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS product_variants (
+  variant_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  product_id INTEGER NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  sku VARCHAR(255) NOT NULL,
+  price DECIMAL(12,2) NOT NULL,
+  stock_quantity INTEGER NOT NULL,
+  attributes TEXT,
+  is_active BOOLEAN,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (sku)
+);
+
+CREATE TABLE IF NOT EXISTS products (
+  product_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  category_id INTEGER NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  slug VARCHAR(255) NOT NULL,
+  description VARCHAR(255),
+  short_description VARCHAR(255),
+  sku VARCHAR(255) NOT NULL,
+  price DECIMAL(12,2) NOT NULL,
+  compare_at_price DECIMAL(12,2),
+  cost_price DECIMAL(12,2),
+  currency VARCHAR(255) NOT NULL,
+  stock_quantity INTEGER NOT NULL,
+  low_stock_threshold INTEGER,
+  weight DECIMAL(12,2),
+  weight_unit VARCHAR(255),
+  is_active BOOLEAN,
+  is_featured BOOLEAN,
+  is_deleted BOOLEAN DEFAULT FALSE,
+  meta TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (sku),
+  UNIQUE (slug)
+);
+
+CREATE TABLE IF NOT EXISTS shipments (
+  shipment_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  order_id INTEGER NOT NULL,
+  carrier VARCHAR(255) NOT NULL,
+  tracking_number VARCHAR(255),
+  status VARCHAR(255) NOT NULL,
+  shipped_at TIMESTAMP,
+  delivered_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS users (
+  user_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name VARCHAR(255) NOT NULL,
+  email VARCHAR(255) NOT NULL,
+  password_hash VARCHAR(255) NOT NULL,
+  phone VARCHAR(255),
+  avatar_url VARCHAR(255),
+  role VARCHAR(255) NOT NULL,
+  is_deleted BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (email)
+);
+
+CREATE TABLE IF NOT EXISTS wishlists (
+  wishlist_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  product_id INTEGER NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);

package/demo/models/addresses.js

@@ -0,0 +1,22 @@
+const { db, model } = require("db-model-router");
+
+const addresses = model(
+  db,
+  "addresses",
+  {
+    "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"
+},
+  "address_id",
+  ["address_id"],
+  { created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = addresses;

package/demo/models/cart_items.js

@@ -0,0 +1,18 @@
+const { db, model } = require("db-model-router");
+
+const cart_items = model(
+  db,
+  "cart_items",
+  {
+    "cart_id": "required|integer",
+    "product_id": "required|integer",
+    "variant_id": "integer",
+    "quantity": "required|integer",
+    "unit_price": "required|numeric"
+},
+  "cart_item_id",
+  ["cart_item_id"],
+  { created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = cart_items;

package/demo/models/carts.js

@@ -0,0 +1,16 @@
+const { db, model } = require("db-model-router");
+
+const carts = model(
+  db,
+  "carts",
+  {
+    "user_id": "integer",
+    "session_id": "string",
+    "currency": "required|string"
+},
+  "cart_id",
+  ["cart_id"],
+  { created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = carts;

package/demo/models/categories.js

@@ -0,0 +1,20 @@
+const { db, model } = require("db-model-router");
+
+const categories = model(
+  db,
+  "categories",
+  {
+    "name": "required|string",
+    "slug": "required|string",
+    "description": "string",
+    "parent_category_id": "integer",
+    "image_url": "string",
+    "sort_order": "integer",
+    "is_active": "boolean"
+},
+  "category_id",
+  ["slug"],
+  { created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = categories;

package/demo/models/coupons.js

@@ -0,0 +1,23 @@
+const { db, model } = require("db-model-router");
+
+const coupons = model(
+  db,
+  "coupons",
+  {
+    "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"
+},
+  "coupon_id",
+  ["code"],
+  { created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = coupons;

package/demo/models/order_items.js

@@ -0,0 +1,21 @@
+const { db, model } = require("db-model-router");
+
+const order_items = model(
+  db,
+  "order_items",
+  {
+    "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"
+},
+  "order_item_id",
+  ["order_item_id"],
+  { created_at: "created_at" },
+);
+
+module.exports = order_items;

package/demo/models/orders.js

@@ -0,0 +1,25 @@
+const { db, model } = require("db-model-router");
+
+const orders = model(
+  db,
+  "orders",
+  {
+    "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"
+},
+  "order_id",
+  ["order_number"],
+  { created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = orders;

package/demo/models/payments.js

@@ -0,0 +1,21 @@
+const { db, model } = require("db-model-router");
+
+const payments = model(
+  db,
+  "payments",
+  {
+    "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"
+},
+  "payment_id",
+  ["payment_id"],
+  { created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = payments;

package/demo/models/product_images.js

@@ -0,0 +1,18 @@
+const { db, model } = require("db-model-router");
+
+const product_images = model(
+  db,
+  "product_images",
+  {
+    "product_id": "required|integer",
+    "url": "required|string",
+    "alt_text": "string",
+    "sort_order": "integer",
+    "is_primary": "boolean"
+},
+  "product_image_id",
+  ["product_image_id"],
+  { created_at: "created_at" },
+);
+
+module.exports = product_images;

package/demo/models/product_reviews.js

@@ -0,0 +1,20 @@
+const { db, model } = require("db-model-router");
+
+const product_reviews = model(
+  db,
+  "product_reviews",
+  {
+    "product_id": "required|integer",
+    "user_id": "required|integer",
+    "rating": "required|integer",
+    "title": "string",
+    "body": "string",
+    "is_verified": "boolean",
+    "is_approved": "boolean"
+},
+  "review_id",
+  ["review_id"],
+  { created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = product_reviews;

package/demo/models/product_variants.js

@@ -0,0 +1,20 @@
+const { db, model } = require("db-model-router");
+
+const product_variants = model(
+  db,
+  "product_variants",
+  {
+    "product_id": "required|integer",
+    "name": "required|string",
+    "sku": "required|string",
+    "price": "required|numeric",
+    "stock_quantity": "required|integer",
+    "attributes": "object",
+    "is_active": "boolean"
+},
+  "variant_id",
+  ["sku"],
+  { created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = product_variants;

package/demo/models/products.js

@@ -0,0 +1,30 @@
+const { db, model } = require("db-model-router");
+
+const products = model(
+  db,
+  "products",
+  {
+    "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",
+    "meta": "object"
+},
+  "product_id",
+  ["sku","slug"],
+  { safeDelete: "is_deleted", created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = products;

package/demo/models/shipments.js

@@ -0,0 +1,19 @@
+const { db, model } = require("db-model-router");
+
+const shipments = model(
+  db,
+  "shipments",
+  {
+    "order_id": "required|integer",
+    "carrier": "required|string",
+    "tracking_number": "string",
+    "status": "required|string",
+    "shipped_at": "datetime",
+    "delivered_at": "datetime"
+},
+  "shipment_id",
+  ["shipment_id"],
+  { created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = shipments;

package/demo/models/users.js

@@ -0,0 +1,19 @@
+const { db, model } = require("db-model-router");
+
+const users = model(
+  db,
+  "users",
+  {
+    "name": "required|string",
+    "email": "required|string",
+    "password_hash": "required|string",
+    "phone": "string",
+    "avatar_url": "string",
+    "role": "required|string"
+},
+  "user_id",
+  ["email"],
+  { safeDelete: "is_deleted", created_at: "created_at", modified_at: "updated_at" },
+);
+
+module.exports = users;

package/demo/models/wishlists.js

@@ -0,0 +1,15 @@
+const { db, model } = require("db-model-router");
+
+const wishlists = model(
+  db,
+  "wishlists",
+  {
+    "user_id": "required|integer",
+    "product_id": "required|integer"
+},
+  "wishlist_id",
+  ["wishlist_id"],
+  { created_at: "created_at" },
+);
+
+module.exports = wishlists;