@effect/platform-node 4.0.0-rc.108 → 4.0.0-rc.109

package/AGENTS.md

@@ -327,6 +327,17 @@ if (Predicate.isObject(thing)) {
 }
 ```
 
+## Working with SQL databases
+
+Use the `effect/unstable/sql` modules together with a driver package such as
+`@effect/sql-sqlite-node` to access SQL databases. Define domain models with
+`Model.Class` to derive schemas for the database and JSON boundaries, run
+migrations, and write type-safe queries.
+
+- **[Getting started with SQL](./ai-docs/src/40_sql/10_basics.ts)**:
+  Define a schema-backed domain model, run migrations against a SQLite
+  database, and expose a derived repository through a service.
+
 ## Effect HttpClient
 
 Build http clients with the `HttpClient` module.
@@ -340,6 +351,9 @@ Build http clients with the `HttpClient` module.
 - **[Getting started with HttpApi](./ai-docs/src/51_http-server/10_basics.ts)**:
   Define a schema-first API, implement handlers, secure endpoints with
   middleware, serve it over HTTP, and call it using a generated typed client.
+- **[Testing HttpApi implementations](./ai-docs/src/51_http-server/20_testing.ts)**:
+  Test handlers through an in-memory typed client with `HttpApiTest`, without
+  starting an HTTP server or touching a real database.
 
 ## Working with child processes
 

package/CLAUDE.md

@@ -327,6 +327,17 @@ if (Predicate.isObject(thing)) {
 }
 ```
 
+## Working with SQL databases
+
+Use the `effect/unstable/sql` modules together with a driver package such as
+`@effect/sql-sqlite-node` to access SQL databases. Define domain models with
+`Model.Class` to derive schemas for the database and JSON boundaries, run
+migrations, and write type-safe queries.
+
+- **[Getting started with SQL](./ai-docs/src/40_sql/10_basics.ts)**:
+  Define a schema-backed domain model, run migrations against a SQLite
+  database, and expose a derived repository through a service.
+
 ## Effect HttpClient
 
 Build http clients with the `HttpClient` module.
@@ -340,6 +351,9 @@ Build http clients with the `HttpClient` module.
 - **[Getting started with HttpApi](./ai-docs/src/51_http-server/10_basics.ts)**:
   Define a schema-first API, implement handlers, secure endpoints with
   middleware, serve it over HTTP, and call it using a generated typed client.
+- **[Testing HttpApi implementations](./ai-docs/src/51_http-server/20_testing.ts)**:
+  Test handlers through an in-memory typed client with `HttpApiTest`, without
+  starting an HTTP server or touching a real database.
 
 ## Working with child processes
 

package/README.md

@@ -5,7 +5,7 @@
 ## Installation
 
 ```sh
-npm install effect@beta @effect/platform-node@beta
+npm install effect@rc @effect/platform-node@rc
 ```
 
 ## Documentation

package/ai-docs/src/40_sql/10_basics.ts

@@ -0,0 +1,175 @@
+/**
+ * @title Getting started with SQL
+ *
+ * Define a schema-backed domain model, run migrations against a SQLite
+ * database, and expose a derived repository through a service.
+ */
+import { NodeRuntime } from "@effect/platform-node"
+import { SqliteClient, SqliteMigrator } from "@effect/sql-sqlite-node"
+import { Context, Effect, Layer, Schema } from "effect"
+import { Model } from "effect/unstable/schema"
+import { SqlClient, SqlModel, SqlSchema } from "effect/unstable/sql"
+
+// Use a branded string for the group id, so it cannot be mixed up with other
+// string ids in the application.
+export const GroupId = Schema.String.pipe(Schema.brand("GroupId"))
+export type GroupId = typeof GroupId.Type
+
+// `Model.Class` defines a domain model with variants for the database and JSON
+// boundaries. The single field declaration is the source of truth, and each
+// variant only contains the fields that make sense for that operation:
+//
+// - `Group` / `Group.insert` / `Group.update` for the database
+// - `Group.json` / `Group.jsonCreate` / `Group.jsonUpdate` for JSON APIs
+export class Group extends Model.Class<Group>("Group")({
+  // A UUID v4 primary key that is generated by the application on insert
+  id: Model.UuidV4Insert(GroupId),
+  name: Schema.NonEmptyString,
+  // `Model.FieldExcept` removes a field from the given variants. The slug is
+  // chosen when the group is created and is immutable afterwards, so it is
+  // removed from the update variants.
+  slug: Schema.NonEmptyString.pipe(Model.FieldExcept(["update", "jsonUpdate"])),
+  // `Model.FieldOnly` keeps a field in only the given variants. Internal notes
+  // live in the database and are never exposed through the JSON variants.
+  notes: Schema.NullOr(Schema.String).pipe(Model.FieldOnly(["select", "insert"])),
+  // `Model.Field` gives full control over the individual variants. The member
+  // count is maintained by the database, so the application can read it but
+  // never writes it.
+  memberCount: Model.Field({
+    select: Schema.Int,
+    json: Schema.Int
+  }),
+  // `createdAt` is set to the current time on insert, and `updatedAt` is
+  // refreshed on every update. Both are stored as strings, which suits SQLite.
+  createdAt: Model.DateTimeInsert,
+  updatedAt: Model.DateTimeUpdate
+}) {}
+
+export class GroupNotFound extends Schema.TaggedError<GroupNotFound>()("GroupNotFound", {
+  id: GroupId
+}) {}
+
+// The SqlClient layer determines which database you are talking to. Swap this
+// layer for `@effect/sql-pg`, `@effect/sql-mysql2` etc. to target another
+// database without changing the rest of the code.
+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_groups": Effect.gen(function*() {
+      const sql = yield* SqlClient.SqlClient
+      yield* sql`
+        CREATE TABLE groups (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          slug TEXT NOT NULL,
+          notes TEXT,
+          memberCount INTEGER NOT NULL DEFAULT 0,
+          createdAt TEXT NOT NULL,
+          updatedAt TEXT NOT NULL
+        )
+      `
+    })
+  })
+})
+
+// Combine the database client with the migrations, so anything built on top of
+// `SqlLive` sees a fully migrated database.
+const SqlLive = MigratorLayer.pipe(Layer.provideMerge(SqlLayer))
+
+// Wrap data access in a service, so the rest of the application depends on
+// `Groups` instead of the database directly.
+export class Groups extends Context.Service<Groups, {
+  create(name: string, slug: string): Effect.Effect<Group>
+  rename(id: GroupId, name: string): Effect.Effect<Group, GroupNotFound>
+  findById(id: GroupId): Effect.Effect<Group, GroupNotFound>
+  readonly list: Effect.Effect<Array<Group>>
+}>()("app/Groups") {
+  static readonly layer = Layer.effect(
+    Groups,
+    Effect.gen(function*() {
+      const sql = yield* SqlClient.SqlClient
+
+      // `SqlModel.makeRepository` derives insert / update / findById / delete
+      // operations from the model, using the matching variant schema for each
+      // operation.
+      const repo = yield* SqlModel.makeRepository(Group, {
+        tableName: "groups",
+        spanPrefix: "Groups",
+        idColumn: "id"
+      })
+
+      // For queries the repository does not cover, combine the `sql` tag with
+      // `SqlSchema` to decode the rows using the model schema.
+      const listAll = SqlSchema.findAll({
+        Request: Schema.Void,
+        Result: Group,
+        execute: () => sql`SELECT * FROM groups ORDER BY createdAt`
+      })
+
+      // Use `Effect.fn` to give each method a named span for observability.
+      const create = Effect.fn("Groups.create")((name: string, slug: string) =>
+        // `Group.insert.makeEffect` fills in the generated id and timestamps
+        // using the Effect clock, so tests can control them with `TestClock`.
+        Group.insert.makeEffect({ name, slug, notes: null }).pipe(
+          Effect.flatMap(repo.insert),
+          // Database and encoding failures are unexpected here, so treat
+          // them as defects to keep the service interface focused on domain
+          // errors.
+          Effect.orDie
+        )
+      )
+
+      const rename = Effect.fn("Groups.rename")((id: GroupId, name: string) =>
+        Group.update.makeEffect({ id, name }).pipe(
+          Effect.flatMap(repo.update),
+          Effect.orDie
+        )
+      )
+
+      const findById = Effect.fn("Groups.findById")((id: GroupId) =>
+        repo.findById(id).pipe(
+          Effect.catchTags({
+            NoSuchElementError: () => new GroupNotFound({ id }),
+            SchemaError: Effect.die,
+            SqlError: Effect.die
+          })
+        )
+      )
+
+      const list = listAll().pipe(
+        Effect.orDie,
+        Effect.withSpan("Groups.list")
+      )
+
+      return Groups.of({ create, rename, findById, list })
+    })
+  ).pipe(
+    // Provide the layers locally, so lots of messy wiring doesn't need to
+    // happen in the "main" entrypoint of the application.
+    Layer.provide(SqlLive)
+  )
+}
+
+const program = Effect.gen(function*() {
+  const groups = yield* Groups
+
+  const engineering = yield* groups.create("Engineering", "engineering")
+  const design = yield* groups.create("Design", "design")
+
+  yield* groups.rename(design.id, "Product Design")
+
+  const found = yield* groups.findById(engineering.id)
+  yield* Effect.log("found group", found)
+
+  const all = yield* groups.list
+  yield* Effect.log(`total groups: ${all.length}`)
+})
+
+program.pipe(
+  Effect.provide(Groups.layer),
+  NodeRuntime.runMain
+)

package/ai-docs/src/40_sql/index.md

@@ -0,0 +1,6 @@
+## Working with SQL databases
+
+Use the `effect/unstable/sql` modules together with a driver package such as
+`@effect/sql-sqlite-node` to access SQL databases. Define domain models with
+`Model.Class` to derive schemas for the database and JSON boundaries, run
+migrations, and write type-safe queries.

package/ai-docs/src/51_http-server/10_basics.ts

@@ -24,7 +24,9 @@ const SystemApiHandlers = HttpApiBuilder.group(
   Api,
   "system",
   Effect.fn(function*(handlers) {
-    return handlers.handle("health", () => Effect.void)
+    return handlers.handleAll({
+      health: () => Effect.void
+    })
   })
 )
 

package/ai-docs/src/51_http-server/20_testing.ts

@@ -0,0 +1,100 @@
+/**
+ * @title Testing HttpApi implementations
+ *
+ * Test handlers through an in-memory typed client with `HttpApiTest`, without
+ * starting an HTTP server or touching a real database.
+ */
+import { assert, layer } from "@effect/vitest"
+import { Effect, Layer } from "effect"
+import { HttpClientRequest, HttpServer } from "effect/unstable/http"
+import { HttpApiMiddleware, HttpApiTest } from "effect/unstable/httpapi"
+import { Api } from "./fixtures/api/Api.ts"
+import { Authorization } from "./fixtures/api/Authorization.ts"
+import { UserId } from "./fixtures/domain/User.ts"
+import { AuthorizationLayer } from "./fixtures/server/Authorization.ts"
+import { Users } from "./fixtures/server/Users.ts"
+import { UsersApiHandlersNoDeps } from "./fixtures/server/Users/http.ts"
+
+// Provide the handlers with the in-memory `Users` implementation, so the full
+// HTTP pipeline is exercised without any SQL. The Authorization middleware is
+// provided with `Layer.provideMerge`, because the HTTP pipeline also resolves
+// it when the routes are built.
+const HandlersLayer = UsersApiHandlersNoDeps.pipe(
+  Layer.provide(Users.layerMemory),
+  Layer.provideMerge(AuthorizationLayer)
+)
+
+// The client-side Authorization middleware supplies the bearer token.
+// Providing different middleware implementations lets the tests cover both
+// authorized and unauthorized requests.
+const AuthorizationMiddlewareGood = HttpApiMiddleware.layerClient(
+  Authorization,
+  ({ next, request }) => next(HttpClientRequest.bearerToken(request, "dev-token"))
+)
+
+const AuthorizationMiddlewareBad = HttpApiMiddleware.layerClient(
+  Authorization,
+  // Forward the request without attaching a token
+  ({ next, request }) => next(request)
+)
+
+// `HttpApiTest.groups` builds a typed client wired directly to the handlers of
+// the selected groups, using the same request encoding, routing, and response
+// decoding as a real server.
+const makeClient = HttpApiTest.groups(Api, ["users"])
+
+// `HttpServer.layerServices` provides the platform services the HTTP pipeline
+// needs in tests.
+layer(Layer.mergeAll(HandlersLayer, HttpServer.layerServices))("UsersApi", (it) => {
+  it.effect("lists, fetches, and creates users", () =>
+    Effect.gen(function*() {
+      const client = yield* makeClient
+
+      const created = yield* client.users.create({
+        payload: { name: "Alice", email: "alice@acme.dev" }
+      })
+      assert.strictEqual(created.name, "Alice")
+
+      const fetched = yield* client.users.getById({
+        params: { id: created.id }
+      })
+      assert.deepStrictEqual(fetched, created)
+
+      const all = yield* client.users.list({ query: {} })
+      assert.isTrue(all.some((user) => user.id === created.id))
+    }).pipe(Effect.provide(AuthorizationMiddlewareGood)))
+
+  it.effect("returns a 404 for a missing user", () =>
+    Effect.gen(function*() {
+      const client = yield* makeClient
+
+      // Use Effect.flip to assert on the error channel
+      const error = yield* client.users.getById({
+        params: { id: UserId.make("019845e1-682f-4b02-a706-3b2422d13aec") }
+      }).pipe(Effect.flip)
+      assert.strictEqual(error._tag, "UserNotFound")
+    }).pipe(Effect.provide(AuthorizationMiddlewareGood)))
+
+  it.effect("rejects requests without a valid bearer token", () =>
+    Effect.gen(function*() {
+      const client = yield* makeClient
+
+      const error = yield* client.users.list({ query: {} }).pipe(Effect.flip)
+      assert.strictEqual(error._tag, "Unauthorized")
+    }).pipe(Effect.provide(AuthorizationMiddlewareBad)))
+
+  it.effect("rejects requests with an invalid bearer token", () =>
+    Effect.gen(function*() {
+      const client = yield* makeClient
+
+      const error = yield* client.users.getById({
+        params: { id: UserId.make("019845e1-682f-4b02-a706-3b2422d13aec") }
+      }).pipe(Effect.flip)
+      assert.strictEqual(error._tag, "Unauthorized")
+    }).pipe(
+      Effect.provide(HttpApiMiddleware.layerClient(
+        Authorization,
+        ({ next, request }) => next(HttpClientRequest.bearerToken(request, "wrong-token"))
+      ))
+    ))
+})

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

@@ -10,7 +10,10 @@ export class UsersApiGroup extends HttpApiGroup.make("users")
       query: {
         search: Schema.optional(Schema.String)
       },
-      success: Schema.Array(User)
+      // Use the `json` variant of the model for API responses. It shares the
+      // field declarations with the database variants, but can encode values
+      // differently where needed.
+      success: Schema.Array(User.json)
     }),
     HttpApiEndpoint.get("search", "/search", {
       // For get requests, payload uses the query string
@@ -18,7 +21,7 @@ export class UsersApiGroup extends HttpApiGroup.make("users")
         search: Schema.String
       },
       success: [
-        Schema.Array(User),
+        Schema.Array(User.json),
         Schema.String.pipe(HttpApiSchema.asText({
           contentType: "text/csv"
         }))
@@ -39,13 +42,12 @@ export class UsersApiGroup extends HttpApiGroup.make("users")
     }),
     HttpApiEndpoint.get("getById", "/:id", {
       params: {
-        // Path parameter schemas need to be able to decode from strings.
-        // Schema.decodeTo can be used to "bridge" between schemas
-        id: Schema.FiniteFromString.pipe(
-          Schema.decodeTo(UserId)
-        )
+        // Path parameter values are automatically coerced from their string
+        // form using `Schema.toCodecStringTree`, so schemas that decode from
+        // other types (like numbers) work here as well.
+        id: UserId
       },
-      success: User,
+      success: User.json,
       error: UserNotFound.pipe(
         // If you want an error to return no content, you can use
         // `HttpApiSchema.asNoContent` and provide a decoder that transforms the
@@ -59,14 +61,28 @@ export class UsersApiGroup extends HttpApiGroup.make("users")
       // For post requests, payload uses the request body. It defaults to JSON,
       // but you can specify other content types as well using
       // `HttpApiSchema.asText`, `HttpApiSchema.asMultipart`, etc.
-      payload: Schema.Struct({
-        name: Schema.String,
-        email: Schema.String
-      }),
-      success: User
+      //
+      // The `jsonCreate` variant only exposes the fields clients are allowed
+      // to provide, so the generated id and timestamps cannot be set here.
+      payload: User.jsonCreate,
+      success: User.json
+    }),
+    HttpApiEndpoint.patch("update", "/:id", {
+      params: {
+        id: UserId
+      },
+      // The `jsonUpdate` variant similarly excludes the id and the managed
+      // timestamps from the update payload.
+      payload: User.jsonUpdate,
+      success: User.json,
+      error: UserNotFound.pipe(
+        HttpApiSchema.asNoContent({
+          decode: () => new UserNotFound()
+        })
+      )
     }),
     HttpApiEndpoint.get("me", "/me", {
-      success: User,
+      success: User.json,
       error: UserNotFound.pipe(HttpApiSchema.status(404))
     })
   )

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

@@ -1,12 +1,21 @@
 import { Schema } from "effect"
+import { Model } from "effect/unstable/schema"
 
-export const UserId = Schema.Int.pipe(
-  Schema.brand("UserId")
-)
+export const UserId = Schema.String.pipe(Schema.brand("UserId"))
 export type UserId = typeof UserId.Type
 
-export class User extends Schema.Class<User>("User")({
-  id: UserId,
+// `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
+  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/server/Authorization.ts

@@ -1,7 +1,16 @@
-import { Effect, Layer, Redacted } from "effect"
+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(
@@ -21,15 +30,7 @@ export const AuthorizationLayer = Layer.effect(
 
         // 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,
-          new User({
-            id: UserId.make(1),
-            name: "Dev User",
-            email: "dev@acme.com"
-          })
-        )
+        return yield* Effect.provideService(httpEffect, CurrentUser, devUser)
       })
     })
   })

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

@@ -5,49 +5,48 @@ import { CurrentUser } from "../../api/Authorization.ts"
 import { AuthorizationLayer } from "../Authorization.ts"
 import { Users } from "../Users.ts"
 
-export const UsersApiHandlers = HttpApiBuilder.group(
+// 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
-      .handle("list", ({ query }) =>
+    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
-        ))
-      .handle(
-        "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
-            )
+        ),
+      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
           )
-        })
-      )
-      .handle("getById", ({ params }) =>
+        )
+      }),
+      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)
-        ))
-      .handle("create", ({ payload }) =>
+        ),
+      create: ({ payload }) =>
         users.create(payload).pipe(
           Effect.orDie
           // You could alse use Effect.unwrapReason to moves rror reasons up to
@@ -59,13 +58,23 @@ export const UsersApiHandlers = HttpApiBuilder.group(
           //   UserNotFound: Effect.die,
           //   SearchQueryTooShort: Effect.die
           // })
-        ))
-      .handle("me", () =>
+        ),
+      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)
+        CurrentUser
+    })
   })
-).pipe(
-  // Provide the dependencies for the handlers.
+)
+
+// 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

@@ -1,28 +1,142 @@
-import { Context, Effect, Layer, Ref } from "effect"
-import { User, UserId } from "../domain/User.ts"
+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: { readonly name: string; readonly email: string }): 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") {
-  static readonly layer = Layer.effect(
+  // 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 users = new Map<number, User>([
-        [
-          1,
-          new User({
-            id: UserId.make(1),
-            name: "Admin",
-            email: "admin@acme.dev"
+      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()
           })
-        ]
-      ])
-      const nextId = yield* Ref.make(2)
+        }
+        yield* Effect.annotateCurrentSpan({ search })
+        return yield* Effect.orDie(searchUsers(search))
+      })
 
-      const list = Effect.fn("UsersRepo.list")(function*(search: string | undefined) {
+      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
@@ -38,7 +152,7 @@ export class Users extends Context.Service<Users, {
         )
       })
 
-      const getById = Effect.fn("UsersRepo.getById")(function*(id: UserId) {
+      const getById = Effect.fn("Users.getById")(function*(id: UserId) {
         yield* Effect.annotateCurrentSpan({ id })
         const user = users.get(id)
         if (user === undefined) {
@@ -49,14 +163,21 @@ export class Users extends Context.Service<Users, {
         return user
       })
 
-      const create = Effect.fn("UsersRepo.create")(function*(input: { readonly name: string; readonly email: string }) {
-        const id = yield* Ref.getAndUpdate(nextId, (current) => current + 1)
-        const user = new User({ id: UserId.make(id), ...input })
+      const create = Effect.fn("Users.create")(function*(input: typeof User.jsonCreate.Type) {
+        const user = yield* makeUser(input)
         users.set(user.id, user)
         return user
       })
 
-      return Users.of({ list, getById, create })
+      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/70_cli/10_basics.ts

@@ -5,7 +5,7 @@
  * handlers into a single executable command.
  */
 import { NodeRuntime, NodeServices } from "@effect/platform-node"
-import { Console, Effect } from "effect"
+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
@@ -29,18 +29,34 @@ const tasks = Command.make("tasks").pipe(
   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")
+      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*({ title, priority }) {
+  Effect.fn(function*({ assignee, priority, title }) {
     // Subcommands can read parent command input by yielding the parent command.
     const root = yield* tasks
 
@@ -49,6 +65,10 @@ const create = Command.make(
     }
 
     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"),
@@ -56,6 +76,10 @@ const create = Command.make(
     {
       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"
     }
   ])
 )

package/dist/NodeRedis.d.ts

@@ -1,11 +1,12 @@
 /**
- * Node.js Redis integration backed by `ioredis`.
+ * Node.js Redis integration backed by `redis` (node-redis).
  *
- * This module creates a scoped `ioredis` client and exposes it in two forms:
+ * This module creates a scoped `node-redis` client and exposes it in two forms:
  * the generic `Redis` service and the {@link NodeRedis} service for direct
- * access to the underlying client. `layer` accepts ioredis options directly,
- * while `layerConfig` reads them from Effect config. Both layers close the
- * client when the layer scope ends.
+ * access to the underlying client. `layer` accepts node-redis client options
+ * directly, while `layerConfig` reads them from Effect config. `node-redis`
+ * connects explicitly, so layer construction can fail with a `RedisError`.
+ * Both layers close the client when the layer scope ends.
  *
  * @since 4.0.0
  */
@@ -14,14 +15,16 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Redis from "effect/unstable/persistence/Redis";
-import * as IoRedis from "ioredis";
+import { createClient } from "redis";
+type NodeRedisClient = ReturnType<typeof createClient>;
+type NodeRedisClientOptions = NonNullable<Parameters<typeof createClient>[0]>;
 declare const NodeRedis_base: Context.ServiceClass<NodeRedis, "@effect/platform-node/NodeRedis", {
-    readonly client: IoRedis.Redis;
-    readonly use: <A>(f: (client: IoRedis.Redis) => Promise<A>) => Effect.Effect<A, Redis.RedisError>;
+    readonly client: NodeRedisClient;
+    readonly use: <A>(f: (client: NodeRedisClient) => Promise<A>) => Effect.Effect<A, Redis.RedisError>;
 }>;
 /**
  * Service tag for the Node Redis integration, exposing the underlying
- * `ioredis` client and a `use` helper that maps client failures to
+ * `node-redis` client and a `use` helper that maps client failures to
  * `RedisError`.
  *
  * @category services
@@ -30,20 +33,42 @@ declare const NodeRedis_base: Context.ServiceClass<NodeRedis, "@effect/platform-
 export declare class NodeRedis extends NodeRedis_base {
 }
 /**
- * Provides `Redis` and `NodeRedis` services backed by an `ioredis` client
- * created with the supplied options and closed when the layer scope ends.
+ * Provides `Redis` and `NodeRedis` services backed by a `node-redis` client
+ * created with the supplied options, connected when the layer is built and
+ * closed when the layer scope ends.
+ *
+ * **Details**
+ *
+ * By default, the initial connection fails on its first connection error. A
+ * caller-supplied `socket.reconnectStrategy` is used instead when present. Once
+ * the client has emitted `ready`, the default reconnect strategy uses
+ * node-redis' exponential backoff and stops on socket timeouts.
+ *
+ * Scope finalization calls `close()`, which waits for in-flight commands,
+ * including blocking commands, and can therefore delay scope closure.
  *
  * @category layers
  * @since 4.0.0
  */
-export declare const layer: (options?: IoRedis.RedisOptions | undefined) => Layer.Layer<Redis.Redis | NodeRedis>;
+export declare const layer: (options?: NodeRedisClientOptions | undefined) => Layer.Layer<Redis.Redis | NodeRedis, Redis.RedisError>;
 /**
- * Provides `Redis` and `NodeRedis` services from `Config`-backed ioredis
- * options, closing the client when the layer scope ends.
+ * Provides `Redis` and `NodeRedis` services from `Config`-backed node-redis
+ * client options, connecting the client when the layer is built and closing it
+ * when the layer scope ends.
+ *
+ * **Details**
+ *
+ * By default, the initial connection fails on its first connection error. A
+ * caller-supplied `socket.reconnectStrategy` is used instead when present. Once
+ * the client has emitted `ready`, the default reconnect strategy uses
+ * node-redis' exponential backoff and stops on socket timeouts.
+ *
+ * Scope finalization calls `close()`, which waits for in-flight commands,
+ * including blocking commands, and can therefore delay scope closure.
  *
  * @category layers
  * @since 4.0.0
  */
-export declare const layerConfig: (options: Config.Wrap<IoRedis.RedisOptions>) => Layer.Layer<Redis.Redis | NodeRedis, Config.ConfigError>;
+export declare const layerConfig: (options: Config.Wrap<NodeRedisClientOptions>) => Layer.Layer<Redis.Redis | NodeRedis, Redis.RedisError | Config.ConfigError>;
 export {};
 //# sourceMappingURL=NodeRedis.d.ts.map

package/dist/NodeRedis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeRedis.d.ts","sourceRoot":"","sources":["../src/NodeRedis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,KAAK,KAAK,MAAM,mCAAmC,CAAA;AAC1D,OAAO,KAAK,OAAO,MAAM,SAAS,CAAA;;qBAWf,OAAO,CAAC,KAAK;kBAChB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC;;AAVnG;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,cAGQ;CAAG;AAiC1C;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,aACN,OAAO,CAAC,YAAY,GAAG,SAAS,KACzC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,CAAuC,CAAA;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,CACxB,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,KACvC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,EAAE,MAAM,CAAC,WAAW,CAOzD,CAAA"}
+{"version":3,"file":"NodeRedis.d.ts","sourceRoot":"","sources":["../src/NodeRedis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,KAAK,MAAM,mCAAmC,CAAA;AAC1D,OAAO,EAAE,YAAY,EAAsB,MAAM,OAAO,CAAA;AAExD,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAA;AACtD,KAAK,sBAAsB,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;;qBAW1D,eAAe;kBAClB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC;;AAVrG;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,cAGQ;CAAG;AAoE1C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,aACN,sBAAsB,GAAG,SAAS,KAC3C,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,EAAE,KAAK,CAAC,UAAU,CAAuC,CAAA;AAE/F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,WAAW,EAAE,CACxB,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,KACzC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,EAAE,KAAK,CAAC,UAAU,GAAG,MAAM,CAAC,WAAW,CAO5E,CAAA"}

package/dist/NodeRedis.js

@@ -1,11 +1,12 @@
 /**
- * Node.js Redis integration backed by `ioredis`.
+ * Node.js Redis integration backed by `redis` (node-redis).
  *
- * This module creates a scoped `ioredis` client and exposes it in two forms:
+ * This module creates a scoped `node-redis` client and exposes it in two forms:
  * the generic `Redis` service and the {@link NodeRedis} service for direct
- * access to the underlying client. `layer` accepts ioredis options directly,
- * while `layerConfig` reads them from Effect config. Both layers close the
- * client when the layer scope ends.
+ * access to the underlying client. `layer` accepts node-redis client options
+ * directly, while `layerConfig` reads them from Effect config. `node-redis`
+ * connects explicitly, so layer construction can fail with a `RedisError`.
+ * Both layers close the client when the layer scope ends.
  *
  * @since 4.0.0
  */
@@ -14,12 +15,11 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Fn from "effect/Function";
 import * as Layer from "effect/Layer";
-import * as Scope from "effect/Scope";
 import * as Redis from "effect/unstable/persistence/Redis";
-import * as IoRedis from "ioredis";
+import { createClient, SocketTimeoutError } from "redis";
 /**
  * Service tag for the Node Redis integration, exposing the underlying
- * `ioredis` client and a `use` helper that maps client failures to
+ * `node-redis` client and a `use` helper that maps client failures to
  * `RedisError`.
  *
  * @category services
@@ -27,9 +27,37 @@ import * as IoRedis from "ioredis";
  */
 export class NodeRedis extends /*#__PURE__*/Context.Service()("@effect/platform-node/NodeRedis") {}
 const make = /*#__PURE__*/Effect.fnUntraced(function* (options) {
-  const scope = yield* Effect.scope;
-  yield* Scope.addFinalizer(scope, Effect.promise(() => client.quit()));
-  const client = new IoRedis.Redis(options ?? {});
+  let ready = false;
+  const socket = options?.socket;
+  const client = yield* Effect.acquireRelease(Effect.sync(() => createClient({
+    ...options,
+    socket: socket?.reconnectStrategy === undefined ? {
+      ...socket,
+      reconnectStrategy: (retries, cause) => {
+        if (!ready) return cause;
+        if (cause instanceof SocketTimeoutError) return false;
+        const jitter = Math.floor(Math.random() * 200);
+        const delay = Math.min(2 ** retries * 50, 2000);
+        return delay + jitter;
+      }
+    } : socket
+  })), client => Effect.ignoreCause(Effect.promise(() => client.close())));
+  client.once("ready", () => {
+    ready = true;
+  });
+  // node-redis rethrows `error` events that have no listener, which would crash
+  // the process on a transient socket failure. Command failures are still
+  // reported as `RedisError`.
+  const runSync = Effect.runSyncWith(yield* Effect.context());
+  client.on("error", cause => {
+    runSync(Effect.logWarning("NodeRedis client error", cause));
+  });
+  yield* Effect.tryPromise({
+    try: () => client.connect(),
+    catch: cause => new Redis.RedisError({
+      cause
+    })
+  });
   const use = f => Effect.tryPromise({
     try: () => f(client),
     catch: cause => new Redis.RedisError({
@@ -38,7 +66,7 @@ const make = /*#__PURE__*/Effect.fnUntraced(function* (options) {
   });
   const redis = yield* Redis.make({
     send: (command, ...args) => Effect.tryPromise({
-      try: () => client.call(command, ...args),
+      try: () => client.sendCommand([command, ...args]),
       catch: cause => new Redis.RedisError({
         cause
       })
@@ -51,16 +79,38 @@ const make = /*#__PURE__*/Effect.fnUntraced(function* (options) {
   return Context.make(NodeRedis, nodeRedis).pipe(Context.add(Redis.Redis, redis));
 });
 /**
- * Provides `Redis` and `NodeRedis` services backed by an `ioredis` client
- * created with the supplied options and closed when the layer scope ends.
+ * Provides `Redis` and `NodeRedis` services backed by a `node-redis` client
+ * created with the supplied options, connected when the layer is built and
+ * closed when the layer scope ends.
+ *
+ * **Details**
+ *
+ * By default, the initial connection fails on its first connection error. A
+ * caller-supplied `socket.reconnectStrategy` is used instead when present. Once
+ * the client has emitted `ready`, the default reconnect strategy uses
+ * node-redis' exponential backoff and stops on socket timeouts.
+ *
+ * Scope finalization calls `close()`, which waits for in-flight commands,
+ * including blocking commands, and can therefore delay scope closure.
  *
  * @category layers
  * @since 4.0.0
  */
 export const layer = options => Layer.effectContext(make(options));
 /**
- * Provides `Redis` and `NodeRedis` services from `Config`-backed ioredis
- * options, closing the client when the layer scope ends.
+ * Provides `Redis` and `NodeRedis` services from `Config`-backed node-redis
+ * client options, connecting the client when the layer is built and closing it
+ * when the layer scope ends.
+ *
+ * **Details**
+ *
+ * By default, the initial connection fails on its first connection error. A
+ * caller-supplied `socket.reconnectStrategy` is used instead when present. Once
+ * the client has emitted `ready`, the default reconnect strategy uses
+ * node-redis' exponential backoff and stops on socket timeouts.
+ *
+ * Scope finalization calls `close()`, which waits for in-flight commands,
+ * including blocking commands, and can therefore delay scope closure.
  *
  * @category layers
  * @since 4.0.0

package/dist/NodeRedis.js.map

@@ -1 +1 @@
-{"version":3,"file":"NodeRedis.js","names":[],"sources":["../src/NodeRedis.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;AAWA,OAAO,KAAK,MAAM,MAAM,eAAe;AACvC,OAAO,KAAK,OAAO,MAAM,gBAAgB;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe;AACvC,OAAO,KAAK,EAAE,MAAM,iBAAiB;AACrC,OAAO,KAAK,KAAK,MAAM,cAAc;AACrC,OAAO,KAAK,KAAK,MAAM,cAAc;AACrC,OAAO,KAAK,KAAK,MAAM,mCAAmC;AAC1D,OAAO,KAAK,OAAO,MAAM,SAAS;AAElC;;;;;;;;AAQA,OAAM,MAAO,SAAU,sBAAQ,OAAO,CAAC,OAAO,EAG1C,CAAC,iCAAiC,CAAC;AAEvC,MAAM,IAAI,gBAAG,MAAM,CAAC,UAAU,CAAC,WAC7B,OAA8B;EAE9B,MAAM,KAAK,GAAG,OAAO,MAAM,CAAC,KAAK;EACjC,OAAO,KAAK,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;EACrE,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;EAE/C,MAAM,GAAG,GAAO,CAAwC,IACtD,MAAM,CAAC,UAAU,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC;IACpB,KAAK,EAAG,KAAK,IAAK,IAAI,KAAK,CAAC,UAAU,CAAC;MAAE;IAAK,CAAE;GACjD,CAAC;EAEJ,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;IAC9B,IAAI,EAAE,CAAc,OAAe,EAAE,GAAG,IAA2B,KACjE,MAAM,CAAC,UAAU,CAAC;MAChB,GAAG,EAAE,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAe;MACtD,KAAK,EAAG,KAAK,IAAK,IAAI,KAAK,CAAC,UAAU,CAAC;QAAE;MAAK,CAAE;KACjD;GACJ,CAAC;EAEF,MAAM,SAAS,GAAG,EAAE,CAAC,QAAQ,CAAuB;IAClD,MAAM;IACN;GACD,CAAC;EAEF,OAAO,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,IAAI,CAC5C,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAChC;AACH,CAAC,CAAC;AAEF;;;;;;;AAOA,OAAO,MAAM,KAAK,GAChB,OAA0C,IACD,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAE7E;;;;;;;AAOA,OAAO,MAAM,WAAW,GAGtB,OAA0C,IAE1C,KAAK,CAAC,aAAa,CACjB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CACzB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CACrB,CACF","ignoreList":[]}
+{"version":3,"file":"NodeRedis.js","names":[],"sources":["../src/NodeRedis.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@effect/platform-node",
   "type": "module",
-  "version": "4.0.0-rc.108",
+  "version": "4.0.0-rc.109",
   "license": "MIT",
   "description": "Platform specific implementations for the Node.js runtime",
   "homepage": "https://effect.website",
@@ -54,18 +54,19 @@
   "dependencies": {
     "mime": "^4.1.0",
     "undici": "^8.7.0",
-    "@effect/platform-node-shared": "^4.0.0-rc.108"
+    "@effect/platform-node-shared": "^4.0.0-rc.109"
   },
   "peerDependencies": {
-    "ioredis": ">=5.7.0 <6.0.0",
-    "effect": "^4.0.0-rc.108"
+    "redis": ">=5.0.0 <7.0.0",
+    "effect": "^4.0.0-rc.109"
   },
   "devDependencies": {
     "@testcontainers/mysql": "^12.0.4",
     "@testcontainers/postgresql": "^12.0.4",
     "@testcontainers/redis": "^12.0.4",
     "@types/node": "^26.1.2",
-    "effect": "^4.0.0-rc.108"
+    "redis": "^6.2.1",
+    "effect": "^4.0.0-rc.109"
   },
   "scripts": {
     "codegen": "effect-utils codegen",

package/src/NodeRedis.ts

@@ -1,11 +1,12 @@
 /**
- * Node.js Redis integration backed by `ioredis`.
+ * Node.js Redis integration backed by `redis` (node-redis).
  *
- * This module creates a scoped `ioredis` client and exposes it in two forms:
+ * This module creates a scoped `node-redis` client and exposes it in two forms:
  * the generic `Redis` service and the {@link NodeRedis} service for direct
- * access to the underlying client. `layer` accepts ioredis options directly,
- * while `layerConfig` reads them from Effect config. Both layers close the
- * client when the layer scope ends.
+ * access to the underlying client. `layer` accepts node-redis client options
+ * directly, while `layerConfig` reads them from Effect config. `node-redis`
+ * connects explicitly, so layer construction can fail with a `RedisError`.
+ * Both layers close the client when the layer scope ends.
  *
  * @since 4.0.0
  */
@@ -14,31 +15,68 @@ import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Fn from "effect/Function"
 import * as Layer from "effect/Layer"
-import * as Scope from "effect/Scope"
 import * as Redis from "effect/unstable/persistence/Redis"
-import * as IoRedis from "ioredis"
+import { createClient, SocketTimeoutError } from "redis"
+
+type NodeRedisClient = ReturnType<typeof createClient>
+type NodeRedisClientOptions = NonNullable<Parameters<typeof createClient>[0]>
 
 /**
  * Service tag for the Node Redis integration, exposing the underlying
- * `ioredis` client and a `use` helper that maps client failures to
+ * `node-redis` client and a `use` helper that maps client failures to
  * `RedisError`.
  *
  * @category services
  * @since 4.0.0
  */
 export class NodeRedis extends Context.Service<NodeRedis, {
-  readonly client: IoRedis.Redis
-  readonly use: <A>(f: (client: IoRedis.Redis) => Promise<A>) => Effect.Effect<A, Redis.RedisError>
+  readonly client: NodeRedisClient
+  readonly use: <A>(f: (client: NodeRedisClient) => Promise<A>) => Effect.Effect<A, Redis.RedisError>
 }>()("@effect/platform-node/NodeRedis") {}
 
 const make = Effect.fnUntraced(function*(
-  options?: IoRedis.RedisOptions
+  options?: NodeRedisClientOptions
 ) {
-  const scope = yield* Effect.scope
-  yield* Scope.addFinalizer(scope, Effect.promise(() => client.quit()))
-  const client = new IoRedis.Redis(options ?? {})
+  let ready = false
+  const socket = options?.socket
+  const client = yield* Effect.acquireRelease(
+    Effect.sync((): NodeRedisClient =>
+      createClient({
+        ...options,
+        socket: socket?.reconnectStrategy === undefined
+          ? {
+            ...socket,
+            reconnectStrategy: (retries, cause) => {
+              if (!ready) return cause
+              if (cause instanceof SocketTimeoutError) return false
+              const jitter = Math.floor(Math.random() * 200)
+              const delay = Math.min(2 ** retries * 50, 2000)
+              return delay + jitter
+            }
+          }
+          : socket
+      })
+    ),
+    (client) => Effect.ignoreCause(Effect.promise(() => client.close()))
+  )
+  client.once("ready", () => {
+    ready = true
+  })
+
+  // node-redis rethrows `error` events that have no listener, which would crash
+  // the process on a transient socket failure. Command failures are still
+  // reported as `RedisError`.
+  const runSync = Effect.runSyncWith(yield* Effect.context<never>())
+  client.on("error", (cause) => {
+    runSync(Effect.logWarning("NodeRedis client error", cause))
+  })
+
+  yield* Effect.tryPromise({
+    try: () => client.connect(),
+    catch: (cause) => new Redis.RedisError({ cause })
+  })
 
-  const use = <A>(f: (client: IoRedis.Redis) => Promise<A>) =>
+  const use = <A>(f: (client: NodeRedisClient) => Promise<A>) =>
     Effect.tryPromise({
       try: () => f(client),
       catch: (cause) => new Redis.RedisError({ cause })
@@ -47,7 +85,7 @@ const make = Effect.fnUntraced(function*(
   const redis = yield* Redis.make({
     send: <A = unknown>(command: string, ...args: ReadonlyArray<string>) =>
       Effect.tryPromise({
-        try: () => client.call(command, ...args) as Promise<A>,
+        try: () => client.sendCommand([command, ...args]) as Promise<A>,
         catch: (cause) => new Redis.RedisError({ cause })
       })
   })
@@ -63,28 +101,50 @@ const make = Effect.fnUntraced(function*(
 })
 
 /**
- * Provides `Redis` and `NodeRedis` services backed by an `ioredis` client
- * created with the supplied options and closed when the layer scope ends.
+ * Provides `Redis` and `NodeRedis` services backed by a `node-redis` client
+ * created with the supplied options, connected when the layer is built and
+ * closed when the layer scope ends.
+ *
+ * **Details**
+ *
+ * By default, the initial connection fails on its first connection error. A
+ * caller-supplied `socket.reconnectStrategy` is used instead when present. Once
+ * the client has emitted `ready`, the default reconnect strategy uses
+ * node-redis' exponential backoff and stops on socket timeouts.
+ *
+ * Scope finalization calls `close()`, which waits for in-flight commands,
+ * including blocking commands, and can therefore delay scope closure.
  *
  * @category layers
  * @since 4.0.0
  */
 export const layer = (
-  options?: IoRedis.RedisOptions | undefined
-): Layer.Layer<Redis.Redis | NodeRedis> => Layer.effectContext(make(options))
+  options?: NodeRedisClientOptions | undefined
+): Layer.Layer<Redis.Redis | NodeRedis, Redis.RedisError> => Layer.effectContext(make(options))
 
 /**
- * Provides `Redis` and `NodeRedis` services from `Config`-backed ioredis
- * options, closing the client when the layer scope ends.
+ * Provides `Redis` and `NodeRedis` services from `Config`-backed node-redis
+ * client options, connecting the client when the layer is built and closing it
+ * when the layer scope ends.
+ *
+ * **Details**
+ *
+ * By default, the initial connection fails on its first connection error. A
+ * caller-supplied `socket.reconnectStrategy` is used instead when present. Once
+ * the client has emitted `ready`, the default reconnect strategy uses
+ * node-redis' exponential backoff and stops on socket timeouts.
+ *
+ * Scope finalization calls `close()`, which waits for in-flight commands,
+ * including blocking commands, and can therefore delay scope closure.
  *
  * @category layers
  * @since 4.0.0
  */
 export const layerConfig: (
-  options: Config.Wrap<IoRedis.RedisOptions>
-) => Layer.Layer<Redis.Redis | NodeRedis, Config.ConfigError> = (
-  options: Config.Wrap<IoRedis.RedisOptions>
-): Layer.Layer<Redis.Redis | NodeRedis, Config.ConfigError> =>
+  options: Config.Wrap<NodeRedisClientOptions>
+) => Layer.Layer<Redis.Redis | NodeRedis, Redis.RedisError | Config.ConfigError> = (
+  options: Config.Wrap<NodeRedisClientOptions>
+): Layer.Layer<Redis.Redis | NodeRedis, Redis.RedisError | Config.ConfigError> =>
   Layer.effectContext(
     Config.unwrap(options).pipe(
       Effect.flatMap(make)