effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/unstable/cli/Primitive.ts

@@ -1,13 +1,62 @@
 /**
- * Primitive types for CLI parameter parsing.
+ * The `Primitive` module defines the lowest-level value parsers used by the
+ * unstable CLI package. A `Primitive<A>` takes one raw command-line string and
+ * returns an `Effect` that either produces an `A` or fails with a parser
+ * message.
+ *
+ * `Argument` and `Flag` build on primitives to add names, aliases, defaults,
+ * prompts, config fallbacks, repetition, and help metadata. Use this module
+ * directly when defining a custom CLI input shape or when composing parser
+ * behavior before it becomes an argument or flag.
+ *
+ * **Mental model**
+ *
+ * - A primitive parses one value token; it does not know whether the token came
+ *   from a positional argument or a named flag.
+ * - Parsing may be pure, such as {@link string}, {@link integer},
+ *   {@link boolean}, or {@link choice}, or effectful, such as {@link path},
+ *   {@link fileText}, {@link fileParse}, and {@link fileSchema}.
+ * - Failure is represented as a string message so higher-level CLI parsers can
+ *   attach it to generated usage and help output.
+ * - File and path primitives require filesystem and path services through the
+ *   parsing effect environment.
+ *
+ * **Common tasks**
+ *
+ * - Parse scalar values with {@link string}, {@link integer}, {@link float},
+ *   {@link boolean}, and {@link date}.
+ * - Restrict input to named alternatives with {@link choice}.
+ * - Resolve and validate filesystem paths with {@link path}.
+ * - Read raw file content with {@link fileText}, parse structured files with
+ *   {@link fileParse}, or decode parsed content with {@link fileSchema}.
+ * - Hide sensitive input with {@link redacted}.
+ * - Parse `key=value` entries with {@link keyValuePair}.
+ *
+ * **Example** (Parsing raw CLI values)
  *
- * Primitives handle the low-level parsing of string input into typed values.
- * Most users should use the higher-level `Argument` and `Flag` modules instead.
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Primitive } from "effect/unstable/cli"
+ *
+ * const parseValues = Effect.gen(function*() {
+ *   const port = yield* Primitive.integer.parse("8080")
+ *   const mode = yield* Primitive.choice([
+ *     ["dev", "development"],
+ *     ["prod", "production"]
+ *   ] as const).parse("prod")
+ *
+ *   return { port, mode }
+ * })
+ * ```
+ *
+ * **Gotchas**
  *
- * This module is primarily useful for:
- * - Creating custom primitive types
- * - Understanding how CLI parsing works internally
- * - Advanced customization of parsing behavior
+ * - `choice` matches input strings exactly; it does not normalize casing or
+ *   trim whitespace.
+ * - `fileParse` selects a parser from `options.format` or the file extension;
+ *   unsupported formats fail before schema decoding.
+ * - {@link none} is a sentinel parser that always fails. It is used by higher
+ *   layers for parameters that must reject attached values.
  *
  * @since 4.0.0
  */
@@ -679,7 +728,7 @@ export const keyValuePair: Primitive<Record<string, string>> = makePrimitive(
  *
  * **When to use**
  *
- * Used for flags that don't accept values.
+ * Use when you need flags that don't accept values.
  *
  * **Example** (Rejecting option values)
  *
@@ -705,7 +754,7 @@ export const none: Primitive<never> = makePrimitive("None", () => Effect.fail("T
  *
  * **When to use**
  *
- * Used for generating help documentation.
+ * Use when you need generating help documentation.
  *
  * **Example** (Getting primitive type names)
  *

package/src/unstable/cli/Prompt.ts

@@ -158,7 +158,7 @@ export interface ConfirmOptions {
    */
   readonly message: string
   /**
-   * The intitial value of the confirm prompt (defaults to `false`).
+   * The initial value of the confirm prompt (defaults to `false`).
    */
   readonly initial?: boolean
   /**
@@ -708,6 +708,17 @@ const annotateErrorLine = (line: string): string => Ansi.annotate(line, Ansi.com
  * Creates a confirmation prompt that asks the user to choose a boolean yes/no
  * value.
  *
+ * **When to use**
+ *
+ * Use to ask for a yes/no answer that can be submitted directly.
+ *
+ * **Details**
+ *
+ * `initial` defaults to `false`. Enter submits the current default, yes-style
+ * input submits `true`, no-style input submits `false`, and other input beeps.
+ *
+ * @see {@link toggle} for an interactive switch-before-submit boolean prompt
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -767,6 +778,20 @@ export const custom = <State, Output>(
  * Creates a date prompt that lets the user edit a formatted date value and
  * validates the final `Date` before submission.
  *
+ * **Details**
+ *
+ * `initial` defaults to the current `Date`, `dateMask` defaults to
+ * `YYYY-MM-DD HH:mm:ss`, mask parsing creates editable date parts plus literal
+ * tokens, `locales` customizes month and weekday labels, and `validate` runs on
+ * submission.
+ *
+ * **Gotchas**
+ *
+ * A supplied `initial` `Date` is edited in place during prompt interaction.
+ * Date edits use JavaScript `Date` setters, so out-of-range typed values can
+ * normalize before validation. If the prompt is meant to be editable,
+ * `dateMask` should contain at least one editable date token.
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/cli/index.ts

@@ -5,276 +5,56 @@
 // @barrel: Auto-generated exports. Do not edit manually.
 
 /**
- * The `Argument` module defines typed positional command-line arguments for
- * Effect CLI applications. Arguments consume ordered values after a command name
- * and its flags, then parse them into the types your command handler expects.
- *
- * Use this module for required inputs such as file paths, directories, numbers,
- * dates, choices, secrets, and structured configuration files. Arguments can be
- * made optional, variadic, validated with Schema, transformed with pure or
- * effectful functions, and supplied from defaults, config, or prompts when
- * missing.
- *
- * **Gotchas**
- *
- * - Positional arguments are order-sensitive; compose them in the same order the
- *   user should type them.
- * - `variadic` arguments can consume more than one value, so place them where
- *   the remaining positional input belongs.
- * - Use {@link withDescription} and {@link withMetavar} to keep generated help
- *   text clear, especially when the parser name differs from the value users
- *   should provide.
- * - Boolean positional arguments are intentionally not provided. Prefer boolean
- *   flags, or use {@link choice} for explicit `"true"` / `"false"` values.
- *
  * @since 4.0.0
  */
 export * as Argument from "./Argument.ts"
 
 /**
- * The `CliError` module defines the structured error model used by the
- * unstable CLI parser and runner. It distinguishes command-line parse failures,
- * CLI definition problems, explicit help requests, and user handler failures so
- * applications can report errors consistently while still pattern matching on
- * the exact cause.
- *
- * **Common tasks**
- *
- * - Detect CLI errors at runtime with {@link isCliError}
- * - Represent parse failures such as unknown flags, missing required inputs, or
- *   invalid argument values
- * - Attach parse or validation errors to {@link ShowHelp} when the runner should
- *   render help text together with the failure
- * - Preserve command handler failures with {@link UserError}
- *
- * **Gotchas**
- *
- * - {@link ShowHelp} is a control-flow error, not a parse failure; it exits with
- *   code `0` for explicit help and `1` when it carries errors
- * - Duplicate option names between parent and child commands are rejected
- *   because the parent command claims the flag before the child can see it
- * - Suggestion-bearing errors keep suggestions separate from the primary cause
- *   so help renderers can decide how much guidance to display
- *
  * @since 4.0.0
  */
 export * as CliError from "./CliError.ts"
 
 /**
- * The `CliOutput` module provides the formatting service used by Effect CLI
- * applications to turn parsed CLI metadata and failures into terminal text.
- * It renders help documents, parser errors, grouped errors, and version output,
- * while allowing applications and tests to replace the formatter through a
- * `Context` service or `Layer`.
- *
- * **Common tasks**
- *
- * - Render generated {@link HelpDoc} values for `--help` output
- * - Display parser failures and validation errors from CLI programs
- * - Customize output for plain text, colored terminals, tests, or alternate
- *   formats
- * - Format version strings consistently with the rest of CLI output
- *
- * **Gotchas**
- *
- * - Color output is auto-detected from `process.stdout.isTTY` and `NO_COLOR`,
- *   but can be forced with {@link defaultFormatter}
- * - Help tables measure visible width after stripping ANSI escape codes, so
- *   colored output stays aligned with plain output
- *
  * @since 4.0.0
  */
 export * as CliOutput from "./CliOutput.ts"
 
 /**
- * The `Command` module provides the core building block for defining and
- * running Effect-based command-line applications. A `Command` combines a name,
- * typed flags and positional arguments, optional subcommands, metadata for help
- * output, and an effectful handler.
- *
- * **Common tasks**
- *
- * - Create commands with {@link make}
- * - Add handlers with {@link withHandler}
- * - Build nested command trees with {@link withSubcommands}
- * - Share parent flags with subcommands using {@link withSharedFlags}
- * - Add command-scoped global flags with {@link withGlobalFlags}
- * - Attach help metadata with {@link withDescription}, {@link withShortDescription},
- *   {@link withAlias}, and {@link withExamples}
- * - Provide handler dependencies with {@link provide}, {@link provideSync},
- *   {@link provideEffect}, and {@link provideEffectDiscard}
- * - Execute commands with {@link run} or test them with {@link runWith}
- *
- * **Gotchas**
- *
- * - `withSharedFlags` accepts only flags, not positional arguments, and the
- *   parsed values are available to descendants by yielding the parent command.
- * - Shared flags may be written before or after the selected subcommand name.
- * - Duplicate flags across command scopes are rejected so parsing and help
- *   output remain unambiguous.
- * - `runWith` is the preferred entry point for tests because it accepts an
- *   explicit argument array instead of reading from the `Stdio` service.
- *
  * @since 4.0.0
  */
 export * as Command from "./Command.ts"
 
 /**
- * Shell completion descriptors and script generation for the unstable CLI API.
- *
  * @since 4.0.0
  */
 export * as Completions from "./Completions.ts"
 
 /**
- * The `Flag` module provides typed command-line options for Effect CLI
- * applications. A `Flag<A>` describes how to read one named option from the
- * parsed command line, validate it, and produce a value of type `A`.
- *
- * Use flags for inputs that are naturally named options, such as ports,
- * verbosity switches, configuration files, output directories, enum-like
- * choices, secrets, and repeated values. Constructors such as {@link string},
- * {@link boolean}, {@link integer}, {@link file}, and {@link fileSchema}
- * define the accepted input shape, while combinators add aliases, defaults,
- * optionality, fallback config or prompts, validation, and typed mapping.
- *
- * Flag names are rendered as long options, for example `Flag.integer("port")`
- * parses `--port 8080`. Boolean flags also support the disabled form shown by
- * this module's boolean documentation, and repeated flags are modeled with the
- * repetition combinators instead of by manually inspecting raw arguments. Help
- * text is generated from flag metadata, so prefer {@link withDescription} and
- * {@link withMetavar} when a flag's value, format, or file-system expectation
- * would otherwise be ambiguous.
- *
  * @since 4.0.0
  */
 export * as Flag from "./Flag.ts"
 
 /**
- * The `GlobalFlag` module defines flags that are available to every command in
- * an Effect CLI application. Global flags are useful for cross-cutting command
- * line behavior such as printing help, showing the application version,
- * generating shell completions, or configuring shared handler settings like the
- * minimum log level.
- *
- * **Common tasks**
- *
- * - Create an action flag with {@link action} for side effects that should run
- *   before the selected command, such as `--help` or `--version`
- * - Create a setting flag with {@link setting} for values that should be made
- *   available to command handlers through the Effect context
- * - Reuse the built-in {@link Help}, {@link Version}, {@link Completions}, and
- *   {@link LogLevel} flags when constructing command runners
- *
- * **Gotchas**
- *
- * - Action flags are intended to perform their effect and exit instead of
- *   continuing into the command handler
- * - Setting flags allocate a distinct context service for each call to
- *   {@link setting}, so reuse exported settings when handlers need to read the
- *   same parsed global value
- *
  * @since 4.0.0
  */
 export * as GlobalFlag from "./GlobalFlag.ts"
 
 /**
- * The `HelpDoc` module defines the structured documentation model used by the
- * unstable CLI package to describe command help. A `HelpDoc` value captures the
- * user-facing parts of a command, including its description, usage string,
- * positional arguments, flags, global flags, subcommands, and examples.
- *
- * **Common tasks**
- *
- * - Build help data from command definitions before rendering it
- * - Pass command documentation to `CliOutput.Formatter` implementations
- * - Represent custom help output formats without changing command parsing
- * - Group subcommands and distinguish local flags from global flags
- *
- * **Gotchas**
- *
- * - `HelpDoc` is format-agnostic; layout, ANSI styling, and table alignment are
- *   handled by the output formatter
- * - Optional argument and flag descriptions use `Option.Option<string>`, while
- *   optional sections are omitted when they have no entries
- * - Long names, aliases, and descriptions may require formatter-specific width
- *   handling when rendering terminal help
- *
  * @since 4.0.0
  */
 export * as HelpDoc from "./HelpDoc.ts"
 
 /**
- * The `Param` module defines the shared parser tree used by the unstable CLI
- * `Argument` and `Flag` modules. A `Param<Kind, A>` describes how to consume
- * either positional arguments or named flags from parsed command-line input and
- * return a typed value.
- *
- * **Common tasks**
- *
- * - Build primitive CLI inputs such as strings, booleans, numbers, choices,
- *   paths, files, and redacted values
- * - Attach help metadata with aliases and descriptions
- * - Transform parsed values with pure or effectful validation
- * - Model missing inputs with `Option`, defaults, config fallbacks, or prompts
- * - Accept repeated inputs with variadic, bounded, and non-empty parameters
- *
- * **Gotchas**
- *
- * - The `Kind` type parameter (`"argument"` or `"flag"`) keeps positional
- *   arguments and flags separate while allowing the implementation and
- *   combinators to be shared.
- * - Combinators preserve the parameter kind, so an argument parameter cannot be
- *   accidentally composed into a flag parameter or the reverse.
- * - Parsers return both the remaining positional arguments and the parsed
- *   value; this is important for argument ordering and variadic parameters.
- * - Some parsers require CLI services such as filesystem, path, terminal, or
- *   child-process support through the parsing environment.
- *
  * @since 4.0.0
  */
 export * as Param from "./Param.ts"
 
 /**
- * Primitive types for CLI parameter parsing.
- *
- * Primitives handle the low-level parsing of string input into typed values.
- * Most users should use the higher-level `Argument` and `Flag` modules instead.
- *
- * This module is primarily useful for:
- * - Creating custom primitive types
- * - Understanding how CLI parsing works internally
- * - Advanced customization of parsing behavior
- *
  * @since 4.0.0
  */
 export * as Primitive from "./Primitive.ts"
 
 /**
- * The `Prompt` module provides composable, effectful building blocks for
- * interactive command-line questions. A `Prompt<A>` describes terminal UI that
- * renders frames, reads keyboard input, validates responses, and eventually
- * produces a value of type `A`.
- *
- * **Common tasks**
- *
- * - Ask for text, password, hidden, list, confirm, toggle, number, or date input
- * - Let users choose from select, autocomplete, multi-select, and file prompts
- * - Combine prompts with {@link all}, {@link map}, and {@link flatMap}
- * - Build specialized prompts with {@link custom}
- * - Run a prompt against the current terminal with {@link run}
- *
- * **Gotchas**
- *
- * - Prompts require terminal services and may fail with `Terminal.QuitError`
- *   when input ends or the prompt is quit
- * - Rendering is frame-based: custom prompts must return ANSI output from
- *   `render` and matching ANSI clearing output from `clear`
- * - Choices and file lists are paged by `maxPerPage`, so keyboard navigation
- *   and filtering should account for hidden off-page entries
- * - `password` and `hidden` return `Redacted` values; unwrap them only at the
- *   boundary where the secret is needed
- *
  * @since 4.0.0
  */
 export * as Prompt from "./Prompt.ts"

package/src/unstable/cluster/ClusterCron.ts

@@ -87,7 +87,7 @@ export const make = <E, R>(options: {
    *
    * **When to use**
    *
-   * This is useful to prevent running jobs that were scheduled too far in the
+   * Use when this is useful to prevent running jobs that were scheduled too far in the
    * past.
    *
    * **Details**

package/src/unstable/cluster/ClusterError.ts

@@ -1,24 +1,45 @@
 /**
- * The `ClusterError` module defines the typed error values used by the
- * unstable cluster runtime when routing messages to entities, coordinating
- * runners, and persisting mailbox work.
+ * The `ClusterError` module defines the tagged, schema-backed error values used
+ * by the unstable cluster runtime. These errors describe failures at routing,
+ * runner membership, serialization, persistence, mailbox capacity, and duplicate
+ * envelope boundaries.
  *
- * These errors are useful when implementing cluster transports, runner
- * supervision, mailbox storage, and entity request handling. They make common
- * distributed-system failures explicit: a message may reach a runner that no
- * longer owns the entity, a runner may be unavailable or unregistered, a
- * payload may fail to decode, persistence may fail, a mailbox may be at
- * capacity, or an envelope may already be in progress.
+ * **Mental model**
+ *
+ * - Cluster operations fail with typed values so callers can distinguish retry,
+ *   supervision, decoding, and storage failures.
+ * - Each error has a stable `_tag` and schema representation for transport or
+ *   storage boundaries.
+ * - Static `is` helpers recognize errors from this module at runtime, and
+ *   `refail` helpers map lower-level failures into cluster errors.
+ *
+ * **Common tasks**
+ *
+ * - Report wrong-runner delivery with {@link EntityNotAssignedToRunner}.
+ * - Surface runner membership and liveness failures with
+ *   {@link RunnerNotRegistered} or {@link RunnerUnavailable}.
+ * - Convert encode and decode failures to {@link MalformedMessage}.
+ * - Preserve storage failures as {@link PersistenceError}.
+ * - Signal mailbox pressure with {@link MailboxFull}.
+ * - Reject duplicate in-flight envelopes with
+ *   {@link AlreadyProcessingMessage}.
  *
  * **Gotchas**
  *
- * - Entity ownership and runner availability can change while messages are in
- *   flight, so routing errors should generally be treated as retryable or
- *   recoverable by higher-level cluster logic.
- * - `MalformedMessage` points to a schema/serialization boundary failure,
- *   while `PersistenceError` preserves failures from durable mailbox storage.
- * - `AlreadyProcessingMessage` protects an entity mailbox from processing the
- *   same envelope concurrently.
+ * - Ownership and health can change while a message is in flight, so routing
+ *   and availability errors are often retryable by higher-level cluster logic.
+ * - {@link MalformedMessage} means the payload crossed a schema or
+ *   serialization boundary incorrectly; it is not an entity handler failure.
+ * - {@link AlreadyProcessingMessage} is per-envelope protection, not a general
+ *   entity lock.
+ *
+ * **See also**
+ *
+ * - {@link EntityNotAssignedToRunner}, {@link RunnerUnavailable}, and
+ *   {@link RunnerNotRegistered} for routing and membership failures.
+ * - {@link MalformedMessage} and {@link PersistenceError} for boundary
+ *   failures.
+ * - {@link MailboxFull} and {@link AlreadyProcessingMessage} for mailbox state.
  *
  * @since 4.0.0
  */
@@ -34,7 +55,7 @@ const TypeId = "~effect/cluster/ClusterError"
 
 /**
  * Represents an error that occurs when a Runner receives a message for an entity
- * that it is not assigned to it.
+ * that is not assigned to the receiving runner.
  *
  * @category errors
  * @since 4.0.0
@@ -63,8 +84,13 @@ export class EntityNotAssignedToRunner
 }
 
 /**
- * Represents an error that occurs when a message fails to be properly
- * deserialized by an entity.
+ * Represents an error that occurs when a message fails at a schema
+ * serialization or deserialization boundary.
+ *
+ * **Details**
+ *
+ * `cause` carries the underlying failure. `refail` maps encode and decode
+ * failures into `MalformedMessage` values.
  *
  * @category errors
  * @since 4.0.0
@@ -176,7 +202,16 @@ export class RunnerUnavailable extends Schema.ErrorClass<RunnerUnavailable>(`${T
 }
 
 /**
- * Represents an error that occurs when the entities mailbox is full.
+ * Represents an error that occurs when the entity mailbox is full.
+ *
+ * **Details**
+ *
+ * Carries the `address` whose bounded mailbox is at capacity.
+ *
+ * **Gotchas**
+ *
+ * Volatile requests fail immediately. Persisted or durable messages are retried
+ * or resumed from storage when the mailbox is full.
  *
  * @category errors
  * @since 4.0.0
@@ -203,8 +238,12 @@ export class MailboxFull extends Schema.ErrorClass<MailboxFull>(`${TypeId}/Mailb
 }
 
 /**
- * Represents an error that occurs when the entity is already processing a
- * request.
+ * Represents an error that occurs when the same request envelope is already
+ * being processed.
+ *
+ * **Details**
+ *
+ * Carries the `address` and `envelopeId` for the affected request envelope.
  *
  * @category errors
  * @since 4.0.0

package/src/unstable/cluster/ClusterMetrics.ts

@@ -29,6 +29,19 @@ import * as Metric from "../../Metric.ts"
  * Gauge tracking the number of active entity instances for each entity type on
  * the current runner.
  *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_entities`, updated with the entity type as
+ * a metric tag.
+ *
+ * **Gotchas**
+ *
+ * This gauge is runner-local and sampled by the entity manager loop. Aggregate
+ * across runners and expect up to roughly one polling interval of lag.
+ *
+ * @see {@link singletons} for singleton process counts on the current runner
+ * @see {@link shards} for shard ownership on the current runner
+ *
  * @category metrics
  * @since 4.0.0
  */
@@ -46,6 +59,16 @@ export const singletons = Metric.gauge("effect_cluster_singletons", { bigint: tr
 /**
  * Gauge tracking the number of registered cluster runners.
  *
+ * **When to use**
+ *
+ * Use to monitor the registered runners currently known to the cluster runtime.
+ *
+ * **Gotchas**
+ *
+ * The value can lag briefly during membership changes or failure detection.
+ *
+ * @see {@link runnersHealthy} for the healthy-runner subset
+ *
  * @category metrics
  * @since 4.0.0
  */
@@ -54,6 +77,21 @@ export const runners = Metric.gauge("effect_cluster_runners", { bigint: true })
 /**
  * Gauge tracking the number of cluster runners currently considered healthy.
  *
+ * **When to use**
+ *
+ * Use to monitor the healthy subset of registered cluster runners.
+ *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_runners_healthy`.
+ *
+ * **Gotchas**
+ *
+ * The value reflects the runtime's health-check view and can lag during
+ * membership changes or failure detection.
+ *
+ * @see {@link runners} for the total registered-runner gauge
+ *
  * @category metrics
  * @since 4.0.0
  */
@@ -62,6 +100,21 @@ export const runnersHealthy = Metric.gauge("effect_cluster_runners_healthy", { b
 /**
  * Gauge tracking the number of shards currently acquired by the current runner.
  *
+ * **When to use**
+ *
+ * Use to observe shard ownership held by the current runner during startup,
+ * rebalancing, or failover.
+ *
+ * **Details**
+ *
+ * Bigint gauge named `effect_cluster_shards`, updated from the sharding
+ * acquisition loop using the current acquired shard count.
+ *
+ * **Gotchas**
+ *
+ * This is runner-local, not a cluster-wide shard total. Aggregate per-runner
+ * values carefully.
+ *
  * @category metrics
  * @since 4.0.0
  */