crudora 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -165,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;
@@ -241,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;
@@ -266,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;
     /**
@@ -319,6 +424,19 @@ interface CrudoraServerConfig {
      * - `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;
@@ -435,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

@@ -165,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;
@@ -241,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;
@@ -266,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;
     /**
@@ -319,6 +424,19 @@ interface CrudoraServerConfig {
      * - `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;
@@ -435,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 };