strike-fw-data

Keyed query cache, mutations, and optional offline helpers for Strike.

Requires Node 18+. Uses strike-fw-store atoms for cache notifications. Strike hooks are optional (strike-fw peer).

store/query vs this pack

| Need | Use | |------|-----| | Promise groups + Progress UI | strike-fw-store/query (createQueryClient) | | Keyed cache, staleMs, invalidate, mutations | strike-fw-data |

You can use both. This pack does not replace store/query.

Install

npm install strike-fw-data [email protected]
# optional hooks:
npm install [email protected]

Queries

import {
  createDataClient,
  defineQuery,
  defineMutation,
  useQuery,
  useMutation
} from 'strike-fw-data';

const client = createDataClient();

const products = defineQuery({
  key: ['products'],
  staleMs: 30_000,
  retry: 2,
  retryDelay: 200,
  queryFn: async ({ signal, vars, meta }) => {
    const r = await fetch('/api/products', {
      signal,
      headers: meta && meta.headers ? meta.headers() : undefined
    });
    if (!r.ok) throw new Error('failed');
    return r.json();
  }
});

await client.fetchQuery(products, { tag: 'wood' });
await client.invalidate(['products']);
client.removeQueries(['products']); // drop matching entries
client.clear(); // wipe cache + abort inflight

Pass the client into hooks (no Provider):

const q = useQuery(client, products, { tag: 'wood' });

Default staleMs is 0 (always stale). Fresh entries skip the network until force or invalidate. Default retry is 0.

useQuery remembers the def for its key so invalidate can refetch after hydrate while the hook is mounted. Advanced: client.remember(def, vars).

Mutations

Mutations do not auto-invalidate. Wire it yourself:

const checkout = defineMutation({
  key: 'checkout',
  mutationFn: async (body, { signal }) => { /* fetch */ }
});

await client.mutate(checkout, body, {
  onSuccess: () => client.invalidate(['products'])
});

const m = useMutation(client, checkout);
await m.mutate(body);
m.cancel(); // abort in-flight mutate

Optimistic updates are DIY: client.setQueryData(key, next) before mutate and roll back in onError if needed.

Auth headers (composition)

// optional peer strike-fw-auth -- app wires headers
client.setDefaultMeta({
  headers: () => auth.getHeaders()
});

Persist subpath

Not store persist(atom).

• dehydrate / hydrate -- cache snapshot for tests or SSR bootstrap
• createMutationQueue -- offline outbox (MutationDef.key required as defKey)

import { dehydrate, hydrate, createMutationQueue } from 'strike-fw-data/persist';

const snap = dehydrate(client);
hydrate(otherClient, snap);

Hydrate restores data only (not queryFn). After a useQuery mounts (or you call remember), invalidate can refetch active keys.

store persist = sync an atom to Web Storage. data ./persist = cache snapshot + mutation outbox.

Tutorials

• docs/index.md
• docs/client.md
• docs/queries.md
• docs/hooks.md
• docs/mutations.md
• docs/meta.md
• docs/persist.md

License

MIT