@firsthandjs/data-urql 0.5.0 → 0.6.1

package/README.md

@@ -1,34 +1,36 @@
 # @firsthandjs/data-urql
 
-urql documents as loaders for [`@firsthandjs/data`](https://www.npmjs.com/package/@firsthandjs/data).
+urql as a client for [`@firsthandjs/data`](https://www.npmjs.com/package/@firsthandjs/data).
 
 ```
 npm install @firsthandjs/data-urql
 ```
 
-0.30 kB gzip. It has **no dependency on urql** and no peer dependency either —
+0.53 kB gzip. It has **no dependency on urql** and no peer dependency either —
 the two methods it uses are declared structurally. It was checked against
 `@urql/core` 6, which has no React dependency of its own.
 
 ```tsx
 import { Client, fetchExchange } from '@urql/core';
-import { urqlLoader } from '@firsthandjs/data-urql';
-import { useResource } from '@firsthandjs/data';
+import { createUrqlClient } from '@firsthandjs/data-urql';
+import { useAction, useResource } from '@firsthandjs/data';
 import InvoicesDocument from './invoices.gql';
+import PayDocument from './pay.gql';
 
-const billing = urqlLoader(
-  new Client({
-    url: '/graphql',
-    exchanges: [fetchExchange],
-    fetchOptions: () => ({ headers: { authorization: `Bearer ${session.token.value}` } }),
-  }),
+export const billing = createUrqlClient(
+  new Client({ url: '/graphql', exchanges: [fetchExchange] }),
+  // Read per request and untracked: the token may change, and a resource must
+  // not depend on it.
+  { headers: () => ({ authorization: `Bearer ${session.token.peek()}` }) },
 );
 
 function Invoices() {
-  const invoices = useResource((context) =>
-    billing(InvoicesDocument, { month: month.value })(context),
+  const invoices = useResource(({ request }) =>
+    billing.query(InvoicesDocument, { month: month.value })(request),
   );
-  return <List items={invoices.data.value?.invoices ?? []} />;
+  const pay = useAction((id: string, { request }) => billing.mutate(PayDocument, { id })(request));
+
+  return <List items={invoices.data.value?.invoices ?? []} onPay={(id) => void pay.run(id)} />;
 }
 ```
 
@@ -38,9 +40,7 @@ again and aborts the one in flight.
 ## Tags come out of the document
 
 `@firsthandjs/data/vite` reads `@tag` and `@invalidates` directives at build
-time and strips them, so what reaches urql is a plain GraphQL document. This
-package binds them against the variables of the call and declares them _before_
-the request goes out — so an invalidation arriving mid-flight still finds it.
+time and strips them, so what reaches urql is a plain GraphQL document.
 
 ```graphql
 query Invoices($month: String!) @tag(name: "invoices", vars: ["month"]) {
@@ -49,27 +49,7 @@ query Invoices($month: String!) @tag(name: "invoices", vars: ["month"]) {
     total
   }
 }
-```
-
-## The decision this package leaves to you: `cacheExchange`
-
-- **Without it,** urql is your transport and the resources are your state. One
-  source of truth.
-- **With it,** urql also caches — which is a real choice, not a default worth
-  inheriting from a helper. `force` is passed on as
-  `requestPolicy: 'network-only'`, so an invalidation reaches past that cache.
-
-If you want urql's cache to be the source of truth for an entity shown in many
-places at once, subscribe to it with `fromObservable` instead of loading it
-per call site. See [ADR-0022](https://github.com/firsthandjs/firsthand/blob/main/docs/adr/0022-resources-not-a-cache.md).
-
-## Mutations
-
-A document whose `kind` is `mutation` goes to `client.mutation`, and what it
-declares is its `@invalidates` directives — so an action hands the document's
-own declaration straight to the store:
 
-```graphql
 mutation Pay($id: ID!) @invalidates(name: "invoices") {
   pay(id: $id) {
     id
@@ -78,10 +58,22 @@ mutation Pay($id: ID!) @invalidates(name: "invoices") {
 }
 ```
 
-```tsx
-const pay = useAction((id: string, { signal, invalidates }) =>
-  billing(PayDocument, { id })({ signal, force: true, tags: invalidates }),
-);
-```
+`query` declares the `@tag` directives into the request before it goes out — so
+an invalidation arriving mid-flight still finds it — and `mutate` declares the
+`@invalidates`. Inside an action the request's tags _are_ the store's
+invalidation, so neither call site writes a tag at all.
+
+## The decision this package leaves to you: `cacheExchange`
+
+- **Without it,** urql is your transport and the resources are your state. Pass
+  `cache: { ttl }` here if you want one anyway; it is the same cache the rest
+  of `@firsthandjs/data` uses, queries only, keyed by operation and variables.
+- **With it,** urql also caches — a real choice, not a default worth inheriting
+  from a helper. `force` is passed on as `requestPolicy: 'network-only'`, so an
+  invalidation reaches past it.
+
+What you should not have is both, because two caches over one piece of data
+disagree. If urql's cache should be the source of truth for an entity shown in
+many places, subscribe to it with `fromObservable` instead.
 
-MIT licensed. See the [data guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/09-data.md).
+MIT licensed. See the [data guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/09-data.md#urql).

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * urql, as loaders for `@firsthandjs/data`.
+ * urql, as a client for `@firsthandjs/data`.
  *
  * It takes a client you built and touches two of its methods. Your exchanges,
  * your authentication, your retry policy stay where they are — including, and
@@ -10,25 +10,26 @@
  *
  * ```ts
  * import { Client, fetchExchange } from '@urql/core';
- * import { urqlLoader } from '@firsthandjs/data-urql';
+ * import { createUrqlClient } from '@firsthandjs/data-urql';
  *
- * const billing = urqlLoader(
- *   new Client({
- *     url: '/graphql',
- *     exchanges: [fetchExchange],
- *     fetchOptions: () => ({ headers: { authorization: `Bearer ${token.value}` } }),
- *   }),
+ * export const billing = createUrqlClient(
+ *   new Client({ url: '/graphql', exchanges: [fetchExchange] }),
+ *   // Read per request and untracked: the token may change, and a resource
+ *   // must not depend on it.
+ *   { headers: () => ({ authorization: `Bearer ${token.value}` }) },
  * );
  *
- * const invoices = useResource((context) => billing(InvoicesDocument, { month: month.value })(context));
+ * const invoices = useResource(({ request }) =>
+ *   billing.query(InvoicesDocument, { month: month.value })(request),
+ * );
  * ```
  *
  * There is no dependency on urql here, and no peer dependency either: the
- * shape below is declared structurally, so this package has no opinion about
+ * shapes below are declared structurally, so this package has no opinion about
  * which version you run. It was checked against `@urql/core` 6, which has no
  * React dependency of its own.
  */
-import { type DocumentArguments, type GraphQLDocument, type LoadContext, type Variables } from '@firsthandjs/data';
+import { type CacheClient, type CacheOptions, type DocumentArguments, type GraphQLDocument, type Loader, type Variables } from '@firsthandjs/data';
 /** What urql gives back: a wonka source with a promise on it. */
 export interface UrqlResult<T> {
     data?: T;
@@ -43,15 +44,38 @@ export interface UrqlLike {
         toPromise(): Promise<UrqlResult<unknown>>;
     };
 }
-/**
- * Binds a urql client so a `.gql` document can be a resource's loader.
- *
- * The tags come from the document's directives, bound against the variables of
- * this call, and are declared before the request goes out — so an invalidation
- * sent while it is in flight still finds it.
- *
- * `force` becomes `requestPolicy: 'network-only'`, which is what makes an
- * invalidation reach past urql's cache if you kept one.
- */
-export declare function urqlLoader(client: UrqlLike): <T, V extends Variables>(document: GraphQLDocument<T, V>, ...rest: DocumentArguments<V>) => ({ tags, force, signal }: LoadContext) => Promise<T>;
+export interface UrqlClientOptions {
+    /**
+     * Headers for every request, sent through urql's `fetchOptions`. A function
+     * is called **per request and untracked**, which is what lets a token change
+     * without making every resource depend on it.
+     */
+    readonly headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * A cache in front of urql: `false` (the default, because urql has one of
+     * its own if you kept `cacheExchange`), options for a cache of this client's
+     * own, or a `CacheClient` shared with the rest of the application. Queries
+     * only, keyed by operation and variables.
+     */
+    readonly cache?: false | CacheOptions | CacheClient;
+    /** Merged into urql's operation context for every request. */
+    readonly context?: Record<string, unknown>;
+}
+export interface UrqlClient {
+    /**
+     * A query, as a loader. Declares the document's `@tag` directives before the
+     * request goes out, so an invalidation sent while it is in flight finds it.
+     */
+    query<T, V extends Variables>(document: GraphQLDocument<T, V>, ...rest: DocumentArguments<V>): Loader<T>;
+    /**
+     * A mutation, as a loader. Declares the document's `@invalidates` directives
+     * into the request — which inside an action is the store's `invalidates`, so
+     * the document's own declaration reaches the store with nothing to wire.
+     */
+    mutate<T, V extends Variables>(document: GraphQLDocument<T, V>, ...rest: DocumentArguments<V>): Loader<T>;
+    /** A copy with some options replaced. The cache is shared unless replaced. */
+    with(options: UrqlClientOptions): UrqlClient;
+    readonly cache: CacheClient | undefined;
+}
+export declare function createUrqlClient(client: UrqlLike, options?: UrqlClientOptions): UrqlClient;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAE3B,iEAAiE;AACjE,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACvB,KAAK,CACH,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC;QAAE,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IACjD,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC;QAAE,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;CAClD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,IAIjC,CAAC,EAAE,CAAC,SAAS,SAAS,EAAE,UAAU,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,iBAAiB,CAAC,CAAC,CAAC,MACrF,yBAAyB,WAAW,KAAG,OAAO,CAAC,CAAC,CAAC,CA0B3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,YAAY,EAEjB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,MAAM,EACX,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAG3B,iEAAiE;AACjE,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACvB,KAAK,CACH,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC;QAAE,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IACjD,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC;QAAE,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;CAClD;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3E;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,YAAY,GAAG,WAAW,CAAC;IACpD,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,SAAS,EAC1B,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAC/B,GAAG,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,MAAM,CAAC,CAAC,CAAC,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,SAAS,EAC3B,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAC/B,GAAG,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,MAAM,CAAC,CAAC,CAAC,CAAC;IACb,8EAA8E;IAC9E,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAsF9F"}

package/dist/index.js

@@ -1 +1 @@
-import{resolveTags as m}from"@firsthandjs/data";function p(t){return(e,...i)=>async({tags:u,force:l,signal:c})=>{let n=i[0]??{},d=e.kind==="mutation"?e.invalidates:e.tags;u(...m(d,n));let r=await((o,a,s)=>e.kind==="mutation"?t.mutation(o,a,s):t.query(o,a,s))(e.source,n,{fetchOptions:{signal:c},requestPolicy:l?"network-only":"cache-first"}).toPromise();if(r.error!==void 0)throw r.error;return r.data}}export{p as urqlLoader};
+import{createCacheClient as h,resolveTags as y}from"@firsthandjs/data";import{untrack as T}from"@firsthandjs/core";function V(c,n={}){let o=n.cache===void 0||n.cache===!1?void 0:"read"in n.cache?n.cache:h(n.cache),l=async(e,t,s,a)=>{let r=typeof n.headers=="function"?T(n.headers):n.headers,i={...n.context,fetchOptions:{signal:a.signal,...r===void 0?{}:{headers:r}},requestPolicy:a.force?"network-only":"cache-first"},u=await(e==="mutation"?c.mutation(t,s,i):c.query(t,s,i)).toPromise();if(u.error!==void 0)throw u.error;return u.data},d=(e,t,s)=>async a=>{let r=s[0]??{};if(a.tags?.(...y(e==="mutation"?t.invalidates:t.tags,r)),o===void 0||e==="mutation")return await l(e,t.source,r,a);let i=`${t.operation}(${JSON.stringify(r)})`;return await o.read(i,m=>l(e,t.source,r,m))(a)};return{cache:o,query:(e,...t)=>d("query",e,t),mutate:(e,...t)=>d("mutation",e,t),with:e=>V(c,{...n,...e,cache:e.cache??o??!1})}}export{V as createUrqlClient};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firsthandjs/data-urql",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Loaders for urql, for @firsthandjs/data. Takes your client; never configures it.",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@firsthandjs/data": "0.5.0"
+    "@firsthandjs/data": "0.6.1"
   },
   "engines": {
     "node": ">=20.11.0"