@firsthandjs/data-apollo 0.5.0 → 0.6.0

package/README.md

@@ -1,34 +1,50 @@
 # @firsthandjs/data-apollo
 
-Apollo Client documents as loaders for [`@firsthandjs/data`](https://www.npmjs.com/package/@firsthandjs/data).
+Apollo Client as a client 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 —
+0.61 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 { createApolloClient } from '@firsthandjs/data-apollo';
+import { useAction, useResource } from '@firsthandjs/data';
 import InvoicesDocument from './invoices.gql';
 
-const billing = apolloLoader(apollo, gql);
+export const billing = createApolloClient(apollo, gql, {
+  // 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 ?? []} />;
 }
 ```
 
-`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.
+`createApolloClient(client, parse, options?)` 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 client
+
+```ts
+billing.query(Document, variables); // a loader; declares @tag
+billing.mutate(Document, variables); // a loader; declares @invalidates
+billing.watch(Document, variables); // what `fromObservable` takes
+billing.with({ options: { errorPolicy: 'all' } }); // a variation
+```
+
+An operation with required variables cannot be called without them: the
+generated types travel with the document.
 
 ## The decision this package leaves to you: the cache
 
@@ -39,12 +55,12 @@ 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:
+- **Apollo as the store.** Use `watch` 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 }));
+  const user = fromObservable(...billing.watch(UserDocument, { id: props.id }));
   ```
 
 What is not on the list is both at once, with the same data living in two
@@ -55,14 +71,12 @@ places under two invalidation rules. See
 
 `@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:
+declares its `@tag` directives before the request goes out; a mutation declares
+its `@invalidates` — and inside an action the request's tags _are_ the store's
+invalidation, so nothing at the call site wires them:
 
 ```tsx
-const pay = useAction((id: string, { signal, invalidates }) =>
-  billing(PayDocument, { id })({ signal, force: true, tags: invalidates }),
-);
+const pay = useAction((id: string, { request }) => billing.mutate(PayDocument, { id })(request));
 ```
 
-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#apollo).

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Apollo Client, as loaders for `@firsthandjs/data`.
+ * Apollo Client, as a client 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
@@ -12,17 +12,32 @@
  *   - **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.
+ *   - **Apollo as the store.** Use `watch` 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).
  *
+ * ```ts
+ * import { gql } from '@apollo/client';
+ * import { createApolloClient } from '@firsthandjs/data-apollo';
+ *
+ * export const billing = createApolloClient(apollo, gql, {
+ *   // 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(({ request }) =>
+ *   billing.query(InvoicesDocument, { month: month.value })(request),
+ * );
+ * ```
+ *
  * 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';
+import { type BridgeOptions, type CacheClient, type CacheOptions, type DocumentArguments, type GraphQLDocument, type Loader, type ObservableLike, 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<{
@@ -32,31 +47,6 @@ export interface ApolloLike {
         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>): {
@@ -72,24 +62,55 @@ export interface WatchLike {
     };
 }
 /**
- * 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.
+ * How to turn a document's source into whatever Apollo wants.
  *
- * ```ts
- * const user = fromObservable(...apolloObservable(apollo, gql)(UserDocument, { id }));
- * ```
+ * 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 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>;
-}];
+export type Parse = (source: string) => unknown;
+export interface ApolloClientOptions {
+    /**
+     * Headers for every request, sent through Apollo's per-operation context. 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 Apollo: `false` (the default, because Apollo has one
+     * of its own and two caches over the same data disagree), options for a
+     * cache of this client's own, or a `CacheClient` shared with the rest of the
+     * application. Queries only.
+     */
+    readonly cache?: false | CacheOptions | CacheClient;
+    /** Merged into the options of every query and mutation. */
+    readonly options?: Record<string, unknown>;
+}
+export interface ApolloClient {
+    /**
+     * A query, as a loader. Declares the document's `@tag` directives before the
+     * request goes out; `force` becomes `fetchPolicy: 'network-only'`, which is
+     * what makes an invalidation reach past Apollo's cache.
+     */
+    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 watched query, for `fromObservable`: Apollo's cache as the one source of
+     * truth, so every view of an entity updates from the same write.
+     *
+     * ```ts
+     * const user = fromObservable(...billing.watch(UserDocument, { id }));
+     * ```
+     */
+    watch<T, V extends Variables>(document: GraphQLDocument<T, V>, ...rest: DocumentArguments<V>): readonly [ObservableLike<T>, BridgeOptions];
+    /** A copy with some options replaced. The cache is shared unless replaced. */
+    with(options: ApolloClientOptions): ApolloClient;
+    readonly cache: CacheClient | undefined;
+}
+export declare function createApolloClient(client: ApolloLike & WatchLike, parse: Parse, options?: ApolloClientOptions): ApolloClient;
 //# 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;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1 +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};
+import{createCacheClient as y,resolveTags as T}from"@firsthandjs/data";import{untrack as V}from"@firsthandjs/core";function b(s,i,t={}){let c=t.cache===void 0||t.cache===!1?void 0:"read"in t.cache?t.cache:y(t.cache),u=()=>{let e=typeof t.headers=="function"?V(t.headers):t.headers;return e===void 0?{}:{context:{headers:e}}},d=async(e,n,o,r)=>{let a=i(n.source);return e==="mutation"?(await s.mutate({...t.options,...u(),mutation:a,variables:o})).data:(await s.query({...t.options,...u(),query:a,variables:o,fetchPolicy:r.force?"network-only":"cache-first"})).data},m=(e,n,o)=>async r=>{let a=o[0]??{};r.tags?.(...T(e==="mutation"?n.invalidates:n.tags,a));let l=n;if(c===void 0||e==="mutation")return await d(e,l,a,r);let p=`${n.operation}(${JSON.stringify(a)})`;return await c.read(p,h=>d(e,l,a,h))(r)};return{cache:c,query:(e,...n)=>m("query",e,n),mutate:(e,...n)=>m("mutation",e,n),watch:(e,...n)=>{let o=s.watchQuery({...t.options,...u(),query:i(e.source),variables:n[0]??{}});return[{subscribe:r=>o.subscribe({next:a=>r.next?.(a.data),...r.error===void 0?{}:{error:r.error}})},{reload:()=>o.refetch()}]},with:e=>b(s,i,{...t,...e,cache:e.cache??c??!1})}}export{b as createApolloClient};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firsthandjs/data-apollo",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Loaders for Apollo Client, 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.0"
   },
   "engines": {
     "node": ">=20.11.0"