API Packages@mockmaster/core

@mockmaster/core

Path matching & HTTP routing engine

npm install @mockmaster/core

Overview

The core package provides low-level path matching and HTTP routing utilities. It’s the foundation for MockMaster’s request matching system.

Key Features:

  • Exact path matching
  • Path parameters (e.g., /users/:id)
  • Wildcard matching (e.g., /api/*)
  • Parameter extraction
  • Reusable matchers for performance

API Reference

matchPath(pattern, path)

Match a path against a pattern.

import { matchPath } from '@mockmaster/core'
 
matchPath('/users', '/users')              // true
matchPath('/users/:id', '/users/123')      // true
matchPath('/api/*', '/api/anything')       // true

Parameters:

  • pattern (string) - Pattern to match against
  • path (string) - Path to test

Returns: boolean - True if path matches pattern

extractParams(pattern, path)

Extract parameter values from a path.

import { extractParams } from '@mockmaster/core'
 
const params = extractParams('/users/:id', '/users/123')
// { id: '123' }
 
const params2 = extractParams(
  '/users/:userId/posts/:postId',
  '/users/1/posts/42'
)
// { userId: '1', postId: '42' }

Parameters:

  • pattern (string) - Pattern with parameters
  • path (string) - Path to extract from

Returns: Record<string, string> - Object with parameter values

createMatcher(patterns)

Create a reusable matcher for multiple patterns.

import { createMatcher } from '@mockmaster/core'
 
const matcher = createMatcher([
  '/users',
  '/users/:id',
  '/posts',
  '/api/*'
])
 
matcher('/users')        // { matched: true, pattern: '/users' }
matcher('/users/123')    // { matched: true, pattern: '/users/:id' }
matcher('/unknown')      // { matched: false }

Parameters:

  • patterns (string[]) - Array of patterns

Returns: Matcher - Function that matches paths

Usage Examples

Basic Routing

import { matchPath } from '@mockmaster/core'
 
function handleRequest(method: string, path: string) {
  if (method === 'GET' && matchPath('/users', path)) {
    return { status: 200, body: [] }
  }
 
  if (method === 'GET' && matchPath('/users/:id', path)) {
    const { id } = extractParams('/users/:id', path)
    return { status: 200, body: { id, name: 'User' } }
  }
 
  return { status: 404, body: { error: 'Not found' } }
}

Parameter Extraction

import { matchPath, extractParams } from '@mockmaster/core'
 
function getUserById(path: string) {
  if (matchPath('/users/:id', path)) {
    const { id } = extractParams('/users/:id', path)
    return fetchUser(parseInt(id, 10))
  }
  return null
}

Wildcard Routing

import { matchPath } from '@mockmaster/core'
 
function isApiRoute(path: string): boolean {
  return matchPath('/api/*', path)
}
 
function isStaticFile(path: string): boolean {
  return matchPath('/static/*', path)
}

Performance with Matchers

import { createMatcher } from '@mockmaster/core'
 
const apiMatcher = createMatcher([
  '/api/users',
  '/api/users/:id',
  '/api/posts',
  '/api/posts/:id'
])
 
// Fast matching (reuses compiled patterns)
apiMatcher('/api/users')        // { matched: true, pattern: '/api/users' }
apiMatcher('/api/users/123')    // { matched: true, pattern: '/api/users/:id' }

Pattern Syntax

Exact Paths

matchPath('/users', '/users')              // true
matchPath('/users', '/users/')             // false
matchPath('/api/v1/users', '/api/v1/users')  // true

Parameters

matchPath('/users/:id', '/users/123')      // true
matchPath('/users/:id', '/users/abc')      // true
 
// Multiple parameters
matchPath('/users/:userId/posts/:postId', '/users/1/posts/42')  // true

Wildcards

matchPath('/api/*', '/api/users')          // true
matchPath('/api/*', '/api/users/123')      // true
matchPath('/api/*', '/api/v1/posts')       // true
 
// At different positions
matchPath('/files/*/download', '/files/doc.pdf/download')  // true

Combining Patterns

matchPath('/users/:id/*', '/users/123/posts')          // true
matchPath('/api/:version/*', '/api/v1/users')          // true

TypeScript Types

import type {
  MatchFunction,
  Matcher,
  MatchResult,
  PathParams
} from '@mockmaster/core'
 
// Match function signature
type MatchFunction = (pattern: string, path: string) => boolean
 
// Matcher result
interface MatchResult {
  matched: boolean
  pattern?: string
}
 
// Path parameters
type PathParams = Record<string, string>

Best Practices

1. Use Specific Patterns

// Good - specific
matchPath('/users/:id', path)
 
// Avoid - too broad
matchPath('/*', path)

2. Reuse Matchers

// Good - create once, use many times
const matcher = createMatcher(patterns)
matcher(path1)
matcher(path2)
matcher(path3)
 
// Avoid - recreating every time
patterns.forEach(p => matchPath(p, path))

3. Validate Parameters

const params = extractParams('/users/:id', path)
if (params.id) {
  const userId = parseInt(params.id, 10)
  if (!isNaN(userId)) {
    // Valid ID
  }
}

Related Documentation

Overview@mockmaster/data