actions

Every export of kitr/actions, read from the published type definitions. The guide shows them in use.

kitr/actions

Re-exports @tanstack/start-client-core unchanged, plus the following.

defineAction

function defineAction<S extends StandardSchemaV1 | undefined = undefined, TOutput = unknown, TContext = {}>(name: string, options: DefineActionOptions<S, TOutput, TContext>): Action<S extends StandardSchemaV1 ? InferOutput<S> : void, TOutput>;

A server action: a TanStack Start server function with kitr's input validation, one error shape (validation errors land on form fields) and cache effects.

export const updateProject = defineAction('projects.update', {
  input: updateProjectSchema,
  effects: (project) => ({ set: [{ key: ['projects', 'detail', project.id], data: project }], invalidate: [['projects', 'list']] }),
  handler: ({ input }) => db.projects.update(input),
})

requireSession

const requireSession: import("@tanstack/react-start").FunctionMiddlewareAfterServer<{}, unknown, undefined, undefined, undefined, undefined, undefined>;

Shortcut: a function middleware that rejects anonymous callers. Expects context.session from an earlier middleware.

Action

interface Action<TInput, TOutput> {
  (input: TInput, options?: {
    signal?: AbortSignal;
  }): Promise<TOutput>;
  readonly name: string;
  key(input: TInput): QueryKey;
  query(): Omit<QueryContract<TInput, TOutput>, 'kind'>;
  mutation(): Omit<MutationContract<TInput, TOutput>, 'kind'>;
  /** The raw TanStack server function, for `useServerFn` or middleware composition. */
  serverFn: (opts: {
    data: unknown;
    signal?: AbortSignal;
  }) => Promise<Envelope<TOutput>>;
}

ActionContext

interface ActionContext<TInput, TContext> {
  input: TInput;
  /** Context from Start middleware (request, session...). */
  context: TContext;
  signal: AbortSignal;
}

DefineActionOptions

interface DefineActionOptions<S extends StandardSchemaV1 | undefined, TOutput, TContext> {
  /** GET actions can be cached and prefetched like queries; POST (default) for mutations. */
  method?: 'GET' | 'POST';
  input?: S;
  /** TanStack Start middleware (`createMiddleware({ type: 'function' })`). */
  middleware?: ReadonlyArray<any>;
  /** Cache effects applied on the client after success (mutations). */
  effects?: CacheEffect | ((result: TOutput, input: S extends StandardSchemaV1 ? InferOutput<S> : void) => CacheEffect);
  handler: (ctx: ActionContext<S extends StandardSchemaV1 ? InferOutput<S> : void, TContext>) => TOutput | Promise<TOutput>;
}