Invocation context

Use invocation metadata, cancellation, time, logging, environment, and declared clients without globals.

A function’s second parameter, context, gives that invocation access to logging, time, cancellation, and its declared resources. RELKIT builds it from the checked graph, so a function receives common runtime capabilities plus typed clients for only the resources it declares. Never store context in a module variable or reuse it after the invocation completes.

Use declared clients

/** Prices validated order input through the declared cache, records request tracing and derives its receipt key. */
import { defineFunction } from "@relkit/app/functions";
import prices from "../cache/prices.cache.js";
import { receiptObjectName } from "../../../platform/receipt-object.js";
import { createOrderOutput, orderInput } from "../../../platform/schemas.js";

const createOrder = defineFunction({
  // RELKIT validates these schemas before the handler runs.
  input: orderInput,
  output: createOrderOutput,
  dependencies: {
    cache: { prices },
  },
  timeoutMs: 10_000,
  concurrency: 100,
  handler: async (input, context) => {
    // Dependencies are accessed through the checked execution context.
    const unitPrice = await context.trace.span(
      "pricing.calculate",
      { attributes: { "pricing.strategy": "catalog" } },
      () => context.cache.prices.getOrSet({ sku: input.sku }, async () => 1_000),
    );
    context.trace.event("pricing.calculated", { "pricing.unit_cents": unitPrice });
    context.trace.setAttributes({ "pricing.quantity": input.quantity });
    const totalCents = unitPrice * input.quantity;
    return {
      orderId: input.orderId,
      receiptKey: receiptObjectName(input.orderId),
      totalCents,
    };
  },
});

export default createOrder;

This function declares the prices cache, so its handler receives context.cache.prices. Merely importing a cache or putting it in the same domain does not grant access.

Event publication uses an explicit publishes list rather than dependencies:

import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

const createOrder = defineFunction({
  input: z.object({
    orderId: z.string().min(1),
    sku: z.string().min(1),
    quantity: z.number().int().positive(),
  }),
  output: z.object({
    orderId: z.string(),
    sku: z.string(),
    totalCents: z.number().int().nonnegative(),
  }),
  publishes: ["orders.created"],
  handler: async (input, context) => {
    const order = { orderId: input.orderId, sku: input.sku, totalCents: input.quantity * 100 };
    await context.events["orders.created"].publish(order);
    return order;
  },
});

export default createOrder;

The exact event ID becomes available under context.events; publishing any undeclared ID fails the checked edge.

Know the common context

There is no service middleware or context.service. A service exposes public functions and events; it does not inject handler state. Database and Auth are specialized application context integrations, documented in Database and Auth sessions.

RELKIT traces routes, functions, declared clients, jobs, events, tools, and agents automatically. Use context.trace only for application work the runtime cannot infer. See Observability for the three tracing operations and an executable example.

Add access safely

bun run check
bun run test