schemock 0.0.1

package/dist/middleware/index.d.ts

@@ -0,0 +1,688 @@
+import { M as Middleware, b as MiddlewareContext } from '../types-C1MiZh1d.js';
+export { a as MiddlewareFunction, c as MiddlewareResult } from '../types-C1MiZh1d.js';
+import { b as AdapterResponse } from '../types-c2AN3vky.js';
+import { o as EntitySchema } from '../types-C2bd2vgy.js';
+
+/**
+ * MiddlewareChain - Executor for composable middleware
+ *
+ * Chains middleware in order, executing before hooks, the handler,
+ * and after hooks in sequence.
+ *
+ * @module middleware/chain
+ * @category Middleware
+ */
+
+/**
+ * MiddlewareChain class for executing middleware in sequence.
+ *
+ * Supports both hook-based middleware (before/after/onError) and
+ * function-based middleware (Koa-style handler).
+ *
+ * @example
+ * ```typescript
+ * const chain = new MiddlewareChain([
+ *   createAuthMiddleware({ getToken: () => 'token' }),
+ *   createLoggerMiddleware(),
+ *   createCacheMiddleware({ ttl: 60000 }),
+ * ]);
+ *
+ * const result = await chain.execute(ctx, async () => {
+ *   return adapter.findMany(ctx);
+ * });
+ * ```
+ */
+declare class MiddlewareChain {
+    /** The middleware stack */
+    private middlewares;
+    /**
+     * Create a new MiddlewareChain.
+     *
+     * @param middlewares - Array of middleware to execute in order
+     */
+    constructor(middlewares: Middleware[]);
+    /**
+     * Execute the middleware chain with the given handler.
+     *
+     * @param ctx - The middleware context
+     * @param handler - The final handler (adapter call)
+     * @returns The response after all middleware processing
+     *
+     * @example
+     * ```typescript
+     * const result = await chain.execute<User[]>(
+     *   { entity: 'user', operation: 'findMany', metadata: {} },
+     *   () => adapter.findMany({ entity: 'user' })
+     * );
+     * ```
+     */
+    execute<T>(ctx: MiddlewareContext, handler: () => Promise<AdapterResponse<T>>): Promise<AdapterResponse<T>>;
+    /**
+     * Execute middleware using hook-style (before/after/onError).
+     */
+    private executeHookStyle;
+    /**
+     * Execute middleware using function-style (Koa-like compose).
+     */
+    private executeFunctionStyle;
+    /**
+     * Add middleware to the chain.
+     *
+     * @param middleware - Middleware to add
+     */
+    use(middleware: Middleware): this;
+    /**
+     * Remove middleware by name.
+     *
+     * @param name - Name of middleware to remove
+     */
+    remove(name: string): this;
+    /**
+     * Get middleware by name.
+     *
+     * @param name - Middleware name
+     * @returns The middleware or undefined
+     */
+    get(name: string): Middleware | undefined;
+    /**
+     * Get all middleware names.
+     *
+     * @returns Array of middleware names
+     */
+    names(): string[];
+    /**
+     * Get the middleware count.
+     */
+    get length(): number;
+}
+/**
+ * Create a middleware chain from an array of middleware.
+ *
+ * @param middlewares - Array of middleware
+ * @returns A configured MiddlewareChain
+ *
+ * @example
+ * ```typescript
+ * const chain = createMiddlewareChain([
+ *   createAuthMiddleware({ getToken: () => token }),
+ *   createLoggerMiddleware(),
+ * ]);
+ * ```
+ */
+declare function createMiddlewareChain(middlewares: Middleware[]): MiddlewareChain;
+
+/**
+ * Auth Middleware - Authentication token management
+ *
+ * Automatically attaches authentication tokens to requests
+ * and handles token refresh on 401 responses.
+ *
+ * @module middleware/auth
+ * @category Middleware
+ */
+
+/**
+ * Configuration options for auth middleware.
+ */
+interface AuthMiddlewareConfig {
+    /** Function to get the current auth token */
+    getToken: () => string | null | Promise<string | null>;
+    /** Function to refresh the token (optional) */
+    refreshToken?: () => Promise<string>;
+    /** Callback when user is unauthorized (optional) */
+    onUnauthorized?: () => void;
+    /** Header name for the token (default: 'Authorization') */
+    headerName?: string;
+    /** Token prefix (default: 'Bearer ') */
+    tokenPrefix?: string;
+    /** Whether to skip auth for certain operations */
+    skipOperations?: string[];
+}
+/**
+ * Create an authentication middleware.
+ *
+ * Attaches auth tokens to requests and handles 401 responses
+ * with optional token refresh.
+ *
+ * @param config - Auth middleware configuration
+ * @returns A configured Middleware instance
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware = createAuthMiddleware({
+ *   getToken: () => localStorage.getItem('token'),
+ *   refreshToken: async () => {
+ *     const response = await fetch('/auth/refresh');
+ *     const { token } = await response.json();
+ *     localStorage.setItem('token', token);
+ *     return token;
+ *   },
+ *   onUnauthorized: () => {
+ *     window.location.href = '/login';
+ *   },
+ * });
+ * ```
+ */
+declare function createAuthMiddleware(config: AuthMiddlewareConfig): Middleware;
+
+/**
+ * Retry Middleware - Automatic retry with exponential backoff
+ *
+ * Automatically retries failed requests with configurable
+ * retry count and exponential backoff delay.
+ *
+ * @module middleware/retry
+ * @category Middleware
+ */
+
+/**
+ * Configuration options for retry middleware.
+ */
+interface RetryMiddlewareConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay between retries in ms (default: 1000) */
+    retryDelay?: number;
+    /** Whether to use exponential backoff (default: true) */
+    exponentialBackoff?: boolean;
+    /** Maximum delay in ms (default: 30000) */
+    maxDelay?: number;
+    /** HTTP status codes that should trigger a retry */
+    retryableStatuses?: number[];
+    /** Custom function to determine if an error is retryable */
+    isRetryable?: (error: Error) => boolean;
+    /** Callback when a retry is attempted */
+    onRetry?: (attempt: number, error: Error, ctx: MiddlewareContext) => void;
+}
+/**
+ * Create a retry middleware with exponential backoff.
+ *
+ * @param config - Retry middleware configuration
+ * @returns A configured Middleware instance
+ *
+ * @example
+ * ```typescript
+ * const retryMiddleware = createRetryMiddleware({
+ *   maxRetries: 3,
+ *   retryDelay: 1000,
+ *   onRetry: (attempt, error) => {
+ *     console.log(`Retry attempt ${attempt}: ${error.message}`);
+ *   },
+ * });
+ * ```
+ */
+declare function createRetryMiddleware(config?: RetryMiddlewareConfig): Middleware;
+
+/**
+ * Cache Middleware - Response caching with TTL
+ *
+ * Caches successful responses to reduce API calls
+ * and improve performance.
+ *
+ * @module middleware/cache
+ * @category Middleware
+ */
+
+/**
+ * Configuration options for cache middleware.
+ */
+interface CacheMiddlewareConfig {
+    /** Time-to-live for cache entries in ms (default: 60000 = 1 minute) */
+    ttl?: number;
+    /** Operations to cache (default: ['findOne', 'findMany']) */
+    cacheOperations?: string[];
+    /** Maximum number of cached entries (default: 1000) */
+    maxSize?: number;
+    /** Custom cache key generator */
+    getCacheKey?: (ctx: MiddlewareContext) => string;
+    /** Whether to cache errors (default: false) */
+    cacheErrors?: boolean;
+    /** Storage backend (default: in-memory Map) */
+    storage?: CacheStorage;
+}
+/**
+ * Cache storage interface.
+ */
+interface CacheStorage {
+    get<T>(key: string): Promise<CacheEntry<T> | undefined>;
+    set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+/**
+ * Cache entry structure.
+ */
+interface CacheEntry<T> {
+    /** Cached response data */
+    data: AdapterResponse<T>;
+    /** Timestamp when cached */
+    timestamp: number;
+    /** TTL for this entry */
+    ttl: number;
+}
+/**
+ * Default in-memory cache storage.
+ */
+declare class MemoryCacheStorage implements CacheStorage {
+    private cache;
+    private maxSize;
+    constructor(maxSize?: number);
+    get<T>(key: string): Promise<CacheEntry<T> | undefined>;
+    set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+/**
+ * Create a cache middleware with TTL.
+ *
+ * @param config - Cache middleware configuration
+ * @returns A configured Middleware instance
+ *
+ * @example
+ * ```typescript
+ * const cacheMiddleware = createCacheMiddleware({
+ *   ttl: 60000, // 1 minute
+ *   cacheOperations: ['findOne', 'findMany'],
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom cache key
+ * const cacheMiddleware = createCacheMiddleware({
+ *   ttl: 300000, // 5 minutes
+ *   getCacheKey: (ctx) => `${ctx.entity}:${ctx.params?.id}:${ctx.filter?.status}`,
+ * });
+ * ```
+ */
+declare function createCacheMiddleware(config?: CacheMiddlewareConfig): Middleware;
+/**
+ * Create a utility to invalidate cache entries.
+ *
+ * @param storage - The cache storage to invalidate
+ * @returns Invalidation functions
+ *
+ * @example
+ * ```typescript
+ * const storage = new MemoryCacheStorage();
+ * const cache = createCacheInvalidator(storage);
+ *
+ * // Clear all cache
+ * await cache.clear();
+ *
+ * // Invalidate specific entry
+ * await cache.invalidate('findMany:user');
+ * ```
+ */
+declare function createCacheInvalidator(storage: CacheStorage): {
+    invalidate: (key: string) => Promise<void>;
+    clear: () => Promise<void>;
+    size: () => Promise<number>;
+};
+
+/**
+ * Logger Middleware - Request/response logging
+ *
+ * Logs request and response information for debugging
+ * and monitoring purposes.
+ *
+ * @module middleware/logger
+ * @category Middleware
+ */
+
+/**
+ * Log level type.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Configuration options for logger middleware.
+ */
+interface LoggerMiddlewareConfig {
+    /** Custom log function (default: console.log) */
+    log?: (message: string, data?: unknown) => void;
+    /** Whether to log requests (default: true) */
+    logRequest?: boolean;
+    /** Whether to log responses (default: true) */
+    logResponse?: boolean;
+    /** Whether to log errors (default: true) */
+    logErrors?: boolean;
+    /** Whether to log timing information (default: true) */
+    logTiming?: boolean;
+    /** Minimum log level (default: 'debug') */
+    level?: LogLevel;
+    /** Custom formatter for log messages */
+    formatter?: (type: 'request' | 'response' | 'error', ctx: MiddlewareContext, data?: unknown) => string;
+    /** Whether to include request data in logs (be careful with sensitive data) */
+    includeData?: boolean;
+    /** Fields to redact from logs */
+    redactFields?: string[];
+}
+/**
+ * Create a logger middleware.
+ *
+ * @param config - Logger middleware configuration
+ * @returns A configured Middleware instance
+ *
+ * @example
+ * ```typescript
+ * const loggerMiddleware = createLoggerMiddleware({
+ *   log: console.log,
+ *   logRequest: true,
+ *   logResponse: true,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom logger
+ * const loggerMiddleware = createLoggerMiddleware({
+ *   log: (msg, data) => winston.info(msg, data),
+ *   formatter: (type, ctx) => `[${type.toUpperCase()}] ${ctx.entity}.${ctx.operation}`,
+ * });
+ * ```
+ */
+declare function createLoggerMiddleware(config?: LoggerMiddlewareConfig): Middleware;
+/**
+ * Create a silent logger (logs nothing).
+ * Useful for testing.
+ */
+declare function createSilentLogger(): Middleware;
+/**
+ * Create a verbose logger (logs everything).
+ * Useful for debugging.
+ */
+declare function createVerboseLogger(): Middleware;
+
+/**
+ * Context Middleware - Extract execution context from headers
+ *
+ * Extracts user information, tenant IDs, and other context from
+ * request headers (Authorization, custom headers) and populates
+ * ctx.context for use by RLS and other middleware.
+ *
+ * @module middleware/context
+ * @category Middleware
+ */
+
+/**
+ * Configuration options for context middleware.
+ */
+interface ContextMiddlewareConfig {
+    /**
+     * Function to decode/validate token and extract user info.
+     * In production, this would validate the JWT signature.
+     *
+     * @param token - The JWT token (without 'Bearer ' prefix)
+     * @returns Decoded token payload or null if invalid
+     */
+    decodeToken?: (token: string) => Record<string, unknown> | null;
+    /**
+     * Additional headers to extract as context.
+     * Headers will be converted to camelCase context keys.
+     *
+     * @example ['X-Tenant-ID', 'X-Request-ID']
+     */
+    extractHeaders?: string[];
+    /**
+     * Mock mode: decode JWT without validation.
+     * In mock mode, the JWT payload is decoded without signature validation.
+     * This is useful for development/testing where tokens may be self-signed.
+     *
+     * @default true
+     */
+    mockMode?: boolean;
+    /**
+     * Header name for the Authorization token.
+     *
+     * @default 'Authorization'
+     */
+    authHeaderName?: string;
+    /**
+     * Token prefix to strip (e.g., 'Bearer ').
+     *
+     * @default 'Bearer '
+     */
+    tokenPrefix?: string;
+}
+/**
+ * Create a context middleware that extracts execution context from headers.
+ *
+ * This middleware:
+ * 1. Extracts JWT payload from Authorization header
+ * 2. Extracts additional values from custom headers
+ * 3. Populates ctx.context for use by RLS middleware
+ *
+ * @param config - Context middleware configuration
+ * @returns A configured Middleware instance
+ *
+ * @example
+ * ```typescript
+ * const contextMiddleware = createContextMiddleware({
+ *   mockMode: true, // Decode JWT without validation
+ *   extractHeaders: ['X-Tenant-ID', 'X-Request-ID'],
+ * });
+ *
+ * // With custom decoder
+ * const contextMiddleware = createContextMiddleware({
+ *   decodeToken: (token) => {
+ *     // Validate and decode the token
+ *     return jwt.verify(token, secret);
+ *   },
+ * });
+ * ```
+ */
+declare function createContextMiddleware(config?: ContextMiddlewareConfig): Middleware;
+/**
+ * Create a mock JWT token for testing.
+ * Encodes the payload as a JWT without signing.
+ *
+ * @param payload - The token payload
+ * @returns A mock JWT token string
+ *
+ * @example
+ * ```typescript
+ * const token = createMockJwt({
+ *   sub: 'user-123',
+ *   userId: 'user-123',
+ *   role: 'admin',
+ *   tenantId: 'tenant-456',
+ * });
+ *
+ * // Use in headers
+ * api._setHeaders({ Authorization: `Bearer ${token}` });
+ * ```
+ */
+declare function createMockJwt(payload: Record<string, unknown>): string;
+
+/**
+ * RLS Middleware - Row-Level Security enforcement in middleware chain
+ *
+ * Applies row-level security policies before and after storage operations.
+ * Works with ctx.context populated by the context middleware.
+ *
+ * @module middleware/rls-middleware
+ * @category Middleware
+ */
+
+/**
+ * RLS filter function type.
+ * Returns true if the row passes the security check.
+ */
+type RLSFilter = (row: Record<string, unknown>, ctx: Record<string, unknown> | null) => boolean;
+/**
+ * RLS filters for a single entity.
+ */
+interface RLSFilters {
+    /** Filter for SELECT/read operations */
+    select?: RLSFilter;
+    /** Filter for INSERT operations */
+    insert?: RLSFilter;
+    /** Filter for UPDATE operations */
+    update?: RLSFilter;
+    /** Filter for DELETE operations */
+    delete?: RLSFilter;
+}
+/**
+ * Configuration options for RLS middleware.
+ */
+interface RLSMiddlewareConfig {
+    /**
+     * Entity schemas with RLS configuration.
+     * Used for schema lookup during operations.
+     */
+    schemas: Map<string, EntitySchema>;
+    /**
+     * Function to get RLS filters for all entities.
+     * Typically returns generated RLS filter functions.
+     *
+     * @returns Map of entity names to RLS filters
+     */
+    getFilters: () => Record<string, RLSFilters>;
+    /**
+     * Enable debug logging.
+     *
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * RLS Error thrown when a security check fails.
+ */
+declare class RLSError extends Error {
+    /** Error code for programmatic handling */
+    readonly code = "RLS_DENIED";
+    /** The entity that was accessed */
+    readonly entity: string;
+    /** The operation that was attempted */
+    readonly operation: string;
+    constructor(operation: string, entity: string);
+}
+/**
+ * Create an RLS middleware that enforces row-level security.
+ *
+ * This middleware:
+ * 1. Pre-checks write operations (insert, update, delete) before execution
+ * 2. Post-filters read operations (select) after execution
+ * 3. Uses ctx.context populated by context middleware
+ *
+ * @param config - RLS middleware configuration
+ * @returns A configured Middleware instance
+ *
+ * @example
+ * ```typescript
+ * const rlsMiddleware = createRLSMiddleware({
+ *   schemas: schemaMap,
+ *   getFilters: () => ({
+ *     post: {
+ *       select: (row, ctx) => row.published || row.authorId === ctx?.userId,
+ *       insert: (row, ctx) => row.authorId === ctx?.userId,
+ *       update: (row, ctx) => row.authorId === ctx?.userId,
+ *       delete: (row, ctx) => row.authorId === ctx?.userId,
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+declare function createRLSMiddleware(config: RLSMiddlewareConfig): Middleware;
+/**
+ * Create a bypass check function from bypass conditions.
+ * Returns a function that checks if the context matches any bypass condition.
+ *
+ * @param bypassConditions - Array of { contextKey, values } conditions
+ * @returns A function that returns true if bypass should occur
+ *
+ * @example
+ * ```typescript
+ * const checkBypass = createBypassCheck([
+ *   { contextKey: 'role', values: ['admin', 'superuser'] },
+ * ]);
+ *
+ * checkBypass({ role: 'admin' }); // true
+ * checkBypass({ role: 'user' }); // false
+ * ```
+ */
+declare function createBypassCheck(bypassConditions: Array<{
+    contextKey: string;
+    values: string[];
+}>): (ctx: Record<string, unknown> | null) => boolean;
+
+/**
+ * Middleware Defaults - Default ordering and configuration
+ *
+ * Provides sensible defaults for middleware ordering and common
+ * middleware chain configurations.
+ *
+ * @module middleware/defaults
+ * @category Middleware
+ */
+
+/**
+ * Default middleware execution order.
+ *
+ * The order is designed for optimal security and performance:
+ * 1. auth - Add authentication token to headers (must be first)
+ * 2. logger - Log request start (early for timing)
+ * 3. context - Extract context from headers (after auth adds token)
+ * 4. rls - Apply row-level security (needs context)
+ * 5. retry - Handle retries (wraps actual request)
+ * 6. cache - Check cache (before hitting storage)
+ *
+ * After hooks execute in reverse order.
+ */
+declare const DEFAULT_MIDDLEWARE_ORDER: string[];
+/**
+ * Sort middleware array according to a specified order.
+ * Unknown middleware are placed at the end in their original order.
+ *
+ * @param middlewares - Array of middleware to sort
+ * @param customOrder - Optional custom order array (defaults to DEFAULT_MIDDLEWARE_ORDER)
+ * @returns Sorted middleware array
+ *
+ * @example
+ * ```typescript
+ * const sorted = orderMiddleware([
+ *   createCacheMiddleware(),
+ *   createAuthMiddleware(),
+ *   createLoggerMiddleware(),
+ * ]);
+ * // => [auth, logger, cache]
+ * ```
+ */
+declare function orderMiddleware(middlewares: Middleware[], customOrder?: string[]): Middleware[];
+/**
+ * Filter middleware by enabled/disabled state and names.
+ *
+ * @param middlewares - Array of middleware to filter
+ * @param enabled - Middleware names to enable (if empty, all are enabled)
+ * @param disabled - Middleware names to disable
+ * @returns Filtered middleware array
+ *
+ * @example
+ * ```typescript
+ * const filtered = filterMiddleware(
+ *   middlewares,
+ *   [], // Enable all
+ *   ['cache'] // But disable cache
+ * );
+ * ```
+ */
+declare function filterMiddleware(middlewares: Middleware[], enabled?: string[], disabled?: string[]): Middleware[];
+/**
+ * Middleware configuration preset for mock/development mode.
+ * Includes auth, context, and logger.
+ */
+declare const MOCK_MIDDLEWARE_PRESET: string[];
+/**
+ * Middleware configuration preset for production mode.
+ * Includes all middleware with caching and retries.
+ */
+declare const PRODUCTION_MIDDLEWARE_PRESET: string[];
+/**
+ * Middleware configuration preset for testing.
+ * Minimal middleware for fast test execution.
+ */
+declare const TEST_MIDDLEWARE_PRESET: string[];
+
+export { type AuthMiddlewareConfig, type CacheEntry, type CacheMiddlewareConfig, type CacheStorage, type ContextMiddlewareConfig, DEFAULT_MIDDLEWARE_ORDER, type LogLevel, type LoggerMiddlewareConfig, MOCK_MIDDLEWARE_PRESET, MemoryCacheStorage, Middleware, MiddlewareChain, MiddlewareContext, PRODUCTION_MIDDLEWARE_PRESET, RLSError, type RLSFilter, type RLSFilters, type RLSMiddlewareConfig, type RetryMiddlewareConfig, TEST_MIDDLEWARE_PRESET, createAuthMiddleware, createBypassCheck, createCacheInvalidator, createCacheMiddleware, createContextMiddleware, createLoggerMiddleware, createMiddlewareChain, createMockJwt, createRLSMiddleware, createRetryMiddleware, createSilentLogger, createVerboseLogger, filterMiddleware, orderMiddleware };