API Reference

createServer(routesDir, config?)

Creates and starts a Lacis server. Used with the Node.js and Bun adapters.

import { createServer } from 'lacis'

createServer('./routes', { port: 3000 })

See Configuration for all config options.

---

defineHandler(config)

Wraps a route handler with schema validation, type inference, and OpenAPI metadata.

import { defineHandler } from 'lacis'

defineHandler({
  params?: StandardSchema,
  query?: StandardSchema,
  body?: StandardSchema,
  meta?: {
    summary?: string
    description?: string
    tags?: string[]
    deprecated?: boolean
  },
  cache?: WithCacheOptions,
  handler: (req, res) => void | Promise<void>,
})

Returns a typed async function (req, res) => Promise<void>.

---

createCorsMiddleware(config)

Creates a CORS middleware function.

import { createCorsMiddleware } from 'lacis'

createCorsMiddleware({
  origin?: string | string[] | RegExp | ((origin: string) => boolean) | '*',
  methods?: string[],
  allowedHeaders?: string[],
  exposedHeaders?: string[],
  credentials?: boolean,
  maxAge?: number,
})

Returns a MiddlewareCallback. See CORS.

---

createRateLimit(options?)

Creates a rate limiting middleware.

import { createRateLimit } from 'lacis'

createRateLimit({
  windowMs?: number,      // default: 60000
  max?: number,           // default: 100
  message?: string,
  keyGenerator?: (req: Request) => string,
})

Returns a MiddlewareCallback. See Rate Limiting.

---

createResponseCache(options)

Creates a response caching middleware.

import { createResponseCache } from 'lacis'

createResponseCache({
  ttl: number,            // seconds, required
  methods?: string[],     // default: ['GET', 'HEAD']
  maxSize?: number,       // default: 500
  keyGenerator?: (req: Request) => string,
  match?: (req: Request) => boolean,
  exclude?: string | string[],
  shouldCache?: (req: Request, res: Response) => boolean,
})

Returns a MiddlewareCallback. See Caching.

---

withCache(options, handler)

Wraps a single handler with response caching.

import { withCache } from 'lacis'

withCache(
  { ttl: number, maxSize?: number, key?: (req: Request) => string },
  async (req, res) => { /* ... */ }
)

Returns (req: Request, res: Response) => Promise<void>.

---

initSSE(res, options?)

Initializes a server-sent events connection. Returns an SSEContext.

import { initSSE } from 'lacis'

// Typically called via res.initSSE() in route handlers
const sse = res.initSSE({
  timeout?: number,   // default: 300000 (5 min)
  headers?: Record<string, string>,
})

---

SSEContext

Returned by res.initSSE().

Method	Signature	Description
send	(data: string) => boolean	Send a raw data line
json	(data: any) => boolean	Send JSON data
event	(event: string, data: any) => boolean	Send a named event
comment	(text: string) => boolean	Send a comment
id	(id: string) => boolean	Set the event ID
retry	(ms: number) => boolean	Set reconnect delay
close	(comment?: string) => void	Close gracefully
error	(event, message, code?, details?) => void	Send error and close

---

createSSEClient(url, options?, handlers?)

Creates a client-side SSE connection.

import { createSSEClient } from 'lacis'

const client = await createSSEClient(url, {
  method?: string,
  body?: string,
  contentType?: string,
  reconnectInterval?: number,   // default: 3000
  maxRetries?: number,          // default: 3
  disableReconnect?: boolean,
}, {
  onMessage?: (data: any) => void,
  onEvent?: Record<string, (data: any) => void>,
  onClose?: () => void,
  onError?: (error: Error) => void,
})

---

TypeScript types

import type {
  // Request / Response
  Request,
  Response,

  // Configuration
  ServerConfig,
  ServerlessConfig,
  CorsConfig,

  // Middleware
  MiddlewareCallback,
  MiddlewareHooks,

  // SSE
  SSEOptions,
  SSEClientOptions,
  SSEEventHandlers,
  SSEClient,

  // Adapters
  Adapter,

  // Monitoring
  MonitorOptions,
  HealthMetrics,
} from 'lacis'