@orpc/experimental-react-swr 0.0.0 → 1.8.3

package/README.md

@@ -8,8 +8,8 @@
   <a href="https://codecov.io/gh/unnoq/orpc">
     <img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
   </a>
-  <a href="https://www.npmjs.com/package/@orpc/react-swr">
-    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Freact-swr?logo=npm" />
+  <a href="https://www.npmjs.com/package/@orpc/experimental-react-swr">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fexperimental-react-swr?logo=npm" />
   </a>
   <a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
     <img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
@@ -31,7 +31,7 @@
 - **📘 First-Class OpenAPI**: Built-in support that fully adheres to the OpenAPI standard.
 - **📝 Contract-First Development**: Optionally define your API contract before implementation.
 - **🔍 First-Class OpenTelemetry**: Seamlessly integrate with OpenTelemetry for observability.
-- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte, Angular), Pinia Colada, and more.
+- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte, Angular), SWR, Pinia Colada, and more.
 - **🚀 Server Actions**: Fully compatible with React Server Actions on Next.js, TanStack Start, and other platforms.
 - **🔠 Standard Schema Support**: Works out of the box with Zod, Valibot, ArkType, and other schema validators.
 - **🗃️ Native Types**: Supports native types like Date, File, Blob, BigInt, URL, and more.
@@ -54,13 +54,14 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 - [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with [NestJS](https://nestjs.com/).
 - [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
 - [@orpc/tanstack-query](https://www.npmjs.com/package/@orpc/tanstack-query): [TanStack Query](https://tanstack.com/query/latest) integration.
+- [@orpc/experimental-react-swr](https://www.npmjs.com/package/@orpc/experimental-react-swr): [SWR](https://swr.vercel.app/) integration.
 - [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
 - [@orpc/hey-api](https://www.npmjs.com/package/@orpc/hey-api): [Hey API](https://heyapi.dev/) integration.
 - [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
 - [@orpc/valibot](https://www.npmjs.com/package/@orpc/valibot): OpenAPI spec generation from [Valibot](https://valibot.dev/).
 - [@orpc/arktype](https://www.npmjs.com/package/@orpc/arktype): OpenAPI spec generation from [ArkType](https://arktype.io/).
 
-## `@orpc/react-swr`
+## `@orpc/experimental-react-swr`
 
 [SWR](https://swr.vercel.app/) integration for oRPC, providing a simple way to fetch data using oRPC endpoints with SWR's caching and revalidation features.
 

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { PartialDeep, MaybeOptionalOptions, InferAsyncIterableYield, ThrowableError } from '@orpc/shared';
+import { PartialDeep, MaybeOptionalOptions, InferAsyncIterableYield } from '@orpc/shared';
 import { ClientContext, Client, NestedClient } from '@orpc/client';
 import { SWRSubscriptionOptions } from 'swr/subscription';
 
@@ -61,6 +61,11 @@ type CreateSubscriberOptions<TClientContext extends ClientContext> = CreateFetch
 type Subscriber<TInput, TOutput, TError> = (key: Key<TInput>, options: SWRSubscriptionOptions<TOutput, TError>) => (() => void);
 
 interface GeneralUtils<TInput> {
+    /**
+     * Generate a matcher function that returns `true` if the key matches the specified conditions.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#manual-revalidation React SWR Manual Revalidation Docs}
+     */
     matcher<TStrategy extends MatcherStrategy>(...rest: MaybeOptionalOptions<CreateMatcherOptions<TStrategy, TInput>>): Matcher;
 }
 declare function createGeneralUtils<TInput>(path: readonly string[]): GeneralUtils<TInput>;
@@ -69,17 +74,41 @@ interface ProcedureUtilsOptions {
     path: readonly string[];
 }
 interface ProcedureUtils<TClientContext extends ClientContext, TInput, TOutput, TError> {
+    /**
+     * Calling corresponding procedure client
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#calling-clients React SWR Calling Procedure Client Docs}
+     */
     call: Client<TClientContext, TInput, TOutput, TError>;
+    /**
+     * Generate a **full matching** key for SWR operations.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#data-fetching React SWR Key Docs}
+     */
     key(...rest: MaybeOptionalOptions<CreateKeyOptions<TInput>>): Key<TInput>;
+    /**
+     * Generate a fetcher function for use with useSWR, useSWRInfinite, and other SWR hooks.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#data-fetching React SWR Data Fetching Docs}
+     */
     fetcher(...rest: MaybeOptionalOptions<CreateFetcherOptions<TClientContext>>): Fetcher<TInput, TOutput>;
     /**
-     * @remarks Uses ThrowableError instead of TError because TError only applies to the initial request. Streaming errors are not validated, so type safety cannot be guaranteed for error types.
+     * Generate a subscriber function that subscribes to an [Event Iterator](https://orpc.unnoq.com/docs/event-iterator) for use with useSWRSubscription, etc.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#subscriptions React SWR Subscriptions Docs}
+     */
+    subscriber(...rest: MaybeOptionalOptions<CreateSubscriberOptions<TClientContext>>): Subscriber<TInput, InferAsyncIterableYield<TOutput>[], TError>;
+    /**
+     * Generate a live subscriber that subscribes to the latest events from an [Event Iterator](https://orpc.unnoq.com/docs/event-iterator) for use with useSWRSubscription, etc.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#subscriptions React SWR Subscriptions Docs}
      */
-    subscriber(...rest: MaybeOptionalOptions<CreateSubscriberOptions<TClientContext>>): Subscriber<TInput, InferAsyncIterableYield<TOutput>[], ThrowableError>;
+    liveSubscriber(...rest: MaybeOptionalOptions<CreateFetcherOptions<TClientContext>>): Subscriber<TInput, InferAsyncIterableYield<TOutput>, TError>;
     /**
-     * @remarks Uses ThrowableError instead of TError because TError only applies to the initial request. Streaming errors are not validated, so type safety cannot be guaranteed for error types.
+     * Generate a mutator function for use with useSWRMutation, etc.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#mutations React SWR Mutations Docs}
      */
-    liveSubscriber(...rest: MaybeOptionalOptions<CreateFetcherOptions<TClientContext>>): Subscriber<TInput, InferAsyncIterableYield<TOutput>, ThrowableError>;
     mutator(...rest: MaybeOptionalOptions<CreateFetcherOptions<TClientContext>>): Mutator<TInput, TOutput>;
 }
 declare function createProcedureUtils<TClientContext extends ClientContext, TInput, TOutput, TError>(client: Client<TClientContext, TInput, TOutput, TError>, options: ProcedureUtilsOptions): ProcedureUtils<TClientContext, TInput, TOutput, TError>;
@@ -90,6 +119,12 @@ type RouterUtils<T extends NestedClient<any>> = T extends Client<infer UClientCo
 interface CreateRouterUtilsOptions {
     path?: readonly string[];
 }
+/**
+ * Create a swr router utils from a client.
+ *
+ * @info Both client-side and server-side clients are supported.
+ * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr React SWR Integration}
+ */
 declare function createRouterUtils<T extends NestedClient<any>>(client: T, options?: CreateRouterUtilsOptions): RouterUtils<T>;
 
 declare function isSubsetOf(subsetKey: unknown, fullKey: unknown): boolean;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PartialDeep, MaybeOptionalOptions, InferAsyncIterableYield, ThrowableError } from '@orpc/shared';
+import { PartialDeep, MaybeOptionalOptions, InferAsyncIterableYield } from '@orpc/shared';
 import { ClientContext, Client, NestedClient } from '@orpc/client';
 import { SWRSubscriptionOptions } from 'swr/subscription';
 
@@ -61,6 +61,11 @@ type CreateSubscriberOptions<TClientContext extends ClientContext> = CreateFetch
 type Subscriber<TInput, TOutput, TError> = (key: Key<TInput>, options: SWRSubscriptionOptions<TOutput, TError>) => (() => void);
 
 interface GeneralUtils<TInput> {
+    /**
+     * Generate a matcher function that returns `true` if the key matches the specified conditions.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#manual-revalidation React SWR Manual Revalidation Docs}
+     */
     matcher<TStrategy extends MatcherStrategy>(...rest: MaybeOptionalOptions<CreateMatcherOptions<TStrategy, TInput>>): Matcher;
 }
 declare function createGeneralUtils<TInput>(path: readonly string[]): GeneralUtils<TInput>;
@@ -69,17 +74,41 @@ interface ProcedureUtilsOptions {
     path: readonly string[];
 }
 interface ProcedureUtils<TClientContext extends ClientContext, TInput, TOutput, TError> {
+    /**
+     * Calling corresponding procedure client
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#calling-clients React SWR Calling Procedure Client Docs}
+     */
     call: Client<TClientContext, TInput, TOutput, TError>;
+    /**
+     * Generate a **full matching** key for SWR operations.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#data-fetching React SWR Key Docs}
+     */
     key(...rest: MaybeOptionalOptions<CreateKeyOptions<TInput>>): Key<TInput>;
+    /**
+     * Generate a fetcher function for use with useSWR, useSWRInfinite, and other SWR hooks.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#data-fetching React SWR Data Fetching Docs}
+     */
     fetcher(...rest: MaybeOptionalOptions<CreateFetcherOptions<TClientContext>>): Fetcher<TInput, TOutput>;
     /**
-     * @remarks Uses ThrowableError instead of TError because TError only applies to the initial request. Streaming errors are not validated, so type safety cannot be guaranteed for error types.
+     * Generate a subscriber function that subscribes to an [Event Iterator](https://orpc.unnoq.com/docs/event-iterator) for use with useSWRSubscription, etc.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#subscriptions React SWR Subscriptions Docs}
+     */
+    subscriber(...rest: MaybeOptionalOptions<CreateSubscriberOptions<TClientContext>>): Subscriber<TInput, InferAsyncIterableYield<TOutput>[], TError>;
+    /**
+     * Generate a live subscriber that subscribes to the latest events from an [Event Iterator](https://orpc.unnoq.com/docs/event-iterator) for use with useSWRSubscription, etc.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#subscriptions React SWR Subscriptions Docs}
      */
-    subscriber(...rest: MaybeOptionalOptions<CreateSubscriberOptions<TClientContext>>): Subscriber<TInput, InferAsyncIterableYield<TOutput>[], ThrowableError>;
+    liveSubscriber(...rest: MaybeOptionalOptions<CreateFetcherOptions<TClientContext>>): Subscriber<TInput, InferAsyncIterableYield<TOutput>, TError>;
     /**
-     * @remarks Uses ThrowableError instead of TError because TError only applies to the initial request. Streaming errors are not validated, so type safety cannot be guaranteed for error types.
+     * Generate a mutator function for use with useSWRMutation, etc.
+     *
+     * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr#mutations React SWR Mutations Docs}
      */
-    liveSubscriber(...rest: MaybeOptionalOptions<CreateFetcherOptions<TClientContext>>): Subscriber<TInput, InferAsyncIterableYield<TOutput>, ThrowableError>;
     mutator(...rest: MaybeOptionalOptions<CreateFetcherOptions<TClientContext>>): Mutator<TInput, TOutput>;
 }
 declare function createProcedureUtils<TClientContext extends ClientContext, TInput, TOutput, TError>(client: Client<TClientContext, TInput, TOutput, TError>, options: ProcedureUtilsOptions): ProcedureUtils<TClientContext, TInput, TOutput, TError>;
@@ -90,6 +119,12 @@ type RouterUtils<T extends NestedClient<any>> = T extends Client<infer UClientCo
 interface CreateRouterUtilsOptions {
     path?: readonly string[];
 }
+/**
+ * Create a swr router utils from a client.
+ *
+ * @info Both client-side and server-side clients are supported.
+ * @see {@link https://orpc.unnoq.com/docs/integrations/react-swr React SWR Integration}
+ */
 declare function createRouterUtils<T extends NestedClient<any>>(client: T, options?: CreateRouterUtilsOptions): RouterUtils<T>;
 
 declare function isSubsetOf(subsetKey: unknown, fullKey: unknown): boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orpc/experimental-react-swr",
   "type": "module",
-  "version": "0.0.0",
+  "version": "1.8.3",
   "license": "MIT",
   "homepage": "https://orpc.unnoq.com",
   "repository": {
@@ -25,10 +25,10 @@
   ],
   "peerDependencies": {
     "swr": ">=2.3.6",
-    "@orpc/client": "1.8.1"
+    "@orpc/client": "1.8.3"
   },
   "dependencies": {
-    "@orpc/shared": "1.8.1"
+    "@orpc/shared": "1.8.3"
   },
   "devDependencies": {
     "swr": "^2.3.6"