effect 4.0.0-beta.99 → 4.0.0-rc.108

package/ai-docs/src/05_batching/10_request-resolver.ts

@@ -0,0 +1,89 @@
+/**
+ * @title Batching requests with RequestResolver
+ *
+ * Define request types with `Request.Class`, resolve them in batches with `RequestResolver`.
+ */
+import { Context, Effect, Exit, Layer, Request, RequestResolver, Schema, Tracer } from "effect"
+
+export class User extends Schema.Class<User>("User")({
+  id: Schema.Int,
+  name: Schema.String,
+  email: Schema.String
+}) {}
+
+export class UserNotFound extends Schema.TaggedError<UserNotFound>()("UserNotFound", {
+  id: Schema.Int
+}) {}
+
+export class Users extends Context.Service<Users, {
+  getUserById(id: number): Effect.Effect<User, UserNotFound>
+}>()("app/Users") {
+  static readonly layer = Layer.effect(
+    Users,
+    Effect.gen(function*() {
+      // Request classes model a single external lookup.
+      class GetUserById extends Request.Class<
+        { readonly id: number },
+        User, // The success type of the request
+        UserNotFound, // The error type of the request
+        never // The requirements type of the request, if any
+      > {}
+
+      // Simulate an external data source that supports batched lookup.
+      const usersTable = new Map<number, User>([
+        [1, new User({ id: 1, name: "Ada Lovelace", email: "ada@acme.dev" })],
+        [2, new User({ id: 2, name: "Alan Turing", email: "alan@acme.dev" })],
+        [3, new User({ id: 3, name: "Grace Hopper", email: "grace@acme.dev" })]
+      ])
+
+      const resolver = yield* RequestResolver.make<GetUserById>(Effect.fn(function*(entries) {
+        for (const entry of entries) {
+          const user = usersTable.get(entry.request.id)
+
+          // If the request had requirements, you can access them with
+          // `entry.context`
+          const requestSpan = Context.getOption(entry.context, Tracer.ParentSpan)
+          console.log("Request span", requestSpan)
+
+          if (user) {
+            // Complete requests with .completeUnsafe and pass in an Exit value
+            entry.completeUnsafe(Exit.succeed(user))
+          } else {
+            entry.completeUnsafe(Exit.fail(new UserNotFound({ id: entry.request.id })))
+          }
+        }
+      })).pipe(
+        // Control the delay before the resolver is executed. This allows more
+        // requests to be batched together, but also adds latency to the first
+        // request.
+        RequestResolver.setDelay("10 millis"),
+        // RequestResolver.withSpan adds a span around the resolver execution,
+        // and also sets up span links for each request
+        RequestResolver.withSpan("Users.getUserById.resolver"),
+        // RequestResolver.withCache adds a simple LRU cache to avoid repeated
+        // lookups for the same ID.
+        RequestResolver.withCache({ capacity: 1024 })
+      )
+
+      // Wrap the resolver in a service method. The resolver batches calls to
+      // `getUserById` that occur within the delay window.
+      const getUserById = (id: number) =>
+        Effect.request(new GetUserById({ id }), resolver).pipe(
+          Effect.withSpan("Users.getUserById", { attributes: { userId: id } })
+        )
+
+      return { getUserById } as const
+    })
+  )
+}
+
+// Run multiple lookups concurrently. The resolver receives one batch and
+// internally deduplicates repeated IDs for the external call.
+export const batchedLookupExample = Effect.gen(function*() {
+  const { getUserById } = yield* Users
+
+  // This will only trigger a single call to the resolver with the unique IDs [1, 2, 3].
+  yield* Effect.forEach([1, 2, 1, 3, 2], getUserById, {
+    concurrency: "unbounded"
+  })
+})

package/ai-docs/src/05_batching/index.md

@@ -0,0 +1,3 @@
+## Batching external requests
+
+Learn how to batch multiple requests into fewer external calls.

package/ai-docs/src/06_schedule/10_schedules.ts

@@ -0,0 +1,110 @@
+/**
+ * @title Working with the Schedule module
+ *
+ * Build schedules, compose them, and use them with `Effect.retry` and `Effect.repeat`.
+ */
+import { Duration, Effect, Random, Schedule, Schema } from "effect"
+
+// Production pattern: capped exponential backoff with jitter and max attempts.
+// Delays start at 250ms, grow exponentially with jitter, and are capped at 10s.
+export const productionRetrySchedule = Schedule.min([
+  Schedule.exponential("250 millis"),
+  // Cap the delay at 10 seconds to avoid excessively long waits.
+  Schedule.spaced("10 seconds")
+]).pipe(
+  Schedule.jittered,
+  Schedule.setInputType<HttpError>(),
+  Schedule.while(({ input }) => input.retryable)
+)
+
+export const fetchUserProfile = Effect.fn("fetchUserProfile")(
+  function*(userId: string) {
+    const random = yield* Random.next
+    const status = random > 0.7
+      ? 200
+      : random > 0.3
+      ? 503
+      : 401
+
+    if (status !== 200) {
+      return yield* new HttpError({
+        message: `Request for ${userId} failed`,
+        status,
+        retryable: status >= 500
+      })
+    }
+
+    return {
+      id: userId,
+      name: "Ada Lovelace"
+    } as const
+  }
+)
+
+// Use the schedule with `Effect.retry` to retry failures.
+export const loadUserWithRetry = fetchUserProfile("user-123").pipe(
+  Effect.retry(productionRetrySchedule),
+  // If the effect still fails after exhausting the schedule, turn the error
+  // into a fatal one.
+  Effect.orDie
+)
+
+export const loadUserWithInferredInput = fetchUserProfile("user-123").pipe(
+  // You can also pass a schedule builder function that assists with inferring
+  // the input type. This is especially useful when the schedule needs to
+  // inspect the error to determine retryability.
+  Effect.retry(($) =>
+    $(Schedule.spaced("1 seconds")).pipe(
+      Schedule.while(({ input }) => input.retryable)
+    )
+  ),
+  Effect.orDie
+)
+
+export class HttpError extends Schema.TaggedError<HttpError>()("HttpError", {
+  message: Schema.String,
+  status: Schema.Int,
+  retryable: Schema.Boolean
+}) {}
+
+// Start with a few schedule constructors.
+export const maxRetries = Schedule.recurs(5)
+export const spacedPolling = Schedule.spaced("30 seconds")
+export const exponentialBackoff = Schedule.exponential("200 millis")
+
+// `Schedule.max` continues only while all schedules continue and outputs
+// the slowest delay. It is useful for combining a delay pattern with a hard
+// attempt cap.
+export const retryBackoffWithLimit = Schedule.max([
+  Schedule.exponential("250 millis"),
+  Schedule.recurs(6)
+])
+
+// `Schedule.min` continues while any schedule continues and outputs
+// the fastest delay. It is useful for fallback behavior.
+//
+// This schedule will start at 500ms, exponentially increase, and will be capped
+// at 2 seconds.
+export const keepTryingUpToTwoSeconds = Schedule.min([
+  Schedule.exponential("500 millis"),
+  Schedule.spaced("2 seconds")
+])
+
+// Use `Schedule.while` to continue only for retryable failures.
+// This lets non-retryable errors fail fast, even if attempts remain.
+export const retryableOnly = Schedule.exponential("200 millis").pipe(
+  // You can use `setInputType` to specify the type of input the schedule will
+  // receive.
+  Schedule.setInputType<HttpError>(),
+  Schedule.while(({ input }) => input.retryable)
+)
+
+// `tap` is useful for performing side effects like logging or metrics.
+export const instrumentedRetrySchedule = retryableOnly.pipe(
+  Schedule.setInputType<HttpError>(),
+  Schedule.tap((meta) =>
+    Effect.logDebug(
+      `Retrying after ${meta.input.status}: ${meta.input.message}. Next retry in ${Duration.toMillis(meta.duration)}ms`
+    )
+  )
+)

package/ai-docs/src/06_schedule/index.md

@@ -0,0 +1,3 @@
+## Working with Schedules
+
+Schedules define recurring patterns for retries, repeats and polling.

package/ai-docs/src/07_datetime/10_creating-and-formatting.ts

@@ -0,0 +1,30 @@
+/**
+ * @title Creating and formatting DateTime values
+ *
+ * Parse incoming date values safely, use Clock-powered current time, and format
+ * instants for API payloads or user-facing labels.
+ */
+import { DateTime, Effect, Option } from "effect"
+
+Effect.gen(function*() {
+  // Use DateTime.now to get the current time from Effect's Clock service.
+  // Using the Clock service ensures tests can use the `TestClock` module to
+  // control time.
+  const now = yield* DateTime.now
+
+  // Use DateTime.make to parse a date input, such as a user-entered string or a
+  // epoch timestamp. It returns an Option depending on whether the input was
+  // valid.
+  const parsedOption: Option.Option<DateTime.Utc> = DateTime.make("2024-06-15T14:30:00.000Z")
+
+  // you can then use the Option apis to unwrap the value
+  Option.getOrUndefined(parsedOption)
+
+  // Calendar/date-time math returns a new DateTime value; the original value is
+  // immutable.
+  const endsAt = now.pipe(DateTime.add({ hours: 2 }))
+
+  // The DateTime.format* functions can be used to convert a DateTime value to
+  // differen formats.
+  yield* Effect.log("ISO string:", DateTime.formatIso(endsAt))
+})

package/ai-docs/src/07_datetime/20_time-zones.ts

@@ -0,0 +1,44 @@
+/**
+ * @title Working with time zones
+ *
+ * Attach IANA zones to instants, render zoned ISO strings, and provide a
+ * CurrentTimeZone service for code that should use the workspace/user zone.
+ */
+import { NodeRuntime } from "@effect/platform-node"
+import { DateTime, Effect, Option } from "effect"
+
+Effect.gen(function*() {
+  // Use DateTime.now to get the current time from Effect's Clock service.
+  const now = yield* DateTime.now
+
+  // To attach a named IANA zone to a DateTime value
+  const nowInAuckland = now.pipe(
+    // Use DateTime.setZoneNamedUnsafe when you know the zone is valid.
+    DateTime.setZoneNamedUnsafe("Pacific/Auckland")
+  )
+  yield* Effect.log("Now in Auckland:", nowInAuckland)
+
+  // Use DateTime.setZoneNamed when you don't know the zone is valid.
+  const nowInSydneyOption: Option.Option<DateTime.Zoned> = now.pipe(
+    DateTime.setZoneNamed("Australia/Sydney")
+  )
+
+  yield* Effect.log("Now in Sydney:", Option.getOrUndefined(nowInSydneyOption))
+
+  // To generate a `DateTime.Zoned` in the `DateTime.CurrentTimeZone`
+  const nowInNewYork = yield* DateTime.nowInCurrentZone
+  yield* Effect.log("Now in New York:", nowInNewYork)
+
+  // If you have a date string that you know is in a particular IANA zone, you
+  // can convert it to a DateTime.Zoned to ensure the instant is correct
+  const dateInAuckland: DateTime.Zoned = DateTime.makeZonedUnsafe("2026-06-05", {
+    timeZone: "Pacific/Auckland",
+    // adjustForTimeZone will adjust the input to the given zone, otherwise it
+    // will be treated as UTC.
+    adjustForTimeZone: true
+  })
+  yield* Effect.log("Date in Auckland:", dateInAuckland)
+}).pipe(
+  Effect.provide(DateTime.layerCurrentZoneNamed("America/New_York")),
+  NodeRuntime.runMain
+)

package/ai-docs/src/07_datetime/index.md

@@ -0,0 +1,5 @@
+## Working with DateTime
+
+When working with dates and time, use the `DateTime` module instead of `Date` and `Date.now`.
+
+Use it when your Effect programs need testable current time, safe parsing, stable ISO formatting, time-zone conversion, or calendar arithmetic.

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

@@ -0,0 +1,66 @@
+/**
+ * @title Customizing logging
+ *
+ * Configure loggers & log-level filtering for production applications.
+ */
+import { NodeFileSystem } from "@effect/platform-node"
+import { Config, Effect, Layer, Logger, References } from "effect"
+
+// Build a logger layer that emits one JSON line per log entry.
+export const JsonLoggerLayer = Logger.layer([Logger.consoleJson])
+
+// Raise the minimum level to "Warn" to skip debug/info logs.
+export const WarnAndAbove = Layer.succeed(References.MinimumLogLevel, "Warn")
+
+// There is a built-in logger for writing to a file
+export const FileLoggerLayer = Logger.layer([
+  Logger.toFile(Logger.formatSimple, "app.log")
+]).pipe(
+  Layer.provide(NodeFileSystem.layer)
+)
+
+// Define a custom logger for app-specific formatting and routing.
+export const appLogger = Effect.gen(function*() {
+  // Here you could initialize a connection to an external logging service, set
+  // up log file rotation, etc.
+  yield* Effect.logDebug("initializing app logger")
+
+  return yield* Logger.batched(Logger.formatStructured, {
+    window: "1 second",
+    flush: Effect.fn(function*(batch) {
+      // In a real implementation, this is where you would send the batch of log entries to an external logging service or write them to a file.
+      console.log(`Flushing ${batch.length} log entries`)
+    })
+  })
+})
+
+export const AppLoggerLayer = Logger.layer([appLogger]).pipe(
+  Layer.provideMerge(WarnAndAbove) // Start with "Warn" level for the app logger.
+)
+
+// 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"))
+  if (env === "production") {
+    return AppLoggerLayer
+  }
+  return Logger.layer([Logger.defaultLogger])
+}))
+
+// Example effect that logs at various levels during a checkout flow.
+export const logCheckoutFlow = Effect.gen(function*() {
+  yield* Effect.logDebug("loading checkout state")
+
+  yield* Effect.logInfo("validating cart")
+  yield* Effect.logWarning("inventory is low for one line item")
+  yield* Effect.logError("payment provider timeout")
+}).pipe(
+  // Attach structured metadata to all log lines emitted by this effect.
+  Effect.annotateLogs({
+    service: "checkout-api",
+    route: "POST /checkout"
+  }),
+  // Add a duration span so each log line includes checkout=<N>ms metadata.
+  Effect.withLogSpan("checkout")
+)

package/ai-docs/src/08_observability/20_otlp-tracing.ts

@@ -0,0 +1,95 @@
+/**
+ * @title Setting up tracing with Otlp modules
+ *
+ * Configure Otlp tracing + log export with a reusable observability layer.
+ */
+import { NodeRuntime } from "@effect/platform-node"
+import { Context, Effect, Layer } from "effect"
+import { FetchHttpClient } from "effect/unstable/http"
+import { OtlpLogger, OtlpSerialization, OtlpTracer } from "effect/unstable/observability"
+
+// Configure OTLP span export.
+export const OtlpTracingLayer = OtlpTracer.layer({
+  url: "http://localhost:4318/v1/traces",
+  resource: {
+    serviceName: "checkout-api",
+    serviceVersion: "1.0.0",
+    attributes: {
+      "deployment.environment": "staging"
+    }
+  }
+})
+
+// Configure OTLP log export.
+export const OtlpLoggingLayer = OtlpLogger.layer({
+  url: "http://localhost:4318/v1/logs",
+  resource: {
+    serviceName: "checkout-api",
+    serviceVersion: "1.0.0"
+  }
+})
+
+// Reusable app-wide observability layer.
+//
+// - OtlpTracer/OtlpLogger require an OTLP serializer and an HttpClient.
+// - FetchHttpClient.layer provides the HttpClient used by the exporter.
+export const ObservabilityLayer = Layer.merge(OtlpTracingLayer, OtlpLoggingLayer).pipe(
+  Layer.provide(OtlpSerialization.layerJson),
+  Layer.provide(FetchHttpClient.layer)
+)
+
+export class Checkout extends Context.Service<Checkout, {
+  processCheckout(orderId: string): Effect.Effect<void>
+}>()("acme/Checkout") {
+  static readonly layer = Layer.effect(
+    Checkout,
+    Effect.gen(function*() {
+      yield* Effect.logInfo("setting up checkout service")
+
+      return Checkout.of({
+        processCheckout: Effect.fn("Checkout.processCheckout")(function*(orderId: string) {
+          yield* Effect.logInfo("starting checkout", { orderId })
+
+          yield* Effect.sleep("50 millis").pipe(
+            Effect.withSpan("checkout.charge-card"),
+            Effect.annotateSpans({
+              "checkout.order_id": orderId,
+              "checkout.provider": "acme-pay"
+            })
+          )
+
+          yield* Effect.sleep("20 millis").pipe(
+            Effect.withSpan("checkout.persist-order")
+          )
+
+          yield* Effect.logInfo("checkout completed", { orderId })
+        })
+      })
+    })
+  )
+}
+
+// Example usage of the Checkout service.
+const CheckoutTest = Layer.effectDiscard(
+  Effect.gen(function*() {
+    const checkout = yield* Checkout
+    yield* checkout.processCheckout("ord_123")
+  }).pipe(
+    Effect.withSpan("checkout-test-run")
+  )
+).pipe(
+  // You can also attach spans to Layers
+  Layer.withSpan("checkout-test"),
+  Layer.provide(Checkout.layer)
+)
+
+const Main = CheckoutTest.pipe(
+  // Provide the observability layer at the very end, so that all spans created
+  // by the app are exported.
+  Layer.provide(ObservabilityLayer)
+)
+
+// Launch the app
+Layer.launch(Main).pipe(
+  NodeRuntime.runMain
+)

package/ai-docs/src/08_observability/index.md

@@ -0,0 +1,7 @@
+## Observability
+
+Effect has built-in support for structured logging, distributed tracing, and
+metrics. For exporting telemetry, use the lightweight Otlp modules from
+`effect/unstable/observability` in new projects, or use
+`@effect/opentelemetry` NodeSdk when integrating with an existing OpenTelemetry
+setup.

package/ai-docs/src/09_testing/10_effect-tests.ts

@@ -0,0 +1,55 @@
+/**
+ * @title Writing Effect tests with @effect/vitest
+ *
+ * Using `it.effect` for Effect-based tests.
+ */
+import { assert, describe, it } from "@effect/vitest"
+import { Effect, Fiber, Schema } from "effect"
+import { TestClock } from "effect/testing"
+
+describe("@effect/vitest basics", () => {
+  it.effect("runs Effect code with assert helpers", () =>
+    Effect.gen(function*() {
+      const upper = ["ada", "lin"].map((name) => name.toUpperCase())
+      assert.deepStrictEqual(upper, ["ADA", "LIN"])
+      assert.strictEqual(upper.length, 2)
+      assert.isTrue(upper.includes("ADA"))
+    }))
+
+  it.effect.each([
+    { input: " Ada ", expected: "ada" },
+    { input: " Lin ", expected: "lin" },
+    { input: " Nia ", expected: "nia" }
+  ])("parameterized normalization %#", ({ input, expected }) =>
+    Effect.gen(function*() {
+      assert.strictEqual(input.trim().toLowerCase(), expected)
+    }))
+
+  it.effect("controls time with TestClock", () =>
+    Effect.gen(function*() {
+      const fiber = yield* Effect.forkChild(
+        Effect.sleep(60_000).pipe(Effect.as("done" as const))
+      )
+
+      // Move virtual time forward to complete sleeping fibers immediately.
+      yield* TestClock.adjust(60_000)
+
+      const value = yield* Fiber.join(fiber)
+      assert.strictEqual(value, "done")
+    }))
+
+  it.live("uses real runtime services", () =>
+    Effect.gen(function*() {
+      const startedAt = Date.now()
+      yield* Effect.sleep(1)
+      assert.isTrue(Date.now() >= startedAt)
+    }))
+
+  // For property-based testing, use `it.effect.prop` with Schema-based
+  // arbitraries
+  it.effect.prop("reversing twice is identity", [Schema.String], ([value]) =>
+    Effect.gen(function*() {
+      const reversedTwice = value.split("").reverse().reverse().join("")
+      assert.strictEqual(reversedTwice, value)
+    }))
+})

package/ai-docs/src/09_testing/20_layer-tests.ts

@@ -0,0 +1,138 @@
+/**
+ * @title Testing services with shared layers
+ *
+ * How to test Effect services that depend on other services.
+ */
+import { assert, describe, it, layer } from "@effect/vitest"
+import { Array, Context, Effect, Layer, Ref } from "effect"
+
+export interface Todo {
+  readonly id: number
+  readonly title: string
+}
+
+// Create a test ref service that can be used to store and manipulate test data
+// in layers.
+export class TodoRepoTestRef extends Context.Service<TodoRepoTestRef, Ref.Ref<Array<Todo>>>()("app/TodoRepoTestRef") {
+  static readonly layer = Layer.effect(TodoRepoTestRef, Ref.make(Array.empty()))
+}
+
+class TodoRepo extends Context.Service<TodoRepo, {
+  create(title: string): Effect.Effect<Todo>
+  readonly list: Effect.Effect<ReadonlyArray<Todo>>
+}>()("app/TodoRepo") {
+  static readonly layerTest = Layer.effect(
+    TodoRepo,
+    Effect.gen(function*() {
+      const store = yield* TodoRepoTestRef
+
+      const create = Effect.fn("TodoRepo.create")(function*(title: string) {
+        const todos = yield* Ref.get(store)
+        const todo = { id: todos.length + 1, title }
+        yield* Ref.set(store, [...todos, todo])
+        return todo
+      })
+
+      const list = Ref.get(store)
+
+      return TodoRepo.of({
+        create,
+        list
+      })
+    })
+  ).pipe(
+    // Provide the test ref layer as a dependency for the test repo layer.
+    // Use Layer.provideMerge so the tests can also access the test ref directly
+    // if needed.
+    Layer.provideMerge(TodoRepoTestRef.layer)
+  )
+}
+
+class TodoService extends Context.Service<TodoService, {
+  addAndCount(title: string): Effect.Effect<number>
+  readonly titles: Effect.Effect<ReadonlyArray<string>>
+}>()("app/TodoService") {
+  static readonly layerNoDeps = Layer.effect(
+    TodoService,
+    Effect.gen(function*() {
+      const repo = yield* TodoRepo
+
+      const addAndCount = Effect.fn("TodoService.addAndCount")(function*(title: string) {
+        yield* repo.create(title)
+        const todos = yield* repo.list
+        return todos.length
+      })
+
+      const titles = repo.list.pipe(
+        Effect.map((todos) => todos.map((todo) => todo.title))
+      )
+
+      return TodoService.of({
+        addAndCount,
+        titles
+      })
+    })
+  )
+
+  // You would also add a live layer here that provides real dependencies for
+  // production code.
+  //
+  // static readonly layer = Layer.effect(TodoService, ...).pipe(
+  //   Layer.provide(TodoRepo.layer)
+  // )
+
+  static readonly layerTest = this.layerNoDeps.pipe(
+    // Provide the test repo layer as a dependency for the test service layer.
+    // Use `Layer.provideMerge` so the tests can also access the test repo
+    // directly if needed, as well as the test ref through the repo layer.
+    Layer.provideMerge(TodoRepo.layerTest)
+  )
+}
+
+// `layer(...)` creates one shared layer for the block and tears it down in
+// `afterAll`, so all tests inside can access the same service context.
+layer(TodoRepo.layerTest)("TodoRepo", (it) => {
+  it.effect("tests repository behavior", () =>
+    Effect.gen(function*() {
+      const repo = yield* TodoRepo
+      const before = (yield* repo.list).length
+      assert.strictEqual(before, 0)
+
+      yield* repo.create("Write docs")
+
+      const after = (yield* repo.list).length
+      assert.strictEqual(after, 1)
+    }))
+
+  it.effect("layer is shared", () =>
+    Effect.gen(function*() {
+      const repo = yield* TodoRepo
+      const before = (yield* repo.list).length
+      assert.strictEqual(before, 1)
+
+      yield* repo.create("Write docs again")
+
+      // because the layer is shared between tests, the todo created in the
+      // previous test is still present, so the count should be 2, not 1
+      const after = (yield* repo.list).length
+      assert.strictEqual(after, 2)
+    }))
+})
+
+describe("TodoService", () => {
+  it.effect("tests higher-level service logic", () =>
+    Effect.gen(function*() {
+      const ref = yield* TodoRepoTestRef
+      const service = yield* TodoService
+      const count = yield* service.addAndCount("Review docs")
+      const titles = yield* service.titles
+
+      assert.isTrue(count >= 1)
+      assert.isTrue(titles.some((title) => title.includes("Review docs")))
+
+      // You can also access the test ref directly to make assertions about the
+      // underlying data.
+      const todos = yield* Ref.get(ref)
+      assert.isTrue(todos.length >= 1)
+    }).pipe(Effect.provide(TodoService.layerTest)))
+})

package/ai-docs/src/09_testing/index.md

@@ -0,0 +1 @@
+## Testing Effect programs

package/ai-docs/src/10_predicate/01_basics.ts

@@ -0,0 +1,14 @@
+/**
+ * @title Using the Predicate module
+ */
+import { Predicate } from "effect"
+
+const thing: unknown = {
+  a: 1
+}
+
+if (Predicate.isObject(thing)) {
+  if (Predicate.isNumber(thing.a)) {
+    console.log("number", thing.a)
+  }
+}

package/ai-docs/src/10_predicate/index.md

@@ -0,0 +1,9 @@
+## Runtime type guards
+
+The `Predicate` module contains small, reusable runtime checks.
+
+**NEVER** write your own helper functions like `isRecord` or `isString`, instead
+use the helpers from the `Predicate` module.
+
+Predicates can be composed with apis such as `Predicate.and`,
+`Predicate.or`, `Predicate.not`, and `Predicate.compose`.