@exyconn/common 2.3.2 → 2.3.4

package/dist/server/middleware/index.d.mts

@@ -1,4 +1,5 @@
-import { Request, Response, NextFunction } from 'express';
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+import { Model, Document } from 'mongoose';
 
 /**
  * Extended Request with auth information
@@ -53,4 +54,284 @@ declare const extractOrganization: (req: AuthRequest, _res: Response, next: Next
  */
 declare const requireOrganization: (req: AuthRequest, res: Response, next: NextFunction) => void;
 
-export { type AuthRequest, type JWTPayload, authenticateApiKey, authenticateJWT, extractOrganization, optionalAuthenticateJWT, requireOrganization };
+/**
+ * Query Parser Middleware
+ *
+ * Parses query parameters into a standardized format for pagination and filtering.
+ */
+
+/**
+ * Parse query parameters from request
+ * Supports:
+ * - page, limit for pagination
+ * - sort or sortBy/sortOrder for sorting
+ * - search for text search
+ * - filter object or direct query params for filtering
+ */
+declare const queryParser: (req: Request, _: Response, next: NextFunction) => void;
+
+/**
+ * Query Pagination Middleware
+ *
+ * Provides standardized pagination for Mongoose models.
+ * Works with queryParser middleware for parsed query parameters.
+ */
+
+type ZodObject$2<T = Record<string, unknown>> = {
+    parse: (data: unknown) => T;
+    safeParse: (data: unknown) => {
+        success: boolean;
+        data?: T;
+        error?: Error;
+    };
+};
+interface PaginationOptions {
+    searchFields?: string[];
+    validatorSchema?: ZodObject$2<unknown>;
+    regexFilterFields?: string[];
+}
+/**
+ * Creates a pagination middleware for a Mongoose model
+ *
+ * @param model - The Mongoose model to paginate
+ * @param options - Pagination options
+ * @param withOrgId - Whether to filter by organization ID from header
+ */
+declare const queryPagination: <T>(model: Model<T>, options?: PaginationOptions, withOrgId?: boolean) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+/**
+ * CRUD Middleware Factory
+ *
+ * High-configuration middleware for standardized CRUD operations.
+ * Provides consistent API patterns across all services.
+ *
+ * Features:
+ * - getAll with pagination, search, filters, sorting
+ * - getById with validation
+ * - create with validation and auto-response
+ * - update with validation and auto-response
+ * - delete (single and bulk)
+ * - Organization-scoped queries
+ */
+
+interface ZodIssue {
+    path: (string | number)[];
+    message: string;
+}
+interface ZodError extends Error {
+    errors: ZodIssue[];
+}
+interface ZodSchema<T = unknown> {
+    parse: (data: unknown) => T;
+    safeParse: (data: unknown) => {
+        success: boolean;
+        data?: T;
+        error?: ZodError;
+    };
+}
+type ZodObject$1<T = Record<string, unknown>> = ZodSchema<T>;
+/**
+ * Extended request with organization ID
+ */
+interface OrgRequest extends Request {
+    organizationId?: string;
+}
+/**
+ * Extended response with paginated result
+ */
+interface PaginatedResponse extends Response {
+    paginatedResult?: {
+        data: unknown[];
+        meta: {
+            page: number;
+            limit: number;
+            total: number;
+            totalPages: number;
+        };
+        columns?: unknown[];
+    };
+}
+/**
+ * CRUD controller configuration
+ */
+interface CrudConfig<T> {
+    /** Mongoose model */
+    model: Model<T>;
+    /** Resource name for logging and messages */
+    resourceName: string;
+    /** Zod schema for create validation */
+    createSchema?: ZodObject$1<unknown>;
+    /** Zod schema for update validation */
+    updateSchema?: ZodObject$1<unknown>;
+    /** Fields to search on (for getAll) */
+    searchFields?: string[];
+    /** Fields that use regex matching for filters */
+    regexFilterFields?: string[];
+    /** Whether to scope by organizationId (default: true) */
+    withOrganization?: boolean;
+    /** Field to use as the organization reference (default: 'organizationId') */
+    orgField?: string;
+    /** Custom transform for create input */
+    transformCreate?: (input: unknown, req: OrgRequest) => unknown;
+    /** Custom transform for update input */
+    transformUpdate?: (input: unknown, req: OrgRequest) => unknown;
+    /** Custom post-create hook */
+    afterCreate?: (doc: Document, req: OrgRequest) => Promise<void> | void;
+    /** Custom post-update hook */
+    afterUpdate?: (doc: Document, req: OrgRequest) => Promise<void> | void;
+    /** Custom post-delete hook */
+    afterDelete?: (id: string, req: OrgRequest) => Promise<void> | void;
+    /** Fields to exclude from response */
+    excludeFields?: string[];
+    /** Fields to populate in queries */
+    populateFields?: string[];
+    /** Custom query builder for getAll */
+    buildQuery?: (req: OrgRequest, baseQuery: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Creates standardized CRUD controller handlers
+ */
+declare function createCrudControllers<T extends Document>(config: CrudConfig<T>): {
+    getAll: RequestHandler;
+    getById: RequestHandler;
+    create: RequestHandler;
+    update: RequestHandler;
+    deleteOne: RequestHandler;
+    bulkDelete: RequestHandler;
+};
+/**
+ * Creates a standardized pagination middleware for a model
+ */
+declare function createPaginationMiddleware<T>(model: Model<T>, config?: Partial<CrudConfig<T>>): RequestHandler;
+
+/**
+ * Bulk Delete Middleware
+ *
+ * Common delete middleware for all services.
+ * Supports:
+ * - ['*'] → delete all records
+ * - ['id1', 'id2', ...] → delete multiple records
+ * - Single ID deletion as subset of multiple
+ */
+
+/**
+ * Extended request interface with parsed delete IDs
+ */
+interface BulkDeleteRequest extends Request {
+    deleteIds?: string[];
+    deleteAll?: boolean;
+}
+/**
+ * Validates and parses bulk delete request body
+ *
+ * Expected request body formats:
+ * - { "ids": ["*"] } or ["*"] → delete all
+ * - { "ids": ["id1", "id2"] } or ["id1", "id2"] → delete specific records
+ */
+declare const parseBulkDelete: (req: Request, res: Response, next: NextFunction) => void | Response;
+/**
+ * Helper function to build delete filter for MongoDB
+ */
+declare const buildDeleteFilter: (req: BulkDeleteRequest, organizationId: string) => Record<string, unknown>;
+/**
+ * Generic bulk delete handler factory
+ *
+ * Creates a controller function that handles bulk delete operations
+ * for any Mongoose model.
+ */
+declare const createBulkDeleteHandler: (Model: {
+    deleteMany: (filter: Record<string, unknown>) => Promise<{
+        deletedCount?: number;
+    }>;
+}, modelName: string) => (req: Request, res: Response) => Promise<Response>;
+
+/**
+ * Pagination Types
+ * Standard types for pagination middleware
+ */
+
+/**
+ * Sort order for queries
+ */
+type SortOrder = 'asc' | 'desc';
+/**
+ * Sort configuration
+ */
+interface SortConfig {
+    field: string;
+    order: SortOrder;
+}
+/**
+ * Parsed query parameters from request
+ */
+interface ParsedQuery {
+    page: number;
+    limit: number;
+    sort?: SortConfig;
+    search?: string;
+    filter: Record<string, string>;
+}
+/**
+ * Extended Express Request with parsed query
+ */
+interface PaginatedRequest extends Request {
+    parsedQuery: ParsedQuery;
+}
+/**
+ * Pagination metadata for response
+ */
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+/**
+ * Paginated result for response
+ */
+interface PaginatedResult<T = unknown> {
+    data: T[];
+    meta: PaginationMeta;
+    columns?: unknown[];
+}
+declare global {
+    namespace Express {
+        interface Request {
+            parsedQuery: ParsedQuery;
+        }
+        interface Response {
+            paginatedResult?: PaginatedResult;
+        }
+    }
+}
+
+/**
+ * Schema Meta Extraction Utility
+ * Extracts column metadata from Mongoose models and Zod schemas
+ */
+
+interface ZodTypeAny {
+    _def?: {
+        typeName?: string;
+        innerType?: ZodTypeAny;
+        values?: unknown[];
+    };
+}
+type ZodObject<T = unknown> = {
+    shape?: Record<string, ZodTypeAny>;
+    parse: (data: unknown) => T;
+};
+/**
+ * Column metadata interface
+ */
+interface ColumnMeta {
+    name: string;
+    datatype: string;
+    required: boolean;
+}
+/**
+ * Extract column metadata from Mongoose model and optional Zod schema
+ */
+declare const extractSchemaMeta: <T>(model: Model<T>, zodSchema?: ZodObject<unknown>) => ColumnMeta[];
+
+export { type AuthRequest, type BulkDeleteRequest, type ColumnMeta, type CrudConfig, type JWTPayload, type OrgRequest, type PaginatedRequest, type PaginatedResponse, type PaginatedResult, type PaginationMeta, type ParsedQuery, type SortConfig, type SortOrder, authenticateApiKey, authenticateJWT, buildDeleteFilter, createBulkDeleteHandler, createCrudControllers, createPaginationMiddleware, extractOrganization, extractSchemaMeta, optionalAuthenticateJWT, parseBulkDelete, queryPagination, queryParser, requireOrganization };

package/dist/server/middleware/index.d.ts

@@ -1,4 +1,5 @@
-import { Request, Response, NextFunction } from 'express';
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+import { Model, Document } from 'mongoose';
 
 /**
  * Extended Request with auth information
@@ -53,4 +54,284 @@ declare const extractOrganization: (req: AuthRequest, _res: Response, next: Next
  */
 declare const requireOrganization: (req: AuthRequest, res: Response, next: NextFunction) => void;
 
-export { type AuthRequest, type JWTPayload, authenticateApiKey, authenticateJWT, extractOrganization, optionalAuthenticateJWT, requireOrganization };
+/**
+ * Query Parser Middleware
+ *
+ * Parses query parameters into a standardized format for pagination and filtering.
+ */
+
+/**
+ * Parse query parameters from request
+ * Supports:
+ * - page, limit for pagination
+ * - sort or sortBy/sortOrder for sorting
+ * - search for text search
+ * - filter object or direct query params for filtering
+ */
+declare const queryParser: (req: Request, _: Response, next: NextFunction) => void;
+
+/**
+ * Query Pagination Middleware
+ *
+ * Provides standardized pagination for Mongoose models.
+ * Works with queryParser middleware for parsed query parameters.
+ */
+
+type ZodObject$2<T = Record<string, unknown>> = {
+    parse: (data: unknown) => T;
+    safeParse: (data: unknown) => {
+        success: boolean;
+        data?: T;
+        error?: Error;
+    };
+};
+interface PaginationOptions {
+    searchFields?: string[];
+    validatorSchema?: ZodObject$2<unknown>;
+    regexFilterFields?: string[];
+}
+/**
+ * Creates a pagination middleware for a Mongoose model
+ *
+ * @param model - The Mongoose model to paginate
+ * @param options - Pagination options
+ * @param withOrgId - Whether to filter by organization ID from header
+ */
+declare const queryPagination: <T>(model: Model<T>, options?: PaginationOptions, withOrgId?: boolean) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+/**
+ * CRUD Middleware Factory
+ *
+ * High-configuration middleware for standardized CRUD operations.
+ * Provides consistent API patterns across all services.
+ *
+ * Features:
+ * - getAll with pagination, search, filters, sorting
+ * - getById with validation
+ * - create with validation and auto-response
+ * - update with validation and auto-response
+ * - delete (single and bulk)
+ * - Organization-scoped queries
+ */
+
+interface ZodIssue {
+    path: (string | number)[];
+    message: string;
+}
+interface ZodError extends Error {
+    errors: ZodIssue[];
+}
+interface ZodSchema<T = unknown> {
+    parse: (data: unknown) => T;
+    safeParse: (data: unknown) => {
+        success: boolean;
+        data?: T;
+        error?: ZodError;
+    };
+}
+type ZodObject$1<T = Record<string, unknown>> = ZodSchema<T>;
+/**
+ * Extended request with organization ID
+ */
+interface OrgRequest extends Request {
+    organizationId?: string;
+}
+/**
+ * Extended response with paginated result
+ */
+interface PaginatedResponse extends Response {
+    paginatedResult?: {
+        data: unknown[];
+        meta: {
+            page: number;
+            limit: number;
+            total: number;
+            totalPages: number;
+        };
+        columns?: unknown[];
+    };
+}
+/**
+ * CRUD controller configuration
+ */
+interface CrudConfig<T> {
+    /** Mongoose model */
+    model: Model<T>;
+    /** Resource name for logging and messages */
+    resourceName: string;
+    /** Zod schema for create validation */
+    createSchema?: ZodObject$1<unknown>;
+    /** Zod schema for update validation */
+    updateSchema?: ZodObject$1<unknown>;
+    /** Fields to search on (for getAll) */
+    searchFields?: string[];
+    /** Fields that use regex matching for filters */
+    regexFilterFields?: string[];
+    /** Whether to scope by organizationId (default: true) */
+    withOrganization?: boolean;
+    /** Field to use as the organization reference (default: 'organizationId') */
+    orgField?: string;
+    /** Custom transform for create input */
+    transformCreate?: (input: unknown, req: OrgRequest) => unknown;
+    /** Custom transform for update input */
+    transformUpdate?: (input: unknown, req: OrgRequest) => unknown;
+    /** Custom post-create hook */
+    afterCreate?: (doc: Document, req: OrgRequest) => Promise<void> | void;
+    /** Custom post-update hook */
+    afterUpdate?: (doc: Document, req: OrgRequest) => Promise<void> | void;
+    /** Custom post-delete hook */
+    afterDelete?: (id: string, req: OrgRequest) => Promise<void> | void;
+    /** Fields to exclude from response */
+    excludeFields?: string[];
+    /** Fields to populate in queries */
+    populateFields?: string[];
+    /** Custom query builder for getAll */
+    buildQuery?: (req: OrgRequest, baseQuery: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Creates standardized CRUD controller handlers
+ */
+declare function createCrudControllers<T extends Document>(config: CrudConfig<T>): {
+    getAll: RequestHandler;
+    getById: RequestHandler;
+    create: RequestHandler;
+    update: RequestHandler;
+    deleteOne: RequestHandler;
+    bulkDelete: RequestHandler;
+};
+/**
+ * Creates a standardized pagination middleware for a model
+ */
+declare function createPaginationMiddleware<T>(model: Model<T>, config?: Partial<CrudConfig<T>>): RequestHandler;
+
+/**
+ * Bulk Delete Middleware
+ *
+ * Common delete middleware for all services.
+ * Supports:
+ * - ['*'] → delete all records
+ * - ['id1', 'id2', ...] → delete multiple records
+ * - Single ID deletion as subset of multiple
+ */
+
+/**
+ * Extended request interface with parsed delete IDs
+ */
+interface BulkDeleteRequest extends Request {
+    deleteIds?: string[];
+    deleteAll?: boolean;
+}
+/**
+ * Validates and parses bulk delete request body
+ *
+ * Expected request body formats:
+ * - { "ids": ["*"] } or ["*"] → delete all
+ * - { "ids": ["id1", "id2"] } or ["id1", "id2"] → delete specific records
+ */
+declare const parseBulkDelete: (req: Request, res: Response, next: NextFunction) => void | Response;
+/**
+ * Helper function to build delete filter for MongoDB
+ */
+declare const buildDeleteFilter: (req: BulkDeleteRequest, organizationId: string) => Record<string, unknown>;
+/**
+ * Generic bulk delete handler factory
+ *
+ * Creates a controller function that handles bulk delete operations
+ * for any Mongoose model.
+ */
+declare const createBulkDeleteHandler: (Model: {
+    deleteMany: (filter: Record<string, unknown>) => Promise<{
+        deletedCount?: number;
+    }>;
+}, modelName: string) => (req: Request, res: Response) => Promise<Response>;
+
+/**
+ * Pagination Types
+ * Standard types for pagination middleware
+ */
+
+/**
+ * Sort order for queries
+ */
+type SortOrder = 'asc' | 'desc';
+/**
+ * Sort configuration
+ */
+interface SortConfig {
+    field: string;
+    order: SortOrder;
+}
+/**
+ * Parsed query parameters from request
+ */
+interface ParsedQuery {
+    page: number;
+    limit: number;
+    sort?: SortConfig;
+    search?: string;
+    filter: Record<string, string>;
+}
+/**
+ * Extended Express Request with parsed query
+ */
+interface PaginatedRequest extends Request {
+    parsedQuery: ParsedQuery;
+}
+/**
+ * Pagination metadata for response
+ */
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+/**
+ * Paginated result for response
+ */
+interface PaginatedResult<T = unknown> {
+    data: T[];
+    meta: PaginationMeta;
+    columns?: unknown[];
+}
+declare global {
+    namespace Express {
+        interface Request {
+            parsedQuery: ParsedQuery;
+        }
+        interface Response {
+            paginatedResult?: PaginatedResult;
+        }
+    }
+}
+
+/**
+ * Schema Meta Extraction Utility
+ * Extracts column metadata from Mongoose models and Zod schemas
+ */
+
+interface ZodTypeAny {
+    _def?: {
+        typeName?: string;
+        innerType?: ZodTypeAny;
+        values?: unknown[];
+    };
+}
+type ZodObject<T = unknown> = {
+    shape?: Record<string, ZodTypeAny>;
+    parse: (data: unknown) => T;
+};
+/**
+ * Column metadata interface
+ */
+interface ColumnMeta {
+    name: string;
+    datatype: string;
+    required: boolean;
+}
+/**
+ * Extract column metadata from Mongoose model and optional Zod schema
+ */
+declare const extractSchemaMeta: <T>(model: Model<T>, zodSchema?: ZodObject<unknown>) => ColumnMeta[];
+
+export { type AuthRequest, type BulkDeleteRequest, type ColumnMeta, type CrudConfig, type JWTPayload, type OrgRequest, type PaginatedRequest, type PaginatedResponse, type PaginatedResult, type PaginationMeta, type ParsedQuery, type SortConfig, type SortOrder, authenticateApiKey, authenticateJWT, buildDeleteFilter, createBulkDeleteHandler, createCrudControllers, createPaginationMiddleware, extractOrganization, extractSchemaMeta, optionalAuthenticateJWT, parseBulkDelete, queryPagination, queryParser, requireOrganization };