effect-app 4.0.0-beta.99 → 4.0.1

package/src/rpc/Invalidation.ts

@@ -0,0 +1,278 @@
+import * as Ref from "effect/Ref"
+import { Rpc } from "effect/rpc"
+import { type ClientForOptions, makeQueryKey } from "../client/clientFor.ts"
+import * as Context from "../Context.ts"
+import * as DataDependencies from "../DataDependencies.ts"
+import * as Effect from "../Effect.ts"
+import * as S from "../Schema.ts"
+
+/**
+ * Shorthand for a handler-derived invalidation key.
+ * Accepts an RPC handler object so `add(GetMe)` is equivalent to
+ * `add(makeQueryKey(GetMe))`.
+ */
+export type InvalidationKeyInput = InvalidationKey | { readonly id: string; readonly options?: ClientForOptions }
+
+const normalizeKey = (input: InvalidationKeyInput): InvalidationKey => {
+  if (Array.isArray(input)) return input
+  const handler = input as { id: string; options?: ClientForOptions }
+  return makeQueryKey(handler.options ? { id: handler.id, options: handler.options } : { id: handler.id })
+}
+
+// Disambiguates `add` overloads: a `string[]` means a single key; an array
+// containing arrays-or-objects means a batch of inputs.
+const isBatch = (
+  input: InvalidationKeyInput | ReadonlyArray<InvalidationKeyInput>
+): input is ReadonlyArray<InvalidationKeyInput> =>
+  Array.isArray(input) && input[0] !== undefined && typeof input[0] !== "string"
+
+const normalizeInputs = (
+  input: InvalidationKeyInput | ReadonlyArray<InvalidationKeyInput>
+): ReadonlyArray<InvalidationKey> => isBatch(input) ? input.map(normalizeKey) : [normalizeKey(input)]
+
+/**
+ * A single segment within an `InvalidationKey` array.
+ * Accepts any JSON-compatible value: string, number, boolean, null,
+ * arrays and objects recursively — matching TanStack Query's `queryKey` element type.
+ */
+export const InvalidationKeySegment = S.Json
+export type InvalidationKeySegment = S.Schema.Type<typeof InvalidationKeySegment>
+
+/** Schema for a single invalidation key – an array of segments compatible with TanStack Query `queryKey`. */
+export const InvalidationKey = S.Array(InvalidationKeySegment)
+export type InvalidationKey = S.Schema.Type<typeof InvalidationKey>
+
+/** Schema for the full set of invalidation keys – an array of `InvalidationKey`. */
+export const InvalidationKeys = S.Array(InvalidationKey)
+export type InvalidationKeys = S.Schema.Type<typeof InvalidationKeys>
+
+/** Metadata included in every command response for server-driven cache invalidation. */
+export const CommandMetaData = S.Struct({
+  invalidateQueries: InvalidationKeys,
+  dataDependencies: DataDependencies.DataDependencySet
+})
+export type CommandMetaData = S.Schema.Type<typeof CommandMetaData>
+
+export const emptyDataDependencies: DataDependencies.DataDependencySet = {
+  reads: DataDependencies.empty(),
+  writes: DataDependencies.empty()
+}
+
+export const makeMetaData = (
+  invalidateQueries: InvalidationKeys,
+  dataDependencies: DataDependencies.DataDependencySet = emptyDataDependencies
+): CommandMetaData => ({ invalidateQueries, dataDependencies })
+
+export const QueryResponseWithMetaData = <S extends S.Top>(success: S) =>
+  S.Struct({ payload: success, metadata: S.Struct({ dataDependencies: DataDependencies.DataDependencySet }) })
+
+/**
+ * Wraps a command's success schema so that the wire format carries both the `payload`
+ * (the handler's actual return value) and `metadata` (server-driven cache invalidation keys).
+ * Transparent to users: the server handler returns the plain payload and the client receives
+ * the plain payload — wrapping/unwrapping is handled internally by the routing layer.
+ */
+export const CommandResponseWithMetaData = <S extends S.Top>(success: S) =>
+  S.Struct({ payload: success, metadata: CommandMetaData })
+
+/**
+ * Wraps a command's failure schema so that the wire format carries both the `error`
+ * (the handler's actual failure value) and `metadata` (server-driven cache invalidation keys
+ * accumulated thus far before the failure occurred).
+ * Transparent to users: the server handler fails with the plain error and the client receives
+ * the plain error — wrapping/unwrapping is handled internally by the routing layer.
+ */
+export const CommandFailureWithMetaData = <E extends S.Top>(error: E) =>
+  S.Struct({ _tag: S.Literal("CommandFailureWithMetaData"), error, metadata: CommandMetaData })
+
+/**
+ * Stream chunk schema for stream responses with metadata.
+ * Each item is either a data value, an intermediate "metadata" signal carrying cache
+ * invalidation keys accumulated since the previous drain, or a final "done" signal.
+ * Transparent to users: stream handlers return plain values and clients receive plain values —
+ * wrapping/unwrapping is handled internally by the routing layer.
+ *
+ * The "done" chunk is always the last item in the stream and carries any remaining invalidation
+ * keys. An optional "metadata" chunk may appear after any "value" chunk and carries keys
+ * accumulated since the last drain (V3: mid-stream invalidation).
+ */
+export const StreamResponseChunk = <S extends S.Top>(success: S) =>
+  S.Union([
+    S.Struct({ _tag: S.Literal("value"), value: success }),
+    S.Struct({ _tag: S.Literal("metadata"), metadata: CommandMetaData }),
+    S.Struct({ _tag: S.Literal("done"), metadata: CommandMetaData })
+  ])
+
+export type StreamResponseChunk<A> =
+  | { readonly _tag: "value"; readonly value: A }
+  | { readonly _tag: "metadata"; readonly metadata: CommandMetaData }
+  | { readonly _tag: "done"; readonly metadata: CommandMetaData }
+
+/**
+ * Stream chunk schema for stream failures with metadata.
+ * Used to signal a stream failure while still carrying cache invalidation keys
+ * accumulated thus far.
+ */
+export const StreamFailureChunk = <E extends S.Top>(error: E) =>
+  S.Struct({ _tag: S.Literal("error"), error, metadata: CommandMetaData })
+
+export type StreamFailureChunk<E> = { readonly _tag: "error"; readonly error: E; readonly metadata: CommandMetaData }
+
+/**
+ * Context annotation for declaring static cache invalidation keys on a low-level `Rpc` definition.
+ * These keys are always included in the command response metadata, regardless of the handler logic.
+ *
+ * Prefer using `makeQueryKey` over raw string arrays to stay in sync with the actual query
+ * definitions without manual string maintenance:
+ *
+ * ```ts
+ * import { makeQueryKey } from "effect-app/client"
+ * import { Invalidation } from "effect-app/rpc"
+ * import * as UserRsc from "../User/index.ts"  // separate module to avoid circular deps
+ *
+ * class UpdateProfile extends Rpc.make("UpdateProfile", { ... })
+ *   .annotate(Invalidation.Invalidates, [makeQueryKey(UserRsc.GetMe), makeQueryKey(UserRsc.GetProfile)]) {}
+ * ```
+ *
+ * **Circular dependency note:** if mutations and queries live in the same file you may hit a
+ * circular reference at evaluation time. The idiomatic fix is to move mutations into their own
+ * module (e.g. `User/mutations.ts`) that directly imports the relevant query classes rather than
+ * re-exporting them through a barrel.
+ *
+ * For the higher-level `Command`/`Query` builders from `makeRpcClient`, use the
+ * `invalidatesQueries` callback argument instead (it receives the same query keys at runtime).
+ */
+export const Invalidates = Context.Reference<ReadonlyArray<InvalidationKey>>(
+  "effect-app/rpc/Invalidates",
+  { defaultValue: () => [] }
+)
+export type Invalidates = typeof Invalidates
+
+/** The shape of the per-request service that accumulates invalidation keys. */
+export interface InvalidationSetService {
+  readonly add: (
+    input: InvalidationKeyInput | ReadonlyArray<InvalidationKeyInput>
+  ) => Effect.Effect<void>
+  readonly get: Effect.Effect<ReadonlyArray<InvalidationKey>>
+  /**
+   * V3: Reads all currently accumulated keys and resets the bucket to empty.
+   * Used by the stream routing layer to emit intermediate "metadata" chunks
+   * without re-sending keys that have already been forwarded to the client.
+   */
+  readonly drain: Effect.Effect<ReadonlyArray<InvalidationKey>>
+}
+
+/**
+ * Request-scoped service for accumulating invalidation keys dynamically inside a handler.
+ * Provided by `InvalidationMiddlewareLive` for every RPC call; has a no-op default so it is
+ * safe to use even when the HTTP middleware is absent (tests, workers, etc.).
+ *
+ * Use `InvalidationSet.add(key)` as a shorthand to skip `.use(_ => _.add(key))`. The
+ * underlying service is still available via `.use` / `.useSync` for advanced cases.
+ *
+ * `add` accepts an RPC handler directly (e.g. `UserRsc.GetMe`) — its query key is derived via
+ * `makeQueryKey` so keys stay in sync with the actual query definitions. Raw `InvalidationKey`
+ * arrays and arrays of either form are also accepted.
+ *
+ * ```ts
+ * import * as Effect from "effect/Effect"
+ * import { Invalidation } from "effect-app/rpc"
+ * import * as CartRsc from "../Cart/queries.ts"
+ * import * as UserRsc from "../User/queries.ts"
+ *
+ * const handler = Effect.fnUntraced(function*(req: UpdateCartRequest) {
+ *   const cart = yield* CartRepo.save(req.cart)
+ *
+ *   // single handler
+ *   yield* Invalidation.InvalidationSet.add(UserRsc.GetMe)
+ *
+ *   // batch
+ *   if (cart.isCheckedOut) {
+ *     yield* Invalidation.InvalidationSet.add([CartRsc.GetCartStats, UserRsc.GetMe])
+ *   }
+ *
+ *   return cart
+ * })
+ * ```
+ *
+ * You can combine static (`Invalidates` annotation) and dynamic (`InvalidationSet.use`) keys:
+ * the annotation pre-populates the set before the handler runs; dynamic additions accumulate
+ * throughout the handler. All keys are included in the command response metadata.
+ */
+const InvalidationSetRef = Context.Reference<InvalidationSetService>(
+  "effect-app/rpc/InvalidationSet",
+  {
+    defaultValue: () => ({
+      add: (_input: InvalidationKeyInput | ReadonlyArray<InvalidationKeyInput>) => Effect.void,
+      get: Effect.succeed([] as ReadonlyArray<InvalidationKey>),
+      drain: Effect.succeed([] as ReadonlyArray<InvalidationKey>)
+    })
+  }
+)
+export const InvalidationSet = Object.assign(InvalidationSetRef, {
+  /**
+   * Shortcut for `InvalidationSet.use(_ => _.add(input))`. Accepts a single
+   * `InvalidationKeyInput` or an array of them.
+   */
+  add: (input: InvalidationKeyInput | ReadonlyArray<InvalidationKeyInput>) =>
+    InvalidationSetRef.use((_) => _.add(input))
+})
+export type InvalidationSet = typeof InvalidationSetRef
+
+/** Creates a fresh `InvalidationSet` implementation backed by a `Ref`. */
+export const makeInvalidationSet = (ref: Ref.Ref<ReadonlyArray<InvalidationKey>>): InvalidationSetService => ({
+  add: (input) => Ref.update(ref, (keys) => [...keys, ...normalizeInputs(input)]),
+  get: Ref.get(ref),
+  drain: Ref.getAndSet(ref, [])
+})
+
+/**
+ * `Rpc.Custom` definition for command RPCs that wrap the success/error schemas
+ * with `CommandResponseWithMetaData` / `CommandFailureWithMetaData`. The wrap
+ * lets server forward accumulated invalidation keys on both success and
+ * handler-thrown failure paths. Middleware-thrown errors bypass the wrap
+ * (the handler never ran, so no metadata) and flow raw at the Cause level —
+ * the client decodes them via the `rpc.middlewares[*].error` failure-union
+ * channel of `Rpc.exitSchema`.
+ */
+// eslint-disable-next-line import/namespace
+export interface CommandRpc extends Rpc.Custom {
+  readonly out: Rpc.Custom.Out<
+    ReturnType<typeof CommandResponseWithMetaData<this["success"] & S.Top>>,
+    ReturnType<typeof CommandFailureWithMetaData<this["error"] & S.Top>>
+  >
+}
+
+/**
+ * Custom Rpc constructor for command RPCs.
+ * Wraps the success schema with `CommandResponseWithMetaData` and the error
+ * schema with `CommandFailureWithMetaData`.
+ */
+export const makeCommandRpc = Rpc.custom<CommandRpc>(({ defect, error, success }) => ({
+  success: CommandResponseWithMetaData(success),
+  error: CommandFailureWithMetaData(error),
+  defect
+}))
+
+/**
+ * `Rpc.Custom` definition for stream RPCs that wrap the success/error schemas
+ * with `StreamResponseChunk` / `StreamFailureChunk`.
+ */
+// eslint-disable-next-line import/namespace
+export interface StreamRpc extends Rpc.Custom {
+  readonly out: Rpc.Custom.Out<
+    ReturnType<typeof StreamResponseChunk<this["success"] & S.Top>>,
+    ReturnType<typeof StreamFailureChunk<this["error"] & S.Top>>
+  >
+}
+
+/**
+ * Custom Rpc constructor for stream RPCs.
+ * Wraps the success schema with `StreamResponseChunk` and
+ * the error schema with `StreamFailureChunk`.
+ */
+export const makeStreamRpc = Rpc.custom<StreamRpc>(({ defect, error, success }) => ({
+  success: StreamResponseChunk(success),
+  error: StreamFailureChunk(error),
+  defect
+}))

package/src/rpc/MiddlewareMaker.ts

@@ -1,18 +1,18 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { Effect, Layer, type Schema, Schema as S, type Scope } from "effect"
 import { type NonEmptyArray, type NonEmptyReadonlyArray } from "effect/Array"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import { Rpc, type RpcGroup, type RpcSchema } from "effect/rpc"
+import { type HandlersFrom } from "effect/rpc/RpcGroup"
+import * as S from "effect/Schema"
+import type * as Scope from "effect/Scope"
 import { type Simplify } from "effect/Types"
-import { Rpc, type RpcGroup, type RpcSchema } from "effect/unstable/rpc"
-import { type HandlersFrom } from "effect/unstable/rpc/RpcGroup"
-import { type RequestId } from "effect/unstable/rpc/RpcMessage"
-import * as Context from "../Context.js"
-import { type HttpHeaders } from "../http.js"
-import { PreludeLogger } from "../logger.js"
-import { type TypeTestId } from "../TypeTest.js"
-import { typedValuesOf } from "../utils.js"
-import { type GetContextConfig, type RequestContextMapTagAny, type RpcContextMap } from "./RpcContextMap.js"
-import { type AddMiddleware, type AnyDynamic, type RpcDynamic, type RpcMiddlewareV4, type TagClassAny } from "./RpcMiddleware.js"
-import * as RpcMiddlewareX from "./RpcMiddleware.js"
+import * as Context from "../Context.ts"
+import { PreludeLogger } from "../logger.ts"
+import { type TypeTestId } from "../TypeTest.ts"
+import { type GetContextConfig, type RequestContextMapTagAny, type RpcContextMap } from "./RpcContextMap.ts"
+import { type AddMiddleware, type AnyDynamic, type RpcDynamic, type RpcMiddlewareV4, type TagClassAny } from "./RpcMiddleware.ts"
+import * as RpcMiddlewareX from "./RpcMiddleware.ts"
 
 // adapter for effect/rpc v3 middleware provides. (in effect-smol (v4), it's just a Service Identifier, no tags.)
 // hm?
@@ -94,7 +94,7 @@ export namespace MiddlewareMaker {
     : never
     : never
 
-  export type Errors<T> = T extends TagClassAny ? T extends { error: S.Top } ? S.Schema.Type<T["error"]>
+  export type Errors<T> = T extends TagClassAny ? T extends { error: S.Top } ? T["error"]["Type"]
     : never
     : never
 
@@ -170,9 +170,9 @@ export interface BuildingMiddleware<
 > {
   rpc: <
     const Tag extends string,
-    Payload extends Schema.Top | Schema.Struct.Fields = typeof Schema.Void,
-    Success extends Schema.Top = typeof Schema.Void,
-    Error extends Schema.Top = typeof Schema.Never,
+    Payload extends S.Top | S.Struct.Fields = typeof S.Void,
+    Success extends S.Top = typeof S.Void,
+    Error extends S.Top = typeof S.Never,
     const Stream extends boolean = false,
     Config extends GetContextConfig<RequestContextMap> = {}
   >(tag: Tag, options?: {
@@ -181,16 +181,16 @@ export interface BuildingMiddleware<
     readonly error?: Error
     readonly stream?: Stream
     readonly config?: Config
-    readonly primaryKey?: [Payload] extends [Schema.Struct.Fields] ? ((
-        payload: Payload extends Schema.Struct.Fields ? Simplify<Schema.Struct<Payload>["Type"]> : Payload["Type"]
+    readonly primaryKey?: [Payload] extends [S.Struct.Fields] ? ((
+        payload: Payload extends S.Struct.Fields ? Simplify<S.Struct<Payload>["Type"]> : Payload["Type"]
       ) => string)
       : never
   }) =>
     & Rpc.Rpc<
       Tag,
-      Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
+      Payload extends S.Struct.Fields ? S.Struct<Payload> : Payload,
       Stream extends true ? RpcSchema.Stream<Success, Error> : Success,
-      Stream extends true ? typeof Schema.Never : Error
+      Stream extends true ? typeof S.Never : Error
     >
     & { readonly config: Config }
 
@@ -259,10 +259,10 @@ export type MiddlewaresBuilder<
     : { new(_: never): {} }
     : { new(_: never): {} })
 
-const middlewareMaker = <
+const middlewareMaker = Effect.fnUntraced(function*<
   MiddlewareProviders extends ReadonlyArray<MiddlewareMaker.Any>
->(middlewares: MiddlewareProviders): Effect.Effect<
-  RpcMiddlewareV4<
+>(middlewares: MiddlewareProviders) {
+  type Middleware = RpcMiddlewareV4<
     MiddlewareMaker.ManyProvided<MiddlewareProviders>,
     MiddlewareMaker.ManyErrors<MiddlewareProviders>,
     Exclude<
@@ -271,42 +271,32 @@ const middlewareMaker = <
     > extends never ? never
       : Exclude<MiddlewareMaker.ManyRequired<MiddlewareProviders>, MiddlewareMaker.ManyProvided<MiddlewareProviders>>
   >
-> => {
+  type Next = Parameters<Middleware>[0]
+  type Options = Parameters<Middleware>[1]
+
   // we want to run them in reverse order because latter middlewares will provide context to former ones
-  middlewares = middlewares.toReversed() as any
-
-  return Effect.gen(function*() {
-    const context = yield* Effect.context()
-
-    // returns a Effect/RpcMiddlewareV4 with Scope.Scope in requirements
-    // v4: wrap middleware takes (effect, options) as two params instead of a single options bag
-    return (
-      next: Effect.Effect<any, any, any>,
-      options: {
-        readonly clientId: number
-        readonly requestId: RequestId
-        readonly rpc: Rpc.AnyWithProps
-        readonly payload: unknown
-        readonly headers: HttpHeaders.Headers
-      }
-    ) => {
-      // we start with the actual handler
-      let handler = next
-
-      // inspired from Effect/RpcMiddleware
-      for (const tag of middlewares) {
-        // use the tag to get the middleware from context
-        const middleware = Context.getUnsafe(context, tag)
-
-        // wrap the current handler, allowing the middleware to run before and after it
-        handler = PreludeLogger.logDebug("Applying middleware wrap " + tag.key).pipe(
-          Effect.andThen(middleware(handler, options))
-        ) as any
-      }
-      return handler
+  const reversed = middlewares.toReversed()
+  const context = yield* Effect.context()
+
+  // returns a Effect/RpcMiddlewareV4 with Scope.Scope in requirements
+  // v4: wrap middleware takes (effect, options) as two params instead of a single options bag
+  return (next: Next, options: Options) => {
+    // we start with the actual handler
+    let handler = next
+
+    // inspired from Effect/RpcMiddleware
+    for (const tag of reversed) {
+      // use the tag to get the middleware from context
+      const middleware = Context.getUnsafe(context, tag)
+
+      // wrap the current handler, allowing the middleware to run before and after it
+      handler = PreludeLogger.logDebug("Applying middleware wrap " + tag.key).pipe(
+        Effect.andThen(middleware(handler, options))
+      ) as any
     }
-  }) as any
-}
+    return handler
+  }
+})
 
 const makeMiddlewareBasic = <Self>() =>
 // by setting RequestContextMap beforehand, execute contextual typing does not fuck up itself to anys
@@ -322,7 +312,26 @@ const makeMiddlewareBasic = <Self>() =>
   // reverse middlewares and wrap one after the other
   const middleware = middlewareMaker(make)
 
-  const failures = make.map((_) => _.error).filter(Boolean)
+  // Per-middleware error: union of the static `error` on the tag (if any) AND
+  // the rcm config entry pointed at by the middleware's `dynamic.key` (if any).
+  // Reason: middlewares declared with `dynamic: RequestContextMap.get("foo")`
+  // don't set a static `error` field — at runtime their `.error` defaults to
+  // `S.Never`. Without pulling from rcm, the composite middleware's
+  // `.error` collapses to `Never`, and `Rpc.exitSchema` (which walks
+  // `rpc.middlewares[*].error` to build the wire failure union) can't decode
+  // the actual middleware-thrown error type. Critical for stream rpcs whose
+  // top-level `errorSchema` is force-set to `Never` by effect-rpc.
+  const isMeaningfulError = (e: S.Top | undefined): e is S.Top => e !== undefined && e !== null && e !== S.Never
+  const rcmRecord = rcm as Record<string, RpcContextMap.Any>
+  const failures: Array<S.Top> = make.flatMap((_) => {
+    const out: Array<S.Top> = []
+    if (isMeaningfulError(_.error)) out.push(_.error)
+    const key = _.dynamic?.key as string | undefined
+    if (key && rcmRecord[key] && isMeaningfulError(rcmRecord[key].error)) {
+      out.push(rcmRecord[key].error)
+    }
+    return out
+  })
   const provides = make.flatMap((_) => !_.provides ? [] : Array.isArray(_.provides) ? _.provides : [_.provides])
   const requires = make
     .flatMap((_) => !_.requires ? [] : Array.isArray(_.requires) ? _.requires : [_.requires])
@@ -358,10 +367,11 @@ const makeMiddlewareBasic = <Self>() =>
     .effect(
       MiddlewareMaker,
       middleware as Effect.Effect<
-        any,
-        Effect.Error<typeof middleware>,
-        Effect.Services<typeof middleware>
+        any
       >
+      // todo; they dont change the type..
+      //  Effect.Error<typeof middleware>,
+      //  Effect.Services<typeof middleware>
     )
 
   // add to the tag a default implementation
@@ -380,7 +390,7 @@ export const Tag = <Self>() =>
   const Id extends string,
   RequestContextMap extends RequestContextMapTagAny
 >(id: Id, rcm: RequestContextMap): MiddlewaresBuilder<Self, Id, RequestContextMap["config"]> => {
-  let allMiddleware: MiddlewareMaker.Any[] = []
+  const allMiddleware: MiddlewareMaker.Any[] = []
   const requestContext = Context.Service<"RequestContextConfig", GetContextConfig<RequestContextMap["config"]>>(
     "RequestContextConfig"
   )
@@ -389,9 +399,9 @@ export const Tag = <Self>() =>
     // rpc with config
     rpc: <
       const Tag extends string,
-      Payload extends Schema.Top | Schema.Struct.Fields = typeof Schema.Void,
-      Success extends Schema.Top = typeof Schema.Void,
-      Error extends Schema.Top = typeof Schema.Never,
+      Payload extends S.Top | S.Struct.Fields = typeof S.Void,
+      Success extends S.Top = typeof S.Void,
+      Error extends S.Top = typeof S.Never,
       const Stream extends boolean = false,
       Config extends GetContextConfig<RequestContextMap["config"]> = {}
     >(tag: Tag, options?: {
@@ -400,35 +410,32 @@ export const Tag = <Self>() =>
       readonly error?: Error
       readonly stream?: Stream
       readonly config?: Config
-      readonly primaryKey?: [Payload] extends [Schema.Struct.Fields] ? ((
-          payload: Payload extends Schema.Struct.Fields ? Simplify<Schema.Struct<Payload>["Type"]> : Payload["Type"]
+      readonly primaryKey?: [Payload] extends [S.Struct.Fields] ? ((
+          payload: Payload extends S.Struct.Fields ? Simplify<S.Struct<Payload>["Type"]> : Payload["Type"]
         ) => string)
         : never
     }):
       & Rpc.Rpc<
         Tag,
-        Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
+        Payload extends S.Struct.Fields ? S.Struct<Payload> : Payload,
         // TODO: enhance `Error`. type based on middleware config.
         Stream extends true ? RpcSchema.Stream<Success, Error> : Success,
-        Stream extends true ? typeof Schema.Never : Error
+        Stream extends true ? typeof S.Never : Error
       >
       & { config: Config } =>
     {
       const config = options?.config ?? {} as Config
 
-      // based on the config, we must enhance (union) or set failures.
-      // TODO: we should only include errors that are relevant based on the middleware config.ks
-      const error = options?.error
-      const errors = typedValuesOf(rcm.config).map((_) => _.error).filter((_) => _ && _ !== S.Never) // TODO: only the errors relevant based on config
-      const allErrors = error ? [error, ...errors] : errors
-      const [firstError, ...restErrors] = allErrors
-      const newError = firstError ? S.Union([firstError, ...restErrors]) : S.Never
-
+      // The rpc's `error` schema carries ONLY the request's own declared errors.
+      // Middleware errors (rcm-derived) reach the wire via the middleware tag
+      // attached to the rpc group later (`RpcGroup.middleware(...)` at the
+      // routing/client level), and are unioned into the failure schema by
+      // `Rpc.exitSchema`'s `rpc.middlewares[*].error` walk.
       // @ts-expect-error — TypeScript can't prove Simplify<T> ≡ { [K in keyof T]: T[K] } for unresolved generics (primaryKey)
       const rpc = Rpc.make(tag, {
         ...options?.payload !== undefined ? { payload: options.payload } : {},
         ...options?.success !== undefined ? { success: options.success } : {},
-        error: newError,
+        ...options?.error !== undefined ? { error: options.error } : {},
         ...options?.stream !== undefined ? { stream: options.stream } : {},
         ...options?.primaryKey !== undefined ? { primaryKey: options.primaryKey } : {}
       }) as any
@@ -438,7 +445,7 @@ export const Tag = <Self>() =>
     middleware: (...middlewares: any[]) => {
       for (const mw of middlewares) {
         // recall that we run middlewares in reverse order
-        allMiddleware = [mw, ...allMiddleware]
+        allMiddleware.unshift(mw)
       }
       return allMiddleware.filter((m) => !!m.dynamic).length !== Object.keys(rcm.config).length
         // for sure, until all the dynamic middlewares are provided it's non sensical to call makeMiddlewareBasic

package/src/rpc/README.md

@@ -3,7 +3,7 @@
 The extensions use V4 format of RPC middleware:
 
 - supports `requires` besides `provides`
-- `requires` and `provides`  should be set as second generic argument: `Tag<Self, Config>`.
+- `requires` and `provides` should be set as second generic argument: `Tag<Self, Config>`.
 - `wrap: true` is the default, there is no classic `provides: Tag`
 
 ## Features
@@ -34,7 +34,7 @@ NOTE: perhaps not as useful anymore if support for dynamic middleware gets integ
 
 ## Examples
 
-See  [tests](../../../infra/test/rpc-multi-middleware.test.ts)
+See [tests](../../../infra/test/rpc-multi-middleware.test.ts)
 
 ## Future
 

package/src/rpc/RpcContextMap.ts

@@ -2,10 +2,10 @@
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-import { type Schema as S } from "effect"
-import { type AnyWithProps } from "effect/unstable/rpc/Rpc"
-import * as Context from "../Context.js"
-import { type RpcDynamic } from "./RpcMiddleware.js"
+import { type AnyWithProps } from "effect/rpc/Rpc"
+import type * as S from "effect/Schema"
+import * as Context from "../Context.ts"
+import { type RpcDynamic } from "./RpcMiddleware.ts"
 
 type Values<T extends Record<any, any>> = T[keyof T]
 

package/src/rpc/RpcMiddleware.ts

@@ -1,18 +1,21 @@
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { type Effect, type Schema, type Schema as S, type Scope, type Stream } from "effect"
 import { type NonEmptyReadonlyArray } from "effect/Array"
-import { type Rpc, RpcMiddleware } from "effect/unstable/rpc"
-import { type TypeId } from "effect/unstable/rpc/RpcMiddleware"
-import type * as Context from "../Context.js"
-import { type GetEffectContext, type RpcContextMap } from "./RpcContextMap.js"
+import type * as Effect from "effect/Effect"
+import { type Rpc, RpcMiddleware } from "effect/rpc"
+import { type TypeId } from "effect/rpc/RpcMiddleware"
+import type * as S from "effect/Schema"
+import type * as Scope from "effect/Scope"
+import type * as Stream from "effect/Stream"
+import type * as Context from "../Context.ts"
+import { type GetEffectContext, type RpcContextMap } from "./RpcContextMap.ts"
 
 export type RpcMiddlewareV4<Provides, E, Requires> = RpcMiddleware.RpcMiddleware<Provides, E, Requires>
 
 export type RpcOptionsOriginal = {
   readonly optional?: boolean
-  readonly error?: Schema.Top
+  readonly error?: S.Top
   readonly requiredForClient?: boolean
 }
 
@@ -40,7 +43,7 @@ export interface TagClassAny extends RpcMiddleware.AnyService {
   readonly optional: boolean
   readonly provides: any
   readonly requires: any
-  readonly error: Schema.Top
+  readonly error: S.Top
   readonly dynamic?: RpcDynamic<any, any> | undefined
   readonly dependsOn?: NonEmptyReadonlyArray<AnyDynamic> | undefined
 }
@@ -50,27 +53,29 @@ export declare namespace TagClass {
    * @since 1.0.0
    * @category models
    */
-  export type FailureSchema<Options> = Options extends { readonly error: Schema.Top; readonly optional?: false }
+  export type FailureSchema<Options> = Options extends { readonly error: S.Top; readonly optional?: false }
     ? Options["error"]
     // actually not, the Failure depends on Dynamic Middleware Configuration!
     // : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? A["error"]
-    : typeof Schema.Never
+    : typeof S.Never
 
   /**
    * @since 1.0.0
    * @category models
    */
-  export type Failure<Options> = Options extends { readonly error: Schema.Codec<infer _A>; readonly optional?: false }
-    ? _A
+  export type Failure<Options> = Options extends { readonly error: S.Codec<infer _A>; readonly optional?: false } ? _A
     // actually not, the Failure depends on Dynamic Middleware Configuration!
-    : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? S.Schema.Type<A["error"]>
+    : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? A["error"]["Type"]
     : never
 
   /**
    * @since 1.0.0
    * @category models
    */
-  export type FailureContext<Options> = Schema.Codec.DecodingServices<FailureSchema<Options>>
+  // Avoid `S.Codec.DecodingServices<X> = X extends Top ? X["DecodingServices"] : never`:
+  // tsgo fails to reduce it here and leaves `unknown`. `FailureSchema<Options>` is
+  // always `S.Top` (either `Options["error"]` or `typeof S.Never`), so read directly.
+  export type FailureContext<Options> = FailureSchema<Options>["DecodingServices"]
 
   /**
    * @since 1.0.0