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 = null,
  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
    ? PrettyMerge<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;

PrettyMerge​

Merges an object without printing "&".

type PrettyMerge<S> = S extends infer U ? { [K in keyof U]: U[K] } : never;

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
    ? PrettyMerge<ErrorList & SchemaErrors<S[K]>>
    : ErrorList;
} & {};

TypeSchema library​

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