@effect/platform-node-shared 4.0.0-beta.99 → 4.0.0-rc.109

package/ai-docs/src/51_http-server/fixtures/domain/User.ts

@@ -0,0 +1,21 @@
+import { Schema } from "effect"
+import { Model } from "effect/unstable/schema"
+
+export const UserId = Schema.String.pipe(Schema.brand("UserId"))
+export type UserId = typeof UserId.Type
+
+// `Model.Class` derives variants for the database (`User`, `User.insert`,
+// `User.update`) and the JSON API (`User.json`, `User.jsonCreate`,
+// `User.jsonUpdate`) from a single field declaration.
+export class User extends Model.Class<User>("User")({
+  // A UUID v4 primary key generated by the application on insert. It is
+  // excluded from the `jsonCreate` / `jsonUpdate` variants, so API clients can
+  // never set it.
+  id: Model.UuidV4Insert(UserId),
+  name: Schema.String,
+  email: Schema.String,
+  // Timestamps are managed by the model: set on insert, refreshed on update,
+  // and also excluded from the JSON create / update variants.
+  createdAt: Model.DateTimeInsert,
+  updatedAt: Model.DateTimeUpdate
+}) {}

package/ai-docs/src/51_http-server/fixtures/domain/UserErrors.ts

@@ -0,0 +1,22 @@
+import { Schema } from "effect"
+
+export class UserNotFound extends Schema.TaggedError<UserNotFound>()(
+  "UserNotFound",
+  {},
+  // You can specify the status code for this error inline
+  { httpApiStatus: 404 }
+) {}
+
+export class SearchQueryTooShort
+  extends Schema.TaggedError<SearchQueryTooShort>()("SearchQueryTooShort", {}, { httpApiStatus: 422 })
+{
+  static readonly minimumLength = 2
+}
+
+// Create a wrapper error class for all errors in the Users API.
+//
+// This prevents adding too many error types to services / endpoint definitions.
+//
+export class UsersError extends Schema.TaggedError<UsersError>()("UsersError", {
+  reason: Schema.Union([UserNotFound, SearchQueryTooShort])
+}) {}

package/ai-docs/src/51_http-server/fixtures/server/Authorization.ts

@@ -0,0 +1,37 @@
+import { DateTime, Effect, Layer, Redacted } from "effect"
+import { Authorization, CurrentUser, Unauthorized } from "../api/Authorization.ts"
+import { User, UserId } from "../domain/User.ts"
+
+const fixedTimestamp = DateTime.makeUnsafe("2026-01-01T00:00:00Z")
+const devUser = new User({
+  id: UserId.make("bf3dbe33-0ad2-4c9c-9c9e-733e57bdcbee"),
+  name: "Dev User",
+  email: "dev@acme.com",
+  createdAt: fixedTimestamp,
+  updatedAt: fixedTimestamp
+})
+
+// The implementation of the Authorization middleware. It is seperate from the
+// service definition to avoid leaking it into a client.
+export const AuthorizationLayer = Layer.effect(
+  Authorization,
+  Effect.gen(function*() {
+    // Here you could access services required by the middleware, like a
+    // database or an external auth provider.
+    yield* Effect.logInfo("Starting Authorization middleware")
+
+    return Authorization.of({
+      bearer: Effect.fn(function*(httpEffect, { credential }) {
+        // Validate the token and return an Unauthorized error if it's invalid.
+        const token = Redacted.value(credential)
+        if (token !== "dev-token") {
+          return yield* new Unauthorized({ message: "Missing or invalid bearer token" })
+        }
+
+        // Provide the current user to the rest of the stack. This will be
+        // available in any endpoint or middleware that runs after this one.
+        return yield* Effect.provideService(httpEffect, CurrentUser, devUser)
+      })
+    })
+  })
+)

package/ai-docs/src/51_http-server/fixtures/server/Users/http.ts

@@ -0,0 +1,80 @@
+import { Effect, Layer } from "effect"
+import { HttpApiBuilder, HttpApiError } from "effect/unstable/httpapi"
+import { Api } from "../../api/Api.ts"
+import { CurrentUser } from "../../api/Authorization.ts"
+import { AuthorizationLayer } from "../Authorization.ts"
+import { Users } from "../Users.ts"
+
+// The handlers without their dependencies provided, so tests can supply an
+// alternative `Users` implementation.
+export const UsersApiHandlersNoDeps = HttpApiBuilder.group(
+  Api,
+  "users",
+  Effect.fn(function*(handlers) {
+    const users = yield* Users
+
+    return handlers.handleAll({
+      list: ({ query }) =>
+        users.list(query.search).pipe(
+          // The list endpoint expects no errors, so we convert any potential
+          // errors into a 500 Internal Server Error.
+          Effect.orDie
+        ),
+      search: Effect.fn(function*({ payload }) {
+        if (payload.search === "bad-request") {
+          // You can use the built in error types like any other
+          // Schema.TaggedError
+          return yield* new HttpApiError.RequestTimeout()
+        }
+        return yield* users.list(payload.search).pipe(
+          Effect.catchReason(
+            "UsersError",
+            "SearchQueryTooShort",
+            // Re-fail the "SearchQueryTooShort" reason
+            Effect.fail,
+            // All other reasons are unexpected, so we convert them into a 500
+            // Internal Server Error.
+            Effect.die
+          )
+        )
+      }),
+      getById: ({ params }) =>
+        users.getById(params.id).pipe(
+          // You can also use Effect.catchReasons to handle multiple error
+          // reasons at once
+          Effect.catchReasons("UsersError", {
+            UserNotFound: (e) => Effect.fail(e)
+          }, Effect.die)
+        ),
+      create: ({ payload }) =>
+        users.create(payload).pipe(
+          Effect.orDie
+          // You could alse use Effect.unwrapReason to moves rror reasons up to
+          // the top level, so you can handle them with Effect.catch or
+          // Effect.catchTag etc.
+          //
+          // Effect.unwrapReason("UsersError"),
+          // Effect.catchTags({
+          //   UserNotFound: Effect.die,
+          //   SearchQueryTooShort: Effect.die
+          // })
+        ),
+      update: ({ params, payload }) =>
+        users.update(params.id, payload).pipe(
+          Effect.catchReasons("UsersError", {
+            UserNotFound: (e) => Effect.fail(e)
+          }, Effect.die)
+        ),
+      me: () =>
+        // The Authorization middleware provides the CurrentUser service, so we
+        // can access it here.
+        CurrentUser
+    })
+  })
+)
+
+// The handlers with all dependencies provided, ready to serve. The SQL-backed
+// `Users.layer` keeps the database wiring out of the server entrypoint.
+export const UsersApiHandlers = UsersApiHandlersNoDeps.pipe(
+  Layer.provide([Users.layer, AuthorizationLayer])
+)

package/ai-docs/src/51_http-server/fixtures/server/Users.ts

@@ -0,0 +1,183 @@
+import { SqliteClient, SqliteMigrator } from "@effect/sql-sqlite-node"
+import { Context, Effect, Layer, Schema } from "effect"
+import { SqlClient, SqlModel, SqlSchema } from "effect/unstable/sql"
+import { User } from "../domain/User.ts"
+import type { UserId } from "../domain/User.ts"
+import { SearchQueryTooShort, UserNotFound, UsersError } from "../domain/UserErrors.ts"
+
+// The SqlClient layer determines which database the SQL implementation talks
+// to. Swap it for another driver package to target a different database.
+const SqlLayer = SqliteClient.layer({ filename: ":memory:" })
+
+// Migrations are effects keyed by `<id>_<name>` that run once, in id order. A
+// real application would keep each migration in its own file and load them
+// with `SqliteMigrator.fromFileSystem` instead of an inline record.
+const MigratorLayer = SqliteMigrator.layer({
+  loader: SqliteMigrator.fromRecord({
+    "0001_create_users": Effect.gen(function*() {
+      const sql = yield* SqlClient.SqlClient
+      yield* sql`
+        CREATE TABLE users (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          email TEXT NOT NULL,
+          createdAt TEXT NOT NULL,
+          updatedAt TEXT NOT NULL
+        )
+      `
+    })
+  })
+})
+
+export class Users extends Context.Service<Users, {
+  list(search: string | undefined): Effect.Effect<Array<User>, UsersError>
+  getById(id: UserId): Effect.Effect<User, UsersError>
+  create(input: typeof User.jsonCreate.Type): Effect.Effect<User, UsersError>
+  update(id: UserId, input: typeof User.jsonUpdate.Type): Effect.Effect<User, UsersError>
+}>()("acme/Users") {
+  // The SQL implementation only requires a `SqlClient`, so entrypoints and
+  // tests decide how the database is provided.
+  static readonly layerNoDeps = Layer.effect(
+    Users,
+    Effect.gen(function*() {
+      const sql = yield* SqlClient.SqlClient
+
+      // CRUD goes through a repository derived from the `User` model. Each
+      // operation uses the matching model variant to encode its input and
+      // decodes rows with the full model schema.
+      const repo = yield* SqlModel.makeRepository(User, {
+        tableName: "users",
+        spanPrefix: "Users",
+        idColumn: "id"
+      })
+
+      // Queries the repository does not cover are written with the `sql` tag
+      // and decoded with the model schema.
+      const listAll = SqlSchema.findAll({
+        Request: Schema.Void,
+        Result: User,
+        execute: () => sql`SELECT * FROM users ORDER BY createdAt`
+      })
+
+      const searchUsers = SqlSchema.findAll({
+        Request: Schema.String,
+        Result: User,
+        execute: (search) => {
+          const pattern = `%${search}%`
+          return sql`SELECT * FROM users WHERE name LIKE ${pattern} OR email LIKE ${pattern}`
+        }
+      })
+
+      const list = Effect.fn("Users.list")(function*(search: string | undefined) {
+        if (search === undefined || search.length === 0) {
+          return yield* Effect.orDie(listAll())
+        } else if (search.length < SearchQueryTooShort.minimumLength) {
+          return yield* new UsersError({
+            reason: new SearchQueryTooShort()
+          })
+        }
+        yield* Effect.annotateCurrentSpan({ search })
+        return yield* Effect.orDie(searchUsers(search))
+      })
+
+      const getById = Effect.fn("Users.getById")((id: UserId) =>
+        repo.findById(id).pipe(
+          Effect.catchTags({
+            NoSuchElementError: () => new UsersError({ reason: new UserNotFound() }),
+            // Database and encoding failures are unexpected, so treat them as
+            // defects to keep the service interface focused on domain errors.
+            SchemaError: Effect.die,
+            SqlError: Effect.die
+          })
+        )
+      )
+
+      const create = Effect.fn("Users.create")((input: typeof User.jsonCreate.Type) =>
+        // `User.insert.makeEffect` fills in the generated id and timestamps
+        // using the Effect clock, so tests can control them with `TestClock`.
+        User.insert.makeEffect(input).pipe(
+          Effect.flatMap(repo.insert),
+          Effect.orDie
+        )
+      )
+
+      const update = Effect.fn("Users.update")(function*(id: UserId, input: typeof User.jsonUpdate.Type) {
+        // Ensure the user exists first, so a missing id fails with the domain
+        // error instead of a defect.
+        yield* getById(id)
+        const update = yield* User.update.makeEffect({ id, ...input }).pipe(Effect.orDie)
+        return yield* repo.update(update).pipe(Effect.orDie)
+      })
+
+      return Users.of({ list, getById, create, update })
+    })
+  )
+
+  // The fully provided SQL implementation: the database client and migrations
+  // are implementation details, so this layer requires nothing.
+  static readonly layer: Layer.Layer<Users> = this.layerNoDeps.pipe(
+    Layer.provide(MigratorLayer.pipe(Layer.provideMerge(SqlLayer))),
+    Layer.orDie
+  )
+
+  // An in-memory implementation for tests, so the HTTP stack can be exercised
+  // without a database.
+  static readonly layerMemory = Layer.effect(
+    Users,
+    Effect.gen(function*() {
+      const users = new Map<UserId, User>()
+
+      const makeUser = (input: typeof User.jsonCreate.Type) =>
+        User.insert.makeEffect(input).pipe(
+          Effect.map((user) => new User(user)),
+          Effect.orDie
+        )
+
+      const admin = yield* makeUser({ name: "Admin", email: "admin@acme.dev" })
+      users.set(admin.id, admin)
+
+      const list = Effect.fn("Users.list")(function*(search: string | undefined) {
+        const allUsers = Array.from(users.values())
+        if (search === undefined || search.length === 0) {
+          return allUsers
+        } else if (search.length < SearchQueryTooShort.minimumLength) {
+          return yield* new UsersError({
+            reason: new SearchQueryTooShort()
+          })
+        }
+        yield* Effect.annotateCurrentSpan({ search })
+        const normalized = search.toLowerCase()
+        return allUsers.filter((user) =>
+          user.name.toLowerCase().includes(normalized) || user.email.toLowerCase().includes(normalized)
+        )
+      })
+
+      const getById = Effect.fn("Users.getById")(function*(id: UserId) {
+        yield* Effect.annotateCurrentSpan({ id })
+        const user = users.get(id)
+        if (user === undefined) {
+          return yield* new UsersError({
+            reason: new UserNotFound()
+          })
+        }
+        return user
+      })
+
+      const create = Effect.fn("Users.create")(function*(input: typeof User.jsonCreate.Type) {
+        const user = yield* makeUser(input)
+        users.set(user.id, user)
+        return user
+      })
+
+      const update = Effect.fn("Users.update")(function*(id: UserId, input: typeof User.jsonUpdate.Type) {
+        const existing = yield* getById(id)
+        const update = yield* User.update.makeEffect({ id, ...input }).pipe(Effect.orDie)
+        const updated = new User({ ...existing, ...update })
+        users.set(id, updated)
+        return updated
+      })
+
+      return Users.of({ list, getById, create, update })
+    })
+  )
+}

package/ai-docs/src/51_http-server/index.md

@@ -0,0 +1,3 @@
+## Building HttpApi servers
+
+`HttpApi` gives you schema-first, type-safe HTTP APIs with runtime validation, typed clients, and OpenAPI docs from one definition.

package/ai-docs/src/60_child-process/10_working-with-child-processes.ts

@@ -0,0 +1,117 @@
+/**
+ * @title Working with child processes
+ *
+ * This example shows how to collect process output, compose pipelines, and stream long-running command output.
+ */
+import { NodeServices } from "@effect/platform-node"
+import { Console, Context, Effect, Layer, Schema, Stream, String } from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
+
+export class DevToolsError extends Schema.TaggedError<DevToolsError>()("DevToolsError", {
+  cause: Schema.Defect()
+}) {}
+
+export class DevTools extends Context.Service<DevTools, {
+  readonly nodeVersion: Effect.Effect<string, DevToolsError>
+  readonly recentCommitSubjects: Effect.Effect<ReadonlyArray<string>, DevToolsError>
+  readonly runLintFix: Effect.Effect<void, DevToolsError>
+  changedTypeScriptFiles(baseRef: string): Effect.Effect<ReadonlyArray<string>, DevToolsError>
+}>()("docs/DevTools") {
+  static readonly layer = Layer.effect(
+    DevTools,
+    Effect.gen(function*() {
+      // To run child processes, we need access to a `ChildProcessSpawner`.
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner
+
+      // Use `spawner.string` when you want to collect the entire output of a
+      // command as a string. This runs `node --version` and collects the
+      // output.
+      const nodeVersion = spawner.string(
+        ChildProcess.make("node", ["--version"])
+      ).pipe(
+        Effect.map(String.trim),
+        Effect.mapError((cause) => new DevToolsError({ cause }))
+      )
+
+      const changedTypeScriptFiles = Effect.fn("DevTools.changedTypeScriptFiles")(function*(baseRef: string) {
+        yield* Effect.annotateCurrentSpan({ baseRef })
+
+        // `spawner.lines` is a convenience helper for line-oriented command
+        // output.
+        const files = yield* spawner.lines(
+          ChildProcess.make("git", ["diff", "--name-only", `${baseRef}...HEAD`])
+        ).pipe(
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        return files.filter((file) => file.endsWith(".ts"))
+      })
+
+      // Build a pipeline from two command values. This runs:
+      // `git log --pretty=format:%s -n 20 | head -n 5`
+      const recentCommitSubjects = spawner.lines(
+        ChildProcess.make("git", ["log", "--pretty=format:%s", "-n", "20"]).pipe(
+          ChildProcess.pipeTo(ChildProcess.make("head", ["-n", "5"]))
+        )
+      ).pipe(
+        Effect.mapError((cause) => new DevToolsError({ cause }))
+      )
+
+      const runLintFix = Effect.gen(function*() {
+        // Use `spawn` when you want the process handle and stream output while
+        // the process is still running.
+        const handle = yield* spawner.spawn(
+          ChildProcess.make("pnpm", ["lint-fix"], {
+            env: { FORCE_COLOR: "1" },
+            extendEnv: true
+          })
+        ).pipe(
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        yield* handle.all.pipe(
+          Stream.decodeText(),
+          Stream.splitLines,
+          Stream.runForEach((line) => Console.log(`[lint-fix] ${line}`)),
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        const exitCode = yield* handle.exitCode.pipe(
+          Effect.mapError((cause) => new DevToolsError({ cause }))
+        )
+
+        if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+          return yield* new DevToolsError({
+            cause: new Error(`pnpm lint-fix failed with exit code ${exitCode}`)
+          })
+        }
+      }).pipe(
+        // `spawner.spawn` adds a `Scope` requirement to manage the lifecycle of
+        // the child process. We can use `Effect.scoped` to provide a `Scope`
+        // and close it when the effect completes.
+        Effect.scoped
+      )
+
+      return DevTools.of({
+        nodeVersion,
+        changedTypeScriptFiles,
+        recentCommitSubjects,
+        runLintFix
+      })
+    })
+  ).pipe(
+    // Provide the `ChildProcessSpawner` dependency from `NodeServices.layer`.
+    Layer.provide(NodeServices.layer)
+  )
+}
+
+export const program = Effect.gen(function*() {
+  const tools = yield* DevTools
+
+  const version = yield* tools.nodeVersion
+  yield* Effect.log(`node=${version}`)
+}).pipe(
+  // `ChildProcess` requires a platform implementation of
+  // `ChildProcessSpawner`. In Node.js, `NodeServices.layer` provides it.
+  Effect.provide(DevTools.layer)
+)

package/ai-docs/src/60_child-process/index.md

@@ -0,0 +1,3 @@
+## Working with child processes
+
+Use the `effect/unstable/process` modules to define child processes and run them with `ChildProcessSpawner`.

package/ai-docs/src/70_cli/10_basics.ts

@@ -0,0 +1,160 @@
+/**
+ * @title Getting started with Effect CLI modules
+ *
+ * Build a command-line app with typed arguments and flags, then wire subcommand
+ * handlers into a single executable command.
+ */
+import { NodeRuntime, NodeServices } from "@effect/platform-node"
+import { Console, Effect, Option, Schema } from "effect"
+import { Argument, Command, Flag } from "effect/unstable/cli"
+
+// You can define flags outside of commands and reuse them across multiple
+// commands.
+const workspace = Flag.string("workspace").pipe(
+  Flag.withAlias("w"),
+  Flag.withDescription("Workspace to operate on"),
+  Flag.withDefault("personal")
+)
+
+// Start with a root command and explicitly share the parent flags that should
+// be available to all subcommands.
+const tasks = Command.make("tasks").pipe(
+  Command.withSharedFlags({
+    workspace,
+    verbose: Flag.boolean("verbose").pipe(
+      Flag.withAlias("v"),
+      Flag.withDescription("Print diagnostic output")
+    )
+  }),
+  Command.withDescription("Track and manage tasks")
+)
+
+// Arguments and flags parse plain strings; use `withSchema` to validate or
+// transform the parsed value with any schema.
+const Email = Schema.String.pipe(
+  Schema.check(Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, {
+    message: "Expected a valid email address"
+  }))
+)
+
+const create = Command.make(
+  "create",
+  {
+    title: Argument.string("title").pipe(
+      Argument.withDescription("Task title"),
+      // Reject empty titles at parse time, so the handler only ever sees
+      // valid input
+      Argument.withSchema(Schema.NonEmptyString)
+    ),
+    priority: Flag.choice("priority", ["low", "normal", "high"]).pipe(
+      Flag.withDescription("Priority for the new task"),
+      Flag.withDefault("normal")
+    ),
+    assignee: Flag.string("assignee").pipe(
+      Flag.withDescription("Email address of the person to assign"),
+      Flag.withSchema(Email),
+      Flag.optional
+    )
+  },
+  Effect.fn(function*({ assignee, priority, title }) {
+    // Subcommands can read parent command input by yielding the parent command.
+    const root = yield* tasks
+
+    if (root.verbose) {
+      yield* Console.log(`workspace=${root.workspace} action=create`)
+    }
+
+    yield* Console.log(`Created "${title}" in ${root.workspace} with ${priority} priority`)
+
+    if (Option.isSome(assignee)) {
+      yield* Console.log(`Assigned to ${assignee.value}`)
+    }
+  })
+).pipe(
+  Command.withDescription("Create a task"),
+  Command.withExamples([
+    {
+      command: "tasks create \"Ship 4.0\" --priority high",
+      description: "Create a high-priority task"
+    },
+    {
+      command: "tasks create \"Ship 4.0\" --assignee dev@acme.com",
+      description: "Create a task assigned to a team member"
+    }
+  ])
+)
+
+const list = Command.make(
+  "list",
+  {
+    status: Flag.choice("status", ["open", "done", "all"]).pipe(
+      Flag.withDescription("Filter tasks by status"),
+      Flag.withDefault("open")
+    ),
+    json: Flag.boolean("json").pipe(
+      Flag.withDescription("Print machine-readable output")
+    )
+  },
+  Effect.fn(function*({ status, json }) {
+    const root = yield* tasks
+    const items = [
+      { title: "Ship 4.0", status: "open" },
+      { title: "Update onboarding guide", status: "done" }
+    ] as const
+    const filtered = status === "all"
+      ? items
+      : items.filter((item) => item.status === status)
+
+    if (root.verbose) {
+      yield* Console.log(`workspace=${root.workspace} action=list`)
+    }
+
+    if (json) {
+      yield* Console.log(JSON.stringify(
+        {
+          workspace: root.workspace,
+          status,
+          items: filtered
+        },
+        null,
+        2
+      ))
+      return
+    }
+
+    yield* Console.log(`Listing ${status} tasks in ${root.workspace}`)
+    if (filtered.length === 0) {
+      yield* Console.log("- No tasks found")
+      return
+    }
+
+    for (const item of filtered) {
+      yield* Console.log(`- ${item.title}`)
+    }
+  })
+).pipe(
+  Command.withDescription("List tasks"),
+  Command.withAlias("ls"),
+  Command.withExamples([
+    {
+      command: "tasks --workspace team-a list --status open",
+      description: "List open tasks in a specific workspace"
+    },
+    {
+      command: "tasks --workspace team-b ls --status open",
+      description: "List open tasks in another workspace"
+    }
+  ])
+)
+
+// Finally, compose the subcommands into a single command and then run it.
+tasks.pipe(
+  Command.withSubcommands([create, list]),
+  Command.run({
+    version: "1.0.0"
+  }),
+  // Provide the services for the platform you are targeting. In this case,
+  // Node.js
+  Effect.provide(NodeServices.layer),
+  NodeRuntime.runMain
+)

package/ai-docs/src/70_cli/index.md

@@ -0,0 +1,5 @@
+## Building CLI applications
+
+Use the "effect/unstable/cli" modules to build CLI applications. These modules
+provide utilities for parsing command-line arguments, handling user input, and
+managing the flow of a CLI application.