Utilities
Motia exports several utility functions and helpers for advanced use cases.
Type guards
Trigger type guards
Type guards for checking trigger types:
import { isApiTrigger, isQueueTrigger, isCronTrigger, isStateTrigger, isStreamTrigger } from 'motia'
import type { TriggerConfig } from 'motia'
const trigger: TriggerConfig = {
type: 'http',
method: 'GET',
path: '/users',
}
if (isApiTrigger(trigger)) {
// TypeScript knows trigger.method and trigger.path exist
console.log(trigger.method, trigger.path)
}
isApiTrigger
(trigger: TriggerConfig) => boolean
Returns true if the trigger is an HTTP/API trigger
isQueueTrigger
(trigger: TriggerConfig) => boolean
Returns true if the trigger is a queue trigger
isCronTrigger
(trigger: TriggerConfig) => boolean
Returns true if the trigger is a cron trigger
isStateTrigger
(trigger: TriggerConfig) => boolean
Returns true if the trigger is a state trigger
isStreamTrigger
(trigger: TriggerConfig) => boolean
Returns true if the trigger is a stream trigger
Step type guards
Type guards for checking if a Step has specific trigger types:
import { isApiStep, isQueueStep, isCronStep, isStateStep, isStreamStep } from 'motia'
import type { Step } from 'motia'
const step: Step = {
filePath: 'steps/hello.step.ts',
config: {
name: 'Hello',
triggers: [
{ type: 'http', method: 'GET', path: '/hello' }
],
},
}
if (isApiStep(step)) {
console.log('This step has HTTP triggers')
}
Returns true if the step has at least one HTTP trigger
Returns true if the step has at least one queue trigger
Returns true if the step has at least one cron trigger
Returns true if the step has at least one state trigger
Returns true if the step has at least one stream trigger
Trigger getters
Functions to extract specific trigger types from a Step:
import { getApiTriggers, getQueueTriggers } from 'motia'
import type { Step } from 'motia'
const step: Step = {
filePath: 'steps/multi.step.ts',
config: {
name: 'MultiTrigger',
triggers: [
{ type: 'http', method: 'POST', path: '/orders' },
{ type: 'queue', topic: 'order.created' },
],
},
}
const apiTriggers = getApiTriggers(step)
console.log(apiTriggers[0].method) // 'POST'
const queueTriggers = getQueueTriggers(step)
console.log(queueTriggers[0].topic) // 'order.created'
getApiTriggers
(step: Step) => ApiTrigger[]
Returns all HTTP triggers from a step
getQueueTriggers
(step: Step) => QueueTrigger[]
Returns all queue triggers from a step
getCronTriggers
(step: Step) => CronTrigger[]
Returns all cron triggers from a step
getStateTriggers
(step: Step) => StateTrigger[]
Returns all state triggers from a step
getStreamTriggers
(step: Step) => StreamTrigger[]
Returns all stream triggers from a step
iii SDK utilities
getContext
Get the current execution context (only available inside handlers):
import { getContext } from 'motia'
export const handler = async (input, ctx) => {
// Alternative way to access context
const context = getContext()
context.logger.info('Using getContext')
}
Returns the current FlowContext. Only works inside handler execution.
Logger
Structured logging interface:
import type { Logger } from 'motia'
interface Logger {
info(message: string, ...args: any[]): void
warn(message: string, ...args: any[]): void
error(message: string, ...args: any[]): void
debug(message: string, ...args: any[]): void
}
ctx.logger in handlers.
ChannelReader and ChannelWriter
Low-level streaming interfaces for request/response bodies:
import type { ChannelReader, ChannelWriter } from 'motia'
export const handler = async ({ request, response }, ctx) => {
// Read request body as stream
const reader: ChannelReader = request.requestBody
// Write response as stream
const writer: ChannelWriter = response.stream
response.status(200)
response.headers({ 'Content-Type': 'text/plain' })
// Stream response
for await (const chunk of reader) {
await writer.write(chunk)
}
response.close()
}
ChannelReader and ChannelWriter are advanced APIs for streaming. Most use cases should use the simpler request.body and response APIs.
Runtime utilities
initIII
Initialize the iii engine connection:
import { initIII } from 'motia'
await initIII()
Initializes the connection to the iii engine. Automatically called by the framework.
getInstance
Get the iii engine client instance:
import { getInstance } from 'motia'
const client = getInstance()
Returns the iii engine client instance for advanced use cases.
generateStepId
Generate a deterministic ID for a step based on its file path:
import { generateStepId } from 'motia'
const stepId = generateStepId('steps/hello.step.ts')
console.log(stepId) // Deterministic hash
generateStepId
(filePath: string) => string
Generates a unique, deterministic ID for a step file.
setupStepEndpoint
Low-level function to register a step with the iii engine:
import { setupStepEndpoint } from 'motia'
await setupStepEndpoint({
filePath: 'steps/hello.step.ts',
config: {
name: 'Hello',
triggers: [{ type: 'http', method: 'GET', path: '/hello' }],
},
handler: async (input, ctx) => {
return { status: 200, body: { message: 'Hello' } }
},
})
This is a low-level API. Most applications should use the file-based Step discovery instead.
Motia class
The core runtime class:
import { Motia } from 'motia'
const motia = new Motia()
The Motia class is used internally by the framework. Most applications don’t need to instantiate it directly.
stateManager
Global state manager instance:
import { stateManager } from 'motia'
// Access state outside of handlers (not recommended)
const value = await stateManager.get('users', 'user-123')
Prefer using ctx.state inside handlers instead of the global stateManager instance.
Next steps
Context API
Learn about the FlowContext API
Types
Explore all TypeScript types
Step API
Create steps with the step() function
State manager
Manage application state