Pica Route

A pure TypeScript URL pattern matching library compatible with the route-parser API.

Features

• Multiple formats - ESM, CommonJS, and IIFE builds available
• Pure TypeScript - No dependencies, fully typed
• Compatible API - Drop-in replacement for route-parser
• Comprehensive pattern matching - Supports parameters, splats, optional groups, and query parameters
• Reversible routes - Generate URLs from parameters
• Parser-based implementation - Clean and maintainable code
• Thoroughly tested - Comprehensive Jest test suite

Installation

npm install pica-route

Usage

ESM (ES Modules)

import { Route } from 'pica-route';

const route = new Route('/users/:id');

// Match URLs
route.match('/users/123'); // { id: '123' }
route.match('/users/john'); // { id: 'john' }

// Reverse generation
route.reverse({ id: 456 }); // '/users/456'

CommonJS

const { Route } = require('pica-route');

const route = new Route('/users/:id');
const result = route.match('/users/123'); // { id: '123' }

IIFE (Browser)

<script src="https://unpkg.com/pica-route/dist/index.iife.min.js"></script>
<script>
  const { Route } = PicaRoute;
  const route = new Route('/api/:version');
  console.log(route.match('/api/v1')); // { version: 'v1' }
</script>

Route Syntax

Parameters

• :name - Captures a parameter up to /, ?, or end of string

const route = new Route('/users/:id/comments/:comment');
route.match('/users/123/comments/456'); // { id: 123, comment: 456 }

Splats

• *name - Captures everything up to ? or end of string

const route = new Route('/files/*path');
route.match('/files/documents/readme.txt'); // { path: 'documents/readme.txt' }

Optional Groups

• () - Optional sections that can contain parameters, splats, or nested optional groups

const route = new Route('/api/users(/:id)(/:action)');
route.match('/api/users'); // {}
route.match('/api/users/123'); // { id: 123 }
route.match('/api/users/123/edit'); // { id: 123, action: 'edit' }

Query Parameters

Query parameters work with the same syntax as path parameters.

const route = new Route('/books?author=:author&subject=:subject');
route.match('/books?author=tolkien&subject=fantasy');
// { author: 'tolkien', subject: 'fantasy' }

API

Constructor

new Route(pattern: string)

Creates a new route instance from a pattern string.

match(url: string)

match(url: string): RouteParams | false

Attempts to match a URL against the route pattern. Returns an object with captured parameters or false if no match.

reverse(params: RouteParams)

reverse(params?: RouteParams): string

Generates a URL from the route pattern using the provided parameters.

Examples

Basic Usage

const route = new Route('/users/:id/comments/:comment/rating/:rating');

route.match('/users/123/comments/456/rating/5');
// { id: 123, comment: 456, rating: 5 }

route.reverse({ id: 123, comment: 456, rating: 5 });
// '/users/123/comments/456/rating/5'

Splat Routes

const route = new Route('/books/*section/:title');

route.match('/books/programming/javascript/learning-js');
// { section: 'programming/javascript', title: 'learning-js' }

Optional Groups

const route = new Route('/some/(optional/):thing');

route.match('/some/optional/value'); // { thing: 'value' }
route.match('/some/value');          // { thing: 'value' }

Query Parameters

const route = new Route('/search?q=:query');

route.match('/search?q=javascript'); // { query: 'javascript' }

TypeScript Support

Full TypeScript support with proper type definitions:

interface RouteParams {
  [key: string]: string | number;
}

class Route {
  match(url: string): RouteParams | false;
  reverse(params?: RouteParams): string;
}

Testing

npm test

Building

npm run build

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build the project
npm run build

# Development build with watch
npm run dev

Release

This project uses semantic-release for automated versioning and publishing.

# Dry run to see what would be released
npm run release:dry

# Create a release (requires proper git setup and npm auth)
npm run release

Commit Message Format

Follow the Conventional Commits specification:

• feat: - new features (minor version bump)
• fix: - bug fixes (patch version bump)
• refactor: - code refactoring (minor version bump)
• perf: - performance improvements (patch version bump)
• docs: - documentation changes (patch version bump)
• chore(deps): - dependency updates (patch version bump)
• BREAKING CHANGE: - breaking changes (major version bump)

License

MIT