crudora 0.2.1 → 0.4.0

package/README.md

@@ -22,6 +22,10 @@ Automatic CRUD API generator for TypeScript with Drizzle ORM — build REST APIs
 - **Lifecycle Hooks** — `beforeCreate`, `afterCreate`, `afterCreateMany`, `beforeUpdate`, `afterUpdate`, `beforeDelete`, `afterDelete`, `beforeFind`, `afterFind`
 - **Structured Logging** — pluggable `CrudoraLogger` with correlation IDs per request; compatible with pino, winston
 - **Field Security** — `hidden` fields stripped at query time via `getTableColumns()`
+- **Request Timeout** — built-in socket-level timeout middleware; returns `503` when a handler exceeds the configured limit
+- **Health Check** — built-in `GET /health` endpoint; configurable path or disable entirely
+- **Graceful Shutdown** — `listen()` returns the underlying `http.Server` for clean SIGTERM handling
+- **Built-in API Docs** — Scalar interactive UI at `/docs`; fully configurable (theme, layout, info); enable with `docs: true` after installing `@scalar/express-api-reference`
 - **Standardized Responses** — all endpoints return `{ success, data, meta?, error? }` OpenAPI-style envelope
 - **Schema Generator** — auto-generate Drizzle TypeScript schema files from models
 - **TypeScript First** — full type safety, ESM and CJS dual build
@@ -92,12 +96,22 @@ class User extends Model {
   }
 }
 
-const server = new CrudoraServer({ db, dialect: 'postgresql', port: 3000 });
+const server = new CrudoraServer({
+  db,
+  dialect:     'postgresql',
+  port:        3000,
+  timeout:     30_000,   // 503 after 30 s with no response
+  healthCheck: true,     // GET /health → { status: 'ok' }
+  // docs: true,         // GET /docs → Scalar UI (requires @scalar/express-api-reference)
+});
 
-server
+const httpServer = server
   .registerModel(User)
   .generateRoutes()
   .listen();
+
+// Graceful shutdown
+process.on('SIGTERM', () => httpServer.close(() => process.exit(0)));
 ```
 
 ## Generated API Endpoints
@@ -473,9 +487,6 @@ npx crudora generate-schema --entry src/server.ts --output src/db/schema.ts
 
 ```typescript
 server
-  .get('/health', (_req, res) => {
-    res.json({ success: true, data: { status: 'ok', timestamp: new Date() } });
-  })
   .post('/auth/login', async (req, res) => {
     const { email, password } = req.body;
     const userRepo = server.getCrudora().getRepository(User);
@@ -521,6 +532,46 @@ server.post('/auth/login', async (req, res) => {
 
 See the [Authentication Guide](./docs/authentication.md) for register, per-route middleware, role guards, and a full JWT example.
 
+## API Documentation (Scalar)
+
+Crudora can serve an interactive API reference powered by [Scalar](https://scalar.com) — auto-generated from your registered models.
+
+**1. Install the peer dependency:**
+
+```bash
+npm install @scalar/express-api-reference
+```
+
+**2. Enable `docs` in your server config:**
+
+```typescript
+const server = new CrudoraServer({
+  db,
+  dialect: 'postgresql',
+  docs: true, // → GET /docs (UI) + GET /docs/openapi.json (spec)
+});
+```
+
+**3. Customize as needed:**
+
+```typescript
+docs: {
+  path: '/docs',           // custom mount path, e.g. '/api-docs'
+  title: 'My API',         // shown in Scalar UI header
+  version: '1.0.0',
+  description: 'Full description of what this API does.',
+  scalar: {                // any @scalar/express-api-reference option
+    theme: 'purple',       // 'default' | 'alternate' | 'moon' | 'purple' | ...
+    darkMode: true,
+    layout: 'classic',     // 'modern' (default) | 'classic'
+  },
+},
+```
+
+The raw OpenAPI 3.0 spec is always available at `{path}/openapi.json` — useful for importing into Postman, Insomnia, or other tooling even without the UI package installed.
+
+> If `@scalar/express-api-reference` is not installed and `docs` is enabled, Crudora logs a warning and serves a plain install-prompt page. The spec endpoint is unaffected.
+
 ## Project Setup
 
 ```bash
@@ -544,6 +595,7 @@ npx ts-node src/server.ts
 - [Custom Routes](./docs/custom-routes.md)
 - [Authentication Guide](./docs/authentication.md)
 - [Deployment Guide](./docs/deployment.md)
+- [API Documentation (Scalar)](#api-documentation-scalar)
 
 ## Contributing
 

package/dist/index.cjs

@@ -40,6 +40,7 @@ __export(src_exports, {
   HasOne: () => HasOne,
   Model: () => Model,
   NotFoundError: () => NotFoundError,
+  OpenApiGenerator: () => OpenApiGenerator,
   Repository: () => Repository,
   SchemaGenerator: () => SchemaGenerator,
   ValidationGenerator: () => ValidationGenerator,
@@ -864,6 +865,299 @@ function getColumnImport(type, dialect) {
   }
 }
 
+// src/core/openApiGenerator.ts
+var SYSTEM_FIELDS2 = /* @__PURE__ */ new Set(["createdAt", "updatedAt", "deletedAt"]);
+function fieldToSchema(opts) {
+  switch (opts.type) {
+    case "uuid":
+      return { type: "string", format: "uuid" };
+    case "text":
+      return { type: "string" };
+    case "integer":
+      return { type: "integer" };
+    case "number":
+      return { type: "number", format: "double" };
+    case "boolean":
+      return { type: "boolean" };
+    case "date":
+      return { type: "string", format: "date-time" };
+    case "decimal":
+      return { type: "number", format: "decimal" };
+    case "json":
+      return { type: "object" };
+    case "enum":
+      return { type: "string", enum: opts.enumValues ?? [] };
+    case "bigint":
+      return { type: "integer", format: "int64" };
+    case "serial":
+      return { type: "integer" };
+    case "array":
+      return { type: "array", items: { type: "string" } };
+    default: {
+      const s = { type: "string" };
+      if (opts.length) s.maxLength = opts.length;
+      return s;
+    }
+  }
+}
+function buildOutputSchema(modelClass) {
+  const fields = getFieldMetadata(modelClass);
+  const hidden = new Set(modelClass.hidden ?? []);
+  const properties = {};
+  for (const [name, opts] of Object.entries(fields)) {
+    if (hidden.has(name)) continue;
+    const schema = fieldToSchema(opts);
+    if (opts.nullable) schema.nullable = true;
+    properties[name] = schema;
+  }
+  if (modelClass.timestamps !== false) {
+    properties.createdAt = { type: "string", format: "date-time" };
+    properties.updatedAt = { type: "string", format: "date-time" };
+  }
+  if (modelClass.softDelete) {
+    properties.deletedAt = { type: "string", format: "date-time", nullable: true };
+  }
+  return { type: "object", properties };
+}
+function buildInputSchema(modelClass) {
+  const fields = getFieldMetadata(modelClass);
+  const fillable = modelClass.fillable;
+  const properties = {};
+  const required = [];
+  let entries = Object.entries(fields).filter(
+    ([name, opts]) => !opts.primary && !SYSTEM_FIELDS2.has(name)
+  );
+  if (fillable?.length) {
+    entries = entries.filter(([name]) => fillable.includes(name));
+  }
+  for (const [name, opts] of entries) {
+    const schema2 = fieldToSchema(opts);
+    if (opts.nullable) schema2.nullable = true;
+    properties[name] = schema2;
+    if (opts.required && !opts.nullable) required.push(name);
+  }
+  const schema = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+function capital(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function itemLabel(tableName) {
+  return tableName.endsWith("s") ? tableName.slice(0, -1) : tableName;
+}
+var listResponse = (ref) => ({
+  description: "OK",
+  content: {
+    "application/json": {
+      schema: {
+        type: "object",
+        properties: {
+          success: { type: "boolean", example: true },
+          data: { type: "array", items: { $ref: ref } },
+          meta: {
+            type: "object",
+            properties: {
+              pagination: {
+                type: "object",
+                properties: {
+                  page: { type: "integer" },
+                  limit: { type: "integer" },
+                  total: { type: "integer" },
+                  pages: { type: "integer" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+});
+var itemResponse = (ref, status = "OK") => ({
+  description: status,
+  content: {
+    "application/json": {
+      schema: {
+        type: "object",
+        properties: {
+          success: { type: "boolean", example: true },
+          data: { $ref: ref }
+        }
+      }
+    }
+  }
+});
+var errorResponse = (description, code) => ({
+  description,
+  content: {
+    "application/json": {
+      schema: {
+        type: "object",
+        properties: {
+          success: { type: "boolean", example: false },
+          error: {
+            type: "object",
+            properties: {
+              code: { type: "string", example: code },
+              message: { type: "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+});
+var validationError = {
+  description: "Validation Error",
+  content: {
+    "application/json": {
+      schema: {
+        type: "object",
+        properties: {
+          success: { type: "boolean", example: false },
+          error: {
+            type: "object",
+            properties: {
+              code: { type: "string", example: "VALIDATION_ERROR" },
+              message: { type: "string" },
+              details: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    field: { type: "string" },
+                    message: { type: "string" }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};
+var idParam = { in: "path", name: "id", required: true, schema: { type: "string" } };
+var OpenApiGenerator = class {
+  static generate(models, customRoutes, basePath, info) {
+    const schemas = {};
+    const paths = {};
+    for (const [, modelClass] of models) {
+      const tableName = modelClass.getTableName();
+      const tag = capital(tableName);
+      const item = itemLabel(tableName);
+      const ref = `#/components/schemas/${tag}`;
+      const inputRef = `#/components/schemas/${tag}Input`;
+      const col = `${basePath}/${tableName}`;
+      const byId = `${basePath}/${tableName}/{id}`;
+      schemas[tag] = buildOutputSchema(modelClass);
+      schemas[`${tag}Input`] = buildInputSchema(modelClass);
+      paths[col] = {
+        get: {
+          summary: `List ${tableName}`,
+          operationId: `list${tag}`,
+          tags: [tag],
+          parameters: [
+            { in: "query", name: "page", schema: { type: "integer", default: 1 } },
+            { in: "query", name: "limit", schema: { type: "integer", default: 10 } },
+            { in: "query", name: "cursor", schema: { type: "string" } },
+            { in: "query", name: "sortBy", schema: { type: "string" } },
+            { in: "query", name: "sortOrder", schema: { type: "string", enum: ["asc", "desc"] } },
+            { in: "query", name: "withDeleted", schema: { type: "boolean" } }
+          ],
+          responses: { "200": listResponse(ref) }
+        },
+        post: {
+          summary: `Create ${item}`,
+          operationId: `create${tag}`,
+          tags: [tag],
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { $ref: inputRef } } }
+          },
+          responses: {
+            "201": itemResponse(ref, "Created"),
+            "422": validationError
+          }
+        }
+      };
+      paths[byId] = {
+        get: {
+          summary: `Get ${item} by ID`,
+          operationId: `get${tag}ById`,
+          tags: [tag],
+          parameters: [idParam],
+          responses: {
+            "200": itemResponse(ref),
+            "404": errorResponse("Not Found", "NOT_FOUND")
+          }
+        },
+        put: {
+          summary: `Replace ${item}`,
+          operationId: `replace${tag}`,
+          tags: [tag],
+          parameters: [idParam],
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { $ref: inputRef } } }
+          },
+          responses: {
+            "200": itemResponse(ref),
+            "404": errorResponse("Not Found", "NOT_FOUND"),
+            "422": validationError
+          }
+        },
+        patch: {
+          summary: `Update ${item}`,
+          operationId: `update${tag}`,
+          tags: [tag],
+          parameters: [idParam],
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: { $ref: inputRef } } }
+          },
+          responses: {
+            "200": itemResponse(ref),
+            "404": errorResponse("Not Found", "NOT_FOUND"),
+            "422": validationError
+          }
+        },
+        delete: {
+          summary: `Delete ${item}`,
+          operationId: `delete${tag}`,
+          tags: [tag],
+          parameters: [idParam],
+          responses: {
+            "200": itemResponse(ref),
+            "404": errorResponse("Not Found", "NOT_FOUND")
+          }
+        }
+      };
+    }
+    for (const route of customRoutes) {
+      const fullPath = `${basePath}${route.path}`.replace(/:([a-zA-Z_]+)/g, "{$1}");
+      if (!paths[fullPath]) paths[fullPath] = {};
+      paths[fullPath][route.method.toLowerCase()] = {
+        summary: `${route.method} ${route.path}`,
+        tags: ["Custom"],
+        responses: { "200": { description: "OK" } }
+      };
+    }
+    const spec = {
+      openapi: "3.0.0",
+      info: {
+        title: info?.title ?? "Crudora API",
+        version: info?.version ?? "1.0.0"
+      },
+      paths,
+      components: { schemas }
+    };
+    if (info?.description) spec.info.description = info.description;
+    return spec;
+  }
+};
+
 // src/utils/validation.ts
 var import_zod = require("zod");
 function zodTypeFor(opts, forStrict) {
@@ -916,14 +1210,14 @@ function zodTypeFor(opts, forStrict) {
   }
   return base.optional();
 }
-var SYSTEM_FIELDS2 = /* @__PURE__ */ new Set(["createdAt", "updatedAt", "deletedAt"]);
+var SYSTEM_FIELDS3 = /* @__PURE__ */ new Set(["createdAt", "updatedAt", "deletedAt"]);
 function resolveFields(modelClass) {
   const fieldMeta = getFieldMetadata(modelClass);
   const hasMeta = Object.keys(fieldMeta).length > 0;
   const fillable = modelClass.fillable;
   if (hasMeta) {
     let entries = Object.entries(fieldMeta).filter(
-      ([name, opts]) => !opts.primary && !SYSTEM_FIELDS2.has(name)
+      ([name, opts]) => !opts.primary && !SYSTEM_FIELDS3.has(name)
     );
     if (fillable?.length) {
       entries = entries.filter(([name]) => fillable.includes(name));
@@ -1202,6 +1496,14 @@ var Crudora = class {
     const modelClasses = Array.from(this.models.values());
     return SchemaGenerator.generateDrizzleSchema(modelClasses, this.dialect);
   }
+  generateOpenApiSpec(basePath = "/api", info) {
+    return OpenApiGenerator.generate(
+      this.models,
+      this.customRoutes.map(({ method, path }) => ({ method, path })),
+      basePath,
+      info
+    );
+  }
   getValidationSchema(modelClass) {
     return ValidationGenerator.generateZodSchema(modelClass);
   }
@@ -1451,6 +1753,7 @@ var Crudora = class {
 };
 
 // src/core/crudoraServer.ts
+var import_http = __toESM(require("http"), 1);
 var import_express = __toESM(require("express"), 1);
 var import_crypto2 = require("crypto");
 function createRateLimiter(config) {
@@ -1495,8 +1798,43 @@ function createDefaultLogger() {
     debug: (msg, ctx) => console.debug(fmt("debug", msg, ctx))
   };
 }
+function resolveDocs(docs) {
+  if (!docs) return false;
+  if (docs === true) return { path: "/docs" };
+  if (typeof docs === "string") return { path: docs };
+  return { path: docs.path ?? "/docs", ...docs };
+}
+function tryRequireScalar() {
+  try {
+    return require("@scalar/express-api-reference");
+  } catch {
+    return null;
+  }
+}
+function buildInstallPromptHtml(specUrl) {
+  return `<!DOCTYPE html>
+<html>
+  <head>
+    <title>API Docs</title>
+    <meta charset="utf-8" />
+    <style>
+      body { font-family: system-ui, sans-serif; max-width: 600px; margin: 80px auto; padding: 0 24px; color: #333; }
+      code { background: #f4f4f4; padding: 2px 6px; border-radius: 4px; }
+      pre  { background: #f4f4f4; padding: 16px; border-radius: 8px; overflow: auto; }
+      a    { color: #0070f3; }
+    </style>
+  </head>
+  <body>
+    <h2>API Docs</h2>
+    <p>Install <code>@scalar/express-api-reference</code> to enable the interactive UI:</p>
+    <pre>npm install @scalar/express-api-reference</pre>
+    <p>OpenAPI spec: <a href="${specUrl}">${specUrl}</a></p>
+  </body>
+</html>`;
+}
 var CrudoraServer = class {
   constructor(config) {
+    this.httpServer = null;
     const resolvedLogger = config.logger === void 0 ? createDefaultLogger() : config.logger;
     const resolvedRateLimit = config.rateLimit === false ? false : {
       windowMs: config.rateLimit?.windowMs ?? 6e4,
@@ -1510,9 +1848,12 @@ var CrudoraServer = class {
       bodyParser: true,
       bodyParserLimit: "100kb",
       basePath: "/api",
+      timeout: 0,
+      healthCheck: true,
       ...config,
       logger: resolvedLogger,
-      rateLimit: resolvedRateLimit
+      rateLimit: resolvedRateLimit,
+      docs: resolveDocs(config.docs)
     };
     this.app = (0, import_express.default)();
     this.crudora = new Crudora(
@@ -1533,6 +1874,19 @@ var CrudoraServer = class {
       req.correlationId = (0, import_crypto2.randomUUID)();
       next();
     });
+    if (this.config.timeout > 0) {
+      const timeoutMs = this.config.timeout;
+      this.app.use((_req, res, next) => {
+        const timer = setTimeout(() => {
+          if (!res.headersSent) {
+            res.status(503).json({ success: false, error: { code: "TIMEOUT", message: "Request timed out" } });
+          }
+        }, timeoutMs);
+        res.on("finish", () => clearTimeout(timer));
+        res.on("close", () => clearTimeout(timer));
+        next();
+      });
+    }
     if (this.config.rateLimit !== false) {
       this.app.use(createRateLimiter(this.config.rateLimit));
     }
@@ -1574,6 +1928,37 @@ var CrudoraServer = class {
     return this;
   }
   generateRoutes() {
+    if (this.config.healthCheck !== false) {
+      const healthPath = typeof this.config.healthCheck === "string" ? this.config.healthCheck : "/health";
+      this.app.get(healthPath, (_req, res) => {
+        res.json({ success: true, data: { status: "ok", timestamp: (/* @__PURE__ */ new Date()).toISOString() } });
+      });
+    }
+    if (this.config.docs !== false) {
+      const { path: docsPath, title, version, description, scalar: scalarOpts } = this.config.docs;
+      const specPath = `${docsPath}/openapi.json`;
+      const spec = this.crudora.generateOpenApiSpec(this.config.basePath, { title, version, description });
+      this.app.get(specPath, (_req, res) => {
+        res.json(spec);
+      });
+      const scalarPkg = tryRequireScalar();
+      if (scalarPkg) {
+        this.app.use(docsPath, scalarPkg.apiReference({
+          spec: { url: specPath },
+          ...scalarOpts
+        }));
+      } else {
+        if (this.config.logger !== false) {
+          this.config.logger.warn(
+            'docs is enabled but @scalar/express-api-reference is not installed. Run "npm install @scalar/express-api-reference" to enable the interactive UI.'
+          );
+        }
+        this.app.get(docsPath, (_req, res) => {
+          res.setHeader("Content-Type", "text/html; charset=utf-8");
+          res.send(buildInstallPromptHtml(specPath));
+        });
+      }
+    }
     this.crudora.generateRoutes(this.app, this.config.basePath);
     return this;
   }
@@ -1581,12 +1966,32 @@ var CrudoraServer = class {
     this.app.use(middleware);
     return this;
   }
+  /**
+   * Starts the HTTP server and returns the underlying `http.Server` instance.
+   * Use the returned server for graceful shutdown:
+   *
+   * @example
+   * const httpServer = server.listen();
+   * process.on('SIGTERM', () => httpServer.close(() => process.exit(0)));
+   */
   listen(callback) {
-    this.app.listen(this.config.port, () => {
+    this.httpServer = import_http.default.createServer(this.app);
+    this.httpServer.listen(this.config.port, () => {
       console.log(`\u{1F680} Crudora server running on port ${this.config.port}`);
       console.log(`\u{1F4DA} API available at http://localhost:${this.config.port}${this.config.basePath}`);
+      if (this.config.docs !== false) {
+        console.log(`\u{1F4D6} API docs at http://localhost:${this.config.port}${this.config.docs.path}`);
+      }
       if (callback) callback();
     });
+    return this.httpServer;
+  }
+  /**
+   * Returns the `http.Server` instance after `listen()` has been called, or `null` before.
+   * Useful when you need the server reference without calling listen again.
+   */
+  getHttpServer() {
+    return this.httpServer;
   }
   getApp() {
     return this.app;
@@ -1683,6 +2088,7 @@ Model.softDelete = false;
   HasOne,
   Model,
   NotFoundError,
+  OpenApiGenerator,
   Repository,
   SchemaGenerator,
   ValidationGenerator,