@usirin/spellbook

Type-safe API surfaces that work across process boundaries.

Overview

Spellbook lets you create type-safe APIs with full validation and error handling. It provides a consistent way to define your API surface once and use it anywhere.

• Type-Safe: End-to-end TypeScript type safety from definition to usage
• Validated: Schema validation with any Standard Schema compatible library
• Composable: Build complex APIs from simple, reusable operations
• Consistent: Standard patterns for defining and consuming APIs
• Context-Aware: Share context across API operations

Installation

npm install @usirin/spellbook   # npm
yarn add @usirin/spellbook      # yarn
pnpm add @usirin/spellbook      # pnpm
bun add @usirin/spellbook       # bun

Quick Start: TodoMVC API

Here's how to create a type-safe API for a TodoMVC application:

import { z } from "zod";
import { createSpell, createSpellbook } from "@usirin/spellbook";

// 1. Define your Todo schema
const TodoSchema = z.object({
  id: z.string().uuid(),
  text: z.string().min(1).max(200),
  completed: z.boolean().default(false),
  createdAt: z.string().datetime(),
});

// 2. Define the context shared across all spells
const contextSchema = z.object({
  db: z.any(), // Your database connection
  logger: z.any(), // Logging utilities
});

// 3. Create your spells
const listTodos = createSpell({
  description: "Get all todo items",
  parameters: z.object({}), // No parameters needed to list all
  result: z.object({
    todos: z.array(TodoSchema),
  }),
  context: contextSchema,
  execute: async ({}, { db, logger }) => {
    logger.info(`Listing all todos`);
    // Implementation would query from database
    const todos = [
      { id: "abc-123", text: "Learn Spellbook", completed: true, createdAt: "2023-01-01T12:00:00Z" },
      { id: "def-456", text: "Build TodoMVC API", completed: false, createdAt: "2023-01-02T12:00:00Z" },
    ];

    // Return all todos directly
    return { todos };
  }
});

const createTodo = createSpell({
  description: "Add a new todo item",
  parameters: z.object({
    text: z.string().min(1).max(200),
  }),
  result: TodoSchema,
  context: contextSchema,
  execute: async ({ text }, { db, logger }) => {
    logger.info(`Creating new todo: ${text}`);
    // Implementation would save to database
    return {
      id: crypto.randomUUID(),
      text,
      completed: false,
      createdAt: new Date().toISOString(),
    };
  }
});

// Spells for toggleTodo, deleteTodo, clearCompleted removed for brevity

// 4. Create the shared context instance
const context = {
  db: { /* your database connection */ },
  logger: {
    info: (message) => console.log(`[INFO] ${message}`),
    error: (message) => console.error(`[ERROR] ${message}`)
  }
};

// 5. Create your API with context
const todoAPI = createSpellbook({
  listTodos,     // Use camelCase keys
  createTodo,
}, context);

// 6. Export the API type for consumers
export type TodoAPI = typeof todoAPI;

async function todoOperations() {
  // Add a new todo with validation
  const newTodo = await todoAPI.createTodo({ // Use camelCase access
    text: "Build an API with Spellbook",
  });
  
  // TypeScript knows the exact shape of newTodo
  console.log(`Created: ${newTodo.text} (${newTodo.id})`);

  // Get all todos
  const { todos } = await todoAPI.listTodos({}); // Use camelCase access, no filter

  console.log(`Fetched ${todos.length} todos.`);

  // Examples for toggle, delete, validation removed for brevity
}

Your API can be used in any JS/TS environment - frontend frameworks like React, Vue or Angular, or backend environments like Node.js, Deno, or Bun.

Core Concepts

Spells

A spell is a single API operation with parameters, result schema, context, and implementation:

const getUserSpell = createSpell({
  description: "Get user by ID",
  parameters: z.object({
    id: z.string().uuid(),
  }),
  result: z.object({
    id: z.string().uuid(),
    username: z.string(),
    email: z.string().email(),
    profile: z.object({
      fullName: z.string(),
      avatarUrl: z.string().url().optional(),
    }),
  }),
  context: z.object({
    db: z.any(),
    authManager: z.any()
  }),
  execute: async ({ id }, { db, authManager }) => {
    // Implementation would fetch user from database
    return {
      id,
      username: "johndoe",
      email: "[email protected]",
      profile: {
        fullName: "John Doe",
        avatarUrl: "https://example.com/avatar.jpg",
      },
    };
  }
});

Key aspects of a spell:

• Description: Human-readable description of what the operation does
• Parameters: Input schema with validation rules
• Result: Output schema defining the expected return type
• Context: Shared resources and dependencies required by the spell
• Execute: Implementation function that performs the operation

Context Handling

Spellbook provides a robust system for managing shared context across your API:

// Define context schema shared by multiple spells
const apiContext = z.object({
  db: z.any(),
  logger: z.any(),
  config: z.object({
    apiVersion: z.string(),
    maxItems: z.number()
  })
});

// Create spells with the shared context
const listItems = createSpell({
  // ...other properties
  context: apiContext,
  execute: async (params, { db, logger, config }) => {
    logger.info(`Listing items with max: ${config.maxItems}`);
    // Implementation
  }
});

// Create a context instance with actual dependencies
const contextInstance = {
  db: new Database(),
  logger: new Logger(),
  config: {
    apiVersion: "v1",
    maxItems: 100
  }
};

// Create a spellbook with the context
const api = createSpellbook({
  listItems,
  // ...other spells
}, contextInstance);

The context is:

• Type-safe: TypeScript infers and validates the context structure
• Automatic: Provided to each spell without manually passing it
• Validated: Context validation happens at runtime
• Shared: Reuse the same dependencies across operations

Spellbooks

A spellbook is a collection of related spells forming a complete API surface with shared context:

const userAPI = createSpellbook({
  getUser: getUserSpell,
  createUser: createUserSpell,
  updateUser: updateUserSpell,
  deleteUser: deleteUserSpell,
}, contextInstance);

Spellbooks allow you to:

• Group related operations
• Share context across operations
• Export a single API type for consumers
• Provide a unified interface for execution

Schema Validation

Spellbook leverages Standard Schema for validation, supporting multiple validation libraries:

// With Zod
import { z } from "zod";
const zodSpell = createSpell({
  parameters: z.object({ email: z.string().email() }),
  // ...
});

// With Valibot
import * as v from "valibot";
const valibotSpell = createSpell({
  parameters: v.object({ email: v.string([v.email()]) }),
  // ...
});

Benefits of Standard Schema integration:

• Use your preferred validation library
• Full type inference for parameters and results
• Runtime validation for both inputs and outputs, handled automatically within the spell's execute method
• Consistent error handling

This type system enables:

• Complete inference of parameter and result types
• Automatic derivation of context types
• Type-safe API consumption

License

MIT