Skip to content

packages.mdx

Latest commit

 

History

History
890 lines (593 loc) · 32.5 KB

packages.mdx

File metadata and controls

890 lines (593 loc) · 32.5 KB
Raw
title Package Reference
description Complete reference of all ObjectStack packages in the monorepo

Package Reference

ObjectStack is distributed as a monorepo containing ~75 package manifests organized into core runtime, client SDKs, framework adapters, drivers, plugins, connectors, triggers, and platform services.

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

Package Overview

Category Count Description
Core runtime 11 spec, core, runtime, types, metadata, metadata-core, metadata-fs, objectql, rest, formula, platform-objects
Client / DX 5 client, client-react, cli, create-objectstack, vscode-objectstack
Framework adapters 7 Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit
Drivers 4 driver-memory, driver-sql, driver-sqlite-wasm, driver-mongodb
Plugins 18 Auth, security, audit, org-scoping, approvals, sharing, email, webhooks, reports, Hono/MCP servers, MSW/dev, record-change & schedule triggers, knowledge, and embedders
Connectors 4 connector-rest, connector-mcp, connector-openapi, connector-slack
Triggers 3 trigger-api, trigger-record-change, trigger-schedule
Platform services 17 AI, Analytics, Automation, Cache, Cluster, Datasource, Feed, I18n, Job, Knowledge, Messaging, Package, Queue, Realtime, Settings, Storage
Other ~6 mcp, console, cloud-connection, observability, app templates, and tooling

Total: ~75 package manifests. Counts drift as packages are added — run find packages -name package.json -not -path '*/node_modules/*' for the exact current set.

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.

Protocol Domains (subpath imports):

The package does not export schemas from the root; import the domain you need via its subpath, e.g. import * as Data from '@objectstack/spec/data'.

  • @objectstack/spec/data - Data protocol schemas (Field, Object, Query, etc.)
  • @objectstack/spec/ui - UI protocol schemas (View, App, Dashboard, etc.)
  • @objectstack/spec/system - System protocol schemas (Manifest, Plugin, Events, Auth config, etc.)
  • @objectstack/spec/identity - Identity & authentication schemas
  • @objectstack/spec/security - Permission and security schemas
  • @objectstack/spec/ai - AI protocol schemas (Agent, RAG Pipeline, etc.)
  • @objectstack/spec/api - API protocol schemas (Contract, Endpoint, etc.)
  • @objectstack/spec/automation - Automation protocol schemas (Flow, Workflow, etc.)
  • @objectstack/spec/integration - Integration protocol schemas
  • @objectstack/spec/contracts - Service contract interfaces
  • @objectstack/spec/kernel - Kernel protocol schemas
  • @objectstack/spec/shared - Shared utilities and identifiers
  • Additional subpaths: studio, cloud, qa

Protocol Count: Hundreds of Zod schemas across these domains — the set grows over time, so refer to the Protocol Reference for the current catalog.

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:

Category Commands
Development init, dev, serve
Build & Validate compile, validate, info
Scaffolding generate (alias: g), create
Quality test, doctor, lint
Publishing & Registry build, publish, register, rollback, login, logout, whoami
Inspection diff, explain
Command groups cloud, data, datasource, environments, i18n, meta, package, plugin

This is a representative list; run os --help for the authoritative set of commands and subcommands.

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:
    • MemoryLoader - In-memory metadata source
    • RemoteLoader - Loads metadata from a remote endpoint
    • DatabaseLoader - Loads metadata persisted in the database
  • 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/metadata-core

Description: Metadata Repository contracts (ADR-0008) — types, canonicalization, errors, and the MetadataRepository interface.

Purpose: The shared contract layer the metadata system and its storage backends implement.

Use Cases: Building custom metadata repositories, integrating with the metadata system.

Implementation Status: ✅ IMPLEMENTED

@objectstack/metadata-fs

Description: FileSystemRepository — a Node-only MetadataRepository implementation backed by JSON files and a JSONL change log (ADR-0008).

Purpose: Persists metadata on the filesystem with an append-only change history.

Use Cases: Local development, file-based metadata storage, change auditing.

Implementation Status: ✅ IMPLEMENTED

@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

The open edition ships the Hono adapter. For another framework, build a thin adapter on the public HttpDispatcher API — the previous Express / Fastify / Next.js / NestJS / Nuxt / SvelteKit adapters were removed in 11 and can be vendored out-of-tree.

@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

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 & Bulk Operations: create, read, update, delete, find, plus bulk insert/update/delete
  • Mingo Query Engine: MongoDB-compatible filtering, projection, and distinct values
  • Aggregation Pipeline: $match, $group, $sort, $project, $unwind, and an IAnalyticsService implementation (memory-analytics)
  • Sorting & Pagination: orderBy sorting with offset-based pagination
  • Snapshot Transactions: beginTransaction / commit / rollback (capability flag transactions: true)
  • Health Checks: Built-in health monitoring
  • Array & JSON Fields: Support for complex field types

Limitations:

  • ⚠️ Non-persistent — all data is held in memory and lost on restart
  • ⚠️ No savepoints within a transaction (savepoints: false)

Use Cases:

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

Status: ✅ Reference implementation for driver developers

Implementation Status: ✅ FULLY IMPLEMENTED (in-memory) - Mingo-backed filtering, aggregation, sorting, and snapshot transactions; non-persistent

@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-auth

Description: Authentication & Identity Plugin for ObjectStack

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

Key Features:

  • better-auth Integration: Wires better-auth's server-side authentication pipeline (sign-up/sign-in, sessions, tokens)
  • Plugin Lifecycle: Full init/start/destroy lifecycle implementation
  • Service Registration: Registers auth service in ObjectKernel
  • HTTP Routes: /api/v1/auth/* endpoints via IHttpServer, plus a /set-initial-password route
  • Configuration Support: Uses AuthConfig schema from @objectstack/spec/system
  • OAuth Provider Support: Configuration for Google, GitHub, Microsoft, etc.
  • ObjectQL Adapter: Persists users/sessions through ObjectQL (no separate ORM required)
  • Password Hashing: Cryptographic password hashing via @noble/hashes
  • 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

Implementation Status: ✅ FULLY IMPLEMENTED - Shipped better-auth integration with an ObjectQL persistence adapter, password hashing, and session/token management

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-audit

Description: Audit Plugin for ObjectStack — system audit log object and audit trail.

Key Features: Records create/update/delete activity into a system audit-log object for compliance and forensics.

Use Cases: Compliance audit trails, change tracking, security investigations.

Implementation Status: ✅ IMPLEMENTED

@objectstack/plugin-org-scoping

Description: Organization-Scoping Plugin for ObjectStack — row-level organization isolation.

Key Features: Per-org row-level isolation, per-org seed replay, default-org bootstrap.

Use Cases: Multi-tenant data isolation, organization-scoped applications.

Implementation Status: ✅ IMPLEMENTED

@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

@objectstack/driver-mongodb

Description: MongoDB driver for ObjectQL

Purpose: Persist objects in MongoDB with native document semantics while still going through the ObjectQL protocol.

Use Cases: Existing MongoDB infrastructure, document-shaped data, hybrid relational/document deployments.

Implementation Status: ⚠️ IN PROGRESS

@objectstack/plugin-approvals

Description: Contributes the approval flow node (ADR-0019) — an approval rides the one automation engine as a durable-pause node, backed by sys_approval_request / sys_approval_action. There is no separate approval-process engine.

Key Features: Approver resolution, first_response / unanimous behavior, record lock, status mirror, per-node SLA escalation, audit trail; multi-step review is successive approval nodes on the flow graph.

Use Cases: Expense, quote, contract, and any workflow requiring human sign-off.

Implementation Status: ✅ IMPLEMENTED

@objectstack/plugin-sharing

Description: Record-level sharing engine for collaborative access.

Key Features: Manual shares, sharing rules, team-based access, sys_record_share table, integration with plugin-security.

Use Cases: Granting per-record access beyond static RBAC, Salesforce-style sharing.

Implementation Status: ✅ IMPLEMENTED

@objectstack/plugin-email

Description: Outbound email channel for ObjectStack flows and notifications.

Key Features: Provider adapters (SMTP, transactional), MJML templates, delivery tracking, retries.

Use Cases: Transactional email, workflow notifications, approval requests.

Implementation Status: ✅ IMPLEMENTED

@objectstack/plugin-webhooks

Description: Outbound HTTP webhook delivery for ObjectStack events.

Key Features: Subscriptions, signed payloads, exponential-backoff retries, delivery logs.

Use Cases: Integrating ObjectStack with external systems (Zapier-style, ETL pipelines, customer integrations).

Implementation Status: ✅ IMPLEMENTED

@objectstack/plugin-reports

Description: Metadata-driven report rendering and scheduling.

Key Features: Tabular and aggregate reports, scheduled delivery, multi-format export (CSV/XLSX/PDF).

Use Cases: Operational reporting on top of business objects without writing custom queries.

Implementation Status: ✅ IMPLEMENTED

@objectstack/service-messaging

Description: Notification and messaging pipeline service.

Purpose: Provides the single notification ingress, delivery outbox, in-app materialization, preferences, templates, quiet-hours, and digest collapse.

Use Cases: Flow notify nodes, collaboration mentions, assignment notifications, inbox messages, email delivery, and future channel plugins.

Implementation Status: ✅ IMPLEMENTED

@objectstack/service-settings

Description: Hierarchical, validated application settings.

Key Features: Per-org / per-user settings, Zod-validated namespaces, default fallbacks, runtime override.

Use Cases: Feature flags, tenant configuration, user preferences.

Implementation Status: ✅ IMPLEMENTED

@objectstack/formula

Description: Shared CEL formula compiler and runtime.

Purpose: One expression language across validation hooks, predicates, formula fields, conditions, and dynamic seed values. See Formula skill.

Use Cases: Anywhere metadata references a CEL expression (F\`, P``, cel```).

Implementation Status: ✅ IMPLEMENTED

@objectstack/platform-objects

Description: Canonical sys_* platform objects bundled with every ObjectOS runtime.

Purpose: Standard system tables — users, sessions, audit logs, approvals, sharing, settings — so applications never redefine identity, audit, or governance primitives.

Use Cases: Always loaded by the runtime; apps reference these via lookups.

Implementation Status: ✅ IMPLEMENTED

Connectors

Connectors register concrete request/action handlers on the automation engine's connector registry, letting flows call external systems (ADR-0018 Addendum, ADR-0022/0023/0024).

@objectstack/connector-rest

Description: Generic REST connector — the reference concrete connector that registers a request action on the connector registry.

Use Cases: Calling arbitrary REST APIs from flows.

Implementation Status: ✅ IMPLEMENTED

@objectstack/connector-openapi

Description: OpenAPI 3.x connector generator — turns a declarative OpenAPI document into connector actions, with a self-contained static-auth HTTP transport.

Use Cases: Integrating any OpenAPI-described service as flow actions.

Implementation Status: ✅ IMPLEMENTED

@objectstack/connector-mcp

Description: Model Context Protocol (MCP) connector — turns any MCP server's tools into a connector's actions on the automation engine.

Use Cases: Exposing MCP-server tools to flows and agents.

Implementation Status: ✅ IMPLEMENTED

@objectstack/connector-slack

Description: Slack Web API connector — registers chat.postMessage / chat.update / call actions on the connector registry.

Use Cases: Posting Slack messages and triggering Slack calls from flows.

Implementation Status: ✅ IMPLEMENTED

Triggers

Trigger packages auto-launch flows in response to events (ADR-0018, ADR-0041).

@objectstack/trigger-record-change

Description: Record-change flow trigger — auto-launches flows on object insert/update/delete via ObjectQL lifecycle hooks.

Use Cases: Event-driven automation reacting to data changes.

Implementation Status: ✅ IMPLEMENTED

@objectstack/trigger-schedule

Description: Schedule flow trigger — auto-launches flows on a cron/interval/once schedule via the IJobService.

Use Cases: Scheduled and recurring automation.

Implementation Status: ✅ IMPLEMENTED

@objectstack/trigger-api

Description: Inbound HTTP/webhook flow trigger — per-flow HMAC-verified endpoints with queue-backed ingestion.

Use Cases: Launching flows from external webhooks and inbound HTTP calls.

Implementation Status: ✅ IMPLEMENTED

Tools

@objectstack/mcp

Description: ObjectStack as an MCP server — exposes your app's objects (and AI tools) over the Model Context Protocol (stdio + Streamable HTTP).

Purpose: Lets MCP clients (and AI agents) discover and operate on ObjectStack data and tools.

Use Cases: Exposing an ObjectStack app to AI assistants and MCP-aware tooling.

Implementation Status: ✅ IMPLEMENTED

@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)
    │               └─→ @objectstack/hono (Hono adapter)
    └─→ @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-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:

Package Version Node.js TypeScript React (for client-react)
1.0.x ≥18.0.0 ≥5.3.0 ≥18.0.0

Next Steps