Actions Reference

Complete reference for actions and workflows.

action()

Create an action builder.

function action<TInput, TOutput>(name?: string): ActionBuilder

ActionBuilder Methods

.input(schema)

Define input validation.

.input({
  email: string.email(),
  message: text,
})

.handler(fn)

Set action handler.

.handler(async (ctx) => {
  return { success: true }
})

.onResource()

Require resource ID.

.onResource()
// Creates: POST /api/entities/:id/action

.rules(...rules)

Set authorization rules.

.rules("owner", "admin")
.rules("authenticated")

.method(method)

Set HTTP method.

.method("GET")
.method("PUT")
.method("DELETE")

.path(path)

Set custom action path (overrides default).

.path("/custom/url/activate")

.get() / .post()

Method shortcuts.

.get()  // GET method
.post() // POST method (default)

.workflow(steps, options?)

Define workflow.

.workflow([
  step("reserve", execute, compensate),
  step("charge", execute, compensate),
])

.meta(metadata)

Add metadata.

.meta({
  description: "Process payment",
  rateLimit: 10,
})

Action Context

interface ActionContext {
  input: TInput           // Validated input
  resourceId?: string     // Resource ID (if onResource)
  user: User | null       // Current user
  driver: Driver          // Database driver
  resolve: (id) => any    // Service resolver
  entity: Entity          // Entity definition
}

step()

Create a workflow step.

function step<TResult>(
  name: string,
  execute: (ctx: WorkflowContext) => Promise<TResult>,
  compensate?: (ctx: WorkflowContext, result: TResult) => Promise<void>
): WorkflowStep

Parameters

Parameter	Type	Description
name	string	Step name
execute	function	Execute function
compensate	function	Compensation function (optional)

Workflow Context

interface WorkflowContext {
  input: TInput              // Action input
  data: Record<string, any>  // Accumulated data
  stepResults: Record<string, any>  // Previous step results
  driver: Driver             // Database driver
  resolve: (id) => any       // Service resolver
}

Workflow Options

.workflow([...steps], {
  useTransaction: true,  // Use database transaction
  timeout: 30000,        // Timeout in ms
  initialData: {},       // Initial data
})

Pre-built Actions

softDeleteAction

import { softDeleteAction } from "nevr"

.actions({
  softDelete: softDeleteAction,
})

restoreAction

import { restoreAction } from "nevr"

.actions({
  restore: restoreAction,
})

archiveAction / unarchiveAction

import { archiveAction, unarchiveAction } from "nevr"

.actions({
  archive: archiveAction,
  unarchive: unarchiveAction,
})

cloneAction

import { cloneAction } from "nevr"

.actions({
  clone: cloneAction,
})

bulkUpdateAction / bulkDeleteAction

import { bulkUpdateAction, bulkDeleteAction } from "nevr"

.actions({
  bulkUpdate: bulkUpdateAction,
  bulkDelete: bulkDeleteAction,
})

toggleAction

import { toggleAction } from "nevr"

.actions({
  toggle: toggleAction("isActive"),
})

countAction / existsAction

import { countAction, existsAction } from "nevr"

.actions({
  count: countAction,
  exists: existsAction,
})

exportAction

import { exportAction } from "nevr"

.actions({
  export: exportAction,
})

Examples

Simple Action

.actions({
  greet: action()
    .handler(async () => ({ message: "Hello!" })),
})

With Input

.actions({
  invite: action()
    .input({ email: string.email() })
    .rules("authenticated")
    .handler(async (ctx) => {
      await sendInvite(ctx.input.email)
      return { sent: true }
    }),
})

Resource Action

.actions({
  publish: action()
    .onResource()
    .rules("owner")
    .handler(async (ctx) => {
      return ctx.driver.update(
        "post",
        { id: ctx.resourceId },
        { published: true }
      )
    }),
})

Workflow

.actions({
  checkout: action()
    .input({ paymentMethodId: string })
    .workflow([
      step("reserve",
        async (ctx) => ctx.resolve("inventory").reserve(ctx.input),
        async (ctx, result) => ctx.resolve("inventory").release(result)
      ),
      step("charge",
        async (ctx) => ctx.resolve("stripe").charge(ctx.input),
        async (ctx, result) => ctx.resolve("stripe").refund(result)
      ),
    ], { useTransaction: true }),
})

See Also

• Creating Actions
• Workflows
• Saga Pattern