effect 4.0.0-beta.31 → 4.0.0-beta.32

package/src/internal/dateTime.ts

@@ -9,11 +9,11 @@ import type { LazyArg } from "../Function.ts"
 import { dual } from "../Function.ts"
 import * as Hash from "../Hash.ts"
 import * as Inspectable from "../Inspectable.ts"
+import * as Option from "../Option.ts"
 import * as order from "../Order.ts"
 import { pipeArguments } from "../Pipeable.ts"
 import * as Predicate from "../Predicate.ts"
 import type { Mutable } from "../Types.ts"
-import * as UndefinedOr from "../UndefinedOr.ts"
 import * as effect from "./effect.ts"
 
 /** @internal */
@@ -264,10 +264,10 @@ export const makeZonedUnsafe = (input: DateTime.DateTime.Input, options?: {
     zone = zoneMakeOffset(timeZoneOption)
   } else {
     const parsedZone = zoneFromString(timeZoneOption)
-    if (parsedZone === undefined) {
+    if (Option.isNone(parsedZone)) {
       throw new IllegalArgumentError(`Invalid time zone: ${timeZoneOption}`)
     }
-    zone = parsedZone
+    zone = parsedZone.value
   }
   if (options?.adjustForTimeZone !== true) {
     return makeZonedProto(self.epochMilliseconds, zone, self.partsUtc)
@@ -283,20 +283,20 @@ export const makeZoned: (
     readonly adjustForTimeZone?: boolean | undefined
     readonly disambiguation?: DateTime.Disambiguation | undefined
   }
-) => DateTime.Zoned | undefined = UndefinedOr.liftThrowable(makeZonedUnsafe)
+) => Option.Option<DateTime.Zoned> = Option.liftThrowable(makeZonedUnsafe)
 
 /** @internal */
-export const make: <A extends DateTime.DateTime.Input>(input: A) => DateTime.DateTime.PreserveZone<A> | undefined =
-  UndefinedOr.liftThrowable(makeUnsafe)
+export const make: <A extends DateTime.DateTime.Input>(input: A) => Option.Option<DateTime.DateTime.PreserveZone<A>> =
+  Option.liftThrowable(makeUnsafe)
 
 const zonedStringRegExp = /^(.{17,35})\[(.+)\]$/
 
 /** @internal */
-export const makeZonedFromString = (input: string): DateTime.Zoned | undefined => {
+export const makeZonedFromString = (input: string): Option.Option<DateTime.Zoned> => {
   const match = zonedStringRegExp.exec(input)
   if (match === null) {
     const offset = parseOffset(input)
-    return offset !== null ? makeZoned(input, { timeZone: offset }) : undefined
+    return offset !== null ? makeZoned(input, { timeZone: offset }) : Option.none()
   }
   const [, isoString, timeZone] = match
   return makeZoned(isoString, { timeZone })
@@ -402,7 +402,7 @@ export const zoneMakeOffset = (offset: number): DateTime.TimeZone.Offset => {
 }
 
 /** @internal */
-export const zoneMakeNamed: (zoneId: string) => DateTime.TimeZone.Named | undefined = UndefinedOr.liftThrowable(
+export const zoneMakeNamed: (zoneId: string) => Option.Option<DateTime.TimeZone.Named> = Option.liftThrowable(
   zoneMakeNamedUnsafe
 )
 
@@ -420,10 +420,10 @@ export const zoneMakeLocal = (): DateTime.TimeZone.Named =>
 const offsetZoneRegExp = /^(?:GMT|[+-])/
 
 /** @internal */
-export const zoneFromString = (zone: string): DateTime.TimeZone | undefined => {
+export const zoneFromString = (zone: string): Option.Option<DateTime.TimeZone> => {
   if (offsetZoneRegExp.test(zone)) {
     const offset = parseOffset(zone)
-    return offset === null ? undefined : zoneMakeOffset(offset)
+    return offset === null ? Option.none() : Option.some(zoneMakeOffset(offset))
   }
   return zoneMakeNamed(zone)
 }
@@ -441,17 +441,17 @@ export const setZoneNamed: {
   (zoneId: string, options?: {
     readonly adjustForTimeZone?: boolean | undefined
     readonly disambiguation?: DateTime.Disambiguation | undefined
-  }): (self: DateTime.DateTime) => DateTime.Zoned | undefined
+  }): (self: DateTime.DateTime) => Option.Option<DateTime.Zoned>
   (self: DateTime.DateTime, zoneId: string, options?: {
     readonly adjustForTimeZone?: boolean | undefined
     readonly disambiguation?: DateTime.Disambiguation | undefined
-  }): DateTime.Zoned | undefined
+  }): Option.Option<DateTime.Zoned>
 } = dual(
   isDateTimeArgs,
   (self: DateTime.DateTime, zoneId: string, options?: {
     readonly adjustForTimeZone?: boolean | undefined
     readonly disambiguation?: DateTime.Disambiguation | undefined
-  }): DateTime.Zoned | undefined => UndefinedOr.map(zoneMakeNamed(zoneId), (zone) => setZone(self, zone, options))
+  }): Option.Option<DateTime.Zoned> => Option.map(zoneMakeNamed(zoneId), (zone) => setZone(self, zone, options))
 )
 
 /** @internal */

package/src/internal/effect.ts

@@ -540,6 +540,11 @@ export class FiberImpl<A = any, E = any> implements Fiber.Fiber<A, E> {
   maxOpsBeforeYield!: number
   currentPreventYield!: boolean
 
+  _dispatcher: Scheduler.SchedulerDispatcher | undefined = undefined
+  get currentDispatcher(): Scheduler.SchedulerDispatcher {
+    return this._dispatcher ??= this.currentScheduler.makeDispatcher()
+  }
+
   getRef<X>(ref: ServiceMap.Reference<X>): X {
     return ServiceMap.getReferenceUnsafe(this.services, ref)
   }
@@ -675,7 +680,11 @@ export class FiberImpl<A = any, E = any> implements Fiber.Fiber<A, E> {
   }
   setServices(services: ServiceMap.ServiceMap<never>): void {
     this.services = services
-    this.currentScheduler = this.getRef(Scheduler.Scheduler)
+    const scheduler = this.getRef(Scheduler.Scheduler)
+    if (scheduler !== this.currentScheduler) {
+      this.currentScheduler = scheduler
+      this._dispatcher = undefined
+    }
     this.currentSpan = services.mapUnsafe.get(Tracer.ParentSpanKey)
     this.currentLogLevel = this.getRef(CurrentLogLevel)
     this.minimumLogLevel = this.getRef(MinimumLogLevel)
@@ -903,7 +912,7 @@ export const yieldNowWith: (priority?: number) => Effect.Effect<void> = makePrim
   op: "Yield",
   [evaluate](fiber) {
     let resumed = false
-    fiber.currentScheduler.scheduleTask(() => {
+    fiber.currentDispatcher.scheduleTask(() => {
       if (resumed) return
       fiber.evaluate(exitVoid as any)
     }, this[args] ?? 0)
@@ -4849,7 +4858,7 @@ export const forkUnsafe = <FA, FE, A, E, R>(
   if (immediate) {
     child.evaluate(effect as any)
   } else {
-    parent.currentScheduler.scheduleTask(() => child.evaluate(effect as any), 0)
+    parent.currentDispatcher.scheduleTask(() => child.evaluate(effect as any), 0)
   }
   if (!daemon && !child._exit) {
     parent.children().add(child)
@@ -4990,10 +4999,8 @@ export const runForkWith = <R>(services: ServiceMap.ServiceMap<R>) =>
   effect: Effect.Effect<A, E, R>,
   options?: Effect.RunOptions | undefined
 ): Fiber.Fiber<A, E> => {
-  const scheduler = options?.scheduler ||
-    (!services.mapUnsafe.has(Scheduler.Scheduler.key) && new Scheduler.MixedScheduler())
   const fiber = new FiberImpl<A, E>(
-    scheduler ? ServiceMap.add(services, Scheduler.Scheduler, scheduler) : services,
+    options?.scheduler ? ServiceMap.add(services, Scheduler.Scheduler, options.scheduler) : services,
     options?.uninterruptible !== true
   )
   fiber.evaluate(effect as any)
@@ -5113,7 +5120,7 @@ export const runSyncExitWith = <R>(services: ServiceMap.ServiceMap<R>) => {
     if (effectIsExit(effect)) return effect
     const scheduler = new Scheduler.MixedScheduler("sync")
     const fiber = runFork(effect, { scheduler })
-    scheduler.flush()
+    fiber.currentDispatcher?.flush()
     return (fiber as FiberImpl<A, E>)._exit ?? exitDie(fiber)
   }
 }
@@ -5136,108 +5143,6 @@ export const runSyncWith = <R>(services: ServiceMap.ServiceMap<R>) => {
 /** @internal */
 export const runSync: <A, E>(effect: Effect.Effect<A, E>) => A = runSyncWith(ServiceMap.empty())
 
-// ----------------------------------------------------------------------------
-// Semaphore
-// ----------------------------------------------------------------------------
-
-/** @internal */
-class Semaphore {
-  public waiters = new Set<() => void>()
-  public taken = 0
-  public permits: number
-
-  constructor(permits: number) {
-    this.permits = permits
-  }
-
-  get free() {
-    return this.permits - this.taken
-  }
-
-  readonly take = (n: number): Effect.Effect<number> => {
-    const take: Effect.Effect<number> = suspend(() => {
-      if (this.free < n) {
-        return callback((resume) => {
-          if (this.free >= n) return resume(take)
-          const observer = () => {
-            if (this.free < n) return
-            this.waiters.delete(observer)
-            resume(take)
-          }
-          this.waiters.add(observer)
-          return sync(() => {
-            this.waiters.delete(observer)
-          })
-        })
-      }
-      this.taken += n
-      return succeed(n)
-    })
-    return take
-  }
-
-  updateTakenUnsafe(fiber: Fiber.Fiber<any, any>, f: (n: number) => number): Effect.Effect<number> {
-    this.taken = f(this.taken)
-    if (this.waiters.size > 0) {
-      fiber.currentScheduler.scheduleTask(() => {
-        const iter = this.waiters.values()
-        let item = iter.next()
-        while (item.done === false && this.free > 0) {
-          item.value()
-          item = iter.next()
-        }
-      }, 0)
-    }
-    return succeed(this.free)
-  }
-
-  updateTaken(f: (n: number) => number): Effect.Effect<number> {
-    return withFiber((fiber) => this.updateTakenUnsafe(fiber, f))
-  }
-
-  readonly resize = (permits: number) =>
-    asVoid(
-      withFiber((fiber) => {
-        this.permits = permits
-        if (this.free < 0) {
-          return void_
-        }
-        return this.updateTakenUnsafe(fiber, (taken) => taken)
-      })
-    )
-
-  readonly release = (n: number): Effect.Effect<number> => this.updateTaken((taken) => taken - n)
-
-  readonly releaseAll: Effect.Effect<number> = this.updateTaken((_) => 0)
-
-  readonly withPermits = (n: number) => <A, E, R>(self: Effect.Effect<A, E, R>) =>
-    uninterruptibleMask((restore) =>
-      flatMap(
-        restore(this.take(n)),
-        (permits) => onExitPrimitive(restore(self), () => this.release(permits), true)
-      )
-    )
-
-  readonly withPermit = this.withPermits(1)
-
-  readonly withPermitsIfAvailable = (n: number) => <A, E, R>(self: Effect.Effect<A, E, R>) =>
-    uninterruptibleMask((restore) =>
-      suspend(() => {
-        if (this.free < n) {
-          return succeedNone
-        }
-        this.taken += n
-        return ensuring(restore(asSome(self)), this.release(n))
-      })
-    )
-}
-
-/** @internal */
-export const makeSemaphoreUnsafe = (permits: number): Semaphore => new Semaphore(permits)
-
-/** @internal */
-export const makeSemaphore = (permits: number) => sync(() => makeSemaphoreUnsafe(permits))
-
 const succeedTrue = succeed(true)
 const succeedFalse = succeed(false)
 
@@ -5255,7 +5160,7 @@ class Latch implements _Latch.Latch {
       return succeedTrue
     }
     this.scheduled = true
-    fiber.currentScheduler.scheduleTask(this.flushWaiters, 0)
+    fiber.currentDispatcher.scheduleTask(this.flushWaiters, 0)
     return succeedTrue
   }
   private flushWaiters = () => {
@@ -5297,7 +5202,7 @@ class Latch implements _Latch.Latch {
     return true
   }
   close = sync(() => this.closeUnsafe())
-  whenOpen = <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> => andThen(this.await, self)
+  whenOpen = <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> => flatMap(this.await, () => self)
 }
 
 /** @internal */
@@ -5360,16 +5265,15 @@ const NoopSpanProto: Omit<Tracer.Span, "parent" | "name" | "annotations" | "leve
 /** @internal */
 export const noopSpan = (options: {
   readonly name: string
-  readonly parent: Tracer.AnySpan | undefined
+  readonly parent: Option.Option<Tracer.AnySpan>
   readonly annotations: ServiceMap.ServiceMap<never>
 }): Tracer.Span => Object.assign(Object.create(NoopSpanProto), options)
 
-const filterDisablePropagation = (span: Tracer.AnySpan | undefined): Tracer.AnySpan | undefined => {
-  if (span) {
-    return ServiceMap.get(span.annotations, Tracer.DisablePropagation)
-      ? span._tag === "Span" ? filterDisablePropagation(span.parent) : undefined
-      : span
-  }
+const filterDisablePropagation = (span: Tracer.AnySpan | undefined): Option.Option<Tracer.AnySpan> => {
+  if (!span) return Option.none()
+  return ServiceMap.get(span.annotations, Tracer.DisablePropagation)
+    ? span._tag === "Span" ? filterDisablePropagation(Option.getOrUndefined(span.parent)) : Option.none()
+    : Option.some(span)
 }
 
 /** @internal */
@@ -5380,7 +5284,11 @@ export const makeSpanUnsafe = <XA, XE>(
 ) => {
   const disablePropagation = !fiber.getRef(TracerEnabled) ||
     (options?.annotations && ServiceMap.get(options.annotations, Tracer.DisablePropagation))
-  const parent = options?.parent ?? (options?.root ? undefined : filterDisablePropagation(fiber.currentSpan))
+  const parent = options?.parent !== undefined
+    ? Option.some(options.parent)
+    : options?.root
+    ? Option.none<Tracer.AnySpan>()
+    : filterDisablePropagation(fiber.currentSpan)
 
   let span: Tracer.Span
 
@@ -5413,9 +5321,9 @@ export const makeSpanUnsafe = <XA, XE>(
       links,
       startTime: timingEnabled ? clock.currentTimeNanosUnsafe() : 0n,
       kind: options?.kind ?? "internal",
-      root: options?.root ?? options?.parent === undefined,
+      root: options?.root ?? Option.isNone(parent),
       sampled: options?.sampled ??
-        (parent?.sampled === false
+        (Option.isSome(parent) && parent.value.sampled === false
           ? false
           : !isLogLevelGreaterThan(fiber.getRef(Tracer.MinimumTraceLevel), level))
     })

package/src/internal/hashMap.ts

@@ -1271,14 +1271,15 @@ export const filterMap = dual<
 
 /** @internal */
 export const findFirst = dual<
-  <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean) => (self: HashMap<K, A>) => [K, A] | undefined,
-  <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean) => [K, A] | undefined
+  <K, A>(predicate: (a: NoInfer<A>, k: K) => boolean) => (self: HashMap<K, A>) => Option.Option<[K, A]>,
+  <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean) => Option.Option<[K, A]>
 >(2, <K, A>(self: HashMap<K, A>, predicate: (a: A, k: K) => boolean) => {
   for (const [key, value] of self) {
     if (predicate(value, key)) {
-      return [key, value]
+      return Option.some([key, value])
     }
   }
+  return Option.none()
 })
 
 /** @internal */

package/src/internal/option.ts

@@ -45,10 +45,17 @@ const SomeProto = Object.assign(Object.create(CommonProto), {
   }
 })
 
+Object.defineProperty(SomeProto, "valueOrUndefined", {
+  get() {
+    return this.value
+  }
+})
+
 const NoneHash = Hash.hash("None")
 const NoneProto = Object.assign(Object.create(CommonProto), {
   _tag: "None",
   _op: "None",
+  valueOrUndefined: undefined,
   [Equal.symbol]<A>(this: Option.None<A>, that: unknown): boolean {
     return isOption(that) && isNone(that)
   },

package/src/internal/trie.ts

@@ -682,19 +682,19 @@ export const modify = dual<
 
 /** @internal */
 export const longestPrefixOf = dual<
-  (key: string) => <V>(self: TR.Trie<V>) => [string, V] | undefined,
-  <V>(self: TR.Trie<V>, key: string) => [string, V] | undefined
+  (key: string) => <V>(self: TR.Trie<V>) => Option.Option<[string, V]>,
+  <V>(self: TR.Trie<V>, key: string) => Option.Option<[string, V]>
 >(
   2,
-  <V>(self: TR.Trie<V>, key: string): [string, V] | undefined => {
+  <V>(self: TR.Trie<V>, key: string): Option.Option<[string, V]> => {
     let n: Node<V> | undefined = (self as TrieImpl<V>)._root
-    if (n === undefined || key.length === 0) return undefined
-    let longestPrefixNode: [string, V] | undefined = undefined
+    if (n === undefined || key.length === 0) return Option.none()
+    let longestPrefixNode: Option.Option<[string, V]> = Option.none()
     let cIndex = 0
     while (cIndex < key.length) {
       const c = key[cIndex]
       if (n.value !== undefined) {
-        longestPrefixNode = [key.slice(0, cIndex + 1), n.value]
+        longestPrefixNode = Option.some([key.slice(0, cIndex + 1), n.value])
       }
 
       if (c > n.key) {

package/src/unstable/ai/AiError.ts

@@ -183,7 +183,7 @@ export class NetworkError extends Schema.ErrorClass<NetworkError>(
       description: error.description,
       reason: error._tag,
       request: {
-        hash: error.request.hash,
+        hash: Option.getOrUndefined(error.request.hash),
         headers: redactHeaders(error.request.headers),
         method: error.request.method,
         url: error.request.url,

package/src/unstable/ai/AnthropicStructuredOutput.ts

@@ -22,6 +22,7 @@ import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
 import * as AST from "../../SchemaAST.ts"
 import * as Transformation from "../../SchemaTransformation.ts"
+import * as Tool from "./Tool.ts"
 
 /**
  * Transforms a `Schema.Codec` into a form compatible with Anthropic's
@@ -225,6 +226,9 @@ function recur(ast: AST.AST): AST.AST {
         }
       } else if (ast.indexSignatures.length === 1 && ast.propertySignatures.length === 0) {
         const is = ast.indexSignatures[0]
+        if (Tool.isEmptyParamsRecord(is)) {
+          return ast
+        }
         // records are not supported by Anthropic, so we translate them to arrays of key-value pairs
         if (annotations !== undefined && typeof annotations.description === "string") {
           annotations.description = `${RECORD_DESCRIPTION}; ${annotations.description}`

package/src/unstable/ai/Chat.ts

@@ -696,7 +696,9 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
           yield* Ref.set(chat.history, history)
           // Export the chat history
           const exported = yield* Effect.orDie(chat.export)
-          const timeToLive = Predicate.isNotUndefined(ttl) ? Duration.fromInput(ttl) : undefined
+          const timeToLive = Predicate.isNotUndefined(ttl)
+            ? Option.getOrUndefined(Duration.fromInput(ttl))
+            : undefined
           // Save the chat to the backing store
           yield* store.set(chatId, exported as object, timeToLive)
         }
@@ -738,7 +740,9 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
       // Export the chat history
       const history = yield* Effect.orDie(chat.export)
       // Save the history for the newly created chat
-      const timeToLive = Predicate.isNotUndefined(ttl) ? Duration.fromInput(ttl) : undefined
+      const timeToLive = Predicate.isNotUndefined(ttl)
+        ? Option.getOrUndefined(Duration.fromInput(ttl))
+        : undefined
       yield* store.set(chatId, history as object, timeToLive)
       // Convert the chat to a persisted chat
       return yield* toPersisted(chatId, chat, ttl)

package/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -11,6 +11,7 @@ import * as Rec from "../../Record.ts"
 import * as Schema from "../../Schema.ts"
 import * as AST from "../../SchemaAST.ts"
 import * as Transformation from "../../SchemaTransformation.ts"
+import * as Tool from "./Tool.ts"
 
 /**
  * Transforms a `Schema.Codec` into a form compatible with OpenAI's
@@ -243,6 +244,9 @@ function recurOpenAI(ast: AST.AST): AST.AST {
         }
       } else if (ast.indexSignatures.length === 1 && ast.propertySignatures.length === 0) {
         const is = ast.indexSignatures[0]
+        if (Tool.isEmptyParamsRecord(is)) {
+          return ast
+        }
         // records are not supported by OpenAI, so we translate them to arrays of key-value pairs
         if (annotations !== undefined && typeof annotations.description === "string") {
           annotations.description = `${RECORD_DESCRIPTION}; ${annotations.description}`

package/src/unstable/ai/Tool.ts

@@ -1129,6 +1129,9 @@ const dynamicProto = <
  * can call. The tool definition includes parameter validation, success/failure
  * schemas, and optional service dependencies.
  *
+ * If a tool accepts no parameters but still needs an explicit empty object
+ * schema, use {@link EmptyParams}.
+ *
  * @example
  * ```ts
  * import { Schema } from "effect"
@@ -1866,3 +1869,20 @@ export const unsafeSecureJsonParse = (text: string): unknown => {
     Error.stackTraceLimit = stackTraceLimit
   }
 }
+
+/**
+ * @since 4.0.0
+ */
+export interface EmptyParams extends Schema.$Record<Schema.String, Schema.Never> {}
+
+/**
+ * A schema for tools that accept no parameters.
+ *
+ * @since 4.0.0
+ */
+export const EmptyParams: EmptyParams = Schema.Record(Schema.String, Schema.Never)
+
+/** @internal */
+export function isEmptyParamsRecord(indexSignature: AST.IndexSignature): boolean {
+  return indexSignature.parameter === AST.string && AST.isNever(indexSignature.type)
+}

package/src/unstable/cli/Argument.ts

@@ -226,9 +226,7 @@ export const fileParse = (
  *   host: Schema.String
  * })
  *
- * const JsonConfigSchema = Schema.fromJsonString(ConfigSchema)
- *
- * const config = Argument.fileSchema("config", JsonConfigSchema)
+ * const config = Argument.fileSchema("config", ConfigSchema)
  * ```
  *
  * @since 4.0.0
@@ -236,7 +234,7 @@ export const fileParse = (
  */
 export const fileSchema = <A>(
   name: string,
-  schema: Schema.Codec<A, string>,
+  schema: Schema.Decoder<A>,
   options?: Primitive.FileSchemaOptions | undefined
 ): Argument<A> => Param.fileSchema(Param.argumentKind, name, schema, options)
 

package/src/unstable/cli/CliOutput.ts

@@ -3,6 +3,7 @@
  */
 
 import * as Layer from "../../Layer.ts"
+import * as Option from "../../Option.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
 import type * as CliError from "./CliError.ts"
 import type { HelpDoc } from "./HelpDoc.ts"
@@ -44,6 +45,7 @@ export interface Formatter {
    *
    * @example
    * ```ts
+   * import { Option as O } from "effect"
    * import type { HelpDoc } from "effect/unstable/cli"
    * import { CliOutput } from "effect/unstable/cli"
    *
@@ -55,7 +57,7 @@ export interface Formatter {
    *       name: "verbose",
    *       aliases: ["-v"],
    *       type: "boolean",
-   *       description: "Enable verbose output",
+   *       description: O.some("Enable verbose output"),
    *       required: false
    *     }
    *   ],
@@ -63,7 +65,7 @@ export interface Formatter {
    *     {
    *       name: "file",
    *       type: "string",
-   *       description: "Input file to process",
+   *       description: O.some("Input file to process"),
    *       required: true,
    *       variadic: false
    *     }
@@ -459,7 +461,7 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
       const nameType = `${coloredName} ${coloredType}`
 
       const optionalSuffix = arg.required ? "" : colors.dim(" (optional)")
-      const description = (arg.description ?? "") + optionalSuffix
+      const description = Option.getOrElse(arg.description, () => "") + optionalSuffix
 
       return {
         left: nameType,
@@ -491,7 +493,7 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
 
       return {
         left: namesPart + typePart,
-        right: flag.description ?? ""
+        right: Option.getOrElse(flag.description, () => "")
       }
     })
 
@@ -519,7 +521,7 @@ const formatHelpDocImpl = (doc: HelpDoc, colors: ColorFunctions): string => {
 
       return {
         left: namesPart + typePart,
-        right: flag.description ?? ""
+        right: Option.getOrElse(flag.description, () => "")
       }
     })
 

package/src/unstable/cli/Command.ts

@@ -360,10 +360,10 @@ export interface ParsedTokens {
   readonly flags: Record<string, ReadonlyArray<string>>
   readonly arguments: ReadonlyArray<string>
   readonly errors?: ReadonlyArray<CliError.CliError>
-  readonly subcommand?: {
+  readonly subcommand: Option.Option<{
     readonly name: string
     readonly parsedInput: ParsedTokens
-  }
+  }>
 }
 
 /**
@@ -939,17 +939,17 @@ export const withSubcommands: {
   type InternalInput = NextInput & { readonly [SubcommandStateSymbol]?: SubcommandState }
 
   const parse = Effect.fnUntraced(function*(raw: ParsedTokens) {
-    if (!raw.subcommand) {
+    if (Option.isNone(raw.subcommand)) {
       return (yield* impl.parse(raw)) as NextInput
     }
 
-    const sub = byName.get(raw.subcommand.name)
+    const sub = byName.get(raw.subcommand.value.name)
     if (!sub) {
       return (yield* impl.parse(raw)) as NextInput
     }
 
     const context = yield* impl.parseContext(raw)
-    const result = yield* sub.parse(raw.subcommand.parsedInput)
+    const result = yield* sub.parse(raw.subcommand.value.parsedInput)
     return Object.assign({}, context, { [SubcommandStateSymbol]: { name: sub.name, result } }) as NextInput
   })
 

package/src/unstable/cli/Flag.ts

@@ -304,7 +304,7 @@ export const fileParse = (
  * const ConfigSchema = Schema.Struct({
  *   port: Schema.Number,
  *   host: Schema.String
- * }).pipe(Schema.fromJsonString)
+ * })
  *
  * const config = Flag.fileSchema("config", ConfigSchema, { format: "json" })
  * ```
@@ -314,7 +314,7 @@ export const fileParse = (
  */
 export const fileSchema = <A>(
   name: string,
-  schema: Schema.Codec<A, string>,
+  schema: Schema.Decoder<A>,
   options?: Primitive.FileSchemaOptions | undefined
 ): Flag<A> => Param.fileSchema(Param.flagKind, name, schema, options)