effect 4.0.0-beta.5 → 4.0.0-beta.50

package/src/FileSystem.ts

@@ -38,13 +38,15 @@
 import * as Arr from "./Array.ts"
 import * as Brand from "./Brand.ts"
 import * as Cause from "./Cause.ts"
+import * as Context from "./Context.ts"
 import * as Effect from "./Effect.ts"
 import { pipe } from "./Function.ts"
 import * as Layer from "./Layer.ts"
+import * as Option from "./Option.ts"
 import { badArgument, type PlatformError, systemError } from "./PlatformError.ts"
+import { hasProperty } from "./Predicate.ts"
 import type * as Pull from "./Pull.ts"
 import type { Scope } from "./Scope.ts"
-import * as ServiceMap from "./ServiceMap.ts"
 import * as Sink from "./Sink.ts"
 import * as Stream from "./Stream.ts"
 
@@ -709,7 +711,7 @@ export type OpenFlag =
  * @since 4.0.0
  * @category tag
  */
-export const FileSystem: ServiceMap.Service<FileSystem, FileSystem> = ServiceMap.Service("effect/platform/FileSystem")
+export const FileSystem: Context.Service<FileSystem, FileSystem> = Context.Service("effect/platform/FileSystem")
 
 /**
  * Creates a FileSystem implementation from a partial implementation.
@@ -756,22 +758,24 @@ export const make = (
       const bytesToRead = options?.bytesToRead !== undefined ? Size(options.bytesToRead) : undefined
       let totalBytesRead = BigInt(0)
       const chunkSize = Size(options?.chunkSize ?? 64 * 1024)
+      const readChunk = file.readAlloc(chunkSize)
       return Stream.fromPull(Effect.succeed(
         Effect.flatMap(
-          Effect.suspend((): Pull.Pull<Uint8Array | undefined, PlatformError> => {
+          Effect.suspend((): Pull.Pull<Option.Option<Uint8Array>, PlatformError> => {
             if (bytesToRead !== undefined && bytesToRead <= totalBytesRead) {
               return Cause.done()
             }
-            const toRead = bytesToRead !== undefined && (bytesToRead - totalBytesRead) < chunkSize
-              ? bytesToRead - totalBytesRead
-              : chunkSize
-            return file.readAlloc(toRead)
+            return bytesToRead !== undefined && (bytesToRead - totalBytesRead) < chunkSize
+              ? file.readAlloc(bytesToRead - totalBytesRead)
+              : readChunk
           }),
-          (buf) => {
-            if (!buf) return Cause.done()
-            totalBytesRead += BigInt(buf.length)
-            return Effect.succeed(Arr.of(buf))
-          }
+          Option.match({
+            onNone: () => Cause.done(),
+            onSome: (buf) => {
+              totalBytesRead += BigInt(buf.length)
+              return Effect.succeed(Arr.of(buf))
+            }
+          })
         )
       ))
     }, Stream.unwrap),
@@ -996,7 +1000,7 @@ export const FileTypeId = "~effect/platform/FileSystem/File"
  * @since 4.0.0
  * @category File
  */
-export const isFile = (u: unknown): u is File => typeof u === "object" && u !== null && FileTypeId in u
+export const isFile = (u: unknown): u is File => hasProperty(u, FileTypeId)
 
 /**
  * Interface representing an open file handle.
@@ -1046,7 +1050,7 @@ export interface File {
   readonly seek: (offset: SizeInput, from: SeekMode) => Effect.Effect<void>
   readonly sync: Effect.Effect<void, PlatformError>
   readonly read: (buffer: Uint8Array) => Effect.Effect<Size, PlatformError>
-  readonly readAlloc: (size: SizeInput) => Effect.Effect<Uint8Array | undefined, PlatformError>
+  readonly readAlloc: (size: SizeInput) => Effect.Effect<Option.Option<Uint8Array>, PlatformError>
   readonly truncate: (length?: SizeInput) => Effect.Effect<void, PlatformError>
   readonly write: (buffer: Uint8Array) => Effect.Effect<Size, PlatformError>
   readonly writeAll: (buffer: Uint8Array) => Effect.Effect<void, PlatformError>
@@ -1096,7 +1100,7 @@ export declare namespace File {
    *
    * @example
    * ```ts
-   * import { Console, Effect, FileSystem } from "effect"
+   * import { Console, Effect, FileSystem, Option } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const fs = yield* FileSystem.FileSystem
@@ -1108,7 +1112,7 @@ export declare namespace File {
    *   yield* Console.log(`Mode: ${info.mode.toString(8)}`) // Octal permissions
    *
    *   // Handle optional timestamps
-   *   const mtime = info.mtime ?? new Date(0)
+   *   const mtime = Option.getOrElse(info.mtime, () => new Date(0))
    *   yield* Console.log(`Modified: ${mtime.toISOString()}`)
    *
    *   // Check if it's a regular file
@@ -1123,19 +1127,19 @@ export declare namespace File {
    */
   export interface Info {
     readonly type: Type
-    readonly mtime: Date | undefined
-    readonly atime: Date | undefined
-    readonly birthtime: Date | undefined
+    readonly mtime: Option.Option<Date>
+    readonly atime: Option.Option<Date>
+    readonly birthtime: Option.Option<Date>
     readonly dev: number
-    readonly ino: number | undefined
+    readonly ino: Option.Option<number>
     readonly mode: number
-    readonly nlink: number | undefined
-    readonly uid: number | undefined
-    readonly gid: number | undefined
-    readonly rdev: number | undefined
+    readonly nlink: Option.Option<number>
+    readonly uid: Option.Option<number>
+    readonly gid: Option.Option<number>
+    readonly rdev: Option.Option<number>
     readonly size: Size
-    readonly blksize: Size | undefined
-    readonly blocks: number | undefined
+    readonly blksize: Option.Option<Size>
+    readonly blocks: Option.Option<number>
   }
 }
 
@@ -1226,13 +1230,13 @@ export declare namespace WatchEvent {
  *
  * @example
  * ```ts
- * import { Effect, FileSystem, Stream } from "effect"
+ * import { Effect, FileSystem, Option, Stream } from "effect"
  *
  * // Custom watch backend implementation
  * const customWatchBackend = {
  *   register: (path: string, stat: FileSystem.File.Info) => {
  *     // Implementation would depend on platform
- *     return Stream.empty // Placeholder implementation
+ *     return Option.some(Stream.empty) // Placeholder implementation
  *   }
  * }
  *
@@ -1254,6 +1258,6 @@ export declare namespace WatchEvent {
  * @since 4.0.0
  * @category file watcher
  */
-export class WatchBackend extends ServiceMap.Service<WatchBackend, {
-  readonly register: (path: string, stat: File.Info) => Stream.Stream<WatchEvent, PlatformError> | undefined
+export class WatchBackend extends Context.Service<WatchBackend, {
+  readonly register: (path: string, stat: File.Info) => Option.Option<Stream.Stream<WatchEvent, PlatformError>>
 }>()("effect/platform/FileSystem/WatchBackend") {}

package/src/Filter.ts

@@ -29,8 +29,8 @@ import type { EqualsWith, ExcludeTag, ExtractReason, ExtractTag, ReasonTags, Tag
  * @since 4.0.0
  * @category Models
  */
-export interface Filter<in Input, out Pass = Input, out Fail = Input, in Args extends ReadonlyArray<any> = []> {
-  (input: Input, ...args: Args): Result.Result<Pass, Fail>
+export interface Filter<in Input, out Pass = Input, out Fail = Input> {
+  (input: Input): Result.Result<Pass, Fail>
 }
 
 /**
@@ -68,67 +68,9 @@ export interface FilterEffect<
   out Pass,
   out Fail,
   out E = never,
-  out R = never,
-  in Args extends Array<any> = []
+  out R = never
 > {
-  (input: Input, ...args: Args): Effect<Result.Result<Pass, Fail>, E, R>
-}
-
-// -------------------------------------------------------------------------------------
-// apply
-// -------------------------------------------------------------------------------------
-
-/**
- * @since 4.0.0
- * @category Apply
- */
-export type OrPredicate<A, R extends boolean | Result.Result<any, any>, Args extends ReadonlyArray<any> = []> = (
-  input: A,
-  ...args: Args
-) => R
-
-/**
- * @since 4.0.0
- * @category Apply
- */
-export type ResultOrBool<Out = any> = boolean | Result.Result<any, Out>
-
-/**
- * @since 4.0.0
- * @category Apply
- */
-export type Pass<A, R extends boolean | Result.Result<any, any>> = [R] extends [Result.Result<infer _P, infer _F>] ? _P
-  : A
-
-/**
- * @since 4.0.0
- * @category Apply
- */
-export type Fail<A, R extends boolean | Result.Result<any, any>> = [R] extends [Result.Result<infer _P, infer _F>] ? _F
-  : A
-
-/**
- * @since 4.0.0
- * @category Apply
- */
-export type ApplyResult<A, R extends boolean | Result.Result<any, any>> = Result.Result<Pass<A, R>, Fail<A, R>>
-
-/**
- * Applies a filter, predicate, or refinement to an input and returns a boxed
- * result. Extra arguments are forwarded to the function.
- *
- * @since 4.0.0
- * @category Apply
- */
-export const apply = <In, R extends ResultOrBool>(
-  filter: (input: In, ...args: Array<any>) => R,
-  input: In,
-  ...args: Array<any>
-): ApplyResult<In, R> => {
-  const result = filter(input, ...args)
-  if (result === true) return Result.succeed(input) as any
-  if (result === false) return Result.fail(input) as any
-  return result as any
+  (input: Input): Effect<Result.Result<Pass, Fail>, E, R>
 }
 
 // -------------------------------------------------------------------------------------

package/src/Formatter.ts

@@ -1,10 +1,85 @@
 /**
+ * Utilities for converting arbitrary JavaScript values into human-readable
+ * strings, with support for circular references, redaction, and common JS
+ * types that `JSON.stringify` handles poorly.
+ *
+ * Mental model:
+ * - A `Formatter<Value, Format>` is a callable `(value: Value) => Format`.
+ * - {@link format} is the general-purpose pretty-printer: it handles
+ *   primitives, arrays, objects, `BigInt`, `Symbol`, `Date`, `RegExp`,
+ *   `Set`, `Map`, class instances, and circular references.
+ * - {@link formatJson} is a safe `JSON.stringify` wrapper that silently
+ *   drops circular references and applies redaction.
+ * - Both functions accept a `space` option for indentation control.
+ *
+ * Common tasks:
+ * - Pretty-print any value for debugging / logging -> {@link format}
+ * - Serialize to JSON safely (no circular throws) -> {@link formatJson}
+ * - Format a single object property key -> {@link formatPropertyKey}
+ * - Format a property path like `["a"]["b"]` -> {@link formatPath}
+ * - Format a `Date` to ISO string safely -> {@link formatDate}
+ *
+ * Gotchas:
+ * - {@link format} output is **not** valid JSON; use {@link formatJson} when
+ *   you need parseable JSON.
+ * - {@link format} calls `toString()` on objects by default; pass
+ *   `ignoreToString: true` to disable.
+ * - {@link formatJson} silently omits circular references (the key is
+ *   dropped from the output).
+ * - Values implementing the `Redactable` protocol are automatically
+ *   redacted by both {@link format} and {@link formatJson}.
+ *
+ * **Example** (Pretty-print a value)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * const obj = { name: "Alice", scores: [100, 97] }
+ * console.log(Formatter.format(obj))
+ * // {"name":"Alice","scores":[100,97]}
+ *
+ * console.log(Formatter.format(obj, { space: 2 }))
+ * // {
+ * //   "name": "Alice",
+ * //   "scores": [
+ * //     100,
+ * //     97
+ * //   ]
+ * // }
+ * ```
+ *
+ * See also: {@link Formatter}, {@link format}, {@link formatJson}
+ *
  * @since 4.0.0
  */
 import * as Predicate from "./Predicate.ts"
 import { getRedacted, redact, symbolRedactable } from "./Redactable.ts"
 
 /**
+ * A callable interface representing a function that converts a `Value` into a
+ * `Format` (defaults to `string`).
+ *
+ * When to use:
+ * - You want to type a formatting / rendering function generically.
+ * - You are building a pipeline that accepts pluggable formatters.
+ *
+ * Behavior:
+ * - Pure callable type; carries no runtime implementation.
+ * - Contravariant in `Value`, covariant in `Format`.
+ *
+ * **Example** (Define a custom formatter)
+ *
+ * ```ts
+ * import type { Formatter } from "effect"
+ *
+ * const upper: Formatter.Formatter<string> = (s) => s.toUpperCase()
+ *
+ * console.log(upper("hello"))
+ * // HELLO
+ * ```
+ *
+ * See also: {@link format}, {@link formatJson}
+ *
  * @category Model
  * @since 4.0.0
  */
@@ -15,31 +90,71 @@ export interface Formatter<in Value, out Format = string> {
 /**
  * Converts any JavaScript value into a human-readable string.
  *
- * For objects that don't have a `toString` method, it applies redaction to
- * protect sensitive information.
- *
- * Unlike `JSON.stringify`, this formatter:
- * - Handles circular references (printed as `"[Circular]"`).
- * - Supports additional types like `BigInt`, `Symbol`, `Set`, `Map`, `Date`, `RegExp`, and
- *   objects with custom `toString` methods.
- * - Includes constructor names for class instances (e.g. `MyClass({"a":1})`).
- * - Does not guarantee valid JSON output — the result is intended for debugging and inspection.
- *
- * Formatting rules:
- * - Primitives are stringified naturally (`null`, `undefined`, `123`, `"abc"`, `true`).
- * - Strings are JSON-quoted.
- * - Arrays and objects with a single element/property are formatted inline.
- * - Larger arrays/objects are pretty-printed with optional indentation.
- * - Circular references are replaced with the literal `"[Circular]"`.
- *
- * **Options**:
- * - `space`: Indentation used when pretty-printing:
- *   - If a number, that many spaces will be used.
- *   - If a string, the string is used as the indentation unit (e.g. `"\t"`).
- *   - If `0`, empty string, or `undefined`, output is compact (no indentation).
- *   Defaults to `0`.
- * - `ignoreToString`: If `true`, the `toString` method is not called on the value.
- *   Defaults to `false`.
+ * When to use:
+ * - Pretty-printing values for debugging, logging, or error messages.
+ * - You need to handle `BigInt`, `Symbol`, `Set`, `Map`, `Date`, `RegExp`,
+ *   or class instances that `JSON.stringify` cannot represent.
+ * - You want circular references shown as `"[Circular]"` instead of
+ *   throwing.
+ *
+ * Behavior:
+ * - Does not mutate input.
+ * - Output is **not** valid JSON; use {@link formatJson} when you need
+ *   parseable JSON.
+ * - Primitives: stringified naturally (`null`, `undefined`, `123`, `true`).
+ *   Strings are JSON-quoted.
+ * - Objects with a custom `toString` (not `Object.prototype.toString`):
+ *   `toString()` is called unless `ignoreToString` is `true`.
+ * - Errors with a `cause`: formatted as `"<message> (cause: <cause>)"`.
+ * - Iterables (`Set`, `Map`, etc.): formatted as
+ *   `ClassName([...elements])`.
+ * - Class instances: wrapped as `ClassName({...})`.
+ * - `Redactable` values are automatically redacted.
+ * - Arrays/objects with 0–1 entries are inline; larger ones are
+ *   pretty-printed when `space` is set.
+ * - Circular references are replaced with `"[Circular]"`.
+ *
+ * Options:
+ * - `space` — indentation unit (number of spaces, or a string like
+ *   `"\t"`). Defaults to `0` (compact).
+ * - `ignoreToString` — skip calling `toString()`. Defaults to `false`.
+ *
+ * **Example** (Compact output)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.format({ a: 1, b: [2, 3] }))
+ * // {"a":1,"b":[2,3]}
+ * ```
+ *
+ * **Example** (Pretty-printed output)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.format({ a: 1, b: [2, 3] }, { space: 2 }))
+ * // {
+ * //   "a": 1,
+ * //   "b": [
+ * //     2,
+ * //     3
+ * //   ]
+ * // }
+ * ```
+ *
+ * **Example** (Circular reference handling)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * const obj: any = { name: "loop" }
+ * obj.self = obj
+ * console.log(Formatter.format(obj))
+ * // {"name":"loop","self":[Circular]}
+ * ```
+ *
+ * See also: {@link formatJson}, {@link Formatter}
  *
  * @since 4.0.0
  */
@@ -101,7 +216,7 @@ export function format(input: unknown, options?: {
 
     if (typeof v === "bigint") return String(v) + "n"
 
-    if (Predicate.isObject(v)) {
+    if (typeof v === "object" || typeof v === "function") {
       if (seen.has(v)) return CIRCULAR
       seen.add(v)
 
@@ -131,7 +246,29 @@ export function format(input: unknown, options?: {
 const CIRCULAR = "[Circular]"
 
 /**
- * Fast path for formatting property keys.
+ * Formats a single property key for display.
+ *
+ * When to use:
+ * - You are building a custom formatter that needs to render object keys.
+ *
+ * Behavior:
+ * - String keys are JSON-quoted (e.g. `"foo"`).
+ * - Symbol and number keys are converted with `String()`.
+ * - Pure function; does not mutate input.
+ *
+ * **Example** (Format property keys)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.formatPropertyKey("name"))
+ * // "name"
+ *
+ * console.log(Formatter.formatPropertyKey(Symbol.for("id")))
+ * // Symbol(id)
+ * ```
+ *
+ * See also: {@link formatPath}, {@link format}
  *
  * @internal
  */
@@ -140,7 +277,28 @@ export function formatPropertyKey(name: PropertyKey): string {
 }
 
 /**
- * Fast path for formatting property paths.
+ * Formats an array of property keys as a bracket-notation path string.
+ *
+ * When to use:
+ * - You need to display a path through a nested object (e.g. in error
+ *   messages or schema validation output).
+ *
+ * Behavior:
+ * - Each key is wrapped in brackets and formatted via
+ *   {@link formatPropertyKey}.
+ * - Returns an empty string for an empty path.
+ * - Pure function; does not mutate input.
+ *
+ * **Example** (Render a property path)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.formatPath(["users", 0, "name"]))
+ * // ["users"][0]["name"]
+ * ```
+ *
+ * See also: {@link formatPropertyKey}, {@link format}
  *
  * @internal
  */
@@ -149,7 +307,31 @@ export function formatPath(path: ReadonlyArray<PropertyKey>): string {
 }
 
 /**
- * Fast path for formatting dates.
+ * Formats a `Date` as an ISO 8601 string, returning `"Invalid Date"` for
+ * invalid dates instead of throwing.
+ *
+ * When to use:
+ * - You want a safe `toISOString()` that never throws.
+ *
+ * Behavior:
+ * - Returns `date.toISOString()` on success.
+ * - Returns `"Invalid Date"` if `toISOString()` throws (e.g. for
+ *   `new Date(NaN)`).
+ * - Pure function; does not mutate input.
+ *
+ * **Example** (Safe date formatting)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.formatDate(new Date("2024-01-15T10:30:00Z")))
+ * // 2024-01-15T10:30:00.000Z
+ *
+ * console.log(Formatter.formatDate(new Date("invalid")))
+ * // Invalid Date
+ * ```
+ *
+ * See also: {@link format}
  *
  * @internal
  */
@@ -171,42 +353,62 @@ function safeToString(input: any): string {
 }
 
 /**
- * Safely stringifies objects that may contain circular references.
+ * Safely stringifies a value to JSON, silently dropping circular references.
+ *
+ * When to use:
+ * - You need valid JSON output (unlike {@link format}).
+ * - The input may contain circular references and you want them silently
+ *   omitted rather than throwing a `TypeError`.
  *
- * This function performs JSON.stringify with circular reference detection and handling.
- * It also applies redaction to sensitive values and provides a safe fallback for
- * any objects that can't be serialized normally.
+ * Behavior:
+ * - Does not mutate input.
+ * - Uses `JSON.stringify` internally with a replacer that tracks seen
+ *   objects.
+ * - Circular references are replaced with `undefined` (omitted from
+ *   output).
+ * - `Redactable` values are automatically redacted before serialization.
+ * - Types not supported by JSON (`BigInt`, `Symbol`, `undefined`,
+ *   functions) follow standard `JSON.stringify` behavior (omitted or
+ *   `null` in arrays).
  *
- * **Options**:
- * - `space`: Indentation used when pretty-printing:
- *   - If a number, that many spaces will be used.
- *   - If a string, the string is used as the indentation unit (e.g. `"\t"`).
- *   - If `0`, empty string, or `undefined`, output is compact (no indentation).
- *   Defaults to `0`.
+ * Options:
+ * - `space` — indentation unit (number of spaces, or a string like
+ *   `"\t"`). Defaults to `0` (compact).
+ *
+ * **Example** (Compact JSON)
  *
- * @example
  * ```ts
- * import { formatJson } from "effect/Formatter"
+ * import { Formatter } from "effect"
  *
- * // Normal object
- * const simple = { name: "Alice", age: 30 }
- * console.log(formatJson(simple))
+ * console.log(Formatter.formatJson({ name: "Alice", age: 30 }))
  * // {"name":"Alice","age":30}
+ * ```
+ *
+ * **Example** (Circular reference handling)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
  *
- * // Object with circular reference
- * const circular: any = { name: "test" }
- * circular.self = circular
- * console.log(formatJson(circular))
- * // {"name":"test"} (circular reference omitted)
+ * const obj: any = { name: "test" }
+ * obj.self = obj
+ * console.log(Formatter.formatJson(obj))
+ * // {"name":"test"}
+ * ```
+ *
+ * **Example** (Pretty-printed JSON)
  *
- * // With formatting
- * console.log(formatJson(simple, { space: 2 }))
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * console.log(Formatter.formatJson({ name: "Alice", age: 30 }, { space: 2 }))
  * // {
  * //   "name": "Alice",
  * //   "age": 30
  * // }
  * ```
  *
+ * See also: {@link format}, {@link Formatter}
+ *
  * @since 4.0.0
  */
 export function formatJson(input: unknown, options?: {

package/src/Function.ts

@@ -402,18 +402,10 @@ export const satisfies = <A>() => <B extends A>(b: B) => b
 /**
  * Casts the result to the specified type.
  *
- * @example
- * ```ts
- * import { coerceUnsafe, identity } from "effect/Function"
- * import * as assert from "node:assert"
- *
- * assert.deepStrictEqual(coerceUnsafe, identity)
- * ```
- *
  * @category type utils
  * @since 2.0.0
  */
-export const coerceUnsafe: <A, B>(a: A) => B = identity as any
+export const cast: <A, B>(a: A) => B = identity as any
 
 /**
  * Creates a constant value that never changes.
@@ -1392,7 +1384,7 @@ export function flow(
  * @category utilities
  * @since 2.0.0
  */
-export const hole: <T>() => T = coerceUnsafe(absurd)
+export const hole: <T>() => T = cast(absurd)
 
 /**
  * The SK combinator, also known as the "S-K combinator" or "S-combinator", is a fundamental combinator in the