crudora 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -0,0 +1,438 @@
+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,
+ * configure lifecycle hooks, and control API behaviour via static properties.
+ *
+ * Use `@Field()` decorators on instance properties to describe columns.
+ * Use `@HasMany()`, `@HasOne()`, `@BelongsTo()`, `@BelongsToMany()` for relations.
+ *
+ * This is a plain class — **not** a decorator. Extend it:
+ * ```ts
+ * class User extends Model {
+ *   static tableName = 'users';
+ * }
+ * ```
+ */
+declare abstract class Model {
+    static tableName?: string;
+    static primaryKey?: string;
+    static timestamps?: boolean;
+    static softDelete?: boolean;
+    static fillable?: string[];
+    static hidden?: string[];
+    static schema?: string;
+    static getTableName(): string;
+    static getPrimaryKey(): string;
+    static beforeCreate?(_data: any): Promise<any>;
+    static afterCreate?(_data: any, result: any): Promise<any>;
+    static afterCreateMany?(_records: any[]): Promise<any[]>;
+    static beforeUpdate?(_id: string, _data: any): Promise<any>;
+    static afterUpdate?(_id: string, _data: any, result: any): Promise<any>;
+    static beforeDelete?(_id: string): Promise<void>;
+    static afterDelete?(_id: string, result: any): Promise<any>;
+    static beforeFind?(options?: any): Promise<any>;
+    static afterFind?(results: any[]): Promise<any[]>;
+    beforeSave?(): Promise<void>;
+    afterSave?(): Promise<void>;
+}
+type ModelConstructor<T extends Model = Model> = {
+    new (): T;
+    tableName?: string;
+    primaryKey?: string;
+    timestamps?: boolean;
+    softDelete?: boolean;
+    fillable?: string[];
+    hidden?: string[];
+    schema?: string;
+    getTableName(): string;
+    getPrimaryKey(): string;
+    beforeCreate?(data: any): Promise<any>;
+    afterCreate?(data: any, result: any): Promise<any>;
+    afterCreateMany?(records: any[]): Promise<any[]>;
+    beforeUpdate?(id: string, data: any): Promise<any>;
+    afterUpdate?(id: string, data: any, result: any): Promise<any>;
+    beforeDelete?(id: string): Promise<void>;
+    afterDelete?(id: string, result: any): Promise<any>;
+    beforeFind?(options?: any): Promise<any>;
+    afterFind?(results: any[]): Promise<any[]>;
+} & typeof Model;
+
+interface FindAllOptions {
+    skip?: number;
+    take?: number;
+    where?: Record<string, any>;
+    orderBy?: string | string[];
+    order?: 'asc' | 'desc' | Array<'asc' | 'desc'>;
+    select?: string[];
+    with?: string[];
+    withDeleted?: boolean;
+    /** When true, fields listed in `static hidden` are included in the result. */
+    includeHidden?: boolean;
+}
+interface FindByIdOptions {
+    select?: string[];
+    with?: string[];
+    withDeleted?: boolean;
+    /** When true, fields listed in `static hidden` are included in the result. */
+    includeHidden?: boolean;
+}
+interface CursorPaginationOptions {
+    take?: number;
+    cursor?: string | null;
+    cursorField?: string;
+    order?: 'asc' | 'desc';
+    where?: Record<string, any>;
+    select?: string[];
+    with?: string[];
+    withDeleted?: boolean;
+    /** When true, fields listed in `static hidden` are included in the result. */
+    includeHidden?: boolean;
+}
+interface CursorResult<T> {
+    data: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+declare class NotFoundError extends Error {
+    readonly code = "NOT_FOUND";
+    constructor(message: string);
+}
+declare class Repository<T extends Model> {
+    private modelClass;
+    private db;
+    private table;
+    /** Shared registry — same Map instance as Crudora holds; populated lazily. */
+    private registry?;
+    constructor(modelClass: ModelConstructor<T>, db: any, table: any, 
+    /** Shared registry — same Map instance as Crudora holds; populated lazily. */
+    registry?: Map<string, Repository<any>> | undefined);
+    /**
+     * Builds the Drizzle select-column object, merging hidden-field exclusion with
+     * an optional explicit field list. Returns `undefined` to select all columns.
+     */
+    private buildSelectCols;
+    private buildWhere;
+    private softDeleteClause;
+    private combineWhere;
+    /**
+     * Batch-loads relations for a list of records. Uses the _in operator so the
+     * total number of DB round-trips equals the number of requested relations.
+     */
+    private loadRelations;
+    create(data: Partial<T>): Promise<T>;
+    findById(id: string, opts?: FindByIdOptions): Promise<T | null>;
+    findAll(options?: FindAllOptions): Promise<T[]>;
+    /**
+     * Cursor-based pagination — more efficient than offset for large datasets.
+     *
+     * @example
+     * const page1 = await userRepo.findWithCursor({ take: 10 });
+     * const page2 = await userRepo.findWithCursor({ take: 10, cursor: page1.nextCursor });
+     */
+    findWithCursor(options: CursorPaginationOptions): Promise<CursorResult<T>>;
+    update(id: string, data: Partial<T>): Promise<T>;
+    delete(id: string): Promise<T>;
+    hardDelete(id: string): Promise<T>;
+    restore(id: string): Promise<T>;
+    count(where?: any, withDeleted?: boolean): Promise<number>;
+    /** Returns the first record matching `where`, or null. Builds a direct LIMIT 1 query — does not delegate to findAll. */
+    findOne(where?: Record<string, any>, opts?: FindByIdOptions): Promise<T | null>;
+    /**
+     * Returns true if at least one record matches `where`.
+     * Uses SELECT pk LIMIT 1 — more efficient than COUNT(*) because the DB stops at the first match.
+     */
+    exists(where?: Record<string, any>, withDeleted?: boolean): Promise<boolean>;
+    /**
+     * Inserts multiple records in a single INSERT statement.
+     * Calls `beforeCreate` for each row. Calls `afterCreateMany` once with all
+     * results — use this hook for batch-aware side effects (e.g. bulk notifications).
+     * Individual `afterCreate` is intentionally NOT called per row for performance.
+     */
+    createMany(data: Partial<T>[]): Promise<T[]>;
+    /**
+     * Runs `fn` inside a database transaction. The callback receives a new
+     * Repository bound to the transaction connection.
+     *
+     * @example
+     * await userRepo.transaction(async (trx) => {
+     *   await trx.create({ name: 'Alice' });
+     *   await trx.update(id, { name: 'Bob' });
+     * });
+     */
+    transaction<R>(fn: (trx: Repository<T>) => Promise<R>): Promise<R>;
+}
+
+type FieldType = 'string' | 'text' | 'integer' | 'number' | 'boolean' | 'date' | 'uuid' | 'decimal' | 'json' | 'enum' | 'bigint' | 'serial' | 'array';
+interface FieldOptions {
+    type: FieldType;
+    required?: boolean;
+    unique?: boolean;
+    default?: any;
+    length?: number;
+    primary?: boolean;
+    nullable?: boolean;
+    precision?: number;
+    scale?: number;
+    /** Required when type is 'enum'. Lists the allowed values. */
+    enumValues?: string[];
+}
+interface ModelOptions {
+    tableName?: string;
+    timestamps?: boolean;
+}
+type Dialect = 'postgresql' | 'mysql';
+type RelationType = 'hasOne' | 'hasMany' | 'belongsTo' | 'belongsToMany';
+interface RelationDefinition {
+    type: RelationType;
+    /** Lazy model getter — avoids circular-import issues */
+    model: () => any;
+    /** The foreign-key column name */
+    foreignKey: string;
+    /**
+     * hasOne / hasMany: column on the owning (local) side. Defaults to the model's primary key.
+     * belongsTo   : column on the related side (the "owner"). Defaults to the related model's primary key.
+     * belongsToMany: override for this model's local key (defaults to primary key).
+     */
+    relatedKey?: string;
+    /** Lazy getter returning the pivot/junction model constructor. */
+    pivotModel?: () => any;
+    /** Column on the pivot table that points to the **related** model. */
+    pivotRelatedKey?: string;
+}
+
+interface CrudoraLogger {
+    error(message: string, context?: Record<string, any>): void;
+    warn(message: string, context?: Record<string, any>): void;
+    info(message: string, context?: Record<string, any>): void;
+    debug(message: string, context?: Record<string, any>): void;
+}
+
+declare class Crudora {
+    private db;
+    private dialect;
+    private logger;
+    private models;
+    private tables;
+    private repositories;
+    private customRoutes;
+    constructor(db: any, dialect: Dialect, logger?: CrudoraLogger);
+    registerModel(...modelClasses: ModelConstructor[]): this;
+    /**
+     * Register a model against a pre-built Drizzle table object (e.g. from `drizzle-kit introspect`).
+     * Skips `DrizzleTableBuilder` — useful when the database already exists and the schema
+     * was generated via introspection rather than Crudora decorators.
+     *
+     * Validation works if the model defines `@Field()` decorators matching the table columns.
+     * Without decorators, POST/PUT bodies pass through without Zod validation.
+     */
+    registerTable<T extends Model>(modelClass: ModelConstructor<T>, table: any): this;
+    getRepository<T extends Model>(modelClass: ModelConstructor<T>): Repository<T>;
+    /**
+     * Returns the Drizzle table object for a registered model.
+     * Useful for raw queries that need access to columns excluded by `hidden`
+     * (e.g. fetching a password hash for authentication).
+     *
+     * @example
+     * const usersTable = crudora.getTable(User);
+     * const [row] = await db.select().from(usersTable).where(eq(usersTable.email, email)).limit(1);
+     */
+    getTable<T extends Model>(modelClass: ModelConstructor<T>): any;
+    generateDrizzleSchema(): string;
+    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;
+    post(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
+    put(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
+    delete(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
+    patch(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
+    /** Runs `fn` inside a database transaction and returns its result. */
+    transaction<R>(fn: (db: any) => Promise<R>): Promise<R>;
+    generateRoutes(app: Express, basePath?: string): void;
+}
+
+interface RateLimitConfig {
+    /** Sliding-window duration in milliseconds. Default: `60_000` (1 minute). */
+    windowMs?: number;
+    /** Maximum number of requests per key per window. Default: `100`. */
+    max?: number;
+    /** Message body returned with 429 responses. Default: `'Too many requests'`. */
+    message?: string;
+    /**
+     * Function that extracts the rate-limit key from a request.
+     * Default: `req.ip` (the direct connection IP, or `X-Forwarded-For` if `trust proxy` is set on Express).
+     */
+    keyGenerator?: (req: any) => string;
+}
+interface CrudoraServerConfig {
+    port?: number;
+    /**
+     * CORS configuration.
+     * - `true` (default): allow all origins (`*`)
+     * - `false`: disable CORS headers entirely
+     * - `string`: allow a single specific origin, e.g. `'https://app.example.com'`
+     * - `string[]`: allow a list of origins; the request's Origin is reflected if it matches
+     */
+    cors?: boolean | string | string[];
+    bodyParser?: boolean;
+    /**
+     * Maximum request body size accepted by the JSON and URL-encoded body parsers.
+     * Accepts a number (bytes) or a string with a unit suffix (`'100kb'`, `'5mb'`).
+     * Default: `'100kb'`.
+     */
+    bodyParserLimit?: string | number;
+    db: any;
+    dialect: Dialect;
+    basePath?: string;
+    /**
+     * Logger for request errors and lifecycle events.
+     * - Omit (default): structured JSON written to console (compatible with log aggregators).
+     * - Pass a pino/winston instance or any object with `error`, `warn`, `info`, `debug` methods.
+     * - Pass `false` to disable all Crudora logging.
+     */
+    logger?: CrudoraLogger | false;
+    /**
+     * Built-in sliding-window rate limiter applied to every route.
+     * - 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;
+    /**
+     * 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;
+    /**
+     * Returns the Drizzle table object for a registered model — delegates to `Crudora.getTable()`.
+     * Use this when you need raw DB access to columns excluded by `static hidden`
+     * (e.g. a login route that must read the password hash).
+     *
+     * @example
+     * const usersTable = server.getTable(User);
+     * const [row] = await db.select().from(usersTable).where(eq(usersTable.email, email)).limit(1);
+     */
+    getTable<T extends Model>(modelClass: ModelConstructor<T>): any;
+    get(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
+    post(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
+    put(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
+    delete(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
+    patch(path: string, ...handlers: Array<(req: any, res: any, next?: any) => void>): this;
+}
+
+declare class SchemaGenerator {
+    static generateDrizzleSchema(models: ModelConstructor[], dialect: Dialect): string;
+}
+
+declare class DrizzleTableBuilder {
+    static build(modelClass: ModelConstructor, dialect: Dialect): any;
+}
+
+declare class ValidationGenerator {
+    static generateZodSchema<T extends Model>(modelClass: ModelConstructor<T>): z.ZodType<Partial<T>>;
+    static generateStrictZodSchema<T extends Model>(modelClass: ModelConstructor<T>): z.ZodType<any>;
+}
+
+declare function Field(options: FieldOptions): (target: any, context: any) => void;
+declare function getFieldMetadata(target: any): any;
+/**
+ * Declares a one-to-many relation.
+ * @param model   Lazy getter returning the related model constructor.
+ * @param foreignKey  Column on the **related** table that references this model.
+ * @param localKey    Column on **this** table (defaults to this model's primary key).
+ *
+ * @example
+ * class User extends Model {
+ *   @HasMany(() => Post, 'authorId')
+ *   posts?: Post[];
+ * }
+ */
+declare function HasMany(model: () => any, foreignKey: string, localKey?: string): (target: any, propertyKey: string) => void;
+/**
+ * Declares a one-to-one relation where the FK lives on the related table.
+ * @param model       Lazy getter returning the related model constructor.
+ * @param foreignKey  Column on the **related** table that references this model.
+ * @param localKey    Column on **this** table (defaults to primary key).
+ *
+ * @example
+ * class User extends Model {
+ *   @HasOne(() => Profile, 'userId')
+ *   profile?: Profile;
+ * }
+ */
+declare function HasOne(model: () => any, foreignKey: string, localKey?: string): (target: any, propertyKey: string) => void;
+/**
+ * Declares a many-to-one (or one-to-one) relation where the FK lives on **this** table.
+ * @param model       Lazy getter returning the related model constructor.
+ * @param foreignKey  Column on **this** table that holds the FK value.
+ * @param ownerKey    Column on the **related** table being pointed to (defaults to its primary key).
+ *
+ * @example
+ * class Post extends Model {
+ *   @BelongsTo(() => User, 'authorId')
+ *   author?: User;
+ * }
+ */
+declare function BelongsTo(model: () => any, foreignKey: string, ownerKey?: string): (target: any, propertyKey: string) => void;
+/**
+ * Declares a many-to-many relation through a pivot/junction model.
+ * @param model            Lazy getter returning the **related** model constructor.
+ * @param pivotModel       Lazy getter returning the **pivot** model constructor.
+ * @param pivotForeignKey  Column on the pivot table that references **this** model.
+ * @param pivotRelatedKey  Column on the pivot table that references the **related** model.
+ * @param localKey         Override for this model's local key (defaults to primary key).
+ *
+ * @example
+ * class User extends Model {
+ *   @BelongsToMany(() => Role, () => UserRole, 'userId', 'roleId')
+ *   roles?: Role[];
+ * }
+ */
+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 };