effect 4.0.0-beta.73 → 4.0.0-beta.74

package/src/unstable/cli/Prompt.ts

@@ -149,7 +149,7 @@ export interface Handlers<State, Output> {
  * Options for a confirmation prompt that asks the user to choose a boolean
  * yes/no value.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface ConfirmOptions {
@@ -195,7 +195,7 @@ export interface ConfirmOptions {
  * Options for a date prompt, including the displayed message, initial value,
  * format mask, validation, and locale labels.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface DateOptions {
@@ -270,7 +270,7 @@ export interface DateOptions {
  * Options for an integer prompt, including bounds, keyboard step sizes, and
  * additional validation.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface IntegerOptions {
@@ -315,7 +315,7 @@ export interface IntegerOptions {
  * In addition to the numeric bounds and step settings from `IntegerOptions`,
  * the prompt can be configured with a display precision.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface FloatOptions extends IntegerOptions {
@@ -329,7 +329,7 @@ export interface FloatOptions extends IntegerOptions {
  * Options for a text prompt that returns a list of strings by splitting the
  * input on a delimiter.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface ListOptions extends TextOptions {
@@ -347,7 +347,7 @@ export interface ListOptions extends TextOptions {
  * They control which path type can be selected, the starting directory, paging,
  * and filtering of displayed entries.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface FileOptions {
@@ -383,7 +383,7 @@ export interface FileOptions {
  * Options for a prompt that asks the user to select one value from a list of
  * choices.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface SelectOptions<A> {
@@ -405,7 +405,7 @@ export interface SelectOptions<A> {
  * Options for an autocomplete prompt that lets the user filter selectable
  * choices by typing.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface AutoCompleteOptions<A> extends SelectOptions<A> {
@@ -427,7 +427,7 @@ export interface AutoCompleteOptions<A> extends SelectOptions<A> {
  * Options for a multi-select prompt, including bulk-selection labels and
  * minimum or maximum selection counts.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface MultiSelectOptions {
@@ -488,7 +488,7 @@ export interface SelectChoice<A> {
  * Options for text-entry prompts, including the displayed message, default
  * text, and effectful validation before submission.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface TextOptions {
@@ -511,7 +511,7 @@ export interface TextOptions {
  * Options for a toggle prompt that lets the user switch between active and
  * inactive boolean states.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface ToggleOptions {

package/src/unstable/cli/internal/parser.ts

@@ -329,6 +329,17 @@ type ConsumedFlagValue =
     readonly _tag: "Error"
     readonly error: CliError.InvalidValue
   }
+type ConsumedFlagValueWithTokens =
+  | {
+    readonly _tag: "Value"
+    readonly value: string | undefined
+    readonly tokens: ReadonlyArray<Token>
+  }
+  | {
+    readonly _tag: "Error"
+    readonly error: CliError.InvalidValue
+    readonly tokens: ReadonlyArray<Token>
+  }
 
 const isFlagToken = (t: Token): t is FlagToken => t._tag === "LongOption" || t._tag === "ShortOption"
 
@@ -407,60 +418,88 @@ const consumeFlagValue = (
   spec: FlagParam,
   negated = false
 ): ConsumedFlagValue => {
+  const consumed = consumeFlagValueWithTokens(cursor, token, spec, negated)
+  switch (consumed._tag) {
+    case "Value":
+      return {
+        _tag: "Value",
+        value: consumed.value
+      }
+    case "Error":
+      return {
+        _tag: "Error",
+        error: consumed.error
+      }
+  }
+}
+
+const consumeFlagValueWithTokens = (
+  cursor: TokenCursor,
+  token: FlagToken,
+  spec: FlagParam,
+  negated = false
+): ConsumedFlagValueWithTokens => {
   // Inline value has highest priority
   if (negated) {
     if (token.value !== undefined) {
       return {
         _tag: "Error",
-        error: invalidNegatedFlagValue(token, spec, token.value)
+        error: invalidNegatedFlagValue(token, spec, token.value),
+        tokens: []
       }
     }
 
     const literal = asBooleanLiteral(cursor.peek())
     if (literal !== undefined) {
-      cursor.take()
+      const literalToken = cursor.take()
       return {
         _tag: "Error",
-        error: invalidNegatedFlagValue(token, spec, literal)
+        error: invalidNegatedFlagValue(token, spec, literal),
+        tokens: literalToken === undefined ? [] : [literalToken]
       }
     }
 
     return {
       _tag: "Value",
-      value: "false"
+      value: "false",
+      tokens: []
     }
   }
 
   if (token.value !== undefined) {
     return {
       _tag: "Value",
-      value: token.value
+      value: token.value,
+      tokens: []
     }
   }
 
   // Boolean flags: check for explicit literal or default to "true"
   if (Primitive.isBoolean(spec.primitiveType)) {
     const literal = asBooleanLiteral(cursor.peek())
-    if (literal !== undefined) cursor.take()
+    const literalToken = literal !== undefined ? cursor.take() : undefined
     return {
       _tag: "Value",
-      value: literal ?? "true"
+      value: literal ?? "true",
+      tokens: literalToken === undefined ? [] : [literalToken]
     }
   }
 
   // Non-boolean: try to consume next Value token
   const next = cursor.peek()
   if (next?._tag === "Value") {
-    cursor.take()
+    const valueToken = cursor.take()
     return {
       _tag: "Value",
-      value: next.value
+      value: next.value,
+      tokens: valueToken === undefined ? [] : [valueToken]
     }
   }
 
   return {
     _tag: "Value",
-    value: undefined
+    value: undefined,
+    tokens: []
   }
 }
 
@@ -504,6 +543,161 @@ export const consumeKnownFlags = (
   return { flagMap, remainder, errors }
 }
 
+const extractFlagParams = (command: Command.Any): ReadonlyArray<FlagParam> => {
+  const commandImpl = toImpl(command)
+  const singles = commandImpl.config.flags.flatMap(Param.extractSingleParams)
+  return singles.filter(Param.isFlagParam)
+}
+
+const extractContextFlagParams = (command: Command.Any): ReadonlyArray<FlagParam> => {
+  const commandImpl = toImpl(command)
+  const singles = commandImpl.contextConfig.flags.flatMap(Param.extractSingleParams)
+  return singles.filter(Param.isFlagParam)
+}
+
+const resolveFromRegistries = (
+  token: FlagToken,
+  registries: ReadonlyArray<FlagRegistry>
+): ResolvedFlag | undefined => {
+  for (const registry of registries) {
+    const resolved = resolveFlag(token, registry)
+    if (resolved !== undefined) {
+      return resolved
+    }
+  }
+  return undefined
+}
+
+const preserveFlag = (
+  remainder: Array<Token>,
+  cursor: TokenCursor,
+  token: FlagToken,
+  resolved: ResolvedFlag
+): void => {
+  remainder.push(token)
+  const consumed = consumeFlagValueWithTokens(cursor, token, resolved.param, resolved.negated)
+  remainder.push(...consumed.tokens)
+}
+
+const localFlagWouldPrecedeSubcommand = (
+  token: FlagToken,
+  remainingTokens: ReadonlyArray<Token>,
+  resolved: ResolvedFlag,
+  subIndex: Map<string, Command<string, unknown, unknown, unknown, unknown>>,
+  registries: ReadonlyArray<FlagRegistry>
+): boolean => {
+  const cursor = makeCursor(remainingTokens)
+  consumeFlagValueWithTokens(cursor, token, resolved.param, resolved.negated)
+  for (let token = cursor.take(); token; token = cursor.take()) {
+    if (isFlagToken(token)) {
+      const known = resolveFromRegistries(token, registries)
+      if (known !== undefined) {
+        consumeFlagValueWithTokens(cursor, token, known.param, known.negated)
+      }
+      continue
+    }
+
+    if (token._tag === "Value") {
+      return subIndex.has(token.value)
+    }
+  }
+  return false
+}
+
+/**
+ * Consumes global flags while walking the command tree.
+ *
+ * Command-local flags take precedence over global flags at the selected command
+ * level. This lets commands reuse a global flag name, for example a subcommand
+ * with its own `--version <value>` flag overriding the built-in global
+ * `--version` action.
+ * @internal
+ */
+export const consumeGlobalFlags = (
+  tokens: ReadonlyArray<Token>,
+  command: Command.Any,
+  registry: FlagRegistry
+): { flagMap: FlagMap; remainder: ReadonlyArray<Token>; errors: ReadonlyArray<CliError.InvalidValue> } => {
+  const flagMap = createEmptyFlagMap(registry.params)
+  const errors: Array<CliError.InvalidValue> = []
+
+  const consumeLevel = (
+    tokens: ReadonlyArray<Token>,
+    command: Command.Any,
+    ignoredRegistries: ReadonlyArray<FlagRegistry>
+  ): ReadonlyArray<Token> => {
+    const localRegistry = createFlagRegistry(extractFlagParams(command))
+    const inheritedRegistry = createFlagRegistry(extractContextFlagParams(command))
+    const subIndex = buildSubcommandIndex(command.subcommands)
+    const cursor = makeCursor(tokens)
+    const remainder: Array<Token> = []
+    let awaitingFirstValue = true
+
+    for (let token = cursor.take(); token; token = cursor.take()) {
+      if (isFlagToken(token)) {
+        const ignored = resolveFromRegistries(token, ignoredRegistries)
+        if (ignored !== undefined) {
+          preserveFlag(remainder, cursor, token, ignored)
+          continue
+        }
+
+        const inherited = resolveFlag(token, inheritedRegistry)
+        if (inherited !== undefined) {
+          preserveFlag(remainder, cursor, token, inherited)
+          continue
+        }
+
+        const local = resolveFlag(token, localRegistry)
+        const global = resolveFlag(token, registry)
+        if (local !== undefined) {
+          if (
+            global === undefined || !awaitingFirstValue ||
+            !localFlagWouldPrecedeSubcommand(token, cursor.rest(), local, subIndex, [
+              localRegistry,
+              inheritedRegistry,
+              registry
+            ])
+          ) {
+            preserveFlag(remainder, cursor, token, local)
+            continue
+          }
+        }
+
+        if (global !== undefined) {
+          const consumed = consumeFlagValueWithTokens(cursor, token, global.param, global.negated)
+          if (consumed._tag === "Error") {
+            errors.push(consumed.error)
+            continue
+          }
+          if (consumed.value !== undefined) {
+            flagMap[global.param.name].push(consumed.value)
+          }
+          continue
+        }
+
+        remainder.push(token)
+        continue
+      }
+
+      if (token._tag === "Value" && awaitingFirstValue) {
+        const sub = subIndex.get(token.value)
+        if (sub !== undefined) {
+          remainder.push(token)
+          remainder.push(...consumeLevel(cursor.rest(), sub, [...ignoredRegistries, inheritedRegistry]))
+          return remainder
+        }
+        awaitingFirstValue = false
+      }
+
+      remainder.push(token)
+    }
+
+    return remainder
+  }
+
+  return { flagMap, remainder: consumeLevel(tokens, command, []), errors }
+}
+
 /* ========================================================================== */
 /* Error Creation                                                             */
 /* ========================================================================== */

package/src/unstable/cluster/Entity.ts

@@ -574,7 +574,7 @@ export declare namespace Replier {
  * It includes the underlying request envelope plus the last stream reply chunk
  * that was sent, allowing handlers to resume chunk sequencing after a restart.
  *
- * @category Request
+ * @category request
  * @since 4.0.0
  */
 export class Request<Rpc extends Rpc.Any> extends Data.Class<

package/src/unstable/cluster/HttpRunner.ts

@@ -166,7 +166,7 @@ export const layerClientProtocolWebsocketDefault: Layer.Layer<
  * The returned effect is produced from `RunnerServer.layerHandlers` and the
  * cluster runner RPC group.
  *
- * @category Http App
+ * @category http app
  * @since 4.0.0
  */
 export const toHttpEffect: Effect.Effect<
@@ -189,7 +189,7 @@ export const toHttpEffect: Effect.Effect<
  * The returned effect is produced from `RunnerServer.layerHandlers` and the
  * cluster runner RPC group.
  *
- * @category Http App
+ * @category http app
  * @since 4.0.0
  */
 export const toHttpEffectWebsocket: Effect.Effect<

package/src/unstable/cluster/K8sHttpClient.ts

@@ -56,7 +56,7 @@ import * as HttpClientResponse from "../http/HttpClientResponse.ts"
 /**
  * Service tag for the HTTP client used to call the Kubernetes API.
  *
- * @category Tags
+ * @category services
  * @since 4.0.0
  */
 export class K8sHttpClient extends Context.Service<

package/src/unstable/cluster/Runners.ts

@@ -702,7 +702,7 @@ export const layerRpc: Layer.Layer<
  * Service that creates an RPC client protocol for communicating with a runner at a
  * given address.
  *
- * @category Client
+ * @category client
  * @since 4.0.0
  */
 export class RpcClientProtocol extends Context.Service<

package/src/unstable/cluster/Sharding.ts

@@ -112,7 +112,7 @@ import * as Snowflake from "./Snowflake.ts"
  * Use to access or provide cluster routing, shard ownership, entity
  * registration, singleton registration, and persisted-work polling.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class Sharding extends Context.Service<Sharding, {

package/src/unstable/cluster/SingletonAddress.ts

@@ -39,7 +39,7 @@ const TypeId = "~effect/cluster/SingletonAddress"
 /**
  * Represents the unique address of an singleton within the cluster.
  *
- * @category Address
+ * @category address
  * @since 4.0.0
  */
 export class SingletonAddress extends Schema.Class<SingletonAddress>(TypeId)({

package/src/unstable/cluster/Snowflake.ts

@@ -179,7 +179,7 @@ export const make = (options: {
 /**
  * Extracts the Unix timestamp in milliseconds from a snowflake id.
  *
- * @category Parts
+ * @category parts
  * @since 4.0.0
  */
 export const timestamp = (snowflake: Snowflake): number => Number(snowflake >> constBigInt22) + sinceUnixEpoch
@@ -187,7 +187,7 @@ export const timestamp = (snowflake: Snowflake): number => Number(snowflake >> c
 /**
  * Extracts the timestamp from a snowflake id as a `DateTime.Utc`.
  *
- * @category Parts
+ * @category parts
  * @since 4.0.0
  */
 export const dateTime = (snowflake: Snowflake): DateTime.Utc => DateTime.makeUnsafe(timestamp(snowflake))
@@ -195,7 +195,7 @@ export const dateTime = (snowflake: Snowflake): DateTime.Utc => DateTime.makeUns
 /**
  * Extracts the machine id component from a snowflake id.
  *
- * @category Parts
+ * @category parts
  * @since 4.0.0
  */
 export const machineId = (snowflake: Snowflake): MachineId =>
@@ -204,7 +204,7 @@ export const machineId = (snowflake: Snowflake): MachineId =>
 /**
  * Extracts the per-machine sequence component from a snowflake id.
  *
- * @category Parts
+ * @category parts
  * @since 4.0.0
  */
 export const sequence = (snowflake: Snowflake): number => Number(snowflake % constBigInt4096)
@@ -212,7 +212,7 @@ export const sequence = (snowflake: Snowflake): number => Number(snowflake % con
 /**
  * Decomposes a snowflake id into its timestamp, machine id, and sequence parts.
  *
- * @category Parts
+ * @category parts
  * @since 4.0.0
  */
 export const toParts = (snowflake: Snowflake): Snowflake.Parts => ({

package/src/unstable/devtools/DevToolsClient.ts

@@ -55,7 +55,7 @@ const ResponseSchema = Schema.toCodecJson(DevToolsSchema.Response)
  * Service for sending span and span-event telemetry to the Effect devtools
  * connection.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class DevToolsClient extends Context.Service<

package/src/unstable/eventlog/EventLog.ts

@@ -66,7 +66,7 @@ import type { EventLogRemote } from "./EventLogRemote.ts"
  * only when the handler succeeds, and exposes access to the underlying journal
  * entries and destroy operation.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class EventLog extends Context.Service<EventLog, {

package/src/unstable/eventlog/EventLogEncryption.ts

@@ -82,7 +82,7 @@ const toBufferSource = (data: Uint8Array): ArrayBufferView<ArrayBuffer> => new U
  * Use to provide cryptographic operations required by encrypted event-log
  * replication.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class EventLogEncryption extends Context.Service<EventLogEncryption, {

package/src/unstable/eventlog/EventLogRemote.ts

@@ -63,7 +63,7 @@ import { makeGetIdentityRootSecretMaterial } from "./internal/identityRootSecret
  * It can write local entries to the remote, stream remote changes from a sequence
  * number, and run effects only after the supplied identity has authenticated.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class EventLogRemote extends Context.Service<EventLogRemote, {

package/src/unstable/eventlog/EventLogServerUnencrypted.ts

@@ -79,7 +79,7 @@ import * as EventLogServer from "./EventLogServer.ts"
  * Use to access or provide the server service that handles plaintext
  * event-log writes.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class EventLogServerUnencrypted extends Context.Service<EventLogServerUnencrypted, {
@@ -290,7 +290,7 @@ export class EventLogServerAuthError extends Data.TaggedError("EventLogServerAut
  * Use to provide authorization checks for plaintext event-log writes, reads,
  * and identity authentication.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class EventLogServerAuthorization extends Context.Service<EventLogServerAuthorization, {
@@ -317,7 +317,7 @@ export class EventLogServerAuthorization extends Context.Service<EventLogServerA
  * Use to map client-visible store identifiers to server storage identifiers
  * before authorizing or serving unencrypted event-log requests.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class StoreMapping extends Context.Service<StoreMapping, {

package/src/unstable/http/Cookies.ts

@@ -152,7 +152,7 @@ const CookieTypeId = "~effect/http/Cookies/Cookie"
  * HTTP cookie value with its decoded value, encoded value, and optional cookie
  * attributes such as domain, path, expiration, security, and same-site settings.
  *
- * @category cookie
+ * @category cookies
  * @since 4.0.0
  */
 export interface Cookie extends Inspectable.Inspectable {

package/src/unstable/http/Etag.ts

@@ -78,7 +78,7 @@ export interface Strong {
 /**
  * Formats an `Etag` as an HTTP header value, including quotes and the `W/` prefix for weak tags.
  *
- * @category convertions
+ * @category converting
  * @since 4.0.0
  */
 export const toString = (self: Etag): string => {

package/src/unstable/http/FetchHttpClient.ts

@@ -47,7 +47,7 @@ import * as HttpClientResponse from "./HttpClientResponse.ts"
  *
  * Defaults to `globalThis.fetch`.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export const Fetch = Context.Reference<typeof globalThis.fetch>("effect/http/FetchHttpClient/Fetch", {
@@ -66,7 +66,7 @@ export const Fetch = Context.Reference<typeof globalThis.fetch>("effect/http/Fet
  *
  * Request-specific method, headers, body, and abort signal are supplied by the client when a request is executed.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class RequestInit extends Context.Service<RequestInit, globalThis.RequestInit>()(

package/src/unstable/http/HttpClient.ts

@@ -168,7 +168,7 @@ export declare namespace HttpClient {
  * Use to provide the HTTP client implementation consumed by the module's
  * request accessor functions.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export const HttpClient: Context.Service<HttpClient, HttpClient> = Context.Service<HttpClient, HttpClient>(

package/src/unstable/http/HttpClientRequest.ts

@@ -90,7 +90,7 @@ export interface HttpClientRequest extends Inspectable.Inspectable, Pipeable {
 /**
  * Options for constructing or modifying an `HttpClientRequest`.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface Options {
@@ -113,7 +113,7 @@ export declare namespace Options {
   /**
    * Request options that omit the method and URL for helpers that already receive those values separately.
    *
-   * @category models
+   * @category options
    * @since 4.0.0
    */
   export interface NoUrl extends Omit<Options, "method" | "url"> {}

package/src/unstable/http/HttpMiddleware.ts

@@ -267,7 +267,7 @@ export const xForwardedHeaders = make((httpApp) =>
 /**
  * Middleware that parses the current request URL's search parameters and provides them as `ParsedSearchParams`.
  *
- * @category Search params
+ * @category search params
  * @since 4.0.0
  */
 export const searchParamsParser = <E, R>(

package/src/unstable/http/HttpPlatform.ts

@@ -38,7 +38,7 @@ import * as Response from "./HttpServerResponse.ts"
 /**
  * Service for platform-specific HTTP response helpers, including file-backed server responses.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class HttpPlatform extends Context.Service<HttpPlatform, {

package/src/unstable/http/HttpRouter.ts

@@ -302,7 +302,7 @@ export const RouterConfig = Context.Reference<Partial<FindMyWay.RouterConfig>>(
  * It provides the route definition and the path parameters captured by the route
  * matcher.
  *
- * @category route context
+ * @category services
  * @since 4.0.0
  */
 export class RouteContext extends Context.Service<RouteContext, {
@@ -313,7 +313,7 @@ export class RouteContext extends Context.Service<RouteContext, {
 /**
  * Effect that returns the path parameters captured for the current matched route.
  *
- * @category RouteContext
+ * @category getters
  * @since 4.0.0
  */
 export const params: Effect.Effect<
@@ -1293,7 +1293,7 @@ export const provideRequest =
 /**
  * Runs the provided application layer as an HTTP server.
  *
- * @category Server
+ * @category server
  * @since 4.0.0
  */
 export const serve = <A, E, R, HE, HR = Request.Only<"Requires", R> | Request.Only<"GlobalRequires", R>>(
@@ -1357,7 +1357,7 @@ export const serve = <A, E, R, HE, HR = Request.Only<"Requires", R> | Request.On
  * Web `Response` values and a `dispose` function for releasing the layer
  * resources.
  *
- * @category Server
+ * @category server
  * @since 4.0.0
  */
 export const toWebHandler = <