Uklad

Framework for Yandex Cloud Functions with TypeScript and Zod validation.

Features

• ✅ Type-safe - Full TypeScript support with Zod schemas
• ✅ Automatic validation - Input/output validation through Zod
• ✅ Auto-generated documentation - Beautiful HTML docs from schemas
• ✅ CORS support - Built-in CORS handling
• ✅ JSON Schema compatible - Automatic conversion from Zod to JSON Schema

Installation

npm install uklad

Quick Start

See full example in examples/calculator.ts

import { Action, ActionDispatcher } from "uklad";
import { z } from "zod";

// Define schemas
const inputSchema = z.object({
  name: z.string().min(1),
  age: z.number().min(0).max(150),
});

const outputSchema = z.object({
  message: z.string(),
  timestamp: z.number(),
});

// Create action
const greetAction = new Action({
  name: "Greet User",
  code: "greet",
  description: "Greets a user by name and age",
  inputSchema,
  outputSchema,
  handler: async (payload, event) => {
    return {
      message: `Hello, ${payload.name}! You are ${payload.age} years old.`,
      timestamp: Date.now(),
    };
  },
});

// Create dispatcher
const dispatcher = new ActionDispatcher({
  title: "My API",
  description: "API with auto-generated documentation",
  cors: true,
  allowedOrigins: ["*"],
  actions: {
    greet: greetAction,
  },
});

// Export for Yandex Cloud Functions
export const handler = dispatcher.handler;

Examples

Check the examples/ directory for complete working examples:

• calculator.ts - Mathematical calculator with multiple operations, precision control, and rounding modes

To run an example:

npx tsx examples/calculator.ts

Development

Build

Build the project to generate JavaScript and TypeScript declaration files:

npm run build

This will:

• Compile TypeScript to JavaScript (ES modules)
• Generate .d.ts type declaration files
• Generate source maps for debugging
• Output everything to dist/ directory

Clean Build

Remove the dist/ directory and rebuild:

npm run build:clean

Project Structure

uklad/
├── src/              # TypeScript source files
│   ├── action.ts
│   ├── actionDispatcher.ts
│   ├── index.ts
│   ├── interfaces.ts
│   └── docsGen/      # Documentation generator
├── dist/             # Compiled JavaScript + .d.ts files (generated)
├── package.json
└── tsconfig.json

API Reference

Action

Create a new action with Zod schemas:

const action = new Action({
  name: string;           // Display name
  code: string;           // Unique identifier
  description?: string;   // Optional description
  inputSchema: ZodObject; // Zod schema for input
  outputSchema: ZodObject;// Zod schema for output
  handler: Function;      // Handler function
});

ActionDispatcher

Create a dispatcher to handle HTTP requests:

const dispatcher = new ActionDispatcher({
  title: string;                  // API title
  description?: string;           // API description
  cors: boolean;                  // Enable CORS
  allowedOrigins?: string[];      // CORS origins
  allowedHeaders?: string[];      // CORS headers
  actions: Record<string, Action>;// Actions map
});

HTTP Methods

• GET - Returns auto-generated HTML documentation
• POST - Executes actions with JSON body: { action: "code", payload: {...} }
• OPTIONS - CORS preflight (if CORS enabled)

Documentation

When you send a GET request to your function endpoint, you'll see auto-generated HTML documentation with:

• All available actions
• Input/output schemas with constraints
• Examples with cURL commands
• Interactive copy-to-clipboard for code snippets

TypeScript Support

The library exports full TypeScript types:

import type { 
  Action, 
  ActionDispatcher,
  YFunctionEvent,
  YFunctionContext 
} from "uklad";

License

MIT © iMkhl