ObjectStackObjectStack

Package Reference

Complete reference of all ObjectStack packages in the monorepo

Package Reference

ObjectStack is distributed as a monorepo containing 16 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

CategoryCountDescription
Core Packages9Essential runtime, protocols, client SDKs, and CLI
Adapter Packages3Framework adapters (Hono, NestJS, Next.js)
Plugin Packages4Drivers, server, and authentication plugins

Total: 16 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: 139 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:

CategoryCommands
Developmentinit, dev, serve
Build & Validatecompile, validate, info
Scaffoldinggenerate (alias: g), create
Qualitytest, doctor

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

Adapter Packages

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

@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

Implementation Status: 🔄 IN PROGRESS

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 plugin structure ready for 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.
  • Advanced Features: Organization/team support, 2FA, passkeys, magic links (planned)
  • Session Management: Configurable session expiry and refresh (planned)

API Routes:

  • POST /api/v1/auth/login - User login
  • POST /api/v1/auth/register - User registration
  • POST /api/v1/auth/logout - User logout
  • GET /api/v1/auth/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

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/client (consumes runtime APIs)
    │               │       ↓
    │               │       └─→ @objectstack/client-react (wraps client)
    │               └─→ Adapters:
    │                       ├─→ @objectstack/hono (Hono routes)
    │                       ├─→ @objectstack/nestjs (NestJS modules)
    │                       └─→ @objectstack/nextjs (Next.js routes)
    └─→ @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)

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:

Package VersionNode.jsTypeScriptReact (for client-react)
1.0.x≥18.0.0≥5.3.0≥18.0.0

Next Steps

Protocol Reference

Explore the 139 protocol schemas

Developer Guide

Build with ObjectStack packages

GitHub Repository

View source code and contribute

On this page

Package ReferencePackage OverviewCore Packages@objectstack/spec@objectstack/core@objectstack/runtime@objectstack/objectql@objectstack/client@objectstack/client-react@objectstack/cli@objectstack/metadata@objectstack/typesAdapter Packages@objectstack/hono@objectstack/nestjs@objectstack/nextjsPlugin Packages@objectstack/driver-memory@objectstack/plugin-hono-server@objectstack/plugin-msw@objectstack/plugin-authPackage DependenciesDependency GraphInstallationVersion CompatibilityNext Steps