1import type { Mutation } from "./mutation.ts";
2
3/**
4 * Plain JSON value. The default serializable leaf set, still exported for
5 * consumers that want the exact JSON shape.
6 */
7export type Json =
8 | string
9 | number
10 | boolean
11 | null
12 | Json[]
13 | { [key: string]: Json };
14
15/**
16 * Registry of serializable leaf types. Empty by default, which reduces
17 * {@link SerializableValue} to plain JSON. Downstream consumers whose transport
18 * handles a superset of JSON augment this to register those types:
19 *
20 * ```ts
21 * declare module "@clo/react-mutation" {
22 * interface SerializableLeaves { file: File | Blob }
23 * }
24 * ```
25 */
26export interface SerializableLeaves {}
27
28type Leaf = string | number | boolean | null | undefined | SerializableLeaves[keyof SerializableLeaves];
29
30/**
31 * Validates that `T` is serializable: every leaf is a registered {@link Leaf}
32 * and nested objects/arrays recurse. Enforced at `define` for `auth: true`
33 * arguments; unlike a concrete value type it accepts `interface` arguments,
34 * because the object case is a mapped type over `keyof T` and so needs no index
35 * signature the way `{ [k: string]: ... }` would. Any non-serializable member
36 * (a function/method, an unregistered class) collapses to `never`.
37 */
38export type Serializable<T> = [T] extends [Leaf] ? T
39 : T extends (...args: never[]) => unknown ? never
40 : T extends readonly unknown[] ? { [I in keyof T]: Serializable<T[I]> }
41 : T extends object ? { [K in keyof T]: Serializable<T[K]> }
42 : never;
43
44/**
45 * A concrete serializable value, driven by the {@link SerializableLeaves}
46 * registry. Stored in a {@link MutationAction} for replay after sign-in.
47 */
48export type SerializableValue =
49 | Leaf
50 | SerializableValue[]
51 | { [key: string]: SerializableValue };
52
53/**
54 * A serializable record of a mutation call. Produced when an authenticated
55 * mutation is attempted without a user; pass it to `MutationClient.run`
56 * after sign-in to re-run the call.
57 */
58export interface MutationAction {
59 id: string;
60 description: string;
61 args: SerializableValue[];
62}
63
64export interface RunOptions<Result> {
65 /** Called to show the success UI. Passing this suppresses the global success handler. */
66 onSuccessUi?: (result: Result) => void;
67 /**
68 * Called with result data, but unlike `onSuccessUi`, this indicates the
69 * caller is not concerned with the UI flow of the success. Passing this
70 * does NOT suppress the global success handler.
71 */
72 onSuccessData?: (result: Result) => void;
73 /** Called on error, suppresses the global error handler */
74 onError?: (error: unknown) => void;
75 /** Called on settled (doesn't suppress global handlers) */
76 onSettled?: (
77 status:
78 | { status: "success"; result: Result }
79 | { status: "error"; error: unknown },
80 ) => void;
81 /** Called when optimistic state is being restored/rolled back */
82 onRestore?: () => void;
83 /**
84 * Called instead of running an authenticated mutation when no user is
85 * available. The action is JSON serializable and can be passed to
86 * `MutationClient.run` after sign-in.
87 */
88 onUnauthenticated?: (action: MutationAction, mutation: Mutation<SerializableValue[], unknown>) => void;
89}
90
91export interface MutationEvent<Result> {
92 status: "idle" | "waiting" | "mutating" | "refetching" | "skipped";
93 result: Result | null;
94 error: unknown;
95 debounced: boolean;
96}