effect 4.0.0-beta.67 → 4.0.0-beta.68

package/src/unstable/cli/Param.ts

@@ -24,7 +24,7 @@
  *   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.
- * @internal
+ *
  * @since 4.0.0
  */
 import * as Config from "../../Config.ts"
@@ -280,7 +280,7 @@ const Proto = {
  * **Example** (Checking for params)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -302,7 +302,7 @@ export const isParam = (u: unknown): u is Param<any, ParamKind> => Predicate.has
  * **Example** (Checking for single params)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -366,7 +366,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
  * **Example** (Creating string parameters)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -398,7 +398,7 @@ export const string = <const Kind extends ParamKind>(
  * **Example** (Creating boolean parameters)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -431,7 +431,7 @@ export const boolean = <const Kind extends ParamKind>(
  * **Example** (Creating integer parameters)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -463,7 +463,7 @@ export const integer = <const Kind extends ParamKind>(
  * **Example** (Creating float parameters)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -495,7 +495,7 @@ export const float = <const Kind extends ParamKind>(
  * **Example** (Creating date parameters)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -529,7 +529,7 @@ export const date = <const Kind extends ParamKind>(
  * **Example** (Creating valued choices)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -569,7 +569,7 @@ export const choiceWithValue = <
  * **Example** (Creating string choices)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -598,7 +598,7 @@ export const choice = <
  * **Example** (Creating path parameters)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -644,7 +644,7 @@ export const path = <Kind extends ParamKind>(
  * **Example** (Creating directory parameters)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -682,7 +682,7 @@ export const directory = <Kind extends ParamKind>(
  * **Example** (Creating file parameters)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -718,7 +718,7 @@ export const file = <Kind extends ParamKind>(
  * **Example** (Creating redacted parameters)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -750,7 +750,7 @@ export const redacted = <Kind extends ParamKind>(
  * **Example** (Reading file text)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -782,7 +782,7 @@ export const fileText = <Kind extends ParamKind>(kind: Kind, name: string): Para
  * **Example** (Parsing file contents)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -817,7 +817,7 @@ export const fileParse = <Kind extends ParamKind>(
  *
  * ```ts
  * import { Schema } from "effect"
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  * // @internal - this module is not exported publicly
  *
  * // Parse JSON config file
@@ -863,7 +863,7 @@ export const fileSchema = <Kind extends ParamKind, A>(
  * **Example** (Parsing key-value pairs)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -901,7 +901,7 @@ export const keyValuePair = <Kind extends ParamKind>(
  * **Example** (Creating sentinel parameters)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -938,7 +938,7 @@ const FLAG_DASH_REGEXP = /^-+/
  * **Example** (Adding parameter aliases)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -970,7 +970,7 @@ export const withAlias: {
    * **Example** (Adding parameter aliases)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1002,7 +1002,7 @@ export const withAlias: {
    * **Example** (Adding parameter aliases)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1039,7 +1039,7 @@ export const withAlias: {
  * **Example** (Adding help descriptions)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1062,7 +1062,7 @@ export const withDescription: {
    * **Example** (Adding help descriptions)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1085,7 +1085,7 @@ export const withDescription: {
    * **Example** (Adding help descriptions)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1113,7 +1113,7 @@ export const withDescription: {
  * **Example** (Mapping parsed values)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1132,7 +1132,7 @@ export const map: {
    * **Example** (Mapping parsed values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1151,7 +1151,7 @@ export const map: {
    * **Example** (Mapping parsed values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1197,11 +1197,10 @@ const transform = <Kind extends ParamKind, A, B>(
  * **Example** (Mapping parsed values effectfully)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Effect } from "effect"
+ * import { CliError, Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
- * import { Effect } from "effect"
- * import { CliError } from "effect/unstable/cli"
  *
  * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
  *   Param.mapEffect((email) =>
@@ -1229,11 +1228,10 @@ export const mapEffect: {
    * **Example** (Mapping parsed values effectfully)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Effect } from "effect"
+   * import { CliError, Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
-   * import { Effect } from "effect"
-   * import { CliError } from "effect/unstable/cli"
    *
    * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
    *   Param.mapEffect((email) =>
@@ -1261,11 +1259,10 @@ export const mapEffect: {
    * **Example** (Mapping parsed values effectfully)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Effect } from "effect"
+   * import { CliError, Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
-   * import { Effect } from "effect"
-   * import { CliError } from "effect/unstable/cli"
    *
    * const validatedEmail = Param.string(Param.flagKind, "email").pipe(
    *   Param.mapEffect((email) =>
@@ -1310,7 +1307,7 @@ export const mapEffect: {
  * **Example** (Mapping thrown errors)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1334,7 +1331,7 @@ export const mapTryCatch: {
    * **Example** (Mapping thrown errors)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1358,7 +1355,7 @@ export const mapTryCatch: {
    * **Example** (Mapping thrown errors)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1414,7 +1411,7 @@ export const mapTryCatch: {
  * **Example** (Making parameters optional)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // Create an optional port option
  * // - When not provided: returns Option.none()
@@ -1468,7 +1465,7 @@ export const optional = <Kind extends ParamKind, A>(
  * **Example** (Providing default values)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1498,7 +1495,7 @@ export const withDefault: {
    * **Example** (Providing default values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1528,7 +1525,7 @@ export const withDefault: {
    * **Example** (Providing default values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1686,7 +1683,7 @@ export type VariadicParamOptions = {
  * **Example** (Accepting multiple values)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1740,7 +1737,7 @@ export const variadic = <Kind extends ParamKind, A>(
  * **Example** (Bounding repeated values)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1775,7 +1772,7 @@ export const between: {
    * **Example** (Bounding repeated values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1810,7 +1807,7 @@ export const between: {
    * **Example** (Bounding repeated values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1856,7 +1853,7 @@ export const between: {
  * **Example** (Limiting repeated values)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1882,7 +1879,7 @@ export const atMost: {
    * **Example** (Limiting repeated values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1908,7 +1905,7 @@ export const atMost: {
    * **Example** (Limiting repeated values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1941,7 +1938,7 @@ export const atMost: {
  * **Example** (Requiring repeated values)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -1968,7 +1965,7 @@ export const atLeast: {
    * **Example** (Requiring repeated values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -1995,7 +1992,7 @@ export const atLeast: {
    * **Example** (Requiring repeated values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2030,7 +2027,7 @@ export const atLeast: {
  *
  * ```ts
  * import { Option } from "effect"
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  * // @internal - this module is not exported publicly
  *
  * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -2055,7 +2052,7 @@ export const filterMap: {
    *
    * ```ts
    * import { Option } from "effect"
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    * // @internal - this module is not exported publicly
    *
    * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -2080,7 +2077,7 @@ export const filterMap: {
    *
    * ```ts
    * import { Option } from "effect"
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    * // @internal - this module is not exported publicly
    *
    * const positiveInt = Param.integer(Param.flagKind, "count").pipe(
@@ -2127,7 +2124,7 @@ export const filterMap: {
  * **Example** (Filtering parsed values)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -2149,7 +2146,7 @@ export const filter: {
    * **Example** (Filtering parsed values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2171,7 +2168,7 @@ export const filter: {
    * **Example** (Filtering parsed values)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2206,7 +2203,7 @@ export const filter: {
  * **Example** (Setting metavars)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -2232,7 +2229,7 @@ export const withMetavar: {
    * **Example** (Setting metavars)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2258,7 +2255,7 @@ export const withMetavar: {
    * **Example** (Setting metavars)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2292,7 +2289,7 @@ export const withMetavar: {
  *
  * ```ts
  * import { Schema } from "effect"
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  * // @internal - this module is not exported publicly
  *
  * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -2317,7 +2314,7 @@ export const withSchema: {
    *
    * ```ts
    * import { Schema } from "effect"
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    * // @internal - this module is not exported publicly
    *
    * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -2342,7 +2339,7 @@ export const withSchema: {
    *
    * ```ts
    * import { Schema } from "effect"
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    * // @internal - this module is not exported publicly
    *
    * const isEmail = Schema.isPattern(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
@@ -2383,7 +2380,7 @@ export const withSchema: {
  * **Example** (Falling back to another parameter)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -2402,7 +2399,7 @@ export const orElse: {
    * **Example** (Falling back to another parameter)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2421,7 +2418,7 @@ export const orElse: {
    * **Example** (Falling back to another parameter)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2453,7 +2450,7 @@ export const orElse: {
  * **Example** (Returning fallback results)
  *
  * ```ts
- * import * as Param from "effect/unstable/cli/Param"
+ * import { Param } from "effect/unstable/cli"
  *
  * // @internal - this module is not exported publicly
  *
@@ -2477,7 +2474,7 @@ export const orElseResult: {
    * **Example** (Returning fallback results)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *
@@ -2501,7 +2498,7 @@ export const orElseResult: {
    * **Example** (Returning fallback results)
    *
    * ```ts
-   * import * as Param from "effect/unstable/cli/Param"
+   * import { Param } from "effect/unstable/cli"
    *
    * // @internal - this module is not exported publicly
    *

package/src/unstable/cli/Primitive.ts

@@ -715,7 +715,7 @@ export const none: Primitive<never> = makePrimitive("None", () => Effect.fail("T
  * console.log(Primitive.getTypeName(logLevelChoice)) // "choice"
  * ```
  *
- * @category utilities
+ * @category utils
  * @since 4.0.0
  */
 export const getTypeName = <A>(primitive: Primitive<A>): string => {

package/src/unstable/cli/Prompt.ts

@@ -117,10 +117,6 @@ export interface ActionDefinition extends Data.TaggedEnum.WithGenerics<2> {
 export interface Handlers<State, Output> {
   /**
    * A function that is called to render the current frame of the `Prompt`.
-   *
-   * @param state The current state of the prompt.
-   * @param action The `Prompt.Action` for the current frame.
-   * @returns An ANSI escape code sequence to display in the terminal screen.
    */
   readonly render: (
     state: State,
@@ -129,10 +125,6 @@ export interface Handlers<State, Output> {
   /**
    * A function that is called to process user input and determine the next
    * `Prompt.Action` that should be taken.
-   *
-   * @param input The input the user provided for the current frame.
-   * @param state The current state of the prompt.
-   * @returns The next `Prompt.Action` that should be taken.
    */
   readonly process: (
     input: Terminal.UserInput,
@@ -141,10 +133,6 @@ export interface Handlers<State, Output> {
   /**
    * A function that is called to clear the terminal screen before rendering
    * the next frame of the `Prompt`.
-   *
-   * @param action The `Prompt.Action` for the current frame.
-   * @param columns The current number of columns available in the `Terminal`.
-   * @returns An ANSI escape code sequence used to clear the terminal screen.
    */
   readonly clear: (
     state: State,
@@ -598,6 +586,7 @@ export declare namespace All {
    *
    * The resulting prompt produces an array of each prompt's output value.
    *
+   * @category utility types
    * @since 4.0.0
    */
   export type ReturnIterable<T extends Iterable<Any>> = [T] extends [Iterable<Prompt<infer A>>] ? Prompt<Array<A>>
@@ -607,6 +596,7 @@ export declare namespace All {
    * Computes the prompt returned by `Prompt.all` for a readonly tuple or array
    * of prompts, preserving tuple positions in the output type.
    *
+   * @category utility types
    * @since 4.0.0
    */
   export type ReturnTuple<T extends ReadonlyArray<unknown>> = Prompt<
@@ -618,6 +608,7 @@ export declare namespace All {
    * Computes the prompt returned by `Prompt.all` for a record of prompts,
    * preserving the record keys and replacing each prompt with its output type.
    *
+   * @category utility types
    * @since 4.0.0
    */
   export type ReturnObject<T> = [T] extends [{ [K: string]: Any }] ? Prompt<
@@ -631,6 +622,7 @@ export declare namespace All {
    * Computes the return prompt type for `Prompt.all` based on the input
    * structure.
    *
+   * @category constructors
    * @since 4.0.0
    */
   export type Return<
@@ -648,7 +640,7 @@ export declare namespace All {
  * Supports either a tuple / iterable of prompts or a record / struct of prompts
  * as an argument.
  *
- * **Example**
+ * **Example** (Collecting prompt results)
  *
  * ```ts
  * import { Effect } from "effect"
@@ -1086,7 +1078,7 @@ export const select = <const A>(options: SelectOptions<A>): Prompt<A> => {
 /**
  * Creates a prompt that lets users filter select choices by typing.
  *
- * **Example**
+ * **Example** (Filtering choices with autocomplete)
  *
  * ```ts
  * import { Prompt } from "effect/unstable/cli"