@typed/router 0.31.0 → 1.0.0-beta.0

package/src/Route.test.ts

@@ -0,0 +1,268 @@
+import { describe, expect, it } from "vitest";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Route from "./Route.js";
+
+describe("typed/router/Route", () => {
+  describe("Parse", () => {
+    it("creates route from literal string", () => {
+      const route = Route.Parse("users");
+
+      expect(route.path).toEqual("/users");
+      expect(route.ast.type).toEqual("path");
+    });
+
+    it("creates route from multi-segment literal", () => {
+      const route = Route.Parse("api/v1/users");
+
+      expect(route.path).toEqual("/api/v1/users");
+    });
+  });
+
+  describe("slash", () => {
+    it("creates root route", () => {
+      expect(Route.Slash.path).toEqual("/");
+    });
+  });
+
+  describe("wildcard", () => {
+    it("creates wildcard route", () => {
+      expect(Route.Wildcard.path).toEqual("/*");
+    });
+  });
+
+  describe("param", () => {
+    it("creates parameter route", () => {
+      const route = Route.Param("id");
+
+      expect(route.path).toEqual("/:id");
+    });
+
+    it("creates parameter route with descriptive name", () => {
+      const route = Route.Param("userId");
+
+      expect(route.path).toEqual("/:userId");
+    });
+  });
+
+  describe("join", () => {
+    it("joins literal routes", () => {
+      const route = Route.Join(Route.Parse("api"), Route.Parse("users"));
+
+      expect(route.path).toEqual("/api/users");
+    });
+
+    it("joins literal with parameter", () => {
+      const route = Route.Join(Route.Parse("users"), Route.Param("id"));
+
+      expect(route.path).toEqual("/users/:id");
+    });
+
+    it("joins multiple routes", () => {
+      const route = Route.Join(
+        Route.Parse("api"),
+        Route.Parse("v1"),
+        Route.Parse("users"),
+        Route.Param("userId"),
+        Route.Parse("posts"),
+        Route.Param("postId"),
+      );
+
+      expect(route.path).toEqual("/api/v1/users/:userId/posts/:postId");
+    });
+
+    it("joins with wildcard", () => {
+      const route = Route.Join(Route.Parse("files"), Route.Wildcard);
+
+      expect(route.path).toEqual("/files/*");
+    });
+  });
+
+  describe("paramsSchema", () => {
+    it("decodes path params from literal route", () =>
+      Effect.gen(function* () {
+        const route = Route.Parse("users");
+        const decoded = yield* Schema.decodeEffect(route.paramsSchema)({});
+
+        expect(decoded).toEqual({});
+      }).pipe(Effect.scoped, Effect.runPromise));
+
+    it("decodes path params from param route", () =>
+      Effect.gen(function* () {
+        const route = Route.Param("id");
+        const decoded = yield* Schema.decodeEffect(route.paramsSchema)({ id: "123" });
+
+        expect(decoded).toEqual({ id: "123" });
+      }).pipe(Effect.scoped, Effect.runPromise));
+
+    it("decodes path params from joined route", () =>
+      Effect.gen(function* () {
+        const route = Route.Join(Route.Parse("users"), Route.Param("id"));
+        const decoded = yield* Schema.decodeEffect(route.paramsSchema)({ id: "123" });
+
+        expect(decoded).toEqual({ id: "123" });
+      }).pipe(Effect.scoped, Effect.runPromise));
+
+    it("decodes wildcard params", () =>
+      Effect.gen(function* () {
+        const route = Route.Join(Route.Parse("files"), Route.Wildcard);
+        const decoded = yield* Schema.decodeEffect(route.paramsSchema)({ "*": "path/to/file" });
+
+        expect(decoded).toEqual({ "*": "path/to/file" });
+      }).pipe(Effect.scoped, Effect.runPromise));
+
+    it("decodes multiple params from joined route", () =>
+      Effect.gen(function* () {
+        const route = Route.Join(
+          Route.Parse("users"),
+          Route.Param("userId"),
+          Route.Parse("posts"),
+          Route.Param("postId"),
+        );
+        const decoded = yield* Schema.decodeEffect(route.paramsSchema)({
+          userId: "u1",
+          postId: "p1",
+        });
+
+        expect(decoded).toEqual({ userId: "u1", postId: "p1" });
+      }).pipe(Effect.scoped, Effect.runPromise));
+  });
+
+  describe("pathSchema", () => {
+    it("decodes path-only params (excludes query)", () =>
+      Effect.gen(function* () {
+        const route = Route.Join(Route.Parse("users"), Route.Param("id"));
+        const decoded = yield* Schema.decodeEffect(route.pathSchema)({ id: "123" });
+
+        expect(decoded).toEqual({ id: "123" });
+      }).pipe(Effect.scoped, Effect.runPromise));
+  });
+
+  describe("querySchema", () => {
+    it("decodes empty query schema for path-only route", () =>
+      Effect.gen(function* () {
+        const route = Route.Join(Route.Parse("users"), Route.Param("id"));
+        const decoded = yield* Schema.decodeEffect(route.querySchema)({});
+
+        expect(decoded).toEqual({});
+      }).pipe(Effect.scoped, Effect.runPromise));
+  });
+
+  describe("pipe", () => {
+    it("supports pipeable interface", () => {
+      const route = Route.Parse("users");
+      const result = route.pipe((r) => r.path);
+
+      expect(result).toEqual("/users");
+    });
+  });
+
+  describe("path correctness", () => {
+    describe("Literal path handling", () => {
+      it("adds leading slash to simple literal", () => {
+        expect(Route.Parse("users").path).toEqual("/users");
+      });
+
+      it("preserves slashes in input", () => {
+        expect(Route.Parse("/users").path).toEqual("/users");
+      });
+
+      it("preserves internal slashes", () => {
+        expect(Route.Parse("api/v1/users").path).toEqual("/api/v1/users");
+      });
+
+      it("handles empty string as root", () => {
+        expect(Route.Parse("").path).toEqual("/");
+      });
+    });
+
+    describe("join path construction", () => {
+      it("joins single route", () => {
+        const route = Route.Join(Route.Parse("users"));
+        expect(route.path).toEqual("/users");
+      });
+
+      it("joins slash with literal", () => {
+        const route = Route.Join(Route.Slash, Route.Parse("users"));
+        expect(route.path).toEqual("//users");
+      });
+
+      it("joins param at start", () => {
+        const route = Route.Join(Route.Param("tenant"), Route.Parse("users"));
+        expect(route.path).toEqual("/:tenant/users");
+      });
+
+      it("joins wildcard at start", () => {
+        const route = Route.Join(Route.Wildcard, Route.Parse("match"));
+        expect(route.path).toEqual("/*/match");
+      });
+
+      it("joins three params", () => {
+        const route = Route.Join(Route.Param("a"), Route.Param("b"), Route.Param("c"));
+        expect(route.path).toEqual("/:a/:b/:c");
+      });
+
+      it("joins param between literals", () => {
+        const route = Route.Join(Route.Parse("users"), Route.Param("id"), Route.Parse("profile"));
+        expect(route.path).toEqual("/users/:id/profile");
+      });
+
+      it("joins nested api pattern", () => {
+        const route = Route.Join(
+          Route.Parse("api"),
+          Route.Parse("v2"),
+          Route.Parse("organizations"),
+          Route.Param("orgId"),
+          Route.Parse("teams"),
+          Route.Param("teamId"),
+          Route.Parse("members"),
+          Route.Param("memberId"),
+        );
+        expect(route.path).toEqual("/api/v2/organizations/:orgId/teams/:teamId/members/:memberId");
+      });
+
+      it("joins wildcard at end for catch-all", () => {
+        const route = Route.Join(Route.Parse("docs"), Route.Param("version"), Route.Wildcard);
+        expect(route.path).toEqual("/docs/:version/*");
+      });
+
+      it("joins multiple wildcards", () => {
+        const route = Route.Join(Route.Wildcard, Route.Wildcard);
+        expect(route.path).toEqual("/*/*");
+      });
+
+      it("joins alternating params and literals", () => {
+        const route = Route.Join(
+          Route.Param("a"),
+          Route.Parse("x"),
+          Route.Param("b"),
+          Route.Parse("y"),
+          Route.Param("c"),
+        );
+        expect(route.path).toEqual("/:a/x/:b/y/:c");
+      });
+    });
+
+    describe("individual route paths", () => {
+      it("Slash is /", () => {
+        expect(Route.Slash.path).toEqual("/");
+      });
+
+      it("Wildcard is /*", () => {
+        expect(Route.Wildcard.path).toEqual("/*");
+      });
+
+      it("Param includes colon prefix", () => {
+        expect(Route.Param("foo").path).toEqual("/:foo");
+      });
+
+      it("Param with long name", () => {
+        expect(Route.Param("organizationId").path).toEqual("/:organizationId");
+      });
+
+      it("Param with numeric suffix", () => {
+        expect(Route.Param("id1").path).toEqual("/:id1");
+      });
+    });
+  });
+});

package/src/Route.ts

@@ -0,0 +1,316 @@
+/* eslint-disable no-restricted-syntax */
+import * as Effect from "effect/Effect";
+import { type Pipeable, pipeArguments } from "effect/Pipeable";
+import { singleton } from "effect/Record";
+import * as Schema from "effect/Schema";
+import * as Parser from "effect/SchemaParser";
+import * as Transformation from "effect/SchemaTransformation";
+import type { Simplify } from "effect/Types";
+import * as AST from "./AST.js";
+import * as Path from "./Path.js";
+
+export interface Route<
+  P extends string,
+  S extends Schema.Codec<any, Path.Params<P>, any, any> = Schema.Codec<Path.Params<P>>,
+> extends Pipeable {
+  readonly ast: AST.RouteAst;
+  readonly path: P;
+
+  readonly paramsSchema: S;
+  readonly pathSchema: Schema.Codec<Path.PathParams<P>>;
+  readonly querySchema: Schema.Codec<Path.QueryParams<P>>;
+}
+
+export declare namespace Route {
+  export type Any = Route<any, any>;
+
+  export type Path<T> = T extends Route<infer P, any> ? P : never;
+  export type Schema<T> = T extends Route<any, infer S> ? S : never;
+  export type Type<T> = T extends Route<any, infer S> ? S["Type"] : never;
+  export type Params<T> = T extends Route<infer P, infer _S> ? Path.Params<P> : never;
+  export type DecodingServices<T> = T extends Route<any, infer S> ? S["DecodingServices"] : never;
+  export type EncodingServices<T> = T extends Route<any, infer S> ? S["EncodingServices"] : never;
+
+  export type PathType<T extends Any> = T["pathSchema"]["Type"];
+  export type QueryType<T extends Any> = T["querySchema"]["Type"];
+}
+
+export function make<
+  const P extends string,
+  S extends Schema.Codec<any, Path.Params<P>, any, any> = Schema.Codec<Path.Params<P>>,
+>(ast: AST.RouteAst): Route<P, S> {
+  const getParts = once(() => getPathAst(ast));
+  const path = once(() => Path.join(getParts()) as P);
+  const paramsSchema = once(() => getParamsSchema(ast) as S);
+  const pathSchema = once(() => getPathSchema(ast) as Schema.Codec<Path.PathParams<P>>);
+  const querySchema = once(() => getQuerySchema(ast) as Schema.Codec<Path.QueryParams<P>>);
+
+  return {
+    ast,
+    get path() {
+      return path();
+    },
+    get paramsSchema() {
+      return paramsSchema();
+    },
+    get pathSchema() {
+      return pathSchema();
+    },
+    get querySchema() {
+      return querySchema();
+    },
+    pipe() {
+      return pipeArguments(this, arguments);
+    },
+  };
+}
+
+function once<T>(fn: () => T): () => T {
+  let memoized: [T] | [] = [];
+  return (): T => {
+    if (memoized.length === 1) {
+      return memoized[0];
+    }
+    const result = fn();
+    memoized = [result];
+    return result;
+  };
+}
+
+function getPathAst(ast: AST.RouteAst): ReadonlyArray<AST.PathAst> {
+  switch (ast.type) {
+    case "path":
+      return [ast.path];
+    case "transform":
+      return getPathAst(ast.from);
+    case "join": {
+      const result: Array<AST.PathAst> = [];
+      for (let i = 0; i < ast.parts.length; i++) {
+        if (i > 0) {
+          result.push(AST.slash());
+        }
+        result.push(...getPathAst(ast.parts[i]));
+      }
+      return result;
+    }
+  }
+}
+
+function getParamsSchema(ast: AST.RouteAst): Schema.Top {
+  switch (ast.type) {
+    case "path": {
+      const { paramsSchema } = Path.getSchemas(getPathAst(ast));
+      return paramsSchema;
+    }
+    case "transform": {
+      const { paramsSchema } = Path.getSchemas(getPathAst(ast.from));
+      return paramsSchema.pipe(Schema.decodeTo(ast.to, ast.transformation));
+    }
+    case "join": {
+      const parts = ast.parts.map((part) => Path.getSchemaFields(getPathAst(part)));
+      const requiredFields: Array<[string, Schema.Top]> = [];
+      const optionalFields: Array<[Schema.Record.Key, Schema.Top]> = [];
+      const queryParams: Array<
+        [
+          string,
+          {
+            readonly requiredFields: Array<[string, Schema.Top]>;
+            readonly optionalFields: Array<[Schema.Record.Key, Schema.Top]>;
+          },
+        ]
+      > = [];
+
+      for (const part of parts) {
+        requiredFields.push(...part.requiredFields);
+        optionalFields.push(...part.optionalFields);
+        queryParams.push(...part.queryParams);
+      }
+
+      const pathFields = Object.fromEntries(requiredFields);
+      const queryFields = Object.fromEntries(
+        queryParams.map(([name, { optionalFields, requiredFields }]) => [
+          name,
+          Schema.StructWithRest(
+            Schema.Struct(Object.fromEntries(requiredFields)),
+            optionalFields.map(([key, value]) => Schema.Record(key, value)),
+          ),
+        ]),
+      );
+
+      const paramsSchema = Schema.StructWithRest(
+        Schema.Struct({ ...pathFields, ...queryFields }),
+        optionalFields.map(([key, value]) => Schema.Record(key, value)),
+      );
+
+      return paramsSchema;
+    }
+  }
+}
+
+function getPathSchema(ast: AST.RouteAst): Schema.Top {
+  if (ast.type !== "join") return Path.getSchemas(getPathAst(ast)).pathSchema;
+
+  const parts = ast.parts.map((part) => Path.getSchemaFields(getPathAst(part)));
+  const requiredFields: Array<[string, Schema.Top]> = [];
+  const optionalFields: Array<[Schema.Record.Key, Schema.Top]> = [];
+
+  for (const part of parts) {
+    requiredFields.push(...part.requiredFields);
+    optionalFields.push(...part.optionalFields);
+  }
+
+  const pathFields = Object.fromEntries(requiredFields);
+  return Schema.StructWithRest(
+    Schema.Struct(pathFields),
+    optionalFields.map(([key, value]) => Schema.Record(key, value)),
+  );
+}
+
+function getQuerySchema(ast: AST.RouteAst): Schema.Top {
+  if (ast.type !== "join") return Path.getSchemas(getPathAst(ast)).querySchema;
+
+  const parts = ast.parts.map((part) => Path.getSchemaFields(getPathAst(part)));
+  const queryParams: Array<
+    [
+      string,
+      {
+        readonly requiredFields: Array<[string, Schema.Top]>;
+        readonly optionalFields: Array<[Schema.Record.Key, Schema.Top]>;
+      },
+    ]
+  > = [];
+
+  for (const part of parts) {
+    queryParams.push(...part.queryParams);
+  }
+
+  const queryFields = Object.fromEntries(
+    queryParams.map(([name, { optionalFields, requiredFields }]) => [
+      name,
+      Schema.StructWithRest(
+        Schema.Struct(Object.fromEntries(requiredFields)),
+        optionalFields.map(([key, value]) => Schema.Record(key, value)),
+      ),
+    ]),
+  );
+
+  return Schema.Struct(queryFields);
+}
+
+export const Parse = <const P extends string>(path: P): Route<Path.Join<Path.ParseAsts<P>>> => {
+  const asts = Path.parse(path) as ReadonlyArray<AST.PathAst>;
+  if (asts.length === 0) return Slash as unknown as Route<Path.Join<Path.ParseAsts<P>>>;
+  if (asts.length === 1) return make(AST.path(asts[0]));
+  return Join<Array<any>>(...asts.map((ast) => make(AST.path(ast)))) as unknown as Route<
+    Path.Join<Path.ParseAsts<P>>
+  >;
+};
+
+export const Slash = make<"/">(AST.path(AST.literal("")));
+
+export const Wildcard = make<"*">(AST.path(AST.wildcard()));
+
+export const Param = <const P extends string>(paramName: P): Route<`/:${P}`> =>
+  make<`/:${P}`>(AST.path(AST.parameter(paramName)));
+
+export const ParamWithSchema = <
+  const P extends string,
+  S extends Schema.Codec<any, string, any, any> = Schema.Codec<string>,
+>(
+  paramName: P,
+  schema: S,
+): Route<
+  `/:${P}`,
+  Schema.Codec<
+    { readonly [K in P]: S["Type"] },
+    Path.Params<`/:${P}`>,
+    S["DecodingServices"],
+    S["EncodingServices"]
+  >
+> => {
+  const decode = Parser.decodeEffect(schema);
+  const encode = Parser.encodeEffect(schema);
+
+  return make(
+    AST.transform(
+      AST.path(AST.parameter(paramName)),
+      Schema.Struct(singleton(paramName, schema.Type)),
+      Transformation.transformOrFail({
+        decode: (input: Record<P, S["Encoded"]>) =>
+          Effect.map(decode(input[paramName]), (decoded) => singleton(paramName, decoded)),
+        encode: (output: Record<P, S["Type"]>) =>
+          Effect.map(encode(output[paramName]), (encoded) => singleton(paramName, encoded)),
+      }),
+    ),
+  );
+};
+
+export const Number = <const P extends string>(
+  paramName: P,
+): Route<`/:${P}`, Schema.Codec<{ readonly [K in P]: number }, Path.Params<`/:${P}`>>> =>
+  ParamWithSchema(paramName, Schema.NumberFromString);
+
+export const Int = <const P extends string>(
+  paramName: P,
+): Route<`/:${P}`, Schema.Codec<{ readonly [K in P]: number }, Path.Params<`/:${P}`>>> =>
+  ParamWithSchema(paramName, Schema.NumberFromString.pipe(Schema.decodeTo(Schema.Int)));
+
+export type Join<Routes extends ReadonlyArray<Route<any, any>>> = [
+  Route<
+    RouteJoinPath<Routes>,
+    Schema.Codec<
+      Simplify<UnionToIntersection<Routes[number]["paramsSchema"]["Type"]>>,
+      Path.Params<RouteJoinPath<Routes>>,
+      Routes[number]["paramsSchema"]["DecodingServices"],
+      Routes[number]["paramsSchema"]["EncodingServices"]
+    >
+  >,
+] extends [Route<infer Path, infer Schema>]
+  ? Route<Path, Schema>
+  : never;
+
+type AnyRoutes = ReadonlyArray<Route<any, any> | ReadonlyArray<Route<any, any>>>;
+type FlattenRoutes<T extends AnyRoutes> = T extends readonly [
+  infer Head extends Route<any, any> | ReadonlyArray<Route<any, any>>,
+  ...infer Tail extends AnyRoutes,
+]
+  ? readonly [
+      ...(Head extends ReadonlyArray<Route<any, any>> ? FlattenRoutes<Head> : [Head]),
+      ...FlattenRoutes<Tail>,
+    ]
+  : [];
+
+const removeSlash = (ast: AST.RouteAst): ReadonlyArray<AST.RouteAst> => {
+  if (ast.type === "path" && ast.path.type === "slash") return [];
+  return [ast];
+};
+
+export const Join = <const Routes extends AnyRoutes>(
+  ...routes: Routes
+): Join<FlattenRoutes<Routes>> =>
+  make(
+    AST.join(
+      routes.flatMap((route) => {
+        if (Array.isArray(route)) return route.flatMap(removeSlash);
+        return removeSlash((route as Route<any, any>).ast);
+      }),
+    ),
+  );
+
+type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any
+  ? R
+  : never;
+type RouteJoinPath<
+  Routes extends ReadonlyArray<Route<any, any>>,
+  R extends string = "",
+> = Routes extends readonly [
+  infer First extends Route<any, any>,
+  ...infer Rest extends ReadonlyArray<Route<any, any>>,
+]
+  ? RouteJoinPath<Rest, `${R}/${StripSlashes<First["path"]>}`>
+  : R;
+type StripSlashes<T extends string> = StripTrailingSlash<StripLeadingSlash<T>>;
+type StripLeadingSlash<T extends string> = T extends `/${infer Rest}` ? StripLeadingSlash<Rest> : T;
+type StripTrailingSlash<T extends string> = T extends `/${infer Rest}`
+  ? StripTrailingSlash<Rest>
+  : T;

package/src/Router.ts

@@ -0,0 +1,31 @@
+import * as Layer from "effect/Layer";
+import { fromWindow } from "@typed/navigation/fromWindow";
+import {
+  initialMemory,
+  type InitialMemoryOptions,
+  memory,
+  type MemoryOptions,
+} from "@typed/navigation/memory";
+import type { Navigation } from "@typed/navigation/Navigation";
+import { CurrentRoute } from "./CurrentRoute.js";
+import { Ids } from "@typed/id";
+
+export type Router = CurrentRoute | Navigation;
+
+export const BrowserRouter = (window?: Window): Layer.Layer<Router> =>
+  CurrentRoute.Default.pipe(
+    Layer.provideMerge(fromWindow(window)),
+    Layer.provideMerge(Ids.Default),
+  );
+
+export const ServerRouter = (options: MemoryOptions | InitialMemoryOptions): Layer.Layer<Router> =>
+  CurrentRoute.Default.pipe(
+    Layer.provideMerge("url" in options ? initialMemory(options) : memory(options)),
+    Layer.provideMerge(Ids.Default),
+  );
+
+export const TestRouter = (options: (MemoryOptions | InitialMemoryOptions) & {}): Layer.Layer<Router> =>
+  CurrentRoute.Default.pipe(
+    Layer.provideMerge("url" in options ? initialMemory(options) : memory(options)),
+    Layer.provideMerge(Ids.Test()),
+  );