express-model-binding 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,411 @@
+import { Request, Response, RequestHandler } from 'express';
+import { I as IORMAdapter, B as BindOptions, a as BindingResult, M as ModelBindingsConfig } from './BaseAdapter-BjvLQijd.js';
+export { b as BaseAdapter, c as BindingContext, C as CacheEntry, E as ExtractModelType, g as MiddlewareFunction, e as ModelBindingGlobalConfig, d as ModelMetadata, Q as QueryOptions, T as TypedRequest, f as TypedRequestHandler } from './BaseAdapter-BjvLQijd.js';
+export { KnexAdapter, KnexModel, defineKnexModel } from './adapters/KnexAdapter.js';
+export { MongooseAdapter } from './adapters/MongooseAdapter.js';
+export { TypeORMAdapter } from './adapters/TypeORMAdapter.js';
+export { SequelizeAdapter } from './adapters/SequelizeAdapter.js';
+export { PrismaAdapter } from './adapters/PrismaAdapter.js';
+import 'knex';
+import 'mongoose';
+import 'typeorm';
+import 'sequelize';
+
+/**
+ * Central model binding orchestrator
+ */
+declare class ModelBinder {
+    private static adapter;
+    private static cache;
+    private static debug;
+    static setAdapter(adapter: IORMAdapter): void;
+    static getAdapter(): IORMAdapter;
+    static hasAdapter(): boolean;
+    static clearAdapter(): void;
+    static setDebug(enabled: boolean): void;
+    static isDebugEnabled(): boolean;
+    static clearCache(): void;
+    static getCacheStats(): {
+        size: number;
+        maxSize: number;
+    };
+    static bind(req: Request, res: Response, paramName: string, model: unknown, options?: BindOptions): Promise<BindingResult>;
+    private static attachToRequest;
+    private static getCacheKey;
+    private static getModelName;
+    static reset(): void;
+}
+
+/**
+ * Create middleware that binds a model to a route parameter
+ *
+ * @param paramName - The route parameter name (without ':')
+ * @param model - The model class/schema/table
+ * @param options - Binding options
+ * @returns Express middleware function
+ *
+ * @example
+ * app.get('/users/:user', bindModel('user', User), (req, res) => {
+ *   res.json(req.user);
+ * });
+ */
+declare function bindModel(paramName: string, model: unknown, options?: BindOptions): RequestHandler;
+/**
+ * Bind multiple models in a single middleware
+ *
+ * @param bindings - Object mapping parameter names to model configs
+ * @returns Express middleware function
+ *
+ * @example
+ * app.get('/users/:user/posts/:post',
+ *   bindModels({
+ *     user: { model: User },
+ *     post: { model: Post, options: { include: ['comments'] } }
+ *   }),
+ *   (req, res) => {
+ *     res.json({ user: req.user, post: req.post });
+ *   }
+ * );
+ */
+declare function bindModels(bindings: ModelBindingsConfig): RequestHandler;
+/**
+ * Bind a model optionally (don't throw 404 if not found)
+ *
+ * @param paramName - The route parameter name
+ * @param model - The model class/schema/table
+ * @param options - Binding options
+ * @returns Express middleware function
+ *
+ * @example
+ * app.get('/posts/:post?', bindOptional('post', Post), (req, res) => {
+ *   if (req.post) {
+ *     res.json(req.post);
+ *   } else {
+ *     res.json({ message: 'No specific post' });
+ *   }
+ * });
+ */
+declare function bindOptional(paramName: string, model: unknown, options?: BindOptions): RequestHandler;
+/**
+ * Create a middleware that binds a model using a custom key
+ *
+ * @param paramName - The route parameter name
+ * @param model - The model class/schema/table
+ * @param key - The field to search by
+ * @param options - Additional binding options
+ * @returns Express middleware function
+ *
+ * @example
+ * app.get('/users/by-email/:email', bindByKey('email', User, 'email'), (req, res) => {
+ *   res.json(req.email);
+ * });
+ */
+declare function bindByKey(paramName: string, model: unknown, key: string, options?: BindOptions): RequestHandler;
+/**
+ * Create a middleware that binds a model and attaches it with a custom name
+ *
+ * @param paramName - The route parameter name
+ * @param model - The model class/schema/table
+ * @param attachAs - The name to attach the model as on the request
+ * @param options - Additional binding options
+ * @returns Express middleware function
+ *
+ * @example
+ * app.get('/users/:id', bindAs('id', User, 'currentUser'), (req, res) => {
+ *   res.json(req.currentUser);
+ * });
+ */
+declare function bindAs(paramName: string, model: unknown, attachAs: string, options?: BindOptions): RequestHandler;
+/**
+ * Create a middleware that binds a model with caching
+ *
+ * @param paramName - The route parameter name
+ * @param model - The model class/schema/table
+ * @param ttl - Cache TTL in milliseconds (default: 60000)
+ * @param options - Additional binding options
+ * @returns Express middleware function
+ *
+ * @example
+ * app.get('/users/:user', bindCached('user', User, 300000), (req, res) => {
+ *   res.json(req.user);
+ * });
+ */
+declare function bindCached(paramName: string, model: unknown, ttl?: number, options?: BindOptions): RequestHandler;
+/**
+ * Create a middleware that binds a model with eager-loaded relations
+ *
+ * @param paramName - The route parameter name
+ * @param model - The model class/schema/table
+ * @param relations - Relations to eager load
+ * @param options - Additional binding options
+ * @returns Express middleware function
+ *
+ * @example
+ * app.get('/users/:user', bindWithRelations('user', User, ['posts', 'profile']), (req, res) => {
+ *   res.json(req.user);
+ * });
+ */
+declare function bindWithRelations(paramName: string, model: unknown, relations: string[] | Record<string, unknown>, options?: BindOptions): RequestHandler;
+
+/**
+ * Base error class for model binding errors
+ */
+declare class BindingError extends Error {
+    readonly originalError?: Error;
+    constructor(message: string, originalError?: Error);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when a model is not found (404)
+ */
+declare class ModelNotFoundError extends Error {
+    readonly statusCode = 404;
+    readonly paramName: string;
+    readonly paramValue: string;
+    readonly modelName: string;
+    constructor(paramName: string, paramValue: string, modelName: string, customMessage?: string);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when no adapter is configured
+ */
+declare class AdapterNotSetError extends Error {
+    constructor(message?: string);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when a model is invalid for an adapter
+ */
+declare class InvalidModelError extends Error {
+    readonly model: unknown;
+    constructor(message: string, model: unknown);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error thrown when validation fails
+ */
+declare class ValidationError extends Error {
+    readonly statusCode: number;
+    readonly details?: unknown;
+    constructor(message: string, statusCode?: number, details?: unknown);
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * Simple in-memory cache for model binding
+ */
+declare class Cache {
+    private store;
+    private maxSize;
+    constructor(maxSize?: number);
+    /**
+     * Get a value from cache
+     */
+    get<T = unknown>(key: string): T | null;
+    /**
+     * Set a value in cache
+     */
+    set<T = unknown>(key: string, value: T, ttl: number): void;
+    /**
+     * Delete a value from cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cached values
+     */
+    clear(): void;
+    /**
+     * Get cache size
+     */
+    get size(): number;
+    /**
+     * Check if key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Get all keys in the cache
+     */
+    keys(): string[];
+    /**
+     * Remove expired entries
+     */
+    prune(): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+    };
+}
+
+/**
+ * Log levels for the logger
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Logger configuration
+ */
+interface LoggerConfig {
+    enabled: boolean;
+    level: LogLevel;
+    prefix: string;
+}
+/**
+ * Simple logger utility for debugging
+ */
+declare class Logger {
+    private config;
+    private levelPriority;
+    /**
+     * Enable debug logging
+     */
+    enable(): void;
+    /**
+     * Disable debug logging
+     */
+    disable(): void;
+    /**
+     * Check if logging is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Set log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get current log level
+     */
+    getLevel(): LogLevel;
+    /**
+     * Set custom prefix
+     */
+    setPrefix(prefix: string): void;
+    /**
+     * Check if a message at the given level should be logged
+     */
+    private shouldLog;
+    /**
+     * Format log message
+     */
+    private formatMessage;
+    /**
+     * Log a debug message
+     */
+    debug(message: string, context?: unknown): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, context?: unknown): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, context?: unknown): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, error?: unknown): void;
+    /**
+     * Reset logger to default configuration
+     */
+    reset(): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): LoggerConfig;
+}
+declare const logger: Logger;
+
+/**
+ * Check if a value is a valid UUID
+ */
+declare function isUUID(value: string): boolean;
+/**
+ * Check if a value is a valid MongoDB ObjectId
+ */
+declare function isObjectId(value: string): boolean;
+/**
+ * Check if a value is a numeric string
+ */
+declare function isNumeric(value: string): boolean;
+/**
+ * Check if a value is a valid positive integer
+ */
+declare function isPositiveInteger(value: string): boolean;
+/**
+ * Check if a value is a valid slug (lowercase alphanumeric with hyphens)
+ */
+declare function isSlug(value: string): boolean;
+/**
+ * Check if a value is a valid email
+ */
+declare function isEmail(value: string): boolean;
+/**
+ * Validate that a value is not empty
+ */
+declare function isNotEmpty(value: unknown): boolean;
+/**
+ * Validate that a value is a non-empty string
+ */
+declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Validate that a value is a plain object
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Validate that a value is a function
+ */
+declare function isFunction(value: unknown): value is Function;
+/**
+ * Validate route parameter name
+ */
+declare function isValidParamName(value: string): boolean;
+
+/**
+ * Transform a string value to a number if it's numeric
+ */
+declare function toNumber(value: string): number | string;
+/**
+ * Transform a string value to a float if it's a valid decimal
+ */
+declare function toFloat(value: string): number | string;
+/**
+ * Transform a string value to a boolean
+ */
+declare function toBoolean(value: string): boolean;
+/**
+ * Transform a string to lowercase
+ */
+declare function toLowerCase(value: string): string;
+/**
+ * Transform a string to uppercase
+ */
+declare function toUpperCase(value: string): string;
+/**
+ * Trim whitespace from a string
+ */
+declare function trim(value: string): string;
+/**
+ * Transform a slug to underscore format
+ */
+declare function slugToUnderscore(value: string): string;
+/**
+ * Transform underscores to dashes (slug format)
+ */
+declare function underscoreToSlug(value: string): string;
+/**
+ * Auto-detect and transform value based on format
+ */
+declare function autoTransform(value: string): unknown;
+/**
+ * Create a composed transformer from multiple transform functions
+ */
+declare function compose(...transformers: Array<(value: string) => unknown>): (value: string) => unknown;
+/**
+ * Identity transformer - returns the value unchanged
+ */
+declare function identity<T>(value: T): T;
+
+declare const VERSION = "1.0.0";
+
+export { AdapterNotSetError, BindOptions, BindingError, BindingResult, Cache, IORMAdapter, InvalidModelError, type LogLevel, type LoggerConfig, ModelBinder, ModelBindingsConfig, ModelNotFoundError, VERSION, ValidationError, autoTransform, bindAs, bindByKey, bindCached, bindModel, bindModels, bindOptional, bindWithRelations, compose, identity, isEmail, isFunction, isNonEmptyString, isNotEmpty, isNumeric, isObjectId, isPlainObject, isPositiveInteger, isSlug, isUUID, isValidParamName, logger, slugToUnderscore, toBoolean, toFloat, toLowerCase, toNumber, toUpperCase, trim, underscoreToSlug };