db-model-router 1.0.2 → 1.0.4

package/src/schema/schema-validator.js

@@ -0,0 +1,255 @@
+"use strict";
+
+const VALID_ADAPTERS = new Set([
+  "mysql",
+  "mariadb",
+  "postgres",
+  "sqlite3",
+  "mongodb",
+  "mssql",
+  "cockroachdb",
+  "oracle",
+  "redis",
+  "dynamodb",
+]);
+
+const VALID_FRAMEWORKS = new Set(["express", "ultimate-express"]);
+
+const COLUMN_RULE_RE =
+  /^(required\|)?(string|integer|numeric|boolean|object|datetime|auto_increment)$/;
+
+class SchemaValidationError extends Error {
+  constructor(errors) {
+    super(`Schema validation failed: ${errors.length} error(s)`);
+    this.errors = errors;
+  }
+}
+
+/**
+ * Validate a raw schema object and collect all errors.
+ * @param {object} raw — parsed JSON object
+ * @returns {{ valid: boolean, errors: Array<{ path: string, message: string }> }}
+ */
+function validateSchema(raw) {
+  const errors = [];
+
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+    errors.push({ path: "", message: "Schema must be a non-null object" });
+    return { valid: false, errors };
+  }
+
+  // adapter
+  if (!raw.adapter || typeof raw.adapter !== "string") {
+    errors.push({
+      path: "adapter",
+      message: "adapter is required and must be a string",
+    });
+  } else if (!VALID_ADAPTERS.has(raw.adapter)) {
+    errors.push({
+      path: "adapter",
+      message: `Invalid adapter "${raw.adapter}". Must be one of: ${[...VALID_ADAPTERS].join(", ")}`,
+    });
+  }
+
+  // framework
+  if (!raw.framework || typeof raw.framework !== "string") {
+    errors.push({
+      path: "framework",
+      message: "framework is required and must be a string",
+    });
+  } else if (!VALID_FRAMEWORKS.has(raw.framework)) {
+    errors.push({
+      path: "framework",
+      message: `Invalid framework "${raw.framework}". Must be one of: ${[...VALID_FRAMEWORKS].join(", ")}`,
+    });
+  }
+
+  // tables
+  if (
+    raw.tables == null ||
+    typeof raw.tables !== "object" ||
+    Array.isArray(raw.tables)
+  ) {
+    errors.push({
+      path: "tables",
+      message: "tables is required and must be an object",
+    });
+  } else {
+    validateTables(raw.tables, errors);
+  }
+
+  // relationships
+  if (raw.relationships !== undefined) {
+    if (!Array.isArray(raw.relationships)) {
+      errors.push({
+        path: "relationships",
+        message: "relationships must be an array",
+      });
+    } else {
+      const tableNames =
+        raw.tables &&
+        typeof raw.tables === "object" &&
+        !Array.isArray(raw.tables)
+          ? new Set(Object.keys(raw.tables))
+          : new Set();
+      validateRelationships(raw.relationships, tableNames, errors);
+    }
+  }
+
+  // options
+  if (raw.options !== undefined) {
+    if (
+      raw.options == null ||
+      typeof raw.options !== "object" ||
+      Array.isArray(raw.options)
+    ) {
+      errors.push({ path: "options", message: "options must be an object" });
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate all table entries.
+ */
+function validateTables(tables, errors) {
+  for (const [tableName, tableDef] of Object.entries(tables)) {
+    const basePath = `tables.${tableName}`;
+
+    if (
+      tableDef == null ||
+      typeof tableDef !== "object" ||
+      Array.isArray(tableDef)
+    ) {
+      errors.push({
+        path: basePath,
+        message: `Table "${tableName}" must be an object`,
+      });
+      continue;
+    }
+
+    // columns
+    if (
+      tableDef.columns == null ||
+      typeof tableDef.columns !== "object" ||
+      Array.isArray(tableDef.columns)
+    ) {
+      errors.push({
+        path: `${basePath}.columns`,
+        message: `Table "${tableName}" must have a columns object`,
+      });
+      continue;
+    }
+
+    const columnNames = new Set(Object.keys(tableDef.columns));
+    const pk = tableDef.pk || "id";
+
+    // Validate each column rule
+    for (const [colName, rule] of Object.entries(tableDef.columns)) {
+      if (typeof rule !== "string" || !COLUMN_RULE_RE.test(rule)) {
+        errors.push({
+          path: `${basePath}.columns.${colName}`,
+          message: `Invalid column rule "${rule}" for column "${colName}". Must match pattern: (required|)?(string|integer|numeric|boolean|object)`,
+        });
+      }
+    }
+
+    // Validate unique entries
+    if (tableDef.unique !== undefined) {
+      if (!Array.isArray(tableDef.unique)) {
+        errors.push({
+          path: `${basePath}.unique`,
+          message: `unique must be an array in table "${tableName}"`,
+        });
+      } else {
+        for (let i = 0; i < tableDef.unique.length; i++) {
+          const entry = tableDef.unique[i];
+          if (typeof entry !== "string") {
+            errors.push({
+              path: `${basePath}.unique[${i}]`,
+              message: `unique entry must be a string in table "${tableName}"`,
+            });
+          } else if (entry !== pk && !columnNames.has(entry)) {
+            errors.push({
+              path: `${basePath}.unique[${i}]`,
+              message: `unique entry "${entry}" does not match any column or the primary key "${pk}" in table "${tableName}"`,
+            });
+          }
+        }
+      }
+    }
+
+    // Validate softDelete
+    if (tableDef.softDelete !== undefined && tableDef.softDelete !== null) {
+      if (typeof tableDef.softDelete !== "string") {
+        errors.push({
+          path: `${basePath}.softDelete`,
+          message: `softDelete must be a string in table "${tableName}"`,
+        });
+      } else if (!columnNames.has(tableDef.softDelete)) {
+        errors.push({
+          path: `${basePath}.softDelete`,
+          message: `softDelete column "${tableDef.softDelete}" does not exist in table "${tableName}"`,
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Validate all relationship entries.
+ */
+function validateRelationships(relationships, tableNames, errors) {
+  for (let i = 0; i < relationships.length; i++) {
+    const rel = relationships[i];
+    const basePath = `relationships[${i}]`;
+
+    if (rel == null || typeof rel !== "object" || Array.isArray(rel)) {
+      errors.push({
+        path: basePath,
+        message: "Each relationship must be an object",
+      });
+      continue;
+    }
+
+    if (!rel.parent || typeof rel.parent !== "string") {
+      errors.push({
+        path: `${basePath}.parent`,
+        message: "Relationship must have a parent string",
+      });
+    } else if (!tableNames.has(rel.parent)) {
+      errors.push({
+        path: `${basePath}.parent`,
+        message: `Relationship parent "${rel.parent}" does not reference an existing table`,
+      });
+    }
+
+    if (!rel.child || typeof rel.child !== "string") {
+      errors.push({
+        path: `${basePath}.child`,
+        message: "Relationship must have a child string",
+      });
+    } else if (!tableNames.has(rel.child)) {
+      errors.push({
+        path: `${basePath}.child`,
+        message: `Relationship child "${rel.child}" does not reference an existing table`,
+      });
+    }
+
+    if (!rel.foreignKey || typeof rel.foreignKey !== "string") {
+      errors.push({
+        path: `${basePath}.foreignKey`,
+        message: "Relationship must have a foreignKey string",
+      });
+    }
+  }
+}
+
+module.exports = {
+  SchemaValidationError,
+  validateSchema,
+  VALID_ADAPTERS,
+  VALID_FRAMEWORKS,
+  COLUMN_RULE_RE,
+};

package/src/serve.js

@@ -21,8 +21,10 @@ if (process.env.NODE_ENV === "TEST") {
   port = process.env.port;
 }
 
-const { db, model, route } = require("./index");
-db.connect({
+const { init, model, route } = require("./index");
+const dbModule = require("./index");
+init("mysql");
+dbModule.db.connect({
   connectionLimit: 100,
   host: process.env.DB_HOST,
   user: process.env.DB_USER,
@@ -32,7 +34,7 @@ db.connect({
   charset: "utf8mb4",
 });
 const test = model(
-  db,
+  dbModule.db,
   "test",
   {
     test_id: "required|integer",

package/docs/README.md

@@ -1,208 +0,0 @@
-# db-model-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
-db-model-router-generate-app --type mysql --env .env
-db-model-router-generate-app --type sqlite3 --database ./myapp.db --output ./my-api
-db-model-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
-db-model-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
-db-model-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).