# Parser

A type lambda from a string literal to a parse result.

## Signatures

```ts
export interface Parser<Output = unknown> extends TypeFunction<string, Result<Output, string>> {
}
```

```ts
export declare namespace Parser {
    type Any = Parser<unknown>;
    type Run<P extends Any, Input extends string> = Apply<P, Input>;
    interface Succeed<A> extends TypeFunction<string, Result<A, string>> {
        readonly return: InputOf<this> extends infer Input extends string ? readonly [
            A,
            Input
        ] : never;
    }
    interface Fail extends TypeFunction<string, never> {
        readonly return: never;
    }
    interface Char<C extends string> extends TypeFunction<string, Result<C, string>> {
        readonly return: InputOf<this> extends `${C}${infer Rest}` ? readonly [
            C,
            Rest
        ] : never;
    }
    interface String<S extends string> extends TypeFunction<string, Result<S, string>> {
        readonly return: InputOf<this> extends `${S}${infer Rest}` ? readonly [
            S,
            Rest
        ] : never;
    }
    type LowercaseAlphabet = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
    type UppercaseAlphabet = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z";
    type Alphabet = LowercaseAlphabet | UppercaseAlphabet;
    type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
    type AlphaNumeric = Alphabet | Digit;
    type TakeWhileInternal<Input extends string, Allowed extends string, Acc extends string = ""> = Input extends `${infer Head}${infer Tail}` ? Head extends Allowed ? TakeWhileInternal<Tail, Allowed, `${Acc}${Head}`> : readonly [
        Acc,
        Input
    ] : readonly [
        Acc,
        Input
    ];
    type TakeWhile1Internal<Input extends string, Allowed extends string> = TakeWhileInternal<Input, Allowed> extends readonly [
        infer Taken extends string,
        infer Rest extends string
    ] ? Taken extends "" ? never : readonly [
        Taken,
        Rest
    ] : never;
    interface TakeWhile<Allowed extends string> extends TypeFunction<string, Result<string, string>> {
        readonly return: InputOf<this> extends infer Input extends string ? TakeWhileInternal<Input, Allowed> : never;
    }
    interface TakeWhile1<Allowed extends string> extends TypeFunction<string, Result<string, string>> {
        readonly return: InputOf<this> extends infer Input extends string ? TakeWhile1Internal<Input, Allowed> : never;
    }
    interface Map<P extends Any, F extends TypeFunction> extends Parser<unknown> {
        readonly return: InputOf<this> extends infer Input extends string ? Apply<P, Input> extends infer R ? [
            R
        ] extends [
            never
        ] ? never : R extends readonly [
            infer Value,
            infer Rest extends string
        ] ? readonly [
            Pipe<Value, F>,
            Rest
        ] : never : never : never;
    }
    interface FlatMap<P extends Any, F extends TypeFunction> extends Parser<unknown> {
        readonly return: InputOf<this> extends infer Input extends string ? Apply<P, Input> extends infer R ? [
            R
        ] extends [
            never
        ] ? never : R extends readonly [
            infer Value,
            infer Rest extends string
        ] ? Pipe<Value, F> extends infer Next ? [
            Next
        ] extends [
            never
        ] ? never : Next extends Any ? Pipe<Rest, Next> : never : never : never : never : never;
    }
    interface Zip<P extends Any, Q extends Any> extends Parser<unknown> {
        readonly return: InputOf<this> extends infer Input extends string ? Apply<P, Input> extends infer R1 ? [
            R1
        ] extends [
            never
        ] ? never : R1 extends readonly [
            infer Value1,
            infer Rest1 extends string
        ] ? Pipe<Rest1, Q> extends infer R2 ? [
            R2
        ] extends [
            never
        ] ? never : R2 extends readonly [
            infer Value2,
            infer Rest2 extends string
        ] ? readonly [
            readonly [
                Value1,
                Value2
            ],
            Rest2
        ] : never : never : never : never : never;
    }
    interface OrElse<P extends Any, Q extends Any> extends Parser<unknown> {
        readonly return: InputOf<this> extends infer Input extends string ? Apply<P, Input> extends infer R ? [
            R
        ] extends [
            never
        ] ? Pipe<Input, Q> : R extends readonly [
            infer Value,
            infer Rest extends string
        ] ? readonly [
            Value,
            Rest
        ] : never : never : never;
    }
    interface Optional<P extends Any> extends Parser<unknown> {
        readonly return: InputOf<this> extends infer Input extends string ? Apply<P, Input> extends infer R ? [
            R
        ] extends [
            never
        ] ? readonly [
            undefined,
            Input
        ] : R extends readonly [
            infer Value,
            infer Rest extends string
        ] ? readonly [
            Value,
            Rest
        ] : never : never : never;
    }
    type ManyInternal<P extends Any, Input extends string, Acc extends ReadonlyArray<unknown> = readonly [
    ]> = Apply<P, Input> extends infer R ? [
        R
    ] extends [
        never
    ] ? readonly [
        Acc,
        Input
    ] : R extends readonly [
        infer Value,
        infer Rest extends string
    ] ? IsNoProgress<Input, Rest> extends true ? never : ManyInternal<P, Rest, readonly [
        ...Acc,
        Value
    ]> : never : never;
    type Many1Internal<P extends Any, Input extends string> = Apply<P, Input> extends infer R ? [
        R
    ] extends [
        never
    ] ? never : R extends readonly [
        infer Value,
        infer Rest extends string
    ] ? IsNoProgress<Input, Rest> extends true ? never : ManyInternal<P, Rest, readonly [
        Value
    ]> : never : never;
    interface Many<P extends Any> extends Parser<unknown> {
        readonly return: InputOf<this> extends infer Input extends string ? ManyInternal<P, Input> : never;
    }
    interface Many1<P extends Any> extends Parser<unknown> {
        readonly return: InputOf<this> extends infer Input extends string ? Many1Internal<P, Input> : never;
    }
    interface MapTo<F extends TypeFunction> extends TypeFunction {
        readonly return: InputOf<this> extends infer P extends Any ? Map<P, F> : never;
    }
    interface FlatMapTo<F extends TypeFunction> extends TypeFunction {
        readonly return: InputOf<this> extends infer P extends Any ? FlatMap<P, F> : never;
    }
    interface ZipWith<Q extends Any> extends TypeFunction {
        readonly return: InputOf<this> extends infer P extends Any ? Zip<P, Q> : never;
    }
    interface OrElseWith<Q extends Any> extends TypeFunction {
        readonly return: InputOf<this> extends infer P extends Any ? OrElse<P, Q> : never;
    }
    interface OptionalOf extends TypeFunction {
        readonly return: InputOf<this> extends infer P extends Any ? Optional<P> : never;
    }
    interface ManyOf extends TypeFunction {
        readonly return: InputOf<this> extends infer P extends Any ? Many<P> : never;
    }
    interface Many1Of extends TypeFunction {
        readonly return: InputOf<this> extends infer P extends Any ? Many1<P> : never;
    }
}
```

## Why

Route grammar can be evaluated in TypeScript while mirroring the runtime parser.

## Ownership and lifetime

`Parser` is an HKT protocol evaluated by TypeScript. Implementing it creates no runtime parser object or subscription.