crudora 0.2.1 → 0.4.0

package/dist/index.js

@@ -1,3 +1,10 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/index.ts
 import "reflect-metadata";
 
@@ -832,6 +839,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
 import { z } from "zod";
 function zodTypeFor(opts, forStrict) {
@@ -884,14 +1184,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));
@@ -1197,6 +1497,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);
   }
@@ -1446,6 +1754,7 @@ var Crudora = class {
 };
 
 // src/core/crudoraServer.ts
+import http from "http";
 import express from "express";
 import { randomUUID as randomUUID2 } from "crypto";
 function createRateLimiter(config) {
@@ -1490,8 +1799,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,
@@ -1505,9 +1849,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 = express();
     this.crudora = new Crudora(
@@ -1528,6 +1875,19 @@ var CrudoraServer = class {
       req.correlationId = randomUUID2();
       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));
     }
@@ -1569,6 +1929,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;
   }
@@ -1576,12 +1967,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 = http.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;
@@ -1677,6 +2088,7 @@ export {
   HasOne,
   Model,
   NotFoundError,
+  OpenApiGenerator,
   Repository,
   SchemaGenerator,
   ValidationGenerator,