README.md

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.

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/driver-sql	Node.js	Adapter for SQL databases (Postgres, MySQL, SQLite) via Knex.
@objectql/driver-mongo	Node.js	Adapter for MongoDB.
@objectql/sdk	Universal	Remote Driver. Connects to an ObjectQL server via HTTP.
@objectql/platform-node	Node.js	Utilities for loading YAML files from the filesystem.

---

⚡ Quick Start

1. Installation

# Install core and a driver (e.g., Postgres or SQLite)
npm install @objectql/core @objectql/driver-sql sqlite3

2. The Universal Script

ObjectQL can run in a single file without complex configuration.

import { ObjectQL } from '@objectql/core';
import { SqlDriver } from '@objectql/driver-sql';

async function main() {
  // 1. Initialize Driver (In-Memory SQLite)
  const driver = new SqlDriver({
    client: 'sqlite3',
    connection: { filename: ':memory:' }, 
    useNullAsDefault: true
  });

  // 2. Initialize Engine
  const app = new ObjectQL({
    datasources: { default: driver }
  });

  // 3. Define Schema (The "Object")
  // In a real app, this would be loaded from a .yml file
  app.registerObject({
    name: "users",
    fields: {
      name: { type: "text", required: true },
      email: { type: "email", unique: true },
      role: { 
        type: "select", 
        options: ["admin", "user"], 
        defaultValue: "user" 
      }
    }
  });

  await app.init();

  // 4. Enjoy Type-Safe(ish) CRUD
  const ctx = app.createContext({ isSystem: true });
  const repo = ctx.object('users');

  // Create
  await repo.create({ name: 'Alice', email: 'alice@example.com' });

  // Find
  const users = await repo.find({
    filters: [['role', '=', 'user']]
  });
  
  console.log(users);
}

main();

---

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

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

---

🛠️ 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 Progress

For a complete status report on ObjectQL's implementation against the documented standard protocol, see PROGRESS.md.

Current Status: 70% Complete (v1.8.3)

• ✅ Core Protocol & Runtime: 85%
• ✅ Data Drivers (SQL/Mongo): 75%
• ⚠️ UI Metadata Layer: 40%
• ⚠️ Workflow Engine: 35%

---

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