feat(app): add auto-dispatching createClient via dispatcher registry

- Add DispatchersFor types and default dispatcher registry\n- Generate dispatchers-by-path module that registers defaults\n- Update examples and add tests for auto-dispatching client

Author: skulidropek

packages/app/examples/strict-error-handling.ts

@@ -8,9 +8,9 @@
 
 import * as FetchHttpClient from "@effect/platform/FetchHttpClient"
 import type * as HttpClient from "@effect/platform/HttpClient"
-import { Console, Effect, Exit, Match } from "effect"
-import { createClient, type ClientOptions } from "../src/shell/api-client/create-client.js"
-import { dispatchercreatePet, dispatchergetPet, dispatcherlistPets } from "../src/generated/dispatch.js"
+import { Cause, Console, Effect, Match } from "effect"
+import "../src/generated/dispatchers-by-path.js"
+import { type ClientOptions, createClient } from "../src/shell/api-client/create-client.js"
 import type { Paths } from "../tests/fixtures/petstore.openapi.js"
 
 /**
@@ -21,6 +21,16 @@ const clientOptions: ClientOptions = {
   credentials: "include"
 }
 
+// CHANGE: Use default dispatcher registry (registered by generated module)
+// WHY: Call createClient(options) without passing dispatcher map
+// QUOTE(ТЗ): "const apiClient = createClient<Paths>(clientOptions)"
+// REF: user-msg-4
+// SOURCE: n/a
+// FORMAT THEOREM: ∀ op ∈ Operations: createClient(options) uses registered dispatchers
+// PURITY: SHELL
+// EFFECT: none
+// INVARIANT: default dispatchers registered before client creation
+// COMPLEXITY: O(1)
 const apiClient = createClient<Paths>(clientOptions)
 
 // =============================================================================
@@ -45,14 +55,9 @@ export const getPetStrictProgram: Effect.Effect<void, never, HttpClient.HttpClie
   yield* Console.log("=== getPet: Strict Error Handling ===")
 
   // Execute request - yields only on 200
-  const result = yield* apiClient.GET(
-    "/pets/{petId}",
-    dispatchergetPet,
-    { params: { petId: "123" } }
+  yield* apiClient.GET("/pets/{petId}", { params: { petId: "123" } }).pipe(
+    Effect.tap((result) => Console.log(`Got pet: ${result.body.name}`))
   )
-
-  // Success! TypeScript knows status is 200
-  yield* Console.log(`Got pet: ${result.body.name}`)
 }).pipe(
   // Handle HttpError with EXHAUSTIVE matching (no orElse!)
   Effect.catchTag("HttpError", (error) =>
@@ -66,7 +71,7 @@ export const getPetStrictProgram: Effect.Effect<void, never, HttpClient.HttpClie
   // Handle ALL boundary errors
   Effect.catchTag("TransportError", (e) => Console.log(`Transport error: ${e.error.message}`)),
   Effect.catchTag("UnexpectedStatus", (e) => Console.log(`Unexpected status: ${e.status}`)),
-  Effect.catchTag("UnexpectedContentType", (e) => Console.log(`Unexpected content-type: ${e.actual}`)),
+  Effect.catchTag("UnexpectedContentType", (e) => Console.log(`Unexpected content-type: ${e.actual ?? "unknown"}`)),
   Effect.catchTag("ParseError", (e) => Console.log(`Parse error: ${e.error.message}`)),
   Effect.catchTag("DecodeError", (e) => Console.log(`Decode error: ${e.error.message}`))
 )
@@ -87,17 +92,15 @@ export const getPetStrictProgram: Effect.Effect<void, never, HttpClient.HttpClie
 export const createPetStrictProgram: Effect.Effect<void, never, HttpClient.HttpClient> = Effect.gen(function*() {
   yield* Console.log("=== createPet: Strict Error Handling ===")
 
-  const result = yield* apiClient.POST(
+  yield* apiClient.POST(
     "/pets",
-    dispatchercreatePet,
     {
       // Body can be typed object - client will auto-stringify and set Content-Type
       body: { name: "Fluffy", tag: "cat" }
     }
+  ).pipe(
+    Effect.tap((result) => Console.log(`Created pet: ${result.body.id}`))
   )
-
-  // Success! TypeScript knows status is 201
-  yield* Console.log(`Created pet: ${result.body.id}`)
 }).pipe(
   // Handle HttpError with EXHAUSTIVE matching
   Effect.catchTag("HttpError", (error) =>
@@ -110,7 +113,7 @@ export const createPetStrictProgram: Effect.Effect<void, never, HttpClient.HttpC
   // Handle ALL boundary errors
   Effect.catchTag("TransportError", (e) => Console.log(`Transport error: ${e.error.message}`)),
   Effect.catchTag("UnexpectedStatus", (e) => Console.log(`Unexpected status: ${e.status}`)),
-  Effect.catchTag("UnexpectedContentType", (e) => Console.log(`Unexpected content-type: ${e.actual}`)),
+  Effect.catchTag("UnexpectedContentType", (e) => Console.log(`Unexpected content-type: ${e.actual ?? "unknown"}`)),
   Effect.catchTag("ParseError", (e) => Console.log(`Parse error: ${e.error.message}`)),
   Effect.catchTag("DecodeError", (e) => Console.log(`Decode error: ${e.error.message}`))
 )
@@ -131,14 +134,13 @@ export const createPetStrictProgram: Effect.Effect<void, never, HttpClient.HttpC
 export const listPetsStrictProgram: Effect.Effect<void, never, HttpClient.HttpClient> = Effect.gen(function*() {
   yield* Console.log("=== listPets: Strict Error Handling ===")
 
-  const result = yield* apiClient.GET(
-    "/pets",
-    dispatcherlistPets,
-    { query: { limit: 10 } }
+  yield* apiClient.GET("/pets", { query: { limit: 10 } }).pipe(
+    Effect.tap((result) => Console.log(`Got ${result.body.length} pets`))
   )
 
-  // Success! TypeScript knows status is 200
-  yield* Console.log(`Got ${result.body.length} pets`)
+  const pets = yield* apiClient.GET("/pets", { query: { limit: 10 } })
+
+  yield* Console.log(`Got ${pets.body.length} pets`)
 }).pipe(
   // Handle HttpError with EXHAUSTIVE matching
   Effect.catchTag("HttpError", (error) =>
@@ -150,7 +152,7 @@ export const listPetsStrictProgram: Effect.Effect<void, never, HttpClient.HttpCl
   // Handle ALL boundary errors
   Effect.catchTag("TransportError", (e) => Console.log(`Transport error: ${e.error.message}`)),
   Effect.catchTag("UnexpectedStatus", (e) => Console.log(`Unexpected status: ${e.status}`)),
-  Effect.catchTag("UnexpectedContentType", (e) => Console.log(`Unexpected content-type: ${e.actual}`)),
+  Effect.catchTag("UnexpectedContentType", (e) => Console.log(`Unexpected content-type: ${e.actual ?? "unknown"}`)),
   Effect.catchTag("ParseError", (e) => Console.log(`Parse error: ${e.error.message}`)),
   Effect.catchTag("DecodeError", (e) => Console.log(`Decode error: ${e.error.message}`))
 )
@@ -183,22 +185,19 @@ const mainProgram: Effect.Effect<void, never, HttpClient.HttpClient> = Effect.ge
   yield* Console.log("========================================")
 })
 
-/**
- * Execute the program
- *
- * CRITICAL: Since mainProgram has E=never, Effect.runPromiseExit
- * will never fail with a typed error - only defects are possible.
- */
+// CHANGE: Remove async/await entrypoint and handle defects in Effect
+// WHY: Lint rules forbid async/await and floating promises; defects are handled in Effect channel
+// QUOTE(ТЗ): "Запрещён async/await — используй Effect.gen / Effect.tryPromise."
+// REF: user-msg-2
+// SOURCE: n/a
+// FORMAT THEOREM: For all exits, mainProgram E=never implies failure(exit) -> defect(exit)
+// PURITY: SHELL
+// EFFECT: Effect<void, never, HttpClient> -> Promise<void> via Effect.runPromise
+// INVARIANT: Typed error channel remains never
+// COMPLEXITY: O(1)
 const program = mainProgram.pipe(
-  Effect.provide(FetchHttpClient.layer)
+  Effect.provide(FetchHttpClient.layer),
+  Effect.catchAllCause((cause) => Console.error(`Unexpected defect: ${Cause.pretty(cause)}`))
 )
 
-const main = async () => {
-  const exit = await Effect.runPromiseExit(program)
-  if (Exit.isFailure(exit)) {
-    // This can only be a defect (unexpected exception), not a typed error
-    console.error("Unexpected defect:", exit.cause)
-  }
-}
-
-main()
+void Effect.runPromise(program)

packages/app/examples/test-create-client.ts

@@ -8,8 +8,11 @@
 
 import * as FetchHttpClient from "@effect/platform/FetchHttpClient"
 import { Console, Effect, Exit, Match } from "effect"
-import { createClient, type ClientOptions } from "../src/shell/api-client/create-client.js"
-import { dispatchercreatePet, dispatchergetPet, dispatcherlistPets } from "../src/generated/dispatch.js"
+import {
+  createClient,
+  type ClientOptions
+} from "../src/shell/api-client/create-client.js"
+import "../src/generated/dispatchers-by-path.js"
 import type { Paths } from "../tests/fixtures/petstore.openapi.js"
 // Types are automatically inferred - no need to import them explicitly
 
@@ -24,6 +27,16 @@ const clientOptions: ClientOptions = {
   credentials: "include"
 }
 
+// CHANGE: Use default dispatcher registry (registered by generated module)
+// WHY: Call createClient(options) without passing dispatcher map
+// QUOTE(ТЗ): "const apiClient = createClient<Paths>(clientOptions)"
+// REF: user-msg-4
+// SOURCE: n/a
+// FORMAT THEOREM: ∀ op ∈ Operations: createClient(options) uses registered dispatchers
+// PURITY: SHELL
+// EFFECT: none
+// INVARIANT: default dispatchers registered before client creation
+// COMPLEXITY: O(1)
 const apiClient = createClient<Paths>(clientOptions)
 
 /**
@@ -44,7 +57,6 @@ const listAllPetsExample = Effect.gen(function*() {
   // Now: success = 200 only, error = 500 | BoundaryError
   const result = yield* apiClient.GET(
     "/pets",
-    dispatcherlistPets,
     {
       query: { limit: 10 }
     }
@@ -83,7 +95,6 @@ const getPetExample = Effect.gen(function*() {
   // Success = 200, Error = 404 | 500 | BoundaryError
   const result = yield* apiClient.GET(
     "/pets/{petId}",
-    dispatchergetPet,
     {
       params: { petId: "123" }
     }
@@ -125,7 +136,6 @@ const createPetExample = Effect.gen(function*() {
   // Success = 201, Error = 400 | 500 | BoundaryError
   const result = yield* apiClient.POST(
     "/pets",
-    dispatchercreatePet,
     {
       // Typed body - client will auto-stringify and set Content-Type
       body: newPet
@@ -159,7 +169,7 @@ const eitherExample = Effect.gen(function*() {
   yield* Console.log("\n=== Example 4: Using Effect.either ===")
 
   const result = yield* Effect.either(
-    apiClient.GET("/pets/{petId}", dispatchergetPet, {
+    apiClient.GET("/pets/{petId}", {
       params: { petId: "999" } // Non-existent pet
     })
   )
@@ -199,7 +209,7 @@ const mainProgram = Effect.gen(function*() {
   yield* Console.log("  - Developers MUST handle HTTP errors explicitly!\n")
 
   yield* Console.log("Example code:")
-  yield* Console.log('  const result = yield* client.GET("/path", dispatcher)')
+  yield* Console.log('  const result = yield* client.GET("/path", { params })')
   yield* Console.log("  // result is 200 - no need to check status!")
   yield* Console.log("").pipe(Effect.flatMap(() =>
     Console.log("  // HTTP errors handled via Effect.catchTag or Effect.match\n")

packages/app/src/core/axioms.ts

@@ -133,3 +133,11 @@ export type ClassifyFn = (
  * @pure true
  */
 export const asStrictApiClient = <T>(client: object): T => client as T
+
+/**
+ * Cast default dispatchers registry to specific schema type
+ * AXIOM: Default dispatcher registry was registered for the current Paths type
+ *
+ * @pure true
+ */
+export const asDispatchersFor = <T>(value: unknown): T => value as T

packages/app/src/generated/dispatchers-by-path.ts

@@ -0,0 +1,40 @@
+// CHANGE: Auto-generated dispatcher map by path+method
+// WHY: Provide a single dispatcher registry without manual wiring in examples
+// QUOTE(ТЗ): "Этого в плане вообще не должно быть"
+// REF: user-msg-3
+// SOURCE: Generated from tests/fixtures/petstore.openapi.json
+// FORMAT THEOREM: ∀ path, method: dispatchersByPath[path][method] = dispatcher(op)
+// PURITY: SHELL
+// EFFECT: none
+// INVARIANT: dispatcher map is total for all operations in Paths
+// COMPLEXITY: O(1)
+
+import type { Paths } from "../../tests/fixtures/petstore.openapi.js"
+import { type DispatchersFor, registerDefaultDispatchers } from "../shell/api-client/create-client.js"
+import { dispatchercreatePet, dispatcherdeletePet, dispatchergetPet, dispatcherlistPets } from "./dispatch.js"
+
+/**
+ * Dispatcher map keyed by OpenAPI path and HTTP method
+ */
+export const dispatchersByPath: DispatchersFor<Paths> = {
+  "/pets": {
+    get: dispatcherlistPets,
+    post: dispatchercreatePet
+  },
+  "/pets/{petId}": {
+    get: dispatchergetPet,
+    delete: dispatcherdeletePet
+  }
+}
+
+// CHANGE: Register default dispatchers at module load
+// WHY: Enable createClient(options) without passing dispatcher map
+// QUOTE(ТЗ): "const apiClient = createClient<Paths>(clientOptions)"
+// REF: user-msg-4
+// SOURCE: n/a
+// FORMAT THEOREM: ∀ call: createClient(options) uses dispatchersByPath
+// PURITY: SHELL
+// EFFECT: none
+// INVARIANT: registerDefaultDispatchers is called exactly once per module load
+// COMPLEXITY: O(1)
+registerDefaultDispatchers(dispatchersByPath)

packages/app/src/generated/index.ts

@@ -6,3 +6,4 @@
 
 export * from "./decoders.js"
 export * from "./dispatch.js"
+export * from "./dispatchers-by-path.js"

packages/app/src/index.ts

@@ -8,7 +8,13 @@
 
 // High-level API (recommended for most users)
 export { createClient as default } from "./shell/api-client/create-client.js"
-export type { ClientOptions, StrictApiClient } from "./shell/api-client/create-client.js"
+export type {
+  ClientOptions,
+  DispatchersFor,
+  StrictApiClient,
+  StrictApiClientWithDispatchers
+} from "./shell/api-client/create-client.js"
+export { registerDefaultDispatchers } from "./shell/api-client/create-client.js"
 
 // Core types (for advanced type manipulation)
 // Effect Channel Design: