crudora 0.2.1 → 0.4.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,
@@ -164,6 +165,18 @@ declare class Repository<T extends Model> {
     transaction<R>(fn: (trx: Repository<T>) => Promise<R>): Promise<R>;
 }
 
+interface OpenApiInfo {
+    title?: string;
+    version?: string;
+    description?: string;
+}
+declare class OpenApiGenerator {
+    static generate(models: Map<string, ModelConstructor>, customRoutes: Array<{
+        method: string;
+        path: string;
+    }>, basePath: string, info?: OpenApiInfo): Record<string, any>;
+}
+
 type FieldType = 'string' | 'text' | 'integer' | 'number' | 'boolean' | 'date' | 'uuid' | 'decimal' | 'json' | 'enum' | 'bigint' | 'serial' | 'array';
 interface FieldOptions {
     type: FieldType;
@@ -240,6 +253,7 @@ declare class Crudora {
      */
     getTable<T extends Model>(modelClass: ModelConstructor<T>): any;
     generateDrizzleSchema(): string;
+    generateOpenApiSpec(basePath?: string, info?: OpenApiInfo): Record<string, any>;
     getValidationSchema<T extends Model>(modelClass: ModelConstructor<T>): z.ZodType<Partial<T>>;
     getStrictValidationSchema<T extends Model>(modelClass: ModelConstructor<T>): z.ZodType<T>;
     get(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
@@ -265,6 +279,98 @@ interface RateLimitConfig {
      */
     keyGenerator?: (req: any) => string;
 }
+/**
+ * Configuration options forwarded to `@scalar/express-api-reference`.
+ * All known options are typed for autocomplete. Any additional option is also
+ * accepted via the index signature.
+ *
+ * Full reference: https://github.com/scalar/scalar/blob/main/documentation/configuration.md
+ */
+interface ScalarConfig {
+    /**
+     * UI color theme.
+     * @default 'default'
+     */
+    theme?: 'default' | 'alternate' | 'moon' | 'purple' | 'solarized' | 'mars' | 'deepSpace' | 'none';
+    /**
+     * Page layout style.
+     * @default 'modern'
+     */
+    layout?: 'modern' | 'classic';
+    /** Enable dark mode by default. */
+    darkMode?: boolean;
+    /** Force light or dark mode, ignoring system preference. */
+    forceDarkModeState?: 'dark' | 'light';
+    /** Hide the dark-mode toggle button. */
+    hideDarkModeToggle?: boolean;
+    /** Hide the model/schema section. */
+    hideModels?: boolean;
+    /** Hide the "Download" button in the spec header. */
+    hideDownloadButton?: boolean;
+    /** Hide the "Test Request" (client) button on each operation. */
+    hideClientButton?: boolean;
+    /** Show or hide the sidebar. @default true */
+    showSidebar?: boolean;
+    /** Expand all operation tags on load. */
+    defaultOpenAllTags?: boolean;
+    /** Inject custom CSS into the Scalar page. */
+    customCss?: string;
+    /** Custom favicon URL or data URI. */
+    favicon?: string;
+    /** Keyboard shortcut that opens the search dialog. @default 'k' */
+    searchHotKey?: string;
+    /**
+     * Override the server list shown in the UI.
+     * Each entry is `{ url: string; description?: string }`.
+     */
+    servers?: Array<{
+        url: string;
+        description?: string;
+        [key: string]: any;
+    }>;
+    /**
+     * Default values pre-filled in the "Try it out" form — useful for dev tokens.
+     * Shape depends on your security scheme; see Scalar docs for details.
+     */
+    authentication?: Record<string, any>;
+    /**
+     * HTML `<meta>` / Open Graph values for the docs page.
+     * Accepts `title`, `description`, `ogDescription`, `ogTitle`, `ogImage`, `twitterTitle`.
+     */
+    metaData?: {
+        title?: string;
+        description?: string;
+        ogDescription?: string;
+        ogTitle?: string;
+        ogImage?: string;
+        twitterTitle?: string;
+        [key: string]: any;
+    };
+    /** Use Scalar's default font stack. @default true */
+    withDefaultFonts?: boolean;
+    /** Allow users to edit the spec inline (read-only by default). */
+    isEditable?: boolean;
+    /** Any other Scalar option not listed above. */
+    [key: string]: any;
+}
+interface DocsConfig {
+    /** Path where the UI and spec are served. Default: `'/docs'`. */
+    path?: string;
+    /** OpenAPI `info.title`. Default: `'Crudora API'`. */
+    title?: string;
+    /** OpenAPI `info.version`. Default: `'1.0.0'`. */
+    version?: string;
+    /** OpenAPI `info.description`. */
+    description?: string;
+    /**
+     * Options forwarded directly to `apiReference()` from `@scalar/express-api-reference`.
+     * Fully typed for autocomplete — see `ScalarConfig` for all available fields.
+     *
+     * @example
+     * scalar: { theme: 'purple', darkMode: true, layout: 'classic' }
+     */
+    scalar?: ScalarConfig;
+}
 interface CrudoraServerConfig {
     port?: number;
     /**
@@ -297,20 +403,66 @@ 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;
+    /**
+     * Built-in API documentation powered by Scalar.
+     * Requires `@scalar/express-api-reference` to be installed separately.
+     *
+     * - `false` (default): disabled.
+     * - `true`: mount UI at `GET /docs` and spec at `GET /docs/openapi.json`.
+     * - `string`: custom base path, e.g. `'/api-docs'`.
+     * - `DocsConfig`: full control — path, OpenAPI info, Scalar theme/layout/etc.
+     *
+     * @example
+     * docs: { path: '/docs', title: 'My API', scalar: { theme: 'purple' } }
+     */
+    docs?: boolean | string | DocsConfig;
 }
 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;
     /**
@@ -401,4 +553,4 @@ declare function BelongsTo(model: () => any, foreignKey: string, ownerKey?: stri
 declare function BelongsToMany(model: () => any, pivotModel: () => any, pivotForeignKey: string, pivotRelatedKey: string, localKey?: string): (target: any, propertyKey: string) => void;
 declare function getRelationMetadata(target: any): Record<string, RelationDefinition>;
 
-export { BelongsTo, BelongsToMany, Crudora, type CrudoraLogger, CrudoraServer, type CrudoraServerConfig, type CursorPaginationOptions, type CursorResult, type Dialect, DrizzleTableBuilder, Field, type FieldOptions, type FieldType, type FindAllOptions, type FindByIdOptions, HasMany, HasOne, Model, type ModelConstructor, type ModelOptions, NotFoundError, type RateLimitConfig, type RelationDefinition, type RelationType, Repository, SchemaGenerator, ValidationGenerator, getFieldMetadata, getRelationMetadata };
+export { BelongsTo, BelongsToMany, Crudora, type CrudoraLogger, CrudoraServer, type CrudoraServerConfig, type CursorPaginationOptions, type CursorResult, type Dialect, type DocsConfig, DrizzleTableBuilder, Field, type FieldOptions, type FieldType, type FindAllOptions, type FindByIdOptions, HasMany, HasOne, Model, type ModelConstructor, type ModelOptions, NotFoundError, OpenApiGenerator, type OpenApiInfo, type RateLimitConfig, type RelationDefinition, type RelationType, Repository, type ScalarConfig, SchemaGenerator, ValidationGenerator, getFieldMetadata, getRelationMetadata };

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,
@@ -164,6 +165,18 @@ declare class Repository<T extends Model> {
     transaction<R>(fn: (trx: Repository<T>) => Promise<R>): Promise<R>;
 }
 
+interface OpenApiInfo {
+    title?: string;
+    version?: string;
+    description?: string;
+}
+declare class OpenApiGenerator {
+    static generate(models: Map<string, ModelConstructor>, customRoutes: Array<{
+        method: string;
+        path: string;
+    }>, basePath: string, info?: OpenApiInfo): Record<string, any>;
+}
+
 type FieldType = 'string' | 'text' | 'integer' | 'number' | 'boolean' | 'date' | 'uuid' | 'decimal' | 'json' | 'enum' | 'bigint' | 'serial' | 'array';
 interface FieldOptions {
     type: FieldType;
@@ -240,6 +253,7 @@ declare class Crudora {
      */
     getTable<T extends Model>(modelClass: ModelConstructor<T>): any;
     generateDrizzleSchema(): string;
+    generateOpenApiSpec(basePath?: string, info?: OpenApiInfo): Record<string, any>;
     getValidationSchema<T extends Model>(modelClass: ModelConstructor<T>): z.ZodType<Partial<T>>;
     getStrictValidationSchema<T extends Model>(modelClass: ModelConstructor<T>): z.ZodType<T>;
     get(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
@@ -265,6 +279,98 @@ interface RateLimitConfig {
      */
     keyGenerator?: (req: any) => string;
 }
+/**
+ * Configuration options forwarded to `@scalar/express-api-reference`.
+ * All known options are typed for autocomplete. Any additional option is also
+ * accepted via the index signature.
+ *
+ * Full reference: https://github.com/scalar/scalar/blob/main/documentation/configuration.md
+ */
+interface ScalarConfig {
+    /**
+     * UI color theme.
+     * @default 'default'
+     */
+    theme?: 'default' | 'alternate' | 'moon' | 'purple' | 'solarized' | 'mars' | 'deepSpace' | 'none';
+    /**
+     * Page layout style.
+     * @default 'modern'
+     */
+    layout?: 'modern' | 'classic';
+    /** Enable dark mode by default. */
+    darkMode?: boolean;
+    /** Force light or dark mode, ignoring system preference. */
+    forceDarkModeState?: 'dark' | 'light';
+    /** Hide the dark-mode toggle button. */
+    hideDarkModeToggle?: boolean;
+    /** Hide the model/schema section. */
+    hideModels?: boolean;
+    /** Hide the "Download" button in the spec header. */
+    hideDownloadButton?: boolean;
+    /** Hide the "Test Request" (client) button on each operation. */
+    hideClientButton?: boolean;
+    /** Show or hide the sidebar. @default true */
+    showSidebar?: boolean;
+    /** Expand all operation tags on load. */
+    defaultOpenAllTags?: boolean;
+    /** Inject custom CSS into the Scalar page. */
+    customCss?: string;
+    /** Custom favicon URL or data URI. */
+    favicon?: string;
+    /** Keyboard shortcut that opens the search dialog. @default 'k' */
+    searchHotKey?: string;
+    /**
+     * Override the server list shown in the UI.
+     * Each entry is `{ url: string; description?: string }`.
+     */
+    servers?: Array<{
+        url: string;
+        description?: string;
+        [key: string]: any;
+    }>;
+    /**
+     * Default values pre-filled in the "Try it out" form — useful for dev tokens.
+     * Shape depends on your security scheme; see Scalar docs for details.
+     */
+    authentication?: Record<string, any>;
+    /**
+     * HTML `<meta>` / Open Graph values for the docs page.
+     * Accepts `title`, `description`, `ogDescription`, `ogTitle`, `ogImage`, `twitterTitle`.
+     */
+    metaData?: {
+        title?: string;
+        description?: string;
+        ogDescription?: string;
+        ogTitle?: string;
+        ogImage?: string;
+        twitterTitle?: string;
+        [key: string]: any;
+    };
+    /** Use Scalar's default font stack. @default true */
+    withDefaultFonts?: boolean;
+    /** Allow users to edit the spec inline (read-only by default). */
+    isEditable?: boolean;
+    /** Any other Scalar option not listed above. */
+    [key: string]: any;
+}
+interface DocsConfig {
+    /** Path where the UI and spec are served. Default: `'/docs'`. */
+    path?: string;
+    /** OpenAPI `info.title`. Default: `'Crudora API'`. */
+    title?: string;
+    /** OpenAPI `info.version`. Default: `'1.0.0'`. */
+    version?: string;
+    /** OpenAPI `info.description`. */
+    description?: string;
+    /**
+     * Options forwarded directly to `apiReference()` from `@scalar/express-api-reference`.
+     * Fully typed for autocomplete — see `ScalarConfig` for all available fields.
+     *
+     * @example
+     * scalar: { theme: 'purple', darkMode: true, layout: 'classic' }
+     */
+    scalar?: ScalarConfig;
+}
 interface CrudoraServerConfig {
     port?: number;
     /**
@@ -297,20 +403,66 @@ 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;
+    /**
+     * Built-in API documentation powered by Scalar.
+     * Requires `@scalar/express-api-reference` to be installed separately.
+     *
+     * - `false` (default): disabled.
+     * - `true`: mount UI at `GET /docs` and spec at `GET /docs/openapi.json`.
+     * - `string`: custom base path, e.g. `'/api-docs'`.
+     * - `DocsConfig`: full control — path, OpenAPI info, Scalar theme/layout/etc.
+     *
+     * @example
+     * docs: { path: '/docs', title: 'My API', scalar: { theme: 'purple' } }
+     */
+    docs?: boolean | string | DocsConfig;
 }
 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;
     /**
@@ -401,4 +553,4 @@ declare function BelongsTo(model: () => any, foreignKey: string, ownerKey?: stri
 declare function BelongsToMany(model: () => any, pivotModel: () => any, pivotForeignKey: string, pivotRelatedKey: string, localKey?: string): (target: any, propertyKey: string) => void;
 declare function getRelationMetadata(target: any): Record<string, RelationDefinition>;
 
-export { BelongsTo, BelongsToMany, Crudora, type CrudoraLogger, CrudoraServer, type CrudoraServerConfig, type CursorPaginationOptions, type CursorResult, type Dialect, DrizzleTableBuilder, Field, type FieldOptions, type FieldType, type FindAllOptions, type FindByIdOptions, HasMany, HasOne, Model, type ModelConstructor, type ModelOptions, NotFoundError, type RateLimitConfig, type RelationDefinition, type RelationType, Repository, SchemaGenerator, ValidationGenerator, getFieldMetadata, getRelationMetadata };
+export { BelongsTo, BelongsToMany, Crudora, type CrudoraLogger, CrudoraServer, type CrudoraServerConfig, type CursorPaginationOptions, type CursorResult, type Dialect, type DocsConfig, DrizzleTableBuilder, Field, type FieldOptions, type FieldType, type FindAllOptions, type FindByIdOptions, HasMany, HasOne, Model, type ModelConstructor, type ModelOptions, NotFoundError, OpenApiGenerator, type OpenApiInfo, type RateLimitConfig, type RelationDefinition, type RelationType, Repository, type ScalarConfig, SchemaGenerator, ValidationGenerator, getFieldMetadata, getRelationMetadata };