@marianmeres/fetch-store 3.1.0 → 3.2.0

package/AGENTS.md

@@ -0,0 +1,79 @@
+# @marianmeres/fetch-store — Agent Guide
+
+> Reactive store for async fetch operations. Tracks loading/error/success state, supports caching, polling, abort, deduplication, and streaming (SSE/WebSocket). Svelte-compatible but framework-agnostic.
+
+## Quick Reference
+
+- **Stack**: TypeScript (erasable-only), Node LTS (`.node-version`), pnpm, `node:test`, Biome
+- **Runtime**: universal — web standards only (browser, Node, any ES2022 runtime); developed
+  and tested on Node LTS
+- **Install**: `pnpm install` | **Test**: `pnpm test` | **Check all**: `pnpm run ci` |
+  **Build**: `pnpm run build` | **Release**: `pnpm run rp` (patch) / `pnpm run rpm` (minor),
+  human only
+- **Registries**: npm (built `dist/`, from `package.json`) and JSR (the `.ts` source, from
+  `jsr.json`). `package.json` holds the version; `jsr.json` has none.
+- **Dependencies**: [@marianmeres/store](https://www.npmjs.com/package/@marianmeres/store)
+  (which brings [@marianmeres/pubsub](https://www.npmjs.com/package/@marianmeres/pubsub)):
+  an npm dependency in `package.json` and a `jsr:` import in `jsr.json`; keep both ranges
+  in step
+
+## Project Structure
+
+```
+src/
+├── mod.ts                  — Export barrel (types + both stores)
+├── types.ts                — All public type definitions
+├── fetch-store.ts          — createFetchStore (request-style: fetch, fetchOnce, polling)
+└── fetch-stream-store.ts   — createFetchStreamStore (push-style: SSE/WebSocket)
+tests/
+├── fetch-store.test.ts     — Combined node:test suite for both stores
+└── consumer/               — A downstream project's type check of the built package
+dist/                       — `pnpm run build` output; gitignored; the only code npm gets
+package.json                — Manifest of record: version, exports, scripts
+tsconfig.json               — Typecheck view (src + tests, noEmit)
+tsconfig.build.json         — Build: src -> dist (ESM + .d.ts)
+jsr.json                    — JSR config: exports, store import, publish set (no version)
+biome.json                  — Format + lint
+```
+
+## Critical Conventions
+
+1. **Two stores, separate files** — `createFetchStore` (request/response) and `createFetchStreamStore` (push-based events). Do not merge; they have distinct lifecycles.
+2. **Types live in `types.ts`** — Both stores re-export their public types from this single file. When adding a type, add it there and re-export in the implementation file for BC.
+3. **Generation token pattern** — `fetch-store.ts` uses `_generation` to invalidate late-resolving fetches after `reset()`. Any new async path that writes to stores must honor it.
+4. **Silent ≠ invisible** — `fetchSilent` skips `isFetching` but still updates `lastFetchStart`, `lastFetchEnd`, `successCounter`, so `fetchOnce`-style caching works.
+5. **Two separate inflight promises** — `_inflightPromise` and `_inflightSilentPromise` are tracked independently; `fetchOnce` joins whichever is active.
+6. **Tabs, 4-wide, 90-col** — See [biome.json](./biome.json). `pnpm run format` before
+   committing; `pnpm run lint` is the read-only check CI runs. No lint warnings: a
+   deliberate exception carries a `biome-ignore` with its reason.
+7. **Published types must stand alone** — `pnpm run typecheck:consumer` builds `dist/` and
+   type-checks [tests/consumer/index.ts](./tests/consumer/index.ts) against it by package
+   name, with a plain `lib`, no `@types/node` and `skipLibCheck: false`. Our own typecheck
+   loads `@types/node`, which hides missing lib types (e.g. `Symbol.dispose`, needed by
+   store's `Unsubscribe` and declared via `/// <reference lib>` in `src/types.ts`).
+8. **Never throw from worker cleanup** — stream worker's returned cancel function is wrapped in try/catch.
+9. **Runtime policy** — Node at the keyboard, npm as the registry. No `Deno.*`, `Bun.*`,
+   `jsr:` or `npm:` specifiers; erasable-only TS (`import type`, `.ts` import extensions,
+   no `enum` / `namespace` / parameter properties). Node never checks types:
+   `pnpm run typecheck` is the only type gate. Deno exists only for JSR: `test:deno` runs
+   the same suite against the JSR dependency graph, and `publish:jsr` runs it first.
+   Nothing is built or tested for Bun.
+
+## Before Making Changes
+
+- [ ] Read [docs/architecture.md](./docs/architecture.md) to understand the state-machine semantics
+- [ ] Check [docs/conventions.md](./docs/conventions.md) for meta-update patterns
+- [ ] Touching the public API or publish shape: also `pnpm run test:deno` and
+      `pnpm run jsr:check`
+- [ ] Run `pnpm run ci` (typecheck + lint + tests + consumer typecheck) — the suite covers every known edge case including late-resolve/generation bugs
+- [ ] Update [CHANGELOG.md](./CHANGELOG.md) for any behavior change
+
+## Documentation Index
+
+- [Architecture](./docs/architecture.md) — State model, data flow, generation token
+- [Conventions](./docs/conventions.md) — Code style, meta update rules, testing patterns
+- [Tasks](./docs/tasks.md) — Add a method, fix a meta bug, release
+- Domains:
+  - [FetchStore](./docs/domains/fetch-store.md) — request-style store
+  - [FetchStreamStore](./docs/domains/fetch-stream-store.md) — push-style store
+- Human docs: [README.md](./README.md), [API.md](./API.md), [CHANGELOG.md](./CHANGELOG.md)

package/API.md

@@ -0,0 +1,243 @@
+# API
+
+## Functions
+
+### `createFetchStore(fetchWorker, initial?, options?)`
+
+Creates a reactive store for async fetch operations.
+
+**Type signature:**
+
+```typescript
+createFetchStore<T, A extends unknown[] = unknown[]>(
+    fetchWorker: (...args: A) => Promise<T>,
+    initial?: T | null,
+    options?: Partial<FetchStoreOptions<T>>
+): FetchStore<T, A>
+```
+
+**Parameters:**
+
+- `fetchWorker` (`(...args: A) => Promise<T>`) — Async function performing the fetch. When `abortable: true`, receives `AbortSignal` as the last argument.
+- `initial` (`T | null`, optional) — Initial data value. Default: `null`.
+- `options` (`Partial<FetchStoreOptions<T>>`, optional) — See [FetchStoreOptions](#fetchstoreoptions).
+
+**Returns:** [`FetchStore<T, A>`](#fetchstore)
+
+**Example:**
+
+```typescript
+const userStore = createFetchStore(
+    async (id: string) => (await fetch(`/api/users/${id}`)).json() as Promise<User>,
+    null,
+    { fetchOnceDefaultThresholdMs: 60_000 }
+);
+
+await userStore.fetch("123");
+const { data } = userStore.get();
+```
+
+---
+
+### `createFetchStreamStore(fetchStreamWorker, initial?, options?)`
+
+Creates a reactive store for streaming data sources (SSE, WebSocket, push-based).
+
+**Type signature:**
+
+```typescript
+createFetchStreamStore<T, A extends unknown[] = unknown[]>(
+    fetchStreamWorker: (
+        emit: FetchStreamEventEmitFn<T>,
+        ...args: A
+    ) => (() => void) | void,
+    initial?: T | null,
+    options?: Partial<FetchStreamStoreOptions<T>>
+): FetchStreamStore<T, A>
+```
+
+**Parameters:**
+
+- `fetchStreamWorker` — Worker function. Receives an `emit` callback as first arg and user args after. May return a cleanup function.
+- `initial` (`T | null`, optional) — Initial data value. Default: `null`.
+- `options` (`Partial<FetchStreamStoreOptions<T>>`, optional) — See [FetchStreamStoreOptions](#fetchstreamstoreoptions).
+
+**Returns:** [`FetchStreamStore<T, A>`](#fetchstreamstore)
+
+**Example:**
+
+```typescript
+const store = createFetchStreamStore<Message>((emit, url: string) => {
+    const es = new EventSource(url);
+    es.onmessage = (e) => emit("data", JSON.parse(e.data));
+    es.onerror = (e) => emit("error", e);
+    return () => es.close();
+});
+
+const stop = store.fetchStream(["/api/events"]);
+```
+
+---
+
+## Interfaces
+
+### `FetchStore`
+
+Returned by `createFetchStore`.
+
+| Method                 | Signature                                                                                                 | Description                                                                                                                                                                                                                      |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subscribe`            | `(fn: (value: FetchStoreValue<T>) => void) => () => void`                                                 | Svelte-compatible subscription. Fires immediately with the current value, then on every change. Returns an unsubscribe function.                                                                                                 |
+| `get`                  | `() => FetchStoreValue<T>`                                                                                | Synchronous snapshot of current value.                                                                                                                                                                                           |
+| `fetch`                | `(...args: A) => Promise<T \| null>`                                                                      | Run the worker. Sets `isFetching: true`. Returns data or `null` on error/abort.                                                                                                                                                  |
+| `fetchSilent`          | `(...args: A) => Promise<T \| null>`                                                                      | Like `fetch` but never sets `isFetching`. Still advances `successCounter`, timestamps.                                                                                                                                           |
+| `fetchOnce`            | `(args?: A \| unknown, thresholdMs?: number) => Promise<T \| null>`                                       | Fetch only if no successful fetch yet **or** last fetch older than `thresholdMs`. Joins any in-flight request.                                                                                                                   |
+| `fetchOnceSilent`      | `(args?: A \| unknown, thresholdMs?: number) => Promise<T \| null>`                                       | Silent version of `fetchOnce`.                                                                                                                                                                                                   |
+| `fetchRecursive`       | `(args?: A \| unknown, delayMs?: number \| (() => number), options?: { silent?: boolean }) => () => void` | Polling. Each iteration waits for the previous to finish. Returns cancel fn. Default uses `fetchSilent`; set `silent: false` to flip `isFetching`. `delayMs` as function allows dynamic intervals — returning `0` stops polling. |
+| `reset`                | `() => void`                                                                                              | Clear data + meta to initial state. Aborts in-flight (when abortable). Invalidates late-resolving fetches via an internal generation token.                                                                                      |
+| `resetError`           | `() => void`                                                                                              | Clear `lastFetchError` **and** `lastFetchSilentError`. Other state untouched.                                                                                                                                                    |
+| `touch`                | `(data?: T) => void`                                                                                      | Advance `lastFetchStart`/`lastFetchEnd` to now (tricks `fetchOnce`). Optionally replaces data. Increments `successCounter`.                                                                                                      |
+| `abort`                | `() => void`                                                                                              | Abort any in-flight requests (requires `abortable: true`).                                                                                                                                                                       |
+| `fetchWorker`          | `(...args: A) => Promise<T>`                                                                              | The original worker, exposed for composition.                                                                                                                                                                                    |
+| `getInternalDataStore` | `() => StoreLike<T \| null>`                                                                              | Access the underlying data store. Bypasses `dataFactory` and meta — use with care.                                                                                                                                               |
+
+`fetchArgs` can be passed either as a tuple (`["x"]`) or as a single non-array value (`"x"`); the store normalizes it.
+
+---
+
+### `FetchStreamStore`
+
+Returned by `createFetchStreamStore`.
+
+| Method                 | Signature                                                                          | Description                                                                                                                                                                                                                                                                                                                  |
+| ---------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subscribe`            | `(fn: (value: FetchStreamStoreValue<T>) => void) => () => void`                    | Svelte-compatible subscription.                                                                                                                                                                                                                                                                                              |
+| `get`                  | `() => FetchStreamStoreValue<T>`                                                   | Synchronous snapshot.                                                                                                                                                                                                                                                                                                        |
+| `fetchStream`          | `(args?: A \| unknown, recursiveDelayMs?: number \| (() => number)) => () => void` | Start the stream. Returns cancel fn, which calls the worker's cleanup and closes the run (`isFetching: false`, `lastFetchEnd`) if it was still active. If `recursiveDelayMs > 0`, the worker is restarted `recursiveDelayMs` after every `emit("end")`. Starting a new stream while one is running cancels the previous one. |
+| `reset`                | `() => void`                                                                       | Stop the running stream (calls its cleanup), clear data + meta.                                                                                                                                                                                                                                                              |
+| `resetError`           | `() => void`                                                                       | Clear `lastFetchError` only.                                                                                                                                                                                                                                                                                                 |
+| `fetchStreamWorker`    | raw worker                                                                         | Original worker, exposed for composition.                                                                                                                                                                                                                                                                                    |
+| `getInternalDataStore` | `() => StoreLike<T \| null>`                                                       | Underlying data store.                                                                                                                                                                                                                                                                                                       |
+
+---
+
+## Types
+
+### `FetchStoreValue<T>`
+
+The value returned by `get()` and passed to subscribers.
+
+```typescript
+interface FetchStoreValue<T> {
+    data: T | null;
+    isFetching: boolean;
+    lastFetchStart: Date | null;
+    lastFetchEnd: Date | null;
+    lastFetchError: Error | null;
+    lastFetchSilentError: Error | null;
+    successCounter: number;
+}
+```
+
+| Field                             | Description                                                                                  |
+| --------------------------------- | -------------------------------------------------------------------------------------------- |
+| `data`                            | Fetched data; `null` before first successful fetch or after `reset()`.                       |
+| `isFetching`                      | `true` during a `fetch()` call. Silent fetches do not flip this.                             |
+| `lastFetchStart` / `lastFetchEnd` | Timestamps of the most recent fetch (silent or not).                                         |
+| `lastFetchError`                  | Error from the last non-silent fetch. Cleared at the start of the next non-silent `fetch()`. |
+| `lastFetchSilentError`            | Error from the last silent fetch. Cleared on next silent success.                            |
+| `successCounter`                  | Incremented on every successful fetch, silent or not (and by `touch()`).                     |
+
+### `FetchStreamStoreValue<T>`
+
+```typescript
+interface FetchStreamStoreValue<T> {
+    data: T | null;
+    isFetching: boolean;
+    lastFetchStart: Date | null;
+    lastFetchEnd: Date | null;
+    lastFetchError: Error | null;
+}
+```
+
+Set to `isFetching: true` when `fetchStream()` starts; flipped back to `false` on `emit("end")` or when the returned cancel fn is called.
+
+### `FetchStoreOptions`
+
+```typescript
+interface FetchStoreOptions<T> extends CreateStoreOptions<T> {
+    fetchOnceDefaultThresholdMs: number;
+    onReset: () => void;
+    dedupeInflight: boolean;
+    abortable: boolean;
+    dataFactory: DataFactory<T>;
+}
+```
+
+| Option                        | Default           | Description                                                                                                        |
+| ----------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `fetchOnceDefaultThresholdMs` | `300_000` (5 min) | TTL for `fetchOnce` / `fetchOnceSilent`. Use `0` at call site to skip threshold and rely only on `successCounter`. |
+| `dedupeInflight`              | `false`           | Concurrent `fetch()` (or `fetchSilent()`) calls return the same promise.                                           |
+| `abortable`                   | `false`           | Worker receives `AbortSignal` as last arg. A new `fetch()` aborts the previous in-flight one.                      |
+| `dataFactory`                 | —                 | `(data, old?) => T` — transform/merge each incoming payload.                                                       |
+| `onReset`                     | —                 | Called after `reset()` wipes state.                                                                                |
+
+### `FetchStreamStoreOptions`
+
+```typescript
+interface FetchStreamStoreOptions<T> extends CreateStoreOptions<T> {
+    onReset: () => void;
+    dataFactory: DataFactory<T>;
+}
+```
+
+### `DataFactory<T>`
+
+```typescript
+type DataFactory<T> = (data: T, old?: T) => T;
+```
+
+Applied to every data write. Use for merge strategies (shallow merge, deep merge, array append, etc.).
+
+### `FetchStreamEventName`
+
+```typescript
+type FetchStreamEventName = "data" | "error" | "end";
+```
+
+### `FetchStreamEventEmitFn<T>`
+
+```typescript
+type FetchStreamEventEmitFn<T = unknown> = (
+    eventName: FetchStreamEventName,
+    eventData?: T | Error
+) => void;
+```
+
+Passed to the stream worker as its first argument. Semantics:
+
+- `emit("data", value)` — writes data; clears any prior `lastFetchError`.
+- `emit("error", err)` — sets `lastFetchError`; does not touch data.
+- `emit("end")` — sets `isFetching: false`, `lastFetchEnd`; **does not** clear errors.
+
+Emits after `cancel()` / `reset()` are silently ignored, including any emit from the worker's cleanup function. The worker does not need to emit `"end"` on cancel: `cancel()` closes the run itself.
+
+### `FetchMetaBase` / `FetchStoreMeta` / `FetchStreamStoreMeta`
+
+Base shape shared by both stores; the concrete `*StoreValue<T>` is `{ data } & *StoreMeta`.
+
+```typescript
+interface FetchMetaBase {
+    isFetching: boolean;
+    lastFetchStart: Date | null;
+    lastFetchEnd: Date | null;
+    lastFetchError: Error | null;
+}
+
+interface FetchStoreMeta extends FetchMetaBase {
+    successCounter: number;
+    lastFetchSilentError: Error | null;
+}
+
+interface FetchStreamStoreMeta extends FetchMetaBase {}
+```

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+## Unreleased
+
+### Bug fixes
+
+- **Type-checks in projects without the disposable lib.** `subscribe()` returns
+  `@marianmeres/store`'s `Unsubscribe`, which declares `[Symbol.dispose]`. A consumer
+  whose `lib` predates `esnext.disposable`, with `skipLibCheck: false` and no `@types/node`
+  (which declares `Symbol.dispose` itself), got `TS2550: Property 'dispose' does not exist
+  on type 'SymbolConstructor'` from store's declarations. `dist/types.d.ts` now carries
+  `/// <reference lib="esnext.disposable" />`, so the types bring the lib they need
+  (`using sub = store.subscribe(...)` type-checks too). Runtime is unchanged:
+  `Symbol.dispose` was already polyfilled by `@marianmeres/pubsub`. (`src/types.ts`; guarded
+  by `pnpm run typecheck:consumer`.)
+
+### Tooling
+
+- **Moved off Deno.** Node LTS is the dev runtime and the CI gate (GitHub Actions); pnpm,
+  `node:test`, Biome and `tsc` replace `deno test`, `deno fmt` / `deno lint` and the
+  `scripts/build-npm.ts` build. `package.json` is the manifest of record; `deno.json` and
+  `deno.lock` are gone. The source changes are type-level and formatting only.
+- **Still on npm and JSR.** npm gets `dist/` built by `tsc`; JSR keeps getting the `.ts`
+  source from `jsr.json`, which has no version of its own (`publish:jsr` passes
+  `--set-version` from `package.json`). `pnpm run test:deno` runs the same suite on Deno
+  against the JSR dependency graph before every JSR publish.
+- **npm package shape.** `exports` map (`types` + `default`) next to `main` / `types`;
+  `sideEffects: false`; `API.md`, `AGENTS.md` and `CHANGELOG.md` are now packed. The
+  built JavaScript is identical to 3.1.1 apart from line wrapping. The `.d.ts` files
+  re-export `./types.ts` (was `./types.js`), which TypeScript 5.9 and 7 resolve to the
+  sibling `.d.ts` under both `bundler` and `nodenext` resolution.
+- **`@marianmeres/pubsub` is no longer a direct dependency.** Nothing imports it; it still
+  arrives through `@marianmeres/store`.
+
+## 3.1.1
+
+### Bug fixes
+
+- **Stopping a running stream no longer leaves `isFetching: true`** ([#1](https://github.com/marianmeres/fetch-store/issues/1)). A 3.1.0 regression: since emits after cancel are ignored, the worker's `"end"` could never arrive once `stop()` was called, whether it came from the cleanup function (the pattern the docs showed) or asynchronously afterwards. `isFetching` stayed `true` and `lastFetchEnd` stayed `null` until the next `fetchStream()` or `reset()`. The cancel function now closes the run itself (`isFetching: false`, `lastFetchEnd: new Date()`) when it was still active; errors are preserved, as with `"end"`. Restarting a stream and `reset()` skip this write, so subscribers see no intermediate `isFetching: false`. Calling `emit("end")` from cleanup is no longer needed, but it is harmless. (`src/fetch-stream-store.ts`: internal `stop(closeRun)` behind the public cancel fn; tests `A8`.)
+
+## 3.1.0
+
+A thorough re-analysis surfaced several real bugs and design gaps. This release
+fixes all of them and tightens a few type signatures. Most fixes are behaviorally
+backward compatible; the BC-visible ones are called out under "Breaking changes"
+below.
+
+### Bug fixes
+
+- **Aborted fetch no longer leaves `isFetching: true` forever.** When a `fetch()` was aborted (manual `abort()` or `reset()`), the `AbortError` branch returned early without resetting meta. `isFetching` got stuck until another fetch started. Now the abort branch clears `isFetching` and sets `lastFetchEnd` (when we are still the current request). (`src/fetch-store.ts` — abort-branch meta update; test `A1`.)
+
+- **`fetchSilent` now advances `lastFetchStart`, `lastFetchEnd`, and `successCounter`.** Previously silent variants updated only `lastFetchSilentError`. That broke `fetchOnceSilent` as a caching primitive: both the cold-store gate (`!successCounter`) and the threshold gate (`lastFetchStart`) never advanced, so every `fetchOnceSilent` call unconditionally re-fetched. The "silent" semantic (no loading-spinner flicker) is preserved — only `isFetching` stays unchanged. (`src/fetch-store.ts` — `doFetchSilent` meta update; tests `A2-*`.)
+
+- **`FetchStreamStore.reset()` now stops the running stream.** Previously `reset()` only cleared state; the worker kept running, emitting into a freshly-reset store (zombie stream / leak). The store now tracks the current stream's cancel function and invokes it before wiping state. (`src/fetch-stream-store.ts` — `_currentCancel` tracked at closure scope; test `A3`.)
+
+- **`emit("end")` no longer wipes a preceding `emit("error")`.** The emit handler unconditionally cleared `lastFetchError` at the top, so the common `emit("error", e); emit("end")` pattern lost the error by the time subscribers saw the terminal state. Error-clearing is now scoped to `"data"` events only (data implies recovery). (`src/fetch-stream-store.ts` — error-clear moved into the data branch; test `A4`.)
+
+- **Synchronous throw in a stream worker no longer leaves `isFetching: true`.** `_metaStore.set({ isFetching: true })` ran before `try { worker(...) }`; a sync throw was caught, but `isFetching` was never reset and the returned cancel function was a no-op. The catch branch now sets `isFetching: false`, `lastFetchEnd`, and `lastFetchError`. (`src/fetch-stream-store.ts` — `catch` branch meta update; test `A5`.)
+
+- **Non-abortable in-flight fetches can no longer overwrite `reset()`.** When `abortable: false` and a fetch was mid-`await`, calling `reset()` wiped state, but the awaited response resumed and wrote stale data + meta on top. A generation token is now bumped on `reset()`; any in-flight fetch whose generation no longer matches discards its writes. (`src/fetch-store.ts` — `_generation` token; test `A6`.)
+
+- **`fetchOnce` joins in-flight requests instead of returning stale data.** When `isFetching` was `true`, both gates failed and the function returned `_dataStore.get()` immediately (usually `null` or stale). Now `fetchOnce` always awaits the current in-flight promise — regardless of the `dedupeInflight` option. (`src/fetch-store.ts` — explicit in-flight join in `_fetchOnce`; test `A7`.)
+
+- **Concurrent `fetchOnce` calls dedupe internally.** Two `fetchOnce()` calls on a cold store used to both see `successCounter: 0` and both fire. The in-flight join above covers this: the second call now joins the first's in-flight promise. (`src/fetch-store.ts`; test `C3`.)
+
+- **Stream worker emits after cancel are silently ignored.** A worker that does not honor its cleanup function synchronously could still write data/errors to the store after the user called `stop()`. The emit callback now short-circuits on the cancel flag. (`src/fetch-stream-store.ts` — `_aborted` guard inside the emit callback; test `C6`.)
+
+- **README code samples now match the 3.x signature.** The `Abortable` and `Deduplication` sections showed 4-arg calls (`createFetchStore(worker, null, null, { ... })`) left over from the 2.x → 3.x migration. Fixed to 3 args. (`README.md`.)
+
+### Design improvements
+
+- **Worker-argument types now propagate through the store.** `createFetchStore` and `createFetchStreamStore` gained a second generic `A extends unknown[]` inferred from the worker. `store.fetch(...)` / `store.fetchStream(...)` now type-check arguments against the worker's signature. Defaults preserve the old `unknown[]` behavior for untyped workers. (`src/types.ts` — `FetchStore<T, A>` and `FetchStreamStore<T, A>`.)
+
+- **`FetchStreamEventEmitFn<T>` is generic.** The public type is now parameterized over `T` with a default of `unknown`, matching the implementation. Workers typed against this interface get type safety on `emit("data", ...)` payloads. (`src/types.ts`.)
+
+- **`fetchRecursive` accepts `{ silent?: boolean }`.** New third argument lets polling flip `isFetching` each iteration when needed. Default remains `silent: true` to preserve the old behavior.
+
+- **`resetError()` clears both error fields.** Previously only cleared `lastFetchError`; now also clears `lastFetchSilentError`.
+
+- **Stream store `fetchStream()` cancels a previously running stream.** Starting a new stream while one is already active now calls the previous stream's cleanup function before the new worker runs — avoids parallel zombie streams if a consumer forgets to call the returned cancel function.
+
+### Breaking changes
+
+The changes below are technically BC-visible. None are expected to affect most real-world usage — the old behaviors were bugs — but each is documented in case you were depending on the exact old semantics.
+
+1. **`fetchSilent` now bumps `successCounter` and updates `lastFetchStart` / `lastFetchEnd`.** If you were subscribing to `successCounter` as a "visible-fetch counter", silent fetches (including those inside `fetchRecursive`) now increment it. Use a separate counter in your own code if you need the old semantics.
+
+2. **`fetchOnceSilent` now caches on its threshold.** Previously every call re-fetched (because silent didn't advance `lastFetchStart` / `successCounter`). If you were using `fetchOnceSilent` in place of `fetchSilent` and relying on the broken no-cache behavior, switch to `fetchSilent` directly or pass `thresholdMs: 0`.
+
+3. **`fetchOnce` waits for an in-flight fetch instead of returning stale data immediately.** If you were calling `fetchOnce()` during a pending `fetch()` and reading the result synchronously, you may observe a longer wait now (the correct data arrives instead of `null` / stale).
+
+4. **`emit("end")` no longer clears `lastFetchError`.** If you were relying on `end` as a "reset the error" signal, either emit a `"data"` first or call `resetError()` explicitly.
+
+5. **`FetchStreamStore.reset()` now stops the running stream.** If you were calling `reset()` purely to wipe displayed state while keeping the underlying stream alive, that no longer works. Start a fresh `fetchStream()` after `reset()`.
+
+6. **`FetchStore<T>` is now `FetchStore<T, A>` (with default).** The second generic is optional (`A extends unknown[] = unknown[]`) so existing `FetchStore<User>` annotations keep working. Code that explicitly asserted the type of `fetch` as `(...args: unknown[]) => Promise<T | null>` may now see a narrower signature.
+
+7. **`FetchStreamEventEmitFn` became `FetchStreamEventEmitFn<T>` (with default).** `type FetchStreamEventEmitFn = ...` style references still compile (default `T = unknown`).
+
+8. **`resetError()` now also clears `lastFetchSilentError`.** If you were calling `resetError()` and reading `lastFetchSilentError` afterwards, expect `null`.
+
+### Non-changes worth noting
+
+- The public `createFetchStore(worker, initial?, options?)` / `createFetchStreamStore(worker, initial?, options?)` signatures are **unchanged** from 3.0.x. No third positional argument was added or removed.
+- `getInternalDataStore()` still returns a fully writable `StoreLike<T | null>` — consumers using it as an escape hatch keep working exactly as before.
+- Svelte store contract (synchronous notify on subscribe, strict-equality short-circuit) is unchanged.
+
+---
+
+## 3.0.4
+
+- Docs updates.
+
+## 3.0.3
+
+- Deps bump.
+
+## 3.0.0
+
+Major release. See earlier README "Breaking Changes" section (now in git history) for the 2.x → 3.x migration — simplified generic types, moved `dataFactory` into `options`, and changed `DataFactory<T>` to receive strongly-typed `T` instead of `unknown`.

package/README.md

@@ -9,13 +9,16 @@ Reactive store for async fetch operations with loading/error/success state track
 ## Installation
 
 ```bash
-deno add jsr:@marianmeres/fetch-store
+npm install @marianmeres/fetch-store
 ```
 
 ```bash
-npm install @marianmeres/fetch-store
+deno add jsr:@marianmeres/fetch-store
 ```
 
+Plain ESM with type declarations, web standards only: runs in browsers, Node and any
+ES2022 runtime.
+
 ## Usage
 
 ```typescript
@@ -99,10 +102,12 @@ const feed = createFetchStreamStore<Message>((emit, url: string) => {
     const es = new EventSource(url);
     es.onmessage = (e) => emit("data", JSON.parse(e.data));
     es.onerror = (e) => emit("error", e);
-    return () => { es.close(); emit("end"); };
+    return () => es.close();
 });
 
 const stop = feed.fetchStream(["/api/events"]);
+// ...later: closes the connection, sets isFetching: false
+stop();
 ```
 
 ## Features
@@ -120,6 +125,24 @@ const stop = feed.fetchStream(["/api/events"]);
 
 See [API.md](API.md) for the complete API reference.
 
+## Development
+
+Node LTS (`.node-version`), pnpm, Biome, `node:test`. The source is erasable-only
+TypeScript that Node runs directly; `dist/` is built only for publishing to npm. JSR is
+served the `.ts` source (`jsr.json`).
+
+| Command                             | Does                                                         |
+| ----------------------------------- | ------------------------------------------------------------ |
+| `pnpm install`                      | installs the dev tooling                                     |
+| `pnpm test` / `pnpm run test:watch` | `node --test` over `tests/**/*.test.ts`                      |
+| `pnpm run test:deno`                | the same suite on Deno, as JSR consumers run it              |
+| `pnpm run typecheck`                | `tsc --noEmit` over `src` and `tests`                        |
+| `pnpm run typecheck:consumer`       | builds `dist/`, type-checks it as a downstream project would |
+| `pnpm run lint` / `pnpm run format` | `biome check .` read-only / with `--write`                   |
+| `pnpm run ci`                       | typecheck + lint + test + consumer typecheck, what CI runs   |
+| `pnpm run build`                    | `tsc -p tsconfig.build.json` → `dist/`                       |
+| `pnpm run rp` / `pnpm run rpm`      | patch / minor release, then publish to npm and JSR           |
+
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md).

package/dist/fetch-store.d.ts

@@ -1,6 +1,6 @@
-export type { DataFactory, FetchStore, FetchStoreMeta, FetchStoreOptions, FetchStoreValue, } from "./types.js";
-export { createFetchStreamStore } from "./fetch-stream-store.js";
-import type { FetchStore, FetchStoreOptions } from "./types.js";
+export { createFetchStreamStore } from "./fetch-stream-store.ts";
+export type { DataFactory, FetchStore, FetchStoreMeta, FetchStoreOptions, FetchStoreValue, } from "./types.ts";
+import type { FetchStore, FetchStoreOptions } from "./types.ts";
 /**
  * Creates a reactive store for managing async fetch operations with built-in
  * state tracking for loading, errors, and success counts.

package/dist/fetch-store.js

@@ -104,7 +104,9 @@ export const createFetchStore = (fetchWorker, initial = null, options = {}) => {
                         return null;
                     // Only clear isFetching if we're still the current request
                     // (otherwise a newer fetch owns the meta).
-                    if (!abortable || myController === _abortController || _abortController === null) {
+                    if (!abortable ||
+                        myController === _abortController ||
+                        _abortController === null) {
                         _metaStore.set({
                             ..._metaStore.get(),
                             isFetching: false,

package/dist/fetch-stream-store.d.ts

@@ -1,5 +1,5 @@
-export type { FetchStreamEventEmitFn, FetchStreamEventName, FetchStreamStore, FetchStreamStoreMeta, FetchStreamStoreOptions, FetchStreamStoreValue, } from "./types.js";
-import type { FetchStreamEventName, FetchStreamStore, FetchStreamStoreOptions } from "./types.js";
+export type { FetchStreamEventEmitFn, FetchStreamEventName, FetchStreamStore, FetchStreamStoreMeta, FetchStreamStoreOptions, FetchStreamStoreValue, } from "./types.ts";
+import type { FetchStreamEventName, FetchStreamStore, FetchStreamStoreOptions } from "./types.ts";
 /**
  * Creates a reactive store for handling streaming data sources like SSE, WebSocket,
  * or any push-based data pattern.
@@ -19,11 +19,11 @@ import type { FetchStreamEventName, FetchStreamStore, FetchStreamStoreOptions }
  *   const eventSource = new EventSource(url);
  *   eventSource.onmessage = (e) => emit("data", JSON.parse(e.data));
  *   eventSource.onerror = (e) => emit("error", e);
- *   return () => { eventSource.close(); emit("end"); };
+ *   return () => eventSource.close();
  * });
  *
  * const stop = sseStore.fetchStream(["/api/events"]);
- * // Later: stop() to close the connection
+ * // Later: stop() closes the connection and the run (isFetching: false, lastFetchEnd)
  * ```
  */
 export declare const createFetchStreamStore: <T, A extends unknown[] = unknown[]>(fetchStreamWorker: (emit: (eventName: FetchStreamEventName, eventData?: T | Error) => void, ...args: A) => (() => void) | void, initial?: T | null, options?: Partial<FetchStreamStoreOptions<T>>) => FetchStreamStore<T, A>;

package/dist/fetch-stream-store.js

@@ -19,11 +19,11 @@ const DEFAULT_OPTIONS = {};
  *   const eventSource = new EventSource(url);
  *   eventSource.onmessage = (e) => emit("data", JSON.parse(e.data));
  *   eventSource.onerror = (e) => emit("error", e);
- *   return () => { eventSource.close(); emit("end"); };
+ *   return () => eventSource.close();
  * });
  *
  * const stop = sseStore.fetchStream(["/api/events"]);
- * // Later: stop() to close the connection
+ * // Later: stop() closes the connection and the run (isFetching: false, lastFetchEnd)
  * ```
  */
 export const createFetchStreamStore = (fetchStreamWorker, initial = null, options = {}) => {
@@ -40,13 +40,17 @@ export const createFetchStreamStore = (fetchStreamWorker, initial = null, option
     const _dataStore = createStore(initial);
     const _metaStore = createStore(_createMetaObj());
     const { subscribe, get } = createDerivedStore([_dataStore, _metaStore], ([data, meta]) => ({ data, ...meta }));
-    // Tracks the cancel fn of the currently running stream so reset() can stop it.
-    let _currentCancel = null;
+    // Tracks the stop fn of the currently running stream so reset() and a new
+    // fetchStream() can stop it.
+    let _currentStop = null;
     const fetchStream = (fetchArgs = [], recursiveDelayMs = 0) => {
         let _timer;
         let _aborted = false;
         let _abortFn;
-        const cancel = () => {
+        // `closeRun` is false when the caller is about to overwrite meta anyway
+        // (reset, or a new fetchStream superseding this one), so subscribers see no
+        // intermediate `isFetching: false` flicker.
+        const stop = (closeRun) => {
             if (_aborted)
                 return;
             _aborted = true;
@@ -60,9 +64,18 @@ export const createFetchStreamStore = (fetchStreamWorker, initial = null, option
                     // cleanup should not throw, but guard anyway
                 }
             }
-            if (_currentCancel === cancel)
-                _currentCancel = null;
+            if (_currentStop === stop)
+                _currentStop = null;
+            // Every emit from here on is ignored (including an "end" from the cleanup
+            // above), so the store closes the run itself. Nothing to close when idle
+            // between recursive runs.
+            const meta = _metaStore.get();
+            if (closeRun && meta.isFetching) {
+                _metaStore.set({ ...meta, isFetching: false, lastFetchEnd: new Date() });
+            }
         };
+        // Public cancel fn takes no args (safe to pass directly as an event handler).
+        const cancel = () => stop(true);
         const normalizedArgs = (Array.isArray(fetchArgs) ? fetchArgs : [fetchArgs]);
         const runOnce = () => {
             if (_aborted)
@@ -131,19 +144,19 @@ export const createFetchStreamStore = (fetchStreamWorker, initial = null, option
                 });
             }
         };
-        // If a previous stream was still running, cancel it before starting a new one.
-        if (_currentCancel)
-            _currentCancel();
-        _currentCancel = cancel;
+        // If a previous stream was still running, stop it before starting a new one.
+        if (_currentStop)
+            _currentStop(false);
+        _currentStop = stop;
         runOnce();
         return cancel;
     };
     const reset = () => {
         // Stop any running stream (calls the worker's cleanup function).
-        if (_currentCancel) {
-            const c = _currentCancel;
-            _currentCancel = null;
-            c();
+        if (_currentStop) {
+            const s = _currentStop;
+            _currentStop = null;
+            s(false);
         }
         _dataStore.set(initial);
         _metaStore.set(_createMetaObj());

package/dist/mod.d.ts

@@ -1,3 +1,3 @@
-export * from "./types.js";
-export * from "./fetch-store.js";
-export * from "./fetch-stream-store.js";
+export * from "./fetch-store.ts";
+export * from "./fetch-stream-store.ts";
+export * from "./types.ts";

package/dist/mod.js

@@ -1,3 +1,3 @@
-export * from "./types.js";
 export * from "./fetch-store.js";
 export * from "./fetch-stream-store.js";
+export * from "./types.js";

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+/// <reference lib="esnext.disposable" preserve="true" />
 import type { CreateStoreOptions, StoreLike, StoreReadable } from "@marianmeres/store";
 /**
  * Factory function that transforms fetched data, useful for merge strategies.
@@ -171,7 +172,8 @@ export interface FetchStreamStore<T, A extends unknown[] = unknown[]> extends St
      * Starts the stream and optionally restarts it after completion.
      * @param args - Arguments passed to the stream worker
      * @param recursiveDelayMs - Delay before restarting stream after "end" event (0 = no restart)
-     * @returns Cancel function to stop the stream
+     * @returns Cancel function: calls the worker's cleanup, ignores any later emits,
+     *   and closes the run (`isFetching: false`, `lastFetchEnd`) if it was still active.
      */
     fetchStream: (args?: A | unknown, recursiveDelayMs?: number | (() => number)) => () => void;
     /**

package/dist/types.js

@@ -1 +1,6 @@
+// The stores' subscribe() returns @marianmeres/store's `Unsubscribe`, which implements
+// `[Symbol.dispose]`. That needs the disposable lib, which a consumer on an older `lib`
+// (and without @types/node) does not load; `preserve` keeps the directive in dist/types.d.ts.
+// At runtime Symbol.dispose is there: @marianmeres/pubsub, loaded by store, polyfills it.
+/// <reference lib="esnext.disposable" preserve="true" />
 export {};

package/package.json

@@ -1,20 +1,71 @@
 {
-	"name": "@marianmeres/fetch-store",
-	"version": "3.1.0",
-	"type": "module",
-	"main": "dist/mod.js",
-	"types": "dist/mod.d.ts",
-	"author": "Marian Meres",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/marianmeres/fetch-store.git"
-	},
-	"bugs": {
-		"url": "https://github.com/marianmeres/fetch-store/issues"
-	},
-	"dependencies": {
-		"@marianmeres/pubsub": "^3.0.0",
-		"@marianmeres/store": "^3.0.0"
-	}
-}
+  "name": "@marianmeres/fetch-store",
+  "version": "3.2.0",
+  "description": "Reactive store for async fetch operations with loading/error/success state tracking, caching, polling, request deduplication, abort support, and streaming (SSE, WebSocket). Svelte-compatible but framework-agnostic.",
+  "license": "MIT",
+  "author": "Marian Meres",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "main": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/mod.d.ts",
+      "default": "./dist/mod.js"
+    }
+  },
+  "files": [
+    "dist",
+    "API.md",
+    "AGENTS.md",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marianmeres/fetch-store.git"
+  },
+  "bugs": {
+    "url": "https://github.com/marianmeres/fetch-store/issues"
+  },
+  "homepage": "https://github.com/marianmeres/fetch-store#readme",
+  "keywords": [
+    "fetch",
+    "store",
+    "svelte-store",
+    "reactive",
+    "async",
+    "polling",
+    "abort",
+    "sse",
+    "websocket"
+  ],
+  "dependencies": {
+    "@marianmeres/store": "^3.0.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.6",
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "typecheck:consumer": "pnpm run build && tsc -p tests/consumer/tsconfig.json",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "node --test \"tests/**/*.test.ts\"",
+    "test:watch": "node --test --watch \"tests/**/*.test.ts\"",
+    "test:deno": "deno test --no-check --no-lock --config jsr.json tests/",
+    "jsr:check": "deno publish --dry-run --allow-dirty --no-check --set-version \"$npm_package_version\"",
+    "ci": "pnpm run typecheck && pnpm run lint && pnpm test && pnpm run typecheck:consumer",
+    "release": "npx --yes @marianmeres/release@^2.2.0",
+    "publish:jsr": "pnpm run test:deno && deno publish --no-check --set-version \"$npm_package_version\"",
+    "publish:all": "pnpm publish && pnpm run publish:jsr",
+    "rp": "pnpm run release -y && pnpm run publish:all",
+    "rpm": "pnpm run release minor -y && pnpm run publish:all"
+  }
+}