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. The runtime logic, validation, and repository pattern.
@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-localstorage	Browser	Browser Storage. Persistent client-side storage using LocalStorage.
@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.

Runtime Layer

Package	Environment	Description
@objectql/server	Node.js	HTTP server adapter for Node.js, Express, Next.js with REST and metadata APIs.

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:

name: story
label: User Story
fields:
  title:
    type: text
    required: true
  status:
    type: select
    options: [draft, active, done]
    default: draft
  points:
    type: number
    scale: 0
    default: 1

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

LocalStorage Driver (@objectql/driver-localstorage)

• Browser-native persistence - Data survives page refreshes
• Built on Web Storage API
• Perfect for offline apps, PWAs, and user preferences
• See LocalStorage Demo for examples

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
• 🎓 Educational Tools - Interactive learning experiences
• 🧪 Testing - Browser-based test environments

Try it now: Check out our interactive Browser Demo and LocalStorage Demo!

// 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 } });

app.registerObject({
  name: 'tasks',
  fields: {
    title: { type: 'text', required: true },
    completed: { type: 'boolean', defaultValue: false }
  }
});

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.

---

📊 Project Status & Planning

Current Version: 3.0.0
Overall Completion: ~75%

Key Documents

• Roadmap - Long-term vision, milestones, and strategic direction
• Development Plan - Detailed 6-month development plan
• Project Status - Current state and metrics
• Contributing Guide - How to contribute

Current Status

• ✅ Core Protocol & Runtime: 90%
• ✅ Data Drivers (SQL/Mongo/Memory/LocalStorage): 85%
• ✅ Developer Tools (CLI, VSCode Extension): 85%
• 🔄 Workflow Engine: 35%
• 🔄 Security & Permissions: 70%
• 🔄 Documentation: 75%

---

🛠️ Development & Contributing

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

1. Setup Workspace

   git clone https://github.com/objectql/objectql.git
   cd objectql
   npm install -g pnpm
   pnpm install

2. Build Packages You must build the core libraries before running examples, as they rely on local workspace builds.

   pnpm build

3. Run Examples

   These examples run as scripts to demonstrate the ObjectQL Core Engine capabilities (Validation, CRUD, Logic Hooks). They use an in-memory SQLite 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

---

⚖️ 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)}