feat: Delegate core types to @objectstack ecosystem #164
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,143 @@ | ||
| # Type System Migration - Phase 1 Summary | ||
|
|
||
| ## Overview | ||
| This document tracks the migration of `@objectql/types` to delegate general types to `@objectstack/spec` and `@objectstack/runtime` packages. | ||
|
|
||
| ## Version Changes | ||
| - **@objectql/types**: `3.0.1` → `4.0.0-beta.1` | ||
| - **Dependency Model**: Changed from `dependencies` to `peerDependencies` + `devDependencies` (workspace) | ||
|
|
||
| ## Type Mapping | ||
|
|
||
| ### Types Delegated to @objectstack/spec | ||
|
|
||
| | Type Name | Source (Before) | Source (After) | Re-exported | Deprecated | | ||
| |-----------|----------------|----------------|-------------|------------| | ||
| | `Field` | Local definition | `@objectstack/spec` | Yes (as `SpecField`) | Yes | | ||
| | `FieldType` | Local definition | `@objectstack/spec` | Yes (as `ProtocolFieldType`) | Yes | | ||
| | `SelectOption` | Local definition | `@objectstack/spec` | Yes (as `SpecSelectOption`) | Yes | | ||
| | `ServiceObject` | Local definition | `@objectstack/spec` | Yes (as `SpecObject`) | Yes | | ||
| | `IndexSchema` | Local definition | `@objectstack/spec` | Yes | Yes | | ||
| | `Action` | Local definition | `@objectstack/spec` | Yes (as `SpecAction`) | Yes | | ||
| | `FilterCondition` | Local definition | `@objectstack/spec` | Direct import | No | | ||
| | `QueryAST` | N/A | `@objectstack/spec` | Via imports | No | | ||
| | `FilterNode` | N/A | `@objectstack/spec` | Via imports | No | | ||
| | `SortNode` | N/A | `@objectstack/spec` | Via imports | No | | ||
|
|
||
| ### Types Delegated to @objectstack/runtime | ||
|
|
||
| | Type Name | Source (Before) | Source (After) | Re-exported | Deprecated | | ||
| |-----------|----------------|----------------|-------------|------------| | ||
| | `RuntimePlugin` | N/A | `@objectstack/runtime` | Direct import | No | | ||
| | `RuntimeContext` | N/A | `@objectstack/runtime` | Direct import | No | | ||
| | `ObjectStackKernel` | N/A | `@objectstack/runtime` | Direct import | No | | ||
| | `ObjectStackRuntimeProtocol` | N/A | `@objectstack/runtime` | Direct import | No | | ||
|
|
||
| ### ObjectQL-Specific Types (Retained) | ||
|
|
||
| The following types remain fully defined in `@objectql/types` as they are ObjectQL-specific extensions: | ||
|
|
||
| #### Field Extensions (`src/field.ts`) | ||
| - `FieldConfig` - Extends protocol Field with runtime properties | ||
| - `FieldType` - Extends protocol FieldType with runtime types (`vector`, `grid`, `location`, `object`) | ||
| - `FieldOption` - Extends SelectOption to allow number values | ||
| - `AttachmentData` - File metadata structure | ||
| - `ImageAttachmentData` - Image-specific metadata | ||
|
|
||
| #### Object Extensions (`src/object.ts`) | ||
| - `ObjectConfig` - Extends ServiceObject with runtime properties | ||
| - `IndexConfig` - Simplified alias for IndexSchema | ||
| - `AiSearchConfig` - AI/semantic search configuration | ||
| - `ObjectAiConfig` - Object-level AI configuration | ||
| - `ObjectDoc` - Document instance interface | ||
|
|
||
| #### Query Types (`src/query.ts`) | ||
| - `UnifiedQuery` - ObjectQL's unified query interface | ||
| - `AggregateFunction` - Aggregation function types | ||
| - `AggregateOption` - Aggregation configuration | ||
|
|
||
| #### Runtime Types | ||
| - `ObjectQLContext` (`src/context.ts`) - ObjectQL execution context | ||
| - `ObjectQLContextOptions` (`src/context.ts`) - Context options | ||
| - `Driver` (`src/driver.ts`) - ObjectQL driver interface | ||
| - `IntrospectedColumn`, `IntrospectedTable`, `IntrospectedSchema` (`src/driver.ts`) - Schema introspection | ||
|
|
||
| ## Workspace Structure Changes | ||
|
|
||
| ### New Packages Created | ||
| ``` | ||
| packages/objectstack/ | ||
| ├── spec/ # @objectstack/spec stub | ||
| │ ├── src/index.ts | ||
| │ ├── package.json | ||
| │ ├── tsconfig.json | ||
| │ └── README.md | ||
| └── runtime/ # @objectstack/runtime stub | ||
| ├── src/index.ts | ||
| ├── package.json | ||
| ├── tsconfig.json | ||
| └── README.md | ||
| ``` | ||
|
|
||
| ### Workspace Configuration | ||
| Updated `pnpm-workspace.yaml` to include: | ||
| ```yaml | ||
| packages: | ||
| - packages/objectstack/* | ||
| ``` | ||
|
|
||
| ## Breaking Changes | ||
|
|
||
| ### For Consumers | ||
| - No breaking changes for typical usage (backward compatible re-exports) | ||
| - Advanced users importing protocol types should prefer importing directly from `@objectstack/spec` | ||
| - All re-exported types are marked `@deprecated` with migration hints | ||
|
|
||
| ### Package Dependencies | ||
| - `@objectstack/spec` and `@objectstack/runtime` are now **peerDependencies** | ||
| - Consumers must ensure these packages are available in their project | ||
|
|
||
| ## Migration Guide for Consumers | ||
|
|
||
| ### Before (v3.x) | ||
| ```typescript | ||
| import { Field, FieldType, ServiceObject } from '@objectql/types'; | ||
| ``` | ||
|
|
||
| ### After (v4.0) | ||
| ```typescript | ||
| // Option 1: Continue using re-exports (deprecated but works) | ||
| import { SpecField, ProtocolFieldType, SpecObject } from '@objectql/types'; | ||
|
|
||
| // Option 2: Import directly from protocol (recommended) | ||
| import { Field, FieldType, ServiceObject } from '@objectstack/spec'; | ||
|
|
||
| // Option 3: Use ObjectQL runtime extensions | ||
| import { FieldConfig, ObjectConfig } from '@objectql/types'; | ||
| ``` | ||
|
|
||
| ## Build Status | ||
|
|
||
| ### ✅ Successfully Building | ||
| - `@objectstack/spec` - All protocol types compile | ||
| - `@objectstack/runtime` - All runtime types compile | ||
| - `@objectql/types` - All types compile, 32 tests passing | ||
|
|
||
| ### ⚠️ Known Issues | ||
| - External package `@objectstack/objectql@0.2.0` in node_modules has compatibility issues | ||
| - Some type mismatches in `@objectql/core` repository.ts (FilterNode usage) | ||
| - These are expected during migration and will be resolved in subsequent phases | ||
|
|
||
| ## Next Steps | ||
|
|
||
| 1. **Phase 2**: Update `@objectql/core` to properly use new type structure | ||
| 2. **Phase 3**: Update driver packages to use delegated types | ||
| 3. **Phase 4**: Publish updated packages with proper semver | ||
| 4. **Phase 5**: Update documentation and migration guides | ||
|
|
||
| ## Notes | ||
|
|
||
| - This is a **preparation phase** for the full ObjectStack v4.0 migration | ||
| - Stub packages created in workspace will be replaced by published npm packages | ||
| - All changes maintain backward compatibility through re-exports | ||
| - Types are properly marked with deprecation notices |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| # @objectstack/runtime | ||
|
|
||
| ObjectStack Runtime - Core Runtime Types | ||
|
|
||
| This package contains the runtime type definitions for the ObjectStack ecosystem. | ||
|
|
||
| ## Purpose | ||
|
|
||
| This stub package is part of the ObjectQL v4.0 migration to the @objectstack ecosystem. It provides: | ||
| - RuntimePlugin interface | ||
| - RuntimeContext interface | ||
| - ObjectStackKernel interface | ||
|
|
||
| ## Migration Notes | ||
|
|
||
| This is a workspace stub package created during the ObjectQL type system cleanup phase. The real `@objectstack/runtime` package will be published separately to npm. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| { | ||
| "name": "@objectstack/runtime", | ||
| "version": "0.2.0", | ||
| "description": "ObjectStack Runtime - Core Runtime Types", | ||
| "keywords": [ | ||
| "objectstack", | ||
| "runtime", | ||
| "types" | ||
| ], | ||
| "license": "MIT", | ||
| "main": "dist/index.js", | ||
| "types": "dist/index.d.ts", | ||
| "files": [ | ||
| "dist" | ||
| ], | ||
| "scripts": { | ||
| "build": "tsc", | ||
| "test": "echo 'No tests for stub package'" | ||
| } | ||
|
There was a problem hiding this comment. Similar to @objectstack/spec, this runtime package has no test coverage. The ObjectStackKernel class and RuntimePlugin interface define the core plugin architecture. Even as a stub, these should have tests to validate the contract. Consider adding tests that verify the interface contracts and method signatures are compatible with expected usage patterns. |
||
| } | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The package.json lists both peerDependencies and devDependencies for @objectstack/spec and @objectstack/runtime. However, the peerDependencies specify ^0.2.0 while devDependencies use workspace:*. This could potentially cause confusion. Consumers will need to install these packages matching the peer dependency version range. Consider adding a note in the package description or README about this requirement.