effect 4.0.0-rc.112 → 4.0.0-rc.114

package/AGENTS.md

@@ -11,9 +11,11 @@ purposes. In practice, you would not include these comments in your code.
 
 ## Writing `Effect` code
 
-Prefer writing Effect code with `Effect.gen` & `Effect.fn("name")`. Then attach
-additional behaviour with combinators. This style is more readable and easier to
-maintain than using combinators alone.
+Prefer `Effect.gen` for inline Effect code. For reusable functions, prefer
+`Effect.fn("name")` when tracing is useful and `Effect.fnUntraced` when it is not,
+particularly in library implementations and hot paths. Avoid functions that only
+wrap and return `Effect.gen`. Attach additional behaviour with combinators; this
+style is more readable and easier to maintain than using combinators alone.
 
 ### Using Effect.gen
 
@@ -46,13 +48,16 @@ export class FileProcessingError extends Schema.TaggedError<FileProcessingError>
 }) {}
 ```
 
-### Using Effect.fn
+### Using Effect.fn and Effect.fnUntraced
 
-When writing functions that return an Effect, use `Effect.fn` to use the
-generator syntax.
+When writing reusable functions that return an Effect, use `Effect.fn` or
+`Effect.fnUntraced` to use the generator syntax.
 
-**Avoid creating functions that return an Effect.gen**, use `Effect.fn`
-instead.
+Use `Effect.fn("name")` when the function should create a tracing span. Prefer
+`Effect.fnUntraced` when tracing is not needed, particularly for library
+implementations and hot paths.
+
+**Avoid creating functions that only wrap and return an `Effect.gen`**.
 
 ```ts
 import { Effect, Schema } from "effect"
@@ -80,6 +85,16 @@ export const effectFunction = Effect.fn("effectFunction")(
   })
 )
 
+// Effect.fnUntraced avoids tracing and stack-frame capture while still reusing
+// the generator body. This is preferred for library functions that do not
+// represent a useful tracing boundary.
+export const validateBatchSize = Effect.fnUntraced(function*(size: number): Effect.fn.Return<number, SomeError> {
+  if (!Number.isInteger(size) || size <= 0) {
+    return yield* new SomeError({ message: "Batch size must be a positive integer" })
+  }
+  return size
+})
+
 // Use Schema.TaggedError to define a custom error
 export class SomeError extends Schema.TaggedError<SomeError>()("SomeError", {
   message: Schema.String
@@ -247,7 +262,7 @@ They let you model finite or infinite data sources.
   - `NodeStream.fromReadable` for Node.js readable streams
 - **[Consuming and transforming streams](./ai-docs/src/03_stream/20_consuming-streams.ts)**: How to transform and consume streams using operators like `map`, `flatMap`, `filter`, `mapEffect`, and various `run*` methods.
 - **[Decoding and encoding streams](./ai-docs/src/03_stream/30_encoding.ts)**:
-  Use `Stream.pipeThroughChannel` with the `Ndjson` & `Msgpack` modules to
+  Use `Stream.pipeThroughChannel` with the `Ndjson` and `SchemaBinary` modules to
   decode and encode streams of structured data.
 
 ## Integrating Effect into existing applications

package/CLAUDE.md

@@ -11,9 +11,11 @@ purposes. In practice, you would not include these comments in your code.
 
 ## Writing `Effect` code
 
-Prefer writing Effect code with `Effect.gen` & `Effect.fn("name")`. Then attach
-additional behaviour with combinators. This style is more readable and easier to
-maintain than using combinators alone.
+Prefer `Effect.gen` for inline Effect code. For reusable functions, prefer
+`Effect.fn("name")` when tracing is useful and `Effect.fnUntraced` when it is not,
+particularly in library implementations and hot paths. Avoid functions that only
+wrap and return `Effect.gen`. Attach additional behaviour with combinators; this
+style is more readable and easier to maintain than using combinators alone.
 
 ### Using Effect.gen
 
@@ -46,13 +48,16 @@ export class FileProcessingError extends Schema.TaggedError<FileProcessingError>
 }) {}
 ```
 
-### Using Effect.fn
+### Using Effect.fn and Effect.fnUntraced
 
-When writing functions that return an Effect, use `Effect.fn` to use the
-generator syntax.
+When writing reusable functions that return an Effect, use `Effect.fn` or
+`Effect.fnUntraced` to use the generator syntax.
 
-**Avoid creating functions that return an Effect.gen**, use `Effect.fn`
-instead.
+Use `Effect.fn("name")` when the function should create a tracing span. Prefer
+`Effect.fnUntraced` when tracing is not needed, particularly for library
+implementations and hot paths.
+
+**Avoid creating functions that only wrap and return an `Effect.gen`**.
 
 ```ts
 import { Effect, Schema } from "effect"
@@ -80,6 +85,16 @@ export const effectFunction = Effect.fn("effectFunction")(
   })
 )
 
+// Effect.fnUntraced avoids tracing and stack-frame capture while still reusing
+// the generator body. This is preferred for library functions that do not
+// represent a useful tracing boundary.
+export const validateBatchSize = Effect.fnUntraced(function*(size: number): Effect.fn.Return<number, SomeError> {
+  if (!Number.isInteger(size) || size <= 0) {
+    return yield* new SomeError({ message: "Batch size must be a positive integer" })
+  }
+  return size
+})
+
 // Use Schema.TaggedError to define a custom error
 export class SomeError extends Schema.TaggedError<SomeError>()("SomeError", {
   message: Schema.String
@@ -247,7 +262,7 @@ They let you model finite or infinite data sources.
   - `NodeStream.fromReadable` for Node.js readable streams
 - **[Consuming and transforming streams](./ai-docs/src/03_stream/20_consuming-streams.ts)**: How to transform and consume streams using operators like `map`, `flatMap`, `filter`, `mapEffect`, and various `run*` methods.
 - **[Decoding and encoding streams](./ai-docs/src/03_stream/30_encoding.ts)**:
-  Use `Stream.pipeThroughChannel` with the `Ndjson` & `Msgpack` modules to
+  Use `Stream.pipeThroughChannel` with the `Ndjson` and `SchemaBinary` modules to
   decode and encode streams of structured data.
 
 ## Integrating Effect into existing applications

package/ai-docs/package.json

@@ -27,8 +27,8 @@
     "@effect/sql-sqlite-wasm": "workspace:*",
     "@effect/vitest": "workspace:*",
     "effect": "workspace:*",
-    "hono": "^4.13.3",
-    "nodemailer": "^9.0.5"
+    "hono": "^4.13.7",
+    "nodemailer": "^10.0.0"
   },
   "devDependencies": {
     "@types/nodemailer": "^8.0.1"

package/ai-docs/src/01_effect/01_basics/02_effect-fn.ts

@@ -1,11 +1,14 @@
 /**
- * @title Using Effect.fn
+ * @title Using Effect.fn and Effect.fnUntraced
  *
- * When writing functions that return an Effect, use `Effect.fn` to use the
- * generator syntax.
+ * When writing reusable functions that return an Effect, use `Effect.fn` or
+ * `Effect.fnUntraced` to use the generator syntax.
  *
- * **Avoid creating functions that return an Effect.gen**, use `Effect.fn`
- * instead.
+ * Use `Effect.fn("name")` when the function should create a tracing span. Prefer
+ * `Effect.fnUntraced` when tracing is not needed, particularly for library
+ * implementations and hot paths.
+ *
+ * **Avoid creating functions that only wrap and return an `Effect.gen`**.
  */
 
 import { Effect, Schema } from "effect"
@@ -33,6 +36,16 @@ export const effectFunction = Effect.fn("effectFunction")(
   })
 )
 
+// Effect.fnUntraced avoids tracing and stack-frame capture while still reusing
+// the generator body. This is preferred for library functions that do not
+// represent a useful tracing boundary.
+export const validateBatchSize = Effect.fnUntraced(function*(size: number): Effect.fn.Return<number, SomeError> {
+  if (!Number.isInteger(size) || size <= 0) {
+    return yield* new SomeError({ message: "Batch size must be a positive integer" })
+  }
+  return size
+})
+
 // Use Schema.TaggedError to define a custom error
 export class SomeError extends Schema.TaggedError<SomeError>()("SomeError", {
   message: Schema.String

package/ai-docs/src/01_effect/01_basics/index.md

@@ -1,5 +1,7 @@
 ## Writing `Effect` code
 
-Prefer writing Effect code with `Effect.gen` & `Effect.fn("name")`. Then attach
-additional behaviour with combinators. This style is more readable and easier to
-maintain than using combinators alone.
+Prefer `Effect.gen` for inline Effect code. For reusable functions, prefer
+`Effect.fn("name")` when tracing is useful and `Effect.fnUntraced` when it is not,
+particularly in library implementations and hot paths. Avoid functions that only
+wrap and return `Effect.gen`. Attach additional behaviour with combinators; this
+style is more readable and easier to maintain than using combinators alone.

package/ai-docs/src/01_effect/03_services/20_layer-composition.ts

@@ -14,7 +14,7 @@ export const SqlClientLayer: Layer.Layer<
   PgClient.PgClient | SqlClient.SqlClient,
   Config.ConfigError | SqlError.SqlError
 > = PgClient.layerConfig({
-  url: Config.redacted("DATABASE_URL")
+  url: Config.Redacted("DATABASE_URL")
 })
 
 export class UserRespositoryError extends Schema.TaggedError<UserRespositoryError>()("UserRespositoryError", {

package/ai-docs/src/01_effect/03_services/20_layer-unwrap.ts

@@ -51,7 +51,7 @@ export class MessageStore extends Context.Service<MessageStore, {
   static readonly layer = Layer.unwrap(
     Effect.gen(function*() {
       // Read config inside an Effect, then choose which concrete layer to use.
-      const useInMemory = yield* Config.boolean("MESSAGE_STORE_IN_MEMORY").pipe(
+      const useInMemory = yield* Config.Boolean("MESSAGE_STORE_IN_MEMORY").pipe(
         Config.withDefault(false)
       )
 
@@ -59,7 +59,7 @@ export class MessageStore extends Context.Service<MessageStore, {
         return MessageStore.layerInMemory
       }
 
-      const remoteUrl = yield* Config.url("MESSAGE_STORE_URL")
+      const remoteUrl = yield* Config.URL("MESSAGE_STORE_URL")
       return MessageStore.layerRemote(remoteUrl)
     })
   )

package/ai-docs/src/01_effect/05_resources/10_acquire-release.ts

@@ -22,8 +22,8 @@ export class Smtp extends Context.Service<Smtp, {
   static readonly layer = Layer.effect(
     Smtp,
     Effect.gen(function*() {
-      const user = yield* Config.string("SMTP_USER")
-      const pass = yield* Config.redacted("SMTP_PASS")
+      const user = yield* Config.String("SMTP_USER")
+      const pass = yield* Config.Redacted("SMTP_PASS")
 
       // Use `Effect.acquireRelease` to manage the lifecycle of the SMTP
       // transporter.

package/ai-docs/src/03_stream/30_encoding.ts

@@ -1,19 +1,17 @@
 /**
  * @title Decoding and encoding streams
  *
- * Use `Stream.pipeThroughChannel` with the `Ndjson` & `Msgpack` modules to
+ * Use `Stream.pipeThroughChannel` with the `Ndjson` and `SchemaBinary` modules to
  * decode and encode streams of structured data.
  */
 import { DateTime, Schema, Stream } from "effect"
-import { Msgpack, Ndjson } from "effect/unstable/encoding"
+import { Ndjson, SchemaBinary } from "effect/unstable/encoding"
 
-// All of the examples below can also be done with Msgpack by replacing `Ndjson`
-// with `Msgpack` and using the appropriate channels (`Msgpack.decode()`,
-// `Msgpack.encode()`, etc.).
-export const msgpackDecoder = Msgpack.decodeSchema(Schema.Struct({
+// SchemaBinary derives a framed binary decoder directly from a schema.
+export const schemaBinaryDecoder = SchemaBinary.decode(Schema.Struct({
   id: Schema.Int,
   name: Schema.String
-}))
+}))()
 
 // ---------------------------------------------------------------------------
 // Domain

package/ai-docs/src/08_observability/10_logging.ts

@@ -41,7 +41,7 @@ export const AppLoggerLayer = Logger.layer([appLogger]).pipe(
 // Create a logger layer that uses the default logger for development, and the
 // custom logger for production
 export const LoggerLayer = Layer.unwrap(Effect.gen(function*() {
-  const env = yield* Config.string("NODE_ENV").pipe(Config.withDefault("development"))
+  const env = yield* Config.String("NODE_ENV").pipe(Config.withDefault("development"))
   if (env === "production") {
     return AppLoggerLayer
   }

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

@@ -10,7 +10,7 @@ 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(
+const workspace = Flag.String("workspace").pipe(
   Flag.withAlias("w"),
   Flag.withDescription("Workspace to operate on"),
   Flag.withDefault("personal")
@@ -21,7 +21,7 @@ const workspace = Flag.string("workspace").pipe(
 const tasks = Command.make("tasks").pipe(
   Command.withSharedFlags({
     workspace,
-    verbose: Flag.boolean("verbose").pipe(
+    verbose: Flag.Boolean("verbose").pipe(
       Flag.withAlias("v"),
       Flag.withDescription("Print diagnostic output"),
       Flag.withDefault(false)
@@ -41,17 +41,17 @@ const Email = Schema.String.pipe(
 const create = Command.make(
   "create",
   {
-    title: Argument.string("title").pipe(
+    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(
+    priority: Flag.Literals("priority", ["low", "normal", "high"]).pipe(
       Flag.withDescription("Priority for the new task"),
       Flag.withDefault("normal")
     ),
-    assignee: Flag.string("assignee").pipe(
+    assignee: Flag.String("assignee").pipe(
       Flag.withDescription("Email address of the person to assign"),
       Flag.withSchema(Email),
       Flag.optional
@@ -88,11 +88,11 @@ const create = Command.make(
 const list = Command.make(
   "list",
   {
-    status: Flag.choice("status", ["open", "done", "all"]).pipe(
+    status: Flag.Literals("status", ["open", "done", "all"]).pipe(
       Flag.withDescription("Filter tasks by status"),
       Flag.withDefault("open")
     ),
-    json: Flag.boolean("json").pipe(
+    json: Flag.Boolean("json").pipe(
       Flag.withDescription("Print machine-readable output"),
       Flag.withDefault(false)
     )

package/ai-docs/src/71_ai/10_language-model.ts

@@ -13,7 +13,7 @@ import { LaunchPlan } from "./fixtures/domain/LaunchPlan.ts"
 
 // You can use Config to create ai clients
 const AnthropicClientLayer = AnthropicClient.layerConfig({
-  apiKey: Config.redacted("ANTHROPIC_API_KEY")
+  apiKey: Config.Redacted("ANTHROPIC_API_KEY")
 }).pipe(
   // Providers typically require an HttpClient, but you can choose which one to
   // use.
@@ -21,7 +21,7 @@ const AnthropicClientLayer = AnthropicClient.layerConfig({
 )
 
 const OpenAiClientLayer = OpenAiClient.layerConfig({
-  apiKey: Config.redacted("OPENAI_API_KEY")
+  apiKey: Config.Redacted("OPENAI_API_KEY")
 }).pipe(
   Layer.provide(FetchHttpClient.layer)
 )

package/ai-docs/src/71_ai/20_tools.ts

@@ -101,7 +101,7 @@ const ProductToolkitLayer = ProductToolkit.toLayer(Effect.gen(function*() {
 
 // Provider setup (same pattern as the language-model example).
 const OpenAiClientLayer = OpenAiClient.layerConfig({
-  apiKey: Config.redacted("OPENAI_API_KEY")
+  apiKey: Config.Redacted("OPENAI_API_KEY")
 }).pipe(Layer.provide(FetchHttpClient.layer))
 
 export class ProductAssistantError extends Schema.TaggedError<ProductAssistantError>()(

package/ai-docs/src/71_ai/30_chat.ts

@@ -14,7 +14,7 @@ import { FetchHttpClient } from "effect/unstable/http"
 // ---------------------------------------------------------------------------
 
 const OpenAiClientLayer = OpenAiClient.layerConfig({
-  apiKey: Config.redacted("OPENAI_API_KEY")
+  apiKey: Config.Redacted("OPENAI_API_KEY")
 }).pipe(Layer.provide(FetchHttpClient.layer))
 
 // ---------------------------------------------------------------------------