url-ast

💡 About

High-performance typed URL parser with automatic type casting and AST-based analysis.

url-ast is a specialized module for analyzing and manipulating URLs using an Abstract Syntax Tree (AST) approach. It provides deep and structured URL analysis, transforming URLs into interconnected nodes that represent each component (protocol, hostname, parameters, etc.), facilitating manipulation and validation with full TypeScript support and automatic type casting.

📖 Full Documentation

🚀 Key Features

• AST-Based Analysis: Deep URL structure analysis through interconnected nodes for precise parsing
• Automatic Type Casting: Built-in support for number, boolean, string, array, and enum type conversion
• Full TypeScript Support: Complete type inference for parameters and values with compile-time safety
• Pattern Matching: Advanced support for route patterns with dynamic, optional, and catch-all parameters
• High Performance: Optimized parser with efficient buffer handling and minimal overhead
• UTF-8 Decoding: Robust support for special characters and encoded URLs
• Visual Debugging: Colored visualization of URL structure for easy debugging and analysis
• Zero Dependencies: Lightweight implementation with no external dependencies

📦 Installation

You can install url-ast using your preferred package manager:

bun add url-ast

(Works with npm, yarn, or pnpm as well)

🛣️ Supported Routing Patterns

| Pattern | Syntax | URL Example | Description | | :--- | :--- | :--- | :--- | | Static | /exact/path | /about/contact | Requires exact match. No variables captured. | | Dynamic (colon) | /:param | /users/:id | Captures a single URL segment. | | Dynamic (bracket) | /[param] | /posts/[slug] | Bracket syntax, Next.js/SvelteKit style. | | Dynamic with type | /:param.type or /[param.type] | /users/:id.number | Captures and converts the type automatically. | | Optional | /:~param or /[~param] | /posts/:id/comments/:~commentId | Parameter can be undefined. | | Catch-all | /[...slug] | /docs/[...path] | Captures multiple segments as string[]. | | Optional catch-all | /[[...slug]] | /blog/[[...slug]] | Base route remains valid without parameters. | | Query params | ?param | ?sort=desc&limit=10 | Captures query string arguments. | | Query with type | ?param.type | ?page.number&active.boolean | Query params with type casting. | | Query with default | ?param.type=value | ?page.number=1 | Query with type and default value. | | Fragment (hash) | #section | #introduction | Captures the anchor at the end of the URL. |

🎯 Type Casting

| Type | Syntax | Description | Input → Output | | :--- | :--- | :--- | :--- | | String | .string (or omitted) | Default behavior. Preserves the text. | user_123 → 'user_123' | | Number | .number | Converts to a numeric value. | -42 → -42 | | Boolean | .boolean | Analyzes intent and converts to boolean. | true or 1 → true | | Array | .array | Splits values by comma into a list. | a,b,c → ['a', 'b', 'c'] | | Enum | .enum[op1,op2] | Restricts values to an allowed list. | admin → 'admin' | | Generic enum | .enum | Enum without variant restriction. | anything → 'anything' |

🏁 Quick Start

import { Analyze } from 'url-ast'

const template = new Analyze('/users/:id.number')
const parsed = new Analyze('/users/42', template)

parsed.getParams()        // { id: 42 }

For more examples, check the examples directory or the full documentation.

🤝 Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue. If you want to contribute code, please open a pull request.

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.