Skip to content

README.md

Latest commit

 

History

History
265 lines (181 loc) · 8.84 KB

README.md

File metadata and controls

265 lines (181 loc) · 8.84 KB

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 TypeScript NPM

🌐 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/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/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.

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:

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

🛠️ 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.4)

  • ✅ Core Protocol & Runtime: 85%
  • ✅ Data Drivers (SQL/Mongo): 75%
  • ⚠️ 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)