Reactive data-fetching and entity management library built on Signalium. Monorepo with the core package plus a docs site.
packages/
fetchium/ Core library (the published package)
docs/ Documentation site (Next.js + Markdoc)
Package manager: npm workspaces. Task runner: turbo.
# From repo root
npm run test # all tests via turbo
npm run build # all packages via turbo
npm run check-types # tsc --noEmit for all packages
npm run lint # eslint + prettier
# From packages/fetchium
npm test # all vitest projects (unit + react)
npm run test:unit # non-React tests only (node env, fast)
npm run test:react # browser tests (Playwright via @vitest/browser)
npm run dev:unit # watch mode for unit tests
npm run check-types # tsc --noEmitReact tests run in a real browser (Playwright/Chromium, headless). Unit tests run in Node. Both use vitest.
IS_DEV is a global boolean replaced at build time:
- In tests and dev builds:
true - In production builds:
false, allif (IS_DEV)blocks are tree-shaken
Declared in packages/fetchium/src/globals.d.ts. Do NOT import it — it's a bare global.
| Import path | Source |
|---|---|
fetchium |
src/index.ts |
fetchium/react |
src/react/index.ts |
fetchium/stores/sync |
src/stores/sync.ts |
fetchium/stores/async |
src/stores/async.ts |
| File | Purpose |
|---|---|
query.ts |
Query base class, fetchQuery(), QueryDefinition |
QueryResult.ts |
QueryInstance — manages a single query's lifecycle (relay, fetch, cache, refetch) |
QueryClient.ts |
QueryClient — central coordinator. Manages query instances, entity store, cache, context |
proxy.ts |
Entity base class, createEntityProxy() — Proxy-based entity objects with lazy parsing |
parseEntities.ts |
Entity extraction during response parsing — normalizes entities into the store |
EntityMap.ts |
PreloadedEntityRecord type, entity store data structures |
typeDefs.ts |
t type DSL (t.string, t.entity(), t.array(), etc.), ValidatorDef, reifyShape() |
types.ts |
TypeScript types: Mask enum, EntityDef, ObjectDef, QueryResult<T>, QueryPromise<T> |
mutation.ts |
Mutation base class, getMutation() |
NetworkManager.ts |
Online/offline detection via signal |
MemoryEvictionManager.ts |
Schedules query eviction after deactivation |
RefetchManager.ts |
Periodic refetch for stale queries |
Entities are normalized: each unique (typename, id, shapeKey) maps to one PreloadedEntityRecord in the entity store.
The entity proxy (createEntityProxy):
- On property access: calls
notifier.consume()(reactive tracking), activates relay if present, parses/caches the value - Handles
__entityRefhydration for nested entities loaded from cache - Wraps methods via
reactiveMethod() - Implements
CONSUME_DEEPusingsubEntityPathsfor efficient deep traversal with cycle protection
fetchQuery(QueryClass, params)→ gets/creates aQueryInstance(memoized by query key)QueryInstancecreates arelay()that manages the query subscription- On activation: loads from cache, then fetches if stale, sets up refetch intervals and stream subscriptions
- Data is parsed via
parseEntities()which normalizes entities into the store and returns proxied objects - For object-shaped responses, a persistent query proxy is created once; updates swap the underlying
_dataand fire_notifier
- Unit tests (
src/__tests__/): UsecreateMockFetch()fromutils.ts,SyncQueryStorewithMemoryPersistentStore - React tests (
src/react/__tests__/): Usevitest-browser-react,ContextProviderwithQueryClientContext - The signalium Babel preset is applied in
vitest.config.tsfor async transform support
Vite library build producing ESM + CJS, with development/production variants. signalium and its subpaths are external dependencies.
Next.js 14 static export site using Markdoc for content, Tailwind CSS 4 for styling. Has its own eslint config (next/core-web-vitals) and prettier config (with prettier-plugin-tailwindcss).
Deployed to GitHub Pages via .github/workflows/deploy.yml.