crudora 0.2.1 → 0.3.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { Express } from 'express';
 import { z } from 'zod';
+import http from 'http';
 
 /**
  * Base class for all Crudora models. Extend this to define your table schema,
@@ -297,20 +298,53 @@ interface CrudoraServerConfig {
      * - Omit / `undefined` (default): enabled with 100 requests per minute per IP.
      * - Pass a `RateLimitConfig` object to customise the window, limit, or key function.
      * - Pass `false` to disable rate limiting entirely (e.g. when using an external proxy-level limiter).
+     *
+     * **Important:** This limiter is in-memory and per-process. In multi-instance deployments
+     * (load balancer, Kubernetes replicas), each instance tracks its own counter independently —
+     * the effective limit per client is `max × instanceCount`. Use a Redis-backed limiter
+     * (e.g. `rate-limiter-flexible`) and pass `rateLimit: false` to disable this one.
      */
     rateLimit?: RateLimitConfig | false;
+    /**
+     * Socket-level request timeout in milliseconds.
+     * Requests that exceed this duration are terminated with a `503` response.
+     * - Omit / `0` (default): no timeout.
+     * - Recommended: `30_000` (30 s) for most APIs.
+     */
+    timeout?: number;
+    /**
+     * Built-in health check endpoint.
+     * - `true` (default): mounts `GET /health` returning `{ status: 'ok' }`.
+     * - `string`: custom path, e.g. `'/healthz'`.
+     * - `false`: disable entirely.
+     */
+    healthCheck?: boolean | string;
 }
 declare class CrudoraServer {
     private app;
     private crudora;
     private config;
+    private httpServer;
     constructor(config: CrudoraServerConfig);
     private setupMiddleware;
     registerModel(...modelClasses: ModelConstructor[]): this;
     registerTable<T extends Model>(modelClass: ModelConstructor<T>, table: any): this;
     generateRoutes(): this;
     use(middleware: any): this;
-    listen(callback?: () => void): void;
+    /**
+     * 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?: () => void): http.Server;
+    /**
+     * 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(): http.Server | null;
     getApp(): Express;
     getCrudora(): Crudora;
     /**

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Express } from 'express';
 import { z } from 'zod';
+import http from 'http';
 
 /**
  * Base class for all Crudora models. Extend this to define your table schema,
@@ -297,20 +298,53 @@ interface CrudoraServerConfig {
      * - Omit / `undefined` (default): enabled with 100 requests per minute per IP.
      * - Pass a `RateLimitConfig` object to customise the window, limit, or key function.
      * - Pass `false` to disable rate limiting entirely (e.g. when using an external proxy-level limiter).
+     *
+     * **Important:** This limiter is in-memory and per-process. In multi-instance deployments
+     * (load balancer, Kubernetes replicas), each instance tracks its own counter independently —
+     * the effective limit per client is `max × instanceCount`. Use a Redis-backed limiter
+     * (e.g. `rate-limiter-flexible`) and pass `rateLimit: false` to disable this one.
      */
     rateLimit?: RateLimitConfig | false;
+    /**
+     * Socket-level request timeout in milliseconds.
+     * Requests that exceed this duration are terminated with a `503` response.
+     * - Omit / `0` (default): no timeout.
+     * - Recommended: `30_000` (30 s) for most APIs.
+     */
+    timeout?: number;
+    /**
+     * Built-in health check endpoint.
+     * - `true` (default): mounts `GET /health` returning `{ status: 'ok' }`.
+     * - `string`: custom path, e.g. `'/healthz'`.
+     * - `false`: disable entirely.
+     */
+    healthCheck?: boolean | string;
 }
 declare class CrudoraServer {
     private app;
     private crudora;
     private config;
+    private httpServer;
     constructor(config: CrudoraServerConfig);
     private setupMiddleware;
     registerModel(...modelClasses: ModelConstructor[]): this;
     registerTable<T extends Model>(modelClass: ModelConstructor<T>, table: any): this;
     generateRoutes(): this;
     use(middleware: any): this;
-    listen(callback?: () => void): void;
+    /**
+     * 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?: () => void): http.Server;
+    /**
+     * 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(): http.Server | null;
     getApp(): Express;
     getCrudora(): Crudora;
     /**

package/dist/index.js

@@ -1446,6 +1446,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) {
@@ -1492,6 +1493,7 @@ function createDefaultLogger() {
 }
 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,6 +1507,8 @@ var CrudoraServer = class {
       bodyParser: true,
       bodyParserLimit: "100kb",
       basePath: "/api",
+      timeout: 0,
+      healthCheck: true,
       ...config,
       logger: resolvedLogger,
       rateLimit: resolvedRateLimit
@@ -1528,6 +1532,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 +1586,12 @@ 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() } });
+      });
+    }
     this.crudora.generateRoutes(this.app, this.config.basePath);
     return this;
   }
@@ -1576,12 +1599,29 @@ 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 (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;