effect-start 0.9.0

package/src/FileRouterCodegen.ts

@@ -0,0 +1,251 @@
+import type { PlatformError } from "@effect/platform/Error"
+import * as FileSystem from "@effect/platform/FileSystem"
+import * as Effect from "effect/Effect"
+import * as NPath from "node:path"
+import * as FileRouter from "./FileRouter.ts"
+import * as Route from "./Route.ts"
+
+export function validateRouteModule(
+  module: unknown,
+): boolean {
+  if (typeof module !== "object" || module === null) {
+    return false
+  }
+  if (!("default" in module)) {
+    return false
+  }
+  return Route.isRouteSet(module.default)
+}
+
+/**
+ * Validates all route modules in the given route handles.
+ */
+export function validateRouteModules(
+  routesPath: string,
+  handles: FileRouter.OrderedRouteHandles,
+): Effect.Effect<void, never, never> {
+  return Effect.gen(function*() {
+    const routeHandles = handles.filter(h => h.handle === "route")
+
+    for (const handle of routeHandles) {
+      const routeModulePath = NPath.resolve(routesPath, handle.modulePath)
+      yield* Effect
+        .tryPromise({
+          try: async () => import(routeModulePath),
+          catch: (error) =>
+            Effect.logWarning(
+              `Failed to validate route module ${routeModulePath}: ${error}`,
+            ),
+        })
+        .pipe(
+          Effect.catchAll((logEffect) => logEffect),
+          Effect.tap((module) => {
+            if (!validateRouteModule(module)) {
+              return Effect.logWarning(
+                `Route module ${routeModulePath} should export default Route`,
+              )
+            }
+            return Effect.void
+          }),
+        )
+    }
+  })
+}
+
+/**
+ * Converts a segment to RouteModuleSegment format
+ */
+function segmentToModuleSegment(segment: FileRouter.Segment): string | null {
+  if ("literal" in segment) {
+    return `{ literal: "${segment.literal}" }`
+  }
+  if ("group" in segment) {
+    return `{ group: "${segment.group}" }`
+  }
+  if ("param" in segment) {
+    return segment.optional
+      ? `{ param: "${segment.param}", optional: true }`
+      : `{ param: "${segment.param}" }`
+  }
+  if ("rest" in segment) {
+    return segment.optional
+      ? `{ rest: "${segment.rest}", optional: true }`
+      : `{ rest: "${segment.rest}" }`
+  }
+  return null
+}
+
+export function generateCode(
+  handles: FileRouter.OrderedRouteHandles,
+): string {
+  const routerModuleId = "effect-start"
+
+  // Group routes by path to find layers
+  const routesByPath = new Map<string, {
+    route?: FileRouter.RouteHandle
+    layers: FileRouter.RouteHandle[]
+  }>()
+
+  for (const handle of handles) {
+    const existing = routesByPath.get(handle.routePath) || { layers: [] }
+    if (handle.handle === "route") {
+      existing.route = handle
+    } else if (handle.handle === "layer") {
+      existing.layers.push(handle)
+    }
+    routesByPath.set(handle.routePath, existing)
+  }
+
+  // Generate module definitions
+  const modules: string[] = []
+
+  // Helper to check if layer's path is an ancestor of route's path
+  const layerMatchesRoute = (
+    layer: FileRouter.RouteHandle,
+    route: FileRouter.RouteHandle,
+  ): boolean => {
+    // Exclude handle segment (last segment) from comparison
+    const layerLength = layer.segments.length - 1
+    const routeLength = route.segments.length - 1
+
+    // Layer's segments must be a prefix of route's segments
+    if (layerLength > routeLength) {
+      return false
+    }
+
+    for (let i = 0; i < layerLength; i++) {
+      if (!FileRouter.isSegmentEqual(layer.segments[i], route.segments[i])) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  // Find layers for each route by walking up the path hierarchy
+  for (const [path, { route }] of routesByPath) {
+    if (!route) continue // Skip paths that only have layers
+
+    // Collect all parent layers that match the route's groups
+    const allLayers: FileRouter.RouteHandle[] = []
+    let currentPath = path
+
+    while (true) {
+      const pathData = routesByPath.get(currentPath)
+      if (pathData?.layers) {
+        const matchingLayers = pathData.layers.filter(layer =>
+          layerMatchesRoute(layer, route)
+        )
+        allLayers.unshift(...matchingLayers)
+      }
+
+      if (currentPath === "/") break
+
+      // Move to parent path
+      const parentPath = currentPath.substring(0, currentPath.lastIndexOf("/"))
+      currentPath = parentPath || "/"
+    }
+
+    // Generate segments array
+    const pathSegments = route.segments.filter(seg => !("handle" in seg))
+    const segmentsCode = pathSegments
+      .map(segmentToModuleSegment)
+      .filter(Boolean)
+      .join(",\n      ") + (pathSegments.length > 0 ? "," : "")
+
+    const segmentsArray = segmentsCode
+      ? `[\n      ${segmentsCode}\n    ]`
+      : "[]"
+
+    // Generate layers array
+    const layersCode = allLayers.length > 0
+      ? `\n    layers: [\n      ${
+        allLayers.map(layer => `() => import("./${layer.modulePath}")`).join(
+          ",\n      ",
+        )
+      },\n    ],`
+      : ""
+
+    const moduleCode = `  {
+    path: "${path}",
+    segments: ${segmentsArray},
+    load: () => import("./${route.modulePath}"),${layersCode}
+  },`
+
+    modules.push(moduleCode)
+  }
+
+  const header = `/**
+ * Auto-generated by effect-start.
+ */`
+
+  const modulesArray = modules.length > 0
+    ? `[\n${modules.join("\n")}\n]`
+    : "[]"
+
+  return `${header}
+
+import type { Router } from "${routerModuleId}"
+
+export const modules = ${modulesArray} as const
+`
+}
+
+/**
+ * Updates the manifest file only if the generated content differs from the existing file.
+ * This prevents infinite loops when watching for file changes.
+ */
+export function update(
+  routesPath: string,
+  manifestPath = "_manifest.ts",
+): Effect.Effect<void, PlatformError, FileSystem.FileSystem> {
+  return Effect.gen(function*() {
+    manifestPath = NPath.resolve(routesPath, manifestPath)
+
+    const fs = yield* FileSystem.FileSystem
+    const files = yield* fs.readDirectory(routesPath, { recursive: true })
+    const handles = FileRouter.getRouteHandlesFromPaths(files)
+
+    // Validate route modules
+    yield* validateRouteModules(routesPath, handles)
+
+    const newCode = generateCode(handles)
+
+    // Check if file exists and content differs
+    const existingCode = yield* fs
+      .readFileString(manifestPath)
+      .pipe(Effect.catchAll(() => Effect.succeed(null)))
+
+    if (existingCode !== newCode) {
+      yield* Effect.logDebug(`Updating file routes manifest: ${manifestPath}`)
+      yield* fs.writeFileString(manifestPath, newCode)
+    } else {
+      yield* Effect.logDebug(`File routes manifest unchanged: ${manifestPath}`)
+    }
+  })
+}
+
+export function dump(
+  routesPath: string,
+  manifestPath = "_manifest.ts",
+): Effect.Effect<void, PlatformError, FileSystem.FileSystem> {
+  return Effect.gen(function*() {
+    manifestPath = NPath.resolve(routesPath, manifestPath)
+
+    const fs = yield* FileSystem.FileSystem
+    const files = yield* fs.readDirectory(routesPath, { recursive: true })
+    const handles = FileRouter.getRouteHandlesFromPaths(files)
+
+    // Validate route modules
+    yield* validateRouteModules(routesPath, handles)
+
+    const code = generateCode(handles)
+
+    yield* Effect.logDebug(`Generating file routes manifest: ${manifestPath}`)
+
+    yield* fs.writeFileString(
+      manifestPath,
+      code,
+    )
+  })
+}

package/src/FileRouter_files.test.ts

@@ -0,0 +1,64 @@
+import * as t from "bun:test"
+import { MemoryFileSystem } from "effect-memfs"
+import * as Effect from "effect/Effect"
+import * as FileRouter from "./FileRouter.ts"
+import { effectFn } from "./testing.ts"
+
+const Files = {
+  "/routes/about/layer.tsx": "",
+  "/routes/about/route.tsx": "",
+  "/routes/users/route.tsx": "",
+  "/routes/users/layer.tsx": "",
+  "/routes/users/[userId]/route.tsx": "",
+  "/routes/layer.tsx": "",
+}
+
+const effect = effectFn()
+
+t.it("walks routes", () =>
+  effect(function*() {
+    const files = yield* FileRouter.walkRoutesDirectory("/routes").pipe(
+      Effect.provide(MemoryFileSystem.layerWith(Files)),
+    )
+
+    t
+      .expect(
+        files.map(v => v.modulePath),
+      )
+      .toEqual([
+        "layer.tsx",
+        "about/layer.tsx",
+        "about/route.tsx",
+        "users/layer.tsx",
+        "users/route.tsx",
+        "users/[userId]/route.tsx",
+      ])
+  }))
+
+t.it("walks routes with rest", () =>
+  effect(function*() {
+    const files = yield* FileRouter.walkRoutesDirectory("/routes").pipe(
+      Effect.provide(
+        MemoryFileSystem.layerWith({
+          ...Files,
+          "/routes/[[...rest]]/route.tsx": "",
+          "/routes/users/[...path]/route.tsx": "",
+        }),
+      ),
+    )
+
+    t
+      .expect(
+        files.map(v => v.modulePath),
+      )
+      .toEqual([
+        "layer.tsx",
+        "about/layer.tsx",
+        "about/route.tsx",
+        "users/layer.tsx",
+        "users/route.tsx",
+        "users/[userId]/route.tsx",
+        "users/[...path]/route.tsx",
+        "[[...rest]]/route.tsx",
+      ])
+  }))

package/src/FileRouter_path.test.ts

@@ -0,0 +1,132 @@
+import * as t from "bun:test"
+import * as FileRouter from "./FileRouter.ts"
+
+t.it("empty path as null", () => {
+  t.expect(FileRouter.segmentPath("")).toEqual([])
+  t.expect(FileRouter.segmentPath("/")).toEqual([])
+})
+
+t.it("literal segments", () => {
+  t.expect(FileRouter.segmentPath("users")).toEqual([{ literal: "users" }])
+  t.expect(FileRouter.segmentPath("/users")).toEqual([{ literal: "users" }])
+  t.expect(FileRouter.segmentPath("users/")).toEqual([{ literal: "users" }])
+  t.expect(FileRouter.segmentPath("/users/create")).toEqual([
+    { literal: "users" },
+    { literal: "create" },
+  ])
+  t.expect(() => FileRouter.segmentPath("path with spaces")).toThrow()
+})
+
+t.it("dynamic parameters", () => {
+  t.expect(FileRouter.segmentPath("[userId]")).toEqual([{ param: "userId" }])
+  t.expect(FileRouter.segmentPath("/users/[userId]")).toEqual([
+    { literal: "users" },
+    { param: "userId" },
+  ])
+  t
+    .expect(FileRouter.segmentPath("/posts/[postId]/comments/[commentId]"))
+    .toEqual([
+      { literal: "posts" },
+      { param: "postId" },
+      { literal: "comments" },
+      { param: "commentId" },
+    ])
+})
+
+t.it("rest parameters", () => {
+  t.expect(FileRouter.segmentPath("[[...rest]]")).toEqual([
+    { rest: "rest", optional: true },
+  ])
+  t.expect(FileRouter.segmentPath("[...rest]")).toEqual([{ rest: "rest" }])
+  t.expect(FileRouter.segmentPath("/docs/[[...slug]]")).toEqual([
+    { literal: "docs" },
+    { rest: "slug", optional: true },
+  ])
+  t.expect(FileRouter.segmentPath("/api/[...path]")).toEqual([
+    { literal: "api" },
+    { rest: "path" },
+  ])
+})
+
+t.it("groups", () => {
+  t.expect(FileRouter.segmentPath("(admin)")).toEqual([{ group: "admin" }])
+  t.expect(FileRouter.segmentPath("/(admin)/users")).toEqual([
+    { group: "admin" },
+    { literal: "users" },
+  ])
+  t.expect(FileRouter.segmentPath("(auth)/login/(step1)")).toEqual([
+    { group: "auth" },
+    { literal: "login" },
+    { group: "step1" },
+  ])
+})
+
+t.it("route handles", () => {
+  t.expect(FileRouter.segmentPath("route.ts")).toEqual([{ handle: "route" }])
+  t.expect(FileRouter.segmentPath("/api/route.js")).toEqual([
+    { literal: "api" },
+    { handle: "route" },
+  ])
+  t.expect(FileRouter.segmentPath("route.tsx")).toEqual([{ handle: "route" }])
+})
+
+t.it("layer handles", () => {
+  t.expect(FileRouter.segmentPath("layer.tsx")).toEqual([{ handle: "layer" }])
+  t.expect(FileRouter.segmentPath("layer.jsx")).toEqual([{ handle: "layer" }])
+  t.expect(FileRouter.segmentPath("layer.js")).toEqual([{ handle: "layer" }])
+  t.expect(FileRouter.segmentPath("/blog/layer.jsx")).toEqual([
+    { literal: "blog" },
+    { handle: "layer" },
+  ])
+})
+
+t.it("complex combinations", () => {
+  t.expect(FileRouter.segmentPath("/users/[userId]/posts/route.tsx")).toEqual([
+    { literal: "users" },
+    { param: "userId" },
+    { literal: "posts" },
+    { handle: "route" },
+  ])
+  t.expect(FileRouter.segmentPath("/api/v1/[[...path]]/route.ts")).toEqual([
+    { literal: "api" },
+    { literal: "v1" },
+    { rest: "path", optional: true },
+    { handle: "route" },
+  ])
+  t.expect(FileRouter.segmentPath("(admin)/users/route.tsx")).toEqual([
+    { group: "admin" },
+    { literal: "users" },
+    { handle: "route" },
+  ])
+})
+
+t.it("invalid paths", () => {
+  t.expect(() => FileRouter.segmentPath("$...")).toThrow()
+  t.expect(() => FileRouter.segmentPath("invalid%char")).toThrow()
+})
+
+t.it("param and rest types", () => {
+  t.expect(FileRouter.segmentPath("[a]")).toEqual([{ param: "a" }])
+  t.expect(FileRouter.segmentPath("[...rest]")).toEqual([{ rest: "rest" }])
+  t.expect(FileRouter.segmentPath("[[...rest]]")).toEqual([
+    { rest: "rest", optional: true },
+  ])
+})
+
+t.it("extractRoute - users/route.ts", () => {
+  t.expect(FileRouter.segmentPath("users/route.ts")).toEqual([
+    { literal: "users" },
+    { handle: "route" },
+  ])
+})
+
+t.it("segments with extensions", () => {
+  t.expect(FileRouter.segmentPath("events.json/route.ts")).toEqual([
+    { literal: "events.json" },
+    { handle: "route" },
+  ])
+  t.expect(FileRouter.segmentPath("config.yaml.backup/route.ts")).toEqual([
+    { literal: "config.yaml.backup" },
+    { handle: "route" },
+  ])
+})

package/src/FileRouter_tree.test.ts

@@ -0,0 +1,126 @@
+import * as t from "bun:test"
+import * as FileRouter from "./FileRouter.ts"
+
+t.it("tree with root only", () => {
+  const handles = [
+    "route.tsx",
+    "layer.tsx",
+  ]
+    .map(FileRouter.parseRoute)
+  const tree = FileRouter.treeFromRouteHandles(handles)
+
+  t.expect(tree).toEqual({
+    path: "/",
+    handles: [
+      t.expect.objectContaining({
+        handle: "route",
+      }),
+      t.expect.objectContaining({
+        handle: "layer",
+      }),
+    ],
+  })
+})
+
+t.it("tree without root", () => {
+  const handles = []
+    .map(FileRouter.parseRoute)
+  const tree = FileRouter.treeFromRouteHandles(handles)
+
+  t.expect(tree).toEqual({
+    path: "/",
+    handles: [],
+  })
+})
+
+t.it("deep tree", () => {
+  const handles = [
+    "users/route.tsx",
+    "users/layer.tsx",
+    "users/[userId]/route.tsx",
+    "layer.tsx",
+  ]
+    .map(FileRouter.parseRoute)
+  const tree = FileRouter.treeFromRouteHandles(handles)
+
+  t.expect(tree).toEqual({
+    path: "/",
+    handles: [
+      t.expect.objectContaining({
+        handle: "layer",
+      }),
+    ],
+    children: [
+      {
+        path: "/users",
+        handles: [
+          t.expect.objectContaining({
+            handle: "route",
+          }),
+          t.expect.objectContaining({
+            handle: "layer",
+          }),
+        ],
+        children: [
+          {
+            path: "/[userId]",
+            handles: [
+              t.expect.objectContaining({
+                handle: "route",
+              }),
+            ],
+          },
+        ],
+      },
+    ],
+  })
+})
+
+t.it("throws on overlapping routes from groups", () => {
+  t
+    .expect(() => {
+      const handles = [
+        "(admin)/users/route.tsx",
+        "users/route.tsx",
+      ]
+        .map(FileRouter.parseRoute)
+
+      FileRouter.getRouteHandlesFromPaths(
+        handles.map(h => h.modulePath),
+      )
+    })
+    .toThrow("Conflicting routes detected at path /users")
+})
+
+t.it("throws on overlapping routes with same path", () => {
+  t
+    .expect(() => {
+      const handles = [
+        "about/route.tsx",
+        "about/route.ts",
+      ]
+        .map(FileRouter.parseRoute)
+
+      FileRouter.getRouteHandlesFromPaths(
+        handles.map(h => h.modulePath),
+      )
+    })
+    .toThrow("Conflicting routes detected at path /about")
+})
+
+t.it("allows route and layer at same path", () => {
+  t
+    .expect(() => {
+      const handles = [
+        "users/route.tsx",
+        "users/layer.tsx",
+      ]
+        .map(FileRouter.parseRoute)
+
+      FileRouter.getRouteHandlesFromPaths(
+        handles.map(h => h.modulePath),
+      )
+    })
+    .not
+    .toThrow()
+})

package/src/FileSystemExtra.ts

@@ -0,0 +1,102 @@
+import * as Error from "@effect/platform/Error"
+import * as Effect from "effect/Effect"
+import * as Function from "effect/Function"
+import * as Stream from "effect/Stream"
+import type { WatchOptions } from "node:fs"
+import * as NFSP from "node:fs/promises"
+import * as NPath from "node:path"
+
+const SOURCE_FILENAME = /\.(tsx?|jsx?|html?|css|json)$/
+
+export type WatchEvent = {
+  eventType: "rename" | "change"
+  filename: string
+  path: string
+}
+
+/**
+ * Filter for source files based on file extension.
+ */
+export const filterSourceFiles = (event: WatchEvent): boolean => {
+  return SOURCE_FILENAME.test(event.path)
+}
+
+/**
+ * Filter for directories (paths ending with /).
+ */
+export const filterDirectory = (event: WatchEvent): boolean => {
+  return event.path.endsWith("/")
+}
+
+/**
+ * `@effect/platform` doesn't support recursive file watching.
+ * This function implements that [2025-05-19]
+ * Additionally, the filename is resolved to an absolute path.
+ * If the path is a directory, it appends / to the path.
+ */
+export const watchSource = (
+  opts?: WatchOptions & {
+    path?: string
+    filter?: (event: WatchEvent) => boolean
+  },
+): Stream.Stream<WatchEvent, Error.SystemError> => {
+  const baseDir = opts?.path ?? process.cwd()
+  const customFilter = opts?.filter
+
+  let stream: Stream.Stream<NFSP.FileChangeInfo<string>, Error.SystemError>
+  try {
+    stream = Stream.fromAsyncIterable(
+      NFSP.watch(baseDir, {
+        persistent: opts?.persistent ?? false,
+        recursive: opts?.recursive ?? true,
+        encoding: opts?.encoding,
+        signal: opts?.signal,
+      }),
+      error => handleWatchError(error, baseDir),
+    )
+  } catch (e) {
+    const err = handleWatchError(e, baseDir)
+
+    stream = Stream.fail(err)
+  }
+
+  const changes = Function.pipe(
+    stream,
+    Stream.mapEffect(e =>
+      Effect.promise(() => {
+        const resolvedPath = NPath.resolve(baseDir, e.filename!)
+        return NFSP
+          .stat(resolvedPath)
+          .then(stat => ({
+            eventType: e.eventType as "rename" | "change",
+            filename: e.filename!,
+            path: stat.isDirectory() ? `${resolvedPath}/` : resolvedPath,
+          }))
+          .catch(() => ({
+            eventType: e.eventType as "rename" | "change",
+            filename: e.filename!,
+            path: resolvedPath,
+          }))
+      })
+    ),
+    customFilter ? Stream.filter(customFilter) : Function.identity,
+    Stream.rechunk(1),
+    Stream.throttle({
+      units: 1,
+      cost: () => 1,
+      duration: "400 millis",
+      strategy: "enforce",
+    }),
+  )
+
+  return changes
+}
+
+const handleWatchError = (error: any, path: string) =>
+  new Error.SystemError({
+    module: "FileSystem",
+    reason: "Unknown",
+    method: "watch",
+    pathOrDescriptor: path,
+    cause: error,
+  })