@tiesen/effect-tanstack-query 0.0.6 → 0.0.8

package/README.md

@@ -1,13 +1,20 @@
 # effect-tanstack-query
 
-A lightweight, type-safe bridge between **Effect HTTP API clients** and **TanStack Query** (`queryOptions`, `mutationOptions`, and `getQueryKey`).
+<p align="center">
+  <a href="https://npmx.dev/package/@tiesen/effect-tanstack-query"><img src="https://img.shields.io/npm/dw/%40tiesen%2Feffect-tanstack-query" alt="Total Downloads"></a>
+  <a href="https://npmx.dev/package/@tiesen/effect-tanstack-query"><img src="https://img.shields.io/npm/v/%40tiesen%2Feffect-tanstack-query" alt="Latest Stable Version"></a>
+  <a href="https://npmx.dev/package/@tiesen/effect-tanstack-query"><img src="https://img.shields.io/npm/l/%40tiesen%2Feffect-tanstack-query" alt="License"></a>
+</p>
+
+Effortlessly bridge **Effect HTTP API clients** with **TanStack Query**. Enjoy end-to-end type safety, zero-boilerplate options (`queryOptions`, `mutationOptions`, `subscriptionOptions`), and built-in streaming support out of the box.
 
 ## Features
 
 - **Seamless Integration**: Effortlessly map Effect `HttpApiClient` endpoints to TanStack Query config objects.
-- **End-to-End Type Safety**: Automatically infers inputs (`params`, `query`, `headers`, `payload`), success types, and error types directly from your Effect schemas.
-- **Zero Boilerplate**: Generates `queryKey` and execution functions under the hood using ES6 Proxies.
-- **Developer Friendly**: Smart optional parameters when no input arguments are required.
+- **End-to-End Type Safety**: Automatically infers inputs (`params`, `query`, `payload`), response types, and error types directly from your Effect schemas.
+- **Event Streaming Support**: Native handling for live streams and Server-Sent Events (SSE) via `subscriptionOptions` and `useSubscription`.
+- **Zero Boilerplate**: Generates `queryKey`, and execution logic under the hood using ES6 Proxies.
+- **Smart Developer Experience**: Auto-manages Fiber lifecycles and abort signals, with smart optional parameters when no inputs are required.
 
 ## Installation
 
@@ -15,16 +22,16 @@ Install using your preferred package manager:
 
 ```bash
 # Using npm
-npm install @tiesen/effect-tanstack-query
+npm install @tiesen/effect-tanstack-query @tanstack/react-query effect@beta
 
 # Using yarn
-yarn add @tiesen/effect-tanstack-query
+yarn add @tiesen/effect-tanstack-query @tanstack/react-query effect@beta
 
 # Using bun
-bun add @tiesen/effect-tanstack-query
+bun add @tiesen/effect-tanstack-query @tanstack/react-query effect@beta
 
 # Using pnpm
-pnpm add @tiesen/effect-tanstack-query
+pnpm add @tiesen/effect-tanstack-query @tanstack/react-query effect@beta
 ```
 
 ## Quick Start
@@ -33,9 +40,14 @@ pnpm add @tiesen/effect-tanstack-query
 
 ```ts
 import { Schema } from 'effect'
-import { HttpApi, HttpApiEndpoint, HttpApiGroup } from 'effect/unstable/httpapi'
+import {
+  HttpApi,
+  HttpApiEndpoint,
+  HttpApiGroup,
+  HttpApiSchema,
+} from 'effect/unstable/httpapi'
 
-class ApiGroup extends HttpApiGroup.make('ApiGroup')
+class ApiGroup extends HttpApiGroup.make('group')
   .add(
     HttpApiEndpoint.get('hello', '/hello/:name', {
       success: Schema.String,
@@ -54,6 +66,13 @@ class ApiGroup extends HttpApiGroup.make('ApiGroup')
         name: Schema.String,
       }),
     })
+  )
+  .add(
+    HttpApiEndpoint.get('stream', '/stream', {
+      success: HttpApiSchema.StreamSse({
+        data: Schema.String,
+      }),
+    })
   ) {}
 
 export class Api extends HttpApi.make('Api').add(ApiGroup) {}
@@ -62,27 +81,18 @@ export class Api extends HttpApi.make('Api').add(ApiGroup) {}
 ### 2. Create an Effect HTTP API Client
 
 ```ts
-import { Context, Function, Layer } from 'effect'
-import {
-  FetchHttpClient,
-  HttpClient,
-  HttpClientRequest,
-} from 'effect/unstable/http'
+import { Context, Layer } from 'effect'
+import { FetchHttpClient } from 'effect/unstable/http'
 import { HttpApiClient } from 'effect/unstable/httpapi'
 
 class ApiClient extends Context.Service<
   ApiClient,
   HttpApiClient.ForApi<typeof Api>
 >()('ApiClient') {
-  public static live = Layer.effect(
+  public static layer = Layer.effect(
     this,
     HttpApiClient.make(Api, {
-      transformClient: (client) =>
-        client.pipe(
-          HttpClient.mapRequest(
-            Function.flow(HttpClientRequest.prependUrl('http://localhost:3000'))
-          )
-        ),
+      baseUrl: 'http://localhost:3000',
     })
   ).pipe(Layer.provide(FetchHttpClient.layer))
 }
@@ -94,7 +104,7 @@ class ApiClient extends Context.Service<
 import { ManagedRuntime } from 'effect'
 import { createTanstackQueryOptionsProxy } from '@tiesen/effect-tanstack-query'
 
-const runtime = ManagedRuntime.make(ApiClient.live)
+const runtime = ManagedRuntime.make(ApiClient.layer)
 const api = createTanstackQueryOptionsProxy(ApiClient, runtime)
 ```
 
@@ -102,26 +112,42 @@ const api = createTanstackQueryOptionsProxy(ApiClient, runtime)
 
 ```ts
 import { useMutation, useQueryClient, useQuery } from '@tanstack/react-query'
+import { useSubscription } from '@tiesen/effect-tanstack-query/react'
 
 // Query Example
 const query = useQuery(
-  api.ApiGroup.hello.queryOptions({
+  api.group.hello.queryOptions({
     params: { name: 'John' },
     query: { greeting: 'Hi' },
   })
 )
 
 // Mutation Example
-const mutation = useMutation(api.ApiGroup.goodbye.mutationOptions())
+const mutation = useMutation(api.group.goodbye.mutationOptions())
 mutation.mutate({ name: 'John' })
 
+// Stream Example
+useSubscription(
+  api.group.stream.subscriptionOptions(undefined, {
+    onData: (data) => console.log('Received data:', data),
+  })
+)
+
 // Invalidate Query Example
 const queryClient = useQueryClient()
 void queryClient.invalidateQueries({
-  queryKey: api.ApiGroup.hello.getQueryKey(),
+  queryKey: api.group.hello.getQueryKey(),
 })
 ```
 
+## Downloads
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://npmx.dev/api/embed/downloads.svg?packages=%40tiesen%2Feffect-tanstack-query&metric=downloads&startDate=2025-08-01&endDate=2026-07-30&mode=dark&granularity=weekly&locale=en-US&accent=oklch%2867.3%25+0+0%29&yLabel=Weekly+Downloads">
+  <source media="(prefers-color-scheme: light)" srcset="https://npmx.dev/api/embed/downloads.svg?packages=%40tiesen%2Feffect-tanstack-query&metric=downloads&startDate=2025-08-01&endDate=2026-07-30&mode=light&granularity=weekly&locale=en-US&accent=oklch%2867.3%25+0+0%29&yLabel=Weekly+Downloads">
+  <img alt="npmx downloads" src="https://npmx.dev/api/embed/downloads.svg?packages=%40tiesen%2Feffect-tanstack-query&metric=downloads&startDate=2025-08-01&endDate=2026-07-30&mode=light&granularity=weekly&locale=en-US&accent=oklch%2867.3%25+0+0%29&yLabel=Weekly+Downloads">
+</picture>
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.

package/dist/index.d.mts

@@ -1,38 +1,10 @@
+import { r as TanstackQueryOptionsProxy } from "./types-BGHsAv5y.mjs";
 import { Service } from "effect/Context";
 import { ManagedRuntime } from "effect/ManagedRuntime";
-import { DefinedInitialDataOptions, MutationOptions } from "@tanstack/react-query";
-import { Schema } from "effect/Schema";
-import { Client } from "effect/unstable/httpapi/HttpApiClient";
-import { HttpApiEndpoint } from "effect/unstable/httpapi/HttpApiEndpoint";
-//#region src/types.d.ts
-type TanstackQueryOptionsProxy<T> = T extends Client.Method<HttpApiEndpoint<infer _Key, infer Method, infer _Path, infer Params, infer Query, infer Payload, infer Headers, infer Success, infer Error>, infer _Error, infer _Requires> ? {
-  queryOptions: Method extends 'GET' ? <TQuery = DefinedInitialDataOptions<UnwrapCodec<Success>, UnwrapCodec<Error>>>(input: MakeOptionalInput<([Params] extends [never] ? {} : {
-    params: UnwrapCodec<Params>;
-  }) & ([Query] extends [never] ? {} : {
-    query: UnwrapCodec<Query>;
-  }) & ([Headers] extends [never] ? {} : {
-    headers: UnwrapCodec<Headers>;
-  })>, options?: Omit<TQuery, 'queryKey' | 'queryFn'>) => TQuery : never;
-  mutationOptions: Method extends 'GET' ? never : <TMutation = MutationOptions<UnwrapCodec<Success>, UnwrapCodec<Error>, UnwrapCodec<Payload>>>(input: MakeOptionalInput<([Params] extends [never] ? {} : {
-    params: UnwrapCodec<Params>;
-  }) & ([Headers] extends [never] ? {} : {
-    headers: UnwrapCodec<Headers>;
-  })>, options?: Omit<TMutation, 'mutationKey' | 'mutationFn'>) => TMutation;
-  getQueryKey: Method extends 'GET' ? (input?: Partial<MakeOptionalInput<([Params] extends [never] ? {} : {
-    params: UnwrapCodec<Params>;
-  }) & ([Query] extends [never] ? {} : {
-    query: UnwrapCodec<Query>;
-  }) & ([Headers] extends [never] ? {} : {
-    headers: UnwrapCodec<Headers>;
-  })>>) => readonly unknown[] : never;
-} : T extends object ? { readonly [K in keyof T]: TanstackQueryOptionsProxy<T[K]>; } : T;
-type UnwrapCodec<T> = T extends Schema<unknown> ? Schema.Type<T> : T extends object ? { [K in keyof T]: UnwrapCodec<T[K]>; } : T;
-type MakeOptionalInput<T> = keyof T extends never ? void | undefined : T;
-//#endregion
 //#region src/index.d.ts
 /**
  * Creates a type-safe proxy that bridges Effect `HttpApiClient` endpoints
- * with TanStack Query options (`queryOptions`, `mutationOptions`, and `getQueryKey`).
+ * with TanStack Query options (`queryOptions`, `subscriptionOptions`, `mutationOptions`, and `getQueryKey`).
  *
  * @param tag - The Effect `Service` tag used to locate the client implementation within the Context.
  * @param runtime - The Effect `ManagedRuntime` used to execute effects as promises.
@@ -42,13 +14,14 @@ type MakeOptionalInput<T> = keyof T extends never ? void | undefined : T;
  * @example
  * ```ts
  * class ApiGroup extends HttpApiGroup.make('ApiGroup')
- *  .add(HttpApiEndpoint.get('hello', '/hello', { success: Schema.String, query: Schema.Struct({ name: Schema.String }) }))
- *  .add(HttpApiEndpoint.post('bye', '/bye', { success: Schema.String, payload: Schema.Struct({ name: Schema.String }) })) {}
+ *   .add(HttpApiEndpoint.get('hello', '/hello', { success: Schema.String, query: Schema.Struct({ name: Schema.String }) }))
+ *   .add(HttpApiEndpoint.post('bye', '/bye', { success: Schema.String, payload: Schema.Struct({ name: Schema.String }) }))
+ *   .add(HttpApiEndpoint.get('stream', '/stream', { success: HttpApiSchema.StreamSse({ data: Schema.String }) })) {}
  *
  * class Api extends HttpApi.make('Api').add(ApiGroup) {}
  *
  * class ApiClient extends Context.Service<ApiClient, HttpApiClient.ForApi<typeof Api>>()('ApiClient') {
- *  public static live = Layer.effect(this, HttpApiClient.make(Api)).pipe(Layer.provide(FetchHttpClient.layer))
+ *   public static live = Layer.effect(this, HttpApiClient.make(Api)).pipe(Layer.provide(FetchHttpClient.layer))
  * }
  *
  * const runtime = ManagedRuntime.make(ApiClient.live)
@@ -56,11 +29,16 @@ type MakeOptionalInput<T> = keyof T extends never ? void | undefined : T;
  *
  * // Example usage in a React component with TanStack Query
  * const { data } = useQuery(api.hello.queryOptions({ query: { name: 'World' } }))
- * //       ^? const data: string = "Hello, World!"
+ *          ^? const data: string = "Hello, World!"
  *
  * const { mutate, data } = useMutation(api.bye.mutationOptions())
- * //               ^? const data: string = "Goodbye, World!"
+ *                  ^? const data: string = "Goodbye, World!"
  * mutate({ name: 'World' })
+ *
+ * useSubscription(api.stream.subscriptionOptions({
+ *   onData: (data) => console.log(data),
+ *             ^? const data: string = "data: keep-alive\n\n"
+ * }))
  * ```
  */
 declare function createTanstackQueryOptionsProxy<TServiceTag, TService>(tag: Service<TServiceTag, TService>, runtime: ManagedRuntime<TServiceTag, never>): TanstackQueryOptionsProxy<TService>;

package/dist/index.mjs

@@ -1 +1 @@
-import*as e from"effect/Effect";function t(t,n){let r=new Map,i=a=>{let o=a.join(`.`);if(r.has(o))return r.get(o);let s=new Proxy(()=>{},{get(e,t){if(typeof t!=`symbol`&&t!==`then`)return i([...a,String(t)])},apply(r,i,o){let s=a.at(-1),c=a.slice(0,-1),[l,u]=o,d=(r,i)=>n.runPromise(e.gen(function*(){let e=yield*t;for(let t of c)e=e[t];return yield*e(r)}),{signal:i}),f=(e,t)=>[{type:e},...c,...t?[t]:[]];if(s===`queryOptions`)return{...u,queryKey:f(`query`,l),queryFn:({signal:e})=>d(l,e)};if(s===`getQueryKey`)return f(`query`,l);if(s===`mutationOptions`)return{...u,mutationKey:f(`mutation`,l),mutationFn:e=>d({payload:e})}}});return r.set(o,s),s};return i([])}export{t as createTanstackQueryOptionsProxy};
+import*as e from"effect/Effect";import*as t from"effect/Stream";function n(n,r){let i=new Map,a=o=>{let s=o.join(`.`);if(i.has(s))return i.get(s);let c=new Proxy(()=>{},{get(e,t){if(typeof t!=`symbol`&&t!==`then`)return a([...o,String(t)])},apply(i,a,s){let c=o.at(-1),l=o.slice(0,-1),[u,d]=s,f=e.fn(function*(e){let t=yield*n;for(let e of l)t=t[e];return yield*t(e)}),p=(e,t)=>r.runPromise(f(e),{signal:t}),m=(e,t)=>[{type:e},...l,...t?[t]:[]];if(c===`queryOptions`)return{...d,queryKey:m(`query`,u),queryFn:({signal:e})=>p(u,e)};if(c===`getQueryKey`)return m(`query`,u);if(c===`subscriptionOptions`){let n=t.unwrap(f({...u,responseMode:`response-only`}).pipe(e.map(e=>e.stream.pipe(t.decodeText())))),i=d;return{...d,subcriptionKey:m(`subscription`,u),subscriptionFn:({signal:a}={})=>{let o=r.runFork(n.pipe(t.tap(t=>e.sync(()=>i.onData(t))),t.runDrain)),s=()=>o.interruptUnsafe(o.id);return a&&(a.aborted?s():a.addEventListener(`abort`,s,{once:!0})),o.addObserver(e=>{e._tag===`Failure`&&i.onError?.(e.cause)}),s}}}if(c===`mutationOptions`)return{...d,mutationKey:m(`mutation`,u),mutationFn:e=>p({payload:e})}}});return i.set(s,c),c};return a([])}export{n as createTanstackQueryOptionsProxy};

package/dist/react.d.mts

@@ -0,0 +1,7 @@
+import { n as SubscriptionReturns, t as SubscriptionOptions } from "./types-BGHsAv5y.mjs";
+//#region src/react.d.ts
+declare function useSubscription<TData, TError>({ enabled, ...subscriptionOptions }: SubscriptionOptions<TData, TError> & {
+  enabled?: boolean;
+}): SubscriptionReturns;
+//#endregion
+export { type SubscriptionOptions, type SubscriptionReturns, useSubscription };

package/dist/react.mjs

@@ -0,0 +1 @@
+import*as e from"react";function t({enabled:t=!0,...n}){let[r,i]=e.useState(`disconnected`),[a,o]=e.useState(0),s=e.useCallback(()=>{o(e=>e+1)},[]);return e.useEffect(()=>{if(!t){i(`disconnected`);return}i(`connecting`);let e=new AbortController,r=n.subscriptionFn({signal:e.signal});return i(`connected`),()=>{e.abort(),r(),i(`disconnected`)}},[t,n.subscriptionFn,a]),e.useMemo(()=>({status:r,reconnect:s}),[r,s])}export{t as useSubscription};

package/dist/types-BGHsAv5y.d.mts

@@ -0,0 +1,54 @@
+import { DefinedInitialDataOptions, MutationOptions } from "@tanstack/react-query";
+import { Schema } from "effect/Schema";
+import { Client } from "effect/unstable/httpapi/HttpApiClient";
+import { HttpApiEndpoint } from "effect/unstable/httpapi/HttpApiEndpoint";
+import { SseEventFromData, StreamSse } from "effect/unstable/httpapi/HttpApiSchema";
+//#region src/types.d.ts
+type TanstackQueryOptionsProxy<T> = T extends Client.Method<HttpApiEndpoint<infer _Key, infer Method, infer _Path, infer Params, infer Query, infer Payload, infer Headers, infer Success, infer Error>, infer _Error, infer _Requires> ? {
+  queryOptions: Method extends 'GET' ? <TQuery = DefinedInitialDataOptions<UnwrapCodec<Success>, UnwrapCodec<Error>>>(input: MakeOptionalInput<([Params] extends [never] ? {} : {
+    params: UnwrapCodec<Params>;
+  }) & ([Query] extends [never] ? {} : {
+    query: UnwrapCodec<Query>;
+  }) & ([Headers] extends [never] ? {} : {
+    headers: UnwrapCodec<Headers>;
+  })>, options?: Omit<TQuery, 'queryKey' | 'queryFn'>) => TQuery : never;
+  subscriptionOptions: Success extends StreamSse<SseEventFromData<infer StreamSuccess>, infer StreamError, infer _StreamValue> ? (input: MakeOptionalInput<([Params] extends [never] ? {} : {
+    params: UnwrapCodec<Params>;
+  }) & ([Query] extends [never] ? {} : {
+    query: UnwrapCodec<Query>;
+  }) & ([Headers] extends [never] ? {} : {
+    headers: UnwrapCodec<Headers>;
+  })>, options?: {
+    onData: (data: StreamSuccess) => void;
+    onError?: (error: StreamError) => void;
+  }) => SubscriptionOptions<StreamSuccess, StreamError> : never;
+  mutationOptions: Method extends 'GET' ? never : <TMutation = MutationOptions<UnwrapCodec<Success>, UnwrapCodec<Error>, UnwrapCodec<Payload>>>(input: MakeOptionalInput<([Params] extends [never] ? {} : {
+    params: UnwrapCodec<Params>;
+  }) & ([Headers] extends [never] ? {} : {
+    headers: UnwrapCodec<Headers>;
+  })>, options?: Omit<TMutation, 'mutationKey' | 'mutationFn'>) => TMutation;
+  getQueryKey: Method extends 'GET' ? (input?: Partial<MakeOptionalInput<([Params] extends [never] ? {} : {
+    params: UnwrapCodec<Params>;
+  }) & ([Query] extends [never] ? {} : {
+    query: UnwrapCodec<Query>;
+  }) & ([Headers] extends [never] ? {} : {
+    headers: UnwrapCodec<Headers>;
+  })>>) => readonly unknown[] : never;
+} : T extends object ? { readonly [K in keyof T]: TanstackQueryOptionsProxy<T[K]>; } : T;
+type UnsubscribeFn = () => void;
+interface SubscriptionOptions<TData, TError> {
+  subcriptionKey: readonly unknown[];
+  subscriptionFn: (options: {
+    signal?: AbortSignal;
+  }) => UnsubscribeFn;
+  onData: (data: TData) => void;
+  onError?: (error: TError) => void;
+}
+interface SubscriptionReturns {
+  status: 'connecting' | 'connected' | 'disconnected' | 'error';
+  reconnect: () => void;
+}
+type UnwrapCodec<T> = T extends Schema<unknown> ? Schema.Type<T> : T extends object ? { [K in keyof T]: UnwrapCodec<T[K]>; } : T;
+type MakeOptionalInput<T> = keyof T extends never ? void | undefined : T;
+//#endregion
+export { SubscriptionReturns as n, TanstackQueryOptionsProxy as r, SubscriptionOptions as t };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@tiesen/effect-tanstack-query",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "private": false,
-  "description": "  A lightweight, type-safe bridge between Effect HTTP API clients and TanStack Query.",
+  "description": "Effortlessly bridge Effect HTTP API clients with TanStack Query. Enjoy end-to-end type safety, zero-boilerplate options, and built-in streaming support out of the box.",
   "keywords": [
     "effect",
     "effect-ts",
@@ -34,8 +34,12 @@
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/index.mjs",
-      "types": "./dist/index.d.mts"
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./react": {
+      "types": "./dist/react.d.mts",
+      "default": "./dist/react.mjs"
     }
   },
   "publishConfig": {
@@ -51,6 +55,7 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
+    "@types/react": "^19.2.18",
     "oxfmt": "^0.61.0",
     "oxlint": "^1.76.0",
     "tegami": "^1.2.7",
@@ -59,7 +64,8 @@
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.100.0",
-    "effect": ">=4.0.0-beta.100 || >=4.0.0"
+    "effect": ">=4.0.0-beta.100 || >=4.0.0",
+    "react": ">=19.2.8"
   },
   "packageManager": "bun@1.3.0",
   "patchedDependencies": {