effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/JsonPointer.ts

@@ -53,24 +53,25 @@
  */
 
 /**
- * Escapes a JSON Pointer reference token according to RFC 6901.
+ * Escapes a JSON Pointer reference token according to RFC 6901 by encoding special characters so the token can be safely used as a segment in a JSON Pointer.
  *
- * Encodes special characters in a reference token so it can be safely used as a segment in a JSON Pointer.
- *
- * ## When to use this
+ * **When to use**
  *
  * - Building JSON Pointers from object keys or path segments that may contain special characters
  * - Escaping tokens before joining them with `/` to form a complete JSON Pointer
  * - Preparing reference tokens for use in JSON Patch operations or schema references
  *
- * ## Behavior
+ * **Details**
  *
  * - Does not mutate the input string; returns a new escaped string
  * - Replaces `~` (tilde) with `~0` and `/` (forward slash) with `~1`
- * - Replacement order matters: `~` is replaced before `/` to prevent double-escaping
  * - Returns the input unchanged if it contains no special characters
  * - Empty strings are valid and returned unchanged
  *
+ * **Gotchas**
+ *
+ * The replacement order matters: `~` is replaced before `/` to prevent double-escaping.
+ *
  * **Example** (Escaping special characters)
  *
  * ```ts
@@ -81,10 +82,7 @@
  * JsonPointer.escapeToken("path/to~key") // "path~1to~0key"
  * ```
  *
- * ## See also
- *
- * - {@link unescapeToken} - The inverse operation for decoding escaped tokens
- *
+ * @see {@link unescapeToken} The inverse operation for decoding escaped tokens
  * @category encoding
  * @since 4.0.0
  */
@@ -93,24 +91,25 @@ export function escapeToken(token: string): string {
 }
 
 /**
- * Unescapes a JSON Pointer reference token according to RFC 6901.
+ * Unescapes a JSON Pointer reference token according to RFC 6901 by decoding escaped characters to recover the original token value.
  *
- * Decodes escaped characters in a reference token to recover the original token value.
- *
- * ## When to use this
+ * **When to use**
  *
  * - Parsing JSON Pointers to extract the original token values from escaped segments
  * - Converting escaped tokens back to their original form for use as object keys or identifiers
  * - Resolving schema references or JSON Patch paths that use escaped tokens
  *
- * ## Behavior
+ * **Details**
  *
  * - Does not mutate the input string; returns a new unescaped string
  * - Replaces `~1` with `/` (forward slash) and `~0` with `~` (tilde)
- * - Replacement order matters: `~1` is replaced before `~0` to prevent incorrect decoding
  * - Returns the input unchanged if it contains no escaped sequences
  * - Empty strings are valid and returned unchanged
  *
+ * **Gotchas**
+ *
+ * The replacement order matters: `~1` is replaced before `~0` to prevent incorrect decoding.
+ *
  * **Example** (Unescaping special characters)
  *
  * ```ts
@@ -121,10 +120,7 @@ export function escapeToken(token: string): string {
  * JsonPointer.unescapeToken("path~1to~0key") // "path/to~key"
  * ```
  *
- * ## See also
- *
- * - {@link escapeToken} - The inverse operation for encoding tokens
- *
+ * @see {@link escapeToken} The inverse operation for encoding tokens
  * @category decoding
  * @since 4.0.0
  */

package/src/JsonSchema.ts

@@ -92,9 +92,10 @@ import * as Rec from "./Record.ts"
 /**
  * A plain object representing a single JSON Schema node.
  *
- * This is an open record type (`[x: string]: unknown`) so it can hold any
- * JSON Schema keyword. Most functions in this module accept or return this
- * type.
+ * **Details**
+ *
+ * This is an open record type (`[x: string]: unknown`) so it can hold any JSON
+ * Schema keyword. Most functions in this module accept or return this type.
  *
  * @category models
  * @since 4.0.0
@@ -106,10 +107,11 @@ export interface JsonSchema {
 /**
  * The set of JSON Schema dialects supported by this module.
  *
- * - `"draft-07"` — JSON Schema Draft-07
- * - `"draft-2020-12"` — JSON Schema Draft 2020-12 (canonical internal form)
- * - `"openapi-3.1"` — OpenAPI 3.1 (uses Draft 2020-12 as its schema dialect)
- * - `"openapi-3.0"` — OpenAPI 3.0 (uses a Draft-04/07 subset with extensions)
+ * **Details**
+ *
+ * Supported values are `"draft-07"` for JSON Schema Draft-07,
+ * `"draft-2020-12"` for JSON Schema Draft 2020-12 and the canonical internal
+ * form, `"openapi-3.1"` for OpenAPI 3.1, and `"openapi-3.0"` for OpenAPI 3.0.
  *
  * @category models
  * @since 4.0.0
@@ -136,16 +138,19 @@ export interface Definitions extends Record<string, JsonSchema> {}
  * A structured container for a single JSON Schema and its associated
  * definitions.
  *
- * - Use when you need to carry a root schema together with its
- *   shared definitions.
- * - Use when converting between dialects via the `from*` / `to*` functions.
+ * **When to use**
+ *
+ * Use `Document` when you need to carry a root schema together with its shared
+ * definitions, or when converting between dialects with the `from*` and `to*`
+ * functions.
+ *
+ * **Details**
  *
  * The `schema` field holds the root schema *without* the definitions
  * collection. Root definitions are stored separately in `definitions` and
- * referenced via:
- * - `#/$defs/<name>` for Draft-2020-12
- * - `#/definitions/<name>` for Draft-07
- * - `#/components/schemas/<name>` for OpenAPI 3.1 and OpenAPI 3.0
+ * referenced via `#/$defs/<name>` for Draft-2020-12, `#/definitions/<name>`
+ * for Draft-07, and `#/components/schemas/<name>` for OpenAPI 3.1 and
+ * OpenAPI 3.0.
  *
  * **Example** (Inspecting a parsed document)
  *
@@ -167,7 +172,6 @@ export interface Definitions extends Record<string, JsonSchema> {}
  * @see {@link MultiDocument}
  * @see {@link fromSchemaDraft2020_12}
  * @category models
- *
  * @since 4.0.0
  */
 export interface Document<D extends Dialect> {
@@ -178,16 +182,20 @@ export interface Document<D extends Dialect> {
 
 /**
  * Like {@link Document}, but carries multiple root schemas that share a
- * single definitions pool. The `schemas` tuple is non-empty (at least one
- * element).
+ * single definitions pool.
+ *
+ * **When to use**
  *
- * - Use when generating several schemas (e.g. request body + response body)
- *   that reference the same set of definitions.
+ * Use `MultiDocument` when generating several schemas, such as a request body
+ * and a response body, that reference the same set of definitions.
+ *
+ * **Details**
+ *
+ * The `schemas` tuple is non-empty and contains at least one element.
  *
  * @see {@link Document}
  * @see {@link toMultiDocumentOpenApi3_1}
  * @category models
- *
  * @since 4.0.0
  */
 export interface MultiDocument<D extends Dialect> {
@@ -219,13 +227,22 @@ const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/
 /**
  * Parses a raw Draft-07 JSON Schema into a `Document<"draft-2020-12">`.
  *
- * - Use when you have a JSON Schema that follows Draft-07 conventions.
- * - Converts Draft-07 tuple syntax (`items` as array + `additionalItems`)
- *   to Draft-2020-12 form (`prefixItems` + `items`).
- * - Rewrites `#/definitions/...` refs to `#/$defs/...`.
- * - Extracts root-level `definitions` into the `definitions` field.
- * - Does not mutate the input. Allocates a new `Document`.
- * - Unsupported keywords (e.g. `if`/`then`/`else`, `$id`) are dropped.
+ * **When to use**
+ *
+ * Use this when you have a JSON Schema that follows Draft-07 conventions and
+ * need the canonical Draft-2020-12 document representation.
+ *
+ * **Details**
+ *
+ * This converts Draft-07 tuple syntax (`items` as array plus
+ * `additionalItems`) to Draft-2020-12 form (`prefixItems` plus `items`),
+ * rewrites `#/definitions/...` refs to `#/$defs/...`, and extracts root-level
+ * `definitions` into the `definitions` field. It does not mutate the input and
+ * allocates a new `Document`.
+ *
+ * **Gotchas**
+ *
+ * Unsupported keywords, such as `if`/`then`/`else` and `$id`, are dropped.
  *
  * **Example** (Parsing a Draft-07 schema)
  *
@@ -251,7 +268,6 @@ const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/
  * @see {@link fromSchemaOpenApi3_0}
  * @see {@link toDocumentDraft07}
  * @category decoding
- *
  * @since 4.0.0
  */
 export function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12"> {
@@ -365,10 +381,15 @@ export function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12"> {
 /**
  * Parses a raw Draft-2020-12 JSON Schema into a `Document<"draft-2020-12">`.
  *
- * - Use when you already have a schema in Draft-2020-12 format.
- * - Separates `$defs` from the root schema into the `definitions` field.
- * - Does not mutate the input. Allocates a new `Document`.
- * - Unlike {@link fromSchemaDraft07}, this performs no keyword rewriting.
+ * **When to use**
+ *
+ * Use this when you already have a schema in Draft-2020-12 format.
+ *
+ * **Details**
+ *
+ * This separates `$defs` from the root schema into the `definitions` field. It
+ * does not mutate the input and allocates a new `Document`. Unlike
+ * {@link fromSchemaDraft07}, this performs no keyword rewriting.
  *
  * **Example** (Parsing a Draft-2020-12 schema)
  *
@@ -389,7 +410,6 @@ export function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12"> {
  * @see {@link fromSchemaDraft07}
  * @see {@link fromSchemaOpenApi3_1}
  * @category decoding
- *
  * @since 4.0.0
  */
 export function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12"> {
@@ -404,10 +424,15 @@ export function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12"
 /**
  * Parses a raw OpenAPI 3.1 JSON Schema into a `Document<"draft-2020-12">`.
  *
- * - Use when consuming schemas from an OpenAPI 3.1 specification.
- * - Rewrites `#/components/schemas/...` refs to `#/$defs/...`.
- * - Delegates to {@link fromSchemaDraft2020_12} after rewriting refs.
- * - Does not mutate the input. Allocates a new `Document`.
+ * **When to use**
+ *
+ * Use this when consuming schemas from an OpenAPI 3.1 specification.
+ *
+ * **Details**
+ *
+ * This rewrites `#/components/schemas/...` refs to `#/$defs/...`, then delegates
+ * to {@link fromSchemaDraft2020_12}. It does not mutate the input and allocates
+ * a new `Document`.
  *
  * **Example** (Parsing an OpenAPI 3.1 schema)
  *
@@ -429,7 +454,6 @@ export function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12"
  * @see {@link fromSchemaOpenApi3_0}
  * @see {@link toMultiDocumentOpenApi3_1}
  * @category decoding
- *
  * @since 4.0.0
  */
 export function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12"> {
@@ -440,12 +464,17 @@ export function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12">
 /**
  * Parses a raw OpenAPI 3.0 JSON Schema into a `Document<"draft-2020-12">`.
  *
- * - Use when consuming schemas from an OpenAPI 3.0 specification.
- * - Handles OpenAPI 3.0 extensions: `nullable`, singular `example`,
- *   boolean `exclusiveMinimum`/`exclusiveMaximum`.
- * - Normalizes the schema to Draft-07 first, then converts to
- *   Draft-2020-12 via {@link fromSchemaDraft07}.
- * - Does not mutate the input. Allocates a new `Document`.
+ * **When to use**
+ *
+ * Use this when consuming schemas from an OpenAPI 3.0 specification.
+ *
+ * **Details**
+ *
+ * This handles OpenAPI 3.0 extensions, including `nullable`, singular
+ * `example`, and boolean `exclusiveMinimum` or `exclusiveMaximum`. It
+ * normalizes the schema to Draft-07 first, then converts to Draft-2020-12 via
+ * {@link fromSchemaDraft07}. It does not mutate the input and allocates a new
+ * `Document`.
  *
  * **Example** (Parsing an OpenAPI 3.0 nullable schema)
  *
@@ -465,7 +494,6 @@ export function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12">
  * @see {@link fromSchemaOpenApi3_1}
  * @see {@link fromSchemaDraft07}
  * @category decoding
- *
  * @since 4.0.0
  */
 export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-12"> {
@@ -476,13 +504,21 @@ export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-1
 /**
  * Converts a `Document<"draft-2020-12">` to a `Document<"draft-07">`.
  *
- * - Use when you need to output a schema in Draft-07 format.
- * - Rewrites `#/$defs/...` refs to `#/definitions/...`.
- * - Converts Draft-2020-12 tuple syntax (`prefixItems` + `items`) to
- *   Draft-07 form (`items` as array + `additionalItems`).
- * - Converts both the root schema and all definitions.
- * - Does not mutate the input. Allocates a new `Document`.
- * - Unsupported Draft-2020-12 keywords are dropped.
+ * **When to use**
+ *
+ * Use this when you need to output a schema in Draft-07 format.
+ *
+ * **Details**
+ *
+ * This rewrites `#/$defs/...` refs to `#/definitions/...`, converts
+ * Draft-2020-12 tuple syntax (`prefixItems` plus `items`) to Draft-07 form
+ * (`items` as array plus `additionalItems`), and converts both the root schema
+ * and all definitions. It does not mutate the input and allocates a new
+ * `Document`.
+ *
+ * **Gotchas**
+ *
+ * Unsupported Draft-2020-12 keywords are dropped.
  *
  * **Example** (Converting to Draft-07)
  *
@@ -504,7 +540,6 @@ export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-1
  * @see {@link fromSchemaDraft07}
  * @see {@link toMultiDocumentOpenApi3_1}
  * @category encoding
- *
  * @since 4.0.0
  */
 export function toDocumentDraft07(document: Document<"draft-2020-12">): Document<"draft-07"> {
@@ -620,13 +655,18 @@ function toSchemaDraft07(schema: JsonSchema): JsonSchema {
  * Converts a `MultiDocument<"draft-2020-12">` to a
  * `MultiDocument<"openapi-3.1">`.
  *
- * - Use when generating an OpenAPI 3.1 specification from internal schemas.
- * - Rewrites `#/$defs/...` refs to `#/components/schemas/...`.
- * - Sanitizes definition keys to match the OpenAPI component key pattern
- *   (`^[a-zA-Z0-9.\-_]+$`), replacing invalid characters with `_`.
- * - Updates all `$ref` pointers to use the sanitized keys.
- * - Converts all schemas and definitions in the multi-document.
- * - Does not mutate the input. Allocates a new `MultiDocument`.
+ * **When to use**
+ *
+ * Use this when generating an OpenAPI 3.1 specification from internal schemas.
+ *
+ * **Details**
+ *
+ * This rewrites `#/$defs/...` refs to `#/components/schemas/...`, sanitizes
+ * definition keys to match the OpenAPI component key pattern
+ * (`^[a-zA-Z0-9.\-_]+$`) by replacing invalid characters with `_`, updates all
+ * `$ref` pointers to use the sanitized keys, and converts all schemas and
+ * definitions in the multi-document. It does not mutate the input and allocates
+ * a new `MultiDocument`.
  *
  * **Example** (Converting to OpenAPI 3.1)
  *
@@ -649,7 +689,6 @@ function toSchemaDraft07(schema: JsonSchema): JsonSchema {
  * @see {@link toDocumentDraft07}
  * @see {@link MultiDocument}
  * @category encoding
- *
  * @since 4.0.0
  */
 export function toMultiDocumentOpenApi3_1(multiDocument: MultiDocument<"draft-2020-12">): MultiDocument<"openapi-3.1"> {
@@ -841,12 +880,20 @@ function widen_type(node: Record<string, unknown>): Record<string, unknown> {
  * Resolves a `$ref` string by looking up the last path segment in a
  * definitions map.
  *
- * - Use when you need to dereference a `$ref` pointer to get the
- *   actual schema it points to.
- * - Only resolves the final segment of the ref path (e.g. `"User"` from
- *   `"#/$defs/User"`); does not follow arbitrary JSON Pointer paths.
- * - Returns `undefined` if the definition is not found.
- * - Does not mutate anything. Pure function.
+ * **When to use**
+ *
+ * Use this when you need to dereference a `$ref` pointer to get the actual
+ * schema it points to.
+ *
+ * **Details**
+ *
+ * This only resolves the final segment of the ref path, such as `"User"` from
+ * `"#/$defs/User"`. It returns `undefined` if the definition is not found and
+ * does not mutate anything.
+ *
+ * **Gotchas**
+ *
+ * This function does not follow arbitrary JSON Pointer paths.
  *
  * **Example** (Resolving a $ref)
  *
@@ -867,7 +914,6 @@ function widen_type(node: Record<string, unknown>): Record<string, unknown> {
  * @see {@link resolveTopLevel$ref}
  * @see {@link Definitions}
  * @category getters
- *
  * @since 4.0.0
  */
 export function resolve$ref($ref: string, definitions: Definitions): JsonSchema | undefined {
@@ -887,10 +933,15 @@ export function resolve$ref($ref: string, definitions: Definitions): JsonSchema
  * schema. Returns the original document unchanged if the root schema is
  * not a `$ref` or if the referenced definition is not found.
  *
- * - Use to dereference a top-level `$ref` before inspecting the root
- *   schema's properties directly.
- * - Does not mutate the input. Returns the same object if no change is
- *   needed, or a shallow copy with the resolved schema.
+ * **When to use**
+ *
+ * Use this to dereference a top-level `$ref` before inspecting the root
+ * schema's properties directly.
+ *
+ * **Details**
+ *
+ * This does not mutate the input. It returns the same object if no change is
+ * needed, or a shallow copy with the resolved schema.
  *
  * **Example** (Resolving a top-level $ref)
  *
@@ -912,7 +963,6 @@ export function resolve$ref($ref: string, definitions: Definitions): JsonSchema
  * @see {@link resolve$ref}
  * @see {@link Document}
  * @category transforming
- *
  * @since 4.0.0
  */
 export function resolveTopLevel$ref(document: Document<"draft-2020-12">): Document<"draft-2020-12"> {

package/src/Latch.ts

@@ -40,6 +40,8 @@ import * as internal from "./internal/effect.ts"
  * A reusable coordination primitive that lets fibers wait until they are
  * released by the latch.
  *
+ * **Details**
+ *
  * A closed latch causes `await` and `whenOpen` to suspend. `open` opens the
  * latch and releases current and future waiters, `release` releases only
  * current waiters without opening it, and `close` makes future waiters suspend
@@ -84,8 +86,14 @@ export interface Latch {
 /**
  * Creates a `Latch` synchronously, outside of `Effect`.
  *
- * The latch starts closed by default; pass `true` to create it open. Use this
- * only when synchronous allocation is required, otherwise prefer `make`.
+ * **When to use**
+ *
+ * Use this only when synchronous allocation is required; otherwise prefer
+ * `make`.
+ *
+ * **Details**
+ *
+ * The latch starts closed by default; pass `true` to create it open.
  *
  * **Example** (Creating a latch unsafely)
  *
@@ -117,6 +125,8 @@ export const makeUnsafe: (open?: boolean | undefined) => Latch = internal.makeLa
 /**
  * Creates a `Latch` inside `Effect`.
  *
+ * **Details**
+ *
  * The latch starts closed by default; pass `true` to create it open.
  *
  * **Example** (Creating a latch)
@@ -151,6 +161,8 @@ export const make: (open?: boolean | undefined) => Effect.Effect<Latch> = intern
 /**
  * Opens the latch and releases fibers waiting on it.
  *
+ * **Details**
+ *
  * The returned effect succeeds with `true` when this call changed the latch
  * from closed to open, or `false` if it was already open.
  *
@@ -162,6 +174,8 @@ export const open = (self: Latch): Effect.Effect<boolean> => self.open
 /**
  * Synchronously opens the latch and releases fibers waiting on it.
  *
+ * **Details**
+ *
  * Returns `true` when this call changed the latch from closed to open, or
  * `false` if it was already open. This unsafe variant performs the state
  * change immediately instead of returning an `Effect`.
@@ -174,6 +188,8 @@ export const openUnsafe = (self: Latch): boolean => self.openUnsafe()
 /**
  * Releases the fibers currently waiting on a closed latch without opening it.
  *
+ * **Details**
+ *
  * The returned effect succeeds with `true` when release was requested while
  * the latch was closed, or `false` if the latch was already open. Future
  * waiters still suspend until the latch is opened or released again.
@@ -198,6 +214,8 @@ export {
 /**
  * Closes the latch so future `await` and `whenOpen` calls suspend.
  *
+ * **Details**
+ *
  * The returned effect succeeds with `true` when this call changed the latch
  * from open to closed, or `false` if it was already closed.
  *
@@ -210,6 +228,8 @@ export const close = (self: Latch): Effect.Effect<boolean> => self.close
  * Synchronously closes the latch so future `await` and `whenOpen` calls
  * suspend.
  *
+ * **Details**
+ *
  * Returns `true` when this call changed the latch from open to closed, or
  * `false` if it was already closed. This unsafe variant performs the state
  * change immediately instead of returning an `Effect`.
@@ -222,6 +242,8 @@ export const closeUnsafe = (self: Latch): boolean => self.closeUnsafe()
 /**
  * Waits on the latch, then runs the provided effect.
  *
+ * **Details**
+ *
  * If the latch is open, the effect runs immediately. If it is closed, the
  * returned effect suspends until the latch is opened or the current waiters are
  * released. The provided effect's success, failure, and requirements are
@@ -234,6 +256,8 @@ export const whenOpen: {
   /**
    * Waits on the latch, then runs the provided effect.
    *
+   * **Details**
+   *
    * If the latch is open, the effect runs immediately. If it is closed, the
    * returned effect suspends until the latch is opened or the current waiters are
    * released. The provided effect's success, failure, and requirements are
@@ -246,6 +270,8 @@ export const whenOpen: {
   /**
    * Waits on the latch, then runs the provided effect.
    *
+   * **Details**
+   *
    * If the latch is open, the effect runs immediately. If it is closed, the
    * returned effect suspends until the latch is opened or the current waiters are
    * released. The provided effect's success, failure, and requirements are