Instance Methods

Builder API reference

The ZagoraBuilder provides a fluent API for defining procedures.

.input(schema)

Define the input validation schema.

.input(z.string())
.input(z.object({ name: z.string() }))
.input(z.tuple([z.string(), z.number()]))
.input(z.array(z.number()))

Parameter: Any StandardSchema-compliant schema
Returns: ZagoraBuilder (chainable)

Tuple Spreading

Tuple inputs are spread as handler arguments:

.input(z.tuple([z.string(), z.number()]))
.handler((_, name, age) => { /* name: string, age: number */ })

.output(schema)

Define the output validation schema.

.output(z.object({ id: z.string(), name: z.string() }))

Parameter: Any StandardSchema-compliant schema
Returns: ZagoraBuilder (chainable)

Output is validated after the handler returns.

.errors(map)

Define typed error schemas.

.errors({
  NOT_FOUND: z.object({ id: z.string() }),
  FORBIDDEN: z.object({ reason: z.string() })
})

Parameter: Object mapping UPPERCASE error kinds to schemas
Returns: ZagoraBuilder (chainable)

The handler receives typed error helpers:

.handler(({ errors }) => {
  throw errors.NOT_FOUND({ id: '123' });
})

.context(initial)

Set initial context values.

.context({ db: myDatabase, logger: console })

Parameter: Object with initial context values
Returns: ZagoraBuilder (chainable)

Context is merged with runtime context from .callable().

.env(schema, runtime?)

Define environment variable schema.

.env(z.object({
  API_KEY: z.string(),
  TIMEOUT: z.coerce.number().default(5000)
}))

Parameters:

schema - StandardSchema for env vars
runtime (optional) - Runtime env vars (for autoCallable mode)

Returns: ZagoraBuilder (chainable)

With autoCallable:

zagora({ autoCallable: true })
  .env(schema, process.env as any)

.cache(adapter)

Set cache adapter for memoization.

.cache(new Map())
.cache(redisAdapter)

Parameter: Object with has, get, set methods
Returns: ZagoraBuilder (chainable)

Cache interface:

interface CacheAdapter<K, V> {
  has(key: K): boolean | Promise<boolean>;
  get(key: K): V | undefined | Promise<V | undefined>;
  set(key: K, value: V): void | Promise<void>;
}

.handler(fn)

Define the handler function.

// With options
.handler((options, input) => {
  const { context, errors, env } = options;
  return result;
})
 
// With tuple input
.handler((options, arg1, arg2) => arg1 + arg2)
 
// With disableOptions
.handler((input) => input.toUpperCase())

Parameter: Handler function
Returns: ZagoraBuilder (chainable) or callable function (if autoCallable)

Handler Signature

Standard mode:

(options: { context, errors?, env? }, ...inputs) => Result

With disableOptions:

(...inputs) => Result

.callable(options?)

Create the callable function.

.callable()
.callable({ context: { db: testDb } })
.callable({ cache: requestCache })
.callable({ env: process.env as any })

Parameter (optional): Runtime options

context - Override/extend context
cache - Override cache adapter
env - Provide environment variables

Returns: Callable procedure function

Return Type

The returned function has signature:

(...inputs) => ZagoraResult<TOutput, TErrors>
// or
(...inputs) => Promise<ZagoraResult<TOutput, TErrors>>

Method Chaining

All methods return the builder, allowing fluent chaining:

const proc = zagora()
  .context({ db })
  .env(envSchema)
  .input(inputSchema)
  .output(outputSchema)
  .errors(errorMap)
  .cache(cache)
  .handler(handlerFn)
  .callable(runtimeOptions);

Optional Methods

Only .handler() is required. All other methods are optional:

// Minimal procedure
const proc = zagora()
  .handler(() => 'Hello')
  .callable();