effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/JsonPatch.ts

@@ -33,7 +33,7 @@
  * **Example** (Computing and applying a patch)
  *
  * ```ts
- * import * as JsonPatch from "effect/JsonPatch"
+ * import { JsonPatch } from "effect"
  *
  * const oldValue = { name: "Alice", age: 30 }
  * const newValue = { name: "Alice", age: 31, city: "NYC" }
@@ -78,7 +78,7 @@ import type * as Schema from "./Schema.ts"
  * **Example** (All operation types)
  *
  * ```ts
- * import * as JsonPatch from "effect/JsonPatch"
+ * import { JsonPatch } from "effect"
  *
  * const addOp: JsonPatch.JsonPatchOperation = {
  *   op: "add",
@@ -104,7 +104,7 @@ import type * as Schema from "./Schema.ts"
  * - {@link get} - Computes operations automatically from value differences
  * - {@link apply} - Applies operations to transform documents
  *
- * @category Model
+ * @category models
  * @since 4.0.0
  */
 export type JsonPatchOperation =
@@ -155,7 +155,7 @@ export type JsonPatchOperation =
  * **Example** (Multi-operation patch)
  *
  * ```ts
- * import * as JsonPatch from "effect/JsonPatch"
+ * import { JsonPatch } from "effect"
  *
  * const patch: JsonPatch.JsonPatch = [
  *   { op: "add", path: "/items/-", value: "apple" },
@@ -173,22 +173,23 @@ export type JsonPatchOperation =
  * - {@link get} - Generates patches from value differences
  * - {@link apply} - Executes patches to transform documents
  *
- * @category Model
+ * @category models
  * @since 4.0.0
  */
 export type JsonPatch = ReadonlyArray<JsonPatchOperation>
 
 /**
- * Compute a patch that transforms `oldValue` into `newValue`.
+ * Computes a patch that transforms `oldValue` into `newValue`.
  *
- * Generates a structural diff between two JSON values, producing a patch that when applied to `oldValue` yields `newValue`.
+ * Generates a structural diff between two JSON values, producing a patch that
+ * yields `newValue` when applied to `oldValue`.
  *
  * ## When to use this
  *
  * - Computing differences between JSON documents
  * - Detecting changes in data structures
  * - Generating patches for synchronization or version control
- * - Creating minimal update operations from before/after states
+ * - Creating deterministic update operations from before/after states
  *
  * ## Behavior
  *
@@ -204,7 +205,7 @@ export type JsonPatch = ReadonlyArray<JsonPatchOperation>
  * **Example** (Computing object diff)
  *
  * ```ts
- * import * as JsonPatch from "effect/JsonPatch"
+ * import { JsonPatch } from "effect"
  *
  * const oldValue = { users: [{ id: 1, name: "Alice" }], count: 1 }
  * const newValue = { users: [{ id: 1, name: "Bob" }, { id: 2, name: "Charlie" }], count: 2 }
@@ -222,6 +223,7 @@ export type JsonPatch = ReadonlyArray<JsonPatchOperation>
  * - {@link apply} - Applies the generated patch to a document
  * - {@link JsonPatchOperation} - The operation types in the patch
  *
+ * @category transforming
  * @since 4.0.0
  */
 export function get(oldValue: Schema.Json, newValue: Schema.Json): JsonPatch {
@@ -312,7 +314,7 @@ export function get(oldValue: Schema.Json, newValue: Schema.Json): JsonPatch {
  * **Example** (Applying a patch)
  *
  * ```ts
- * import * as JsonPatch from "effect/JsonPatch"
+ * import { JsonPatch } from "effect"
  *
  * const document = { items: [1, 2, 3], total: 6 }
  * const patch: JsonPatch.JsonPatch = [
@@ -329,6 +331,7 @@ export function get(oldValue: Schema.Json, newValue: Schema.Json): JsonPatch {
  * - {@link get} - Generates patches from value differences
  * - {@link JsonPatchOperation} - The operation types being applied
  *
+ * @category transforming
  * @since 4.0.0
  */
 export function apply(patch: JsonPatch, oldValue: Schema.Json): Schema.Json {

package/src/JsonPointer.ts

@@ -32,15 +32,15 @@
  * **Example** (Building and parsing a JSON Pointer)
  *
  * ```ts
- * import { escapeToken, unescapeToken } from "effect/JsonPointer"
+ * import { JsonPointer } from "effect"
  *
  * // Build a JSON Pointer from path segments
  * const segments = ["users", "name/alias", "value"]
- * const pointer = "/" + segments.map(escapeToken).join("/")
+ * const pointer = "/" + segments.map(JsonPointer.escapeToken).join("/")
  * // "/users/name~1alias/value"
  *
  * // Parse a JSON Pointer back to segments
- * const tokens = pointer.split("/").slice(1).map(unescapeToken)
+ * const tokens = pointer.split("/").slice(1).map(JsonPointer.unescapeToken)
  * // ["users", "name/alias", "value"]
  * ```
  *
@@ -74,17 +74,18 @@
  * **Example** (Escaping special characters)
  *
  * ```ts
- * import { escapeToken } from "effect/JsonPointer"
+ * import { JsonPointer } from "effect"
  *
- * escapeToken("a/b") // "a~1b"
- * escapeToken("c~d") // "c~0d"
- * escapeToken("path/to~key") // "path~1to~0key"
+ * JsonPointer.escapeToken("a/b") // "a~1b"
+ * JsonPointer.escapeToken("c~d") // "c~0d"
+ * JsonPointer.escapeToken("path/to~key") // "path~1to~0key"
  * ```
  *
  * ## See also
  *
  * - {@link unescapeToken} - The inverse operation for decoding escaped tokens
  *
+ * @category encoding
  * @since 4.0.0
  */
 export function escapeToken(token: string): string {
@@ -113,17 +114,18 @@ export function escapeToken(token: string): string {
  * **Example** (Unescaping special characters)
  *
  * ```ts
- * import { unescapeToken } from "effect/JsonPointer"
+ * import { JsonPointer } from "effect"
  *
- * unescapeToken("a~1b") // "a/b"
- * unescapeToken("c~0d") // "c~d"
- * unescapeToken("path~1to~0key") // "path/to~key"
+ * JsonPointer.unescapeToken("a~1b") // "a/b"
+ * JsonPointer.unescapeToken("c~0d") // "c~d"
+ * JsonPointer.unescapeToken("path~1to~0key") // "path/to~key"
  * ```
  *
  * ## See also
  *
  * - {@link escapeToken} - The inverse operation for encoding tokens
  *
+ * @category decoding
  * @since 4.0.0
  */
 export function unescapeToken(token: string): string {

package/src/JsonSchema.ts

@@ -96,6 +96,7 @@ import * as Rec from "./Record.ts"
  * JSON Schema keyword. Most functions in this module accept or return this
  * type.
  *
+ * @category models
  * @since 4.0.0
  */
 export interface JsonSchema {
@@ -110,6 +111,7 @@ export interface JsonSchema {
  * - `"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)
  *
+ * @category models
  * @since 4.0.0
  */
 export type Dialect = "draft-07" | "draft-2020-12" | "openapi-3.1" | "openapi-3.0"
@@ -117,6 +119,7 @@ export type Dialect = "draft-07" | "draft-2020-12" | "openapi-3.1" | "openapi-3.
 /**
  * The JSON Schema primitive type names.
  *
+ * @category models
  * @since 4.0.0
  */
 export type Type = "string" | "number" | "boolean" | "array" | "object" | "null" | "integer"
@@ -124,6 +127,7 @@ export type Type = "string" | "number" | "boolean" | "array" | "object" | "null"
 /**
  * A record of named JSON Schema definitions, keyed by definition name.
  *
+ * @category models
  * @since 4.0.0
  */
 export interface Definitions extends Record<string, JsonSchema> {}
@@ -162,6 +166,7 @@ export interface Definitions extends Record<string, JsonSchema> {}
  *
  * @see {@link MultiDocument}
  * @see {@link fromSchemaDraft2020_12}
+ * @category models
  *
  * @since 4.0.0
  */
@@ -181,6 +186,7 @@ export interface Document<D extends Dialect> {
  *
  * @see {@link Document}
  * @see {@link toMultiDocumentOpenApi3_1}
+ * @category models
  *
  * @since 4.0.0
  */
@@ -193,6 +199,7 @@ export interface MultiDocument<D extends Dialect> {
 /**
  * The `$schema` meta-schema URI for JSON Schema Draft-07.
  *
+ * @category constants
  * @since 4.0.0
  */
 export const META_SCHEMA_URI_DRAFT_07 = "http://json-schema.org/draft-07/schema"
@@ -200,6 +207,7 @@ 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.
  *
+ * @category constants
  * @since 4.0.0
  */
 export const META_SCHEMA_URI_DRAFT_2020_12 = "https://json-schema.org/draft/2020-12/schema"
@@ -242,6 +250,7 @@ const RE_COMPONENTS_SCHEMAS = /^#\/components\/schemas(?=\/|$)/
  * @see {@link fromSchemaDraft2020_12}
  * @see {@link fromSchemaOpenApi3_0}
  * @see {@link toDocumentDraft07}
+ * @category decoding
  *
  * @since 4.0.0
  */
@@ -379,6 +388,7 @@ export function fromSchemaDraft07(js: JsonSchema): Document<"draft-2020-12"> {
  *
  * @see {@link fromSchemaDraft07}
  * @see {@link fromSchemaOpenApi3_1}
+ * @category decoding
  *
  * @since 4.0.0
  */
@@ -418,6 +428,7 @@ export function fromSchemaDraft2020_12(js: JsonSchema): Document<"draft-2020-12"
  *
  * @see {@link fromSchemaOpenApi3_0}
  * @see {@link toMultiDocumentOpenApi3_1}
+ * @category decoding
  *
  * @since 4.0.0
  */
@@ -453,6 +464,7 @@ export function fromSchemaOpenApi3_1(js: JsonSchema): Document<"draft-2020-12">
  *
  * @see {@link fromSchemaOpenApi3_1}
  * @see {@link fromSchemaDraft07}
+ * @category decoding
  *
  * @since 4.0.0
  */
@@ -491,6 +503,7 @@ export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-1
  *
  * @see {@link fromSchemaDraft07}
  * @see {@link toMultiDocumentOpenApi3_1}
+ * @category encoding
  *
  * @since 4.0.0
  */
@@ -635,6 +648,7 @@ function toSchemaDraft07(schema: JsonSchema): JsonSchema {
  *
  * @see {@link toDocumentDraft07}
  * @see {@link MultiDocument}
+ * @category encoding
  *
  * @since 4.0.0
  */
@@ -852,6 +866,7 @@ function widen_type(node: Record<string, unknown>): Record<string, unknown> {
  *
  * @see {@link resolveTopLevel$ref}
  * @see {@link Definitions}
+ * @category getters
  *
  * @since 4.0.0
  */
@@ -896,6 +911,7 @@ export function resolve$ref($ref: string, definitions: Definitions): JsonSchema
  *
  * @see {@link resolve$ref}
  * @see {@link Document}
+ * @category transforming
  *
  * @since 4.0.0
  */

package/src/Latch.ts

@@ -1,13 +1,52 @@
 /**
- * @since 3.8.0
+ * The `Latch` module provides a reusable synchronization primitive for
+ * coordinating fibers. A `Latch` is either open or closed: when it is closed,
+ * fibers that use {@link await} or {@link whenOpen} suspend until the latch is
+ * opened or the current waiters are released.
+ *
+ * **Mental model**
+ *
+ * - An open latch lets current and future waiters continue immediately
+ * - A closed latch causes `await` and `whenOpen` to suspend
+ * - {@link open} permanently opens the latch until it is closed again
+ * - {@link release} wakes only the fibers currently waiting and leaves the
+ *   latch closed for future waiters
+ * - {@link close} resets the latch so later waiters suspend again
+ *
+ * **Common tasks**
+ *
+ * - Create a latch inside `Effect`: {@link make}
+ * - Create a latch synchronously: {@link makeUnsafe}
+ * - Wait for a signal before continuing: {@link await}
+ * - Guard an effect so it runs only after the latch is open: {@link whenOpen}
+ * - Let all current and future waiters proceed: {@link open}
+ * - Let only the current waiters proceed: {@link release}
+ * - Re-enable waiting after opening: {@link close}
+ *
+ * **Gotchas**
+ *
+ * - `release` is not the same as `open`; new waiters still suspend after the
+ *   current waiters are released
+ * - `open` and `close` report whether they changed the latch state
+ * - Prefer the effectful APIs unless synchronous allocation or mutation is
+ *   required
+ *
+ * @since 4.0.0
  */
 import type * as Effect from "./Effect.ts"
 import * as internal from "./internal/effect.ts"
 
 /**
- * @category models
- * @since 3.8.0
- * @example
+ * A reusable coordination primitive that lets fibers wait until they are
+ * released by the latch.
+ *
+ * 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
+ * again.
+ *
+ * **Example** (Coordinating fibers with a latch)
+ *
  * ```ts
  * import { Effect, Latch } from "effect"
  *
@@ -21,6 +60,9 @@ import * as internal from "./internal/effect.ts"
  *   return "Latch was opened!"
  * })
  * ```
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface Latch {
   /** open the latch, releasing all fibers waiting on it */
@@ -40,15 +82,13 @@ export interface Latch {
 }
 
 /**
- * Creates a new Latch unsafely.
- *
- * **Previously Known As**
+ * Creates a `Latch` synchronously, outside of `Effect`.
  *
- * This API replaces the following from Effect 3.x:
+ * The latch starts closed by default; pass `true` to create it open. Use this
+ * only when synchronous allocation is required, otherwise prefer `make`.
  *
- * - `Effect.makeLatchUnsafe`
+ * **Example** (Creating a latch unsafely)
  *
- * @example
  * ```ts
  * import { Effect, Latch } from "effect"
  *
@@ -70,20 +110,17 @@ export interface Latch {
  * ```
  *
  * @category constructors
- * @since 3.8.0
+ * @since 4.0.0
  */
 export const makeUnsafe: (open?: boolean | undefined) => Latch = internal.makeLatchUnsafe
 
 /**
- * Creates a new Latch.
- *
- * **Previously Known As**
+ * Creates a `Latch` inside `Effect`.
  *
- * This API replaces the following from Effect 3.x:
+ * The latch starts closed by default; pass `true` to create it open.
  *
- * - `Effect.makeLatch`
+ * **Example** (Creating a latch)
  *
- * @example
  * ```ts
  * import { Effect, Latch } from "effect"
  *
@@ -107,12 +144,15 @@ export const makeUnsafe: (open?: boolean | undefined) => Latch = internal.makeLa
  * ```
  *
  * @category constructors
- * @since 3.8.0
+ * @since 4.0.0
  */
 export const make: (open?: boolean | undefined) => Effect.Effect<Latch> = internal.makeLatch
 
 /**
- * Opens the latch, releasing all fibers waiting on it.
+ * Opens the latch and releases fibers waiting on it.
+ *
+ * The returned effect succeeds with `true` when this call changed the latch
+ * from closed to open, or `false` if it was already open.
  *
  * @category combinators
  * @since 4.0.0
@@ -120,7 +160,11 @@ export const make: (open?: boolean | undefined) => Effect.Effect<Latch> = intern
 export const open = (self: Latch): Effect.Effect<boolean> => self.open
 
 /**
- * Opens the latch, releasing all fibers waiting on it.
+ * Synchronously opens the latch and releases fibers waiting on it.
+ *
+ * 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`.
  *
  * @category unsafe
  * @since 4.0.0
@@ -128,7 +172,11 @@ export const open = (self: Latch): Effect.Effect<boolean> => self.open
 export const openUnsafe = (self: Latch): boolean => self.openUnsafe()
 
 /**
- * Releases all fibers waiting on the latch, without opening it.
+ * Releases the fibers currently waiting on a closed latch without opening it.
+ *
+ * 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.
  *
  * @category combinators
  * @since 4.0.0
@@ -148,7 +196,10 @@ export {
 }
 
 /**
- * Closes the latch.
+ * Closes the latch so future `await` and `whenOpen` calls suspend.
+ *
+ * The returned effect succeeds with `true` when this call changed the latch
+ * from open to closed, or `false` if it was already closed.
  *
  * @category combinators
  * @since 4.0.0
@@ -156,7 +207,12 @@ export {
 export const close = (self: Latch): Effect.Effect<boolean> => self.close
 
 /**
- * Closes the latch.
+ * Synchronously closes the latch so future `await` and `whenOpen` calls
+ * suspend.
+ *
+ * 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`.
  *
  * @category unsafe
  * @since 4.0.0
@@ -164,21 +220,36 @@ export const close = (self: Latch): Effect.Effect<boolean> => self.close
 export const closeUnsafe = (self: Latch): boolean => self.closeUnsafe()
 
 /**
- * Runs the given effect only when the latch is open.
+ * Waits on the latch, then runs the provided effect.
+ *
+ * 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
+ * preserved.
  *
  * @category combinators
  * @since 4.0.0
  */
 export const whenOpen: {
   /**
-   * Runs the given effect only when the latch is open.
+   * Waits on the latch, then runs the provided effect.
+   *
+   * 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
+   * preserved.
    *
    * @category combinators
    * @since 4.0.0
    */
   (self: Latch): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * Runs the given effect only when the latch is open.
+   * Waits on the latch, then runs the provided effect.
+   *
+   * 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
+   * preserved.
    *
    * @category combinators
    * @since 4.0.0