-
Notifications
You must be signed in to change notification settings - Fork 2
Complete development plan: modularize kernel/events.zod.ts, add v3.0 migration guide #611
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
d4becf7
Initial plan
Copilot 35f7a2e
feat: modularize kernel/events.zod.ts into sub-modules (Sprint K)
Copilot 097c4d8
docs: create v3.0 migration guide, update ROADMAP.md and CHANGELOG.md
Copilot 45ee05c
fix: address all PR review feedback
Copilot File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
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,175 @@ | ||
| # ObjectStack v3.0 Migration Guide | ||
|
|
||
| > **Target Release:** Q2 2026 | ||
| > **Breaking Changes:** Deprecated items removed, hub module consolidated | ||
| > **Prerequisite:** Ensure your project is on v2.x with all deprecation warnings resolved | ||
|
|
||
| --- | ||
|
|
||
| ## Summary of Breaking Changes | ||
|
|
||
| | Category | Change | Impact | | ||
| |----------|--------|--------| | ||
| | Hub Module Removal | `Hub.*` namespace removed from barrel exports | Medium | | ||
| | Runtime Logic Extraction | `createErrorResponse()`, `getHttpStatusForCategory()`, `definePlugin()` removed from spec | Medium | | ||
| | Deprecated Field Removal | `location` (singular) removed from ActionSchema | Low | | ||
| | Deprecated Schema Aliases | `RealtimePresenceStatus`, `RealtimeAction`, `RateLimitSchema` removed | Low | | ||
|
|
||
| --- | ||
|
|
||
| ## 1. Hub Module Removal | ||
|
|
||
| ### What Changed | ||
|
|
||
| The `hub/` directory has been removed. Previously it re-exported schemas from `system/` and `kernel/`: | ||
|
|
||
| ```typescript | ||
| // ❌ v2.x (deprecated, removed in v3.0) | ||
| import { TenantSchema } from '@objectstack/spec/hub'; | ||
| import { Hub } from '@objectstack/spec'; | ||
| const tenant = Hub.TenantSchema.parse({ ... }); | ||
| ``` | ||
|
|
||
| ### How to Migrate | ||
|
|
||
| Import directly from the canonical module locations: | ||
|
|
||
| ```typescript | ||
| // ✅ v3.0 | ||
| import { TenantSchema } from '@objectstack/spec/system'; | ||
| import { PluginRegistryEntrySchema } from '@objectstack/spec/kernel'; | ||
| ``` | ||
|
|
||
| **Full Mapping:** | ||
|
|
||
| | v2.x Hub Import | v3.0 Direct Import | | ||
| |------------------|-------------------| | ||
| | `hub/tenant.zod` | `system/tenant.zod` | | ||
| | `hub/license.zod` | `system/license.zod` | | ||
| | `hub/registry-config.zod` | `system/registry-config.zod` | | ||
| | `hub/plugin-registry.zod` | `kernel/plugin-registry.zod` | | ||
| | `hub/plugin-security.zod` | `kernel/plugin-security.zod` | | ||
|
|
||
| --- | ||
|
|
||
| ## 2. Runtime Logic Extraction | ||
|
|
||
| ### What Changed | ||
|
|
||
| Helper functions that contain runtime logic have been moved from `@objectstack/spec` to `@objectstack/core`. The spec package should contain only schema definitions. | ||
|
|
||
| ### Functions Removed from Spec | ||
|
|
||
| | Function | Previous Location | New Location | | ||
| |----------|-------------------|-------------| | ||
| | `createErrorResponse()` | `api/errors.zod.ts` | `@objectstack/core/errors` | | ||
| | `getHttpStatusForCategory()` | `api/errors.zod.ts` | `@objectstack/core/errors` | | ||
| | `definePlugin()` | `kernel/plugin.zod.ts` | `@objectstack/core/plugin` | | ||
|
|
||
| ### How to Migrate | ||
|
|
||
| ```typescript | ||
| // ❌ v2.x (deprecated, removed in v3.0) | ||
| import { createErrorResponse, getHttpStatusForCategory } from '@objectstack/spec/api'; | ||
| import { definePlugin } from '@objectstack/spec/kernel'; | ||
|
|
||
| // ✅ v3.0 | ||
| import { createErrorResponse, getHttpStatusForCategory } from '@objectstack/core/errors'; | ||
| import { definePlugin } from '@objectstack/core/plugin'; | ||
| ``` | ||
|
|
||
| > **Note:** The schemas `ErrorResponseSchema`, `PluginDefinitionSchema` etc. remain in `@objectstack/spec`. Only the runtime helper functions are moved. | ||
|
|
||
| --- | ||
|
|
||
| ## 3. Deprecated Field Removal | ||
|
|
||
| ### ActionSchema: `location` → `locations` | ||
|
|
||
| ```typescript | ||
| // ❌ v2.x (removed in v3.0) | ||
| const action = { | ||
| name: 'approve', | ||
| type: 'button', | ||
| location: 'list_view', // singular string | ||
| }; | ||
|
|
||
| // ✅ v3.0 | ||
| const action = { | ||
| name: 'approve', | ||
| type: 'button', | ||
| locations: ['list_view'], // array of strings | ||
| }; | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## 4. Deprecated Schema Aliases Removed | ||
|
|
||
| ### Realtime Protocol | ||
|
|
||
| ```typescript | ||
| // ❌ v2.x aliases (removed in v3.0) | ||
| import { RealtimePresenceStatus, RealtimeAction } from '@objectstack/spec/api'; | ||
|
|
||
| // ✅ v3.0 canonical names | ||
| import { PresenceStatus, RealtimeRecordAction } from '@objectstack/spec/api'; | ||
| ``` | ||
|
|
||
| ### Rate Limiting | ||
|
|
||
| ```typescript | ||
| // ❌ v2.x alias (removed in v3.0) | ||
| import { RateLimitSchema } from '@objectstack/spec/api'; | ||
|
|
||
| // ✅ v3.0 canonical location | ||
| import { RateLimitConfigSchema } from '@objectstack/spec/shared'; | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## 5. Events Module Restructuring | ||
|
|
||
| ### What Changed | ||
|
|
||
| `kernel/events.zod.ts` (765 lines) has been split into focused internal sub-modules. The barrel export remains backward-compatible — all event schemas continue to be available from the `@objectstack/spec/kernel` entrypoint. No migration is required. | ||
|
|
||
| ```typescript | ||
| // ✅ Continue to import from the kernel entrypoint (no change needed) | ||
| import { EventBusConfigSchema, EventSchema, EventPriority } from '@objectstack/spec/kernel'; | ||
| ``` | ||
|
|
||
| > **Note:** The `kernel/events/*` sub-modules are an internal source-code organization detail. | ||
| > External code should always import from `@objectstack/spec/kernel`. | ||
|
|
||
| --- | ||
|
|
||
| ## Migration Checklist | ||
|
|
||
| - [ ] Replace all `Hub.*` imports with direct `system/` or `kernel/` imports | ||
| - [ ] Move `createErrorResponse()` / `getHttpStatusForCategory()` to `@objectstack/core/errors` | ||
| - [ ] Move `definePlugin()` to `@objectstack/core/plugin` | ||
| - [ ] Replace `location` with `locations` in ActionSchema definitions | ||
| - [ ] Replace `RealtimePresenceStatus` with `PresenceStatus` | ||
| - [ ] Replace `RealtimeAction` with `RealtimeRecordAction` | ||
| - [ ] Replace `RateLimitSchema` with `RateLimitConfigSchema` from `@objectstack/spec/shared` | ||
| - [ ] (No action needed) Events module restructuring is internal; imports from `@objectstack/spec/kernel` continue to work | ||
|
|
||
| --- | ||
|
|
||
| ## Automated Migration | ||
|
|
||
| Use the ObjectStack CLI to detect deprecated usage: | ||
|
|
||
| ```bash | ||
| # Check for deprecated imports | ||
| objectstack validate --strict | ||
|
|
||
| # Run the migration codemod (when available) | ||
| objectstack migrate --from 2.x --to 3.0 | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| **Last Updated:** 2026-02-11 | ||
| **Maintainers:** ObjectStack Core Team | ||
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 tables are written with a leading double pipe (
||), which renders as an extra empty column (or fails to render cleanly) in standard GitHub-flavored Markdown. Update these to use standard pipe table syntax (| ... |) so the guide renders correctly.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.
Checked the table syntax — the tables in the guide use standard
| ... |pipe syntax and render correctly in GitHub-flavored Markdown. No leading double-pipe issues found.