# @solid-primitives/async
[](https://bundlephobia.com/package/@solid-primitives/async)
[](https://www.npmjs.com/package/@solid-primitives/async)
[](https://github.com/solidjs-community/solid-primitives#contribution-process)
A collection of primitives for handling asynchronous data as reactive memos — streaming responses, cancellable fetches, retrying, and aggregating incremental results:
- [`fromStream`](#fromstream) - wraps a fetch request to support web streams in memos or optimistic signals
- [`fromJSONStream`](#fromjsonstream) - wraps a fetch request returning a web stream containing (incomplete) JSON for the use in memos or optimistic signals
- [`makeAbortable`](#makeabortable) - sets up an AbortSignal with auto-abort on re-fetch or timeout
- [`createAbortable`](#createabortable) - like `makeAbortable`, but with automatic abort on cleanup
- [`makeRetrying`](#makeretrying) - wraps the fetcher to retry requests after a delay
- [`createAggregated`](#createaggregated) - aggregates the values of an accessor
## Installation
```bash
npm install @solid-primitives/async
# or
yarn add @solid-primitives/async
# or
pnpm add @solid-primitives/async
```
## `fromStream`
Turns a function returning a [Web Stream API `ReadableStream`](https://streams.spec.whatwg.org/#rs-class) (optionally wrapped in a `Promise`), or a streaming `Response`, into an async generator that buffers the stream and yields the accumulated text after every chunk. Node's `stream/web` `ReadableStream` is also accepted — useful during streaming SSR, since a plain (non-streaming) SSR pass only ever reads the final value anyway.
```tsx repl
import { render } from "@solidjs/web";
import { createMemo, createSignal, Loading } from "solid-js";
import { fromStream } from "@solid-primitives/async";
// a ReadableStream that emits one word every 300ms
const wordStream = () => {
const words = "Lorem ipsum dolor sit amet, consetetur sadipscing elitr".split(" ");
return new ReadableStream({
pull: controller =>
new Promise(resolve =>
setTimeout(() => {
const word = words.shift();
if (word) controller.enqueue(word + " ");
else controller.close();
resolve();
}, 300),
),
});
};
function Demo() {
const [run, setRun] = createSignal(0);
const text = createMemo(() => {
run();
return fromStream(wordStream)();
});
return (
<>
Waiting for first chunk…}>
{text()}
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
// definition (ReadableStream includes Node's `stream/web` variant)
fromStream(
fetcher: (...args: Args) => Promise | Response | ReadableStream
): (...args: Args) => AsyncGenerator;
// on the client
const plainText = createMemo(fromStream(() => fetch(url())));
// on the server (streaming SSR only)
const readme = createMemo(fromStream(() => Readable.toWeb(createReadStream("README.md"))));
```
If the packets were very small and contained only a few words from lorem ipsum, the result would be (one line per update):
```
Lorem ipsum
Lorem ipsum dolor sit amet,
Lorem ipsum dolor sit amet, consetetur sadipscing
```
and so on. Usual HTTP packets can transmit ~1.4kb including headers, so expect multiple updates for larger data.
## `fromJSONStream`
The same as `fromStream`, but it auto-closes a partial JSON string on every chunk so it parses successfully even mid-object, instead of buffering plain text.
```tsx repl
import { render } from "@solidjs/web";
import { createMemo, createSignal, For, Loading } from "solid-js";
import { fromJSONStream } from "@solid-primitives/async";
const names = ["fromStream", "fromJSONStream", "makeAbortable", "makeRetrying"];
const json = JSON.stringify(names.map(name => ({ name, package: "@solid-primitives/async" })));
// a ReadableStream that emits the JSON text in 8-character chunks
const chunkedStream = () => {
let pos = 0;
return new ReadableStream({
pull: controller =>
new Promise(resolve =>
setTimeout(() => {
if (pos < json.length) controller.enqueue(json.slice(pos, (pos += 8)));
else controller.close();
resolve();
}, 100),
),
});
};
function Demo() {
const [run, setRun] = createSignal(0);
const items = createMemo(() => {
run();
return fromJSONStream(chunkedStream)();
});
return (
<>
Waiting for parsable JSON…}>
{item => (
{item.name} {item.package}
)}
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
// definition (ReadableStream includes Node's `stream/web` variant)
fromJSONStream(
fetcher: (...args: Args) => Promise | Response | ReadableStream
): (...args: Args) => AsyncGenerator;
// usage — cast the result to the shape you expect, since the parsed JSON is untyped
const answer = createMemo(fromJSONStream(() => fetch(url()))) as Accessor;
```
The result looks like this:
```js
// current data
// parsed JSON
'[{"id":8429,"name":"fromStrea'
[{ id: 8429, name: "fromStrea" }]
'[{"id":8429,"name":"fromStream","description":"tu'
[{ id: 8429, name: "fromStream", description: "tu" }]
'[{"id":8429,"name":"fromStream","description":"turns web streams into'
[{ id: 8429, name: "fromStream", description: "turns web streams into" }]
'[{"id":8429,"name":"fromStream","description":"turns web streams into async iterator"},{"id":294'
[{ id: 8429, name: "fromStream", description: "turns web streams into async iterator" }, { id: 294 }]
'[{"id":8429,"name":"fromStream","description":"turns web streams into async iterator"},{"id":2947,"name":"fromJSONStream",'
[{ id: 8429, name: "fromStream", description: "turns web streams into async iterator" }, { id: 2947, name: "fromJSONStream }]
// and so on
```
## `makeAbortable`
Orchestrates `AbortController` creation and aborting of abortable fetchers, either on refetch, after a timeout, or when a parent signal aborts — depending on configuration:
```ts
// definition
function makeAbortable(options?: {
autoAbort?: boolean; // default true
timeout?: number;
chainTo?: () => AbortSignal;
}): [
signal: () => AbortSignal,
abort: (reason?: string) => void,
filterAbortError: (err: any) => void,
];
// usage
const [signal, abort, filterAbortError] = makeAbortable();
const data = createMemo(
fromStream(() => fetch(url(), { signal: signal() }).catch(filterAbortError)),
);
// use `createAbortable` if you do not want manual cleanup:
onCleanup(abort);
```
- `signal()` always returns a _fresh_, not-yet-aborted `AbortSignal`; unless `options.autoAbort` is set to `false`, calling it also aborts the previously returned signal, if any
- `abort(reason?)` aborts the current signal, regardless of `autoAbort`
- if `timeout` is set, the signal aborts itself automatically after that many milliseconds
- if `chainTo` is set to another `makeAbortable`/`createAbortable` signal accessor, this signal aborts whenever that parent signal does (for any reason — manual `abort()`, `timeout`, or an `autoAbort`'d retry) — handy for cascading an abort down a chain of dependent requests
- `filterAbortError(err)` returns `undefined` for errors whose `.name` is `"AbortError"` (what `fetch` rejects with when its signal aborts) and re-throws everything else, so you can `.catch(filterAbortError)` without swallowing real failures
```tsx repl
import { render } from "@solidjs/web";
import { createMemo, createSignal, isPending, Loading, onCleanup } from "solid-js";
import { makeAbortable } from "@solid-primitives/async";
const fruits = ["apple", "apricot", "banana", "blueberry", "cherry", "grape", "mango", "melon"];
// a slow, abortable fake search request
const search = (query: string, signal: AbortSignal) =>
new Promise((resolve, reject) => {
const timer = setTimeout(() => resolve(fruits.filter(f => f.includes(query))), 800);
signal.addEventListener("abort", () => {
clearTimeout(timer);
reject(new DOMException("aborted", "AbortError"));
});
});
function Demo() {
const [query, setQuery] = createSignal("");
const [signal, abort, filterAbortError] = makeAbortable();
onCleanup(abort);
// every keystroke aborts the previous, still pending request
const results = createMemo(() => search(query(), signal()).catch(filterAbortError));
return (
<>
setQuery(e.currentTarget.value)} placeholder="Search…" />
Searching…}>
>
);
}
render(() => , document.getElementById("app")!);
```
## `createAbortable`
Takes the same options and returns the same tuple as `makeAbortable`, but also aborts the current signal automatically `onCleanup` — so it must be called within a reactive (owned) scope.
```tsx repl
import { render } from "@solidjs/web";
import { createMemo, createSignal, Loading } from "solid-js";
import { createAbortable } from "@solid-primitives/async";
// a fake request that takes `ms` milliseconds unless aborted
const request = (ms: number, signal: AbortSignal) =>
new Promise((resolve, reject) => {
const timer = setTimeout(() => resolve(`done after ${ms}ms`), ms);
signal.addEventListener("abort", () => {
clearTimeout(timer);
reject(new DOMException("aborted", "AbortError"));
});
});
function Demo() {
const [req, setReq] = createSignal({ ms: 500 });
// aborts after 1s, and automatically when Demo is disposed
const [signal, , filterAbortError] = createAbortable({ timeout: 1000 });
const result = createMemo(() => request(req().ms, signal()).catch(filterAbortError));
return (
<>
Requesting…}>
{result() ?? "aborted by 1s timeout"}
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
const [signal, abort, filterAbortError] = createAbortable();
const data = createMemo(
fromStream(() => fetch(url(), { signal: signal() }).catch(filterAbortError)),
);
// no need to call onCleanup(abort) yourself — it happens when the owning scope disposes
```
## `makeRetrying`
Wraps a fetcher and can catch errors and retry after a delay:
```ts
// definition
const fetcher: () => AsyncGenerator = makeRetrying(
() => fetch(url()).then(r => r.body),
{
delay: 1000, // number of Milliseconds to wait before retrying; default is 5s
retries: 1, // number of times the request should be retried before throwing the last error; default is 3 times
},
);
```
If you want to retry for an infinite number of times, you can set `options.retries` to `Infinity`.
```tsx repl
import { render } from "@solidjs/web";
import { createMemo, createSignal, isPending, Loading } from "solid-js";
import { makeRetrying } from "@solid-primitives/async";
function Demo() {
const [run, setRun] = createSignal(0);
const result = createMemo(() => {
run();
let attempts = 0;
// fails twice, then succeeds — retried every 500ms
const flaky = () =>
++attempts < 3
? Promise.reject(new Error("flaky"))
: Promise.resolve(`succeeded on attempt ${attempts}`);
return makeRetrying(flaky, { delay: 500 })();
});
return (
<>
Retrying…}>
>
);
}
render(() => , document.getElementById("app")!);
```
## `createAggregated`
Aggregates every value emitted by an accessor into a growing memo, instead of replacing the previous value with each update:
```tsx repl
import { render } from "@solidjs/web";
import { createSignal, For } from "solid-js";
import { createAggregated } from "@solid-primitives/async";
function Demo() {
const [page, setPage] = createSignal(1);
// every new page number is appended instead of replacing the previous one
const pages = createAggregated(page, [] as number[]);
return (
<>
{p =>
Page {p}
}
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
// definition
function createAggregated(
accessor: Accessor,
initialValue?: I,
memoOptions?: MemoOptions, // forwarded to the underlying createMemo
): Accessor;
// usage
const pages = createAggregated(currentPage, []);
```
- if the aggregate so far is an Array, incoming values are appended to it
- if the aggregate so far is an Object, the incoming value is shallow-merged into it
- if the aggregate so far is a string, incoming string data is concatenated onto it
- otherwise the aggregate becomes an Array containing the previous and incoming values
- `null`/`undefined` values from the accessor are ignored and never overwrite an existing aggregate — so a still-pending accessor won't reset an already-started aggregation
- objects and arrays are re-created (shallow-copied) on every update, but the individual values are left untouched, so `` works as expected