Types

This page documents all the TypeScript types exported by next-safe-action. Types are exported from the main next-safe-action entry point unless otherwise noted.

Core types

`SafeActionResult`

The result object returned by every action execution. Each field is optional, and the presence of fields indicates the action's outcome.

type SafeActionResult<ServerError, S, CVE, Data> = {
	data?: Data;
	serverError?: ServerError;
	validationErrors?: CVE;
};

Prop

Type

`SafeActionFn`

The callable function type returned by .action().

type SafeActionFn<ServerError, S, BAS, CVE, Data> = (
	...clientInputs: [...bindArgsInputs: InferInputArray<BAS>, input: InferInput<S>]
) => Promise<SafeActionResult<ServerError, S, CVE, Data>>;

When bind args are defined, they appear as leading parameters. The main input is always the last parameter.

`SafeStateActionFn`

The callable function type returned by .stateAction().

type SafeStateActionFn<ServerError, S, BAS, CVE, Data> = (
	...clientInputs: [
		...bindArgsInputs: InferInputArray<BAS>,
		prevResult: SafeActionResult<ServerError, S, CVE, Data>,
		input: InferInput<S>,
	]
) => Promise<SafeActionResult<ServerError, S, CVE, Data>>;

Same as SafeActionFn but includes prevResult as the second-to-last parameter, before the main input.

Middleware types

`MiddlewareFn`

The function type for middleware defined via .use() or createMiddleware().define().

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

`MiddlewareResult`

The result type returned by the next() function inside middleware. Extends SafeActionResult with execution metadata.

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

Prop

Type

Server code types

`ServerCodeFn`

The function type for the server code passed to .action().

type ServerCodeFn<MD, Ctx, S, BAS, Data> = (args: {
	parsedInput: InferOutput<S> | undefined;
	clientInput: InferInput<S> | undefined;
	bindArgsParsedInputs: InferOutputArray<BAS>;
	bindArgsClientInputs: InferInputArray<BAS>;
	ctx: Ctx;
	metadata: MD;
}) => Promise<Data>;

`StateServerCodeFn`

The function type for the server code passed to .stateAction(). Same as ServerCodeFn but with a second utils argument.

type StateServerCodeFn<ServerError, MD, Ctx, S, BAS, CVE, Data> = (
	args: {
		parsedInput: InferOutput<S> | undefined;
		clientInput: InferInput<S> | undefined;
		bindArgsParsedInputs: InferOutputArray<BAS>;
		bindArgsClientInputs: InferInputArray<BAS>;
		ctx: Ctx;
		metadata: MD;
	},
	utils: {
		prevResult: SafeActionResult<ServerError, S, CVE, Data>;
	}
) => Promise<Data>;

Configuration types

`CreateClientOpts`

Options passed to createSafeActionClient().

type CreateClientOpts<ODVES, ServerError, MetadataSchema> = {
	defineMetadataSchema?: () => MetadataSchema;
	handleServerError?: HandleServerErrorFn<ServerError, MetadataSchema>;
	defaultValidationErrorsShape?: ODVES;
	throwValidationErrors?: boolean;
};

`SafeActionUtils`

Server-side callbacks and options passed as the second argument to .action() and .stateAction().

type SafeActionUtils<ServerError, MD, Ctx, S, BAS, CVE, Data> = {
	throwServerError?: boolean;
	throwValidationErrors?: boolean | {
		overrideErrorMessage: (validationErrors: CVE) => Promise<string>;
	};
	onSuccess?: (args: { data?, metadata, ctx?, clientInput, bindArgsClientInputs, parsedInput, bindArgsParsedInputs }) => Promise<unknown>;
	onNavigation?: (args: { metadata, ctx?, clientInput, bindArgsClientInputs, navigationKind }) => Promise<unknown>;
	onError?: (args: { error, metadata, ctx?, clientInput, bindArgsClientInputs }) => Promise<unknown>;
	onSettled?: (args: { result, metadata, ctx?, clientInput, bindArgsClientInputs, navigationKind? }) => Promise<unknown>;
};

`HandleServerErrorFn`

The type for the handleServerError callback.

type HandleServerErrorFn<ServerError, MetadataSchema> = (
	error: Error,
	utils: ServerErrorFunctionUtils<MetadataSchema>
) => MaybePromise<ServerError>;

`ServerErrorFunctionUtils`

Utils passed to handleServerError.

type ServerErrorFunctionUtils<MetadataSchema> = {
	clientInput: unknown;
	bindArgsClientInputs: unknown[];
	ctx: object;
	metadata: InferOutput<MetadataSchema> | undefined;
};

Validation error types

`ValidationErrors`

The formatted validation errors type, mirroring the schema structure.

type ValidationErrors<S> = S extends StandardSchemaV1
	? InferOutput<S> extends NotObject
		? { _errors?: string[] }
		: { _errors?: string[] } & SchemaErrors<InferOutput<S>>
	: undefined;

Each level of the schema can have an _errors array. Nested objects create nested error objects.

`FlattenedValidationErrors`

The flattened validation errors type, with top-level formErrors and fieldErrors.

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

`HandleValidationErrorsShapeFn`

Function type for custom validation error shaping.

type HandleValidationErrorsShapeFn<S, BAS, MD, Ctx, CVE> = (
	validationErrors: ValidationErrors<S>,
	utils: {
		clientInput: InferInput<S> | undefined;
		bindArgsClientInputs: InferInputArray<BAS>;
		metadata: MD;
		ctx: Ctx;
	}
) => Promise<CVE>;

`NavigationKind`

Union type representing framework navigation functions.

type NavigationKind = "redirect" | "notFound" | "forbidden" | "unauthorized" | "other";

Enums and constants

`DVES`

The default validation errors shape type.

type DVES = "formatted" | "flattened";

Utility types

`Prettify`

Makes complex intersection types readable in IDE hover tooltips.

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

`MaybePromise`

Accepts a value or a promise of a value.

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

`MaybeArray`

Accepts a value or an array of values.

type MaybeArray<T> = T | T[];