PathCat 🐾

PathCat is a powerful and flexible URL building library for .NET, inspired by the popular JavaScript library pathcat. It provides an intuitive way to construct URLs with dynamic parameters, offering extensive configuration options to suit various serialization needs.

Features

Simple and expressive API for URL construction
Support for path placeholders and query parameters
Flexible parameter handling (dictionaries, anonymous objects, strongly-typed classes)
Customizable serialization formats for various data types
Efficient string manipulation using Span<T> and ReadOnlySpan<T>

Installation

Install PathCat via NuGet:

dotnet add package PathCat

Quick Start

using PathCat;

// Basic usage
string url = PathCat.BuildUrl("/users/:id", new { id = 123, filter = "active" });
// Result: "/users/123?filter=active"

// With nested objects
string url = PathCat.BuildUrl("/api/:version/resource/:id", new
{
    version = "v2",
    id = 789,
    options = new { sort = "asc", limit = 10 }
});
// Result: "/api/v2/resource/789?options.sort=asc&options.limit=10"

Advanced Usage

Configuration Options

PathCat offers various configuration options to customize its behavior:

var config = new PathCatConfig
{
    BooleanSerializationFormat = PathCatConfig.BooleanFormat.LowerCase,
    ArraySerializationFormat = PathCatConfig.ArrayFormat.Indexed,
    PropertyNameSerializationFormat = PathCatConfig.PropertyNameFormat.CamelCase,
    ObjectAccessorSerializationFormat = PathCatConfig.ObjectAccessorFormat.IndexBrackets,
    ArrayDelimiter = '|'
};

string url = PathCat.BuildUrl("/api", parameters, config);

Boolean Serialization

Default: Uses .NET's default boolean representation
LowerCase: Uses "true" or "false"
Numeric: Uses "1" or "0"
OnOff: Uses "on" or "off"

Array Serialization

Default: Repeats the key for each array element
Indexed: Uses indexed notation (e.g., items[0]=value)
Delimited: Joins array elements with a specified delimiter

Property Name Serialization

Default: Uses the original property names
CamelCase: Converts property names to camelCase
SnakeCase: Converts property names to snake_case

Object Accessor Serialization

DotNotation: Uses dot notation for nested objects
IndexBrackets: Uses bracket notation for nested objects
OmitParent: Flattens nested object structure

Examples

Using different boolean formats:

var config = new PathCatConfig
{
    BooleanSerializationFormat = PathCatConfig.BooleanFormat.Numeric
};
string url = PathCat.BuildUrl("/api", new { enabled = true }, config);
// Result: "/api?enabled=1"

Customizing array serialization:

var config = new PathCatConfig
{
    ArraySerializationFormat = PathCatConfig.ArrayFormat.Delimited,
    ArrayDelimiter = '|'
};
string url = PathCat.BuildUrl("/api", new { tags = new[] { "urgent", "important" } }, config);
// Result: "/api?tags=urgent|important"

Using different property name formats:

var config = new PathCatConfig
{
    PropertyNameSerializationFormat = PathCatConfig.PropertyNameFormat.SnakeCase
};
string url = PathCat.BuildUrl("/api", new { FirstName = "John", LastName = "Doe" }, config);
// Result: "/api?first_name=John&last_name=Doe"

Customizing object accessor format:

var config = new PathCatConfig
{
    ObjectAccessorSerializationFormat = PathCatConfig.ObjectAccessorFormat.IndexBrackets
};
string url = PathCat.BuildUrl("/api", new { user = new { name = "Alice", age = 30 } }, config);
// Result: "/api?user[name]=Alice&user[age]=30"

System.Text.Json Integration

PathCat now supports System.Text.Json serialization settings for property names. This feature allows you to leverage existing System.Text.Json configurations in your URL building process.

To use this feature:

var config = new PathCatConfig
{
    UseSystemTextJsonSerialization = true,
    SystemTextJsonOptions = new JsonSerializerOptions
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
        Converters = { new JsonStringEnumConverter() }
    }
};

var parameters = new
{
    UserName = "JohnDoe",
    IsActive = true,
    LastLoginDate = DateTime.Now,
    UserType = UserType.Admin
};

string url = PathCat.BuildUrl("/api/users", parameters, config);
// Result: "/api/users?userName=JohnDoe&isActive=true&lastLoginDate=2023-05-15T10:30:00&userType=Admin"

Performance

PathCat is designed with performance in mind, utilizing Span<T> and ReadOnlySpan<T> for efficient string manipulation. It employs a pre-allocated buffer to minimize memory allocations during URL construction.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

PathCat is a partial port of and inspired by the pathcat JavaScript library. While maintaining the core concepts, it has been adapted and enhanced for the .NET ecosystem.

zettersten / pathcat Goto Github PK

pathcat's Introduction