@typed/router 0.31.0 → 1.0.0-beta.0

package/src/Parser.ts

@@ -0,0 +1,282 @@
+import type { Arg0, Pipe, TypeLambda, TypeLambda1 } from "hkt-core";
+
+export type Result<Value, Rest extends string> = readonly [value: Value, rest: Rest];
+
+export interface Parser<Output = unknown> extends TypeLambda<
+  [input: string],
+  Result<Output, string>
+> {}
+
+export type Parse<P extends Parser<unknown>, Input extends string> = Pipe<Input, P>;
+
+type IsStringLiteral<T extends string> = string extends T ? false : true;
+
+type StrictEquals<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+type IsNoProgress<Input extends string, Rest extends string> =
+  IsStringLiteral<Input> extends true ? StrictEquals<Input, Rest> : false;
+
+export declare namespace Parser {
+  export type Any = Parser<unknown>;
+
+  export type Run<P extends Any, Input extends string> = Pipe<Input, P>;
+
+  export interface Succeed<A> extends TypeLambda<[input: string], Result<A, string>> {
+    readonly return: Arg0<this> extends infer Input extends string ? readonly [A, Input] : never;
+  }
+
+  export interface Fail extends TypeLambda<[input: string], never> {
+    readonly return: never;
+  }
+
+  export interface Char<C extends string> extends TypeLambda<
+    [input: string],
+    Result<C, string> | never
+  > {
+    readonly return: Arg0<this> extends `${C}${infer Rest}` ? readonly [C, Rest] : never;
+  }
+
+  export interface String<S extends string> extends TypeLambda<
+    [input: string],
+    Result<S, string> | never
+  > {
+    readonly return: Arg0<this> extends `${S}${infer Rest}` ? readonly [S, Rest] : never;
+  }
+
+  export 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";
+
+  export 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";
+
+  export type Alphabet = LowercaseAlphabet | UppercaseAlphabet;
+
+  export type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+
+  export 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;
+
+  export interface TakeWhile<Allowed extends string> extends TypeLambda<
+    [input: string],
+    Result<string, string>
+  > {
+    readonly return: Arg0<this> extends infer Input extends string
+      ? TakeWhileInternal<Input, Allowed>
+      : never;
+  }
+
+  export interface TakeWhile1<Allowed extends string> extends TypeLambda<
+    [input: string],
+    Result<string, string> | never
+  > {
+    readonly return: Arg0<this> extends infer Input extends string
+      ? TakeWhile1Internal<Input, Allowed>
+      : never;
+  }
+
+  export interface Map<P extends Any, F extends TypeLambda1> extends Parser<unknown> {
+    readonly return: Arg0<this> extends infer Input extends string
+      ? Pipe<Input, P> extends infer R
+        ? [R] extends [never]
+          ? never
+          : R extends readonly [infer Value, infer Rest extends string]
+            ? readonly [Pipe<Value, F>, Rest]
+            : never
+        : never
+      : never;
+  }
+
+  export interface FlatMap<P extends Any, F extends TypeLambda1> extends Parser<unknown> {
+    readonly return: Arg0<this> extends infer Input extends string
+      ? Pipe<Input, P> 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;
+  }
+
+  export interface Zip<P extends Any, Q extends Any> extends Parser<unknown> {
+    readonly return: Arg0<this> extends infer Input extends string
+      ? Pipe<Input, P> 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;
+  }
+
+  export interface OrElse<P extends Any, Q extends Any> extends Parser<unknown> {
+    readonly return: Arg0<this> extends infer Input extends string
+      ? Pipe<Input, P> extends infer R
+        ? [R] extends [never]
+          ? Pipe<Input, Q>
+          : R extends readonly [infer Value, infer Rest extends string]
+            ? readonly [Value, Rest]
+            : never
+        : never
+      : never;
+  }
+
+  export interface Optional<P extends Any> extends Parser<unknown> {
+    readonly return: Arg0<this> extends infer Input extends string
+      ? Pipe<Input, P> 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 [],
+  > =
+    Pipe<Input, P> 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> =
+    Pipe<Input, P> 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;
+
+  export interface Many<P extends Any> extends Parser<unknown> {
+    readonly return: Arg0<this> extends infer Input extends string ? ManyInternal<P, Input> : never;
+  }
+
+  export interface Many1<P extends Any> extends Parser<unknown> {
+    readonly return: Arg0<this> extends infer Input extends string
+      ? Many1Internal<P, Input>
+      : never;
+  }
+
+  export interface MapTo<F extends TypeLambda1> extends TypeLambda1 {
+    readonly return: Arg0<this> extends infer P extends Any ? Map<P, F> : never;
+  }
+
+  export interface FlatMapTo<F extends TypeLambda1> extends TypeLambda1 {
+    readonly return: Arg0<this> extends infer P extends Any ? FlatMap<P, F> : never;
+  }
+
+  export interface ZipWith<Q extends Any> extends TypeLambda1 {
+    readonly return: Arg0<this> extends infer P extends Any ? Zip<P, Q> : never;
+  }
+
+  export interface OrElseWith<Q extends Any> extends TypeLambda1 {
+    readonly return: Arg0<this> extends infer P extends Any ? OrElse<P, Q> : never;
+  }
+
+  export interface OptionalOf extends TypeLambda1 {
+    readonly return: Arg0<this> extends infer P extends Any ? Optional<P> : never;
+  }
+
+  export interface ManyOf extends TypeLambda1 {
+    readonly return: Arg0<this> extends infer P extends Any ? Many<P> : never;
+  }
+
+  export interface Many1Of extends TypeLambda1 {
+    readonly return: Arg0<this> extends infer P extends Any ? Many1<P> : never;
+  }
+}

package/src/Path.test.ts

@@ -0,0 +1,318 @@
+import { describe, expect, it } from "vitest";
+
+import * as AST from "./AST.js";
+import * as Path from "./Path.js";
+
+describe("typed/router/Path", () => {
+  describe("parseWithRest", () => {
+    it("parses literals and parameters", () => {
+      const [asts, rest] = Path.parseWithRest("/users/:id");
+
+      expect(asts).toEqual([AST.literal("users"), AST.slash(), AST.parameter("id")]);
+      expect(rest).toEqual("");
+    });
+
+    it("parses wildcard segments", () => {
+      const [asts, rest] = Path.parseWithRest("/files/*");
+
+      expect(asts).toEqual([AST.literal("files"), AST.slash(), AST.wildcard()]);
+      expect(rest).toEqual("");
+    });
+
+    it("parses parameters with regex and optional mark", () => {
+      const [asts, rest] = Path.parseWithRest("/:id(\\d+)?");
+
+      expect(asts).toEqual([AST.parameter("id", true, "\\d+")]);
+      expect(rest).toEqual("");
+    });
+
+    it("emits slash AST nodes only when a '/' actually separates atoms", () => {
+      expect(Path.parseWithRest("*foo")[0]).toEqual([AST.wildcard(), AST.literal("foo")]);
+      expect(Path.parseWithRest("*/foo")[0]).toEqual([
+        AST.wildcard(),
+        AST.slash(),
+        AST.literal("foo"),
+      ]);
+    });
+
+    it("parses query params with literal, parameter, and wildcard values", () => {
+      const [asts, rest] = Path.parseWithRest("/search?term=:term&limit=10&rest=*");
+
+      expect(asts).toEqual([
+        AST.literal("search"),
+        AST.queryParams([
+          AST.queryParam("term", AST.parameter("term")),
+          AST.queryParam("limit", AST.literal("10")),
+          AST.queryParam("rest", AST.wildcard()),
+        ]),
+      ]);
+      expect(rest).toEqual("");
+    });
+
+    it("stops parsing query params when a tail param can't be parsed, leaving '&' for the outer parser", () => {
+      const [asts, rest] = Path.parseWithRest("/?a=b&");
+
+      expect(asts).toEqual([
+        AST.queryParams([AST.queryParam("a", AST.literal("b"))]),
+        AST.literal("&"),
+      ]);
+      expect(rest).toEqual("");
+    });
+
+    it("parses multiple path segments", () => {
+      const [asts, rest] = Path.parseWithRest("/api/v1/users/:userId/posts/:postId");
+
+      expect(asts).toEqual([
+        AST.literal("api"),
+        AST.slash(),
+        AST.literal("v1"),
+        AST.slash(),
+        AST.literal("users"),
+        AST.slash(),
+        AST.parameter("userId"),
+        AST.slash(),
+        AST.literal("posts"),
+        AST.slash(),
+        AST.parameter("postId"),
+      ]);
+      expect(rest).toEqual("");
+    });
+
+    it("parses parameter with regex only (no optional)", () => {
+      const [asts, rest] = Path.parseWithRest("/:id(\\d+)");
+
+      expect(asts).toEqual([AST.parameter("id", undefined, "\\d+")]);
+      expect(rest).toEqual("");
+    });
+
+    it("parses optional parameter without regex", () => {
+      const [asts, rest] = Path.parseWithRest("/:id?");
+
+      expect(asts).toEqual([AST.parameter("id", true)]);
+      expect(rest).toEqual("");
+    });
+
+    it("parses consecutive parameters", () => {
+      const [asts, rest] = Path.parseWithRest("/:a:b");
+
+      expect(asts).toEqual([AST.parameter("a"), AST.parameter("b")]);
+      expect(rest).toEqual("");
+    });
+
+    it("parses mixed slashes", () => {
+      const [asts, rest] = Path.parseWithRest("//users///profile");
+
+      expect(asts).toEqual([AST.literal("users"), AST.slash(), AST.literal("profile")]);
+      expect(rest).toEqual("");
+    });
+
+    it("parses empty string", () => {
+      const [asts, rest] = Path.parseWithRest("");
+
+      expect(asts).toEqual([]);
+      expect(rest).toEqual("");
+    });
+
+    it("handles trailing slashes", () => {
+      const [asts, rest] = Path.parseWithRest("/users/");
+
+      expect(asts).toEqual([AST.literal("users")]);
+      expect(rest).toEqual("/");
+    });
+
+    it("parses single query param", () => {
+      const [asts, rest] = Path.parseWithRest("?foo=bar");
+
+      expect(asts).toEqual([AST.queryParams([AST.queryParam("foo", AST.literal("bar"))])]);
+      expect(rest).toEqual("");
+    });
+
+    it("parses multiple query params", () => {
+      const [asts, rest] = Path.parseWithRest("?foo=bar&baz=qux");
+
+      expect(asts).toEqual([
+        AST.queryParams([
+          AST.queryParam("foo", AST.literal("bar")),
+          AST.queryParam("baz", AST.literal("qux")),
+        ]),
+      ]);
+      expect(rest).toEqual("");
+    });
+
+    it("parses path with query params containing parameters", () => {
+      const [asts, rest] = Path.parseWithRest("/users?id=:id&name=:name");
+
+      expect(asts).toEqual([
+        AST.literal("users"),
+        AST.queryParams([
+          AST.queryParam("id", AST.parameter("id")),
+          AST.queryParam("name", AST.parameter("name")),
+        ]),
+      ]);
+      expect(rest).toEqual("");
+    });
+  });
+
+  describe("parse", () => {
+    it("accepts a root path", () => {
+      expect(Path.parse("/")).toEqual([]);
+    });
+
+    it("throws when unparsed rest contains non-slash characters", () => {
+      expect(() => Path.parse("/:")).toThrow();
+    });
+
+    it("parses simple path", () => {
+      expect(Path.parse("/users")).toEqual([AST.literal("users")]);
+    });
+
+    it("parses path with parameter", () => {
+      expect(Path.parse("/users/:id")).toEqual([
+        AST.literal("users"),
+        AST.slash(),
+        AST.parameter("id"),
+      ]);
+    });
+
+    it("parses path with wildcard", () => {
+      expect(Path.parse("/files/*")).toEqual([AST.literal("files"), AST.slash(), AST.wildcard()]);
+    });
+
+    it("accepts trailing slashes", () => {
+      expect(Path.parse("/users/")).toEqual([AST.literal("users")]);
+      expect(Path.parse("/users///")).toEqual([AST.literal("users")]);
+    });
+
+    it("throws on invalid parameter syntax", () => {
+      expect(() => Path.parse("/users/:")).toThrow();
+    });
+
+    it("throws on unclosed regex", () => {
+      expect(() => Path.parse("/:id(abc")).toThrow();
+    });
+  });
+
+  describe("join", () => {
+    it("joins literal ASTs", () => {
+      expect(Path.join([AST.literal("users")])).toEqual("/users");
+    });
+
+    it("joins literal with slash and parameter", () => {
+      expect(Path.join([AST.literal("users"), AST.slash(), AST.parameter("id")])).toEqual(
+        "/users/:id",
+      );
+    });
+
+    it("joins with wildcard", () => {
+      expect(Path.join([AST.literal("files"), AST.slash(), AST.wildcard()])).toEqual("/files/*");
+    });
+
+    it("joins with optional parameter", () => {
+      const ast = AST.parameter("id", true);
+      // Note: formatAst doesn't include the optional marker in output
+      expect(Path.join([ast])).toEqual("/:id");
+    });
+
+    it("joins with query params", () => {
+      expect(
+        Path.join([
+          AST.literal("search"),
+          AST.queryParams([
+            AST.queryParam("term", AST.parameter("term")),
+            AST.queryParam("limit", AST.literal("10")),
+          ]),
+        ]),
+      ).toEqual("/search?term=:term&limit=10");
+    });
+
+    it("joins empty array", () => {
+      expect(Path.join([])).toEqual("/");
+    });
+
+    it("joins multiple slashes", () => {
+      expect(Path.join([AST.slash(), AST.literal("a"), AST.slash(), AST.slash()])).toEqual("//a//");
+    });
+  });
+
+  describe("getSchemaFields", () => {
+    it("extracts parameter fields", () => {
+      const result = Path.getSchemaFields([AST.parameter("id"), AST.parameter("name")]);
+
+      expect(result.requiredFields.map(([name]) => name)).toEqual(["id", "name"]);
+      expect(result.optionalFields).toEqual([]);
+      expect(result.queryParams).toEqual([]);
+    });
+
+    it("extracts optional parameter fields", () => {
+      const result = Path.getSchemaFields([AST.parameter("id", true)]);
+
+      expect(result.requiredFields).toEqual([]);
+      expect(result.optionalFields.length).toEqual(1);
+    });
+
+    it("extracts wildcard as required field", () => {
+      const result = Path.getSchemaFields([AST.wildcard()]);
+
+      expect(result.requiredFields.map(([name]) => name)).toEqual(["*"]);
+    });
+
+    it("extracts query params", () => {
+      const result = Path.getSchemaFields([
+        AST.queryParams([AST.queryParam("foo", AST.parameter("bar"))]),
+      ]);
+
+      expect(result.queryParams.length).toEqual(1);
+      expect(result.queryParams[0][0]).toEqual("foo");
+    });
+
+    it("ignores literals and slashes", () => {
+      const result = Path.getSchemaFields([AST.literal("users"), AST.slash()]);
+
+      expect(result.requiredFields).toEqual([]);
+      expect(result.optionalFields).toEqual([]);
+      expect(result.queryParams).toEqual([]);
+    });
+
+    it("handles parameter with regex", () => {
+      const result = Path.getSchemaFields([AST.parameter("id", undefined, "\\d+")]);
+
+      expect(result.requiredFields.length).toEqual(1);
+      expect(result.requiredFields[0][0]).toEqual("id");
+    });
+  });
+
+  describe("getSchemas", () => {
+    it("creates path schema for parameters", () => {
+      const result = Path.getSchemas([AST.parameter("id")]);
+
+      expect(result.pathSchema).toBeDefined();
+      expect(result.querySchema).toBeDefined();
+      expect(result.paramsSchema).toBeDefined();
+    });
+
+    it("creates schemas for path with query params", () => {
+      const result = Path.getSchemas([
+        AST.literal("search"),
+        AST.queryParams([AST.queryParam("term", AST.parameter("term"))]),
+      ]);
+
+      expect(result.pathSchema).toBeDefined();
+      expect(result.querySchema).toBeDefined();
+      expect(result.paramsSchema).toBeDefined();
+    });
+
+    it("creates schemas for wildcard", () => {
+      const result = Path.getSchemas([AST.wildcard()]);
+
+      expect(result.pathSchema).toBeDefined();
+    });
+
+    it("creates schemas for empty path", () => {
+      const result = Path.getSchemas([]);
+
+      expect(result.pathSchema).toBeDefined();
+      expect(result.querySchema).toBeDefined();
+      expect(result.paramsSchema).toBeDefined();
+    });
+  });
+});