https://github.com/objectstack-ai/objectql

The Universal Data Protocol. A high-performance engine that virtualizes SQL, NoSQL (Redis), and Files (Excel) into a unified API. Write once, query anywhere.
https://github.com/objectstack-ai/objectql
database json-schema orm protocol typescript universal
Last synced: about 2 months ago
JSON representation
The Universal Data Protocol. A high-performance engine that virtualizes SQL, NoSQL (Redis), and Files (Excel) into a unified API. Write once, query anywhere.
Host: GitHub
URL: https://github.com/objectstack-ai/objectql
Owner: objectstack-ai
License: mit
Created: 2026-01-10T03:40:45.000Z (3 months ago)
Default Branch: main
Last Pushed: 2026-02-08T01:12:12.000Z (2 months ago)
Last Synced: 2026-02-08T01:52:41.164Z (2 months ago)
Topics: database, json-schema, orm, protocol, typescript, universal
Language: TypeScript
Homepage: https://www.objectql.org
Size: 7.05 MB
Stars: 3
Watchers: 0
Forks: 0
Open Issues: 3
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

          # 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.

  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

  [![TypeScript](https://img.shields.io/badge/written%20in-TypeScript-3178C6.svg)](https://www.typescriptlang.org/)

  [![NPM](https://img.shields.io/npm/v/@objectql/core.svg)](https://www.npmjs.com/package/@objectql/core)

---

## 🌐 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`](./packages/foundation/types)** | Universal | **The Contract.** Pure TypeScript interfaces defining the protocol. |

| **[`@objectql/core`](./packages/foundation/core)** | Universal | **The Engine.** Plugin orchestrator, repository pattern, and kernel factory. Delegates query and optimization logic to dedicated plugins. |

| **[`@objectql/plugin-query`](./packages/foundation/plugin-query)** | Universal | **Query Plugin.** QueryService, QueryBuilder, QueryAnalyzer, and FilterTranslator. |

| **[`@objectql/plugin-optimizations`](./packages/foundation/plugin-optimizations)** | Universal | **Optimizations Plugin.** Connection pooling, query compilation, compiled hooks, lazy metadata loading, and SQL query optimization. |

| **[`@objectql/plugin-security`](./packages/foundation/plugin-security)**| Universal | **Security Plugin.** Comprehensive RBAC, Field-Level Security (FLS), and Row-Level Security (RLS) with AST-level enforcement. |

| **[`@objectql/plugin-validator`](./packages/foundation/plugin-validator)**| Universal | **Validation Plugin.** 5-type validation engine: field, cross-field, state machine, unique, and business rule. |

| **[`@objectql/plugin-formula`](./packages/foundation/plugin-formula)**| Universal | **Formula Plugin.** Computed fields with JavaScript expressions in a sandboxed evaluator. |

| **[`@objectql/plugin-workflow`](./packages/foundation/plugin-workflow)**| Universal | **Workflow Plugin.** State machine executor with guards, actions, and compound states. |

| **[`@objectql/plugin-multitenancy`](./packages/foundation/plugin-multitenancy)**| Universal | **Multi-Tenancy Plugin.** Automatic tenant isolation via hook-based filter rewriting. |

| **[`@objectql/plugin-sync`](./packages/foundation/plugin-sync)**| Universal | **Sync Plugin.** Offline-first sync engine with conflict resolution strategies. |

| **[`@objectql/edge-adapter`](./packages/foundation/edge-adapter)**| Universal | **Edge Adapter.** Runtime detection and capability validation for edge environments. |

| **[`@objectql/platform-node`](./packages/foundation/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`](./packages/drivers/sql)** | Node.js | SQL database driver (PostgreSQL, MySQL, SQLite, SQL Server) via Knex. |

| **[`@objectql/driver-mongo`](./packages/drivers/mongo)** | Node.js | MongoDB driver with native aggregation pipeline support. |

| **[`@objectql/driver-memory`](./packages/drivers/memory)** | Universal | **In-Memory Driver.** Zero dependencies, perfect for testing and browser apps. |

| **[`@objectql/driver-fs`](./packages/drivers/fs)** | Node.js | File system driver with JSON file-based persistent storage. |

| **[`@objectql/driver-excel`](./packages/drivers/excel)** | Node.js | Excel file driver for using `.xlsx` spreadsheets as a data source. |

| **[`@objectql/driver-redis`](./packages/drivers/redis)** | Node.js | Redis driver (example/template implementation for key-value stores). |

| **[`@objectql/sdk`](./packages/drivers/sdk)** | Universal | **Remote HTTP Driver.** Type-safe client for connecting to ObjectQL servers. |

| **[`@objectql/driver-sqlite-wasm`](./packages/drivers/sqlite-wasm)** | Browser | **SQLite WASM Driver.** Browser-native SQL via WebAssembly + OPFS persistence. |

| **[`@objectql/driver-pg-wasm`](./packages/drivers/pg-wasm)** | Browser | **PostgreSQL WASM Driver.** Full PG feature set in the browser via PGlite. |

### Tools Layer

| Package | Environment | Description |

| :--- | :--- | :--- |

| **[`@objectql/cli`](./packages/tools/cli)** | Node.js | Command-line interface with AI-powered generation, dev server, and project management. |

| **[`@objectql/create`](./packages/tools/create)** | Node.js | Project scaffolding tool (`npm create @objectql@latest`). |

| **[`vscode-objectql`](./packages/tools/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.

```bash

# 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!

```yaml

# 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.

```bash

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](./examples/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](./examples/integrations/browser/)!

```javascript

// 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](./docs/guide/drivers/extensibility.md) - Lists potential databases and their implementation complexity

* [Implementing Custom Drivers](./docs/guide/drivers/implementing-custom-driver.md) - Step-by-step guide with code examples

* [Redis Driver Example](./packages/drivers/redis/) - 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](./docs/guide/query-best-practices.md) 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:**

```bash

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`](./packages/tools/vscode-objectql/README.md) for detailed documentation.

---

## 🛠️ Validation & Logic

ObjectQL includes a powerful validation engine that runs universally.

```yaml

# 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](./PROTOCOL_COMPLIANCE_REPORT.md))

### 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](./PROTOCOL_COMPLIANCE_SUMMARY.md) for quick reference**  

> **📄 See [Protocol Compliance Report](./PROTOCOL_COMPLIANCE_REPORT.md) for comprehensive analysis**  

> **🗺️ See [Protocol Development Plan](./PROTOCOL_DEVELOPMENT_PLAN_ZH.md) for detailed roadmap (中文)**

### Plugin Ecosystem 🧩

| Plugin | Status | Description |

|--------|--------|-------------|

| **[`@objectql/plugin-workflow`](./packages/foundation/plugin-workflow)** | ✅ Implemented | Full state machine executor with guards, actions, compound states |

| **[`@objectql/plugin-multitenancy`](./packages/foundation/plugin-multitenancy)** | ✅ Implemented | Automatic tenant isolation via hook-based filter rewriting |

| **[`@objectql/plugin-sync`](./packages/foundation/plugin-sync)** | ✅ Implemented | Offline-first sync with LWW, CRDT, and manual conflict resolution |

| **[`@objectql/edge-adapter`](./packages/foundation/edge-adapter)** | ✅ Implemented | Edge runtime detection and capability validation |

### Protocol Layer 🌐

| Package | Compliance | Status |

|---------|-----------|--------|

| **[`@objectql/protocol-graphql`](./packages/protocols/graphql)** | 85% | ⚠️ Good — Subscriptions, Federation planned Q2 |

| **[`@objectql/protocol-odata-v4`](./packages/protocols/odata-v4)** | 80% | ⚠️ Good — $expand, $count, $batch planned Q2 |

| **[`@objectql/protocol-json-rpc`](./packages/protocols/json-rpc)** | 90% | ✅ Excellent |

| **[`@objectql/protocol-sync`](./packages/protocols/sync)** | ✅ | ✅ Sync protocol handler with change logs and checkpoints |

### Key Documents

- **[📋 Implementation Status](./IMPLEMENTATION_STATUS.md)** - Complete feature matrix with detailed status

- **[🌐 Protocol Compliance Summary](./PROTOCOL_COMPLIANCE_SUMMARY.md)** - Quick reference (CN/EN)

- **[📊 Protocol Compliance Report](./PROTOCOL_COMPLIANCE_REPORT.md)** - Comprehensive audit (60 pages)

- **[🗺️ Protocol Development Plan (中文)](./PROTOCOL_DEVELOPMENT_PLAN_ZH.md)** - Detailed roadmap (100 pages)

- **[Roadmap](./docs/roadmap.md)** - Long-term vision and milestones *(if exists)*

- **[Contributing Guide](./docs/contributing.md)** - How to contribute *(if exists)*

> **💡 See [IMPLEMENTATION_STATUS.md](./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**

   ```bash

   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.

   ```bash

   pnpm build

   ```

3. **Run Dev Server**

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

   ```bash

   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:

   ```typescript

   // 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**

   ```bash

   # 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):**

   ```bash

   # 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:**

   ```bash

   pnpm --filter @objectql/example-enterprise-erp start

   # Output: Plugin initialization, Employee creation logs, Audit trails

   ```

### Architecture Note

Since [#373](https://github.com/objectstack-ai/objectql/pull/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:**

```typescript

// ✅ 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](https://www.google.com/search?q=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)}
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/objectstack-ai/objectql

Awesome Lists containing this project

README
