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

package/src/JsonPatch.ts

@@ -1,54 +1,62 @@
 /**
- * JSON Patch operations for transforming JSON documents.
+ * The `JsonPatch` module computes and applies deterministic patch documents for
+ * JSON values. A patch is an ordered list of `add`, `remove`, and `replace`
+ * operations addressed by JSON Pointer paths. Use it to describe the structural
+ * difference between two JSON documents, serialize that difference, and replay
+ * it without mutating the original input.
+ *
+ * **Mental model**
+ *
+ * - A {@link JsonPatch} is applied from left to right; each operation observes
+ *   the document produced by the operations before it.
+ * - Paths use JSON Pointer syntax. The empty path `""` targets the whole
+ *   document, and `/users/0/name` targets a nested property or array element.
+ * - This module implements the deterministic `add`, `remove`, and `replace`
+ *   subset of RFC 6902. It does not model `test`, `move`, or `copy`.
+ * - {@link get} compares JSON structure, not domain meaning. It can detect that
+ *   a value changed, but it does not infer semantic edits such as array moves.
+ * - {@link apply} copies changed containers and returns a new JSON value. An
+ *   empty patch returns the original document reference.
+ *
+ * **Common tasks**
+ *
+ * - Compute a structural diff between two JSON values with {@link get}.
+ * - Apply generated or hand-written operations with {@link apply}.
+ * - Accept, store, or serialize complete patch documents as {@link JsonPatch}.
+ * - Type individual operations with {@link JsonPatchOperation}.
  *
- * This module implements a subset of RFC 6902, providing operations that can be applied deterministically without additional context. It supports computing structural diffs between JSON values and applying patches to transform documents.
- *
- * ## Mental model
- *
- * - **JSON Patch**: An ordered sequence of operations that transform a document from one state to another
- * - **JSON Pointer**: Path syntax for targeting specific locations in a JSON document (e.g., `/users/0/name`)
- * - **Operations**: Three types - `add` (insert value), `remove` (delete value), `replace` (update value)
- * - **Immutable transformations**: All operations return new values; inputs are never mutated
- * - **Sequential application**: Operations are applied in order, with later operations observing changes from earlier ones
- * - **Structural diff**: The `get` function computes differences by comparing structure, not content semantics
- *
- * ## Common tasks
- *
- * - Computing diffs between JSON values → {@link get}
- * - Applying patches to transform documents → {@link apply}
- * - Creating patches manually → {@link JsonPatchOperation}
- * - Storing and validating patch documents → {@link JsonPatch}
- *
- * ## Gotchas
- *
- * - Array removals are emitted from highest index to lowest to avoid index shifting during application
- * - Root operations use an empty string path `""` to target the entire document
- * - Array append operations use `-` as the last token in the path (e.g., `/items/-`)
- * - Generated patches are deterministic but not guaranteed to be minimal
- * - Empty patches return the original document reference (no allocation)
- * - Invalid paths or operations throw errors rather than returning a result type
+ * **Gotchas**
  *
- * ## Quickstart
+ * - Generated patches are deterministic, but not guaranteed to be minimal.
+ * - Array removals are emitted from highest index to lowest so later removals do
+ *   not shift earlier targets.
+ * - `"-"` is valid only as the final token for array append operations.
+ * - Invalid paths, missing properties, and out-of-bounds array indices throw.
+ * - Root `add` and `replace` operations replace the whole document; root
+ *   `remove` is unsupported.
  *
  * **Example** (Computing and applying a patch)
  *
  * ```ts
  * import { JsonPatch } from "effect"
  *
- * const oldValue = { name: "Alice", age: 30 }
- * const newValue = { name: "Alice", age: 31, city: "NYC" }
+ * const before = { title: "draft", tags: ["fp"] }
+ * const after = { title: "published", tags: ["fp", "effect"] }
  *
- * const patch = JsonPatch.get(oldValue, newValue)
- * // [{ op: "replace", path: "/age", value: 31 }, { op: "add", path: "/city", value: "NYC" }]
+ * const patch = JsonPatch.get(before, after)
+ * // [
+ * //   { op: "add", path: "/tags/1", value: "effect" },
+ * //   { op: "replace", path: "/title", value: "published" }
+ * // ]
  *
- * const result = JsonPatch.apply(patch, oldValue)
- * // { name: "Alice", age: 31, city: "NYC" }
+ * const updated = JsonPatch.apply(patch, before)
+ * // { title: "published", tags: ["fp", "effect"] }
  * ```
  *
- * ## See also
+ * **See also**
  *
- * - {@link JsonPointer} - Utilities for working with JSON Pointer paths
- * - {@link Schema.Json} - The JSON value type used by this module
+ * - `JsonPointer` for escaping and unescaping JSON Pointer path tokens.
+ * - {@link Schema.Json} for the JSON value shape accepted by this module.
  *
  * @since 4.0.0
  */
@@ -62,8 +70,8 @@ import type * as Schema from "./Schema.ts"
  *
  * **When to use**
  *
- * Use this type when manually constructing patch operations, accepting patch
- * operations from callers, or type-checking patch operation structures.
+ * Use to manually construct patch operations, accept patch operations from
+ * callers, or type-check patch operation structures.
  *
  * **Details**
  *
@@ -97,9 +105,9 @@ import type * as Schema from "./Schema.ts"
  * }
  * ```
  *
- * @see {@link JsonPatch} - Array of operations forming a complete patch
- * @see {@link get} - Computes operations automatically from value differences
- * @see {@link apply} - Applies operations to transform documents
+ * @see {@link JsonPatch} for the array of operations forming a complete patch
+ * @see {@link get} to compute operations automatically from value differences
+ * @see {@link apply} to apply operations to transform documents
  * @category models
  * @since 4.0.0
  */
@@ -109,6 +117,10 @@ export type JsonPatchOperation =
     /**
      * JSON Pointer to the target location. For arrays, the last token may be `-`
      * to append.
+     *
+     * **When to use**
+     *
+     * Use to identify where the `add` operation inserts its value.
      */
     readonly path: string
     readonly value: Schema.Json
@@ -116,13 +128,25 @@ export type JsonPatchOperation =
   }
   | {
     readonly op: "remove"
-    /** JSON Pointer to the target location. */
+    /**
+     * JSON Pointer to the target location.
+     *
+     * **When to use**
+     *
+     * Use to identify which location the `remove` operation deletes.
+     */
     readonly path: string
     readonly description?: string
   }
   | {
     readonly op: "replace"
-    /** JSON Pointer to the target location. Use `""` to replace the root document. */
+    /**
+     * JSON Pointer to the target location. Use `""` to replace the root document.
+     *
+     * **When to use**
+     *
+     * Use to identify which location the `replace` operation overwrites.
+     */
     readonly path: string
     readonly value: Schema.Json
     readonly description?: string
@@ -133,8 +157,7 @@ export type JsonPatchOperation =
  *
  * **When to use**
  *
- * Use this type when storing, serializing, passing, or validating complete patch
- * documents.
+ * Use to store, serialize, pass, or validate complete patch documents.
  *
  * **Details**
  *
@@ -158,9 +181,9 @@ export type JsonPatchOperation =
  * // { count: 5, items: ["apple"] }
  * ```
  *
- * @see {@link JsonPatchOperation} - Individual operation types
- * @see {@link get} - Generates patches from value differences
- * @see {@link apply} - Executes patches to transform documents
+ * @see {@link JsonPatchOperation} for individual operation types
+ * @see {@link get} to generate patches from value differences
+ * @see {@link apply} to execute patches to transform documents
  * @category models
  * @since 4.0.0
  */
@@ -171,7 +194,7 @@ export type JsonPatch = ReadonlyArray<JsonPatchOperation>
  *
  * **When to use**
  *
- * Use `get` to compute differences between JSON documents, detect structural
+ * Use to compute differences between JSON documents, detect structural
  * changes, or create deterministic update operations from before and after
  * states.
  *
@@ -181,7 +204,7 @@ export type JsonPatch = ReadonlyArray<JsonPatchOperation>
  * yields `newValue` when applied to `oldValue`. It returns an empty array when
  * values are identical, recursively diffs nested structures, emits root
  * `replace` operations for primitive changes, and processes object keys in
- * sorted order for stable output. Inputs are not mutated.
+ * sorted order for stable output.
  *
  * **Gotchas**
  *
@@ -205,8 +228,8 @@ export type JsonPatch = ReadonlyArray<JsonPatchOperation>
  * // ]
  * ```
  *
- * @see {@link apply} - Applies the generated patch to a document
- * @see {@link JsonPatchOperation} - The operation types in the patch
+ * @see {@link apply} to apply the generated patch to a document
+ * @see {@link JsonPatchOperation} for the operation types in the patch
  * @category transforming
  * @since 4.0.0
  */
@@ -278,7 +301,7 @@ export function get(oldValue: Schema.Json, newValue: Schema.Json): JsonPatch {
  *
  * **When to use**
  *
- * Use `apply` to execute patches generated by {@link get}, transform documents
+ * Use to execute patches generated by {@link get}, transform documents
  * with manually constructed patches, or process patch operations from external
  * sources.
  *
@@ -310,8 +333,8 @@ export function get(oldValue: Schema.Json, newValue: Schema.Json): JsonPatch {
  * // { items: [1, 2, 3, 4], total: 10 }
  * ```
  *
- * @see {@link get} - Generates patches from value differences
- * @see {@link JsonPatchOperation} - The operation types being applied
+ * @see {@link get} to generate patches from value differences
+ * @see {@link JsonPatchOperation} for the operation types being applied
  * @category transforming
  * @since 4.0.0
  */

package/src/JsonPointer.ts

@@ -57,13 +57,13 @@
  *
  * **When to use**
  *
- * - Building JSON Pointers from object keys or path segments that may contain special characters
+ * Use to build 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
  *
  * **Details**
  *
- * - Does not mutate the input string; returns a new escaped string
+ * - Returns a new escaped string
  * - Replaces `~` (tilde) with `~0` and `/` (forward slash) with `~1`
  * - Returns the input unchanged if it contains no special characters
  * - Empty strings are valid and returned unchanged
@@ -91,17 +91,17 @@ export function escapeToken(token: string): string {
 }
 
 /**
- * Unescapes a JSON Pointer reference token according to RFC 6901 by decoding escaped characters to recover the original token value.
+ * Decodes a JSON Pointer reference token according to RFC 6901 escaping rules.
  *
  * **When to use**
  *
- * - Parsing JSON Pointers to extract the original token values from escaped segments
+ * Use to parse 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
  *
  * **Details**
  *
- * - Does not mutate the input string; returns a new unescaped string
+ * - Returns a new unescaped string
  * - Replaces `~1` with `/` (forward slash) and `~0` with `~` (tilde)
  * - Returns the input unchanged if it contains no escaped sequences
  * - Empty strings are valid and returned unchanged

package/src/JsonSchema.ts

@@ -92,6 +92,10 @@ import * as Rec from "./Record.ts"
 /**
  * A plain object representing a single JSON Schema node.
  *
+ * **When to use**
+ *
+ * Use to represent an arbitrary JSON Schema object regardless of dialect.
+ *
  * **Details**
  *
  * This is an open record type (`[x: string]: unknown`) so it can hold any JSON
@@ -107,12 +111,20 @@ export interface JsonSchema {
 /**
  * The set of JSON Schema dialects supported by this module.
  *
+ * **When to use**
+ *
+ * Use as the dialect marker for `JsonSchema` documents when parsing,
+ * converting, or emitting schemas across the supported formats.
+ *
  * **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.
  *
+ * @see {@link Document} for a single root schema tagged with a dialect
+ * @see {@link MultiDocument} for multiple root schemas tagged with a dialect
+ *
  * @category models
  * @since 4.0.0
  */
@@ -121,6 +133,10 @@ export type Dialect = "draft-07" | "draft-2020-12" | "openapi-3.1" | "openapi-3.
 /**
  * The JSON Schema primitive type names.
  *
+ * **When to use**
+ *
+ * Use to restrict a JSON Schema `type` keyword to the supported primitive names.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -129,6 +145,20 @@ export type Type = "string" | "number" | "boolean" | "array" | "object" | "null"
 /**
  * A record of named JSON Schema definitions, keyed by definition name.
  *
+ * **When to use**
+ *
+ * Use as the shared lookup table for named JSON Schema nodes that are
+ * referenced from JSON Schema documents.
+ *
+ * **Details**
+ *
+ * The map is dialect-neutral. Conversion APIs emit it as `$defs`,
+ * `definitions`, or `components.schemas` depending on the target format.
+ *
+ * @see {@link Document} for a single root schema with definitions
+ * @see {@link MultiDocument} for multiple root schemas sharing definitions
+ * @see {@link resolve$ref} for resolving a `$ref` against definitions
+ *
  * @category models
  * @since 4.0.0
  */
@@ -140,7 +170,7 @@ export interface Definitions extends Record<string, JsonSchema> {}
  *
  * **When to use**
  *
- * Use `Document` when you need to carry a root schema together with its shared
+ * Use when you need to carry a root schema together with its shared
  * definitions, or when converting between dialects with the `from*` and `to*`
  * functions.
  *
@@ -186,7 +216,7 @@ export interface Document<D extends Dialect> {
  *
  * **When to use**
  *
- * Use `MultiDocument` when generating several schemas, such as a request body
+ * Use when generating several schemas, such as a request body
  * and a response body, that reference the same set of definitions.
  *
  * **Details**
@@ -205,7 +235,19 @@ export interface MultiDocument<D extends Dialect> {
 }
 
 /**
- * The `$schema` meta-schema URI for JSON Schema Draft-07.
+ * Represents the `$schema` meta-schema URI for JSON Schema Draft-07.
+ *
+ * **When to use**
+ *
+ * Use when constructing a Draft-07 JSON Schema document and you need a stable
+ * value for the root `$schema` field.
+ *
+ * **Details**
+ *
+ * The exported value is the literal string
+ * `http://json-schema.org/draft-07/schema`.
+ *
+ * @see {@link META_SCHEMA_URI_DRAFT_2020_12} for the Draft 2020-12 `$schema` URI
  *
  * @category constants
  * @since 4.0.0
@@ -213,7 +255,19 @@ export interface MultiDocument<D extends Dialect> {
 export const META_SCHEMA_URI_DRAFT_07 = "http://json-schema.org/draft-07/schema"
 
 /**
- * The `$schema` meta-schema URI for JSON Schema Draft 2020-12.
+ * Represents the `$schema` meta-schema URI for JSON Schema Draft 2020-12.
+ *
+ * **When to use**
+ *
+ * Use to populate the `$schema` field when emitting a JSON Schema document that
+ * should declare JSON Schema Draft 2020-12.
+ *
+ * **Details**
+ *
+ * The exported value is the literal string
+ * `https://json-schema.org/draft/2020-12/schema`.
+ *
+ * @see {@link META_SCHEMA_URI_DRAFT_07} for the Draft-07 `$schema` URI
  *
  * @category constants
  * @since 4.0.0
@@ -229,7 +283,7 @@ const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/
  *
  * **When to use**
  *
- * Use this when you have a JSON Schema that follows Draft-07 conventions and
+ * Use when you have a JSON Schema that follows Draft-07 conventions and
  * need the canonical Draft-2020-12 document representation.
  *
  * **Details**
@@ -237,8 +291,7 @@ const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/
  * 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`.
+ * `definitions` into the `definitions` field.
  *
  * **Gotchas**
  *
@@ -383,13 +436,12 @@ export function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12"> {
  *
  * **When to use**
  *
- * Use this when you already have a schema in Draft-2020-12 format.
+ * Use 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.
+ * This separates `$defs` from the root schema into the `definitions` field.
+ * Unlike {@link fromSchemaDraft07}, this performs no keyword rewriting.
  *
  * **Example** (Parsing a Draft-2020-12 schema)
  *
@@ -426,13 +478,12 @@ export function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12"
  *
  * **When to use**
  *
- * Use this when consuming schemas from an OpenAPI 3.1 specification.
+ * Use 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`.
+ * to {@link fromSchemaDraft2020_12}.
  *
  * **Example** (Parsing an OpenAPI 3.1 schema)
  *
@@ -466,15 +517,14 @@ export function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12">
  *
  * **When to use**
  *
- * Use this when consuming schemas from an OpenAPI 3.0 specification.
+ * Use 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`.
+ * {@link fromSchemaDraft07}.
  *
  * **Example** (Parsing an OpenAPI 3.0 nullable schema)
  *
@@ -506,15 +556,14 @@ export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-1
  *
  * **When to use**
  *
- * Use this when you need to output a schema in Draft-07 format.
+ * Use 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`.
+ * and all definitions.
  *
  * **Gotchas**
  *
@@ -657,7 +706,7 @@ function toSchemaDraft07(schema: JsonSchema): JsonSchema {
  *
  * **When to use**
  *
- * Use this when generating an OpenAPI 3.1 specification from internal schemas.
+ * Use when generating an OpenAPI 3.1 specification from internal schemas.
  *
  * **Details**
  *
@@ -665,8 +714,7 @@ function toSchemaDraft07(schema: JsonSchema): JsonSchema {
  * 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`.
+ * definitions in the multi-document.
  *
  * **Example** (Converting to OpenAPI 3.1)
  *
@@ -882,14 +930,13 @@ function widen_type(node: Record<string, unknown>): Record<string, unknown> {
  *
  * **When to use**
  *
- * Use this when you need to dereference a `$ref` pointer to get the actual
+ * Use 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.
+ * `"#/$defs/User"`. It returns `undefined` if the definition is not found.
  *
  * **Gotchas**
  *
@@ -928,20 +975,17 @@ export function resolve$ref($ref: string, definitions: Definitions): JsonSchema
 }
 
 /**
- * If the root schema of a document is a `$ref`, resolves it against the
- * document's definitions and returns a new document with the inlined
- * schema. Returns the original document unchanged if the root schema is
- * not a `$ref` or if the referenced definition is not found.
+ * Resolves a document whose root schema is a top-level `$ref`.
  *
  * **When to use**
  *
- * Use this to dereference a top-level `$ref` before inspecting the root
+ * Use 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.
+ * This returns the same object if no change is needed, or a shallow copy with
+ * the resolved schema.
  *
  * **Example** (Resolving a top-level $ref)
  *