API Reference - @gograb-space/mock-api

Complete API reference for all types, interfaces, and functions in the mock-api library.

Core Types

MockRequest

interface MockRequest {
  /** HTTP method (GET, POST, PUT, DELETE, etc.) */
  method: string;

  /** Full request URL */
  url: string;

  /** URL path parameters (e.g., :id in /api/users/:id) */
  params: Record<string, string>;

  /** Query string parameters */
  query: Record<string, string>;

  /** Request body payload */
  body: any;

  /** Request headers */
  headers: Record<string, string>;

  /** Request timestamp (auto-generated) */
  timestamp?: number;

  /** Unique request ID (auto-generated) */
  requestId?: string;
}

MockResponse

interface MockResponse {
  /** HTTP status code */
  status: number;

  /** Response data/payload */
  data: any;

  /** Response headers */
  headers?: Record<string, string>;

  /** Custom delay in milliseconds */
  delay?: number;

  /** HTTP status text */
  statusText?: string;
}

MockHandler

type MockHandler = (
  req: MockRequest
) => MockResponse | Promise<MockResponse> | Observable<MockResponse>;

Handler function that processes a request and returns a response. Supports:

• Synchronous responses (MockResponse)
• Asynchronous responses (Promise<MockResponse>)
• Observable responses (Observable<MockResponse>)

MockDefinition

type MockDefinition = Record<string, MockHandler>;

Object mapping HTTP method + path patterns to handler functions:

const mocks: MockDefinition = {
  'GET /api/users': getUsersHandler,
  'POST /api/users': createUserHandler,
  'GET /api/users/:id': getUserHandler
};

Configuration Types

GlobalInterceptorConfig

interface GlobalInterceptorConfig {
  /** Enable/disable the interceptor */
  enabled: boolean;

  /** Base URL prefix for all requests */
  baseURL?: string;

  /** Global delay (ms) or range [min, max] */
  delay?: number | [number, number];

  /** Fall back to network if no mock matches */
  fallbackToNetwork?: boolean;

  /** Logging configuration */
  logging?: LoggingConfig;

  /** Persistence/caching configuration */
  persistence?: PersistenceConfig;

  /** Middleware stack */
  middleware?: MockMiddleware[];

  /** Default headers for all responses */
  defaultHeaders?: Record<string, string>;

  /** Preserve original request headers */
  preserveOriginalHeaders?: boolean;

  /** URL patterns to ignore */
  ignorePatterns?: (string | RegExp)[];

  /** URL patterns to include (whitelist) */
  includePatterns?: (string | RegExp)[];

  /** Route matching configuration */
  routeMatching?: RouteMatchingConfig;
}

LoggingConfig

interface LoggingConfig {
  /** Enable logging */
  enabled: boolean;

  /** Log level */
  level: 'debug' | 'info' | 'warn' | 'error';

  /** Log incoming requests */
  logRequests?: boolean;

  /** Log outgoing responses */
  logResponses?: boolean;

  /** Log route matching process */
  logRouteMatching?: boolean;

  /** Log cache operations */
  logCacheOperations?: boolean;
}

PersistenceConfig

interface PersistenceConfig {
  /** Enable response caching */
  enabled: boolean;

  /** Cache TTL in milliseconds */
  ttl?: number;

  /** Storage adapter type */
  storage?: 'indexeddb' | 'localstorage' | 'memory' | 'intelligent';

  /** Database name (for IndexedDB) */
  dbName?: string;

  /** Database version (for IndexedDB) */
  dbVersion?: number;

  /** Store name (for IndexedDB) */
  storeName?: string;

  /** Maximum cache entries */
  maxCacheSize?: number;

  /** Auto cleanup expired entries */
  autoCleanup?: boolean;

  /** Namespace for intelligent storage */
  namespace?: string;
}

RouteMatchingConfig

interface RouteMatchingConfig {
  /** Case-sensitive matching */
  caseSensitive?: boolean;

  /** Exact URL matching */
  exactMatch?: boolean;

  /** URL prefix to strip before matching */
  stripPrefix?: string;

  /** Normalize URLs (remove trailing slashes, etc.) */
  normalizeURLs?: boolean;

  /** Parameter prefix character (default: ':') */
  parameterPrefix?: string;

  /** Support wildcard patterns */
  supportWildcards?: boolean;
}

Middleware Types

MockMiddleware

interface MockMiddleware {
  /** Middleware name */
  name: string;

  /** Execution priority (higher = earlier) */
  priority: number;

  /** Process request before handling */
  onRequest?: (request: MockRequest) => MockRequest | Promise<MockRequest>;

  /** Process response after handling */
  onResponse?: (
    response: MockResponse,
    request: MockRequest
  ) => MockResponse | Promise<MockResponse>;

  /** Handle errors */
  onError?: (
    error: Error,
    request: MockRequest
  ) => MockResponse | Promise<MockResponse>;
}

Services

MockInterceptorUtilsService

Injectable service for managing the mock interceptor at runtime.

Methods

class MockInterceptorUtilsService {
  /**
   * Configure the mock interceptor
   */
  configureMockInterceptor(
    config: GlobalInterceptorConfig,
    mocks: MockDefinition
  ): void;

  /**
   * Update mock definitions at runtime
   */
  updateMocks(mocks: MockDefinition): void;

  /**
   * Add new mock definitions
   */
  addMocks(mocks: MockDefinition): void;

  /**
   * Remove specific mock routes
   */
  removeMocks(routes: string[]): void;

  /**
   * Clear all mock definitions
   */
  clearMocks(): void;

  /**
   * Enable/disable interceptor
   */
  setEnabled(enabled: boolean): void;

  /**
   * Check if interceptor is enabled
   */
  isEnabled(): boolean;

  /**
   * Get usage statistics
   */
  getStats(): MockUsageStats;

  /**
   * Reset statistics
   */
  resetStats(): void;

  /**
   * Get current configuration
   */
  getConfig(): GlobalInterceptorConfig;

  /**
   * Update configuration
   */
  updateConfig(config: Partial<GlobalInterceptorConfig>): void;
}

MockInterceptorConfig

Injectable configuration service.

class MockInterceptorConfig {
  /**
   * Set global enabled state
   */
  setEnabled(enabled: boolean): void;

  /**
   * Get current enabled state
   */
  getEnabled(): boolean;

  /**
   * Set global delay
   */
  setDelay(delay: number | [number, number]): void;

  /**
   * Get current delay setting
   */
  getDelay(): number | [number, number];

  /**
   * Set fallback to network
   */
  setFallbackToNetwork(fallback: boolean): void;

  /**
   * Get fallback setting
   */
  getFallbackToNetwork(): boolean;
}

Utility Classes

DataGenerator

Singleton class for generating mock data.

class DataGenerator {
  /**
   * Get singleton instance
   */
  static getInstance(): DataGenerator;

  /**
   * Generate a mock user
   */
  generateUser(overrides?: Partial<User>): User;

  /**
   * Generate a mock product
   */
  generateProduct(overrides?: Partial<Product>): Product;

  /**
   * Generate a mock address
   */
  generateAddress(overrides?: Partial<Address>): Address;

  /**
   * Generate a phone number
   */
  generatePhone(): string;

  /**
   * Generate an array of items
   */
  generateArray<T>(generator: () => T, count: number): T[];

  /**
   * Generate random integer
   */
  generateInt(min: number, max: number): number;

  /**
   * Generate random string
   */
  generateString(length: number, charset?: string): string;

  /**
   * Generate random date
   */
  generateDate(start?: Date, end?: Date): Date;

  /**
   * Generate random boolean
   */
  generateBoolean(probability?: number): boolean;

  /**
   * Pick random item from array
   */
  pickRandom<T>(array: T[]): T;
}

RouteMatcher

URL pattern matching utility.

class RouteMatcher {
  constructor(config?: RouteMatchingConfig);

  /**
   * Check if URL matches pattern
   */
  match(
    pattern: string,
    url: string,
    method: string
  ): RouteMatchResult;

  /**
   * Extract parameters from URL
   */
  extractParams(pattern: string, url: string): Record<string, string>;

  /**
   * Normalize URL
   */
  normalizeUrl(url: string): string;
}

interface RouteMatchResult {
  /** Whether pattern matches URL */
  matches: boolean;

  /** Extracted parameters */
  params: Record<string, string>;

  /** Match score (higher = better match) */
  score: number;
}

MockValidator

Validation utility for mock definitions.

class MockValidator {
  /**
   * Validate mock definitions
   */
  static validateMockDefinitions(
    mocks: MockDefinition
  ): ValidationResult;

  /**
   * Validate single mock handler
   */
  static validateMockHandler(
    route: string,
    handler: MockHandler
  ): ValidationResult;

  /**
   * Validate route pattern
   */
  static validateRoutePattern(pattern: string): ValidationResult;
}

interface ValidationResult {
  /** Whether validation passed */
  isValid: boolean;

  /** Validation errors */
  errors: ValidationError[];

  /** Validation warnings */
  warnings: ValidationError[];
}

interface ValidationError {
  /** Error message */
  message: string;

  /** Error code */
  code: string;

  /** Route that caused error */
  route?: string;

  /** Error severity */
  severity: 'error' | 'warning';
}

MiddlewareFactory

Factory for creating common middleware.

class MiddlewareFactory {
  /**
   * Create logging middleware
   */
  static createLoggingMiddleware(
    options?: LoggingMiddlewareOptions
  ): MockMiddleware;

  /**
   * Create CORS middleware
   */
  static createCorsMiddleware(
    options?: CorsMiddlewareOptions
  ): MockMiddleware;

  /**
   * Create delay middleware
   */
  static createDelayMiddleware(
    delay: number | [number, number]
  ): MockMiddleware;

  /**
   * Create authentication middleware
   */
  static createAuthMiddleware(
    options?: AuthMiddlewareOptions
  ): MockMiddleware;

  /**
   * Create rate limiting middleware
   */
  static createRateLimitMiddleware(
    options?: RateLimitOptions
  ): MockMiddleware;
}

Statistics Types

MockUsageStats

interface MockUsageStats {
  /** Total requests processed */
  totalRequests: number;

  /** Requests by route pattern */
  requestsByRoute: Record<string, number>;

  /** Requests by HTTP method */
  requestsByMethod: Record<string, number>;

  /** Average response time (ms) */
  averageResponseTime: number;

  /** Requests that didn't match any mock */
  unmatchedRequests: number;

  /** Last statistics reset timestamp */
  lastReset: number;

  /** Cache hit rate (if persistence enabled) */
  cacheHitRate?: number;

  /** Most requested routes */
  topRoutes: Array<{
    route: string;
    count: number;
    averageTime: number;
  }>;
}

RouteMatchInfo

interface RouteMatchInfo {
  /** Whether route matched */
  matched: boolean;

  /** Route pattern that matched */
  matchedRoute?: string;

  /** Parameters extracted from URL */
  extractedParams?: Record<string, string>;

  /** Processing time for match */
  processingTime?: number;

  /** Match score */
  score?: number;
}

Constants

HTTP Status Codes

export const HttpStatus = {
  OK: 200,
  CREATED: 201,
  NO_CONTENT: 204,
  BAD_REQUEST: 400,
  UNAUTHORIZED: 401,
  FORBIDDEN: 403,
  NOT_FOUND: 404,
  CONFLICT: 409,
  INTERNAL_SERVER_ERROR: 500
} as const;

Default Configuration Values

export const DefaultConfig: Required<GlobalInterceptorConfig> = {
  enabled: true,
  baseURL: '',
  delay: 0,
  fallbackToNetwork: true,
  logging: {
    enabled: false,
    level: 'info',
    logRequests: false,
    logResponses: false,
    logRouteMatching: false,
    logCacheOperations: false
  },
  persistence: {
    enabled: false,
    ttl: 300000,
    storage: 'memory',
    maxCacheSize: 100,
    autoCleanup: true
  },
  middleware: [],
  defaultHeaders: {
    'Content-Type': 'application/json'
  },
  preserveOriginalHeaders: true,
  ignorePatterns: [],
  includePatterns: [],
  routeMatching: {
    caseSensitive: false,
    exactMatch: false,
    normalizeURLs: true,
    parameterPrefix: ':',
    supportWildcards: true
  }
};

Error Types

MockInterceptorError

class MockInterceptorError extends Error {
  constructor(
    message: string,
    public code: string,
    public route?: string,
    public request?: MockRequest
  );
}

Common error codes:

• INVALID_MOCK_DEFINITION - Mock definition validation failed
• ROUTE_MATCH_FAILED - No route matched the request
• HANDLER_EXECUTION_ERROR - Mock handler threw an error
• MIDDLEWARE_ERROR - Middleware execution failed
• PERSISTENCE_ERROR - Cache/storage operation failed