Simple Serializer

A TypeScript library for URL query parameter serialization with a pluggable serializer architecture.

Installation

bun add @petite-org/simple-serialyzer

Quick Start

Use the pre-configured default serializer:

import { defaultQueryParamSerializer } from '@petite-org/simple-serialyzer';

const url = defaultQueryParamSerializer.serialize({
    name: "Hello",
    count: 42,
    active: true,
    tags: ["a", "b"],
    date: new Date(),
});
// -> ?name=Hello&count=42&active=true&tags=a&tags=b&date=03-12-2025

Custom Configuration

Create your own serializer with specific handlers:

import {
    QueryParamSerializer,
    PrimitiveSerializer,
    BooleanSerializer,
    DateSerializer,
    PrimitiveArraySerializer,
} from '@petite-org/simple-serialyzer';

const querySerializer = new QueryParamSerializer([
    new PrimitiveSerializer(),
    new BooleanSerializer(),
    new DateSerializer(),
    new PrimitiveArraySerializer(),
]);

const url = querySerializer.serialize({
    test: "Hello",
    arr: [1, 2, 3],
});
// -> ?test=Hello&arr=1&arr=2&arr=3

Creating Custom Serializers

Implement the ValueSerializer interface to handle custom types:

import { ValueSerializer, KeyValuePair } from '@petite-org/simple-serialyzer';

class User {
    constructor(public id: number, public name: string) {}
}

class UserSerializer implements ValueSerializer<User> {
    canSerialize(value: unknown): value is User {
        return value instanceof User;
    }

    serialize(value: User, key: string): KeyValuePair[] {
        return [{ key, value: encodeURIComponent(`${value.id}:${value.name}`) }];
    }
}

// Add to your serializer chain
const querySerializer = new QueryParamSerializer([
    new UserSerializer(),
    new PrimitiveSerializer(),
    // ... other serializers
]);

Built-in Serializers

| Serializer | Handles | Output | |------------|---------|--------| | PrimitiveSerializer | strings, numbers | URI-encoded value | | BooleanSerializer | booleans | "true" or "false" | | DateSerializer | valid Date objects | DD-MM-YYYY format | | PrimitiveArraySerializer | (string | number)[] | Multiple pairs: key=1&key=2 | | EmptySerializer | null, undefined | Skipped (empty array) |

API

QueryParamSerializer.serialize(params, first?)

• params: Object with values to serialize
• first: If true (default), prepends ?; if false, prepends &

Returns the serialized query string.

Throws:

• TypeError if params is not an object
• MissingRenderer if no serializer can handle a value (including invalid dates)

ValueSerializer<T> Interface

interface ValueSerializer<T> {
    canSerialize(value: unknown): value is T;
    serialize(value: T, key: string): KeyValuePair[];
}

type KeyValuePair = { key: string; value: string };

License

ISC