effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/testing/TestSchema.ts

@@ -78,11 +78,11 @@ import * as Parser from "../SchemaParser.ts"
 import * as FastCheck from "../testing/FastCheck.ts"
 
 /**
- * Entry point for schema test assertions. Wraps a schema and exposes operation-specific helpers for decoding, encoding, make, arbitrary generation, and round-trip verification.
+ * Provides schema test assertions for decoding, encoding, make, arbitrary generation, and round-trip verification.
  *
  * **When to use**
  *
- * Use `Asserts` when writing schema unit tests for decoding, encoding, construction, property-based round-trip, or generation behavior.
+ * Use when writing schema unit tests for decoding, encoding, construction, property-based round-trip, or generation behavior.
  *
  * **Example** (Decoding and encoding a struct)
  *
@@ -109,6 +109,11 @@ export class Asserts<S extends Schema.Top> {
   /**
    * Static helpers for comparing schema AST structures.
    *
+   * **When to use**
+   *
+   * Use to assert that two schema field or tuple element definitions produce
+   * the same AST structure.
+   *
    * **Details**
    *
    * `ast.fields.equals(a, b)` compares struct field ASTs via `assert.deepStrictEqual`. `ast.elements.equals(a, b)` compares tuple element ASTs via `assert.deepStrictEqual`.
@@ -144,6 +149,11 @@ export class Asserts<S extends Schema.Top> {
   /**
    * Returns an object with `succeed` and `fail` helpers for testing the schema's `make` operation.
    *
+   * **When to use**
+   *
+   * Use to assert how `Schema.make` accepts, transforms, or rejects
+   * construction input for this schema.
+   *
    * **Details**
    *
    * `succeed(input)` asserts make returns the input unchanged. `succeed(input, expected)` asserts make returns `expected`. `fail(input, message)` asserts make fails with `message`.
@@ -158,6 +168,9 @@ export class Asserts<S extends Schema.Top> {
    * const asserts = new TestSchema.Asserts(schema)
    * await asserts.make().succeed("hello")
    * ```
+   *
+   * @see {@link decoding} for assertions against decoded input
+   * @see {@link encoding} for assertions against encoded output
    */
   make(options?: Schema.MakeOptions) {
     const makeEffect = Parser.makeEffect(this.schema)
@@ -189,6 +202,11 @@ export class Asserts<S extends Schema.Top> {
   /**
    * Runs a property-based test that encodes arbitrary values and then decodes them, asserting the decoded value equals the original.
    *
+   * **When to use**
+   *
+   * Use to verify that generated schema values survive an encode-then-decode
+   * round trip.
+   *
    * **Details**
    *
    * FastCheck generates arbitrary values matching the schema's `Type`. The assertion fails if any generated value does not round-trip. Pass `options.params` to control FastCheck parameters such as `numRuns`.
@@ -202,6 +220,8 @@ export class Asserts<S extends Schema.Top> {
    * const asserts = new TestSchema.Asserts(Schema.NumberFromString)
    * await asserts.verifyLosslessTransformation()
    * ```
+   *
+   * @see {@link arbitrary} for checking that generated values satisfy the schema
    */
   verifyLosslessTransformation<S extends Schema.Codec<unknown, unknown>>(this: Asserts<S>, options?: {
     readonly params?: FastCheck.Parameters<[S["Type"]]>
@@ -226,6 +246,10 @@ export class Asserts<S extends Schema.Top> {
   /**
    * Returns a {@link Decoding} instance for this schema with helpers for decoding assertions.
    *
+   * **When to use**
+   *
+   * Use to test how unknown input is decoded into the schema's type.
+   *
    * **Details**
    *
    * Pass `parseOptions` to control error reporting, for example `{ errors: "all" }`.
@@ -243,6 +267,7 @@ export class Asserts<S extends Schema.Top> {
    * ```
    *
    * @see {@link Decoding}
+   * @see {@link encoding} for assertions in the opposite direction
    */
   decoding(options?: {
     readonly parseOptions?: AST.ParseOptions | undefined
@@ -252,6 +277,10 @@ export class Asserts<S extends Schema.Top> {
   /**
    * Returns an {@link Encoding} instance for this schema with helpers for encoding assertions.
    *
+   * **When to use**
+   *
+   * Use to test how schema values are encoded into their external form.
+   *
    * **Details**
    *
    * Pass `parseOptions` to control error reporting, for example `{ errors: "all" }`.
@@ -268,6 +297,7 @@ export class Asserts<S extends Schema.Top> {
    * ```
    *
    * @see {@link Encoding}
+   * @see {@link decoding} for assertions in the opposite direction
    */
   encoding(options?: {
     readonly parseOptions?: AST.ParseOptions | undefined
@@ -277,6 +307,11 @@ export class Asserts<S extends Schema.Top> {
   /**
    * Returns an object with property-based testing helpers for the schema's arbitrary generator.
    *
+   * **When to use**
+   *
+   * Use to verify that arbitrary values generated for this schema satisfy the
+   * schema's predicate.
+   *
    * **Details**
    *
    * `verifyGeneration()` generates arbitrary values and asserts each value satisfies the schema's `is` predicate. It defaults to 20 runs. Pass `options.params` to override FastCheck parameters.
@@ -290,6 +325,8 @@ export class Asserts<S extends Schema.Top> {
    * const asserts = new TestSchema.Asserts(Schema.String)
    * asserts.arbitrary().verifyGeneration()
    * ```
+   *
+   * @see {@link verifyLosslessTransformation} for property-based round-trip checks
    */
   arbitrary<S extends Schema.Codec<unknown, unknown, never, unknown>>(this: Asserts<S>) {
     const schema = this.schema
@@ -307,11 +344,11 @@ export class Asserts<S extends Schema.Top> {
 }
 
 /**
- * Decoding test helper that wraps a schema and exposes `succeed` and `fail` methods that run the schema's decoder and compare the result.
+ * Provides decoding test assertions through `succeed` and `fail` methods that run the schema's decoder and compare the result.
  *
  * **When to use**
  *
- * Use `Decoding` when you want to assert that specific inputs decode to expected values, invalid inputs produce specific error messages, or schemas receive required decoding services.
+ * Use when you want to assert that specific inputs decode to expected values, invalid inputs produce specific error messages, or schemas receive required decoding services.
  *
  * **Details**
  *
@@ -354,6 +391,10 @@ export class Decoding<S extends Schema.Top> {
    * output equals the input. With two arguments, asserts the output equals
    * `expected`.
    *
+   * **When to use**
+   *
+   * Use to verify successful decoding for one input case.
+   *
    * **Example** (Identity and transformed decoding)
    *
    * ```ts
@@ -363,6 +404,8 @@ export class Decoding<S extends Schema.Top> {
    * const decoding = new TestSchema.Asserts(Schema.NumberFromString).decoding()
    * await decoding.succeed("1", 1) // transformed
    * ```
+   *
+   * @see {@link fail} for asserting decoding failures
    */
   async succeed<S extends Schema.Decoder<unknown, never>>(
     this: Decoding<S>,
@@ -391,6 +434,10 @@ export class Decoding<S extends Schema.Top> {
    * Asserts that decoding `input` fails and the stringified issue equals
    * `message`.
    *
+   * **When to use**
+   *
+   * Use to verify that invalid decoding input produces the expected issue text.
+   *
    * **Example** (Asserting a decoding failure)
    *
    * ```ts
@@ -400,6 +447,8 @@ export class Decoding<S extends Schema.Top> {
    * const decoding = new TestSchema.Asserts(Schema.String).decoding()
    * await decoding.fail(42, "Expected string, got 42")
    * ```
+   *
+   * @see {@link succeed} for asserting successful decoding
    */
   async fail<S extends Schema.Decoder<unknown, never>>(
     this: Decoding<S>,
@@ -419,11 +468,7 @@ export class Decoding<S extends Schema.Top> {
    *
    * **When to use**
    *
-   * Use this when the schema's decoder requires a service dependency.
-   *
-   * **Details**
-   *
-   * This method does not mutate the current instance.
+   * Use when the schema's decoder requires a service dependency.
    *
    * @see {@link Encoding.provide}
    */
@@ -439,23 +484,15 @@ export class Decoding<S extends Schema.Top> {
 }
 
 /**
- * Encoding test helper. Mirrors {@link Decoding} but exercises the schema's
- * encoder direction.
- *
- * When to use:
- * - You want to assert that specific values encode to expected outputs.
- * - You want to assert that invalid inputs produce specific error messages
- *   during encoding.
- * - You need to provide services required by the schema's encoding pipeline.
- *
- * Behavior:
- * - All assertions are async and use `assert.deepStrictEqual` internally.
- * - `succeed(input)` asserts the encoded output equals `input` (identity).
- * - `succeed(input, expected)` asserts the encoded output equals `expected`.
- * - `fail(input, message)` asserts encoding fails and the stringified issue
- *   equals `message`.
- * - `provide(key, impl)` returns a new `Encoding` with the service injected
- *   into the encoding context.
+ * Provides encoding test assertions through `succeed` and `fail` methods that run the schema's encoder and compare the result.
+ *
+ * **When to use**
+ *
+ * Use when you want to assert that specific values encode to expected outputs, invalid inputs produce specific error messages, or schemas receive required encoding services.
+ *
+ * **Details**
+ *
+ * All assertions are async and use `assert.deepStrictEqual` internally. `succeed(input)` asserts the encoded output equals `input`; `succeed(input, expected)` asserts it equals `expected`; `fail(input, message)` asserts encoding fails and the stringified issue equals `message`. `provide(key, impl)` returns a new `Encoding` with the service injected into the encoding context.
  *
  * **Example** (Encoding assertions)
  *
@@ -470,9 +507,10 @@ export class Decoding<S extends Schema.Top> {
  * @see {@link Asserts}
  * @see {@link Decoding}
  *
+ * @category testing
  * @since 4.0.0
  */
-class Encoding<S extends Schema.Top> {
+export class Encoding<S extends Schema.Top> {
   readonly schema: S
   readonly encodeUnknownEffect: (
     input: unknown,
@@ -493,6 +531,10 @@ class Encoding<S extends Schema.Top> {
    * output equals the input. With two arguments, asserts the output equals
    * `expected`.
    *
+   * **When to use**
+   *
+   * Use to verify successful encoding for one input case.
+   *
    * **Example** (Identity and transformed encoding)
    *
    * ```ts
@@ -502,6 +544,8 @@ class Encoding<S extends Schema.Top> {
    * const encoding = new TestSchema.Asserts(Schema.NumberFromString).encoding()
    * await encoding.succeed(1, "1") // transformed
    * ```
+   *
+   * @see {@link fail} for asserting encoding failures
    */
   async succeed<S extends Schema.Encoder<unknown, never>>(
     this: Encoding<S>,
@@ -530,6 +574,10 @@ class Encoding<S extends Schema.Top> {
    * Asserts that encoding `input` fails and the stringified issue equals
    * `message`.
    *
+   * **When to use**
+   *
+   * Use to verify that invalid encoding input produces the expected issue text.
+   *
    * **Example** (Asserting an encoding failure)
    *
    * ```ts
@@ -539,6 +587,8 @@ class Encoding<S extends Schema.Top> {
    * const encoding = new TestSchema.Asserts(Schema.NumberFromString).encoding()
    * await encoding.fail("not-a-number", "Expected number, got \"not-a-number\"")
    * ```
+   *
+   * @see {@link succeed} for asserting successful encoding
    */
   async fail<S extends Schema.Encoder<unknown, never>>(
     this: Encoding<S>,
@@ -554,11 +604,11 @@ class Encoding<S extends Schema.Top> {
     assert.deepStrictEqual(r, Result.fail(message))
   }
   /**
-   * Returns a new {@link Encoding} instance with the given service injected
-   * into the encoding effect context. Use this when the schema's encoder
-   * requires a service dependency.
+   * Returns a new {@link Encoding} instance with the given service injected into the encoding effect context.
+   *
+   * **When to use**
    *
-   * - Does not mutate the current instance; returns a new one.
+   * Use when the schema's encoder requires a service dependency.
    *
    * @see {@link Decoding.provide}
    */

package/src/testing/index.ts

@@ -5,128 +5,21 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * This module provides a re-export of the fast-check library for property-based testing.
- * Fast-check is a property-based testing framework that generates random test cases
- * to validate that properties hold true for a wide range of inputs.
- *
- * Property-based testing is a testing methodology where you specify properties that
- * should hold true for your functions, and the framework generates many random test
- * cases to try to find counterexamples.
- *
  * @since 3.10.0
  */
 export * as FastCheck from "./FastCheck.ts"
 
 /**
- * The `TestClock` module provides a controllable implementation of the Effect
- * `Clock` service for tests. Instead of waiting for real time to pass, effects
- * that use `Effect.sleep`, timeouts, schedules, retries, and other time-based
- * operators can be driven deterministically by advancing the test clock.
- *
- * **Common use cases**
- *
- * - Testing sleeps, delays, timeouts, debouncing, retries, and schedules without
- *   slowing the test suite down
- * - Advancing time with {@link adjust} or jumping to an exact timestamp with
- *   {@link setTime}
- * - Running a specific effect against the live clock with {@link withLive}
- *   while the rest of the test remains under test-clock control
- *
- * **Testing gotchas**
- *
- * - Effects that sleep semantically block until the clock is advanced far
- *   enough, so tests usually fork the time-dependent effect before calling
- *   {@link adjust} or {@link setTime}
- * - Scheduled sleeps are resumed in clock-time order as the test clock moves
- *   forward
- * - If a test uses time but never advances the `TestClock`, the module starts a
- *   delayed warning to help identify a hanging test
- *
  * @since 2.0.0
  */
 export * as TestClock from "./TestClock.ts"
 
 /**
- * The `TestConsole` module provides a test implementation of the `Console`
- * service that records console calls instead of writing them to the host
- * environment. It is useful when testing workflows that use `Console.log` or
- * `Console.error` and need to assert on the produced output.
- *
- * Use {@link layer} to provide the test console to an effect, then inspect
- * captured output with {@link logLines} and {@link errorLines}. Because console
- * operations are service-based effects, programs under test must be run with
- * this layer for their output to be captured.
- *
  * @since 4.0.0
  */
 export * as TestConsole from "./TestConsole.ts"
 
 /**
- * Testing utilities for asserting Schema decoding, encoding, make, and
- * arbitrary-generation behavior. Used in unit tests to verify that schemas
- * accept, reject, and round-trip values correctly.
- *
- * ## Mental model
- *
- * - **Asserts** – entry point: wraps a schema and exposes helpers grouped by
- *   operation (decoding, encoding, make, arbitrary, round-trip).
- * - **Decoding** – returned by `asserts.decoding()`; has `succeed` / `fail`
- *   helpers that run the schema's decoder and compare the result.
- * - **Encoding** – returned by `asserts.encoding()`; mirrors {@link Decoding}
- *   but exercises the encoder direction.
- * - Every assertion is async (`Promise<void>`) because parsing may involve
- *   effectful schemas.
- * - `succeed` with one argument asserts identity (output equals input);
- *   with two arguments asserts a specific expected output.
- * - `fail` always takes the input and the expected error message string.
- *
- * ## Common tasks
- *
- * - Assert decoding succeeds / fails → `new Asserts(schema).decoding().succeed(…)` / `.fail(…)`
- * - Assert encoding succeeds / fails → `new Asserts(schema).encoding().succeed(…)` / `.fail(…)`
- * - Assert make succeeds / fails → `new Asserts(schema).make().succeed(…)` / `.fail(…)`
- * - Verify round-trip (encode then decode) → `new Asserts(schema).verifyLosslessTransformation()`
- * - Verify arbitrary generation → `new Asserts(schema).arbitrary().verifyGeneration()`
- * - Compare AST of struct fields → `Asserts.ast.fields.equals(a, b)`
- * - Provide a service dependency for decoding → `asserts.decoding().provide(key, impl)`
- *
- * ## Gotchas
- *
- * - `succeed` uses `assert.deepStrictEqual`, so reference equality is not
- *   required but structural equality is.
- * - `fail` compares against the stringified `Issue`, not the `Issue` object
- *   itself. Pass the exact multiline string the issue produces.
- * - `verifyLosslessTransformation` and `arbitrary().verifyGeneration` run
- *   property-based tests via FastCheck; default run count is 20 for
- *   `verifyGeneration`.
- *
- * ## Quickstart
- *
- * **Example** (Basic decoding and encoding assertions)
- *
- * ```ts
- * import { Schema } from "effect"
- * import { TestSchema } from "effect/testing"
- *
- * const schema = Schema.NumberFromString
- * const asserts = new TestSchema.Asserts(schema)
- *
- * // decoding
- * const decoding = asserts.decoding()
- * await decoding.succeed("1", 1)
- * await decoding.fail(null, "Expected string, got null")
- *
- * // encoding
- * const encoding = asserts.encoding()
- * await encoding.succeed(1, "1")
- * ```
- *
- * ## See also
- *
- * - {@link Asserts}
- * - {@link Decoding}
- * - {@link Encoding}
- *
  * @since 4.0.0
  */
 export * as TestSchema from "./TestSchema.ts"

package/src/unstable/ai/AiError.ts

@@ -364,7 +364,12 @@ export interface UnsupportedSchemaErrorMetadata extends ProviderMetadata {}
 export interface UnknownErrorMetadata extends ProviderMetadata {}
 
 /**
- * Token usage information from AI operations.
+ * Schema for token usage information from AI operations.
+ *
+ * **Details**
+ *
+ * Schema for optional provider-reported token counts for prompt tokens,
+ * completion tokens, and total tokens.
  *
  * @category schemas
  * @since 4.0.0
@@ -376,7 +381,20 @@ export const UsageInfo = Schema.Struct({
 }).annotate({ identifier: "UsageInfo" })
 
 /**
- * Combined HTTP context for error reporting.
+ * Schema for the combined HTTP context used in error reporting.
+ *
+ * **When to use**
+ *
+ * Use to attach request details, optional response details, and optional body
+ * text to AI provider errors.
+ *
+ * **Details**
+ *
+ * Includes the required request details plus optional response details and raw
+ * response body.
+ *
+ * @see {@link HttpRequestDetails} for captured request details
+ * @see {@link HttpResponseDetails} for captured response details
  *
  * @category schemas
  * @since 4.0.0
@@ -937,7 +955,7 @@ export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaE
 }
 
 /**
- * Catch-all error for unknown or unexpected errors.
+ * Error data for unknown or unexpected AI failures.
  *
  * **Details**
  *
@@ -1415,6 +1433,16 @@ export type AiErrorReason =
 /**
  * Schema for validating and parsing AI error reasons.
  *
+ * **When to use**
+ *
+ * Use when decoding or validating unknown AI error reason values with Schema.
+ *
+ * **Details**
+ *
+ * This runtime schema is the union of the concrete AI error reason classes.
+ *
+ * @see {@link isAiErrorReason} for checking an existing value without Schema decoding
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -1465,7 +1493,7 @@ export const AiErrorReason: Schema.Union<[
 const TypeId = "~effect/unstable/ai/AiError/AiError" as const
 
 /**
- * Top-level AI error wrapper using the `reason` pattern.
+ * Schema for the top-level AI error wrapper using the `reason` pattern.
  *
  * **When to use**
  *
@@ -1619,7 +1647,7 @@ export const make = (params: {
  *
  * **When to use**
  *
- * Provider packages can use this as a base for provider-specific mapping.
+ * Use when provider packages can use this as a base for provider-specific mapping.
  *
  * **Example** (Mapping an HTTP status to a reason)
  *

package/src/unstable/ai/AnthropicStructuredOutput.ts

@@ -1,17 +1,38 @@
 /**
- * Provides a codec transformation for Anthropic structured output.
+ * Adapt Effect Schema codecs to the JSON Schema subset accepted by Anthropic
+ * structured output.
  *
- * Anthropic's API has specific constraints on JSON schema support that differ
- * from the full JSON Schema specification. This module transforms Effect
- * `Schema.Codec` types into a form compatible with Anthropic's structured
- * output requirements by:
+ * The main entry point is {@link toCodecAnthropic}. It returns the JSON Schema
+ * to send to Anthropic and a codec that preserves the original decoded value
+ * type while changing the encoded representation when Anthropic cannot express
+ * that shape directly.
  *
- * - Converting tuples to objects with string keys (tuples are unsupported)
- * - Converting optional properties to nullable unions (`T | null`)
- * - Converting index signatures (records) to arrays of key-value pairs
- * - Converting `oneOf` unions to `anyOf` unions
- * - Stripping unsupported annotations and preserving only Anthropic-compatible
- *   formats and descriptions
+ * **Mental model**
+ *
+ * Anthropic structured output accepts a narrower schema vocabulary than Effect
+ * Schema. This module walks the encoded schema AST before JSON Schema
+ * generation, rewrites unsupported shapes into provider-safe encodings, and
+ * leaves the returned codec responsible for translating model output back into
+ * the original application shape.
+ *
+ * **Common tasks**
+ *
+ * - Convert a `Schema.Codec` for Anthropic structured output with
+ *   {@link toCodecAnthropic}
+ * - Decode model output with the returned codec so transformed tuples, records,
+ *   and optional properties become the original values again
+ * - Preserve provider-compatible descriptions and formats while dropping or
+ *   rewriting annotations Anthropic cannot represent
+ *
+ * **Gotchas**
+ *
+ * - The emitted JSON Schema may use an encoded shape: tuples become objects
+ *   with numeric string keys, records become arrays of `[key, value]` pairs, and
+ *   optional properties become required properties that accept `null`.
+ * - Unsupported schema kinds throw during conversion rather than producing a
+ *   lossy schema.
+ * - `oneOf` unions are emitted as `anyOf` unions because Anthropic's structured
+ *   output subset does not support the full JSON Schema vocabulary.
  *
  * @since 4.0.0
  */
@@ -22,11 +43,19 @@ import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
 import * as AST from "../../SchemaAST.ts"
 import * as Transformation from "../../SchemaTransformation.ts"
+import * as LanguageModel from "./LanguageModel.ts"
+import * as OpenAiStructuredOutput from "./OpenAiStructuredOutput.ts"
 import * as Tool from "./Tool.ts"
 
 /**
  * Transforms a `Schema.Codec` into a form compatible with Anthropic's structured output constraints.
  *
+ * **When to use**
+ *
+ * Use to adapt an `Effect` `Schema.Codec` for Anthropic structured output by
+ * returning an Anthropic-compatible JSON Schema together with a codec that
+ * preserves the decoded value type.
+ *
  * **Details**
  *
  * The transformation walks the schema AST and rewrites constructs that Anthropic does not support natively:
@@ -46,6 +75,9 @@ import * as Tool from "./Tool.ts"
  * If the schema is already compatible, the original codec is returned
  * unchanged.
  *
+ * @see {@link LanguageModel.CodecTransformer} for the structured-output transformer contract
+ * @see {@link OpenAiStructuredOutput.toCodecOpenAI} for the OpenAI-specific transformer
+ *
  * @category Codec Transformation
  * @since 4.0.0
  */