docs(typed-channel): recommend calc transforms and document Ash version requirements

Author: Torkan

AGENTS.md

@@ -130,9 +130,34 @@ listTodosChannel({
 
 ### Typed Channel Event Subscriptions
 
-For typed one-way push events from Ash PubSub publications:
+For typed one-way push events from Ash PubSub publications.
+
+**Recommended**: Use `transform :some_calc` to reference a resource calculation.
+Ash auto-derives the `returns` type when the calculation uses `:auto`, so
+AshTypescript gets the type information it needs without manual `returns` declarations.
 
 ```elixir
+# Resource with calculation transforms (recommended)
+defmodule MyApp.Post do
+  use Ash.Resource, notifiers: [Ash.Notifier.PubSub]
+
+  pub_sub do
+    module MyApp.Endpoint
+    prefix "posts"
+
+    publish :create, [:id], event: "post_created", public?: true, transform: :post_summary
+    publish :update, [:id], event: "post_updated", public?: true, transform: :post_summary
+  end
+
+  calculations do
+    calculate :post_summary, :auto, expr(%{id: id, title: title}) do
+      public? true
+    end
+  end
+  # ...
+end
+
+# Channel definition (unchanged — only references events)
 defmodule MyApp.OrgChannel do
   use AshTypescript.TypedChannel
 
@@ -147,6 +172,18 @@ defmodule MyApp.OrgChannel do
 end
 ```
 
+You can also use explicit `returns` with an anonymous function transform, but
+this requires manually keeping the type and transform in sync:
+
+```elixir
+publish :create, [:id],
+  event: "post_created",
+  public?: true,
+  returns: :map,
+  constraints: [fields: [id: [type: :uuid], title: [type: :string]]],
+  transform: fn notification -> %{id: notification.data.id, title: notification.data.title} end
+```
+
 ```typescript
 import { createOrgChannel, onOrgChannelMessages, unsubscribeOrgChannel } from './ash_typed_channels';
 
@@ -367,7 +404,7 @@ mix credo --strict                   # Linting
 | "No publication with event X found" | Typed channel event doesn't match any publication | Check `event:` option on the resource's `pub_sub` block |
 | "Duplicate event names found in typed_channel" | Same event name across resources in one channel | Use unique event names per channel |
 | "Payload type name conflict" | Same event name across different channels maps to different TS types | Rename events or ensure same `returns` type |
-| Channel `unknown` payload type | Publication missing `returns` option | Add `returns: :some_type` to the publication |
+| Channel `unknown` payload type | Publication missing `returns` type (no `transform :calc` or explicit `returns`) | Use `transform :some_calc` with an `:auto`-typed calculation (recommended), or add explicit `returns:` |
 | "not `public?`" error on RPC action | Action has `public? false` | Set `public? true` on the action or remove it from `typescript_rpc` |
 | "not `public?`" error on read_action | `read_action` has `public? false` | Set `public? true` on the read action |
 | "not `public?`" error on relationship read action | Relationship destination's read action has `public? false` | Set `public? true` on the destination's read action |

agent-docs/features/typed-channel.md

@@ -10,10 +10,16 @@ SPDX-License-Identifier: MIT
 
 The `AshTypescript.TypedChannel` DSL generates typed TypeScript event subscriptions from Ash PubSub publications. It reads the `returns` type from each declared publication and generates branded channel types, typed payload aliases, event maps, and subscription helper functions.
 
+**Recommended approach**: Use `transform :some_calc` on publications to reference a resource calculation. When the calculation uses `:auto` typing, Ash automatically derives the `returns` type from the expression, so AshTypescript gets full type information without any manual `returns` declarations. This keeps the type and the transform logic in sync via a single source of truth (the calculation). You can also use explicit `returns: :type` with an anonymous function transform, but this requires manually keeping the type and transform in sync.
+
 **Key distinction**: `AshTypescript.Rpc` with `generate_phx_channel_rpc_actions` is for request/response RPC over channels. `AshTypescript.TypedChannel` is for one-way push events (PubSub broadcasts) where the server pushes typed payloads to the client.
 
 **Important**: `AshTypescript.TypedChannel` is a standalone Spark DSL — completely independent from `Ash.Resource` and `AshTypescript.Rpc`. The developer owns channel authorization via Phoenix's `join/3`.
 
+## Requirements
+
+Typed channels require **Ash >= 3.17.1**, which introduced `returns`, `public?`, and calculation `transform` support on PubSub publications. **Ash >= 3.21.1 is recommended**, as it added support for `:auto`-typed calculations as transforms, allowing Ash to automatically derive the `returns` type from the calculation expression.
+
 ## Architecture
 
 ### Three-Layer Design
@@ -26,7 +32,8 @@ The `AshTypescript.TypedChannel` DSL generates typed TypeScript event subscripti
 │  - Compile-time verification (event existence, uniq)    │
 ├─────────────────────────────────────────────────────────┤
 │  Type Resolution Layer: Codegen                          │
-│  - Reads publication `returns` type from Ash PubSub     │
+│  - Reads `returns` type from publication (auto-derived  │
+│    via `transform :calc` or explicit `returns:`)        │
 │  - Maps types via TypeMapper.map_channel_payload_type   │
 │  - Plain object types (no __type/__primitiveFields)     │
 ├─────────────────────────────────────────────────────────┤
@@ -51,10 +58,67 @@ The Orchestrator appends channel types to the end of `ash_types.ts` after all re
 
 ### Type Mapping
 
-Channel payload types use `TypeMapper.map_channel_payload_type/2` instead of `map_type/3`. The difference: typed containers (maps/structs with `:fields`) generate plain object types without the `__type`/`__primitiveFields` metadata that the RPC field-selection system needs. Non-container types (primitives, lists, etc.) delegate to `map_type/3` with `:output` direction.
+Channel payload types use `TypeMapper.map_channel_payload_type/2` instead of `map_type/3`. The codegen reads the publication's `returns` type — which Ash auto-populates when `transform :some_calc` references a calculation, or which can be set explicitly via `returns:`. The difference from RPC types: typed containers (maps/structs with `:fields`) generate plain object types without the `__type`/`__primitiveFields` metadata that the RPC field-selection system needs. Non-container types (primitives, lists, etc.) delegate to `map_type/3` with `:output` direction.
 
 ## DSL Reference
 
+### Resource setup (recommended: calculation transforms)
+
+Publications should use `transform :some_calc` to reference a resource calculation.
+When the calculation uses `:auto` typing, Ash auto-derives `returns` from the expression:
+
+```elixir
+defmodule MyApp.Post do
+  use Ash.Resource, notifiers: [Ash.Notifier.PubSub]
+
+  pub_sub do
+    module MyApp.Endpoint
+    prefix "posts"
+
+    publish :create, [:id], event: "post_created", public?: true, transform: :post_summary
+    publish :update, [:id], event: "post_updated", public?: true, transform: :post_summary
+  end
+
+  calculations do
+    calculate :post_summary, :auto, expr(%{id: id, title: title}) do
+      public? true
+    end
+  end
+  # ...
+end
+
+defmodule MyApp.Comment do
+  use Ash.Resource, notifiers: [Ash.Notifier.PubSub]
+
+  pub_sub do
+    module MyApp.Endpoint
+    prefix "comments"
+
+    publish :create, [:id], event: "comment_created", public?: true, transform: :comment_body
+  end
+
+  calculations do
+    calculate :comment_body, :auto, expr(body) do
+      public? true
+    end
+  end
+  # ...
+end
+```
+
+You can also use explicit `returns` with an anonymous function transform:
+
+```elixir
+publish :create, [:id],
+  event: "post_created",
+  public?: true,
+  returns: :map,
+  constraints: [fields: [id: [type: :uuid], title: [type: :string]]],
+  transform: fn notification -> %{id: notification.data.id, title: notification.data.title} end
+```
+
+### Channel definition
+
 ```elixir
 defmodule MyApp.OrgChannel do
   use AshTypescript.TypedChannel
@@ -101,7 +165,7 @@ The `VerifyTypedChannel` verifier runs at compile time:
 | Event exists | Error | Each declared event must match a publication on the resource |
 | Unique events | Error | Event names must be unique across all resources in a channel |
 | `public?: true` | Warning | Publications should be marked `public?: true` |
-| `returns` set | Warning | Publications without `returns` produce `unknown` TypeScript type |
+| `returns` set | Warning | Publications without `returns` (no `transform :calc` or explicit `returns:`) produce `unknown` TypeScript type |
 
 ## Generated TypeScript
 
@@ -177,7 +241,7 @@ When `generate_all_channel_types/1` processes multiple channels, payload type al
 
 Before deduplication, `validate_no_payload_type_conflicts!/2` checks that events sharing a payload type name also share the same TypeScript type. If two events across different channels produce the same type name (e.g., `ItemCreatedPayload`) but map to different TypeScript types (e.g., `{id: UUID}` vs `string`), codegen raises a `RuntimeError` with details about the conflicting events and channels.
 
-This can happen when two resources declare publications with the same event name but different `returns` types, and those resources are used in separate channels. The verifier's unique-event check only applies within a single channel, so this cross-channel conflict is caught at codegen time instead.
+This can happen when two resources declare publications with the same event name but different `returns` types (whether auto-derived from calculation transforms or explicitly declared), and those resources are used in separate channels. The verifier's unique-event check only applies within a single channel, so this cross-channel conflict is caught at codegen time instead.
 
 ## Configuration
 
@@ -258,6 +322,6 @@ mix test test/ash_typescript/typed_channel/   # Typed channel tests
 | "No publication with event X found" | Event name doesn't match any publication on the resource | Check the `event:` option (or action name fallback) on the resource's `pub_sub` block |
 | "Duplicate event names found" | Same event name used across multiple resources in one channel | Use unique event names per channel |
 | "Payload type name conflict" | Same event name across different channels maps to different TypeScript types | Rename conflicting events or ensure they return the same type |
-| `unknown` TypeScript payload type | Publication missing `returns` option | Add `returns: :some_type` to the publication |
+| `unknown` TypeScript payload type | Publication missing `returns` type (no `transform :calc` or explicit `returns:`) | Use `transform :some_calc` with an `:auto`-typed calculation (recommended), or add explicit `returns:` |
 | Channel types not in output | `typed_channels` not configured | Add modules to `typed_channels: [...]` in config |
 | Channel functions not generated | `typed_channels_output_file` not configured | Set `typed_channels_output_file:` in config |

documentation/features/typed-channels.md

@@ -20,9 +20,19 @@ Use `AshTypescript.TypedChannel` when your application pushes events to clients
 | Client sends requests over WebSocket | [Channel-based RPC](phoenix-channels.md) |
 | Controller-style routes (Inertia, redirects) | [Typed Controllers](../guides/typed-controllers.md) |
 
+## Requirements
+
+Typed channels require **Ash >= 3.17.1**, which introduced `returns`, `public?`, and calculation `transform` support on PubSub publications. **Ash >= 3.21.1 is recommended**, as it added support for `:auto`-typed calculations as transforms, allowing Ash to automatically derive the `returns` type from the calculation expression.
+
 ## Quick Start
 
-### 1. Add PubSub publications with `returns` types
+### 1. Add PubSub publications with calculation transforms
+
+The recommended way to get typed payloads is to use `transform :some_calc` on
+publications, pointing to a resource calculation with `:auto` typing. Ash
+automatically derives the `returns` type from the calculation expression, so
+AshTypescript gets the type information it needs without manual `returns`
+declarations.
 
 ```elixir
 defmodule MyApp.Post do
@@ -37,28 +47,47 @@ defmodule MyApp.Post do
     publish :create, [:id],
       event: "post_created",
       public?: true,
-      returns: :map,
-      constraints: [
-        fields: [
-          id: [type: :uuid, allow_nil?: false],
-          title: [type: :string, allow_nil?: true]
-        ]
-      ],
-      transform: fn notification ->
-        %{id: notification.data.id, title: notification.data.title}
-      end
+      transform: :post_summary
 
     publish :update, [:id],
       event: "post_updated",
       public?: true,
-      returns: :string,
-      transform: fn notification -> notification.data.title end
+      transform: :post_title
+  end
+
+  calculations do
+    calculate :post_summary, :auto, expr(%{id: id, title: title}) do
+      public? true
+    end
+
+    calculate :post_title, :auto, expr(title) do
+      public? true
+    end
   end
 
   # ... attributes, actions, etc.
 end
 ```
 
+You can also use explicit `returns` with an anonymous function transform, but
+this requires manually keeping the type and transform in sync:
+
+```elixir
+publish :create, [:id],
+  event: "post_created",
+  public?: true,
+  returns: :map,
+  constraints: [
+    fields: [
+      id: [type: :uuid, allow_nil?: false],
+      title: [type: :string, allow_nil?: true]
+    ]
+  ],
+  transform: fn notification ->
+    %{id: notification.data.id, title: notification.data.title}
+  end
+```
+
 ### 2. Define your channel
 
 A typed channel consists of two parts: a DSL module that declares which events get TypeScript types, and a Phoenix channel that handles runtime behavior. You can put them in the same module or keep them separate.
@@ -274,25 +303,25 @@ Wildcard topics require a `suffix` parameter that replaces the `*`. The factory
 
 ## Payload Type Resolution
 
-The TypeScript payload type is derived from the publication's `returns` option:
+The TypeScript payload type is derived from the publication's `returns` type. When using `transform :some_calc`, Ash auto-populates `returns` from the calculation's type. You can also set `returns` explicitly.
 
-| `returns` Value | TypeScript Type |
-|----------------|-----------------|
-| `:string` | `string` |
-| `:integer` | `number` |
-| `:boolean` | `boolean` |
-| `:uuid` | `UUID` |
-| `:utc_datetime` | `UtcDateTime` |
-| `:map` with `fields` | `{fieldName: type, ...}` |
-| Not set | `unknown` |
+| `returns` Value | TypeScript Type | How to Get It |
+|----------------|-----------------|---------------|
+| `:string` | `string` | `calculate :my_calc, :auto, expr(name)` or explicit `returns: :string` |
+| `:integer` | `number` | `calculate :my_calc, :auto, expr(priority)` or explicit `returns: :integer` |
+| `:boolean` | `boolean` | `calculate :my_calc, :auto, expr(active == true)` or explicit `returns: :boolean` |
+| `:uuid` | `UUID` | `calculate :my_calc, :auto, expr(id)` or explicit `returns: :uuid` |
+| `:utc_datetime` | `UtcDateTime` | Explicit `returns: :utc_datetime` |
+| `:map` with `fields` | `{fieldName: type, ...}` | `calculate :my_calc, :auto, expr(%{id: id, name: name})` or explicit `returns: :map` with `constraints` |
+| Not set | `unknown` | Missing `transform :calc` and no explicit `returns` |
 
 Map types with `:fields` constraints generate plain object types without the `__type`/`__primitiveFields` metadata used by the RPC field-selection system.
 
 ### Multi-Channel Payload Deduplication
 
 When multiple channels are configured, payload type aliases are deduplicated by name. If two channels both subscribe to `article_published` from the same resource, only one `ArticlePublishedPayload` type is emitted in `ash_types.ts`.
 
-If two different resources declare publications with the same event name but different `returns` types and those resources appear in separate channels, codegen will raise an error:
+If two different resources declare publications with the same event name but different `returns` types (whether auto-derived or explicit) and those resources appear in separate channels, codegen will raise an error:
 
 ```
 Payload type name conflict detected across typed channels.
@@ -355,7 +384,7 @@ The DSL verifier checks your configuration at compile time:
 | Event exists | Error | Declared event doesn't match any publication on the resource |
 | Unique events | Error | Same event name used across multiple resources in one channel |
 | `public?: true` | Warning | Publication not marked as public |
-| `returns` set | Warning | Publication missing `returns` (payload type becomes `unknown`) |
+| `returns` set | Warning | Publication missing `returns` — no `transform :calc` or explicit `returns:` (payload type becomes `unknown`) |
 
 ## Configuration
 

lib/ash_typescript/typed_channel.ex

@@ -11,13 +11,39 @@ defmodule AshTypescript.TypedChannel do
   generate typed TypeScript payload types and a subscription helper for each
   channel. The developer owns authorization (via `join/3`).
 
+  Publications should use `transform :some_calc` to reference a resource
+  calculation. When the calculation uses `:auto` typing, Ash automatically
+  derives the `returns` type from the expression, giving AshTypescript the
+  type information it needs without manual `returns` declarations. You can
+  also use explicit `returns:` with an anonymous function transform.
+
   Register typed channels in application config:
 
       config :ash_typescript,
         typed_channels: [MyApp.OrgAdminChannel]
 
   ## Usage
 
+      # Resource with calculation transforms (recommended)
+      defmodule MyApp.Post do
+        use Ash.Resource, notifiers: [Ash.Notifier.PubSub]
+
+        pub_sub do
+          module MyApp.Endpoint
+          prefix "posts"
+
+          publish :create, [:id], event: "post_created", public?: true, transform: :post_summary
+          publish :update, [:id], event: "post_updated", public?: true, transform: :post_summary
+        end
+
+        calculations do
+          calculate :post_summary, :auto, expr(%{id: id, title: title}) do
+            public? true
+          end
+        end
+      end
+
+      # Channel definition
       defmodule MyApp.OrgAdminChannel do
         use AshTypescript.TypedChannel
 

lib/ash_typescript/typed_channel/codegen.ex

@@ -7,7 +7,8 @@ defmodule AshTypescript.TypedChannel.Codegen do
   Generates TypeScript types and functions for typed channel event subscriptions.
 
   For each declared event in a typed channel module, introspects the matching
-  Ash PubSub publication's `returns` type and maps it to a TypeScript type.
+  Ash PubSub publication's `returns` type (auto-derived via `transform :calc`
+  or explicitly set) and maps it to a TypeScript type.
 
   ## Generated Output