@orpc/pinia-colada 2.0.0-beta.48 → 2.0.0-beta.50

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +4 -4
  2. package/dist/contract-utils.d.ts +35 -0
  3. package/dist/contract-utils.js +42 -0
  4. package/dist/index.d.ts +13 -0
  5. package/dist/index.js +7 -0
  6. package/dist/key.d.ts +36 -0
  7. package/dist/key.js +45 -0
  8. package/dist/live-query.js +34 -0
  9. package/dist/meta.d.ts +42 -0
  10. package/dist/meta.js +53 -0
  11. package/dist/plugin.d.ts +39 -0
  12. package/dist/plugin.js +19 -0
  13. package/dist/procedure-utils.d.ts +187 -0
  14. package/dist/procedure-utils.js +383 -0
  15. package/dist/router-utils.d.ts +62 -0
  16. package/dist/router-utils.js +54 -0
  17. package/dist/shared-utils.d.ts +13 -0
  18. package/dist/shared-utils.js +23 -0
  19. package/dist/ssr.d.ts +22 -0
  20. package/dist/ssr.js +22 -0
  21. package/dist/stream-query.d.ts +33 -0
  22. package/dist/stream-query.js +47 -0
  23. package/dist/types.d.ts +80 -0
  24. package/dist/types.js +9 -0
  25. package/package.json +31 -33
  26. package/dist/contract-utils.d.mts +0 -35
  27. package/dist/contract-utils.mjs +0 -23
  28. package/dist/index.d.mts +0 -19
  29. package/dist/index.mjs +0 -11
  30. package/dist/key.d.mts +0 -57
  31. package/dist/key.mjs +0 -29
  32. package/dist/live-query.d.mts +0 -7
  33. package/dist/live-query.mjs +0 -24
  34. package/dist/meta.d.mts +0 -55
  35. package/dist/meta.mjs +0 -37
  36. package/dist/plugin.d.mts +0 -46
  37. package/dist/plugin.mjs +0 -25
  38. package/dist/procedure-utils.d.mts +0 -245
  39. package/dist/procedure-utils.mjs +0 -394
  40. package/dist/router-utils.d.mts +0 -57
  41. package/dist/router-utils.mjs +0 -51
  42. package/dist/shared-utils.d.mts +0 -13
  43. package/dist/shared-utils.mjs +0 -17
  44. package/dist/stream-query.d.mts +0 -30
  45. package/dist/stream-query.mjs +0 -45
  46. package/dist/types.d.mts +0 -125
  47. package/dist/types.mjs +0 -2
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  <img alt="codecov" src="https://codecov.io/gh/middleapi/orpc/branch/main/graph/badge.svg">
6
6
  </a>
7
7
  <a href="https://www.npmjs.com/package/@orpc/pinia-colada">
8
- <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fpinia-colada?logo=npm" />
8
+ <img alt="monthly downloads" src="https://img.shields.io/npm/dm/%40orpc%2Fpinia-colada?logo=npm" />
9
9
  </a>
10
10
  <a href="https://app.codspeed.io/middleapi/orpc?utm_source=badge">
11
11
  <img alt="CodSpeed" src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" />
@@ -41,10 +41,11 @@ export const router = {
41
41
  Then call them from a client that knows every input and output, without generating anything:
42
42
 
43
43
  ```ts
44
- import type { RouterClient } from '@orpc/server'
45
- import type { router } from './router'
46
44
  import { createORPCClient } from '@orpc/client'
47
45
  import { RPCLink } from '@orpc/client/fetch'
46
+ import type { RouterClient } from '@orpc/server'
47
+
48
+ import type { router } from './router'
48
49
 
49
50
  const link = new RPCLink({ origin: 'http://localhost:3000', url: '/rpc' })
50
51
  const client: RouterClient<typeof router> = createORPCClient(link)
@@ -208,7 +209,6 @@ With thanks to [40 past sponsors](https://orpc.dev/sponsors#past-sponsors) who h
208
209
  <tr>
209
210
  <td align="center"><a href="https://claude.com/contact-sales/claude-for-oss" target="_blank" rel="noopener" title="Claude for Open Source"><img src="https://cdn.simpleicons.org/claude" width="64" alt="Claude"/><br />Claude</a></td>
210
211
  <td align="center"><a href="https://pullfrog.com/for-oss" target="_blank" rel="noopener" title="Pullfrog for OSS"><img src="https://avatars.githubusercontent.com/in/1768019?s=128&amp;v=4" width="64" alt="Pullfrog"/><br />Pullfrog</a></td>
211
- <td align="center"><a href="https://macroscope.com/open-source" target="_blank" rel="noopener" title="Macroscope for Open Source"><img src="https://avatars.githubusercontent.com/in/900172?s=128&amp;v=4" width="64" alt="Macroscope"/><br />Macroscope</a></td>
212
212
  </tr>
213
213
  </table>
214
214
 
@@ -0,0 +1,35 @@
1
+ import { RouterUtils, RouterUtilsOptions } from "./router-utils.js";
2
+ import { ContractClientFactory, RouterContract, RouterContractClient } from "@orpc/contract";
3
+ import { ClientContext } from "@orpc/client";
4
+ import { ContractJsonifiedClientFactory, JsonifiedClient } from "@orpc/openapi";
5
+ export interface ContractUtilsFactory<TClientContext extends ClientContext> {
6
+ <T extends RouterContract>(contract: T): RouterUtils<RouterContractClient<T, TClientContext>>;
7
+ }
8
+ export interface ContractUtilsFactoryOptions<TClientContext extends ClientContext> extends Omit<RouterUtilsOptions<RouterContractClient<RouterContract, TClientContext>>, "path"> {}
9
+ /**
10
+ * Creates a factory that builds Pinia Colada utils directly from a contract,
11
+ * using the given contract client factory. Useful for scaling large projects
12
+ * where each part only needs a slice of the router.
13
+ *
14
+ * @remarks
15
+ * **Note**: The contract must define a `path` meta matching its position in the root router contract.
16
+ *
17
+ * @see {@link https://orpc.dev/docs/contract/client-factory#pinia-colada-integration | Contract Client Factory - Pinia Colada Integration}
18
+ */
19
+ export declare function createContractUtilsFactory<TClientContext extends ClientContext>(clientFactory: ContractClientFactory<TClientContext>, options: ContractUtilsFactoryOptions<TClientContext>): ContractUtilsFactory<TClientContext>;
20
+ export interface ContractJsonifiedUtilsFactory<TClientContext extends ClientContext> {
21
+ <T extends RouterContract>(contract: T): RouterUtils<JsonifiedClient<RouterContractClient<T, TClientContext>>>;
22
+ }
23
+ export interface ContractJsonifiedUtilsFactoryOptions<TClientContext extends ClientContext> extends Omit<RouterUtilsOptions<JsonifiedClient<RouterContractClient<RouterContract, TClientContext>>>, "path"> {}
24
+ /**
25
+ * Like `createContractUtilsFactory`, but for clients whose types are wrapped in `JsonifiedClient`,
26
+ * such as clients using OpenAPI Link.
27
+ *
28
+ * @remarks
29
+ * Takes a client factory created by `createContractJsonifiedClientFactory` from `@orpc/openapi`.
30
+ *
31
+ * **Note**: The contract must define a `path` meta matching its position in the root router contract.
32
+ *
33
+ * @see {@link https://orpc.dev/docs/contract/client-factory#pinia-colada-integration | Contract Client Factory - Pinia Colada Integration}
34
+ */
35
+ export declare function createContractJsonifiedUtilsFactory<TClientContext extends ClientContext>(clientFactory: ContractJsonifiedClientFactory<TClientContext>, options: ContractJsonifiedUtilsFactoryOptions<TClientContext>): ContractJsonifiedUtilsFactory<TClientContext>;
@@ -0,0 +1,42 @@
1
+ import { createRouterUtils } from "./router-utils.js";
2
+ import { resolveBasePathMeta } from "@orpc/contract";
3
+ import { get } from "@orpc/shared";
4
+ // src/contract-utils.ts
5
+ /**
6
+ * Creates a factory that builds Pinia Colada utils directly from a contract,
7
+ * using the given contract client factory. Useful for scaling large projects
8
+ * where each part only needs a slice of the router.
9
+ *
10
+ * @remarks
11
+ * **Note**: The contract must define a `path` meta matching its position in the root router contract.
12
+ *
13
+ * @see {@link https://orpc.dev/docs/contract/client-factory#pinia-colada-integration | Contract Client Factory - Pinia Colada Integration}
14
+ */
15
+ function createContractUtilsFactory(clientFactory, options) {
16
+ const factory = (contract) => {
17
+ const client = clientFactory(contract);
18
+ const path = resolveBasePathMeta(contract);
19
+ if (path === void 0) throw new TypeError("ContractUtilsFactory: procedure contract must define `meta.path` that matches its path in the root router contract.");
20
+ return createRouterUtils(client, {
21
+ ...options,
22
+ path,
23
+ scoped: get(options.scoped, path)
24
+ });
25
+ };
26
+ return factory;
27
+ }
28
+ /**
29
+ * Like `createContractUtilsFactory`, but for clients whose types are wrapped in `JsonifiedClient`,
30
+ * such as clients using OpenAPI Link.
31
+ *
32
+ * @remarks
33
+ * Takes a client factory created by `createContractJsonifiedClientFactory` from `@orpc/openapi`.
34
+ *
35
+ * **Note**: The contract must define a `path` meta matching its position in the root router contract.
36
+ *
37
+ * @see {@link https://orpc.dev/docs/contract/client-factory#pinia-colada-integration | Contract Client Factory - Pinia Colada Integration}
38
+ */
39
+ function createContractJsonifiedUtilsFactory(clientFactory, options) {
40
+ return createContractUtilsFactory(clientFactory, options);
41
+ }
42
+ export { createContractJsonifiedUtilsFactory, createContractUtilsFactory };
@@ -0,0 +1,13 @@
1
+ import { ContractJsonifiedUtilsFactory, ContractJsonifiedUtilsFactoryOptions, ContractUtilsFactory, ContractUtilsFactoryOptions, createContractJsonifiedUtilsFactory, createContractUtilsFactory } from "./contract-utils.js";
2
+ import { OperationKey, OperationKeyBaseOptions, OperationKeyOptions, OperationKeyPrefixOptions } from "./key.js";
3
+ import { ContractOptionsUtilsPlugin, PiniaColadaMetaOptions, PiniaColadaMetaPlugin, getPiniaColadaMeta, piniaColada } from "./meta.js";
4
+ import { RouterUtilsPlugin } from "./plugin.js";
5
+ import { ProcedureUtils, ProcedureUtilsInfiniteInterceptor, ProcedureUtilsInfiniteInterceptorOptions, ProcedureUtilsLiveInterceptor, ProcedureUtilsLiveInterceptorOptions, ProcedureUtilsModifier, ProcedureUtilsMutationInterceptor, ProcedureUtilsMutationInterceptorOptions, ProcedureUtilsOptions, ProcedureUtilsQueryInterceptor, ProcedureUtilsQueryInterceptorOptions, ProcedureUtilsStreamedInterceptor, ProcedureUtilsStreamedInterceptorOptions, mergeProcedureUtilsOptions } from "./procedure-utils.js";
6
+ import { RouterUtils, RouterUtilsOptions, RouterUtilsScoped, createRouterUtils } from "./router-utils.js";
7
+ import { SharedUtils } from "./shared-utils.js";
8
+ import { StreamQuerySSRUtilsPlugin, StreamQuerySSRUtilsPluginOptions } from "./ssr.js";
9
+ import { SerializableStreamedQueryOptions, SettleOnFirstDataOptions } from "./stream-query.js";
10
+ import { InferLiveQueryOutput, InferStreamedQueryOutput, InfiniteKeyOptions, InfiniteOptionsIn, InfiniteOptionsOut, LiveOptionsIn, MutationKeyOptions, MutationOptionsIn, MutationOptionsOut, OPERATION_CONTEXT_SYMBOL, OperationContext, OperationType, QueryKeyOptions, QueryOptionsIn, QueryOptionsOut, StreamedKeyOptions, StreamedOptionsIn, StreamedOptionsOut, UseMutationFnContext, UseQueryFnContext } from "./types.js";
11
+ import { Public } from "@orpc/shared";
12
+ import { AnyNestedClient } from "@orpc/client";
13
+ export { type AnyNestedClient, ContractJsonifiedUtilsFactory, ContractJsonifiedUtilsFactoryOptions, ContractOptionsUtilsPlugin, ContractUtilsFactory, ContractUtilsFactoryOptions, InferLiveQueryOutput, InferStreamedQueryOutput, InfiniteKeyOptions, InfiniteOptionsIn, InfiniteOptionsOut, LiveOptionsIn, MutationKeyOptions, MutationOptionsIn, MutationOptionsOut, OPERATION_CONTEXT_SYMBOL, OperationContext, type OperationKey, type OperationKeyBaseOptions, type OperationKeyOptions, type OperationKeyPrefixOptions, OperationType, OPERATION_CONTEXT_SYMBOL as PINIA_COLADA_OPERATION_CONTEXT_SYMBOL, PiniaColadaMetaOptions, PiniaColadaMetaPlugin, type OperationContext as PiniaColadaOperationContext, ProcedureUtils, type ProcedureUtilsInfiniteInterceptor, type ProcedureUtilsInfiniteInterceptorOptions, type ProcedureUtilsLiveInterceptor, type ProcedureUtilsLiveInterceptorOptions, type ProcedureUtilsModifier, type ProcedureUtilsMutationInterceptor, type ProcedureUtilsMutationInterceptorOptions, type ProcedureUtilsOptions, type ProcedureUtilsQueryInterceptor, type ProcedureUtilsQueryInterceptorOptions, type ProcedureUtilsStreamedInterceptor, type ProcedureUtilsStreamedInterceptorOptions, type Public, QueryKeyOptions, QueryOptionsIn, QueryOptionsOut, RouterUtils, RouterUtilsOptions, type RouterUtilsPlugin, RouterUtilsScoped, type SerializableStreamedQueryOptions, type SettleOnFirstDataOptions, SharedUtils, StreamQuerySSRUtilsPlugin, StreamQuerySSRUtilsPluginOptions, StreamedKeyOptions, StreamedOptionsIn, StreamedOptionsOut, UseMutationFnContext, UseQueryFnContext, createContractJsonifiedUtilsFactory, createContractUtilsFactory, createRouterUtils as createORPCVueColadaUtils, createRouterUtils as createPiniaColadaUtils, createRouterUtils, getPiniaColadaMeta, mergeProcedureUtilsOptions, piniaColada };
package/dist/index.js ADDED
@@ -0,0 +1,7 @@
1
+ export { createContractJsonifiedUtilsFactory, createContractUtilsFactory } from "./contract-utils.js";
2
+ export { ContractOptionsUtilsPlugin, getPiniaColadaMeta, piniaColada } from "./meta.js";
3
+ export { ProcedureUtils, mergeProcedureUtilsOptions } from "./procedure-utils.js";
4
+ export { createRouterUtils as createORPCVueColadaUtils, createRouterUtils as createPiniaColadaUtils, createRouterUtils } from "./router-utils.js";
5
+ export { SharedUtils } from "./shared-utils.js";
6
+ export { StreamQuerySSRUtilsPlugin } from "./ssr.js";
7
+ export { OPERATION_CONTEXT_SYMBOL, OPERATION_CONTEXT_SYMBOL as PINIA_COLADA_OPERATION_CONTEXT_SYMBOL } from "./types.js";
package/dist/key.d.ts ADDED
@@ -0,0 +1,36 @@
1
+ import { SerializableStreamedQueryOptions } from "./stream-query.js";
2
+ import { OperationType } from "./types.js";
3
+ import { PartialDeep, Public } from "@orpc/shared";
4
+ import { RPCJsonSerializer } from "@orpc/client";
5
+ import { EntryKey } from "@pinia/colada";
6
+ export interface OperationKeyPrefixOptions {
7
+ /**
8
+ * Prepended as the first element of the key when present.
9
+ * Use this to avoid key conflicts when multiple router utils share the same client.
10
+ */
11
+ prefix?: string | undefined;
12
+ }
13
+ export interface OperationKeyBaseOptions extends OperationKeyPrefixOptions {
14
+ /**
15
+ * Serializes inputs into JSON-compatible values when building keys.
16
+ * Pass the serializer your link uses so custom types produce consistent keys.
17
+ *
18
+ * @default new RPCJsonSerializer()
19
+ */
20
+ serializer?: Public<RPCJsonSerializer> | undefined;
21
+ }
22
+ export type OperationKeyOptions<TType extends OperationType, TInput> = OperationKeyBaseOptions & {
23
+ type?: TType | undefined;
24
+ input?: PartialDeep<TInput> | undefined;
25
+ fnOptions?: (TType extends "streamed" ? SerializableStreamedQueryOptions : never) | undefined;
26
+ };
27
+ type OperationKeyContent<TType extends OperationType, TInput> = Omit<OperationKeyOptions<TType, TInput>, keyof OperationKeyBaseOptions> & {
28
+ /**
29
+ * Serializer types of non-JSON values in `input`, keyed by their JSON-encoded path,
30
+ * so inputs with the same JSON form (like a `Date` and its ISO string) produce different keys.
31
+ * Keyed by path (not a list) so partial keys still match.
32
+ */
33
+ inputMeta?: Record<string, string[]> | undefined;
34
+ };
35
+ export type OperationKey<TType extends OperationType, TInput> = EntryKey & ([path: string[], options: OperationKeyContent<TType, TInput>] | [prefix: string, path: string[], options: OperationKeyContent<TType, TInput>]);
36
+ export {};
package/dist/key.js ADDED
@@ -0,0 +1,45 @@
1
+ import { stringifyJSON } from "@orpc/shared";
2
+ import { RPCJsonSerializer } from "@orpc/client";
3
+ // src/key.ts
4
+ const defaultSerializer = /* @__PURE__ */ new RPCJsonSerializer();
5
+ /**
6
+ * Generate a Pinia Colada entry key for a procedure.
7
+ *
8
+ * The input is serialized to JSON-compatible values because Pinia Colada
9
+ * requires entry keys to be serializable.
10
+ *
11
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#querymutation-key | Pinia Colada Integration - Query/Mutation Key}
12
+ */
13
+ function generateOperationKey(path, options = {}) {
14
+ return [
15
+ ...options.prefix !== void 0 ? [options.prefix] : [],
16
+ path,
17
+ {
18
+ ...options.input !== void 0 ? serializeInput(options.serializer ?? defaultSerializer, options.input) : {},
19
+ ...options.type !== void 0 ? { type: options.type } : {},
20
+ ...streamedKeyOptions(options.fnOptions)
21
+ }
22
+ ];
23
+ }
24
+ function serializeInput(serializer, input) {
25
+ const { json, meta } = serializer.serializeJson(input);
26
+ if (!meta?.length) return { input: json };
27
+ const inputMeta = {};
28
+ for (const [type, ...segments] of meta) (inputMeta[stringifyJSON(segments)] ??= []).push(type);
29
+ return {
30
+ input: json,
31
+ inputMeta
32
+ };
33
+ }
34
+ /**
35
+ * Leaves out default streamed options, so passing a default gives the same key as omitting it.
36
+ */
37
+ function streamedKeyOptions(options) {
38
+ const { refetchMode, maxChunks } = options ?? {};
39
+ const fnOptions = {
40
+ ...refetchMode !== void 0 && refetchMode !== "reset" ? { refetchMode } : {},
41
+ ...maxChunks !== void 0 && maxChunks !== Number.POSITIVE_INFINITY ? { maxChunks } : {}
42
+ };
43
+ return Object.keys(fnOptions).length > 0 ? { fnOptions } : {};
44
+ }
45
+ export { generateOperationKey };
@@ -0,0 +1,34 @@
1
+ import { listenAbort, stringifyJSON, throwIfAborted } from "@orpc/shared";
2
+ // src/live-query.ts
3
+ /**
4
+ * A Pinia Colada query function that publishes each streamed chunk to the
5
+ * cache entry as it arrives, replacing the previous value.
6
+ */
7
+ function liveQuery(queryFn, { settleOnFirstData = false } = {}) {
8
+ return async (context) => {
9
+ const { entry, signal } = context;
10
+ listenAbort(signal, () => {
11
+ entry.when = 0;
12
+ });
13
+ const stream = await queryFn(context);
14
+ if (signal.aborted) {
15
+ await stream[Symbol.asyncIterator]().return?.();
16
+ throw signal.reason;
17
+ }
18
+ let last;
19
+ for await (const chunk of stream) {
20
+ throwIfAborted(signal);
21
+ last = { chunk };
22
+ entry.state.value = {
23
+ status: "success",
24
+ data: chunk,
25
+ error: null
26
+ };
27
+ if (settleOnFirstData) break;
28
+ }
29
+ throwIfAborted(signal);
30
+ if (!last) throw new TypeError(`Live query for ${stringifyJSON(entry.key)} did not yield any data. Ensure the query function returns an AsyncIterable with at least one chunk.`);
31
+ return last.chunk;
32
+ };
33
+ }
34
+ export { liveQuery };
package/dist/meta.d.ts ADDED
@@ -0,0 +1,42 @@
1
+ import { OperationKeyBaseOptions } from "./key.js";
2
+ import { RouterUtilsPlugin } from "./plugin.js";
3
+ import { ProcedureUtilsOptions } from "./procedure-utils.js";
4
+ import { AnySchema, ErrorMap, InferSchemaInput, InferSchemaOutput, Meta, MetaPlugin, ORPCErrorFromErrorMap, RouterContract } from "@orpc/contract";
5
+ import { ThrowableError } from "@orpc/shared";
6
+ import { AnyNestedClient, ClientContext, InferClientContext, InferClientError } from "@orpc/client";
7
+ export type PiniaColadaMetaOptions<TClientContext extends ClientContext, TInput, TOutput, TError> = Omit<ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>, keyof OperationKeyBaseOptions>;
8
+ export interface PiniaColadaMetaPlugin<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> extends MetaPlugin<TInputSchema, TOutputSchema, TErrorMap> {
9
+ name: "~pinia-colada";
10
+ }
11
+ /**
12
+ * Define base Pinia Colada options and interceptors on a procedure contract.
13
+ * Applied multiple times, later options are spread-merged with higher priority
14
+ * while interceptors are concatenated. A key explicitly set to `undefined`
15
+ * resets the value from earlier applications instead of merging.
16
+ *
17
+ * Apply them to router utils with {@link ContractOptionsUtilsPlugin}.
18
+ *
19
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#contract-options-plugin | Pinia Colada Integration - Contract Options Plugin}
20
+ */
21
+ export declare function piniaColada<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap>(options: PiniaColadaMetaOptions<ClientContext, InferSchemaInput<TInputSchema>, InferSchemaOutput<TOutputSchema>, ORPCErrorFromErrorMap<TErrorMap> | ThrowableError>): PiniaColadaMetaPlugin<TInputSchema, TOutputSchema, TErrorMap>;
22
+ export declare function getPiniaColadaMeta(procedureOrLazy: {
23
+ "~orpc": {
24
+ meta: Meta;
25
+ };
26
+ }): PiniaColadaMetaOptions<ClientContext, unknown, unknown, ThrowableError> | undefined;
27
+ /**
28
+ * Router utils plugin that applies base options defined via {@link piniaColada}
29
+ * on the given router contract. Meta options act as the base layer: options defined
30
+ * on the utils override them, and utils interceptors run after meta interceptors.
31
+ *
32
+ * The contract shape must match the client the utils are created from,
33
+ * so pass the root router contract when utils paths start from the root.
34
+ *
35
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#contract-options-plugin | Pinia Colada Integration - Contract Options Plugin}
36
+ */
37
+ export declare class ContractOptionsUtilsPlugin<T extends AnyNestedClient = AnyNestedClient> implements RouterUtilsPlugin<T> {
38
+ private readonly contract;
39
+ readonly name = "~contract-options";
40
+ constructor(contract: RouterContract);
41
+ initProcedureOptions(path: string[], options: ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>): ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>;
42
+ }
package/dist/meta.js ADDED
@@ -0,0 +1,53 @@
1
+ import { mergeProcedureUtilsOptions } from "./procedure-utils.js";
2
+ import { ProcedureContract, getRouterContract } from "@orpc/contract";
3
+ // src/meta.ts
4
+ /**
5
+ * Define base Pinia Colada options and interceptors on a procedure contract.
6
+ * Applied multiple times, later options are spread-merged with higher priority
7
+ * while interceptors are concatenated. A key explicitly set to `undefined`
8
+ * resets the value from earlier applications instead of merging.
9
+ *
10
+ * Apply them to router utils with {@link ContractOptionsUtilsPlugin}.
11
+ *
12
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#contract-options-plugin | Pinia Colada Integration - Contract Options Plugin}
13
+ */
14
+ function piniaColada(options) {
15
+ return {
16
+ name: "~pinia-colada",
17
+ init(meta) {
18
+ const current = meta["~pinia-colada"];
19
+ return {
20
+ ...meta,
21
+ "~pinia-colada": current ? mergeProcedureUtilsOptions(current, options) : options
22
+ };
23
+ }
24
+ };
25
+ }
26
+ function getPiniaColadaMeta(procedureOrLazy) {
27
+ return procedureOrLazy["~orpc"].meta["~pinia-colada"];
28
+ }
29
+ /**
30
+ * Router utils plugin that applies base options defined via {@link piniaColada}
31
+ * on the given router contract. Meta options act as the base layer: options defined
32
+ * on the utils override them, and utils interceptors run after meta interceptors.
33
+ *
34
+ * The contract shape must match the client the utils are created from,
35
+ * so pass the root router contract when utils paths start from the root.
36
+ *
37
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#contract-options-plugin | Pinia Colada Integration - Contract Options Plugin}
38
+ */
39
+ var ContractOptionsUtilsPlugin = class {
40
+ contract;
41
+ name = "~contract-options";
42
+ constructor(contract) {
43
+ this.contract = contract;
44
+ }
45
+ initProcedureOptions(path, options) {
46
+ const procedure = getRouterContract(this.contract, path);
47
+ if (!(procedure instanceof ProcedureContract)) return options;
48
+ const base = getPiniaColadaMeta(procedure);
49
+ if (!base) return options;
50
+ return mergeProcedureUtilsOptions(base, options);
51
+ }
52
+ };
53
+ export { ContractOptionsUtilsPlugin, getPiniaColadaMeta, piniaColada };
@@ -0,0 +1,39 @@
1
+ import { ProcedureUtilsOptions } from "./procedure-utils.js";
2
+ import { RouterUtilsOptions } from "./router-utils.js";
3
+ import { OrderablePlugin } from "@orpc/shared";
4
+ import { AnyNestedClient, InferClientContext, InferClientError } from "@orpc/client";
5
+ export interface RouterUtilsPlugin<T extends AnyNestedClient> extends OrderablePlugin {
6
+ /**
7
+ * Initializes the router utils plugin and returns updated router utils options.
8
+ * Called once per plugin instance during composition.
9
+ *
10
+ * This method allows plugins to wrap, extend, or transform router utils options,
11
+ * such as interceptors or configuration.
12
+ *
13
+ * @param options - The current router utils options from previous plugins or base configuration
14
+ * @returns Transformed router utils options with this plugin's modifications applied
15
+ *
16
+ * @example
17
+ * ```ts
18
+ * init(options) {
19
+ * return {
20
+ * ...options,
21
+ * mutationInterceptors: [...(options.mutationInterceptors ?? []), myInterceptor]
22
+ * }
23
+ * }
24
+ * ```
25
+ */
26
+ init?(options: RouterUtilsOptions<T>): RouterUtilsOptions<T>;
27
+ /**
28
+ * Initializes per-procedure router utils options and returns updated options.
29
+ * Called once per procedure utils instance during composition.
30
+ *
31
+ * This method allows plugins to customize merged procedure-specific defaults,
32
+ * such as query or mutation options, for the current path.
33
+ *
34
+ * @param path - The current procedure path
35
+ * @param options - The merged procedure utils options for the current procedure
36
+ * @returns Transformed procedure utils options with this plugin's modifications applied
37
+ */
38
+ initProcedureOptions?(path: string[], options: ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>): ProcedureUtilsOptions<InferClientContext<T>, any, any, InferClientError<T>>;
39
+ }
package/dist/plugin.js ADDED
@@ -0,0 +1,19 @@
1
+ import { sortPlugins } from "@orpc/shared";
2
+ // src/plugin.ts
3
+ var CompositeRouterUtilsPlugin = class {
4
+ plugins;
5
+ name = "~composite";
6
+ constructor(plugins = []) {
7
+ this.plugins = plugins;
8
+ this.plugins = sortPlugins(plugins);
9
+ }
10
+ init(options) {
11
+ for (const plugin of this.plugins) if (plugin.init) options = plugin.init(options);
12
+ return options;
13
+ }
14
+ initProcedureOptions(path, options) {
15
+ for (const plugin of this.plugins) if (plugin.initProcedureOptions) options = plugin.initProcedureOptions(path, options);
16
+ return options;
17
+ }
18
+ };
19
+ export { CompositeRouterUtilsPlugin };
@@ -0,0 +1,187 @@
1
+ import { OperationKeyBaseOptions } from "./key.js";
2
+ import { SharedUtils } from "./shared-utils.js";
3
+ import { InferLiveQueryOutput, InferStreamedQueryOutput, InfiniteKeyOptions, InfiniteOptionsIn, InfiniteOptionsOut, LiveOptionsIn, MutationKeyOptions, MutationOptionsIn, MutationOptionsOut, OperationContext, QueryKeyOptions, QueryOptionsIn, QueryOptionsOut, StreamedKeyOptions, StreamedOptionsIn, StreamedOptionsOut, UseMutationFnContext, UseQueryFnContext } from "./types.js";
4
+ import { Interceptor, MaybeOptionalOptions, PromiseWithError } from "@orpc/shared";
5
+ import { Client, ClientContext } from "@orpc/client";
6
+ import { EntryKeyTagged, UseInfiniteQueryData, UseInfiniteQueryFnContext, _EmptyObject } from "@pinia/colada";
7
+ export interface ProcedureUtilsQueryInterceptorOptions<TClientContext extends ClientContext, TInput> {
8
+ path: string[];
9
+ context: TClientContext & OperationContext;
10
+ input: TInput;
11
+ fnContext: UseQueryFnContext;
12
+ }
13
+ export type ProcedureUtilsQueryInterceptor<TClientContext extends ClientContext, TInput, TOutput, TError> = Interceptor<ProcedureUtilsQueryInterceptorOptions<TClientContext, TInput>, PromiseWithError<TOutput, TError>>;
14
+ export interface ProcedureUtilsStreamedInterceptorOptions<TClientContext extends ClientContext, TInput> extends ProcedureUtilsQueryInterceptorOptions<TClientContext, TInput> {}
15
+ export type ProcedureUtilsStreamedInterceptor<TClientContext extends ClientContext, TInput, TOutput, TError> = Interceptor<ProcedureUtilsStreamedInterceptorOptions<TClientContext, TInput>, PromiseWithError<InferStreamedQueryOutput<TOutput>, TError>>;
16
+ export interface ProcedureUtilsLiveInterceptorOptions<TClientContext extends ClientContext, TInput> extends ProcedureUtilsQueryInterceptorOptions<TClientContext, TInput> {}
17
+ export type ProcedureUtilsLiveInterceptor<TClientContext extends ClientContext, TInput, TOutput, TError> = Interceptor<ProcedureUtilsLiveInterceptorOptions<TClientContext, TInput>, PromiseWithError<InferLiveQueryOutput<TOutput>, TError>>;
18
+ export interface ProcedureUtilsInfiniteInterceptorOptions<TClientContext extends ClientContext, TInput> {
19
+ path: string[];
20
+ context: TClientContext & OperationContext;
21
+ input: TInput;
22
+ fnContext: UseInfiniteQueryFnContext<any, any, any, any>;
23
+ }
24
+ export type ProcedureUtilsInfiniteInterceptor<TClientContext extends ClientContext, TInput, TOutput, TError> = Interceptor<ProcedureUtilsInfiniteInterceptorOptions<TClientContext, TInput>, PromiseWithError<TOutput, TError>>;
25
+ export interface ProcedureUtilsMutationInterceptorOptions<TClientContext extends ClientContext, TInput> {
26
+ path: string[];
27
+ context: TClientContext & OperationContext;
28
+ input: TInput;
29
+ fnContext: UseMutationFnContext;
30
+ }
31
+ export type ProcedureUtilsMutationInterceptor<TClientContext extends ClientContext, TInput, TOutput, TError> = Interceptor<ProcedureUtilsMutationInterceptorOptions<TClientContext, TInput>, PromiseWithError<TOutput, TError>>;
32
+ /**
33
+ * Can be partial options for spread-merged options,
34
+ * or a function that receives per-call options and returns overridden this.options.
35
+ */
36
+ export type ProcedureUtilsModifier<T extends object> = Partial<T> | ((options: T) => T);
37
+ export interface ProcedureUtilsOptions<TClientContext extends ClientContext, TInput, TOutput, TError> extends OperationKeyBaseOptions {
38
+ /**
39
+ * Key options modifier for .queryKey and .queryOptions
40
+ * Can be partial options or a function that receives per-call options and returns override this.options.
41
+ */
42
+ queryKey?: ProcedureUtilsModifier<QueryKeyOptions<TInput>> | undefined;
43
+ /**
44
+ * Interceptors that intercept query inside .queryOptions, guaranteed to be executed.
45
+ */
46
+ queryInterceptors?: ProcedureUtilsQueryInterceptor<TClientContext, TInput, TOutput, TError>[] | undefined;
47
+ /**
48
+ * Options modifier for .queryOptions
49
+ * Can be partial options or a function that receives per-call options and returns override this.options.
50
+ */
51
+ queryOptions?: ProcedureUtilsModifier<QueryOptionsIn<TClientContext, TInput, TOutput, TError, TOutput | undefined>> | undefined;
52
+ /**
53
+ * Key options modifier for .streamedKey and .streamedOptions
54
+ * Can be partial options or a function that receives per-call options and returns override this.options.
55
+ */
56
+ streamedKey?: ProcedureUtilsModifier<StreamedKeyOptions<TInput>> | undefined;
57
+ /**
58
+ * Interceptors that intercept query inside .streamedOptions, guaranteed to be executed.
59
+ */
60
+ streamedInterceptors?: ProcedureUtilsStreamedInterceptor<TClientContext, TInput, TOutput, TError>[] | undefined;
61
+ /**
62
+ * Options modifier for .streamedOptions
63
+ * Can be partial options or a function that receives per-call options and returns override this.options.
64
+ */
65
+ streamedOptions?: ProcedureUtilsModifier<StreamedOptionsIn<TClientContext, TInput, InferStreamedQueryOutput<TOutput>, TError, InferStreamedQueryOutput<TOutput> | undefined>> | undefined;
66
+ /**
67
+ * Key options modifier for .liveKey and .liveOptions
68
+ * Can be partial options or a function that receives per-call options and returns override this.options.
69
+ */
70
+ liveKey?: ProcedureUtilsModifier<QueryKeyOptions<TInput>> | undefined;
71
+ /**
72
+ * Interceptors that intercept query inside .liveOptions, guaranteed to be executed.
73
+ */
74
+ liveInterceptors?: ProcedureUtilsLiveInterceptor<TClientContext, TInput, TOutput, TError>[] | undefined;
75
+ /**
76
+ * Options modifier for .liveOptions
77
+ * Can be partial options or a function that receives per-call options and returns override this.options.
78
+ */
79
+ liveOptions?: ProcedureUtilsModifier<LiveOptionsIn<TClientContext, TInput, InferLiveQueryOutput<TOutput>, TError, InferLiveQueryOutput<TOutput> | undefined>> | undefined;
80
+ /**
81
+ * Key options modifier for .infiniteKey and .infiniteOptions
82
+ * Can be partial options or a function that receives per-call options and returns override this.options.
83
+ */
84
+ infiniteKey?: ProcedureUtilsModifier<InfiniteKeyOptions<TInput, unknown>> | undefined;
85
+ /**
86
+ * Interceptors that intercept query inside .infiniteOptions, guaranteed to be executed.
87
+ */
88
+ infiniteInterceptors?: ProcedureUtilsInfiniteInterceptor<TClientContext, TInput, TOutput, TError>[] | undefined;
89
+ /**
90
+ * Options modifier for .infiniteOptions
91
+ * Can be partial options or a function that receives per-call options and returns override this.options.
92
+ */
93
+ infiniteOptions?: ProcedureUtilsModifier<InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, unknown, UseInfiniteQueryData<TOutput, unknown> | undefined>> | undefined;
94
+ /**
95
+ * Key options modifier for .mutationKey and .mutationOptions
96
+ * Can be partial options or a function that receives per-call options and returns override this.options.
97
+ */
98
+ mutationKey?: ProcedureUtilsModifier<MutationKeyOptions<TInput>> | undefined;
99
+ /**
100
+ * Interceptors that intercept mutation inside .mutationOptions, guaranteed to be executed.
101
+ */
102
+ mutationInterceptors?: ProcedureUtilsMutationInterceptor<TClientContext, TInput, TOutput, TError>[] | undefined;
103
+ /**
104
+ * Options modifier for .mutationOptions
105
+ * Can be partial options or a function that receives per-call options and returns override this.options.
106
+ */
107
+ mutationOptions?: ProcedureUtilsModifier<MutationOptionsIn<TClientContext, TInput, TOutput, TError, Record<any, any>>> | undefined;
108
+ }
109
+ /**
110
+ * Merge two procedure utils options where `override` takes priority.
111
+ * A key explicitly set to `undefined` in `override` resets the base value.
112
+ * When both sides define a key, interceptors are concatenated (base ones run first) and
113
+ * modifiers are combined so that, for object values, per-call options beat `override`,
114
+ * which beats `base`. A function modifier receives the merged options and its result wins.
115
+ */
116
+ export declare function mergeProcedureUtilsOptions<TClientContext extends ClientContext, TInput, TOutput, TError>(base: ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>, override: ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>): ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>;
117
+ export declare class ProcedureUtils<TClientContext extends ClientContext, TInput, TOutput, TError> extends SharedUtils<TInput> {
118
+ protected readonly options: ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>;
119
+ /**
120
+ * Calling corresponding procedure client
121
+ *
122
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#calling-procedure-clients | Pinia Colada Integration - Calling Procedure Clients}
123
+ */
124
+ call: Client<TClientContext, TInput, TOutput, TError>;
125
+ constructor(path: string[], client: Client<TClientContext, TInput, TOutput, TError>, options?: ProcedureUtilsOptions<TClientContext, TInput, TOutput, TError>);
126
+ /**
127
+ * Generate a **full matching** key for useQuery/...
128
+ *
129
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#querymutation-key | Pinia Colada Integration - Query/Mutation Key}
130
+ */
131
+ queryKey(...rest: MaybeOptionalOptions<QueryKeyOptions<TInput>>): EntryKeyTagged<TOutput, TError>;
132
+ /**
133
+ * Generate options used for useQuery/...
134
+ *
135
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#query-options-utility | Pinia Colada Integration - Query Options Utility}
136
+ */
137
+ queryOptions<UInitialData extends TOutput | undefined = TOutput | undefined>(...rest: MaybeOptionalOptions<QueryOptionsIn<TClientContext, TInput, TOutput, TError, UInitialData>>): NoInfer<QueryOptionsOut<TOutput, TError, UInitialData>>;
138
+ /**
139
+ * Generate a **full matching** key for [Streamed Query Options](https://orpc.dev/docs/integrations/pinia-colada#streamed-query-options-utility).
140
+ *
141
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#querymutation-key | Pinia Colada Integration - Query/Mutation Key}
142
+ */
143
+ streamedKey(...rest: MaybeOptionalOptions<StreamedKeyOptions<TInput>>): EntryKeyTagged<InferStreamedQueryOutput<TOutput>, TError>;
144
+ /**
145
+ * Configure queries for [AsyncIteratorObject](https://orpc.dev/docs/async-iterator-object).
146
+ * The resulting data is an array of chunks, and each new chunk is appended as it arrives.
147
+ * It never returns to pending once it has data.
148
+ * Works with `useQuery` and any other API that accepts query options.
149
+ */
150
+ streamedOptions<UInitialData extends InferStreamedQueryOutput<TOutput> | undefined = undefined>(...rest: MaybeOptionalOptions<StreamedOptionsIn<TClientContext, TInput, InferStreamedQueryOutput<TOutput>, TError, UInitialData>>): NoInfer<StreamedOptionsOut<InferStreamedQueryOutput<TOutput>, TError, UInitialData>>;
151
+ /**
152
+ * Generate a **full matching** key for [Live Query Options](https://orpc.dev/docs/integrations/pinia-colada#live-query-options-utility).
153
+ *
154
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#querymutation-key | Pinia Colada Integration - Query/Mutation Key}
155
+ */
156
+ liveKey(...rest: MaybeOptionalOptions<QueryKeyOptions<TInput>>): EntryKeyTagged<InferLiveQueryOutput<TOutput>, TError>;
157
+ /**
158
+ * Configure live queries for [AsyncIteratorObject](https://orpc.dev/docs/async-iterator-object).
159
+ * Unlike `.streamedOptions` which accumulates chunks, live queries replace the entire result with each new chunk received.
160
+ * Works with `useQuery` and any other API that accepts query options.
161
+ */
162
+ liveOptions<UInitialData extends InferLiveQueryOutput<TOutput> | undefined = undefined>(...rest: MaybeOptionalOptions<LiveOptionsIn<TClientContext, TInput, InferLiveQueryOutput<TOutput>, TError, UInitialData>>): NoInfer<QueryOptionsOut<InferLiveQueryOutput<TOutput>, TError, UInitialData>>;
163
+ /**
164
+ * Generate a **full matching** key for useInfiniteQuery/...
165
+ *
166
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#querymutation-key | Pinia Colada Integration - Query/Mutation Key}
167
+ */
168
+ infiniteKey<UPageParam>(optionsIn: InfiniteKeyOptions<TInput, UPageParam>): EntryKeyTagged<UseInfiniteQueryData<TOutput, UPageParam>, TError>;
169
+ /**
170
+ * Generate options used for useInfiniteQuery/...
171
+ *
172
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#infinite-query-options-utility | Pinia Colada Integration - Infinite Query Options Utility}
173
+ */
174
+ infiniteOptions<UPageParam, UInitialData extends UseInfiniteQueryData<TOutput, UPageParam> | undefined = undefined>(optionsIn: InfiniteOptionsIn<TClientContext, TInput, TOutput, TError, UPageParam, UInitialData>): NoInfer<InfiniteOptionsOut<TOutput, TError, UPageParam, UInitialData>>;
175
+ /**
176
+ * Generate a **full matching** key for useMutation/...
177
+ *
178
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#querymutation-key | Pinia Colada Integration - Query/Mutation Key}
179
+ */
180
+ mutationKey(...rest: MaybeOptionalOptions<MutationKeyOptions<TInput>>): MutationOptionsOut<TInput, TOutput, TError, _EmptyObject>["key"];
181
+ /**
182
+ * Generate options used for useMutation/...
183
+ *
184
+ * @see {@link https://orpc.dev/docs/integrations/pinia-colada#mutation-options | Pinia Colada Integration - Mutation Options}
185
+ */
186
+ mutationOptions<UMutationContext extends Record<any, any> = _EmptyObject>(...rest: MaybeOptionalOptions<MutationOptionsIn<TClientContext, TInput, TOutput, TError, UMutationContext>>): NoInfer<MutationOptionsOut<TInput, TOutput, TError, UMutationContext>>;
187
+ }