Package Reference

ObjectStack is distributed as a monorepo containing 25 packages organized into core packages, adapters, and plugins.

Note for AI Agents: Each package's README.md contains a specific "AI Development Context" section describing its architectural role and usage rules.

Package Overview

Total: 25 packages

Core Packages

@objectstack/spec

Description: ObjectStack Protocol & Specification - TypeScript Interfaces, JSON Schemas, and Convention Configurations

Purpose: The foundational package containing all protocol definitions and schemas. This is the "DNA" of ObjectStack.

Key Exports:

• Data - Data protocol schemas (Field, Object, Query, etc.)
• UI - UI protocol schemas (View, App, Dashboard, etc.)
• System - System protocol schemas (Manifest, Plugin, Events, etc.)
• AI - AI protocol schemas (Agent, RAG Pipeline, etc.)
• API - API protocol schemas (Contract, Endpoint, etc.)
• Automation - Automation protocol schemas (Flow, Workflow, etc.)
• Auth - Authentication protocol schemas
• Permission - Permission protocol schemas
• Hub - Hub protocol schemas
• Integration - Integration protocol schemas
• Shared - Shared utilities and identifiers

Protocol Count: 175 Zod schemas

Learn more: Protocol Reference

@objectstack/core

Description: Microkernel Core for ObjectStack

Purpose: Provides the runtime foundation for ObjectStack, including the plugin system, service registry, and logging infrastructure.

Key Features:

• ObjectKernel: Plugin-based microkernel with dependency injection
• Plugin Lifecycle: Init → Start → Destroy with topological dependency resolution
• Service Registry: Dependency injection (registerService, getService)
• Hook/Event System: Inter-plugin communication (beforeFind, afterInsert, etc.)
• Security: PluginConfigValidator, PluginSignatureVerifier, PluginPermissionEnforcer
• Logging: Cross-platform logger (browser + server) with multiple formats
• API Registry: Central API registry for dynamic endpoint management
• QA Framework: Testing framework with HTTP adapter support

Use Cases:

• Building custom ObjectStack runtimes
• Creating plugin-based architectures
• Implementing microkernel patterns

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

@objectstack/runtime

Description: ObjectStack Server Runtime & REST API Engine

Purpose: The main server runtime that provides HTTP endpoints and REST API generation.

Key Features:

• RestServer: Auto-generates RESTful CRUD endpoints from object schemas
• Route Management: Centralized route registration and middleware chain management
• HTTP Server: Implements IHttpServer interface (adapter pattern)
• Endpoint Generation: Configuration-driven CRUD API (GET/POST/PATCH/DELETE)
• Batch Operations: /createMany, /updateMany, /deleteMany, /batch endpoints
• Metadata Endpoints: /meta, /meta/{type}, /meta/{type}/{name}
• Discovery: /api/v1 API discovery endpoint
• HTTP Caching: ETag, Last-Modified headers support
• Path Transformations: plural, kebab-case, camelCase
• Plugin Adapters: AppPlugin, DriverPlugin for kernel integration

Use Cases:

• Running ObjectStack server applications
• Auto-generating REST APIs from metadata
• Building production API servers

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

@objectstack/objectql

Description: Isomorphic ObjectQL Engine & Protocol Implementation

Purpose: Standalone ObjectQL query engine that implements the ObjectStack protocol and can run in any JavaScript environment (Node.js, browsers, edge).

Key Features:

• ObjectQL Engine: Implements IDataEngine interface
  • Query operations: find, insert, update, delete, count
  • Hook system: beforeFind, afterFind, beforeInsert, afterInsert, etc.
  • Driver management: registerDriver, getDriver
• SchemaRegistry: Central metadata registry
  • registerObject, registerApp, registerMetadata
  • getObject, getItem, listItems, getRegisteredTypes
• ObjectStackProtocolImplementation: Full ObjectStackProtocol implementation
  • Discovery: getDiscovery()
  • Metadata: getMetaTypes(), getMetaItems(type), getMetaItem(type, name)
  • UI Views: getUiView(object, type)
  • CRUD operations: findData, getData, createData, updateData, deleteData
  • Batch operations: batchUpdate, batchDelete
  • HTTP Caching: ETag-based caching with 304 Not Modified support
• Isomorphic: Works in Node.js, browsers, and edge environments
• Driver-agnostic: Query interface abstraction

Use Cases:

• Client-side data querying
• Edge function data access
• Serverless query execution
• Implementing ObjectStack protocol

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

@objectstack/client

Description: Official TypeScript Client SDK for ObjectStack Protocol

Purpose: Type-safe client library for interacting with ObjectStack REST APIs.

Key Features:

• Discovery API: connect() → /api/v1 endpoint
• Metadata API:
  • meta.getTypes(), meta.getItems(type), meta.getItem(type, name)
  • meta.getObject(name) - Object definitions
  • meta.getView(object, type) - UI schemas with ETag caching
  • meta.getCached() - Conditional 304 Not Modified support
• Data Operations (CRUD):
  • data.query(object, ast) - Advanced AST queries via POST
  • data.find(object, options) - Simplified queries with filters/sort/select
  • data.get(id), data.create(), data.update(), data.delete()
  • data.createMany(), data.updateMany(), data.deleteMany()
  • data.batch() - Atomic batch operations
• Query Builder: QueryBuilder, FilterBuilder, createQuery(), createFilter()
• Error Handling: StandardError with code, category, httpStatus, retryable flag
• Authentication: Bearer token support via token config
• Type Safety: Full TypeScript types from spec schemas

Use Cases:

• Building frontend applications
• Consuming ObjectStack APIs
• Type-safe data fetching

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

@objectstack/client-react

Description: React hooks for ObjectStack Client SDK

Purpose: React-specific hooks and components for ObjectStack integration.

Requirements: React 18+

Key Features:

• Context & Provider:
  • ObjectStackProvider - Makes client available to all React components
  • useClient() - Access ObjectStackClient instance
• Data Hooks:
  • useQuery<T>(object, options) - Query with caching, refetch, enabled flag
  • useMutation<TData, TVariables>(object, options) - Create/Update/Delete with optimistic updates
  • usePagination<T>(object, options) - Paginated queries with next/previous helpers
  • useInfiniteQuery<T>(object, options) - Infinite scroll support
• Metadata Hooks:
  • useObject(name) - Get object schema
  • useView(object, type) - Get list/form UI schema
  • useFields(object) - Get field definitions
  • useMetadata<T>(type, name, options) - Generic metadata access
• Automatic Caching: Built-in cache management
• TypeScript Support: Full type inference from schemas

Use Cases:

• Building React applications
• Real-time data synchronization
• Form handling with ObjectStack data

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

@objectstack/cli

Description: Command Line Interface for ObjectStack Development

Purpose: Complete developer tools for scaffolding, building, validating, and managing ObjectStack applications.

Commands:

Key Features:

• Project Initialization: os init creates projects from templates (app, plugin, empty)
• Code Generation: os generate scaffolds objects, views, actions, flows, agents, dashboards, apps
• Schema Validation: os validate checks config against ObjectStackDefinitionSchema with --strict and --json modes
• Metadata Introspection: os info displays metadata summary without compilation
• Config Compilation: os compile bundles config to deployable JSON artifact with metadata stats
• Development Server: os serve --dev with auto-plugin detection, port conflict resolution
• CI/CD Integration: All output commands support --json for machine-readable output
• Shared Utilities: Unified formatting, config loading, and error handling across all commands
• Monorepo Support: pnpm workspace integration via os dev
• Environment Diagnostics: os doctor validates Node.js, pnpm, TypeScript, dependencies

Use Cases:

• Project scaffolding and initialization
• Metadata generation and validation
• Development workflows with hot-reload
• CI/CD pipeline integration
• Environment diagnostics

Learn more: CLI Guide

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

@objectstack/metadata

Description: Metadata Management System

Purpose: Provides metadata loading, saving, watching, and caching capabilities for ObjectStack.

Key Features:

• MetadataManager: Orchestrates loading, saving, watching, caching metadata
• MetadataPlugin: Kernel plugin adapter for metadata system
• Loaders:
  • FilesystemLoader - Loads metadata from disk (rootDir)
• Serializers:
  • JSONSerializer - .json files
  • YAMLSerializer - .yaml files
  • TypeScriptSerializer - .ts files (also handles JavaScript)
• Watch Mode: File system notifications with chokidar
• Auto-detection: Format auto-detection for load/save
• Caching: Metadata caching with statistics
• Migration: Metadata migration system

Use Cases:

• Loading metadata from multiple formats
• Hot-reloading metadata during development
• Managing metadata lifecycle

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

@objectstack/types

Description: Shared Runtime Type Definitions

Purpose: Provides core TypeScript interfaces used across all ObjectStack packages at runtime.

Key Exports:

• IKernel - Kernel interface
• RuntimePlugin - Plugin base interface
• RuntimeContext - Runtime context type
• Other shared runtime types

Use Cases:

• Building plugins that need kernel interfaces
• Implementing custom runtimes
• Type-safe cross-package integration

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

Framework Adapters

Framework adapters that bridge ObjectStack's unified HttpDispatcher to specific HTTP frameworks.

@objectstack/express

Description: Express Framework Adapter

Purpose: Converts ObjectStack's standard HTTP dispatch interface to Express routes.

Key Features:

• Maps standard routes to Express handlers
• Supports Express v5 middleware chain
• Bearer token authentication via AuthPlugin

Implementation Status: ✅ FULLY IMPLEMENTED

@objectstack/fastify

Description: Fastify Framework Adapter

Purpose: Converts ObjectStack's standard HTTP dispatch interface to Fastify routes.

Key Features:

• Maps standard routes to Fastify handlers
• Supports Fastify v5 plugin system
• Bearer token authentication via AuthPlugin

Implementation Status: ✅ FULLY IMPLEMENTED

@objectstack/hono

Description: Hono Framework Adapter

Purpose: Converts ObjectStack's standard HTTP dispatch interface to Hono routes.

Key Features:

• Maps standard routes to Hono handlers
• Supports Hono's middleware chain
• Works with Node.js, Bun, Deno, Cloudflare Workers

Implementation Status: ✅ FULLY IMPLEMENTED

@objectstack/nestjs

Description: NestJS Framework Adapter

Purpose: Integrates ObjectStack as a NestJS module with automatic controller generation.

Key Features:

• NestJS module registration
• Automatic controller generation from metadata
• Dependency injection integration

Implementation Status: 🔄 IN PROGRESS

@objectstack/nextjs

Description: Next.js Framework Adapter

Purpose: Integrates ObjectStack with Next.js App Router and API routes.

Key Features:

• App Router integration
• API route handlers
• Server-side data access and server actions

Implementation Status: ✅ FULLY IMPLEMENTED

@objectstack/nuxt

Description: Nuxt Framework Adapter

Purpose: Integrates ObjectStack with Nuxt server routes via h3.

Key Features:

• h3 event handler integration
• Nitro server route support
• Bearer token authentication via AuthPlugin

Implementation Status: ✅ FULLY IMPLEMENTED

@objectstack/sveltekit

Description: SvelteKit Framework Adapter

Purpose: Integrates ObjectStack with SvelteKit hooks and server routes.

Key Features:

• SvelteKit handle hook integration
• Server route handlers
• Bearer token authentication via AuthPlugin

Implementation Status: ✅ FULLY IMPLEMENTED

Plugin Packages

@objectstack/driver-memory

Description: In-Memory Driver for ObjectStack (Reference Implementation)

Purpose: A reference in-memory database driver used for testing and development.

Key Features:

• CRUD Operations: create, read, update, delete, find
• Pagination Support: Offset-based pagination
• Health Checks: Built-in health monitoring
• Array & JSON Fields: Support for complex field types
• Simple Implementation: No external dependencies

Limitations:

• ⚠️ No transaction support
• ⚠️ No advanced filtering (basic only)
• ⚠️ No aggregations
• ⚠️ No sorting
• ⚠️ No window functions or subqueries

Use Cases:

• Testing ObjectStack applications
• Development without database setup
• Understanding driver implementation patterns
• Quick prototyping

Status: ✅ Reference implementation for driver developers

Implementation Status: ⚠️ PARTIALLY IMPLEMENTED - Basic CRUD only, suitable for testing

@objectstack/plugin-hono-server

Description: Hono HTTP Server Adapter for ObjectStack Runtime

Purpose: Production HTTP server adapter using the Hono framework.

Key Features:

• Standard Runtime: Uses the unified HttpDispatcher and standard Hono adapter via @objectstack/hono
• Full Protocol Support: Automatically provides all ObjectStack Runtime endpoints (Auth, Data, Metadata, Storage)
• Fast HTTP Server: Uses Hono framework for high performance
• Port Configuration: Configurable port with conflict detection
• Static File Serving: Built-in static file support
• API Registry Integration: Centralized endpoint management
• Metadata Caching: ETag-based caching for metadata endpoints
• Edge Runtime Compatible: Can run on edge environments

Use Cases:

• Production REST API deployment
• Edge function hosting (Cloudflare Workers, Deno Deploy, etc.)
• Serverless deployments
• Local development server

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

@objectstack/plugin-msw

Description: Mock Service Worker (MSW) Plugin for ObjectStack Testing

Purpose: Testing plugin that mocks the entire ObjectStack backend in browser/node using the unified Runtime logic.

Key Features:

• Unified Dispatcher: Uses @objectstack/runtime's HttpDispatcher to behave exactly like the real server
• Full Protocol Mocking: Mocks Auth, Metadata, Data, Storage, Analytics, and Automation endpoints
• Browser Testing: High-fidelity backend simulation in browser environments
• Custom Handlers: Support for custom request handlers
• Request Logging: Built-in request/response logging
• Service Worker Based: Uses MSW's service worker approach

Use Cases:

• Unit testing React components
• Integration testing frontend applications
• Browser-based testing without backend
• E2E testing with mocked APIs

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready for testing

@objectstack/plugin-auth

Description: Authentication & Identity Plugin for ObjectStack

Purpose: Provides authentication and identity management services for ObjectStack applications with better-auth integration.

Key Features:

• Plugin Lifecycle: Full init/start/destroy lifecycle implementation
• Service Registration: Registers auth service in ObjectKernel
• HTTP Route Scaffolding: /api/v1/auth/* endpoints via IHttpServer
• Configuration Support: Uses AuthConfig schema from @objectstack/spec/system
• OAuth Provider Support: Configuration for Google, GitHub, Microsoft, etc.
• ObjectQL Database: Uses ObjectQL for data persistence (no ORM required)
• Advanced Features: Organization/team support, 2FA, passkeys, magic links

API Routes:

• POST /api/v1/auth/sign-in/email - Sign in with email and password
• POST /api/v1/auth/sign-up/email - Register new user
• POST /api/v1/auth/sign-out - Sign out
• GET /api/v1/auth/get-session - Get current session

Use Cases:

• Adding authentication to ObjectStack applications
• Multi-tenant applications with organization support
• OAuth social login integration
• Secure session management

Status: 🟡 IN DEVELOPMENT - Structure complete, authentication logic planned

Implementation Status: ⚠️ PARTIALLY IMPLEMENTED - Plugin structure and routes scaffolded, authentication logic to be added with better-auth integration

Learn more: Auth Config Reference

@objectstack/plugin-security

Description: Security Plugin for ObjectStack — RBAC, RLS, and Field-Level Security Runtime

Purpose: Provides runtime security enforcement for ObjectStack applications, including role-based access control, row-level security, and field-level masking.

Key Features:

• RBAC Permission Evaluator: Checks object-level CRUD permissions per user role
• Row-Level Security (RLS): Compiles policy expressions into ObjectQL query filters
• Field-Level Masking: Strips non-readable fields from query results
• ObjectQL Middleware Integration: Transparent security enforcement on every operation
• Most-Permissive Merging: If any role grants access, the operation is allowed

Security Chain (4 steps):

1. Resolve permission sets from user roles
2. Check CRUD permissions on objects
3. Inject RLS filters into queries
4. Mask restricted fields in results

Use Cases:

• Multi-tenant applications with role-based access
• Data isolation between teams/organizations
• Compliance requirements (field masking for sensitive data)

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

@objectstack/plugin-dev

Description: Development Mode Plugin for ObjectStack

Purpose: Auto-enables all 17+ kernel services with in-memory implementations for a full-featured API development environment.

Key Features:

• Zero Configuration: Single plugin enables entire development stack
• In-Memory Services: All services use in-memory implementations
• Full Protocol Support: Auth, Data, Metadata, Storage, Analytics, and more
• Hot Reload Compatible: Works with os dev for hot-reload workflows

Use Cases:

• Rapid prototyping without database setup
• Local development and testing
• CI/CD pipeline testing

Implementation Status: ✅ FULLY IMPLEMENTED - Development ready

Tools

@objectstack/rest

Description: ObjectStack REST API Server — automatic REST endpoint generation from protocol

Purpose: Turns ObjectStack schema definitions into fully functional CRUD endpoints with zero boilerplate.

Key Features:

• Auto-Generated Endpoints: CRUD routes from object schemas
• Batch Operations: /createMany, /updateMany, /deleteMany, /batch endpoints
• Metadata API: /meta, /meta/{type}, /meta/{type}/{name} for runtime introspection
• Discovery Endpoint: /api/v1 for API self-documentation
• Route Manager: Centralized route registration, grouping, and middleware chain
• HTTP Caching: ETag and Last-Modified header support
• Configurable Paths: Plural, kebab-case, and camelCase path transformations

Use Cases:

• Auto-generating REST APIs from metadata
• Building production API servers
• Custom route management

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

create-objectstack

Description: Create a new ObjectStack project — npx create-objectstack

Purpose: Interactive project scaffolder for quickly creating new ObjectStack projects.

Key Features:

• Interactive Mode: Guided project setup with prompts
• Template Support: full-stack, api-only, plugin templates
• Dependency Installation: Automatic pnpm install (skippable)
• Zero Config: Works out-of-the-box with sensible defaults

Use Cases:

• Starting new ObjectStack projects
• Creating plugin packages
• Scaffolding from templates

Implementation Status: ✅ FULLY IMPLEMENTED - Production ready

objectstack-vscode

Description: ObjectStack Protocol — Autocomplete, validation, and inline diagnostics for .object.ts, .view.ts, and objectstack.config.ts files

Purpose: VSCode extension providing IDE support for ObjectStack protocol development.

Key Features:

• Autocomplete: IntelliSense for ObjectStack schemas
• Validation: Real-time schema validation with error diagnostics
• Protocol Awareness: Understands .object.ts, .view.ts, and config files

Use Cases:

• ObjectStack development in VSCode
• Real-time feedback on schema definitions
• Productivity improvement

Implementation Status: ✅ FULLY IMPLEMENTED

Package Dependencies

Dependency Graph

@objectstack/spec (no dependencies)
    ↓
    ├─→ @objectstack/types (shared runtime interfaces)
    ├─→ @objectstack/core (uses spec contracts)
    ├─→ @objectstack/metadata (uses spec system schemas)
    ├─→ @objectstack/objectql (implements spec protocols)
    │       ↓
    │       └─→ @objectstack/runtime (uses objectql engine)
    │               ↓
    │               ├─→ @objectstack/rest (REST API generation)
    │               ├─→ @objectstack/client (consumes runtime APIs)
    │               │       ↓
    │               │       └─→ @objectstack/client-react (wraps client)
    │               └─→ Adapters:
    │                       ├─→ @objectstack/express (Express routes)
    │                       ├─→ @objectstack/fastify (Fastify routes)
    │                       ├─→ @objectstack/hono (Hono routes)
    │                       ├─→ @objectstack/nestjs (NestJS modules)
    │                       ├─→ @objectstack/nextjs (Next.js routes)
    │                       ├─→ @objectstack/nuxt (Nuxt/h3 routes)
    │                       └─→ @objectstack/sveltekit (SvelteKit hooks)
    └─→ @objectstack/cli (validates against spec schemas)

Plugins (depend on core packages):
    ├─→ @objectstack/driver-memory (implements driver interface)
    ├─→ @objectstack/plugin-hono-server (HTTP server via @objectstack/hono)
    ├─→ @objectstack/plugin-msw (mocks for testing via runtime)
    ├─→ @objectstack/plugin-auth (authentication via better-auth)
    ├─→ @objectstack/plugin-security (RBAC, RLS, field masking)
    └─→ @objectstack/plugin-dev (dev mode, all services in-memory)

Tools:
    ├─→ create-objectstack (project scaffolder)
    └─→ objectstack-vscode (VSCode extension)

Installation

For Application Development:

pnpm add @objectstack/runtime @objectstack/client @objectstack/plugin-hono-server

For React Applications:

pnpm add @objectstack/client-react

For Plugin Development:

pnpm add @objectstack/core @objectstack/spec

For CLI Tools:

pnpm add -D @objectstack/cli
# Or install globally
pnpm add -g @objectstack/cli

Version Compatibility

All packages in the monorepo are versioned together and released simultaneously to ensure compatibility.

Current Version: Check CHANGELOG.md

Compatibility Matrix:

Next Steps