Skip to main content

Types

/

SafeActionClientOpts

Type of options when creating a new safe action client.

export type SafeActionClientOpts<
ServerError,
MetadataSchema extends Schema | undefined,
> = {
handleServerErrorLog?: (e: Error) => MaybePromise<void>;
handleReturnedServerError?: (e: Error) => MaybePromise<ServerError>;
defineMetadataSchema?: () => MetadataSchema;
};

SafeActionResult

Type of the result of a safe action.

export type SafeActionResult<
ServerError,
S extends Schema | undefined,
BAS extends readonly Schema[],
FVE = ValidationErrors<S>,
FBAVE = BindArgsValidationErrors<BAS>,
Data = unknown,
NextCtx = unknown,
> = {
data?: Data;
serverError?: ServerError;
validationErrors?: FVE;
bindArgsValidationErrors?: FBAVE;
};

SafeActionFn

Type of the function called from components with typesafe input data.

export type SafeActionFn<
ServerError,
S extends Schema | undefined,
BAS extends readonly Schema[],
FVE,
FBAVE,
Data,
> = (
...clientInputs: [...InferInArray<BAS>, S extends Schema ? InferIn<S> : void]
) => Promise<SafeActionResult<ServerError, S, BAS, FVE, FBAVE, Data>>;

MiddlewareResult

Type of the result of a middleware function. It extends the result of a safe action with information about the action execution.

export type MiddlewareResult<ServerError, NextCtx> = SafeActionResult<
ServerError,
any,
any,
any,
any,
unknown,
NextCtx
> & {
parsedInput?: unknown;
bindArgsParsedInputs?: unknown[];
ctx?: unknown;
success: boolean;
};

MiddlewareFn

Type of the middleware function passed to a safe action client.

export type MiddlewareFn<ServerError, Ctx, NextCtx, MD> = {
(opts: {
clientInput: unknown;
bindArgsClientInputs: unknown[];
ctx: Ctx;
metadata: MD | null;
next: {
<const NC>(opts: { ctx: NC }): Promise<MiddlewareResult<ServerError, NC>>;
};
}): Promise<MiddlewareResult<ServerError, NextCtx>>;
};

ServerCodeFn

Type of the function that executes server code when defining a new safe action.

export type ServerCodeFn<
S extends Schema | undefined,
BAS extends readonly Schema[],
Data,
Ctx,
MD,
> = (args: {
parsedInput: S extends Schema ? Infer<S> : undefined;
bindArgsParsedInputs: InferArray<BAS>;
ctx: Ctx;
metadata: MD;
}) => Promise<Data>;

ValidationErrors

Type of the returned object when input validation fails.

export type ValidationErrors<S extends Schema | undefined> = S extends Schema
? Infer<S> extends object
? Prettify<ErrorList & SchemaErrors<Infer<S>>>
: ErrorList
: undefined;

BindArgsValidationErrors

Type of the array of validation errors of bind arguments.

export type BindArgsValidationErrors<BAS extends readonly Schema[]> = {
[K in keyof BAS]: ValidationErrors<BAS[K]>;

FlattenedValidationErrors

Type of flattened validation errors. formErrors contains global errors, and fieldErrors contains errors for each field, one level deep.

export type FlattenedValidationErrors<VE extends ValidationErrors<any>> =
Prettify<{
formErrors: string[];
fieldErrors: {
[K in keyof Omit<VE, "_errors">]?: string[];
};
}>;

FlattenedBindArgsValidationErrors

Type of flattened bind arguments validation errors.

export type FlattenedBindArgsValidationErrors<
BAVE extends readonly ValidationErrors<any>[],
> = {
[K in keyof BAVE]: FlattenedValidationErrors<BAVE[K]>;
};

FormatValidationErrorsFn

Type of the function used to format validation errors.

export type FormatValidationErrorsFn<S extends Schema | undefined, FVE> = (
validationErrors: ValidationErrors<S>
) => FVE;

FormatBindArgsValidationErrorsFn

Type of the function used to format bind arguments validation errors.

export type FormatBindArgsValidationErrorsFn<
BAS extends readonly Schema[],
FBAVE,
> = (bindArgsValidationErrors: BindArgsValidationErrors<BAS>) => FBAVE;

/hooks

HookResult

Type of result object returned by useAction and useOptimisticAction hooks.

If a server-client communication error occurs, fetchError will be set to the error message.

export type HookResult<
ServerError,
S extends Schema | undefined,
BAS extends readonly Schema[],
FVE,
FBAVE,
Data,
> = SafeActionResult<ServerError, S, BAS, FVE, FBAVE, Data> & {
fetchError?: string;
};

HookCallbacks

Type of hooks callbacks. These are executed when action is in a specific state.

export type HookCallbacks<
ServerError,
S extends Schema | undefined,
BAS extends readonly Schema[],
FVE,
FBAVE,
Data,
> = {
onExecute?: (args: {
input: S extends Schema ? InferIn<S> : undefined;
}) => MaybePromise<void>;
onSuccess?: (args: {
data: Data;
input: S extends Schema ? InferIn<S> : undefined;
reset: () => void;
}) => MaybePromise<void>;
onError?: (args: {
error: Omit<HookResult<ServerError, S, BAS, FVE, FBAVE, Data>, "data">;
input: S extends Schema ? InferIn<S> : undefined;
reset: () => void;
}) => MaybePromise<void>;
onSettled?: (args: {
result: HookResult<ServerError, S, BAS, FVE, FBAVE, Data>;
input: S extends Schema ? InferIn<S> : undefined;
reset: () => void;
}) => MaybePromise<void>;
};

HookSafeActionFn

Type of the safe action function passed to hooks. Same as SafeActionFn except it accepts just a single input, without bind arguments.

export type HookSafeActionFn<
ServerError,
S extends Schema | undefined,
BAS extends readonly Schema[],
FVE,
FBAVE,
Data,
> = (
clientInput: S extends Schema ? InferIn<S> : undefined
) => Promise<SafeActionResult<ServerError, S, BAS, FVE, FBAVE, Data>>;

HookActionStatus

Type of the action status returned by useAction and useOptimisticAction hooks.

type HookActionStatus = "idle" | "executing" | "hasSucceeded" | "hasErrored";

Internal utility types

Prettify

Takes an object type and makes it more readable.

export type Prettify<T> = {
[K in keyof T]: T[K];
} & {};

MaybePromise

Returns type or promise of type.

export type MaybePromise<T> = Promise<T> | T;

InferArray

Infers output schema type in array of schemas.

export type InferArray<BAS extends readonly Schema[]> = {
[K in keyof BAS]: Infer<BAS[K]>;
};

InferInArray

Infers input schema type in array of schemas.

export type InferInArray<BAS extends readonly Schema[]> = {
[K in keyof BAS]: InferIn<BAS[K]>;
};

Internal validation errors types

ErrorList

Object with an optional list of validation errors. Used in ValidationErrors type.

export type ErrorList = Prettify<{ _errors?: string[] }>;

SchemaErrors

Creates nested schema validation errors type using recursion. Used in ValidationErrors type.

type SchemaErrors<S> = {
[K in keyof S]?: S[K] extends object | null | undefined
? Prettify<ErrorList & SchemaErrors<S[K]>>
: ErrorList;
} & {};

TypeSchema library

Infer, InferIn, Schema types used in this documentation come from TypeSchema library.