express-model-binding 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sepehr Mohseni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# express-model-binding
+
+[![npm version](https://badge.fury.io/js/express-model-binding.svg)](https://www.npmjs.com/package/express-model-binding)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](http://www.typescriptlang.org/)
+
+Route model binding for Express.js. If you've used Laravel, you know how useful this pattern is—automatically resolve route parameters to database models.
+
+Works with Knex, Mongoose, TypeORM, Sequelize, and Prisma.
+
+## Why?
+
+Instead of this:
+
+```typescript
+app.get('/users/:id', async (req, res) => {
+  const user = await db('users').where('id', req.params.id).first();
+  if (!user) return res.status(404).json({ error: 'User not found' });
+  res.json(user);
+});
+```
+
+Write this:
+
+```typescript
+app.get('/users/:user', bindModel('user', 'users'), (req, res) => {
+  res.json(req.user);
+});
+```
+
+## Install
+
+```bash
+npm install express-model-binding
+```
+
+Then install your ORM:
+
+```bash
+npm install knex pg          # Knex + Postgres
+npm install mongoose         # MongoDB
+npm install typeorm          # TypeORM
+npm install sequelize        # Sequelize
+npm install @prisma/client   # Prisma
+```
+
+## Setup
+
+```typescript
+import express from 'express';
+import Knex from 'knex';
+import { ModelBinder, KnexAdapter, bindModel } from 'express-model-binding';
+
+const app = express();
+const knex = Knex({ client: 'pg', connection: process.env.DATABASE_URL });
+
+// Configure once at startup
+ModelBinder.setAdapter(new KnexAdapter(knex));
+
+// Use in routes
+app.get('/users/:user', bindModel('user', 'users'), (req, res) => {
+  res.json(req.user);
+});
+```
+
+## Adapters
+
+**Knex**
+```typescript
+import { KnexAdapter } from 'express-model-binding';
+ModelBinder.setAdapter(new KnexAdapter(knex));
+app.get('/users/:user', bindModel('user', 'users'), handler);
+```
+
+**Mongoose**
+```typescript
+import { MongooseAdapter } from 'express-model-binding';
+ModelBinder.setAdapter(new MongooseAdapter());
+app.get('/users/:user', bindModel('user', User), handler);
+```
+
+**TypeORM**
+```typescript
+import { TypeORMAdapter } from 'express-model-binding';
+ModelBinder.setAdapter(new TypeORMAdapter(dataSource));
+app.get('/users/:user', bindModel('user', User), handler);
+```
+
+**Sequelize**
+```typescript
+import { SequelizeAdapter } from 'express-model-binding';
+ModelBinder.setAdapter(new SequelizeAdapter(sequelize));
+app.get('/users/:user', bindModel('user', User), handler);
+```
+
+**Prisma**
+```typescript
+import { PrismaAdapter } from 'express-model-binding';
+ModelBinder.setAdapter(new PrismaAdapter(prisma));
+app.get('/users/:user', bindModel('user', 'user'), handler);
+```
+
+## Middleware
+
+**bindModel** — Basic binding
+```typescript
+app.get('/users/:user', bindModel('user', 'users'), handler);
+```
+
+**bindModels** — Multiple models
+```typescript
+app.get('/users/:user/posts/:post', bindModels({
+  user: { model: 'users' },
+  post: { model: 'posts' },
+}), handler);
+```
+
+**bindOptional** — Don't throw if missing
+```typescript
+app.get('/users/:user', bindOptional('user', 'users'), handler);
+```
+
+**bindByKey** — Bind by slug, email, etc.
+```typescript
+app.get('/posts/:slug', bindByKey('slug', 'posts', 'slug'), handler);
+```
+
+**bindAs** — Custom request property name
+```typescript
+app.get('/profile/:id', bindAs('id', 'users', 'profile'), handler);
+```
+
+**bindCached** — With caching
+```typescript
+app.get('/users/:user', bindCached('user', 'users', 60000), handler);
+```
+
+**bindWithRelations** — Eager load relations
+```typescript
+app.get('/users/:user', bindWithRelations('user', 'users', ['posts']), handler);
+```
+
+## Options
+
+```typescript
+bindModel('user', 'users', {
+  key: 'slug',              // Field to query (default: primary key)
+  optional: true,           // Don't throw 404 if not found
+  select: ['id', 'name'],   // Select specific fields
+  include: ['posts'],       // Load relations
+  where: { active: true },  // Extra conditions
+  withTrashed: true,        // Include soft-deleted
+  cache: true,              // Enable caching
+  cacheTTL: 30000,          // Cache duration (ms)
+  errorMessage: 'Not found',
+});
+```
+
+## Error Handling
+
+```typescript
+import { ModelNotFoundError } from 'express-model-binding';
+
+app.use((err, req, res, next) => {
+  if (err instanceof ModelNotFoundError) {
+    return res.status(404).json({ error: err.message });
+  }
+  next(err);
+});
+```
+
+## Utilities
+
+**Transformers** — Convert parameter values
+```typescript
+import { toNumber, toLowerCase } from 'express-model-binding';
+bindModel('user', 'users', { transformValue: toNumber });
+```
+
+**Validators** — Check format before querying
+```typescript
+import { isUUID, isObjectId } from 'express-model-binding';
+```
+
+## Debugging
+
+```typescript
+ModelBinder.setDebug(true);
+```
+
+## API
+
+```typescript
+ModelBinder.setAdapter(adapter)   // Set ORM adapter
+ModelBinder.getAdapter()          // Get current adapter
+ModelBinder.clearCache()          // Clear binding cache
+ModelBinder.reset()               // Reset all state
+```
+
+## License
+
+MIT © [Sepehr Mohseni](https://github.com/sepehr-mohseni)
+
+## Links
+
+- [npm](https://www.npmjs.com/package/express-model-binding)
+- [GitHub](https://github.com/sepehr-mohseni/express-model-binding)
+- [Issues](https://github.com/sepehr-mohseni/express-model-binding/issues)

package/dist/BaseAdapter-BjvLQijd.d.mts

@@ -0,0 +1,214 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+
+/**
+ * Generic query builder type - adapters can narrow this to their specific type
+ */
+type QueryBuilder<T = unknown> = T;
+/**
+ * Query modifier function type
+ */
+type QueryModifier<T = unknown> = (queryBuilder: QueryBuilder<T>) => QueryBuilder<T>;
+/**
+ * Base adapter interface that all ORM adapters must implement
+ */
+interface IORMAdapter<TModel = unknown, TResult = unknown> {
+    readonly name: string;
+    findByKey(model: TModel, key: string, value: unknown, options?: QueryOptions): Promise<TResult | null>;
+    getPrimaryKeyName(model: TModel): string;
+    isValidModel(model: unknown): model is TModel;
+    transformValue(model: TModel, key: string, value: string): unknown;
+    supportsSoftDeletes(model: TModel): boolean;
+    getModelMetadata?(model: TModel): ModelMetadata;
+}
+/**
+ * Query options for model lookups
+ */
+interface QueryOptions {
+    /**
+     * Relations to eager load
+     */
+    include?: string[] | Record<string, unknown>;
+    /**
+     * Additional WHERE conditions
+     */
+    where?: Record<string, unknown>;
+    /**
+     * Custom query modifier - receives ORM-specific query builder
+     */
+    query?: QueryModifier;
+    /**
+     * Fields to select
+     */
+    select?: string[];
+    /**
+     * Include soft-deleted records
+     */
+    withTrashed?: boolean;
+    /**
+     * Only return soft-deleted records
+     */
+    onlyTrashed?: boolean;
+    /**
+     * Enable result caching
+     */
+    cache?: boolean | number;
+    /**
+     * Row locking for transactions
+     */
+    lock?: 'forUpdate' | 'forShare';
+}
+/**
+ * Binding middleware options
+ */
+interface BindOptions extends QueryOptions {
+    /**
+     * Field to search by (defaults to primary key)
+     */
+    key?: string;
+    /**
+     * Custom error when model not found
+     */
+    onNotFound?: Error | ((paramName: string, paramValue: string) => Error);
+    /**
+     * Transform parameter value before querying
+     */
+    transformValue?: (value: string) => unknown;
+    /**
+     * Property name for attaching model to request
+     */
+    as?: string;
+    /**
+     * Don't throw if model not found
+     */
+    optional?: boolean;
+    /**
+     * Custom 404 message
+     */
+    errorMessage?: string;
+    /**
+     * Validate loaded model
+     */
+    validate?: (model: unknown, req: Request) => void | Promise<void>;
+    /**
+     * Enable caching
+     */
+    cache?: boolean;
+    /**
+     * Cache TTL in milliseconds
+     */
+    cacheTTL?: number;
+}
+/**
+ * Multi-model binding configuration
+ */
+interface ModelBindingsConfig {
+    [paramName: string]: {
+        model: unknown;
+        options?: BindOptions;
+    };
+}
+/**
+ * Binding operation context
+ */
+interface BindingContext {
+    req: Request;
+    res: Response;
+    paramName: string;
+    paramValue: string;
+    model: unknown;
+    options: BindOptions;
+    adapter: IORMAdapter;
+    startTime: number;
+}
+/**
+ * Binding operation result
+ */
+interface BindingResult {
+    success: boolean;
+    model?: unknown;
+    error?: Error;
+    duration: number;
+    fromCache?: boolean;
+}
+/**
+ * Model metadata for debugging
+ */
+interface ModelMetadata {
+    name: string;
+    primaryKey: string;
+    tableName?: string;
+    relations?: string[];
+    softDeletes: boolean;
+    adapter?: string;
+    [key: string]: unknown;
+}
+/**
+ * Cache entry structure
+ */
+interface CacheEntry<T = unknown> {
+    value: T;
+    timestamp: number;
+    ttl: number;
+}
+/**
+ * Global configuration options
+ */
+interface ModelBindingGlobalConfig {
+    adapter?: IORMAdapter;
+    cache?: {
+        enabled: boolean;
+        ttl: number;
+        maxSize?: number;
+    };
+    debug?: boolean;
+    logger?: (message: string, context?: unknown) => void;
+    onError?: (error: Error, context: BindingContext) => void;
+}
+/**
+ * Express request with bound models
+ */
+interface TypedRequest<P = Record<string, string>, ResBody = unknown, ReqBody = unknown, ReqQuery = unknown, Models extends Record<string, unknown> = Record<string, unknown>> extends Request<P, ResBody, ReqBody, ReqQuery> {
+    [K: string]: unknown;
+    models?: Models;
+}
+/**
+ * Extract model type from binding config
+ */
+type ExtractModelType<T> = T extends {
+    model: infer M;
+} ? M : never;
+/**
+ * Typed request handler
+ */
+type TypedRequestHandler<Models extends Record<string, unknown> = Record<string, unknown>, P = Record<string, string>, ResBody = unknown, ReqBody = unknown, ReqQuery = unknown> = (req: TypedRequest<P, ResBody, ReqBody, ReqQuery, Models>, res: Response<ResBody>, next: NextFunction) => void | Promise<void>;
+/**
+ * Middleware function type
+ */
+type MiddlewareFunction = RequestHandler;
+
+/**
+ * Abstract base class providing common adapter functionality.
+ * Extend this class to implement ORM-specific adapters.
+ *
+ * @typeParam TModel - Model type accepted by this adapter
+ * @typeParam TResult - Result type returned by queries
+ * @typeParam TQueryBuilder - ORM-specific query builder type
+ */
+declare abstract class BaseAdapter<TModel = unknown, TResult = unknown, TQueryBuilder = unknown> implements IORMAdapter<TModel, TResult> {
+    abstract readonly name: string;
+    abstract findByKey(model: TModel, key: string, value: unknown, options?: QueryOptions): Promise<TResult | null>;
+    abstract getPrimaryKeyName(model: TModel): string;
+    abstract isValidModel(model: unknown): model is TModel;
+    transformValue(_model: TModel, _key: string, value: string): unknown;
+    supportsSoftDeletes(_model: TModel): boolean;
+    getModelMetadata(model: TModel): ModelMetadata;
+    protected validateModel(model: unknown): asserts model is TModel;
+    protected getModelName(model: TModel): string;
+    protected applySoftDeleteFilter(queryBuilder: TQueryBuilder, _options?: QueryOptions): TQueryBuilder;
+    protected applyIncludes(queryBuilder: TQueryBuilder, _includes?: string[] | Record<string, unknown>): TQueryBuilder;
+    protected applySelect(queryBuilder: TQueryBuilder, _select?: string[]): TQueryBuilder;
+    protected applyWhereConditions(queryBuilder: TQueryBuilder, _where?: Record<string, unknown>): TQueryBuilder;
+    protected applyCustomQuery(queryBuilder: TQueryBuilder, queryFn?: QueryModifier<TQueryBuilder>): TQueryBuilder;
+}
+
+export { type BindOptions as B, type CacheEntry as C, type ExtractModelType as E, type IORMAdapter as I, type ModelBindingsConfig as M, type QueryOptions as Q, type TypedRequest as T, type BindingResult as a, BaseAdapter as b, type BindingContext as c, type ModelMetadata as d, type ModelBindingGlobalConfig as e, type TypedRequestHandler as f, type MiddlewareFunction as g };

package/dist/BaseAdapter-BjvLQijd.d.ts

@@ -0,0 +1,214 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+
+/**
+ * Generic query builder type - adapters can narrow this to their specific type
+ */
+type QueryBuilder<T = unknown> = T;
+/**
+ * Query modifier function type
+ */
+type QueryModifier<T = unknown> = (queryBuilder: QueryBuilder<T>) => QueryBuilder<T>;
+/**
+ * Base adapter interface that all ORM adapters must implement
+ */
+interface IORMAdapter<TModel = unknown, TResult = unknown> {
+    readonly name: string;
+    findByKey(model: TModel, key: string, value: unknown, options?: QueryOptions): Promise<TResult | null>;
+    getPrimaryKeyName(model: TModel): string;
+    isValidModel(model: unknown): model is TModel;
+    transformValue(model: TModel, key: string, value: string): unknown;
+    supportsSoftDeletes(model: TModel): boolean;
+    getModelMetadata?(model: TModel): ModelMetadata;
+}
+/**
+ * Query options for model lookups
+ */
+interface QueryOptions {
+    /**
+     * Relations to eager load
+     */
+    include?: string[] | Record<string, unknown>;
+    /**
+     * Additional WHERE conditions
+     */
+    where?: Record<string, unknown>;
+    /**
+     * Custom query modifier - receives ORM-specific query builder
+     */
+    query?: QueryModifier;
+    /**
+     * Fields to select
+     */
+    select?: string[];
+    /**
+     * Include soft-deleted records
+     */
+    withTrashed?: boolean;
+    /**
+     * Only return soft-deleted records
+     */
+    onlyTrashed?: boolean;
+    /**
+     * Enable result caching
+     */
+    cache?: boolean | number;
+    /**
+     * Row locking for transactions
+     */
+    lock?: 'forUpdate' | 'forShare';
+}
+/**
+ * Binding middleware options
+ */
+interface BindOptions extends QueryOptions {
+    /**
+     * Field to search by (defaults to primary key)
+     */
+    key?: string;
+    /**
+     * Custom error when model not found
+     */
+    onNotFound?: Error | ((paramName: string, paramValue: string) => Error);
+    /**
+     * Transform parameter value before querying
+     */
+    transformValue?: (value: string) => unknown;
+    /**
+     * Property name for attaching model to request
+     */
+    as?: string;
+    /**
+     * Don't throw if model not found
+     */
+    optional?: boolean;
+    /**
+     * Custom 404 message
+     */
+    errorMessage?: string;
+    /**
+     * Validate loaded model
+     */
+    validate?: (model: unknown, req: Request) => void | Promise<void>;
+    /**
+     * Enable caching
+     */
+    cache?: boolean;
+    /**
+     * Cache TTL in milliseconds
+     */
+    cacheTTL?: number;
+}
+/**
+ * Multi-model binding configuration
+ */
+interface ModelBindingsConfig {
+    [paramName: string]: {
+        model: unknown;
+        options?: BindOptions;
+    };
+}
+/**
+ * Binding operation context
+ */
+interface BindingContext {
+    req: Request;
+    res: Response;
+    paramName: string;
+    paramValue: string;
+    model: unknown;
+    options: BindOptions;
+    adapter: IORMAdapter;
+    startTime: number;
+}
+/**
+ * Binding operation result
+ */
+interface BindingResult {
+    success: boolean;
+    model?: unknown;
+    error?: Error;
+    duration: number;
+    fromCache?: boolean;
+}
+/**
+ * Model metadata for debugging
+ */
+interface ModelMetadata {
+    name: string;
+    primaryKey: string;
+    tableName?: string;
+    relations?: string[];
+    softDeletes: boolean;
+    adapter?: string;
+    [key: string]: unknown;
+}
+/**
+ * Cache entry structure
+ */
+interface CacheEntry<T = unknown> {
+    value: T;
+    timestamp: number;
+    ttl: number;
+}
+/**
+ * Global configuration options
+ */
+interface ModelBindingGlobalConfig {
+    adapter?: IORMAdapter;
+    cache?: {
+        enabled: boolean;
+        ttl: number;
+        maxSize?: number;
+    };
+    debug?: boolean;
+    logger?: (message: string, context?: unknown) => void;
+    onError?: (error: Error, context: BindingContext) => void;
+}
+/**
+ * Express request with bound models
+ */
+interface TypedRequest<P = Record<string, string>, ResBody = unknown, ReqBody = unknown, ReqQuery = unknown, Models extends Record<string, unknown> = Record<string, unknown>> extends Request<P, ResBody, ReqBody, ReqQuery> {
+    [K: string]: unknown;
+    models?: Models;
+}
+/**
+ * Extract model type from binding config
+ */
+type ExtractModelType<T> = T extends {
+    model: infer M;
+} ? M : never;
+/**
+ * Typed request handler
+ */
+type TypedRequestHandler<Models extends Record<string, unknown> = Record<string, unknown>, P = Record<string, string>, ResBody = unknown, ReqBody = unknown, ReqQuery = unknown> = (req: TypedRequest<P, ResBody, ReqBody, ReqQuery, Models>, res: Response<ResBody>, next: NextFunction) => void | Promise<void>;
+/**
+ * Middleware function type
+ */
+type MiddlewareFunction = RequestHandler;
+
+/**
+ * Abstract base class providing common adapter functionality.
+ * Extend this class to implement ORM-specific adapters.
+ *
+ * @typeParam TModel - Model type accepted by this adapter
+ * @typeParam TResult - Result type returned by queries
+ * @typeParam TQueryBuilder - ORM-specific query builder type
+ */
+declare abstract class BaseAdapter<TModel = unknown, TResult = unknown, TQueryBuilder = unknown> implements IORMAdapter<TModel, TResult> {
+    abstract readonly name: string;
+    abstract findByKey(model: TModel, key: string, value: unknown, options?: QueryOptions): Promise<TResult | null>;
+    abstract getPrimaryKeyName(model: TModel): string;
+    abstract isValidModel(model: unknown): model is TModel;
+    transformValue(_model: TModel, _key: string, value: string): unknown;
+    supportsSoftDeletes(_model: TModel): boolean;
+    getModelMetadata(model: TModel): ModelMetadata;
+    protected validateModel(model: unknown): asserts model is TModel;
+    protected getModelName(model: TModel): string;
+    protected applySoftDeleteFilter(queryBuilder: TQueryBuilder, _options?: QueryOptions): TQueryBuilder;
+    protected applyIncludes(queryBuilder: TQueryBuilder, _includes?: string[] | Record<string, unknown>): TQueryBuilder;
+    protected applySelect(queryBuilder: TQueryBuilder, _select?: string[]): TQueryBuilder;
+    protected applyWhereConditions(queryBuilder: TQueryBuilder, _where?: Record<string, unknown>): TQueryBuilder;
+    protected applyCustomQuery(queryBuilder: TQueryBuilder, queryFn?: QueryModifier<TQueryBuilder>): TQueryBuilder;
+}
+
+export { type BindOptions as B, type CacheEntry as C, type ExtractModelType as E, type IORMAdapter as I, type ModelBindingsConfig as M, type QueryOptions as Q, type TypedRequest as T, type BindingResult as a, BaseAdapter as b, type BindingContext as c, type ModelMetadata as d, type ModelBindingGlobalConfig as e, type TypedRequestHandler as f, type MiddlewareFunction as g };

package/dist/adapters/KnexAdapter.d.mts

@@ -0,0 +1,44 @@
+import { Knex } from 'knex';
+import { b as BaseAdapter, Q as QueryOptions, d as ModelMetadata } from '../BaseAdapter-BjvLQijd.mjs';
+import 'express';
+
+/**
+ * Model definition for Knex tables with soft delete support
+ */
+interface KnexModel {
+    tableName: string;
+    primaryKey?: string;
+    softDeleteColumn?: string;
+}
+/**
+ * Union type for Knex model inputs
+ */
+type KnexModelInput = string | KnexModel;
+/**
+ * Adapter for Knex query builder supporting PostgreSQL, MySQL, SQLite, MSSQL, Oracle
+ */
+declare class KnexAdapter extends BaseAdapter<KnexModelInput, Record<string, unknown>, Knex.QueryBuilder> {
+    private knex;
+    readonly name = "knex";
+    constructor(knex: Knex);
+    getKnex(): Knex;
+    findByKey(model: KnexModelInput, key: string, value: unknown, options?: QueryOptions): Promise<Record<string, unknown> | null>;
+    getPrimaryKeyName(model: KnexModelInput): string;
+    isValidModel(model: unknown): model is KnexModelInput;
+    transformValue(model: KnexModelInput, key: string, value: string): unknown;
+    supportsSoftDeletes(model: KnexModelInput): boolean;
+    getModelMetadata(model: KnexModelInput): ModelMetadata;
+    private getTableName;
+    private getSoftDeleteColumn;
+    protected applyWhereConditions(query: Knex.QueryBuilder, where: Record<string, unknown>): Knex.QueryBuilder;
+}
+/**
+ * Create a Knex model definition
+ */
+declare function defineKnexModel(config: {
+    tableName: string;
+    primaryKey?: string;
+    softDeleteColumn?: string;
+}): KnexModel;
+
+export { KnexAdapter, type KnexModel, type KnexModelInput, defineKnexModel };