|
| 1 | +# ObjectQL Migration Summary |
| 2 | + |
| 3 | +## What is this migration about? |
| 4 | + |
| 5 | +ObjectQL is transitioning from a **standalone ORM framework** to a **plugin ecosystem for ObjectStack**. This repositions ObjectQL as a collection of query-related extensions built on top of the @objectstack/runtime architecture. |
| 6 | + |
| 7 | +## Why this migration? |
| 8 | + |
| 9 | +1. **Avoid Duplication**: @objectstack/runtime already provides core runtime, query engine, and plugin system functionality |
| 10 | +2. **Better Separation of Concerns**: ObjectQL focuses on what it does best - advanced query capabilities and database drivers |
| 11 | +3. **Leverage ObjectStack Ecosystem**: Benefit from the broader ObjectStack platform and community |
| 12 | +4. **Plugin Architecture**: Make ObjectQL components more modular and composable |
| 13 | + |
| 14 | +## What changes for users? |
| 15 | + |
| 16 | +### Current Usage (v3.x) |
| 17 | +```typescript |
| 18 | +import { ObjectQL } from '@objectql/core'; |
| 19 | +import { SQLDriver } from '@objectql/driver-sql'; |
| 20 | + |
| 21 | +const app = new ObjectQL({ |
| 22 | + datasources: { |
| 23 | + default: new SQLDriver(config) |
| 24 | + } |
| 25 | +}); |
| 26 | + |
| 27 | +await app.init(); |
| 28 | +const ctx = app.createContext({ isSystem: true }); |
| 29 | +const users = ctx.object('users'); |
| 30 | +await users.find({ filters: [/*...*/] }); |
| 31 | +``` |
| 32 | + |
| 33 | +### New Usage (v4.x - Plugin Model) |
| 34 | +```typescript |
| 35 | +import { ObjectStackKernel } from '@objectstack/runtime'; |
| 36 | +import { ObjectQLPlugin } from '@objectql/core'; |
| 37 | +import { SQLDriver } from '@objectql/driver-sql'; |
| 38 | + |
| 39 | +const kernel = new ObjectStackKernel({ |
| 40 | + datasources: { |
| 41 | + default: new SQLDriver(config) |
| 42 | + } |
| 43 | +}); |
| 44 | + |
| 45 | +// Install ObjectQL plugin for enhanced query features |
| 46 | +kernel.use(new ObjectQLPlugin()); |
| 47 | + |
| 48 | +await kernel.init(); |
| 49 | +const ctx = kernel.createContext({ isSystem: true }); |
| 50 | +const users = ctx.object('users'); |
| 51 | +await users.find({ filters: [/*...*/] }); // Same API! |
| 52 | +``` |
| 53 | + |
| 54 | +### Backward Compatibility (v4.x) |
| 55 | +```typescript |
| 56 | +// Legacy API still works through compatibility layer |
| 57 | +import { ObjectQL } from '@objectql/core'; |
| 58 | +import { SQLDriver } from '@objectql/driver-sql'; |
| 59 | + |
| 60 | +const app = new ObjectQL({ |
| 61 | + datasources: { default: new SQLDriver(config) } |
| 62 | +}); |
| 63 | +// Internally uses ObjectStack kernel + ObjectQL plugin |
| 64 | +``` |
| 65 | + |
| 66 | +## What stays the same? |
| 67 | + |
| 68 | +✅ **Repository Pattern API** - `find()`, `create()`, `update()`, `delete()` methods |
| 69 | +✅ **All 9 Database Drivers** - SQL, MongoDB, Memory, LocalStorage, FS, Excel, Redis, SDK |
| 70 | +✅ **Validation Engine** - Field validation, cross-field validation, custom validators |
| 71 | +✅ **Formula Engine** - Computed fields and formula expressions |
| 72 | +✅ **AI Agent** - Query generation and explanation |
| 73 | +✅ **Developer Tools** - CLI, VSCode extension, project scaffolding |
| 74 | + |
| 75 | +## What changes? |
| 76 | + |
| 77 | +🔄 **Architecture** - Built on @objectstack/runtime instead of standalone |
| 78 | +🔄 **Type System** - Uses @objectstack/spec as base, ObjectQL adds extensions |
| 79 | +🔄 **Driver Interface** - Implements @objectstack DriverInterface |
| 80 | +🔄 **Plugin System** - Components are plugins, not monolithic |
| 81 | +🔄 **Package Dependencies** - @objectstack/* as peer dependencies |
| 82 | + |
| 83 | +## Migration Timeline |
| 84 | + |
| 85 | +| Phase | Duration | Status | |
| 86 | +|-------|----------|--------| |
| 87 | +| 1. Dependency Alignment | 2 weeks | 📅 Planning | |
| 88 | +| 2. Types Consolidation | 1 week | 📅 Planning | |
| 89 | +| 3. Core Refactoring | 2 weeks | 📅 Planning | |
| 90 | +| 4. Driver Migration | 2 weeks | 📅 Planning | |
| 91 | +| 5. Runtime & Tools | 1 week | 📅 Planning | |
| 92 | +| 6. Documentation | 1 week | 📅 Planning | |
| 93 | +| 7. Testing | 1 week | 📅 Planning | |
| 94 | +| 8. Publishing | 1 week | 📅 Planning | |
| 95 | + |
| 96 | +**Total Estimated Time**: 11 weeks |
| 97 | + |
| 98 | +## Current Status |
| 99 | + |
| 100 | +✅ **Assessment Complete** - Repository analyzed, dependencies identified |
| 101 | +✅ **Migration Plan Created** - Comprehensive 8-phase plan documented |
| 102 | +✅ **Implementation Roadmap** - Detailed task breakdown with code examples |
| 103 | +📅 **Next**: Begin Phase 1 - Dependency Alignment |
| 104 | + |
| 105 | +## Key Documents |
| 106 | + |
| 107 | +1. **[MIGRATION_TO_OBJECTSTACK.md](./MIGRATION_TO_OBJECTSTACK.md)** - Full migration plan (English) |
| 108 | +2. **[MIGRATION_TO_OBJECTSTACK.zh-CN.md](./MIGRATION_TO_OBJECTSTACK.zh-CN.md)** - 完整迁移计划（中文） |
| 109 | +3. **[IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md)** - Actionable tasks with code |
| 110 | + |
| 111 | +## Package Transformation |
| 112 | + |
| 113 | +| Package | Current Role | New Role | |
| 114 | +|---------|-------------|----------| |
| 115 | +| @objectql/types | Type definitions | Query type extensions only | |
| 116 | +| @objectql/core | Runtime engine | Query engine plugin | |
| 117 | +| @objectql/platform-node | Platform layer | Platform plugin utilities | |
| 118 | +| @objectql/driver-sql | SQL driver | @objectstack-compatible SQL driver | |
| 119 | +| @objectql/driver-mongo | MongoDB driver | @objectstack-compatible Mongo driver | |
| 120 | +| @objectql/driver-memory | Memory driver | @objectstack-compatible Memory driver | |
| 121 | +| @objectql/driver-* | Other drivers | @objectstack-compatible drivers | |
| 122 | +| @objectql/server | HTTP server | Server plugin for @objectstack/runtime | |
| 123 | +| @objectql/cli | CLI tool | ObjectStack-aware CLI | |
| 124 | +| vscode-objectql | VS Code extension | ObjectStack + ObjectQL extension | |
| 125 | + |
| 126 | +## Risk Mitigation |
| 127 | + |
| 128 | +### Potential Risks |
| 129 | +1. **Breaking Changes** - Some APIs may change |
| 130 | +2. **Performance** - Need to ensure no regression |
| 131 | +3. **Community Impact** - Users need to migrate |
| 132 | + |
| 133 | +### Mitigation Strategies |
| 134 | +1. **Compatibility Layer** - Maintain v3.x API surface |
| 135 | +2. **Comprehensive Testing** - 100% test coverage maintained |
| 136 | +3. **Migration Tools** - Automated migration assistance |
| 137 | +4. **Documentation** - Clear migration guide with examples |
| 138 | +5. **Support Period** - v3.x maintained for 6 months |
| 139 | + |
| 140 | +## Success Metrics |
| 141 | + |
| 142 | +### Technical |
| 143 | +- ✅ All 97 source files successfully migrated |
| 144 | +- ✅ Zero duplicate type definitions |
| 145 | +- ✅ All 9 drivers implement @objectstack DriverInterface |
| 146 | +- ✅ Test coverage ≥ 80% |
| 147 | +- ✅ Performance within 5% of v3.x |
| 148 | + |
| 149 | +### Community |
| 150 | +- ✅ 50+ successful migrations using guide |
| 151 | +- ✅ < 5 critical bugs in first month |
| 152 | +- ✅ Positive early adopter feedback |
| 153 | +- ✅ 3+ community plugin contributions |
| 154 | + |
| 155 | +## Questions? |
| 156 | + |
| 157 | +- **GitHub Issues**: https://github.com/objectstack-ai/objectql/issues |
| 158 | +- **Discussions**: Create topic in repository discussions |
| 159 | +- **Migration Support**: Tag issues with `migration` label |
| 160 | + |
| 161 | +--- |
| 162 | + |
| 163 | +**Last Updated**: 2026-01-21 |
| 164 | +**Status**: Planning Phase |
| 165 | +**Version**: v3.x → v4.x migration |
0 commit comments