@venturekit/runtime

Installation

npm install @venturekit/runtime@dev

What It Provides

Handler

The unified handler() function wraps your Lambda business logic:

import { handler } from '@venturekit/runtime';

// Public
export const main = handler(async (_body, ctx, logger) => {
  return { status: 'ok' };
});

// Authenticated
export const main = handler(async (body, ctx, logger) => {
  return { id: '123', name: body.name };
}, { scopes: ['api.write'] });

Task Handler

For non-HTTP Lambdas — queue consumers, scheduled crons, internal jobs — use taskHandler() / queueBatchHandler(). They expose the same middleware, logging, validation, transaction, and retry primitives as handler(), plus a TaskValidationError that bypasses the retry loop.

import { taskHandler, queueBatchHandler, TaskValidationError } from '@venturekit/runtime';

Context

Typed request context with user info, tenant context, and metadata:

import { buildContext, extractUserContext, extractLocale } from '@venturekit/runtime';

Key fields: requestId, timestamp, method, path, user, tenant, locale, queryParams, tx, intentOutputs.

Response Helpers

import { success, created, noContent, error, errorResponse, redirect } from '@venturekit/runtime';

Errors

Structured error classes that map to HTTP status codes:

import {
  VentureError, BadRequestError, UnauthorizedError, ForbiddenError,
  NotFoundError, ConflictError, PayloadTooLargeError, ValidationError,
  RateLimitError, InternalError, ServiceUnavailableError, isVentureError,
} from '@venturekit/runtime';

Logger

Structured logging via Pino:

import { Logger, createLogger, logger } from '@venturekit/runtime';

Middleware

Composable middleware system:

import {
  compose,
  loggingMiddleware,
  corsMiddleware,
  timeoutMiddleware,
  errorBoundaryMiddleware,
  rateLimitMiddleware,
  requestIdMiddleware,
  timingMiddleware,
  apiKeyAuthMiddleware,
} from '@venturekit/runtime';

// In-process rate-limit store (auto-selected by `createDefaultRateLimiter()`
// in local dev — falls back to DynamoDB in deployed Lambdas).
import { createMemoryRateLimitStore, RATE_LIMIT_PRESETS } from '@venturekit/runtime';

Metrics

CloudWatch Embedded-Metric-Format emitter — no AWS SDK call per metric, just structured logs that CloudWatch ingests as metrics:

import { createMetrics } from '@venturekit/runtime';

const metrics = createMetrics({ namespace: 'MyApp/API' });
metrics.putDimensions({ Service: 'orders', Stage: 'prod' });
metrics.putMetric('OrdersCreated', 1, 'Count');
metrics.putMetric('CheckoutDurationMs', durationMs, 'Milliseconds');
metrics.flush();

// Or wrap an async block:
await metrics.timeAsync('Checkout', () => processCheckout(body));

Tracing

W3C traceparent propagation primitives — used internally by invoke() and queue dispatchers, exposed so custom integrations can join the same trace:

import {
  extractTraceContext,
  injectTraceHeaders,
  createChildTrace,
  traceFromRequest,
  generateId,
  TRACE_HEADERS,
} from '@venturekit/runtime';

Local Dev Adapter

Convert plain Node HTTP requests into Lambda events (and back) so the same handler can power both the deployed API Gateway route and the vk dev HTTP server:

import {
  httpToLambdaEvent,
  createLocalContext,
  lambdaResultToHttp,
  adaptHandler,
} from '@venturekit/runtime';

Env Client

Lightweight, typed wrapper around process.env — required for the schema-validated env-var path used by the rest of the runtime:

import { env, createEnvClient } from '@venturekit/runtime';

const port = env.getNumber('PORT', 3000);
const dbUrl = env.require('DATABASE_URL');
const debug = env.getBool('DEBUG', false);

WebSocket Connection Store

For real-time applications:

import { connectionStore } from '@venturekit/runtime/ws';

await connectionStore.save(connectionId);
await connectionStore.authenticate(connectionId, { userId, email });
await connectionStore.sendToUser(domain, stage, userId, data);
await connectionStore.broadcast(domain, stage, data);

Subpath Exports

Heavy optional modules are split into subpath imports to keep the core entry point lightweight:

Subpath	Description
`@venturekit/runtime/ws`	WebSocket connection store (DynamoDB)
`@venturekit/runtime/patterns`	`invoke`, `saga`, circuit breaker, idempotency
`@venturekit/runtime/queue`	Queue driver types + `createRedisDriver` for cross-process queues in dev
`@venturekit/runtime/rate-limit`	DynamoDB-backed rate limit stores
`@venturekit/runtime/secrets`	SSM / Secrets Manager client
`@venturekit/runtime/openapi`	OpenAPI spec generation
`@venturekit/runtime/testing`	Test utilities (`mockEvent`, `mockContext`, etc.)

Dependencies

@venturekit/core — required
pino — structured logging
@venturekit/data — optional peer (for transactional handlers)
AWS SDK — optional peers (for WebSocket connection store)

Handlers — deep dive into the handler API
Middleware — writing and composing middleware
Error Handling — structured error classes
WebSockets — real-time applications
API Reference — full type documentation