@firsthandjs/data-apollo 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,68 @@
+# @firsthandjs/data-apollo
+
+Apollo Client documents as loaders for [`@firsthandjs/data`](https://www.npmjs.com/package/@firsthandjs/data).
+
+```
+npm install @firsthandjs/data-apollo
+```
+
+0.37 kB gzip. It has **no dependency on Apollo** and no peer dependency either —
+the three methods it uses are declared structurally. That also keeps your copy
+of `graphql` the only copy, which is a category of afternoon worth avoiding.
+
+```tsx
+import { gql } from '@apollo/client';
+import { apolloLoader } from '@firsthandjs/data-apollo';
+import { useResource } from '@firsthandjs/data';
+import InvoicesDocument from './invoices.gql';
+
+const billing = apolloLoader(apollo, gql);
+
+function Invoices() {
+  const invoices = useResource((context) =>
+    billing(InvoicesDocument, { month: month.value })(context),
+  );
+  return <List items={invoices.data.value?.invoices ?? []} />;
+}
+```
+
+`apolloLoader(client, parse)` takes the parse function too — `gql` from
+`@apollo/client`, or `parse` from `graphql` — because Apollo wants a parsed
+`DocumentNode` and that parser should be yours, not ours.
+
+## The decision this package leaves to you: the cache
+
+Apollo requires an `InMemoryCache`, and it is a _normalising_ cache — a
+different thing from a store of resources. There are two ways to run them
+together, and only two:
+
+- **Apollo as transport.** The resources are your state. `force` is passed on
+  as `fetchPolicy: 'network-only'`, so an invalidation reaches past the cache;
+  set `no-cache` on the client if you want it out of the way entirely.
+- **Apollo as the store.** Use `apolloObservable` instead. One write in
+  Apollo's cache then updates every view of that entity at the same moment,
+  which is what a per-call-site resource cannot do:
+
+  ```tsx
+  const user = fromObservable(...apolloObservable(apollo, gql)(UserDocument, { id: props.id }));
+  ```
+
+What is not on the list is both at once, with the same data living in two
+places under two invalidation rules. See
+[ADR-0022](https://github.com/firsthandjs/firsthand/blob/main/docs/adr/0022-resources-not-a-cache.md).
+
+## Tags come out of the document
+
+`@firsthandjs/data/vite` reads `@tag` and `@invalidates` at build time and
+strips them, so what reaches Apollo is a plain GraphQL document. A query
+declares its `@tag` directives before the request goes out — so an invalidation
+arriving mid-flight still finds it — and a mutation declares its `@invalidates`,
+which an action hands straight to the store:
+
+```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,95 @@
+/**
+ * Apollo Client, as loaders for `@firsthandjs/data`.
+ *
+ * It takes a client you built and touches three of its methods. Your links,
+ * your authentication, your uploads stay where they are — and so does the
+ * decision that matters most here: what to do with Apollo's own cache.
+ *
+ * Apollo requires an `InMemoryCache` instance, and it is a *normalising* cache,
+ * which is a different thing from a store of resources. Two ways to run them
+ * together, and only these two:
+ *
+ *   - **Apollo as transport.** `fetchPolicy: 'no-cache'`, or the `force` this
+ *     package passes on, and the resources are your state. One source of
+ *     truth.
+ *   - **Apollo as the store.** Use `apolloObservable` instead: one write in
+ *     Apollo's cache updates every view of that entity at once, which is what
+ *     a per-call-site resource cannot do. Also one source of truth.
+ *
+ * What is not on the list is both at once (ADR-0022).
+ *
+ * There is no dependency on Apollo here, and no peer dependency either: the
+ * shapes below are declared structurally, so this package has no opinion about
+ * which version you run, and nothing to follow when that version changes.
+ */
+import { type DocumentArguments, type GraphQLDocument, type LoadContext, type Variables } from '@firsthandjs/data';
+/** The part of an Apollo client this package uses. Nothing else. */
+export interface ApolloLike {
+    query(options: Record<string, unknown>): Promise<{
+        data: unknown;
+    }>;
+    mutate(options: Record<string, unknown>): Promise<{
+        data?: unknown;
+    }>;
+}
+/**
+ * How to turn a document's source into whatever Apollo wants.
+ *
+ * Apollo takes a parsed `DocumentNode`, which means `gql` from `@apollo/client`
+ * or `parse` from `graphql` — your copy of it, not ours, since two copies of
+ * `graphql` in one application is its own kind of afternoon.
+ */
+export type Parse = (source: string) => unknown;
+/**
+ * Binds an Apollo client so a `.gql` document can be a resource's loader.
+ *
+ * ```ts
+ * import { gql } from '@apollo/client';
+ * import { apolloLoader } from '@firsthandjs/data-apollo';
+ *
+ * const billing = apolloLoader(apollo, gql);
+ *
+ * const invoices = useResource((context) => billing(InvoicesDocument, { month: month.value })(context));
+ * ```
+ *
+ * The tags come from the document's directives, declared before the request
+ * goes out. `force` becomes `fetchPolicy: 'network-only'`, which is what makes
+ * an invalidation reach past Apollo's cache.
+ */
+export declare function apolloLoader(client: ApolloLike, parse: Parse): <T, V extends Variables>(document: GraphQLDocument<T, V>, ...rest: DocumentArguments<V>) => ({ tags, force }: LoadContext) => Promise<T>;
+/** A watched query: what Apollo pushes when its cache changes. */
+export interface WatchLike {
+    watchQuery(options: Record<string, unknown>): {
+        subscribe(observer: {
+            next?: (value: {
+                data: unknown;
+            }) => void;
+            error?: (error: unknown) => void;
+        }): {
+            unsubscribe: () => void;
+        };
+        refetch(): Promise<unknown>;
+    };
+}
+/**
+ * A document as something that pushes, for `fromObservable`.
+ *
+ * This is the shape to reach for when the same entity is shown in many places
+ * and must stay consistent: Apollo's cache is then the one source of truth,
+ * and every view of it updates from the same write at the same moment.
+ *
+ * ```ts
+ * const user = fromObservable(...apolloObservable(apollo, gql)(UserDocument, { id }));
+ * ```
+ */
+export declare function apolloObservable(client: WatchLike, parse: Parse): <T, V extends Variables>(document: GraphQLDocument<T, V>, ...rest: DocumentArguments<V>) => readonly [{
+    readonly subscribe: (observer: {
+        next?: (value: T) => void;
+        error?: (error: unknown) => void;
+    }) => {
+        unsubscribe: () => void;
+    };
+}, {
+    readonly reload: () => Promise<unknown>;
+}];
+//# 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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAE3B,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACvE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,IAInD,CAAC,EAAE,CAAC,SAAS,SAAS,EAAE,UAAU,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,iBAAiB,CAAC,CAAC,CAAC,MACrF,iBAAiB,WAAW,KAAG,OAAO,CAAC,CAAC,CAAC,CAoBnD;AAED,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAC5C,SAAS,CAAC,QAAQ,EAAE;YAClB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE;gBAAE,IAAI,EAAE,OAAO,CAAA;aAAE,KAAK,IAAI,CAAC;YAC1C,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;SAClC,GAAG;YAAE,WAAW,EAAE,MAAM,IAAI,CAAA;SAAE,CAAC;QAChC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;KAC7B,CAAC;CACH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,IACtD,CAAC,EAAE,CAAC,SAAS,SAAS,EAC5B,UAAU,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAC/B,GAAG,MAAM,iBAAiB,CAAC,CAAC,CAAC;mCAKH;QAAE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE;qBAxBtE,MAAM,IAAI;;;;GAiChC"}

package/dist/index.js

@@ -0,0 +1 @@
+import{resolveTags as c}from"@firsthandjs/data";function k(n,a){return(e,...s)=>async({tags:o,force:r})=>{let t=s[0]??{},i=e.kind==="mutation"?e.invalidates:e.tags;o(...c(i,t));let u=a(e.source);return e.kind==="mutation"?(await n.mutate({mutation:u,variables:t})).data:(await n.query({query:u,variables:t,fetchPolicy:r?"network-only":"cache-first"})).data}}function m(n,a){return(e,...s)=>{let o=n.watchQuery({query:a(e.source),variables:s[0]??{}});return[{subscribe:r=>o.subscribe({next:t=>r.next?.(t.data),...r.error===void 0?{}:{error:r.error}})},{reload:()=>o.refetch()}]}}export{k as apolloLoader,m as apolloObservable};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@firsthandjs/data-apollo",
+  "version": "0.5.0",
+  "description": "Loaders for Apollo Client, 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-apollo"
+  },
+  "bugs": {
+    "url": "https://github.com/firsthandjs/firsthand/issues"
+  },
+  "homepage": "https://github.com/firsthandjs/firsthand#readme",
+  "keywords": [
+    "firsthand",
+    "data",
+    "apollo",
+    "resources",
+    "tags"
+  ]
+}