ObjectQL

The Standard Protocol for AI Software Generation.

Define your data in JSON/YAML. Run anywhere: Node.js, Browser, Edge. Empower LLMs to build hallucination-free backends.

---

🌐 Introduction

ObjectQL is a universal data protocol and ORM engine designed for the AI Coding Era.

Traditional ORMs (TypeORM, Prisma) are built for humans writing code in IDEs. ObjectQL is built for LLMs generating logic. It uses rigid, declarative JSON/YAML Metadata and a strict JSON-AST Query Protocol to ensure AI Agents generate perfect, hallucination-free database operations.

Why ObjectQL?

• 🤖 AI-Native: Metadata-driven architecture provides the perfect context window for LLMs. No more parsing complex TypeScript classes or guessing SQL syntax.
• 🛡️ Hallucination-Proof: The strict JSON protocol eliminates "imaginary methods" or invalid SQL syntax often generated by AI.
• 🌍 Universal Runtime: The core engine has zero dependencies on Node.js native modules. It runs in Browsers, Cloudflare Workers, and Deno.
• 🔌 Driver Agnostic: Switch between PostgreSQL, MongoDB, SQLite, or even a Remote API without changing your business logic.

---

📦 Architecture

ObjectQL is organized as a Monorepo to ensure modularity and universal compatibility.

Foundation Layer

Package	Environment	Description
@objectql/types	Universal	The Contract. Pure TypeScript interfaces defining the protocol.
@objectql/core	Universal	The Engine. Plugin orchestrator, repository pattern, and kernel factory. Delegates query and optimization logic to dedicated plugins.
@objectql/plugin-query	Universal	Query Plugin. QueryService, QueryBuilder, QueryAnalyzer, and FilterTranslator.
@objectql/plugin-optimizations	Universal	Optimizations Plugin. Connection pooling, query compilation, compiled hooks, lazy metadata loading, and SQL query optimization.
@objectql/plugin-security	Universal	Security Plugin. Comprehensive RBAC, Field-Level Security (FLS), and Row-Level Security (RLS) with AST-level enforcement.
@objectql/plugin-validator	Universal	Validation Plugin. 5-type validation engine: field, cross-field, state machine, unique, and business rule.
@objectql/plugin-formula	Universal	Formula Plugin. Computed fields with JavaScript expressions in a sandboxed evaluator.
@objectql/plugin-workflow	Universal	Workflow Plugin. State machine executor with guards, actions, and compound states.
@objectql/plugin-multitenancy	Universal	Multi-Tenancy Plugin. Automatic tenant isolation via hook-based filter rewriting.
@objectql/plugin-sync	Universal	Sync Plugin. Offline-first sync engine with conflict resolution strategies.
@objectql/edge-adapter	Universal	Edge Adapter. Runtime detection and capability validation for edge environments.
@objectql/platform-node	Node.js	Node.js platform utilities for file system integration, YAML loading, and plugin management.

Driver Layer

Package	Environment	Description
@objectql/driver-sql	Node.js	SQL database driver (PostgreSQL, MySQL, SQLite, SQL Server) via Knex.
@objectql/driver-mongo	Node.js	MongoDB driver with native aggregation pipeline support.
@objectql/driver-memory	Universal	In-Memory Driver. Zero dependencies, perfect for testing and browser apps.
@objectql/driver-fs	Node.js	File system driver with JSON file-based persistent storage.
@objectql/driver-excel	Node.js	Excel file driver for using .xlsx spreadsheets as a data source.
@objectql/driver-redis	Node.js	Redis driver (example/template implementation for key-value stores).
@objectql/sdk	Universal	Remote HTTP Driver. Type-safe client for connecting to ObjectQL servers.
@objectql/driver-sqlite-wasm	Browser	SQLite WASM Driver. Browser-native SQL via WebAssembly + OPFS persistence.
@objectql/driver-pg-wasm	Browser	PostgreSQL WASM Driver. Full PG feature set in the browser via PGlite.

Tools Layer

Package	Environment	Description
@objectql/cli	Node.js	Command-line interface with AI-powered generation, dev server, and project management.
@objectql/create	Node.js	Project scaffolding tool (npm create @objectql@latest).
vscode-objectql	VS Code	Official VS Code extension with IntelliSense, validation, and snippets.

---

⚡ Quick Start

1. Create a New Project

The fastest way to start is using the CLI to scaffold a new project.

# Generate a new project
npm create @objectql@latest my-app

# Choose 'starter' for a complete example or 'hello-world' for minimal setup

2. Install VS Code Extension (Critical 🚨)

For the best experience, install the official extension. It provides Intelligent IntelliSense and Real-time Validation for your YAML models.

• Search for "ObjectQL" in the VS Code Marketplace.
• Or open your new project, and VS Code will recommend it automatically via .vscode/extensions.json.

3. Define Metadata (The "Object")

ObjectQL uses YAML as the source of truth. Create a file src/objects/story.object.yml:

Key Convention (v4.0+): The object name is inferred from the filename - no redundant name: field needed!

# File: story.object.yml
# Object name is automatically inferred as 'story' ✅
label: User Story
fields:
  title:
    type: text
    required: true
    label: Story Title
  status:
    type: select
    options:
      - label: Draft
        value: draft
      - label: Active
        value: active
      - label: Done
        value: done
    defaultValue: draft
  points:
    type: number
    scale: 0
    defaultValue: 1
    label: Story Points

4. Run & Play

Start the development server. ObjectQL will automatically load your YAML files and generate the database schema.

npm run dev

---

🔌 The Driver Ecosystem

ObjectQL isolates the "What" (Query) from the "How" (Execution).

Official Drivers

SQL Driver (@objectql/driver-sql)

• Supports PostgreSQL, MySQL, SQLite, SQL Server.
• Smart Hybrid Mode: Automatically maps defined fields to SQL columns and undefined fields to a _jsonb column. This gives you the speed of SQL with the flexibility of NoSQL.

Mongo Driver (@objectql/driver-mongo)

• Native translation to Aggregation Pipelines.
• High performance for massive datasets.

SDK / Remote Driver (@objectql/sdk)

• The Magic: You can run ObjectQL in the Browser.
• Instead of connecting to a DB, it connects to an ObjectQL Server API.
• The API usage remains exactly the same (repo.find(...)), but it runs over HTTP.

Memory Driver (@objectql/driver-memory)

• Zero dependencies - Pure JavaScript implementation
• Universal - Works in Node.js, Browser, Edge environments
• Perfect for testing, prototyping, and client-side state management
• See Browser Demo for live examples

SQLite WASM Driver (@objectql/driver-sqlite-wasm)

• Browser-native SQL via WebAssembly (~300KB gzip)
• OPFS persistence — GB-scale storage, data survives page refreshes
• Reuses the Knex SQLite dialect — same query compilation as driver-sql
• Perfect for offline-first apps and PWAs

PostgreSQL WASM Driver (@objectql/driver-pg-wasm)

• Full PostgreSQL in the browser via PGlite (~3MB gzip)
• JSONB, full-text search, arrays, range types
• IndexedDB/OPFS persistence
• For apps that need PG-specific features client-side

Browser Support 🌐

ObjectQL runs natively in web browsers with zero backend required! This makes it perfect for:

• 🚀 Rapid Prototyping - Build UIs without server setup
• 📱 Offline-First Apps - PWAs with client-side data via WASM SQL drivers
• 🎓 Educational Tools - Interactive learning experiences
• 🧪 Testing - Browser-based test environments

Try it now: Check out the Browser Example!

// Running ObjectQL in the browser - it's that simple!
import { ObjectQL } from '@objectql/core';
import { MemoryDriver } from '@objectql/driver-memory';

const driver = new MemoryDriver();
const app = new ObjectQL({ datasources: { default: driver } });

// Define object following latest ObjectStack specification
app.registerObject({
  name: 'tasks',  // Required for programmatic registration
  label: 'Tasks',
  fields: {
    title: { 
      type: 'text', 
      required: true,
      label: 'Task Title'
    },
    completed: { 
      type: 'boolean', 
      defaultValue: false,
      label: 'Completed'
    }
  }
});

await app.init();

// Use it just like on the server!
const ctx = app.createContext({ isSystem: true });
const tasks = ctx.object('tasks');
await tasks.create({ title: 'Build awesome app!' });

Extensibility

ObjectQL's driver architecture supports custom database implementations. Potential databases include:

• Key-Value Stores: Redis, Memcached, etcd
• Search Engines: Elasticsearch, OpenSearch, Algolia
• Graph Databases: Neo4j, ArangoDB
• Time-Series: InfluxDB, TimescaleDB
• Cloud Databases: DynamoDB, Firestore, Cosmos DB

Want to add support for your database? Check out:

• Driver Extensibility Guide - Lists potential databases and their implementation complexity
• Implementing Custom Drivers - Step-by-step guide with code examples
• Redis Driver Example - Reference implementation

---

🔍 Query Approaches

ObjectQL supports three distinct query interfaces, each optimized for different scenarios:

• JSON-DSL (Core): AI-friendly protocol, server-side logic, cross-driver compatibility
• REST API: Simple CRUD operations, mobile apps, third-party integrations
• GraphQL: Complex data graphs, modern SPAs, efficient multi-table fetching

Looking for best practices? Check out the Query Best Practices Guide for detailed comparisons, performance strategies, and optimization techniques.

---

🛠️ Developer Tools

VSCode Extension

Enhance your ObjectQL development experience with our official VSCode extension.

Features:

• 🎯 Intelligent IntelliSense for .object.yml, .validation.yml, .permission.yml, .app.yml
• ✅ Real-time JSON Schema validation with inline errors
• 📝 30+ code snippets for objects, fields, validations, hooks, and actions
• ⚡ Quick commands to create new ObjectQL files from templates
• 🎨 Custom file icons and syntax highlighting
• 🔍 Context-aware auto-completion

Installation:

cd packages/tools/vscode-objectql
npm install
npm run compile
npm run package
# Then install the generated .vsix file in VS Code

See packages/tools/vscode-objectql/README.md for detailed documentation.

---

🛠️ Validation & Logic

ObjectQL includes a powerful validation engine that runs universally.

# user.validation.yml
fields:
  age:
    min: 18
    message: "Must be an adult"
  
  # Cross-field validation supported!
  end_date:
    operator: ">"
    compare_to: "start_date"

This validation logic runs:

1. On the Client (Browser): For immediate UI feedback (via Object UI).
2. On the Server: For data integrity security. Write once, validate everywhere.

---

📊 Implementation Status

Current Version: 4.2.0
Overall Completion: ~85%
Protocol Compliance: 85/100 (see Protocol Compliance Report)

Production-Ready Features ✅

ObjectQL has mature, production-ready implementations of core features:

• ✅ Validation System (100%) - Field, cross-field, state machine, uniqueness validation
• ✅ Formula Engine (100%) - Computed fields with JavaScript expressions
• ✅ Hook System (100%) - Complete event lifecycle (before/after create/update/delete/find)
• ✅ Action System (100%) - Custom RPC operations
• ✅ Repository Pattern (100%) - Full CRUD operations
• ✅ Security Plugin (100%) - Comprehensive RBAC, FLS, and RLS with pre-compiled permission checks
• ✅ 7 Database Drivers (100%) - SQL, MongoDB, Memory, FS, Excel, Redis, SDK
• ✅ 3 Protocol Implementations - GraphQL (85%), OData V4 (80%), JSON-RPC 2.0 (90%)
• ✅ CLI Tools (100%) - Complete development lifecycle
• ✅ VSCode Extension (90%) - IntelliSense and validation

Protocol Implementation Status 🌐

Protocol	Compliance	Status	Priority Enhancements
GraphQL	85%	⚠️ Good	Subscriptions, Federation
OData V4	80%	⚠️ Good	$expand, $count, $batch
JSON-RPC 2.0	90%	✅ Excellent	object.count(), action.execute()

📋 See Protocol Compliance Summary for quick reference
📄 See Protocol Compliance Report for comprehensive analysis
🗺️ See Protocol Development Plan for detailed roadmap (中文)

Plugin Ecosystem 🧩

Plugin	Status	Description
@objectql/plugin-workflow	✅ Implemented	Full state machine executor with guards, actions, compound states
@objectql/plugin-multitenancy	✅ Implemented	Automatic tenant isolation via hook-based filter rewriting
@objectql/plugin-sync	✅ Implemented	Offline-first sync with LWW, CRDT, and manual conflict resolution
@objectql/edge-adapter	✅ Implemented	Edge runtime detection and capability validation

Protocol Layer 🌐

Package	Compliance	Status
@objectql/protocol-graphql	85%	⚠️ Good — Subscriptions, Federation planned Q2
@objectql/protocol-odata-v4	80%	⚠️ Good — $expand, $count, $batch planned Q2
@objectql/protocol-json-rpc	90%	✅ Excellent
@objectql/protocol-sync	✅	✅ Sync protocol handler with change logs and checkpoints

Key Documents

• 📋 Implementation Status - Complete feature matrix with detailed status
• 🌐 Protocol Compliance Summary - Quick reference (CN/EN)
• 📊 Protocol Compliance Report - Comprehensive audit (60 pages)
• 🗺️ Protocol Development Plan (中文) - Detailed roadmap (100 pages)
• Roadmap - Long-term vision and milestones (if exists)
• Contributing Guide - How to contribute (if exists)

💡 See IMPLEMENTATION_STATUS.md for a comprehensive breakdown of what's implemented vs. planned.

---

🛠️ Development & Contributing

If you fork or clone the repository to contribute or run examples from source:

1. Setup Workspace

   git clone https://github.com/objectstack-ai/objectql.git
   cd objectql
   corepack enable && corepack prepare pnpm@10.28.2 --activate
   pnpm install

2. Build Packages You must build all packages before running examples or the dev server, as they rely on local workspace builds.

   pnpm build

3. Run Dev Server Start the full-stack development server with all plugins (ObjectQL + Security + GraphQL + OData + JSON-RPC):

   pnpm dev
   # Equivalent to: objectstack serve --dev
   # Starts ObjectStack kernel at http://localhost:5050
   # Loads project-tracker example metadata from objectstack.config.ts

   The dev server is powered by @objectstack/cli (v3.0.0). It reads objectstack.config.ts in the project root, which configures the kernel with all plugins:

   // objectstack.config.ts
   export default {
     metadata: { name: 'objectos', version: '1.0.0' },
     objects: loadObjects(projectTrackerDir),
     plugins: [
       new HonoServerPlugin({ port: 5050 }),
       new ObjectQLPlugin({
         enableRepository: true,
         enableQueryService: true,   // ← uses @objectql/plugin-query internally
         enableValidator: true,
         enableFormulas: true,
         datasources: { default: new MemoryDriver() }
       }),
       new ObjectQLSecurityPlugin({ enableAudit: false }),
       new GraphQLPlugin({ basePath: '/graphql' }),
       new ODataV4Plugin({ basePath: '/odata' }),
       new JSONRPCPlugin({ basePath: '/rpc' }),
     ]
   };

   Available objectstack CLI commands (via @objectstack/cli):

   Command	Description
   objectstack serve --dev	Start dev server (same as pnpm dev)
   objectstack serve	Start production server
   objectstack create	Scaffold a new project
   objectstack doctor	Diagnose environment issues

4. Run Tests

   # Run all tests
   npx vitest run
   
   # Run tests for a specific package
   npx vitest run packages/foundation/core
   
   # Run tests in watch mode
   npx vitest --watch

5. Run Examples

   These examples run as scripts to demonstrate the ObjectQL Core Engine capabilities (Validation, CRUD, Logic Hooks). They use an in-memory database.

   Starter (Project Tracker):

   # Starts the API Server (http://localhost:3000)
   pnpm --filter @objectql/example-project-tracker start
   
   # Note: Sample data (projects.data.yml) is automatically loaded on startup

   Enterprise ERP:

   pnpm --filter @objectql/example-enterprise-erp start
   # Output: Plugin initialization, Employee creation logs, Audit trails

Architecture Note

Since #373, @objectql/core has been decomposed into focused plugin packages:

• @objectql/plugin-query — QueryService, QueryBuilder, QueryAnalyzer, FilterTranslator
• @objectql/plugin-optimizations — Connection pooling, query compilation, compiled hooks, SQL optimization

@objectql/core re-exports these modules with @deprecated tags for backward compatibility. New code should import directly from the plugin packages:

// ✅ Recommended
import { QueryService } from '@objectql/plugin-query';
import { QueryCompiler } from '@objectql/plugin-optimizations';

// ❌ Deprecated (still works, but will be removed in v5)
import { QueryService, QueryCompiler } from '@objectql/core';

---

⚖️ License

ObjectQL is open-source software licensed under the MIT License.

You can use it freely in personal, commercial, or open-source projects.

---

_{The Foundation of the Object Ecosystem}

_{ObjectQL (Data) • ObjectOS (System) • Object UI (View)}