Open History to see the last commit
1import { defaultSerializeError } from './router'
2β
3/**
4 * Well-known symbol used by {@link defer} to tag a promise with
5 * its deferred state. Consumers can read `promise[TSR_DEFERRED_PROMISE]`
6 * to access `status`, `data`, or `error`.
7 */
8export const TSR_DEFERRED_PROMISE = Symbol.for('TSR_DEFERRED_PROMISE')
9β
10export type DeferredPromiseState<T> =
11 | {
12 status: 'pending'
13 data?: T
14 error?: unknown
15 }
16 | {
17 status: 'success'
18 data: T
19 }
20 | {
21 status: 'error'
22 data?: T
23 error: unknown
24 }
25β
26export type DeferredPromise<T> = Promise<T> & {
27 [TSR_DEFERRED_PROMISE]: DeferredPromiseState<T>
28}
29β
30/**
31 * Wrap a promise with a deferred state for use with `<Await>` and `useAwaited`.
32 *
33 * The returned promise is augmented with internal state (status/data/error)
34 * so UI can read progress or suspend until it settles.
35 *
36 * @param _promise The promise to wrap.
37 * @param options Optional config. Provide `serializeError` to customize how
38 * errors are serialized for transfer.
39 * @returns The same promise with attached deferred metadata.
40 * @link https://tanstack.com/router/latest/docs/framework/react/api/router/deferFunction
41 */
42export function defer<T>(
43 _promise: Promise<T>,
44 options?: {
45 serializeError?: typeof defaultSerializeError
46 },
47) {
48 const promise = _promise as DeferredPromise<T>
49 // this is already deferred promise
50 if ((promise as any)[TSR_DEFERRED_PROMISE]) {
51 return promise
52 }
53 promise[TSR_DEFERRED_PROMISE] = { status: 'pending' }
54β
55 promise
56 .then((data) => {
57 promise[TSR_DEFERRED_PROMISE].status = 'success'
58 promise[TSR_DEFERRED_PROMISE].data = data
59 })
60 .catch((error) => {
61 promise[TSR_DEFERRED_PROMISE].status = 'error'
62 ;(promise[TSR_DEFERRED_PROMISE] as any).error = {
63 data: (options?.serializeError ?? defaultSerializeError)(error),
64 __isServerError: true,
65 }
66 })
67β
68 return promise
69}