effect-app 4.0.0-beta.99 → 4.0.0

package/src/client/makeClient.ts

@@ -1,21 +1,105 @@
-import { SchemaTransformation } from "effect"
-import { type GetContextConfig, type GetEffectError, type RequestContextMapTagAny } from "../rpc/RpcContextMap.js"
-import * as S from "../Schema.js"
-import { AST } from "../Schema.js"
+import type * as Exit from "effect/Exit"
+import { type GetContextConfig, type RpcContextMap } from "../rpc/RpcContextMap.ts"
+import * as S from "../Schema.ts"
+import { AST } from "../Schema.ts"
+import type { ClientForOptions } from "./clientFor.ts"
+
+/**
+ * Minimal structural shape for an rpc-client middleware tag.
+ * Captures only what `makeRpcClient` and routing/client factory consume from it
+ * (no `Default` layer required — that is provided to `makeRouter`).
+ */
+export interface ClientMiddleware<RequestContextMap extends Record<string, RpcContextMap.Any>> {
+  readonly requestContextMap: RequestContextMap
+  readonly requestContext: unknown
+  readonly provides?: unknown
+  readonly requires?: unknown
+}
 
 const merge = (a: any, b: Array<any>) =>
   a !== undefined && b.length ? S.Union([a, ...b]) : a !== undefined ? a : b.length ? S.Union(b) : S.Never
 
+type SchemaOrFields<T> = T extends S.Top ? T : T extends S.Struct.Fields ? S.Struct<T> : S.Void
+
+type TaggedRequestSchema<Tag extends string, Payload extends S.Struct.Fields> = S.Struct<
+  { readonly _tag: S.tag<Tag> } & Payload
+>
+
+type QueryOnlyRequests<Resource> = {
+  [K in keyof Resource as Resource[K] extends { readonly type: "query" } ? K : never]: Resource[K]
+}
+
+type QueryOnlyResources<Resources> = {
+  [K in keyof Resources]: QueryOnlyRequests<Resources[K]>
+}
+
+type InputFromPayload<Payload extends S.Struct.Fields> = keyof Payload extends never ? void
+  : S.Struct<Payload>["Type"]
+
+type OutputFromSuccess<Success extends S.Top> = Success extends typeof S.Void ? void : Success["Type"]
+
+type InvalidationResources = Record<string, Record<string, unknown>>
+
 /**
- * Whatever the input, we will only decode or encode to void
+ * An invalidation instruction returned from `invalidatesQueries`. One of:
+ *  - a raw query key (`ReadonlyArray<string>`)
+ *  - an RPC handler object (`{ id, options? }`) — query key derived from `id`
+ *  - a compatibility `{ filters: { queryKey }, options? }` shape
+ *
+ * Predicate filters are intentionally not represented: atom invalidation is keyed by
+ * concrete query keys.
  */
-export const ForceVoid = S
-  .declare((_: unknown): _ is unknown => true)
-  .pipe(
-    S.decodeTo(S.Any, SchemaTransformation.transform<unknown, unknown>({ decode: () => void 0, encode: () => void 0 }))
-  )
+export type InvalidateQueryInstruction<
+  Filters = { readonly queryKey: ReadonlyArray<unknown> },
+  Options = Record<string, unknown>
+> =
+  | ReadonlyArray<string>
+  | {
+    readonly id: string
+    readonly options?: ClientForOptions
+  }
+  | {
+    readonly filters: Filters
+    readonly options?: Options
+  }
 
-type SchemaOrFields<T> = T extends S.Top ? T : T extends S.Struct.Fields ? S.Struct<T> : S.Void
+export type InvalidationCallback<Resources, Input = unknown, Success = unknown, Failure = unknown> = (
+  queryKey: readonly string[],
+  resources: QueryOnlyResources<Resources>,
+  ...args: [Input] extends [void] ? [exit: Exit.Exit<Success, Failure>]
+    : [input: Input, exit: Exit.Exit<Success, Failure>]
+) => ReadonlyArray<InvalidateQueryInstruction>
+
+export type InvalidationConfig<Resources, Input = unknown, Success = unknown, Failure = unknown> = {
+  readonly invalidatesQueries: InvalidationCallback<Resources, Input, Success, Failure>
+  readonly invalidationResources?: Resources
+  readonly disableQueryInvalidation?: boolean
+}
+
+type InvalidationConfigForCommand<
+  Resources,
+  Payload extends S.Struct.Fields,
+  Success extends S.Top,
+  Error extends S.Top
+> = InvalidationConfig<
+  Resources,
+  InputFromPayload<Payload>,
+  OutputFromSuccess<Success>,
+  Error["Type"]
+>
+
+export const configureInvalidation = <Resources>() =>
+<Input, Success, Failure>(
+  invalidatesQueries: InvalidationCallback<Resources, NoInfer<Input>, NoInfer<Success>, NoInfer<Failure>>
+): InvalidationConfig<Resources, Input, Success, Failure> => ({ invalidatesQueries })
+
+export const configureInvalidationCallback = <Resources>() =>
+<Input, Success, Failure>(
+  invalidatesQueries: InvalidationCallback<Resources, NoInfer<Input>, NoInfer<Success>, NoInfer<Failure>>
+): InvalidationCallback<Resources, Input, Success, Failure> => invalidatesQueries
+
+export const configureInvalidationResources = <Resources>() =>
+  ({}) as Pick<InvalidationConfig<Resources>, "invalidationResources">
 
 type TaggedRequestForResult<
   Self,
@@ -24,119 +108,451 @@ type TaggedRequestForResult<
   Success extends S.Top,
   Error extends S.Top,
   Config,
-  ModuleName extends string
+  ModuleName extends string,
+  Type extends "command" | "query",
+  Stream extends boolean,
+  Resources = never,
+  Final extends S.Top = never,
+  Middleware = unknown
 > =
-  & S.EnhancedClass<Self, S.TaggedStruct<Tag, Payload>, {}>
+  & S.Opaque<Self, S.ExtendedSchemaNoEncoded, TaggedRequestSchema<Tag, Payload>, {}>
   & {
+    readonly fields: TaggedRequestSchema<Tag, Payload>["fields"]
     readonly _tag: Tag
     readonly success: Success
     readonly error: Error
     readonly config: Config
-    readonly "~decodingServices": S.Codec.DecodingServices<Success> | S.Codec.DecodingServices<Error>
-    readonly "~encodingServices": S.Codec.EncodingServices<Success> | S.Codec.EncodingServices<Error>
     readonly id: `${ModuleName}.${Tag}`
     readonly moduleName: ModuleName
+    readonly type: Type
+    readonly stream: Stream
+    readonly middleware?: Middleware
+    readonly "~invalidationResources"?: Resources
   }
+  & ([Final] extends [never] ? {} : { readonly final: Final })
 
 export const makeRpcClient = <
-  RequestContextMap extends RequestContextMapTagAny,
+  Middleware extends ClientMiddleware<Record<string, RpcContextMap.Any>>,
   GeneralErrors extends S.Top = never
->(rcs: RequestContextMap, generalErrors?: GeneralErrors) => {
+>(middleware: Middleware, generalErrors?: GeneralErrors) => {
   // Long way around Context/C extends etc to support actual jsdoc from passed in RequestConfig etc... (??)
   type ServiceMap = {
     success: S.Top | S.Struct.Fields // SchemaOrFields will make a Schema type out of Struct.Fields
     error: S.Top | S.Struct.Fields // SchemaOrFields will make a Schema type out of Struct.Fields
+    final?: S.Top | S.Struct.Fields // optional final-value schema for stream requests
+    stream?: boolean // request metadata — stripped from stored config
   }
 
-  type RequestConfig = GetContextConfig<RequestContextMap["config"]>
+  type RequestConfig = GetContextConfig<Middleware["requestContextMap"]>
 
+  // Errors raised by RPC middleware (e.g. `NotLoggedInError` from auth) used to
+  // be merged into `resource.error` here so they would surface in the wire
+  // failure schema. That merging is gone — the canonical source for middleware
+  // errors is now the middleware tag attached to the rpc on both server and
+  // client (see `ApiClientFactory.makeFor({ middleware })`). `Rpc.exitSchema`
+  // unions in `rpc.middlewares[*].error` automatically.
   type MergeError<E> = [GeneralErrors] extends [never] ? SchemaOrFields<E> : S.Union<[SchemaOrFields<E>, GeneralErrors]>
   type ErrorResult<C> = C extends { error: infer E } ? MergeError<E>
-    : [GeneralErrors] extends [never] ? GetEffectError<RequestContextMap["config"], C>
-    : MergeError<GetEffectError<RequestContextMap["config"], C>>
-
-  // TODO: filter errors based on config + take care of inversion
-  const errorSchemas = Object.values(rcs.config).map((_) => _.error)
+    : [GeneralErrors] extends [never] ? typeof S.Never
+    : GeneralErrors
 
-  function makeRequestClass<Tag extends string, Fields extends S.Struct.Fields, C extends ServiceMap>(
+  function makeRequestClass<Tag extends string, Fields extends S.Struct.Fields, C extends Partial<ServiceMap>>(
     tag: Tag,
     fields: Fields,
     config?: C
   ) {
     const failureSchema = merge(
       config?.error ? S.isSchema(config.error) ? config.error : S.Struct(config.error) : undefined,
-      [...errorSchemas, generalErrors].filter(Boolean)
+      [generalErrors].filter(Boolean)
     )
     const successSchema = config?.success
       ? S.isSchema(config.success)
-        ? AST.isVoid(config.success.ast) ? ForceVoid : config.success
+        ? AST.isVoid(config.success.ast) ? S.Void : config.success
         : S.Struct(config.success)
-      : ForceVoid
+      : S.Void
+
+    const finalConfig = (config as any)?.final
+    const finalSchema = finalConfig && S.isSchema(finalConfig) ? finalConfig : undefined
+
+    // Strip stream from the stored config — it's request metadata, not handler config
+    const { stream: _stream, ...restConfig } = config ?? ({} as C)
 
-    const RequestClass = S.TaggedClass<any>()(tag, fields)
+    const RequestClass = S.Opaque()(S.TaggedStruct(tag, fields))
     Object.assign(RequestClass, {
       _tag: tag,
       success: successSchema,
       error: failureSchema,
-      config
+      ...(finalSchema !== undefined ? { final: finalSchema } : {}),
+      config: restConfig
     })
 
     return RequestClass
   }
 
-  function TaggedRequestFor<ModuleName extends string>(moduleName: ModuleName) {
-    function TaggedRequestWithMeta<Self>(): {
-      <Tag extends string, Payload extends S.Struct.Fields, C extends ServiceMap>(
+  function makeTaggedRequestWithMeta<
+    ModuleName extends string,
+    Type extends "command" | "query"
+  >(
+    moduleName: ModuleName,
+    type: Type
+  ) {
+    function TaggedRequestWithMeta<Self, Resources extends InvalidationResources = never>(): {
+      // ─── stream: true overloads (must come before non-stream so TypeScript picks them) ───────────
+      <
+        Tag extends string,
+        Payload extends S.Struct.Fields,
+        Success extends S.Top | S.Struct.Fields,
+        Error extends S.Top | S.Struct.Fields,
+        Final extends S.Top | S.Struct.Fields = never,
+        C extends RequestConfig & Record<string, any> = RequestConfig & Record<string, any>
+      >(
         tag: Tag,
         fields: Payload,
-        config: RequestConfig & C
+        config:
+          & Omit<C, "invalidatesQueries">
+          & { stream: true; success: Success; error: Error; final?: Final },
+        invalidatesQueries?: InvalidationCallback<
+          Resources,
+          InputFromPayload<Payload>,
+          OutputFromSuccess<SchemaOrFields<Success>>,
+          ErrorResult<C & { success: Success; error: Error }>["Type"]
+        >
       ): TaggedRequestForResult<
         Self,
         Tag,
         Payload,
-        SchemaOrFields<C["success"]>,
-        ErrorResult<C>,
-        Omit<C, "success" | "error">,
-        ModuleName
+        SchemaOrFields<Success>,
+        ErrorResult<C & { success: Success; error: Error }>,
+        Omit<
+          & Omit<C, "invalidatesQueries">
+          & {
+            success: Success
+            error: Error
+          }
+          & Partial<
+            InvalidationConfigForCommand<
+              Resources,
+              Payload,
+              SchemaOrFields<Success>,
+              ErrorResult<C & { success: Success; error: Error }>
+            >
+          >,
+          "success" | "error" | "stream"
+        >,
+        ModuleName,
+        Type,
+        true,
+        Resources,
+        [Final] extends [never] ? never : SchemaOrFields<Final>,
+        Middleware
       >
-      <Tag extends string, Payload extends S.Struct.Fields, C extends Pick<ServiceMap, "success">>(
+      <
+        Tag extends string,
+        Payload extends S.Struct.Fields,
+        Success extends S.Top | S.Struct.Fields,
+        Final extends S.Top | S.Struct.Fields = never,
+        C extends RequestConfig & Record<string, any> & { error?: never } =
+          & RequestConfig
+          & Record<string, any>
+          & { error?: never }
+      >(
         tag: Tag,
         fields: Payload,
-        config: RequestConfig & C
+        config:
+          & Omit<C, "invalidatesQueries">
+          & { stream: true; success: Success; final?: Final },
+        invalidatesQueries?: InvalidationCallback<
+          Resources,
+          InputFromPayload<Payload>,
+          OutputFromSuccess<SchemaOrFields<Success>>,
+          ErrorResult<C & { success: Success }>["Type"]
+        >
       ): TaggedRequestForResult<
         Self,
         Tag,
         Payload,
-        SchemaOrFields<C["success"]>,
-        ErrorResult<C>,
-        Omit<C, "success" | "error">,
-        ModuleName
+        SchemaOrFields<Success>,
+        ErrorResult<C & { success: Success }>,
+        Omit<
+          & Omit<C, "invalidatesQueries">
+          & { success: Success }
+          & Partial<
+            InvalidationConfigForCommand<
+              Resources,
+              Payload,
+              SchemaOrFields<Success>,
+              ErrorResult<C & { success: Success }>
+            >
+          >,
+          "success" | "error" | "stream"
+        >,
+        ModuleName,
+        Type,
+        true,
+        Resources,
+        [Final] extends [never] ? never : SchemaOrFields<Final>,
+        Middleware
       >
-      <Tag extends string, Payload extends S.Struct.Fields, C extends Pick<ServiceMap, "error">>(
+      // ─── stream: true without `success` overloads ────────────────────────────────────────────────
+      <
+        Tag extends string,
+        Payload extends S.Struct.Fields,
+        Error extends S.Top | S.Struct.Fields,
+        C extends RequestConfig & Record<string, any> & { success?: never } =
+          & RequestConfig
+          & Record<string, any>
+          & { success?: never }
+      >(
         tag: Tag,
         fields: Payload,
-        config: RequestConfig & C
+        config:
+          & Omit<C, "invalidatesQueries">
+          & { stream: true; error: Error },
+        invalidatesQueries?: InvalidationCallback<
+          Resources,
+          InputFromPayload<Payload>,
+          void,
+          ErrorResult<C & { error: Error }>["Type"]
+        >
       ): TaggedRequestForResult<
         Self,
         Tag,
         Payload,
-        typeof ForceVoid,
+        typeof S.Void,
+        ErrorResult<C & { error: Error }>,
+        Omit<
+          & Omit<C, "invalidatesQueries">
+          & { error: Error }
+          & Partial<
+            InvalidationConfigForCommand<
+              Resources,
+              Payload,
+              typeof S.Void,
+              ErrorResult<C & { error: Error }>
+            >
+          >,
+          "success" | "error" | "stream"
+        >,
+        ModuleName,
+        Type,
+        true,
+        Resources,
+        never,
+        Middleware
+      >
+      <
+        Tag extends string,
+        Payload extends S.Struct.Fields,
+        C extends RequestConfig & Record<string, any> & { success?: never; error?: never } =
+          & RequestConfig
+          & Record<string, any>
+          & { success?: never; error?: never }
+      >(
+        tag: Tag,
+        fields: Payload,
+        config:
+          & Omit<C, "invalidatesQueries">
+          & { stream: true },
+        invalidatesQueries?: InvalidationCallback<
+          Resources,
+          InputFromPayload<Payload>,
+          void,
+          ErrorResult<C>["Type"]
+        >
+      ): TaggedRequestForResult<
+        Self,
+        Tag,
+        Payload,
+        typeof S.Void,
         ErrorResult<C>,
-        Omit<C, "success" | "error">,
-        ModuleName
+        Omit<
+          & Omit<C, "invalidatesQueries">
+          & Partial<InvalidationConfigForCommand<Resources, Payload, typeof S.Void, ErrorResult<C>>>,
+          "success" | "error" | "stream"
+        >,
+        ModuleName,
+        Type,
+        true,
+        Resources,
+        never,
+        Middleware
+      >
+      // ─── non-stream overloads ────────────────────────────────────────────────────────────────────
+      <
+        Tag extends string,
+        Payload extends S.Struct.Fields,
+        Success extends S.Top | S.Struct.Fields,
+        Error extends S.Top | S.Struct.Fields,
+        Final extends S.Top | S.Struct.Fields = never,
+        C extends RequestConfig & Record<string, any> = RequestConfig & Record<string, any>
+      >(
+        tag: Tag,
+        fields: Payload,
+        config:
+          & Omit<C, "invalidatesQueries">
+          & { success: Success; error: Error; final?: Final },
+        invalidatesQueries?: InvalidationCallback<
+          Resources,
+          InputFromPayload<Payload>,
+          OutputFromSuccess<SchemaOrFields<Success>>,
+          ErrorResult<C & { success: Success; error: Error }>["Type"]
+        >
+      ): TaggedRequestForResult<
+        Self,
+        Tag,
+        Payload,
+        SchemaOrFields<Success>,
+        ErrorResult<C & { success: Success; error: Error }>,
+        Omit<
+          & Omit<C, "invalidatesQueries">
+          & {
+            success: Success
+            error: Error
+          }
+          & Partial<
+            InvalidationConfigForCommand<
+              Resources,
+              Payload,
+              SchemaOrFields<Success>,
+              ErrorResult<C & { success: Success; error: Error }>
+            >
+          >,
+          "success" | "error" | "stream"
+        >,
+        ModuleName,
+        Type,
+        false,
+        Resources,
+        [Final] extends [never] ? never : SchemaOrFields<Final>,
+        Middleware
+      >
+      <
+        Tag extends string,
+        Payload extends S.Struct.Fields,
+        Success extends S.Top | S.Struct.Fields,
+        Final extends S.Top | S.Struct.Fields = never,
+        C extends RequestConfig & Record<string, any> & { error?: never } =
+          & RequestConfig
+          & Record<string, any>
+          & {
+            error?: never
+          }
+      >(
+        tag: Tag,
+        fields: Payload,
+        config:
+          & Omit<C, "invalidatesQueries">
+          & { success: Success; final?: Final },
+        invalidatesQueries?: InvalidationCallback<
+          Resources,
+          InputFromPayload<Payload>,
+          OutputFromSuccess<SchemaOrFields<Success>>,
+          ErrorResult<C & { success: Success }>["Type"]
+        >
+      ): TaggedRequestForResult<
+        Self,
+        Tag,
+        Payload,
+        SchemaOrFields<Success>,
+        ErrorResult<C & { success: Success }>,
+        Omit<
+          & Omit<C, "invalidatesQueries">
+          & {
+            success: Success
+          }
+          & Partial<
+            InvalidationConfigForCommand<
+              Resources,
+              Payload,
+              SchemaOrFields<Success>,
+              ErrorResult<C & { success: Success }>
+            >
+          >,
+          "success" | "error" | "stream"
+        >,
+        ModuleName,
+        Type,
+        false,
+        Resources,
+        [Final] extends [never] ? never : SchemaOrFields<Final>,
+        Middleware
+      >
+      <
+        Tag extends string,
+        Payload extends S.Struct.Fields,
+        Error extends S.Top | S.Struct.Fields,
+        C extends RequestConfig & Record<string, any> & { success?: never }
+      >(
+        tag: Tag,
+        fields: Payload,
+        config:
+          & Omit<C, "invalidatesQueries">
+          & { error: Error },
+        invalidatesQueries?: InvalidationCallback<
+          Resources,
+          InputFromPayload<Payload>,
+          void,
+          ErrorResult<C & { error: Error }>["Type"]
+        >
+      ): TaggedRequestForResult<
+        Self,
+        Tag,
+        Payload,
+        typeof S.Void,
+        ErrorResult<C & { error: Error }>,
+        Omit<
+          & Omit<C, "invalidatesQueries">
+          & {
+            error: Error
+          }
+          & Partial<
+            InvalidationConfigForCommand<
+              Resources,
+              Payload,
+              typeof S.Void,
+              ErrorResult<C & { error: Error }>
+            >
+          >,
+          "success" | "error" | "stream"
+        >,
+        ModuleName,
+        Type,
+        false,
+        Resources,
+        never,
+        Middleware
       >
-      <Tag extends string, Payload extends S.Struct.Fields, C extends Record<string, any>>(
+      <
+        Tag extends string,
+        Payload extends S.Struct.Fields,
+        C extends RequestConfig & Record<string, any> & { success?: never; error?: never }
+      >(
         tag: Tag,
         fields: Payload,
-        config: C & RequestConfig
+        config: Omit<C, "invalidatesQueries">,
+        invalidatesQueries?: InvalidationCallback<
+          Resources,
+          InputFromPayload<Payload>,
+          void,
+          ErrorResult<C>["Type"]
+        >
       ): TaggedRequestForResult<
         Self,
         Tag,
         Payload,
-        typeof ForceVoid,
+        typeof S.Void,
         ErrorResult<C>,
-        Omit<C, "success" | "error">,
-        ModuleName
+        Omit<
+          & Omit<C, "invalidatesQueries">
+          & Partial<InvalidationConfigForCommand<Resources, Payload, typeof S.Void, ErrorResult<C>>>,
+          "success" | "error" | "stream"
+        >,
+        ModuleName,
+        Type,
+        false,
+        Resources,
+        never,
+        Middleware
       >
       <Tag extends string, Payload extends S.Struct.Fields>(
         tag: Tag,
@@ -145,23 +561,66 @@ export const makeRpcClient = <
         Self,
         Tag,
         Payload,
-        typeof ForceVoid,
+        typeof S.Void,
         ErrorResult<{}>,
-        Record<string, never>,
-        ModuleName
+        // Empty config, NOT `Record<string, never>`: the config type flows into
+        // `GetEffectContext`/`GetEffectError` as `T`, and `keyof Record<string, never>`
+        // is `string` — so an inverted key like `allowAnonymous` would satisfy
+        // `key extends keyof T`, then `T[key]` (`never`) `extends true` (true, since
+        // `never` is assignable to everything) and the middleware wrongly takes the
+        // "allowAnonymous: true" (anonymous) branch, dropping `UserProfile`. `{}` has
+        // `keyof {} = never`, so no config key is treated as set and the defaults
+        // (auth required, `UserProfile` provided) apply — same as passing `{}` explicitly.
+        {},
+        ModuleName,
+        Type,
+        false,
+        never,
+        never,
+        Middleware
       >
     } {
       return (<Tag extends string, Fields extends S.Struct.Fields, C extends ServiceMap>(
         tag: Tag,
         fields: Fields,
-        config?: C
+        config?: C,
+        invalidatesQueries?: InvalidationCallback<Resources>
       ) => {
-        const cls = makeRequestClass(tag, fields, config)
-        Object.assign(cls, { id: `${moduleName}.${tag}`, moduleName })
+        const isStream = (config as any)?.stream === true
+        const requestConfig = invalidatesQueries === undefined ? config : { ...config, invalidatesQueries }
+        const cls = makeRequestClass(tag, fields, requestConfig)
+        Object.assign(cls, {
+          id: `${moduleName}.${tag}`,
+          moduleName,
+          type,
+          stream: isStream,
+          middleware
+        })
         return cls
       }) as any
     }
-    return Object.assign(TaggedRequestWithMeta, { moduleName } as const)
+    return Object.assign(TaggedRequestWithMeta, { moduleName, type } as const)
+  }
+
+  function TaggedRequestFor<ModuleName extends string>(moduleName: ModuleName) {
+    const Query = makeTaggedRequestWithMeta(moduleName, "query")
+    const Command = makeTaggedRequestWithMeta(moduleName, "command")
+
+    return {
+      moduleName,
+      /**
+       * Create query request classes for this module.
+       * Queries read state and should not mutate server state.
+       * Pass `stream: true` in the config to produce a Stream of `success` values (QueryStream behaviour).
+       */
+      Query,
+      /**
+       * Create command request classes for this module.
+       * Commands mutate state and should avoid returning complex read models.
+       * Pass `stream: true` in the config to produce a Stream of `success` values (CommandStream behaviour).
+       */
+      Command
+    } as const
   }
 
   return {