diff --git a/.changeset/config.json b/.changeset/config.json index 0ed34771..cf8f8062 100644 --- a/.changeset/config.json +++ b/.changeset/config.json @@ -11,16 +11,25 @@ "@objectql/driver-fs", "@objectql/driver-memory", "@objectql/driver-mongo", + "@objectql/driver-pg-wasm", "@objectql/driver-redis", "@objectql/driver-sql", + "@objectql/driver-sqlite-wasm", "@objectql/driver-tck", + "@objectql/edge-adapter", "@objectql/platform-node", "@objectql/plugin-formula", + "@objectql/plugin-multitenancy", + "@objectql/plugin-optimizations", + "@objectql/plugin-query", "@objectql/plugin-security", + "@objectql/plugin-sync", "@objectql/plugin-validator", + "@objectql/plugin-workflow", "@objectql/protocol-graphql", "@objectql/protocol-json-rpc", "@objectql/protocol-odata-v4", + "@objectql/protocol-sync", "@objectql/protocol-tck", "@objectql/sdk", "@objectql/types" diff --git a/README.md b/README.md index cbf14ff5..2066b98a 100644 --- a/README.md +++ b/README.md @@ -35,9 +35,13 @@ ObjectQL is organized as a Monorepo to ensure modularity and universal compatibi | 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.** The runtime logic, validation, and repository pattern. | -| **[`@objectql/platform-node`](./packages/foundation/platform-node)**| Node.js | Node.js platform utilities for file system integration, YAML loading, and plugin management. | +| **[`@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/platform-node`](./packages/foundation/platform-node)**| Node.js | Node.js platform utilities for file system integration, YAML loading, and plugin management. | ### Driver Layer @@ -357,21 +361,75 @@ If you fork or clone the repository to contribute or run examples from source: 1. **Setup Workspace** ```bash - git clone https://github.com/objectql/objectql.git + git clone https://github.com/objectstack-ai/objectql.git cd objectql - npm install -g pnpm + corepack enable && corepack prepare pnpm@10.28.2 --activate pnpm install ``` 2. **Build Packages** - You must build the core libraries before running examples, as they rely on local workspace builds. + You must build all packages before running examples or the dev server, as they rely on local workspace builds. ```bash pnpm build ``` -3. **Run Examples** +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 + ``` - These examples run as **scripts** to demonstrate the ObjectQL Core Engine capabilities (Validation, CRUD, Logic Hooks). They use an in-memory SQLite database. + The dev server is powered by `@objectstack/cli` (v2.0.6). 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 @@ -387,6 +445,24 @@ If you fork or clone the repository to contribute or run examples from source: # 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 diff --git a/docs/DESIGN_CORE_REFACTOR.md b/docs/DESIGN_CORE_REFACTOR.md index 9e73759b..25eeef13 100644 --- a/docs/DESIGN_CORE_REFACTOR.md +++ b/docs/DESIGN_CORE_REFACTOR.md @@ -3,7 +3,7 @@ > **Author:** ObjectStack Architecture Team > **Date:** 2026-02-10 > **Updated:** 2026-02-11 -> **Status:** Ready for Implementation — Upstream prerequisites met +> **Status:** ✅ Completed — Implemented in [PR #373](https://github.com/objectstack-ai/objectql/pull/373) > **Scope:** Decompose `@objectql/core`, align with `@objectstack/objectql` plugin extension model > **Upstream Repo:** https://github.com/objectstack-ai/spec (v2.0.5+, latest commit `33646a7`) > **Local Repo:** https://github.com/objectstack-ai/objectql (v4.2.0) diff --git a/docs/ROADMAP_NEXT_PHASE.md b/docs/ROADMAP_NEXT_PHASE.md index 123972a4..a2289cc2 100644 --- a/docs/ROADMAP_NEXT_PHASE.md +++ b/docs/ROADMAP_NEXT_PHASE.md @@ -364,17 +364,17 @@ Each rule should be re-enabled incrementally after fixing violations: ### 7A. Core performance -The `packages/foundation/core/src/optimizations/` directory contains advanced optimization modules that are already implemented: - -| Module | Status | Action | -|--------|--------|--------| -| `GlobalConnectionPool.ts` | ✅ Implemented | Benchmark and tune pool sizes | -| `QueryCompiler.ts` | ✅ Implemented | Add cache hit/miss metrics | -| `LazyMetadataLoader.ts` | ✅ Implemented | Verify lazy loading in production | -| `OptimizedValidationEngine.ts` | ✅ Implemented | Benchmark vs. base validator | -| `CompiledHookManager.ts` | ✅ Implemented | Profile hook chain overhead | -| `SQLQueryOptimizer.ts` | ✅ Implemented | Add query plan analysis | -| `DependencyGraph.ts` | ✅ Implemented | Ensure circular dependency detection | +The optimization modules have been extracted into `@objectql/plugin-optimizations` (see [PR #373](https://github.com/objectstack-ai/objectql/pull/373)): + +| Module | Package | Status | Action | +|--------|---------|--------|--------| +| `GlobalConnectionPool.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Benchmark and tune pool sizes | +| `QueryCompiler.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Add cache hit/miss metrics | +| `LazyMetadataLoader.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Verify lazy loading in production | +| `OptimizedValidationEngine.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Benchmark vs. base validator | +| `CompiledHookManager.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Profile hook chain overhead | +| `SQLQueryOptimizer.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Add query plan analysis | +| `DependencyGraph.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Ensure circular dependency detection | ### 7B. Browser bundle optimization diff --git a/docs/WORK_PLAN_2026_Q1_P2.md b/docs/WORK_PLAN_2026_Q1_P2.md index 7d7b8dd6..5890ae7b 100644 --- a/docs/WORK_PLAN_2026_Q1_P2.md +++ b/docs/WORK_PLAN_2026_Q1_P2.md @@ -1,9 +1,9 @@ # ObjectQL Work Plan — 2026 Roadmap -> Created: 2026-02-08 | Last Updated: 2026-02-09 | Status: **Active** +> Created: 2026-02-08 | Last Updated: 2026-02-11 | Status: **Active** > Current Version: **4.2.0** (all packages aligned, except `vscode-objectql` at 4.1.0) -> Runtime: `@objectstack/cli` v2.0.1 (Kernel pattern) — `@objectql/server` deprecated, `packages/runtime/` removed. -> @objectstack Platform: **v2.0.1** (upgraded from v2.0.0 — maintenance & stability patch) +> Runtime: `@objectstack/cli` v2.0.6 (Kernel pattern) — `@objectql/server` deprecated, `packages/runtime/` removed. +> @objectstack Platform: **v2.0.6** --- @@ -429,7 +429,9 @@ Standardize third-party plugin distribution. | Package | NPM Name | Environment | Description | |---------|----------|-------------|-------------| | `packages/foundation/types` | `@objectql/types` | Universal | **The Constitution.** Protocol-derived TypeScript types. Zero runtime deps. | -| `packages/foundation/core` | `@objectql/core` | Universal | **The Engine.** QueryBuilder, QueryCompiler, Repository, HookManager. No Node.js natives. | +| `packages/foundation/core` | `@objectql/core` | Universal | **The Engine.** Plugin orchestrator, repository pattern, and kernel factory. Delegates query and optimization logic to dedicated plugins. | +| `packages/foundation/plugin-query` | `@objectql/plugin-query` | Universal | **🆕 PR #373.** QueryService, QueryBuilder, QueryAnalyzer, FilterTranslator. Extracted from `@objectql/core`. | +| `packages/foundation/plugin-optimizations` | `@objectql/plugin-optimizations` | Universal | **🆕 PR #373.** Connection pooling, query compilation, compiled hooks, lazy metadata loading, SQL query optimization. Extracted from `@objectql/core`. | | `packages/foundation/platform-node` | `@objectql/platform-node` | Node.js | File system integration, YAML loading, glob-based plugin discovery. | | `packages/foundation/plugin-security` | `@objectql/plugin-security` | Universal | RBAC, Field-Level Security, Row-Level Security with AST-level enforcement. | | `packages/foundation/plugin-validator` | `@objectql/plugin-validator` | Universal | 5-type validation engine: field, cross-field, state_machine, unique, business_rule. | @@ -472,12 +474,12 @@ Standardize third-party plugin distribution. | Package | Owner | Version | Role in ObjectQL | |---------|-------|---------|-----------------| -| `@objectstack/cli` | ObjectStack | 2.0.1 | Kernel bootstrapper (`objectstack serve`) | -| `@objectstack/core` | ObjectStack | 2.0.1 | Kernel runtime, plugin lifecycle | -| `@objectstack/plugin-hono-server` | ObjectStack | 2.0.1 | HTTP server (Hono-based) | -| `@objectstack/spec` | ObjectStack | 2.0.1 | Formal protocol specifications (Zod schemas) | -| `@objectstack/runtime` | ObjectStack | 2.0.1 | Core runtime & query engine | -| `@objectstack/objectql` | ObjectStack | 2.0.1 | ObjectQL runtime bridge | +| `@objectstack/cli` | ObjectStack | 2.0.6 | Kernel bootstrapper (`objectstack serve`) | +| `@objectstack/core` | ObjectStack | 2.0.6 | Kernel runtime, plugin lifecycle | +| `@objectstack/plugin-hono-server` | ObjectStack | 2.0.6 | HTTP server (Hono-based) | +| `@objectstack/spec` | ObjectStack | 2.0.6 | Formal protocol specifications (Zod schemas) | +| `@objectstack/runtime` | ObjectStack | 2.0.6 | Core runtime & query engine | +| `@objectstack/objectql` | ObjectStack | 2.0.6 | ObjectQL runtime bridge | | AI Agent / AI tooling | **Separate project** | — | Not in this monorepo | --- diff --git a/tsconfig.json b/tsconfig.json index bea200fc..7bfd0ba5 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -3,9 +3,15 @@ "references": [ // Foundation Layer { "path": "./packages/foundation/types" }, + { "path": "./packages/foundation/plugin-query" }, + { "path": "./packages/foundation/plugin-optimizations" }, { "path": "./packages/foundation/plugin-validator" }, { "path": "./packages/foundation/plugin-formula" }, { "path": "./packages/foundation/plugin-security" }, + { "path": "./packages/foundation/plugin-multitenancy" }, + { "path": "./packages/foundation/plugin-workflow" }, + { "path": "./packages/foundation/plugin-sync" }, + { "path": "./packages/foundation/edge-adapter" }, { "path": "./packages/foundation/core" }, { "path": "./packages/foundation/platform-node" }, @@ -17,16 +23,20 @@ { "path": "./packages/drivers/fs" }, { "path": "./packages/drivers/redis" }, { "path": "./packages/drivers/excel" }, + { "path": "./packages/drivers/sqlite-wasm" }, + { "path": "./packages/drivers/pg-wasm" }, // Protocols Layer { "path": "./packages/protocols/graphql" }, { "path": "./packages/protocols/json-rpc" }, { "path": "./packages/protocols/odata-v4" }, + { "path": "./packages/protocols/sync" }, // Tools Layer { "path": "./packages/tools/cli" }, { "path": "./packages/tools/create" }, { "path": "./packages/tools/driver-tck" }, + { "path": "./packages/tools/protocol-tck" }, { "path": "./packages/tools/vscode-objectql" }, // Examples