@firsthandjs/data-urql 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firsthand contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# @firsthandjs/data-urql
+
+urql documents as loaders 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 —
+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 InvoicesDocument from './invoices.gql';
+
+const billing = urqlLoader(
+  new Client({
+    url: '/graphql',
+    exchanges: [fetchExchange],
+    fetchOptions: () => ({ headers: { authorization: `Bearer ${session.token.value}` } }),
+  }),
+);
+
+function Invoices() {
+  const invoices = useResource((context) =>
+    billing(InvoicesDocument, { month: month.value })(context),
+  );
+  return <List items={invoices.data.value?.invoices ?? []} />;
+}
+```
+
+`month.value` is read inside the loader, so changing the month runs the query
+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.
+
+```graphql
+query Invoices($month: String!) @tag(name: "invoices", vars: ["month"]) {
+  invoices(month: $month) {
+    id
+    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
+    paidAt
+  }
+}
+```
+
+```tsx
+const pay = useAction((id: string, { signal, invalidates }) =>
+  billing(PayDocument, { id })({ signal, force: true, tags: invalidates }),
+);
+```
+
+MIT licensed. See the [data guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/09-data.md).

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * urql, as loaders 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
+ * this is the one that matters, whether you keep `cacheExchange`. Without it
+ * urql is your transport and the resources are your state; with it urql also
+ * caches, which is a decision worth making on purpose rather than inheriting
+ * from a helper (ADR-0022).
+ *
+ * ```ts
+ * import { Client, fetchExchange } from '@urql/core';
+ * import { urqlLoader } from '@firsthandjs/data-urql';
+ *
+ * const billing = urqlLoader(
+ *   new Client({
+ *     url: '/graphql',
+ *     exchanges: [fetchExchange],
+ *     fetchOptions: () => ({ headers: { authorization: `Bearer ${token.value}` } }),
+ *   }),
+ * );
+ *
+ * const invoices = useResource((context) => billing(InvoicesDocument, { month: month.value })(context));
+ * ```
+ *
+ * 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
+ * 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';
+/** What urql gives back: a wonka source with a promise on it. */
+export interface UrqlResult<T> {
+    data?: T;
+    error?: unknown;
+}
+/** The part of an urql client this package uses. Nothing else. */
+export interface UrqlLike {
+    query(document: string, variables: Variables, context?: Record<string, unknown>): {
+        toPromise(): Promise<UrqlResult<unknown>>;
+    };
+    mutation(document: string, variables: Variables, context?: Record<string, unknown>): {
+        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>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +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};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@firsthandjs/data-urql",
+  "version": "0.5.0",
+  "description": "Loaders for urql, for @firsthandjs/data. Takes your client; never configures it.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@firsthandjs/data": "0.5.0"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firsthandjs/firsthand.git",
+    "directory": "packages/data-urql"
+  },
+  "bugs": {
+    "url": "https://github.com/firsthandjs/firsthand/issues"
+  },
+  "homepage": "https://github.com/firsthandjs/firsthand#readme",
+  "keywords": [
+    "firsthand",
+    "data",
+    "urql",
+    "resources",
+    "tags"
+  ]
+}