effect 4.0.0-beta.67 → 4.0.0-beta.69

package/src/Inspectable.ts

@@ -11,8 +11,7 @@
  * **Example** (Creating inspectable values)
  *
  * ```ts
- * import { Inspectable } from "effect"
- * import { format } from "effect/Formatter"
+ * import { Formatter, Inspectable } from "effect"
  *
  * class User extends Inspectable.Class {
  *   constructor(
@@ -33,7 +32,7 @@
  *
  * const user = new User("Alice", "alice@example.com")
  * console.log(user.toString()) // Pretty printed JSON
- * console.log(format(user)) // Same as toString()
+ * console.log(Formatter.format(user)) // Same as toString()
  * ```
  *
  * @since 2.0.0
@@ -108,8 +107,7 @@ export type NodeInspectSymbol = typeof NodeInspectSymbol
  * **Example** (Implementing inspectable objects)
  *
  * ```ts
- * import { Inspectable } from "effect"
- * import { format } from "effect/Formatter"
+ * import { Formatter, Inspectable } from "effect"
  *
  * class Result implements Inspectable.Inspectable {
  *   constructor(
@@ -118,7 +116,7 @@ export type NodeInspectSymbol = typeof NodeInspectSymbol
  *   ) {}
  *
  *   toString(): string {
- *     return format(this.toJSON())
+ *     return Formatter.format(this.toJSON())
  *   }
  *
  *   toJSON() {
@@ -152,7 +150,8 @@ export interface Inspectable {
  * For objects that don't have a `toJSON` method, it applies redaction to
  * protect sensitive information.
  *
- * @since 2.0.0
+ * @category converting
+ * @since 4.0.0
  */
 export const toJson = (input: unknown): unknown => {
   try {
@@ -178,6 +177,7 @@ export const toJson = (input: unknown): unknown => {
  * provided whitespace setting when possible, and values that cannot be
  * formatted are converted with `String`.
  *
+ * @category converting
  * @since 2.0.0
  */
 export const toStringUnknown = (u: unknown, whitespace: number | string | undefined = 2): string => {
@@ -218,6 +218,7 @@ export const toStringUnknown = (u: unknown, whitespace: number | string | undefi
  * MyClass.prototype.constructor = MyClass
  * ```
  *
+ * @category models
  * @since 2.0.0
  */
 export const BaseProto: Inspectable = {

package/src/Iterable.ts

@@ -50,9 +50,6 @@ import type { NoInfer } from "./Types.ts"
  * with each index starting from 0. If no length is specified, the iterable will
  * be infinite. This is useful for generating sequences, patterns, or any indexed data.
  *
- * @param f - Function that receives the index and returns the element
- * @param options - Configuration object with optional length
- *
  * **Example** (Generating values by index)
  *
  * ```ts
@@ -104,10 +101,10 @@ export const makeBy = <A>(f: (i: number) => A, options?: {
  * **Example** (Creating a range)
  *
  * ```ts
- * import { range } from "effect/Iterable"
+ * import { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Array.from(range(1, 3)), [1, 2, 3])
+ * assert.deepStrictEqual(Array.from(Iterable.range(1, 3)), [1, 2, 3])
  * ```
  *
  * @category constructors
@@ -130,10 +127,10 @@ export const range = (start: number, end?: number): Iterable<number> => {
  * **Example** (Repeating a value)
  *
  * ```ts
- * import { replicate } from "effect/Iterable"
+ * import { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Array.from(replicate("a", 3)), ["a", "a", "a"])
+ * assert.deepStrictEqual(Array.from(Iterable.replicate("a", 3)), ["a", "a", "a"])
  * ```
  *
  * @category constructors
@@ -148,10 +145,10 @@ export const replicate: {
    * **Example** (Repeating a value)
    *
    * ```ts
-   * import { replicate } from "effect/Iterable"
+   * import { Iterable } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(Array.from(replicate("a", 3)), ["a", "a", "a"])
+   * assert.deepStrictEqual(Array.from(Iterable.replicate("a", 3)), ["a", "a", "a"])
    * ```
    *
    * @category constructors
@@ -166,10 +163,10 @@ export const replicate: {
    * **Example** (Repeating a value)
    *
    * ```ts
-   * import { replicate } from "effect/Iterable"
+   * import { Iterable } from "effect"
    * import * as assert from "node:assert"
    *
-   * assert.deepStrictEqual(Array.from(replicate("a", 3)), ["a", "a", "a"])
+   * assert.deepStrictEqual(Array.from(Iterable.replicate("a", 3)), ["a", "a", "a"])
    * ```
    *
    * @category constructors
@@ -227,17 +224,17 @@ export const forever = <A>(self: Iterable<A>): Iterable<A> => repeat(self, Infin
  * **Example** (Converting a record to entries)
  *
  * ```ts
- * import { fromRecord } from "effect/Iterable"
+ * import { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
  * const x = { a: 1, b: 2, c: 3 }
- * assert.deepStrictEqual(Array.from(fromRecord(x)), [["a", 1], ["b", 2], [
+ * assert.deepStrictEqual(Array.from(Iterable.fromRecord(x)), [["a", 1], ["b", 2], [
  *   "c",
  *   3
  * ]])
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export const fromRecord = <K extends string, A>(self: Readonly<Record<K, A>>): Iterable<[K, A]> => ({
@@ -679,11 +676,11 @@ export const scan: {
  * **Example** (Checking for emptiness)
  *
  * ```ts
- * import { isEmpty } from "effect/Iterable"
+ * import { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isEmpty([]), true)
- * assert.deepStrictEqual(isEmpty([1, 2, 3]), false)
+ * assert.deepStrictEqual(Iterable.isEmpty([]), true)
+ * assert.deepStrictEqual(Iterable.isEmpty([1, 2, 3]), false)
  * ```
  *
  * @category guards
@@ -735,8 +732,7 @@ export const size = <A>(self: Iterable<A>): number => {
  * **Example** (Getting the first element)
  *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Option from "effect/Option"
+ * import { Iterable, Option } from "effect"
  *
  * const numbers = [1, 2, 3]
  * console.log(Iterable.head(numbers)) // Option.some(1)
@@ -787,7 +783,7 @@ export const head = <A>(self: Iterable<A>): Option<A> => {
  * ```
  *
  * @category getters
- * @since 3.3.0
+ * @since 4.0.0
  */
 export const headUnsafe = <A>(self: Iterable<A>): A => {
   const iterator = self[Symbol.iterator]()
@@ -1218,8 +1214,7 @@ export const drop: {
  * **Example** (Finding the first match)
  *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Option from "effect/Option"
+ * import { Iterable, Option } from "effect"
  *
  * const numbers = [1, 3, 4, 6, 8]
  * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1260,8 +1255,7 @@ export const findFirst: {
    * **Example** (Finding the first match)
    *
    * ```ts
-   * import { Iterable } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Iterable, Option } from "effect"
    *
    * const numbers = [1, 3, 4, 6, 8]
    * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1302,8 +1296,7 @@ export const findFirst: {
    * **Example** (Finding the first match)
    *
    * ```ts
-   * import { Iterable } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Iterable, Option } from "effect"
    *
    * const numbers = [1, 3, 4, 6, 8]
    * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1344,8 +1337,7 @@ export const findFirst: {
    * **Example** (Finding the first match)
    *
    * ```ts
-   * import { Iterable } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Iterable, Option } from "effect"
    *
    * const numbers = [1, 3, 4, 6, 8]
    * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1386,8 +1378,7 @@ export const findFirst: {
    * **Example** (Finding the first match)
    *
    * ```ts
-   * import { Iterable } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Iterable, Option } from "effect"
    *
    * const numbers = [1, 3, 4, 6, 8]
    * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1428,8 +1419,7 @@ export const findFirst: {
    * **Example** (Finding the first match)
    *
    * ```ts
-   * import { Iterable } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Iterable, Option } from "effect"
    *
    * const numbers = [1, 3, 4, 6, 8]
    * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1470,8 +1460,7 @@ export const findFirst: {
    * **Example** (Finding the first match)
    *
    * ```ts
-   * import { Iterable } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Iterable, Option } from "effect"
    *
    * const numbers = [1, 3, 4, 6, 8]
    * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -2898,8 +2887,6 @@ export const empty = <A = never>(): Iterable<A> => constEmpty
  * This is useful for wrapping a single value in an iterable context,
  * allowing it to be used with other iterable operations.
  *
- * @param a - The single element to wrap in an iterable
- *
  * **Example** (Wrapping a single value)
  *
  * ```ts
@@ -2937,9 +2924,6 @@ export const of = <A>(a: A): Iterable<A> => [a]
  * with the transformed values. The operation is lazy - elements are only
  * transformed when the iterable is consumed.
  *
- * @param self - The source iterable to transform
- * @param f - Function that transforms each element (receives value and index)
- *
  * **Example** (Mapping elements)
  *
  * ```ts
@@ -2974,9 +2958,6 @@ export const map: {
    * with the transformed values. The operation is lazy - elements are only
    * transformed when the iterable is consumed.
    *
-   * @param self - The source iterable to transform
-   * @param f - Function that transforms each element (receives value and index)
-   *
    * **Example** (Mapping elements)
    *
    * ```ts
@@ -3011,9 +2992,6 @@ export const map: {
    * with the transformed values. The operation is lazy - elements are only
    * transformed when the iterable is consumed.
    *
-   * @param self - The source iterable to transform
-   * @param f - Function that transforms each element (receives value and index)
-   *
    * **Example** (Mapping elements)
    *
    * ```ts
@@ -3243,8 +3221,7 @@ export const flatten = <A>(self: Iterable<Iterable<A>>): Iterable<A> => ({
  * **Example** (Filtering and transforming Result values)
  *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Result from "effect/Result"
+ * import { Iterable, Result } from "effect"
  *
  * // Parse strings to numbers, keeping only valid ones
  * const strings = ["1", "2", "invalid", "4", "not-a-number"]
@@ -3290,8 +3267,7 @@ export const filterMap: {
    * **Example** (Filtering and transforming Result values)
    *
    * ```ts
-   * import { Iterable } from "effect"
-   * import * as Result from "effect/Result"
+   * import { Iterable, Result } from "effect"
    *
    * // Parse strings to numbers, keeping only valid ones
    * const strings = ["1", "2", "invalid", "4", "not-a-number"]
@@ -3337,8 +3313,7 @@ export const filterMap: {
    * **Example** (Filtering and transforming Result values)
    *
    * ```ts
-   * import { Iterable } from "effect"
-   * import * as Result from "effect/Result"
+   * import { Iterable, Result } from "effect"
    *
    * // Parse strings to numbers, keeping only valid ones
    * const strings = ["1", "2", "invalid", "4", "not-a-number"]
@@ -3404,8 +3379,7 @@ export const filterMap: {
  * **Example** (Filtering and transforming until failure)
  *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Result from "effect/Result"
+ * import { Iterable, Result } from "effect"
  *
  * // Parse numbers until we hit an invalid one
  * const strings = ["1", "2", "3", "invalid", "4", "5"]
@@ -3442,8 +3416,7 @@ export const filterMapWhile: {
    * **Example** (Filtering and transforming until failure)
    *
    * ```ts
-   * import { Iterable } from "effect"
-   * import * as Result from "effect/Result"
+   * import { Iterable, Result } from "effect"
    *
    * // Parse numbers until we hit an invalid one
    * const strings = ["1", "2", "3", "invalid", "4", "5"]
@@ -3480,8 +3453,7 @@ export const filterMapWhile: {
    * **Example** (Filtering and transforming until failure)
    *
    * ```ts
-   * import { Iterable } from "effect"
-   * import * as Result from "effect/Result"
+   * import { Iterable, Result } from "effect"
    *
    * // Parse numbers until we hit an invalid one
    * const strings = ["1", "2", "3", "invalid", "4", "5"]
@@ -3538,8 +3510,7 @@ export const filterMapWhile: {
  * **Example** (Extracting Some values)
  *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Option from "effect/Option"
+ * import { Iterable, Option } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -3580,8 +3551,7 @@ export const getSomes = <A>(self: Iterable<Option<A>>): Iterable<A> => {
  * **Example** (Extracting failures)
  *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Result from "effect/Result"
+ * import { Iterable, Result } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -3597,7 +3567,7 @@ export const getSomes = <A>(self: Iterable<Option<A>>): Iterable<A> => {
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const getFailures = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<L> => {
   return {
@@ -3626,8 +3596,7 @@ export const getFailures = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<L> =
  * **Example** (Extracting successes)
  *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Result from "effect/Result"
+ * import { Iterable, Result } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -3643,7 +3612,7 @@ export const getFailures = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<L> =
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const getSuccesses = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<R0> => {
   return {
@@ -3672,9 +3641,6 @@ export const getSuccesses = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<R0>
  * the predicate function returns true. Like map, this operation is lazy and
  * elements are only tested when the iterable is consumed.
  *
- * @param self - The source iterable to filter
- * @param predicate - Function that tests each element (receives value and index)
- *
  * **Example** (Filtering elements)
  *
  * ```ts
@@ -3717,9 +3683,6 @@ export const filter: {
    * the predicate function returns true. Like map, this operation is lazy and
    * elements are only tested when the iterable is consumed.
    *
-   * @param self - The source iterable to filter
-   * @param predicate - Function that tests each element (receives value and index)
-   *
    * **Example** (Filtering elements)
    *
    * ```ts
@@ -3762,9 +3725,6 @@ export const filter: {
    * the predicate function returns true. Like map, this operation is lazy and
    * elements are only tested when the iterable is consumed.
    *
-   * @param self - The source iterable to filter
-   * @param predicate - Function that tests each element (receives value and index)
-   *
    * **Example** (Filtering elements)
    *
    * ```ts
@@ -3807,9 +3767,6 @@ export const filter: {
    * the predicate function returns true. Like map, this operation is lazy and
    * elements are only tested when the iterable is consumed.
    *
-   * @param self - The source iterable to filter
-   * @param predicate - Function that tests each element (receives value and index)
-   *
    * **Example** (Filtering elements)
    *
    * ```ts
@@ -3852,9 +3809,6 @@ export const filter: {
    * the predicate function returns true. Like map, this operation is lazy and
    * elements are only tested when the iterable is consumed.
    *
-   * @param self - The source iterable to filter
-   * @param predicate - Function that tests each element (receives value and index)
-   *
    * **Example** (Filtering elements)
    *
    * ```ts
@@ -3953,7 +3907,7 @@ export const filter: {
  * ```
  *
  * @category sequencing
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const flatMapNullishOr: {
   /**
@@ -3997,7 +3951,7 @@ export const flatMapNullishOr: {
    * ```
    *
    * @category sequencing
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B): (self: Iterable<A>) => Iterable<NonNullable<B>>
   /**
@@ -4041,7 +3995,7 @@ export const flatMapNullishOr: {
    * ```
    *
    * @category sequencing
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(self: Iterable<A>, f: (a: A) => B): Iterable<NonNullable<B>>
 } = dual(

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,7 +173,7 @@ 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>
@@ -205,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 }
@@ -223,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 {
@@ -313,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 = [
@@ -330,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 {