effect 4.0.0-beta.25 → 4.0.0-beta.26

package/src/unstable/cli/GlobalFlag.ts

@@ -22,7 +22,7 @@ import * as Flag from "./Flag.ts"
  * @category models
  */
 export interface HandlerContext {
-  readonly command: Command.Command<any, unknown, unknown, unknown>
+  readonly command: Command.Command<any, unknown, any, unknown, unknown>
   readonly commandPath: ReadonlyArray<string>
   readonly version: string
 }

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

@@ -16,7 +16,7 @@ import type * as GlobalFlag from "../GlobalFlag.ts"
 import type { ArgDoc, ExampleDoc, FlagDoc, HelpDoc, SubcommandGroupDoc } from "../HelpDoc.ts"
 import * as Param from "../Param.ts"
 import * as Primitive from "../Primitive.ts"
-import { type ConfigInternal, reconstructTree } from "./config.ts"
+import { type ConfigInternal, emptyConfig, reconstructTree } from "./config.ts"
 
 /* ========================================================================== */
 /* Types                                                                      */
@@ -26,19 +26,23 @@ import type { Command, CommandContext, Environment, ParsedTokens } from "../Comm
 
 interface SubcommandGroup {
   readonly group: string | undefined
-  readonly commands: Arr.NonEmptyReadonlyArray<Command<any, unknown, unknown, unknown>>
+  readonly commands: Arr.NonEmptyReadonlyArray<Command<any, unknown, any, unknown, unknown>>
 }
 
 /**
  * Internal implementation interface with all the machinery.
  * Use toImpl() to access from internal code.
  */
-export interface CommandInternal<Name extends string, Input, E, R> extends Command<Name, Input, E, R> {
+export interface CommandInternal<Name extends string, Input, E, R, ContextInput>
+  extends Command<Name, Input, ContextInput, E, R>
+{
   readonly config: ConfigInternal
-  readonly service: ServiceMap.Key<CommandContext<Name>, Input>
+  readonly contextConfig: ConfigInternal
+  readonly service: ServiceMap.Key<CommandContext<Name>, ContextInput>
   readonly annotations: ServiceMap.ServiceMap<never>
   readonly globalFlags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
   readonly parse: (input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>
+  readonly parseContext: (input: ParsedTokens) => Effect.Effect<ContextInput, CliError.CliError, Environment>
   readonly handle: (
     input: Input,
     commandPath: ReadonlyArray<string>
@@ -60,9 +64,9 @@ export const TypeId = "~effect/cli/Command" as const
  * Casts a Command to its internal implementation.
  * For use by internal modules that need access to config, parse, handle, etc.
  */
-export const toImpl = <Name extends string, Input, E, R>(
-  self: Command<Name, Input, E, R>
-): CommandInternal<Name, Input, E, R> => self as CommandInternal<Name, Input, E, R>
+export const toImpl = <Name extends string, Input, E, R, ContextInput = {}>(
+  self: Command<Name, Input, ContextInput, E, R>
+): CommandInternal<Name, Input, E, R, ContextInput> => self as CommandInternal<Name, Input, E, R, ContextInput>
 
 /* ========================================================================== */
 /* Proto                                                                      */
@@ -73,7 +77,7 @@ export const Proto = {
   pipe() {
     return pipeArguments(this, arguments)
   },
-  asEffect(this: Command<any, any, any, any>) {
+  asEffect(this: Command<any, any, any, any, any>) {
     return toImpl(this).service.asEffect()
   }
 }
@@ -85,10 +89,11 @@ export const Proto = {
 /**
  * Internal command constructor. Only accepts already-parsed ConfigInternal.
  */
-export const makeCommand = <const Name extends string, Input, E, R>(options: {
+export const makeCommand = <const Name extends string, Input, E, R, ContextInput = {}>(options: {
   readonly name: Name
   readonly config: ConfigInternal
-  readonly service?: ServiceMap.Key<CommandContext<Name>, Input> | undefined
+  readonly contextConfig?: ConfigInternal | undefined
+  readonly service?: ServiceMap.Key<CommandContext<Name>, ContextInput> | undefined
   readonly annotations?: ServiceMap.ServiceMap<never> | undefined
   readonly globalFlags?: ReadonlyArray<GlobalFlag.GlobalFlag<any>> | undefined
   readonly description?: string | undefined
@@ -97,12 +102,16 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
   readonly examples?: ReadonlyArray<Command.Example> | undefined
   readonly subcommands?: ReadonlyArray<SubcommandGroup> | undefined
   readonly parse?: ((input: ParsedTokens) => Effect.Effect<Input, CliError.CliError, Environment>) | undefined
+  readonly parseContext?:
+    | ((input: ParsedTokens) => Effect.Effect<ContextInput, CliError.CliError, Environment>)
+    | undefined
   readonly handle?:
     | ((input: Input, commandPath: ReadonlyArray<string>) => Effect.Effect<void, E, R | Environment>)
     | undefined
-}): Command<Name, Input, E, R> => {
-  const service = options.service ?? ServiceMap.Service<CommandContext<Name>, Input>(`${TypeId}/${options.name}`)
+}): Command<Name, Input, ContextInput, E, R> => {
   const config = options.config
+  const contextConfig = options.contextConfig ?? emptyConfig
+  const service = options.service ?? ServiceMap.Service<CommandContext<Name>, ContextInput>(`${TypeId}/${options.name}`)
   const annotations = options.annotations ?? ServiceMap.empty()
   const globalFlags = options.globalFlags ?? []
   const subcommands = options.subcommands ?? []
@@ -113,13 +122,10 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
   ): Effect.Effect<void, CliError.CliError | E, R | Environment> =>
     Predicate.isNotUndefined(options.handle)
       ? options.handle(input, commandPath)
-      : Effect.fail(new CliError.ShowHelp({ commandPath }))
+      : Effect.fail(new CliError.ShowHelp({ commandPath, errors: [] }))
 
-  const parse = options.parse ?? Effect.fnUntraced(function*(input: ParsedTokens) {
-    const parsedArgs: Param.ParsedArgs = { flags: input.flags, arguments: input.arguments }
-    const values = yield* parseParams(parsedArgs, config.orderedParams)
-    return reconstructTree(config.tree, values) as Input
-  })
+  const parse = options.parse ?? makeParser(config) as any
+  const parseContext = options.parseContext ?? makeParser(contextConfig) as any
 
   const buildHelpDoc = (commandPath: ReadonlyArray<string>): HelpDoc => {
     const args: Array<ArgDoc> = []
@@ -152,14 +158,7 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
     for (const option of config.flags) {
       const singles = Param.extractSingleParams(option)
       for (const single of singles) {
-        const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)
-        flags.push({
-          name: single.name,
-          aliases: formattedAliases,
-          type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
-          description: single.description,
-          required: single.primitiveType._tag !== "Boolean"
-        })
+        flags.push(toFlagDoc(single))
       }
     }
 
@@ -198,8 +197,10 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
     globalFlags,
     subcommands,
     config,
+    contextConfig,
     service,
     parse,
+    parseContext,
     handle,
     buildHelpDoc,
     ...(Predicate.isNotUndefined(options.description)
@@ -218,6 +219,32 @@ export const makeCommand = <const Name extends string, Input, E, R>(options: {
 /* Helpers                                                                    */
 /* ========================================================================== */
 
+/**
+ * Converts a single flag param into a FlagDoc for help display.
+ */
+export const toFlagDoc = (single: Param.Single<typeof Param.flagKind, unknown>): FlagDoc => {
+  const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)
+  return {
+    name: single.name,
+    aliases: formattedAliases,
+    type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
+    description: single.description,
+    required: single.primitiveType._tag !== "Boolean"
+  }
+}
+
+/**
+ * Creates a parser for a given config. Used as the default for both `parse`
+ * and `parseContext`, and also by `withSharedFlags` to avoid constructing a
+ * full throwaway command.
+ */
+export const makeParser = (cfg: ConfigInternal) =>
+  Effect.fnUntraced(function*(input: ParsedTokens) {
+    const parsedArgs: Param.ParsedArgs = { flags: input.flags, arguments: input.arguments }
+    const values = yield* parseParams(parsedArgs, cfg.orderedParams)
+    return reconstructTree(cfg.tree, values)
+  })
+
 /**
  * Parses param values from parsed command arguments into their typed
  * representations.
@@ -245,15 +272,18 @@ const parseParams: (parsedArgs: Param.ParsedArgs, params: ReadonlyArray<Param.An
 /**
  * Checks for duplicate flag names between parent and child commands.
  */
-export const checkForDuplicateFlags = <Name extends string, Input>(
-  parent: Command<Name, Input, unknown, unknown>,
-  subcommands: ReadonlyArray<Command<any, unknown, unknown, unknown>>
+export const checkForDuplicateFlags = <Name extends string, Input, ContextInput>(
+  parent: Command<Name, Input, ContextInput, unknown, unknown>,
+  subcommands: ReadonlyArray<Command<any, unknown, any, unknown, unknown>>,
+  options?: {
+    readonly contextConfig?: ConfigInternal | undefined
+  } | undefined
 ): void => {
   const parentImpl = toImpl(parent)
   const parentOptionNames = new Set<string>()
 
-  const extractNames = (options: ReadonlyArray<Param.Any>): void => {
-    for (const option of options) {
+  const extractNames = (flags: ReadonlyArray<Param.Any>): void => {
+    for (const option of flags) {
       const singles = Param.extractSingleParams(option)
       for (const single of singles) {
         parentOptionNames.add(single.name)
@@ -261,7 +291,7 @@ export const checkForDuplicateFlags = <Name extends string, Input>(
     }
   }
 
-  extractNames(parentImpl.config.flags)
+  extractNames((options?.contextConfig ?? parentImpl.contextConfig).flags)
 
   for (const subcommand of subcommands) {
     const subImpl = toImpl(subcommand)

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

@@ -183,6 +183,55 @@ export const parseConfig = (config: Config): ConfigInternal => {
   }
 }
 
+/** @internal */
+export const emptyConfig: ConfigInternal = parseConfig({})
+
+const shiftNodeIndexes = (node: ConfigInternal.Node, offset: number): ConfigInternal.Node => {
+  switch (node._tag) {
+    case "Param":
+      return {
+        _tag: "Param",
+        index: node.index + offset
+      }
+    case "Array":
+      return {
+        _tag: "Array",
+        children: node.children.map((child) => shiftNodeIndexes(child, offset))
+      }
+    case "Nested":
+      return {
+        _tag: "Nested",
+        tree: shiftTreeIndexes(node.tree, offset)
+      }
+  }
+}
+
+const shiftTreeIndexes = (tree: ConfigInternal.Tree, offset: number): ConfigInternal.Tree => {
+  const output: ConfigInternal.Tree = {}
+  for (const key in tree) {
+    output[key] = shiftNodeIndexes(tree[key], offset)
+  }
+  return output
+}
+
+/** @internal */
+export const mergeConfig = (
+  left: ConfigInternal,
+  right: ConfigInternal
+): ConfigInternal => {
+  const offset = left.orderedParams.length
+  return {
+    [ConfigInternalTypeId]: ConfigInternalTypeId,
+    flags: [...left.flags, ...right.flags],
+    arguments: [...left.arguments, ...right.arguments],
+    orderedParams: [...left.orderedParams, ...right.orderedParams],
+    tree: {
+      ...left.tree,
+      ...shiftTreeIndexes(right.tree, offset)
+    }
+  }
+}
+
 /* ========================================================================== */
 /* Reconstruction                                                             */
 /* ========================================================================== */

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

@@ -10,8 +10,7 @@ import type { Command } from "../Command.ts"
 import type * as GlobalFlag from "../GlobalFlag.ts"
 import type { FlagDoc, HelpDoc } from "../HelpDoc.ts"
 import * as Param from "../Param.ts"
-import * as Primitive from "../Primitive.ts"
-import { toImpl } from "./command.ts"
+import { toFlagDoc, toImpl } from "./command.ts"
 
 const dedupeGlobalFlags = (
   flags: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
@@ -32,8 +31,8 @@ const dedupeGlobalFlags = (
  * Returns the resolved command lineage for the provided path.
  * Includes the root command as the first element.
  */
-export const getCommandsForCommandPath = <Name extends string, Input, E, R>(
-  command: Command<Name, Input, E, R>,
+export const getCommandsForCommandPath = <Name extends string, Input, E, R, ContextInput>(
+  command: Command<Name, Input, ContextInput, E, R>,
   commandPath: ReadonlyArray<string>
 ): ReadonlyArray<Command.Any> => {
   const commands: Array<Command.Any> = [command]
@@ -65,8 +64,8 @@ export const getCommandsForCommandPath = <Name extends string, Input, E, R>(
  * Returns active global flags for a command path.
  * Built-ins are prepended and declarations are collected root -> leaf.
  */
-export const getGlobalFlagsForCommandPath = <Name extends string, Input, E, R>(
-  command: Command<Name, Input, E, R>,
+export const getGlobalFlagsForCommandPath = <Name extends string, Input, E, R, ContextInput>(
+  command: Command<Name, Input, ContextInput, E, R>,
   commandPath: ReadonlyArray<string>,
   builtIns: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
 ): ReadonlyArray<GlobalFlag.GlobalFlag<any>> => {
@@ -97,12 +96,40 @@ const collectDeclaredGlobalFlags = (command: Command.Any): ReadonlyArray<GlobalF
   return dedupeGlobalFlags(collected)
 }
 
+const getSharedFlagsForCommandPath = (
+  commands: ReadonlyArray<Command.Any>,
+  currentFlags: ReadonlyArray<FlagDoc>
+): ReadonlyArray<FlagDoc> => {
+  if (commands.length <= 1) {
+    return []
+  }
+
+  const seen = new Set(currentFlags.map((flag) => flag.name))
+  const sharedFlags: Array<FlagDoc> = []
+
+  for (const ancestor of commands.slice(0, -1)) {
+    const ancestorImpl = toImpl(ancestor)
+    for (const flag of ancestorImpl.contextConfig.flags) {
+      const singles = Param.extractSingleParams(flag)
+      for (const single of singles) {
+        if (seen.has(single.name)) {
+          continue
+        }
+        seen.add(single.name)
+        sharedFlags.push(toFlagDoc(single))
+      }
+    }
+  }
+
+  return sharedFlags
+}
+
 /**
  * Returns all global flags declared in a command tree.
  * Built-ins are prepended and command declarations are deduplicated by identity.
  */
-export const getGlobalFlagsForCommandTree = <Name extends string, Input, E, R>(
-  command: Command<Name, Input, E, R>,
+export const getGlobalFlagsForCommandTree = <Name extends string, Input, E, R, ContextInput>(
+  command: Command<Name, Input, ContextInput, E, R>,
   builtIns: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
 ): ReadonlyArray<GlobalFlag.GlobalFlag<any>> =>
   dedupeGlobalFlags([
@@ -115,8 +142,8 @@ export const getGlobalFlagsForCommandTree = <Name extends string, Input, E, R>(
  * Navigates through the command hierarchy to find the right command.
  * Reads active global flags for the path and includes them in the help doc.
  */
-export const getHelpForCommandPath = <Name extends string, Input, E, R>(
-  command: Command<Name, Input, E, R>,
+export const getHelpForCommandPath = <Name extends string, Input, E, R, ContextInput>(
+  command: Command<Name, Input, ContextInput, E, R>,
   commandPath: ReadonlyArray<string>,
   builtIns: ReadonlyArray<GlobalFlag.GlobalFlag<any>>
 ): Effect.Effect<HelpDoc, never, never> =>
@@ -126,21 +153,19 @@ export const getHelpForCommandPath = <Name extends string, Input, E, R>(
 
     const baseDoc = toImpl(currentCommand).buildHelpDoc(commandPath)
 
+    const sharedFlags = getSharedFlagsForCommandPath(commands, baseDoc.flags)
+
     const flags = getGlobalFlagsForCommandPath(command, commandPath, builtIns)
     const globalFlagDocs: Array<FlagDoc> = []
     for (const flag of flags) {
       const singles = Param.extractSingleParams(flag.flag)
       for (const single of singles) {
-        const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)
         globalFlagDocs.push({
-          name: single.name,
-          aliases: formattedAliases,
-          type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
-          description: single.description,
+          ...toFlagDoc(single),
           required: false
         })
       }
     }
 
-    return { ...baseDoc, globalFlags: globalFlagDocs }
+    return { ...baseDoc, flags: [...sharedFlags, ...baseDoc.flags], globalFlags: globalFlagDocs }
   })

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

@@ -20,7 +20,7 @@
  *
  * Key Behaviors
  * -------------
- * - Parent flags may appear before OR after the subcommand name (npm-style)
+ * - Inherited parent flags may appear before OR after the subcommand name (npm-style)
  * - Only the first Value token can open a subcommand
  * - Errors accumulate rather than throwing exceptions
  */
@@ -58,10 +58,17 @@ export const parseArgs = (
     const flagParams = singles.filter(Param.isFlagParam)
     const flagRegistry = createFlagRegistry(flagParams)
 
+    const inheritedSingles = commandImpl.contextConfig.flags.flatMap(Param.extractSingleParams)
+    const inheritedFlagParams = inheritedSingles.filter(Param.isFlagParam)
+    const inheritedFlagRegistry = createFlagRegistry(inheritedFlagParams)
+    const inheritedNames = new Set(inheritedFlagParams.map((param) => param.name))
+
     const context: CommandContext = {
       command,
       commandPath: newCommandPath,
-      flagRegistry
+      flagRegistry,
+      inheritedFlagRegistry,
+      localFlagNames: flagParams.filter((param) => !inheritedNames.has(param.name)).map((param) => param.name)
     }
 
     const result = scanCommandLevel(tokens, context)
@@ -133,6 +140,8 @@ type CommandContext = {
   readonly command: Command.Any
   readonly commandPath: ReadonlyArray<string>
   readonly flagRegistry: FlagRegistry
+  readonly inheritedFlagRegistry: FlagRegistry
+  readonly localFlagNames: ReadonlyArray<string>
 }
 
 /**
@@ -176,7 +185,7 @@ type LeafResult = {
 type SubcommandResult = {
   readonly _tag: "Sub"
   readonly flags: Readonly<FlagMap>
-  readonly sub: Command<string, unknown, unknown, unknown>
+  readonly sub: Command<string, unknown, unknown, unknown, unknown>
   readonly childTokens: ReadonlyArray<Token>
   readonly errors: ReadonlyArray<CliError.CliError>
 }
@@ -242,9 +251,9 @@ export const createFlagRegistry = (params: ReadonlyArray<FlagParam>): FlagRegist
 
 const buildSubcommandIndex = (
   subcommands: Command.Any["subcommands"]
-): Map<string, Command<string, unknown, unknown, unknown>> => {
-  const index = new Map<string, Command<string, unknown, unknown, unknown>>()
-  const setKey = (key: string, command: Command<string, unknown, unknown, unknown>) => {
+): Map<string, Command<string, unknown, unknown, unknown, unknown>> => {
+  const index = new Map<string, Command<string, unknown, unknown, unknown, unknown>>()
+  const setKey = (key: string, command: Command<string, unknown, unknown, unknown, unknown>) => {
     const existing = index.get(key)
     if (existing && existing !== command) {
       throw new Error(
@@ -448,7 +457,7 @@ const toLeafResult = (state: ParseState): LeafResult => ({
  * Determines how to handle the first value token.
  *
  * If it matches a known subcommand:
- * - Collect any parent flags from remaining tokens (npm-style)
+ * - Collect inherited parent flags from remaining tokens (npm-style)
  * - Return SubcommandResult with child tokens
  *
  * Otherwise:
@@ -461,13 +470,30 @@ const resolveFirstValue = (
   context: CommandContext,
   state: ParseState
 ): FirstValueResult => {
-  const { command, commandPath, flagRegistry } = context
+  const { command, commandPath, inheritedFlagRegistry, localFlagNames } = context
   const subIndex = buildSubcommandIndex(command.subcommands)
   const sub = subIndex.get(value)
 
   if (sub) {
-    // npm-style: parent flags can appear after subcommand name
-    const tail = consumeKnownFlags(cursor.rest(), flagRegistry)
+    const selectedPath = [...commandPath, sub.name]
+
+    // Local flags are not inherited by subcommands.
+    const parentFlags = state.flags.snapshot()
+    for (const localFlagName of localFlagNames) {
+      const values = parentFlags[localFlagName]
+      if (values !== undefined && values.length > 0) {
+        state.errors.push(
+          new CliError.UnrecognizedOption({
+            option: `--${localFlagName}`,
+            suggestions: [],
+            command: selectedPath
+          })
+        )
+      }
+    }
+
+    // npm-style: inherited parent flags can appear after subcommand name
+    const tail = consumeKnownFlags(cursor.rest(), inheritedFlagRegistry)
     state.flags.merge(tail.flagMap)
 
     return {

package/src/unstable/httpapi/HttpApiBuilder.ts

@@ -36,7 +36,6 @@ import * as Multipart from "../http/Multipart.ts"
 import * as UrlParams from "../http/UrlParams.ts"
 import type * as HttpApi from "./HttpApi.ts"
 import * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
-import { HttpApiSchemaError } from "./HttpApiError.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
 import * as HttpApiMiddleware from "./HttpApiMiddleware.ts"
 import * as HttpApiSchema from "./HttpApiSchema.ts"
@@ -598,12 +597,7 @@ function handlerToHttpEffect(
     })
   ).pipe(
     Effect.withErrorReporting,
-    Effect.catch((error) => {
-      if (Schema.isSchemaError(error)) {
-        error = HttpApiSchemaError.fromSchemaError(error)
-      }
-      return Effect.orDie(encodeError(error))
-    }),
+    Effect.catch((error) => Effect.orDie(encodeError(error))),
     Effect.provideServices(services)
   )
 }

package/src/unstable/httpapi/HttpApiClient.ts

@@ -23,7 +23,7 @@ import * as HttpMethod from "../http/HttpMethod.ts"
 import * as UrlParams from "../http/UrlParams.ts"
 import * as HttpApi from "./HttpApi.ts"
 import * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
-import type { HttpApiSchemaError } from "./HttpApiError.ts"
+import type { BadRequest } from "./HttpApiError.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
 import type * as HttpApiMiddleware from "./HttpApiMiddleware.ts"
 import * as HttpApiSchema from "./HttpApiSchema.ts"
@@ -32,7 +32,7 @@ import * as HttpApiSchema from "./HttpApiSchema.ts"
  * @since 4.0.0
  * @category models
  */
-export type Client<Groups extends HttpApiGroup.Any, E = HttpApiSchemaError, R = never> = Simplify<
+export type Client<Groups extends HttpApiGroup.Any, E = BadRequest, R = never> = Simplify<
   & {
     readonly [Group in Extract<Groups, { readonly topLevel: false }> as HttpApiGroup.Name<Group>]: Client.Group<
       Group,
@@ -50,7 +50,7 @@ export type Client<Groups extends HttpApiGroup.Any, E = HttpApiSchemaError, R =
  * @since 4.0.0
  * @category models
  */
-export type ForApi<Api extends HttpApi.Any, E = HttpApiSchemaError, R = never> = Api extends
+export type ForApi<Api extends HttpApi.Any, E = BadRequest, R = never> = Api extends
   HttpApi.HttpApi<infer _Id, infer Groups> ? Client<Groups, E, R> :
   never
 
@@ -383,7 +383,7 @@ export const makeWith = <ApiId extends string, Groups extends HttpApiGroup.Any,
       | undefined
     readonly baseUrl?: URL | string | undefined
   }
-): Effect.Effect<Client<Groups, HttpApiSchemaError | E, R>, never, HttpApiGroup.MiddlewareClient<Groups>> => {
+): Effect.Effect<Client<Groups, BadRequest | E, R>, never, HttpApiGroup.MiddlewareClient<Groups>> => {
   const client: Record<string, Record<string, any>> = {}
   return makeClient(api, {
     ...options,
@@ -418,7 +418,7 @@ export const group = <
     readonly baseUrl?: URL | string | undefined
   }
 ): Effect.Effect<
-  Client.Group<Groups, GroupName, HttpApiSchemaError | E, R>,
+  Client.Group<Groups, GroupName, BadRequest | E, R>,
   never,
   HttpApiGroup.MiddlewareClient<HttpApiGroup.WithName<Groups, GroupName>>
 > => {
@@ -458,7 +458,7 @@ export const endpoint = <
 ): Effect.Effect<
   Client.Method<
     HttpApiEndpoint.WithName<HttpApiGroup.Endpoints<HttpApiGroup.WithName<Groups, GroupName>>, EndpointName>,
-    HttpApiSchemaError | E,
+    BadRequest | E,
     R
   >,
   never,

package/src/unstable/httpapi/HttpApiEndpoint.ts

@@ -15,7 +15,7 @@ import * as HttpRouter from "../http/HttpRouter.ts"
 import type { HttpServerRequest } from "../http/HttpServerRequest.ts"
 import type { HttpServerResponse } from "../http/HttpServerResponse.ts"
 import type * as Multipart from "../http/Multipart.ts"
-import { HttpApiSchemaError } from "./HttpApiError.ts"
+import { BadRequestFromSchemaError, type BadRequestNoContent } from "./HttpApiError.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
 import type * as HttpApiMiddleware from "./HttpApiMiddleware.ts"
 import * as HttpApiSchema from "./HttpApiSchema.ts"
@@ -53,7 +53,7 @@ export interface HttpApiEndpoint<
   out Payload extends Schema.Top = never,
   out Headers extends Schema.Top = never,
   out Success extends Schema.Top = typeof HttpApiSchema.NoContent,
-  out Error extends Schema.Top = typeof HttpApiSchemaError,
+  out Error extends Schema.Top = typeof BadRequestNoContent,
   in out Middleware = never,
   out MiddlewareR = never
 > extends Pipeable {
@@ -179,7 +179,7 @@ export function getErrorSchemas(endpoint: AnyWithProps): [Schema.Top, ...Array<S
       schemas.add(key.error)
     }
   }
-  return Arr.append(Array.from(schemas), HttpApiSchemaError)
+  return Arr.append(Array.from(schemas), BadRequestFromSchemaError)
 }
 
 /**
@@ -936,7 +936,7 @@ export const make = <Method extends HttpMethod>(method: Method) =>
     : Payload,
   Headers extends Schema.Struct.Fields ? Schema.Struct<Headers> : Headers,
   Success extends ReadonlyArray<Schema.Top> ? Success[number] : Success,
-  (Error extends ReadonlyArray<Schema.Top> ? Error[number] : Error) | typeof HttpApiSchemaError
+  (Error extends ReadonlyArray<Schema.Top> ? Error[number] : Error) | typeof BadRequestNoContent
 > => {
   return makeProto({
     name,

package/src/unstable/httpapi/HttpApiError.ts

@@ -2,30 +2,11 @@
  * @since 4.0.0
  */
 import * as ErrorReporter from "../../ErrorReporter.ts"
+import { identity } from "../../Function.ts"
 import * as Schema from "../../Schema.ts"
+import * as Transformation from "../../SchemaTransformation.ts"
 import * as HttpApiSchema from "./HttpApiSchema.ts"
 
-/**
- * @category errors
- * @since 4.0.0
- */
-export class HttpApiSchemaError extends Schema.ErrorClass<HttpApiSchemaError>("effect/HttpApiSchemaError")({
-  _tag: Schema.tag("HttpApiSchemaError"),
-  message: Schema.String
-}, {
-  httpApiStatus: 400,
-  description: "The request or response did not match the expected schema"
-}) {
-  /**
-   * @since 4.0.0
-   */
-  static fromSchemaError(error: Schema.SchemaError): HttpApiSchemaError {
-    return new HttpApiSchemaError({ message: error.message })
-  }
-
-  override readonly [ErrorReporter.ignore] = true
-}
-
 /**
  * @category Built-in errors
  * @since 4.0.0
@@ -37,6 +18,7 @@ export class BadRequest extends Schema.ErrorClass<BadRequest>("effect/HttpApiErr
   httpApiStatus: 400
 }) {
   override readonly [ErrorReporter.ignore] = true
+  static readonly singleton = new BadRequest()
 }
 
 /**
@@ -47,6 +29,26 @@ export const BadRequestNoContent = BadRequest.pipe(HttpApiSchema.asNoContent({
   decode: () => new BadRequest({})
 }))
 
+/**
+ * @category Built-in errors
+ * @since 4.0.0
+ */
+export const BadRequestFromSchemaError = BadRequest.pipe(
+  Schema.decodeTo(
+    Schema.Union([Schema.declare(Schema.isSchemaError), BadRequest]),
+    Transformation.transform({
+      encode: (_) => BadRequest.singleton,
+      decode: identity
+    })
+  ),
+  HttpApiSchema.asNoContent({
+    decode: () => new BadRequest({})
+  })
+).annotate({
+  httpApiStatus: 400,
+  description: "BadRequest"
+})
+
 /**
  * @category Built-in errors
  * @since 4.0.0