Skip to content

Commit 6ae0193

Browse files
atilafassinakodiakhq[bot]
atilafassina
and
kodiakhq[bot]
authored
Expand createAsync entry (#915)
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
1 parent 7312d59 commit 6ae0193

File tree

2 files changed

+84
-61
lines changed

2 files changed

+84
-61
lines changed

‎src/routes/reference/basic-reactivity/create-resource.mdx‎

Lines changed: 52 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -2,56 +2,6 @@
22
title: createResource
33
---
44

5-
This creates a signal that returns the result of an async request.
6-
7-
```ts
8-
import { createResource } from "solid-js"
9-
import type { ResourceReturn, ResourceOptions } from "solid-js"
10-
11-
type ResourceReturn<T> = [
12-
{
13-
(): T | undefined
14-
state: "unresolved" | "pending" | "ready" | "refreshing" | "errored"
15-
loading: boolean
16-
error: any
17-
latest: T | undefined
18-
},
19-
{
20-
mutate: (v: T | undefined) => T | undefined
21-
refetch: (info: unknown) => Promise<T> | T
22-
}
23-
]
24-
25-
type ResourceOptions<T, S = unknown> = {
26-
initialValue?: T
27-
name?: string
28-
deferStream?: boolean
29-
ssrLoadFrom?: "initial" | "server"
30-
storage?: (
31-
init: T | undefined
32-
) => [Accessor<T | undefined>, Setter<T | undefined>]
33-
onHydrated?: (k: S | undefined, info: { value: T | undefined }) => void
34-
}
35-
36-
function createResource<T, U = true>(
37-
fetcher: (
38-
k: U,
39-
info: { value: T | undefined; refetching: boolean | unknown }
40-
) => T | Promise<T>,
41-
options?: ResourceOptions<T, U>
42-
): ResourceReturn<T>
43-
44-
function createResource<T, U>(
45-
source: U | false | null | (() => U | false | null),
46-
fetcher: (
47-
k: U,
48-
info: { value: T | undefined; refetching: boolean | unknown }
49-
) => T | Promise<T>,
50-
options?: ResourceOptions<T, U>
51-
): ResourceReturn<T>
52-
53-
```
54-
555
`createResource` takes an asynchronous fetcher function and returns a signal that is updated with the resulting data when the fetcher completes.
566

577
There are two ways to use `createResource`: you can pass the fetcher function as the sole argument, or you can additionally pass a source signal as the first argument.
@@ -196,3 +146,55 @@ The `createResource` function takes an optional third argument, an options objec
196146
| onHydrated | `function` | `undefined` | A callback that is called when the resource is hydrated. |
197147
| ssrLoadFrom | `"server" \| "initial"` | `"server"` | The source of the initial value for SSR. If set to `"initial"`, the resource will use the `initialValue` option instead of the value returned by the fetcher. |
198148
| storage | `function` | `createSignal` | A function that returns a signal. This can be used to create a custom storage for the resource. This is still experimental |
149+
150+
## Note for TypeScript users
151+
152+
The function and type definitions for `createResource` are as follows:
153+
154+
```tsx
155+
import { createResource } from "solid-js"
156+
import type { ResourceReturn, ResourceOptions } from "solid-js"
157+
158+
type ResourceReturn<T> = [
159+
{
160+
(): T | undefined
161+
state: "unresolved" | "pending" | "ready" | "refreshing" | "errored"
162+
loading: boolean
163+
error: any
164+
latest: T | undefined
165+
},
166+
{
167+
mutate: (v: T | undefined) => T | undefined
168+
refetch: (info: unknown) => Promise<T> | T
169+
}
170+
]
171+
172+
type ResourceOptions<T, S = unknown> = {
173+
initialValue?: T
174+
name?: string
175+
deferStream?: boolean
176+
ssrLoadFrom?: "initial" | "server"
177+
storage?: (
178+
init: T | undefined
179+
) => [Accessor<T | undefined>, Setter<T | undefined>]
180+
onHydrated?: (k: S | undefined, info: { value: T | undefined }) => void
181+
}
182+
183+
function createResource<T, U = true>(
184+
fetcher: (
185+
k: U,
186+
info: { value: T | undefined; refetching: boolean | unknown }
187+
) => T | Promise<T>,
188+
options?: ResourceOptions<T, U>
189+
): ResourceReturn<T>
190+
191+
function createResource<T, U>(
192+
source: U | false | null | (() => U | false | null),
193+
fetcher: (
194+
k: U,
195+
info: { value: T | undefined; refetching: boolean | unknown }
196+
) => T | Promise<T>,
197+
options?: ResourceOptions<T, U>
198+
): ResourceReturn<T>
199+
200+
```

‎src/routes/solid-router/reference/data-apis/create-async.mdx‎

Lines changed: 32 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,42 @@
22
title: createAsync
33
---
44

5-
<Callout>
6-
This is light wrapper over [`createResource`](/reference/basic-reactivity/create-resource)
7-
which serves as a stand-in for a future primitive being brought to Solid core
8-
in 2.0.
9-
</Callout>
10-
115
An asynchronous primitive with a function that tracks similar to `createMemo`.
126
`createAsync` expects a promise back that is then turned into a Signal.
137
Reading it before it is ready causes Suspense/Transitions to trigger.
148

15-
```jsx
16-
const user = createAsync(() => getUser(params.id));
17-
```
18-
19-
<Callout>
9+
<Callout type="caution">
2010
Using `cache` in `createResource` directly will not work since the fetcher is
2111
not reactive. This means that it will not invalidate properly.
2212
</Callout>
13+
14+
This is light wrapper over [`createResource`](/reference/basic-reactivity/create-resource) which serves as a stand-in for a future primitive being brought to Solid core in 2.0.
15+
It is recommended that `createAsync` be used in favor of `createResource` specially when in a **SolidStart** app because `createAsync` works better in conjunction with the [cache](/solid-router/reference/data-apis/cache) helper.
16+
17+
18+
19+
```tsx title="component.tsx" {6,10}
20+
import { createAsync } from "solid/router";
21+
import { Suspense } from "solid-js";
22+
import { getUser } from "./api";
23+
24+
export function Component () => {
25+
const user = createAsync(() => getUser(params.id));
26+
27+
return (
28+
<Suspense fallback="loading user...">
29+
<p>{user()}</p>
30+
</Suspense>
31+
);
32+
```
33+
34+
## Options
35+
36+
| Name | Type | Default | Description |
37+
| ------------ | ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
38+
| name | `string` | `undefined` | A name for the resource. This is used for debugging purposes. |
39+
| deferStream | `boolean` | `false` | If true, Solid will wait for the resource to resolve before flushing the stream. |
40+
| initialValue | `any` | `undefined` | The initial value of the resource. |
41+
| onHydrated | `function` | `undefined` | A callback that is called when the resource is hydrated. |
42+
| ssrLoadFrom | `"server" \| "initial"` | `"server"` | The source of the initial value for SSR. If set to `"initial"`, the resource will use the `initialValue` option instead of the value returned by the fetcher. |
43+
| storage | `function` | `createSignal` | A function that returns a signal. This can be used to create a custom storage for the resource. This is still experimental

0 commit comments

Comments
 (0)