Skip to content

Commit c26c355

Browse files
hotlonghotlong
authored
Merge pull request #375 from objectstack-ai/copilot/refactor-development-debugging-methods
2 parents c84c6ff + e2882f6 commit c26c355

6 files changed

Lines changed: 126 additions & 29 deletions

File tree

‎.changeset/config.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,25 @@
1111
"@objectql/driver-fs",
1212
"@objectql/driver-memory",
1313
"@objectql/driver-mongo",
14+
"@objectql/driver-pg-wasm",
1415
"@objectql/driver-redis",
1516
"@objectql/driver-sql",
17+
"@objectql/driver-sqlite-wasm",
1618
"@objectql/driver-tck",
19+
"@objectql/edge-adapter",
1720
"@objectql/platform-node",
1821
"@objectql/plugin-formula",
22+
"@objectql/plugin-multitenancy",
23+
"@objectql/plugin-optimizations",
24+
"@objectql/plugin-query",
1925
"@objectql/plugin-security",
26+
"@objectql/plugin-sync",
2027
"@objectql/plugin-validator",
28+
"@objectql/plugin-workflow",
2129
"@objectql/protocol-graphql",
2230
"@objectql/protocol-json-rpc",
2331
"@objectql/protocol-odata-v4",
32+
"@objectql/protocol-sync",
2433
"@objectql/protocol-tck",
2534
"@objectql/sdk",
2635
"@objectql/types"

‎README.md‎

Lines changed: 83 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,13 @@ ObjectQL is organized as a Monorepo to ensure modularity and universal compatibi
3535
| Package | Environment | Description |
3636
| :--- | :--- | :--- |
3737
| **[`@objectql/types`](./packages/foundation/types)** | Universal | **The Contract.** Pure TypeScript interfaces defining the protocol. |
38-
| **[`@objectql/core`](./packages/foundation/core)** | Universal | **The Engine.** The runtime logic, validation, and repository pattern. |
39-
| **[`@objectql/platform-node`](./packages/foundation/platform-node)**| Node.js | Node.js platform utilities for file system integration, YAML loading, and plugin management. |
38+
| **[`@objectql/core`](./packages/foundation/core)** | Universal | **The Engine.** Plugin orchestrator, repository pattern, and kernel factory. Delegates query and optimization logic to dedicated plugins. |
39+
| **[`@objectql/plugin-query`](./packages/foundation/plugin-query)** | Universal | **Query Plugin.** QueryService, QueryBuilder, QueryAnalyzer, and FilterTranslator. |
40+
| **[`@objectql/plugin-optimizations`](./packages/foundation/plugin-optimizations)** | Universal | **Optimizations Plugin.** Connection pooling, query compilation, compiled hooks, lazy metadata loading, and SQL query optimization. |
4041
| **[`@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. |
42+
| **[`@objectql/plugin-validator`](./packages/foundation/plugin-validator)**| Universal | **Validation Plugin.** 5-type validation engine: field, cross-field, state machine, unique, and business rule. |
43+
| **[`@objectql/plugin-formula`](./packages/foundation/plugin-formula)**| Universal | **Formula Plugin.** Computed fields with JavaScript expressions in a sandboxed evaluator. |
44+
| **[`@objectql/platform-node`](./packages/foundation/platform-node)**| Node.js | Node.js platform utilities for file system integration, YAML loading, and plugin management. |
4145

4246
### Driver Layer
4347

@@ -357,21 +361,75 @@ If you fork or clone the repository to contribute or run examples from source:
357361

358362
1. **Setup Workspace**
359363
```bash
360-
git clone https://github.com/objectql/objectql.git
364+
git clone https://github.com/objectstack-ai/objectql.git
361365
cd objectql
362-
npm install -g pnpm
366+
corepack enable && corepack prepare pnpm@10.28.2 --activate
363367
pnpm install
364368
```
365369

366370
2. **Build Packages**
367-
You must build the core libraries before running examples, as they rely on local workspace builds.
371+
You must build all packages before running examples or the dev server, as they rely on local workspace builds.
368372
```bash
369373
pnpm build
370374
```
371375

372-
3. **Run Examples**
376+
3. **Run Dev Server**
377+
Start the full-stack development server with all plugins (ObjectQL + Security + GraphQL + OData + JSON-RPC):
378+
```bash
379+
pnpm dev
380+
# Equivalent to: objectstack serve --dev
381+
# Starts ObjectStack kernel at http://localhost:5050
382+
# Loads project-tracker example metadata from objectstack.config.ts
383+
```
373384

374-
These examples run as **scripts** to demonstrate the ObjectQL Core Engine capabilities (Validation, CRUD, Logic Hooks). They use an in-memory SQLite database.
385+
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:
386+
387+
```typescript
388+
// objectstack.config.ts
389+
export default {
390+
metadata: { name: 'objectos', version: '1.0.0' },
391+
objects: loadObjects(projectTrackerDir),
392+
plugins: [
393+
new HonoServerPlugin({ port: 5050 }),
394+
new ObjectQLPlugin({
395+
enableRepository: true,
396+
enableQueryService: true, // ← uses @objectql/plugin-query internally
397+
enableValidator: true,
398+
enableFormulas: true,
399+
datasources: { default: new MemoryDriver() }
400+
}),
401+
new ObjectQLSecurityPlugin({ enableAudit: false }),
402+
new GraphQLPlugin({ basePath: '/graphql' }),
403+
new ODataV4Plugin({ basePath: '/odata' }),
404+
new JSONRPCPlugin({ basePath: '/rpc' }),
405+
]
406+
};
407+
```
408+
409+
**Available `objectstack` CLI commands** (via `@objectstack/cli`):
410+
411+
| Command | Description |
412+
| :--- | :--- |
413+
| `objectstack serve --dev` | Start dev server (same as `pnpm dev`) |
414+
| `objectstack serve` | Start production server |
415+
| `objectstack create` | Scaffold a new project |
416+
| `objectstack doctor` | Diagnose environment issues |
417+
418+
4. **Run Tests**
419+
```bash
420+
# Run all tests
421+
npx vitest run
422+
423+
# Run tests for a specific package
424+
npx vitest run packages/foundation/core
425+
426+
# Run tests in watch mode
427+
npx vitest --watch
428+
```
429+
430+
5. **Run Examples**
431+
432+
These examples run as **scripts** to demonstrate the ObjectQL Core Engine capabilities (Validation, CRUD, Logic Hooks). They use an in-memory database.
375433

376434
**Starter (Project Tracker):**
377435
```bash
@@ -387,6 +445,24 @@ If you fork or clone the repository to contribute or run examples from source:
387445
# Output: Plugin initialization, Employee creation logs, Audit trails
388446
```
389447

448+
### Architecture Note
449+
450+
Since [#373](https://github.com/objectstack-ai/objectql/pull/373), `@objectql/core` has been decomposed into focused plugin packages:
451+
452+
- **`@objectql/plugin-query`** — QueryService, QueryBuilder, QueryAnalyzer, FilterTranslator
453+
- **`@objectql/plugin-optimizations`** — Connection pooling, query compilation, compiled hooks, SQL optimization
454+
455+
`@objectql/core` re-exports these modules with `@deprecated` tags for backward compatibility. **New code should import directly from the plugin packages:**
456+
457+
```typescript
458+
// ✅ Recommended
459+
import { QueryService } from '@objectql/plugin-query';
460+
import { QueryCompiler } from '@objectql/plugin-optimizations';
461+
462+
// ❌ Deprecated (still works, but will be removed in v5)
463+
import { QueryService, QueryCompiler } from '@objectql/core';
464+
```
465+
390466
---
391467

392468
## ⚖️ License

‎docs/DESIGN_CORE_REFACTOR.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
> **Author:** ObjectStack Architecture Team
44
> **Date:** 2026-02-10
55
> **Updated:** 2026-02-11
6-
> **Status:** Ready for Implementation — Upstream prerequisites met
6+
> **Status:** ✅ Completed — Implemented in [PR #373](https://github.com/objectstack-ai/objectql/pull/373)
77
> **Scope:** Decompose `@objectql/core`, align with `@objectstack/objectql` plugin extension model
88
> **Upstream Repo:** https://github.com/objectstack-ai/spec (v2.0.5+, latest commit `33646a7`)
99
> **Local Repo:** https://github.com/objectstack-ai/objectql (v4.2.0)

‎docs/ROADMAP_NEXT_PHASE.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -364,17 +364,17 @@ Each rule should be re-enabled incrementally after fixing violations:
364364
365365
### 7A. Core performance
366366

367-
The `packages/foundation/core/src/optimizations/` directory contains advanced optimization modules that are already implemented:
368-
369-
| Module | Status | Action |
370-
|--------|--------|--------|
371-
| `GlobalConnectionPool.ts` | ✅ Implemented | Benchmark and tune pool sizes |
372-
| `QueryCompiler.ts` | ✅ Implemented | Add cache hit/miss metrics |
373-
| `LazyMetadataLoader.ts` | ✅ Implemented | Verify lazy loading in production |
374-
| `OptimizedValidationEngine.ts` | ✅ Implemented | Benchmark vs. base validator |
375-
| `CompiledHookManager.ts` | ✅ Implemented | Profile hook chain overhead |
376-
| `SQLQueryOptimizer.ts` | ✅ Implemented | Add query plan analysis |
377-
| `DependencyGraph.ts` | ✅ Implemented | Ensure circular dependency detection |
367+
The optimization modules have been extracted into `@objectql/plugin-optimizations` (see [PR #373](https://github.com/objectstack-ai/objectql/pull/373)):
368+
369+
| Module | Package | Status | Action |
370+
|--------|---------|--------|--------|
371+
| `GlobalConnectionPool.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Benchmark and tune pool sizes |
372+
| `QueryCompiler.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Add cache hit/miss metrics |
373+
| `LazyMetadataLoader.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Verify lazy loading in production |
374+
| `OptimizedValidationEngine.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Benchmark vs. base validator |
375+
| `CompiledHookManager.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Profile hook chain overhead |
376+
| `SQLQueryOptimizer.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Add query plan analysis |
377+
| `DependencyGraph.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Ensure circular dependency detection |
378378

379379
### 7B. Browser bundle optimization
380380

‎docs/WORK_PLAN_2026_Q1_P2.md‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# ObjectQL Work Plan — 2026 Roadmap
22

3-
> Created: 2026-02-08 | Last Updated: 2026-02-09 | Status: **Active**
3+
> Created: 2026-02-08 | Last Updated: 2026-02-11 | Status: **Active**
44
> Current Version: **4.2.0** (all packages aligned, except `vscode-objectql` at 4.1.0)
5-
> Runtime: `@objectstack/cli` v2.0.1 (Kernel pattern) — `@objectql/server` deprecated, `packages/runtime/` removed.
6-
> @objectstack Platform: **v2.0.1** (upgraded from v2.0.0 — maintenance & stability patch)
5+
> Runtime: `@objectstack/cli` v2.0.6 (Kernel pattern) — `@objectql/server` deprecated, `packages/runtime/` removed.
6+
> @objectstack Platform: **v2.0.6**
77
88
---
99

@@ -429,7 +429,9 @@ Standardize third-party plugin distribution.
429429
| Package | NPM Name | Environment | Description |
430430
|---------|----------|-------------|-------------|
431431
| `packages/foundation/types` | `@objectql/types` | Universal | **The Constitution.** Protocol-derived TypeScript types. Zero runtime deps. |
432-
| `packages/foundation/core` | `@objectql/core` | Universal | **The Engine.** QueryBuilder, QueryCompiler, Repository, HookManager. No Node.js natives. |
432+
| `packages/foundation/core` | `@objectql/core` | Universal | **The Engine.** Plugin orchestrator, repository pattern, and kernel factory. Delegates query and optimization logic to dedicated plugins. |
433+
| `packages/foundation/plugin-query` | `@objectql/plugin-query` | Universal | **🆕 PR #373.** QueryService, QueryBuilder, QueryAnalyzer, FilterTranslator. Extracted from `@objectql/core`. |
434+
| `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`. |
433435
| `packages/foundation/platform-node` | `@objectql/platform-node` | Node.js | File system integration, YAML loading, glob-based plugin discovery. |
434436
| `packages/foundation/plugin-security` | `@objectql/plugin-security` | Universal | RBAC, Field-Level Security, Row-Level Security with AST-level enforcement. |
435437
| `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.
472474

473475
| Package | Owner | Version | Role in ObjectQL |
474476
|---------|-------|---------|-----------------|
475-
| `@objectstack/cli` | ObjectStack | 2.0.1 | Kernel bootstrapper (`objectstack serve`) |
476-
| `@objectstack/core` | ObjectStack | 2.0.1 | Kernel runtime, plugin lifecycle |
477-
| `@objectstack/plugin-hono-server` | ObjectStack | 2.0.1 | HTTP server (Hono-based) |
478-
| `@objectstack/spec` | ObjectStack | 2.0.1 | Formal protocol specifications (Zod schemas) |
479-
| `@objectstack/runtime` | ObjectStack | 2.0.1 | Core runtime & query engine |
480-
| `@objectstack/objectql` | ObjectStack | 2.0.1 | ObjectQL runtime bridge |
477+
| `@objectstack/cli` | ObjectStack | 2.0.6 | Kernel bootstrapper (`objectstack serve`) |
478+
| `@objectstack/core` | ObjectStack | 2.0.6 | Kernel runtime, plugin lifecycle |
479+
| `@objectstack/plugin-hono-server` | ObjectStack | 2.0.6 | HTTP server (Hono-based) |
480+
| `@objectstack/spec` | ObjectStack | 2.0.6 | Formal protocol specifications (Zod schemas) |
481+
| `@objectstack/runtime` | ObjectStack | 2.0.6 | Core runtime & query engine |
482+
| `@objectstack/objectql` | ObjectStack | 2.0.6 | ObjectQL runtime bridge |
481483
| AI Agent / AI tooling | **Separate project** | — | Not in this monorepo |
482484

483485
---

‎tsconfig.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,15 @@
33
"references": [
44
// Foundation Layer
55
{ "path": "./packages/foundation/types" },
6+
{ "path": "./packages/foundation/plugin-query" },
7+
{ "path": "./packages/foundation/plugin-optimizations" },
68
{ "path": "./packages/foundation/plugin-validator" },
79
{ "path": "./packages/foundation/plugin-formula" },
810
{ "path": "./packages/foundation/plugin-security" },
11+
{ "path": "./packages/foundation/plugin-multitenancy" },
12+
{ "path": "./packages/foundation/plugin-workflow" },
13+
{ "path": "./packages/foundation/plugin-sync" },
14+
{ "path": "./packages/foundation/edge-adapter" },
915
{ "path": "./packages/foundation/core" },
1016
{ "path": "./packages/foundation/platform-node" },
1117

@@ -17,16 +23,20 @@
1723
{ "path": "./packages/drivers/fs" },
1824
{ "path": "./packages/drivers/redis" },
1925
{ "path": "./packages/drivers/excel" },
26+
{ "path": "./packages/drivers/sqlite-wasm" },
27+
{ "path": "./packages/drivers/pg-wasm" },
2028

2129
// Protocols Layer
2230
{ "path": "./packages/protocols/graphql" },
2331
{ "path": "./packages/protocols/json-rpc" },
2432
{ "path": "./packages/protocols/odata-v4" },
33+
{ "path": "./packages/protocols/sync" },
2534

2635
// Tools Layer
2736
{ "path": "./packages/tools/cli" },
2837
{ "path": "./packages/tools/create" },
2938
{ "path": "./packages/tools/driver-tck" },
39+
{ "path": "./packages/tools/protocol-tck" },
3040
{ "path": "./packages/tools/vscode-objectql" },
3141

3242
// Examples

0 commit comments

Comments
 (0)