@tiesen/effect-tanstack-query 0.0.7 → 0.0.9

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,4 +1,4 @@
-import { r as TanstackQueryOptionsProxy } from "./types-BGHsAv5y.mjs";
+import { r as TanstackQueryOptionsProxy } from "./types-CcB8FTUv.mjs";
 import { Service } from "effect/Context";
 import { ManagedRuntime } from "effect/ManagedRuntime";
 //#region src/index.d.ts

package/dist/index.mjs

@@ -1 +1 @@
-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};
+import*as e from"effect/Effect";import*as t from"effect/Fiber";import*as n from"effect/Schedule";import*as r from"effect/Stream";function i(i,a){let o=new Map,s=c=>{let l=c.join(`.`);if(o.has(l))return o.get(l);let u=new Proxy(()=>{},{get(e,t){if(typeof t!=`symbol`&&t!==`then`)return s([...c,String(t)])},apply(o,s,l){let u=c.at(-1),d=c.slice(0,-1),[f,p]=l,m=e.fn(function*(e){let t=yield*i;for(let e of d)t=t[e];return yield*t(e)}),h=(e,t)=>a.runPromise(m(e),{signal:t}),g=(e,t)=>[{type:e},...d,...t?[t]:[]];if(u===`queryOptions`)return{...p,queryKey:g(`query`,f),queryFn:({signal:e})=>h(f,e)};if(u===`getQueryKey`)return g(`query`,f);if(u===`mutationOptions`)return{...p,mutationKey:g(`mutation`,f),mutationFn:e=>h({payload:e})};if(u===`subscriptionOptions`){let{onData:i,onError:o,keepAliveTimeout:s=`10 seconds`}=p;return{...p,subcriptionKey:g(`subscription`,f),subscriptionFn:({signal:c}={})=>{let l=e.gen(function*(){let t=yield*(yield*m({...f,responseMode:`response-only`})).stream.pipe(r.decodeText,r.splitLines,r.filter(e=>e.length>0),r.share({capacity:`unbounded`})),n=t.pipe(r.filter(e=>e.startsWith(`:keep-alive`)),r.timeout(s),r.tapError(()=>e.logError(`Keep-alive timeout, reconnecting...`))),a=yield*t.pipe(r.filter(e=>e.startsWith(`data:`)),r.map(e=>e.slice(5).trim()),r.filter(e=>e.length>0),r.tap(t=>e.sync(()=>i(t))),r.share({capacity:`unbounded`})),o=r.merge(n,a);yield*r.runDrain(o),yield*e.fail(`restart`)}).pipe(e.catchTag(`HttpClientError`,t=>t.reason._tag===`DecodeError`?e.void:(o&&o(t),e.fail(t))),e.scoped,e.retry(n.exponential(`3 seconds`))),u=a.runFork(l),d=()=>t.interrupt(u);return c&&(c.aborted?d():c.addEventListener(`abort`,d,{once:!0})),d}}}}});return o.set(l,u),u};return s([])}export{i as createTanstackQueryOptionsProxy};

package/dist/react.d.mts

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

package/dist/react.mjs

@@ -1 +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};
+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)},[]),c=e.useMemo(()=>JSON.stringify(n.subcriptionKey),[n.subcriptionKey]);return e.useEffect(()=>{if(!t)return i(`disconnected`);i(`connecting`);let e=new AbortController,r=n.subscriptionFn({signal:e.signal});return i(`connected`),()=>{e.abort(),r(),i(`disconnected`)}},[t,c,a]),e.useMemo(()=>({status:r,reconnect:s}),[r,s])}export{t as useSubscription};

package/dist/{types-BGHsAv5y.d.mts → types-CcB8FTUv.d.mts}

@@ -1,4 +1,5 @@
 import { DefinedInitialDataOptions, MutationOptions } from "@tanstack/react-query";
+import { Input } from "effect/Duration";
 import { Schema } from "effect/Schema";
 import { Client } from "effect/unstable/httpapi/HttpApiClient";
 import { HttpApiEndpoint } from "effect/unstable/httpapi/HttpApiEndpoint";
@@ -19,9 +20,9 @@ type TanstackQueryOptionsProxy<T> = T extends Client.Method<HttpApiEndpoint<infe
   }) & ([Headers] extends [never] ? {} : {
     headers: UnwrapCodec<Headers>;
   })>, options?: {
-    onData: (data: StreamSuccess) => void;
-    onError?: (error: StreamError) => void;
-  }) => SubscriptionOptions<StreamSuccess, StreamError> : never;
+    onData: (data: UnwrapCodec<StreamSuccess>) => void;
+    onError?: (error: UnwrapCodec<StreamError>) => void;
+  }) => SubscriptionOptions<UnwrapCodec<StreamSuccess>, UnwrapCodec<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] ? {} : {
@@ -43,6 +44,7 @@ interface SubscriptionOptions<TData, TError> {
   }) => UnsubscribeFn;
   onData: (data: TData) => void;
   onError?: (error: TError) => void;
+  keepAliveTimeout?: Input;
 }
 interface SubscriptionReturns {
   status: 'connecting' | 'connected' | 'disconnected' | 'error';

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@tiesen/effect-tanstack-query",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "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",