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

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"
@@ -205,6 +205,7 @@ export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
   readonly aliases: ReadonlyArray<string>
   readonly primitiveType: Primitive.Primitive<A>
   readonly typeName?: string | undefined
+  readonly hidden: boolean
 }
 
 /**
@@ -280,7 +281,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 +303,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
  *
@@ -346,6 +347,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
   readonly typeName?: string | undefined
   readonly description?: Option.Option<string> | undefined
   readonly aliases?: ReadonlyArray<string> | undefined
+  readonly hidden?: boolean | undefined
 }): Single<Kind, A> => {
   const parse: Parse<A> = (args) =>
     params.kind === argumentKind
@@ -356,6 +358,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
     ...params,
     description: params.description ?? Option.none(),
     aliases: params.aliases ?? [],
+    hidden: params.hidden ?? false,
     parse
   })
 }
@@ -366,7 +369,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 +401,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 +434,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 +466,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 +498,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 +532,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 +572,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 +601,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 +647,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 +685,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 +721,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 +753,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 +785,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 +820,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 +866,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 +904,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 +941,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 +973,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 +1005,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 +1042,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 +1065,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 +1088,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
    *
@@ -1107,13 +1110,42 @@ export const withDescription: {
     }))
 })
 
+/**
+ * Hides a parameter from generated help output and completions while keeping
+ * it parseable on the command line.
+ *
+ * Useful for experimental, internal, or deprecated flags that should be
+ * accepted but not advertised.
+ *
+ * **Example** (Hiding a flag from help)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // @internal - this module is not exported publicly
+ *
+ * const experimental = Param.boolean(Param.flagKind, "experimental-foo").pipe(
+ *   Param.withHidden
+ * )
+ * ```
+ *
+ * @category metadata
+ * @since 4.0.0
+ */
+export const withHidden = <Kind extends ParamKind, A>(self: Param<Kind, A>): Param<Kind, A> =>
+  transformSingle(self, <X>(single: Single<Kind, X>) =>
+    makeSingle({
+      ...single,
+      hidden: true
+    }))
+
 /**
  * Transforms the parsed value of an option using a mapping function.
  *
  * **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 +1164,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 +1183,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 +1229,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 +1260,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 +1291,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 +1339,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 +1363,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 +1387,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 +1443,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 +1497,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 +1527,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 +1557,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 +1715,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 +1769,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 +1804,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 +1839,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 +1885,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 +1911,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 +1937,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 +1970,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 +1997,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 +2024,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 +2059,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 +2084,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 +2109,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 +2156,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 +2178,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 +2200,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 +2235,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 +2261,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 +2287,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 +2321,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 +2346,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 +2371,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 +2412,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 +2431,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 +2450,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 +2482,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 +2506,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 +2530,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 => {