effect-start 0.14.0 → 0.16.0

package/src/RouteTrie.test.ts

@@ -0,0 +1,322 @@
+import * as test from "bun:test"
+import * as Route from "./Route.ts"
+import * as RouteMount from "./RouteMount.ts"
+import * as RouteTrie from "./RouteTrie.ts"
+
+test.describe(RouteTrie.make, () => {
+  test.it("creates trie from route set", () => {
+    const routes = Route
+      .add("/about", Route.get(Route.text("About")))
+
+    const trie = RouteTrie.make(routes)
+
+    test
+      .expect(trie.methods["GET"])
+      .toBeDefined()
+  })
+})
+
+test.describe(RouteTrie.lookup, () => {
+  test.it("matches exact static path", () => {
+    const routes = Route
+      .add("/about", Route.get(Route.text("About")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/about")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+    test
+      .expect(results[0].params)
+      .toEqual({})
+  })
+
+  test.it("returns empty for non-matching path", () => {
+    const routes = Route
+      .add("/about", Route.get(Route.text("About")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/contact")
+
+    test
+      .expect(results.length)
+      .toBe(0)
+  })
+
+  test.it("matches path with single param", () => {
+    const routes = Route
+      .add("/users/:id", Route.get(Route.text("User")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/users/123")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+    test
+      .expect(results[0].params)
+      .toEqual({ id: "123" })
+  })
+
+  test.it("matches path with multiple params", () => {
+    const routes = Route
+      .add("/users/:userId/posts/:postId", Route.get(Route.text("Post")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/users/42/posts/7")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+    test
+      .expect(results[0].params)
+      .toEqual({
+        userId: "42",
+        postId: "7",
+      })
+  })
+
+  test.it("matches path with optional param present", () => {
+    const routes = Route
+      .add("/files/:name?", Route.get(Route.text("File")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/files/readme")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+    test
+      .expect(results[0].params)
+      .toEqual({ name: "readme" })
+  })
+
+  test.it("matches path with optional param absent", () => {
+    const routes = Route
+      .add("/files/:name?", Route.get(Route.text("File")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/files")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+    test
+      .expect(results[0].params)
+      .toEqual({})
+  })
+
+  test.it("matches path with optional wildcard param", () => {
+    const routes = Route
+      .add("/docs/:path*", Route.get(Route.text("Docs")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/docs/api/users/create")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+    test
+      .expect(results[0].params)
+      .toEqual({
+        path: "api/users/create",
+      })
+  })
+
+  test.it("matches path with optional wildcard when empty", () => {
+    const routes = Route
+      .add("/docs/:path*", Route.get(Route.text("Docs")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/docs")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+    test
+      .expect(results[0].params)
+      .toEqual({})
+  })
+
+  test.it("matches path with required wildcard param", () => {
+    const routes = Route
+      .add("/docs/:path+", Route.get(Route.text("Docs")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/docs/api/users/create")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+    test
+      .expect(results[0].params)
+      .toEqual({
+        path: "api/users/create",
+      })
+  })
+
+  test.it("does not match required wildcard when empty", () => {
+    const routes = Route
+      .add("/docs/:path+", Route.get(Route.text("Docs")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/docs")
+
+    test
+      .expect(results.length)
+      .toBe(0)
+  })
+
+  test.it("required wildcard beats optional wildcard in priority", () => {
+    const routes = Route
+      .add("/files/:path*", Route.get(Route.text("Optional")))
+      .add("/files/:path+", Route.get(Route.text("Required")))
+    const trie = RouteTrie.make(routes)
+
+    const multiResults = RouteTrie.lookup(trie, "GET", "/files/a/b/c")
+
+    test
+      .expect(multiResults.length)
+      .toBe(2)
+    test
+      .expect(multiResults[0].params)
+      .toEqual({ path: "a/b/c" })
+    test
+      .expect(multiResults[1].params)
+      .toEqual({ path: "a/b/c" })
+  })
+
+  test.it("optional wildcard matches when required cannot", () => {
+    const routes = Route
+      .add("/files/:path*", Route.get(Route.text("Optional")))
+      .add("/files/:path+", Route.get(Route.text("Required")))
+    const trie = RouteTrie.make(routes)
+
+    const emptyResults = RouteTrie.lookup(trie, "GET", "/files")
+
+    test
+      .expect(emptyResults.length)
+      .toBe(1)
+    test
+      .expect(emptyResults[0].params)
+      .toEqual({})
+  })
+
+  test.it("prioritizes static over param routes", () => {
+    const routes = Route
+      .add("/users/:id", Route.get(Route.text("User by ID")))
+      .add("/users/me", Route.get(Route.text("Current user")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/users/me")
+
+    test
+      .expect(results.length)
+      .toBe(2)
+    test
+      .expect(results[0].params)
+      .toEqual({})
+    test
+      .expect(results[1].params)
+      .toEqual({ id: "me" })
+  })
+
+  test.it("matches nested mounted routes", () => {
+    const routes = Route
+      .add(
+        "/admin",
+        Route
+          .add("/users", Route.get(Route.text("Admin users")))
+          .add("/settings", Route.get(Route.text("Admin settings"))),
+      )
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/admin/users")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+  })
+
+  test.it("normalizes paths with trailing slashes", () => {
+    const routes = Route
+      .add("/about", Route.get(Route.text("About")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/about/")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+    test
+      .expect(results[0].params)
+      .toEqual({})
+  })
+
+  test.it("matches root path", () => {
+    const routes = Route
+      .add("/", Route.get(Route.text("Home")))
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/")
+
+    test
+      .expect(results.length)
+      .toBe(1)
+    test
+      .expect(results[0].params)
+      .toEqual({})
+  })
+
+  test.it("matches method-specific routes", () => {
+    const routes = Route
+      .add("/users", Route.get(Route.text("List users")))
+      .add("/users", Route.post(Route.text("Create user")))
+    const trie = RouteTrie.make(routes)
+
+    const getResults = RouteTrie.lookup(trie, "GET", "/users")
+    const postResults = RouteTrie.lookup(trie, "POST", "/users")
+
+    test
+      .expect(getResults.length)
+      .toBe(1)
+    test
+      .expect(postResults.length)
+      .toBe(1)
+  })
+
+  test.it("matches wildcard method routes", () => {
+    const routes = Route
+      .add("/health", Route.use(Route.text("OK")))
+    const trie = RouteTrie.make(routes)
+
+    const getResults = RouteTrie.lookup(trie, "GET", "/health")
+    const postResults = RouteTrie.lookup(trie, "POST", "/health")
+
+    test
+      .expect(getResults.length)
+      .toBe(1)
+    test
+      .expect(postResults.length)
+      .toBe(1)
+  })
+
+  test.it("returns multiple matches for content negotiation", () => {
+    const routes = Route
+      .add(
+        "/page",
+        Route.get(
+          Route.text("Plain text"),
+          Route.html("<p>HTML</p>"),
+        ),
+      )
+    const trie = RouteTrie.make(routes)
+
+    const results = RouteTrie.lookup(trie, "GET", "/page")
+
+    test
+      .expect(results.length)
+      .toBe(2)
+  })
+})

package/src/RouteTrie.ts

@@ -0,0 +1,224 @@
+import * as PathPattern from "./PathPattern.ts"
+import * as Route from "./Route.ts"
+
+export interface Node {
+  children: Record<string, Node>
+  paramChild: Node | null
+  paramName: string | null
+  requiredWildcardChild: Node | null
+  requiredWildcardName: string | null
+  optionalWildcardChild: Node | null
+  optionalWildcardName: string | null
+  routes: Route.Route.Route[]
+}
+
+export interface RouteTrie {
+  readonly methods: Record<string, Node>
+}
+
+export interface LookupResult {
+  route: Route.Route.Route
+  params: Record<string, string>
+}
+
+function createNode(): Node {
+  return {
+    children: {},
+    paramChild: null,
+    paramName: null,
+    requiredWildcardChild: null,
+    requiredWildcardName: null,
+    optionalWildcardChild: null,
+    optionalWildcardName: null,
+    routes: [],
+  }
+}
+
+function insertRoute(
+  node: Node,
+  segments: string[],
+  route: Route.Route.Route,
+): void {
+  if (segments.length === 0) {
+    node.routes.push(route)
+    return
+  }
+
+  const segment = segments[0]
+  const rest = segments.slice(1)
+
+  if (segment.startsWith(":")) {
+    const name = segment.slice(1)
+
+    if (name.endsWith("+")) {
+      if (!node.requiredWildcardChild) {
+        node.requiredWildcardChild = createNode()
+      }
+      node.requiredWildcardChild.requiredWildcardName = name.slice(0, -1)
+      node.requiredWildcardChild.routes.push(route)
+    } else if (name.endsWith("*")) {
+      if (!node.optionalWildcardChild) {
+        node.optionalWildcardChild = createNode()
+      }
+      node.optionalWildcardChild.optionalWildcardName = name.slice(0, -1)
+      node.optionalWildcardChild.routes.push(route)
+    } else if (name.endsWith("?")) {
+      if (!node.paramChild) {
+        node.paramChild = createNode()
+      }
+      node.paramChild.paramName = name.slice(0, -1)
+      insertRoute(node.paramChild, rest, route)
+      insertRoute(node, rest, route)
+    } else {
+      if (!node.paramChild) {
+        node.paramChild = createNode()
+      }
+      node.paramChild.paramName = name
+      insertRoute(node.paramChild, rest, route)
+    }
+  } else {
+    if (!node.children[segment]) {
+      node.children[segment] = createNode()
+    }
+    insertRoute(node.children[segment], rest, route)
+  }
+}
+
+interface CollectedRoute {
+  route: Route.Route.Route
+  method: string
+  path: string
+}
+
+function collectRoutes(
+  items: Route.Route.Tuple,
+  parentPath: string,
+  parentMethod: string,
+): CollectedRoute[] {
+  const results: CollectedRoute[] = []
+
+  for (const item of items) {
+    const desc = Route.descriptor(item) as { path?: string; method?: string }
+    const currentPath = typeof desc?.path === "string"
+      ? parentPath + desc.path
+      : parentPath
+    const currentMethod = desc?.method ?? parentMethod
+
+    if (Route.isRoute(item)) {
+      if (currentPath !== "") {
+        results.push({
+          route: item,
+          method: currentMethod,
+          path: currentPath,
+        })
+      }
+    } else {
+      const nestedItems = Route.items(item)
+      results.push(...collectRoutes(nestedItems, currentPath, currentMethod))
+    }
+  }
+
+  return results
+}
+
+export function make(set: Route.RouteSet.Any): RouteTrie {
+  const methods: Record<string, Node> = {}
+  const collected = collectRoutes(Route.items(set), "", "*")
+
+  for (const { route, method, path } of collected) {
+    if (!methods[method]) {
+      methods[method] = createNode()
+    }
+    const result = PathPattern.validate(path)
+    if (!result.ok) {
+      throw new Error(result.error)
+    }
+    insertRoute(methods[method], result.segments, route)
+  }
+
+  return { methods }
+}
+
+function lookupNode(
+  node: Node,
+  segments: string[],
+  params: Record<string, string>,
+): LookupResult[] {
+  const results: LookupResult[] = []
+
+  if (segments.length === 0) {
+    for (const route of node.routes) {
+      results.push({ route, params })
+    }
+    if (
+      node.optionalWildcardChild
+      && node.optionalWildcardChild.optionalWildcardName
+    ) {
+      for (const route of node.optionalWildcardChild.routes) {
+        results.push({ route, params })
+      }
+    }
+    return results
+  }
+
+  const segment = segments[0]
+  const rest = segments.slice(1)
+
+  if (node.children[segment]) {
+    results.push(...lookupNode(node.children[segment], rest, params))
+  }
+
+  if (node.paramChild && node.paramChild.paramName) {
+    const newParams = { ...params, [node.paramChild.paramName]: segment }
+    results.push(...lookupNode(node.paramChild, rest, newParams))
+  }
+
+  if (
+    node.requiredWildcardChild
+    && node.requiredWildcardChild.requiredWildcardName
+  ) {
+    const wildcardValue = segments.join("/")
+    const newParams = {
+      ...params,
+      [node.requiredWildcardChild.requiredWildcardName]: wildcardValue,
+    }
+    for (const route of node.requiredWildcardChild.routes) {
+      results.push({ route, params: newParams })
+    }
+  }
+
+  if (
+    node.optionalWildcardChild
+    && node.optionalWildcardChild.optionalWildcardName
+  ) {
+    const wildcardValue = segments.join("/")
+    const newParams = {
+      ...params,
+      [node.optionalWildcardChild.optionalWildcardName]: wildcardValue,
+    }
+    for (const route of node.optionalWildcardChild.routes) {
+      results.push({ route, params: newParams })
+    }
+  }
+
+  return results
+}
+
+export function lookup(
+  trie: RouteTrie,
+  method: string,
+  path: string,
+): LookupResult[] {
+  const segments = path.split("/").filter(Boolean)
+  const results: LookupResult[] = []
+
+  if (trie.methods[method]) {
+    results.push(...lookupNode(trie.methods[method], segments, {}))
+  }
+
+  if (method !== "*" && trie.methods["*"]) {
+    results.push(...lookupNode(trie.methods["*"], segments, {}))
+  }
+
+  return results
+}