|
| 1 | +# ObjectStack v3.0 Migration Guide |
| 2 | + |
| 3 | +> **Target Release:** Q2 2026 |
| 4 | +> **Breaking Changes:** Deprecated items removed, hub module consolidated |
| 5 | +> **Prerequisite:** Ensure your project is on v2.x with all deprecation warnings resolved |
| 6 | +
|
| 7 | +--- |
| 8 | + |
| 9 | +## Summary of Breaking Changes |
| 10 | + |
| 11 | +| Category | Change | Impact | |
| 12 | +|----------|--------|--------| |
| 13 | +| Hub Module Removal | `Hub.*` namespace removed from barrel exports | Medium | |
| 14 | +| Runtime Logic Extraction | `createErrorResponse()`, `getHttpStatusForCategory()`, `definePlugin()` removed from spec | Medium | |
| 15 | +| Deprecated Field Removal | `location` (singular) removed from ActionSchema | Low | |
| 16 | +| Deprecated Schema Aliases | `RealtimePresenceStatus`, `RealtimeAction`, `RateLimitSchema` removed | Low | |
| 17 | + |
| 18 | +--- |
| 19 | + |
| 20 | +## 1. Hub Module Removal |
| 21 | + |
| 22 | +### What Changed |
| 23 | + |
| 24 | +The `hub/` directory has been removed. Previously it re-exported schemas from `system/` and `kernel/`: |
| 25 | + |
| 26 | +```typescript |
| 27 | +// ❌ v2.x (deprecated, removed in v3.0) |
| 28 | +import { TenantSchema } from '@objectstack/spec/hub'; |
| 29 | +import { Hub } from '@objectstack/spec'; |
| 30 | +const tenant = Hub.TenantSchema.parse({ ... }); |
| 31 | +``` |
| 32 | + |
| 33 | +### How to Migrate |
| 34 | + |
| 35 | +Import directly from the canonical module locations: |
| 36 | + |
| 37 | +```typescript |
| 38 | +// ✅ v3.0 |
| 39 | +import { TenantSchema } from '@objectstack/spec/system'; |
| 40 | +import { PluginRegistryEntrySchema } from '@objectstack/spec/kernel'; |
| 41 | +``` |
| 42 | + |
| 43 | +**Full Mapping:** |
| 44 | + |
| 45 | +| v2.x Hub Import | v3.0 Direct Import | |
| 46 | +|------------------|-------------------| |
| 47 | +| `hub/tenant.zod` | `system/tenant.zod` | |
| 48 | +| `hub/license.zod` | `system/license.zod` | |
| 49 | +| `hub/registry-config.zod` | `system/registry-config.zod` | |
| 50 | +| `hub/plugin-registry.zod` | `kernel/plugin-registry.zod` | |
| 51 | +| `hub/plugin-security.zod` | `kernel/plugin-security.zod` | |
| 52 | + |
| 53 | +--- |
| 54 | + |
| 55 | +## 2. Runtime Logic Extraction |
| 56 | + |
| 57 | +### What Changed |
| 58 | + |
| 59 | +Helper functions that contain runtime logic have been moved from `@objectstack/spec` to `@objectstack/core`. The spec package should contain only schema definitions. |
| 60 | + |
| 61 | +### Functions Removed from Spec |
| 62 | + |
| 63 | +| Function | Previous Location | New Location | |
| 64 | +|----------|-------------------|-------------| |
| 65 | +| `createErrorResponse()` | `api/errors.zod.ts` | `@objectstack/core/errors` | |
| 66 | +| `getHttpStatusForCategory()` | `api/errors.zod.ts` | `@objectstack/core/errors` | |
| 67 | +| `definePlugin()` | `kernel/plugin.zod.ts` | `@objectstack/core/plugin` | |
| 68 | + |
| 69 | +### How to Migrate |
| 70 | + |
| 71 | +```typescript |
| 72 | +// ❌ v2.x (deprecated, removed in v3.0) |
| 73 | +import { createErrorResponse, getHttpStatusForCategory } from '@objectstack/spec/api'; |
| 74 | +import { definePlugin } from '@objectstack/spec/kernel'; |
| 75 | + |
| 76 | +// ✅ v3.0 |
| 77 | +import { createErrorResponse, getHttpStatusForCategory } from '@objectstack/core/errors'; |
| 78 | +import { definePlugin } from '@objectstack/core/plugin'; |
| 79 | +``` |
| 80 | + |
| 81 | +> **Note:** The schemas `ErrorResponseSchema`, `PluginDefinitionSchema` etc. remain in `@objectstack/spec`. Only the runtime helper functions are moved. |
| 82 | +
|
| 83 | +--- |
| 84 | + |
| 85 | +## 3. Deprecated Field Removal |
| 86 | + |
| 87 | +### ActionSchema: `location` → `locations` |
| 88 | + |
| 89 | +```typescript |
| 90 | +// ❌ v2.x (removed in v3.0) |
| 91 | +const action = { |
| 92 | + name: 'approve', |
| 93 | + type: 'button', |
| 94 | + location: 'list_view', // singular string |
| 95 | +}; |
| 96 | + |
| 97 | +// ✅ v3.0 |
| 98 | +const action = { |
| 99 | + name: 'approve', |
| 100 | + type: 'button', |
| 101 | + locations: ['list_view'], // array of strings |
| 102 | +}; |
| 103 | +``` |
| 104 | + |
| 105 | +--- |
| 106 | + |
| 107 | +## 4. Deprecated Schema Aliases Removed |
| 108 | + |
| 109 | +### Realtime Protocol |
| 110 | + |
| 111 | +```typescript |
| 112 | +// ❌ v2.x aliases (removed in v3.0) |
| 113 | +import { RealtimePresenceStatus, RealtimeAction } from '@objectstack/spec/api'; |
| 114 | + |
| 115 | +// ✅ v3.0 canonical names |
| 116 | +import { PresenceStatus, RealtimeRecordAction } from '@objectstack/spec/api'; |
| 117 | +``` |
| 118 | + |
| 119 | +### Rate Limiting |
| 120 | + |
| 121 | +```typescript |
| 122 | +// ❌ v2.x alias (removed in v3.0) |
| 123 | +import { RateLimitSchema } from '@objectstack/spec/api/endpoint'; |
| 124 | + |
| 125 | +// ✅ v3.0 canonical location |
| 126 | +import { RateLimitConfigSchema } from '@objectstack/spec/shared/http'; |
| 127 | +``` |
| 128 | + |
| 129 | +--- |
| 130 | + |
| 131 | +## 5. Events Module Restructuring |
| 132 | + |
| 133 | +### What Changed |
| 134 | + |
| 135 | +`kernel/events.zod.ts` (765 lines) has been split into focused sub-modules for better tree-shaking. The barrel export remains backward-compatible, but you can now import from specific sub-modules. |
| 136 | + |
| 137 | +### Optional Migration (Recommended) |
| 138 | + |
| 139 | +```typescript |
| 140 | +// ✅ Both work in v3.0 (barrel re-export is backward compatible) |
| 141 | +import { EventBusConfigSchema } from '@objectstack/spec/kernel'; |
| 142 | + |
| 143 | +// ✅ Preferred: Direct sub-module import for better tree-shaking |
| 144 | +import { EventBusConfigSchema } from '@objectstack/spec/kernel/events/bus'; |
| 145 | +import { EventSchema, EventPriority } from '@objectstack/spec/kernel/events/core'; |
| 146 | +import { EventWebhookConfigSchema } from '@objectstack/spec/kernel/events/integrations'; |
| 147 | +``` |
| 148 | + |
| 149 | +**Sub-module Map:** |
| 150 | + |
| 151 | +| Sub-module | Contains | |
| 152 | +|-----------|----------| |
| 153 | +| `events/core.zod` | `EventPriority`, `EventMetadataSchema`, `EventSchema`, `EventTypeDefinitionSchema` | |
| 154 | +| `events/handlers.zod` | `EventHandlerSchema`, `EventRouteSchema`, `EventPersistenceSchema` | |
| 155 | +| `events/queue.zod` | `EventQueueConfigSchema`, `EventReplayConfigSchema`, `EventSourcingConfigSchema` | |
| 156 | +| `events/dlq.zod` | `DeadLetterQueueEntrySchema`, `EventLogEntrySchema` | |
| 157 | +| `events/integrations.zod` | `EventWebhookConfigSchema`, `EventMessageQueueConfigSchema`, `RealTimeNotificationConfigSchema` | |
| 158 | +| `events/bus.zod` | `EventBusConfigSchema`, helper functions | |
| 159 | + |
| 160 | +--- |
| 161 | + |
| 162 | +## Migration Checklist |
| 163 | + |
| 164 | +- [ ] Replace all `Hub.*` imports with direct `system/` or `kernel/` imports |
| 165 | +- [ ] Move `createErrorResponse()` / `getHttpStatusForCategory()` to `@objectstack/core/errors` |
| 166 | +- [ ] Move `definePlugin()` to `@objectstack/core/plugin` |
| 167 | +- [ ] Replace `location` with `locations` in ActionSchema definitions |
| 168 | +- [ ] Replace `RealtimePresenceStatus` with `PresenceStatus` |
| 169 | +- [ ] Replace `RealtimeAction` with `RealtimeRecordAction` |
| 170 | +- [ ] Replace `RateLimitSchema` with `RateLimitConfigSchema` from `shared/http` |
| 171 | +- [ ] (Optional) Update events imports to use sub-modules for tree-shaking |
| 172 | + |
| 173 | +--- |
| 174 | + |
| 175 | +## Automated Migration |
| 176 | + |
| 177 | +Use the ObjectStack CLI to detect deprecated usage: |
| 178 | + |
| 179 | +```bash |
| 180 | +# Check for deprecated imports |
| 181 | +objectstack validate --strict |
| 182 | + |
| 183 | +# Run the migration codemod (when available) |
| 184 | +objectstack migrate --from 2.x --to 3.0 |
| 185 | +``` |
| 186 | + |
| 187 | +--- |
| 188 | + |
| 189 | +**Last Updated:** 2026-02-11 |
| 190 | +**Maintainers:** ObjectStack Core Team |
0 commit comments