Skip to content

Commit e8b6c9a

Browse files
Copilothotlong
Copilot
and
hotlong
committed
feat: Add comprehensive deprecation warnings and type compatibility tests (v4.0.0-alpha.1)
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent 7486e91 commit e8b6c9a

3 files changed

Lines changed: 228 additions & 2 deletions

File tree

‎packages/foundation/types/CHANGELOG.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,90 @@
11
# @objectql/types
22

3+
## 4.0.0-alpha.1 - 2026-01-22
4+
5+
### 🎯 Major Changes - Plugin Architecture Migration
6+
7+
This version marks the beginning of the migration to position ObjectQL as a query extension plugin for @objectstack/runtime. The package is being refactored to contain only query-specific types.
8+
9+
### Added
10+
11+
- **Query-Specific Type Organization**: Reorganized exports into clear sections
12+
- Query-Specific Types (Core ObjectQL features)
13+
- Re-exports from @objectstack (Backward compatibility)
14+
- ObjectQL-Owned Types (May migrate in future)
15+
16+
- **Comprehensive Deprecation Warnings**: Added detailed JSDoc deprecation notices
17+
- `FilterCondition` - Use `@objectstack/spec` instead
18+
- `RuntimePlugin` - Use `@objectstack/runtime` instead
19+
- Includes migration examples in documentation
20+
21+
- **Migration Documentation**:
22+
- `TYPE_MIGRATION.md` - Detailed type-by-type migration tracking
23+
- `README_V4.md` - v4.0 documentation with migration guide
24+
- Clear migration examples in deprecation warnings
25+
26+
- **Package Metadata Updates**:
27+
- Added `objectstack-plugin` keyword
28+
- Added peerDependencies for `@objectstack/spec` and `@objectstack/runtime`
29+
- Updated description to reflect plugin architecture
30+
31+
### Changed
32+
33+
- **Package Description**: Now "Query-specific type definitions for ObjectQL - A plugin for @objectstack/runtime"
34+
- **Package Keywords**: Updated to emphasize query focus and plugin architecture
35+
- **Version**: 3.0.1 → 4.0.0-alpha.1 (breaking changes in future)
36+
37+
### Deprecated
38+
39+
The following types are re-exported for backward compatibility but will be removed in v5.0.0:
40+
41+
- `FilterCondition` - Import from `@objectstack/spec` instead
42+
- `RuntimePlugin` - Import from `@objectstack/runtime` instead
43+
44+
More types will be deprecated in future alpha releases as they migrate to @objectstack packages.
45+
46+
### Migration Guide
47+
48+
#### v3.x to v4.0 Migration
49+
50+
**Option 1: Update Imports (Recommended)**
51+
52+
```typescript
53+
// Before (v3.x)
54+
import { FilterCondition, UnifiedQuery } from '@objectql/types';
55+
56+
// After (v4.0 - Recommended)
57+
import { FilterCondition } from '@objectstack/spec';
58+
import { UnifiedQuery } from '@objectql/types';
59+
```
60+
61+
**Option 2: Use Re-exports (Temporary)**
62+
63+
```typescript
64+
// Still works in v4.0 but deprecated
65+
import { FilterCondition, UnifiedQuery } from '@objectql/types';
66+
```
67+
68+
#### Deprecation Timeline
69+
70+
- **v4.0-alpha**: Re-exports available with deprecation warnings
71+
- **v4.0-beta**: All re-exports finalized
72+
- **v4.0**: Stable release with full backward compatibility
73+
- **v4.x**: Re-exports maintained throughout v4 lifecycle
74+
- **v5.0**: Re-exports removed (breaking change)
75+
76+
### Notes
77+
78+
#### Query-Specific Types (Staying in @objectql/types)
79+
80+
- `UnifiedQuery`, `Filter`, `AggregateOption`
81+
- `IntrospectedTable`, `IntrospectedColumn`, `IntrospectedForeignKey`
82+
- `ObjectQLRepository`
83+
84+
See `TYPE_MIGRATION.md` for complete details.
85+
86+
---
87+
388
## 3.0.1
489

590
### Patch Changes

‎packages/foundation/types/src/__tests__/type-compatibility.test.ts‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
/**
2+
* Type Compatibility Tests for @objectql/types v4.0
3+
*
4+
* These tests ensure backward compatibility with v3.x while
5+
* validating the new v4.0 import patterns.
6+
*/
7+
8+
// ============================================================================
9+
// TEST 1: Query-Specific Types (Should always work from @objectql/types)
10+
// ============================================================================
11+
12+
import type {
13+
UnifiedQuery,
14+
Filter,
15+
AggregateOption,
16+
IntrospectedTable
17+
} from '../index';
18+
19+
describe('@objectql/types v4.0 - Type Compatibility', () => {
20+
it('should support UnifiedQuery type', () => {
21+
const testQuery: UnifiedQuery = {
22+
fields: ['id', 'name', 'email'],
23+
filters: {
24+
status: 'active',
25+
age: { $gte: 18 }
26+
},
27+
sort: [['created_at', 'desc']],
28+
skip: 0,
29+
limit: 10
30+
};
31+
32+
expect(testQuery).toBeDefined();
33+
expect(testQuery.fields).toHaveLength(3);
34+
});
35+
36+
it('should support Filter type', () => {
37+
const testFilter: Filter = {
38+
$and: [
39+
{ status: 'active' },
40+
{ age: { $gte: 18, $lte: 65 } }
41+
]
42+
};
43+
44+
expect(testFilter).toBeDefined();
45+
});
46+
47+
it('should support AggregateOption type', () => {
48+
const testAggregation: AggregateOption = {
49+
func: 'sum',
50+
field: 'amount',
51+
alias: 'total_amount'
52+
};
53+
54+
expect(testAggregation.func).toBe('sum');
55+
});
56+
57+
it('should support IntrospectedTable type', () => {
58+
const testTable: IntrospectedTable = {
59+
name: 'users',
60+
columns: [
61+
{
62+
name: 'id',
63+
type: 'integer',
64+
nullable: false,
65+
isPrimary: true
66+
}
67+
],
68+
foreignKeys: []
69+
};
70+
71+
expect(testTable.name).toBe('users');
72+
expect(testTable.columns).toHaveLength(1);
73+
});
74+
});
75+
76+
// ============================================================================
77+
// TEST 2: Re-exported Types (Deprecated but should still work)
78+
// ============================================================================
79+
80+
import type { FilterCondition, RuntimePlugin } from '../index';
81+
82+
describe('@objectql/types v4.0 - Deprecated Re-exports', () => {
83+
it('should support FilterCondition re-export (deprecated)', () => {
84+
const testFilterCondition: FilterCondition = {
85+
field: 'status',
86+
operator: '=',
87+
value: 'active'
88+
};
89+
90+
expect(testFilterCondition.field).toBe('status');
91+
});
92+
93+
it('should support RuntimePlugin re-export (deprecated)', () => {
94+
const testPlugin: RuntimePlugin = {
95+
name: 'test-plugin',
96+
async install() {},
97+
async onStart() {}
98+
};
99+
100+
expect(testPlugin.name).toBe('test-plugin');
101+
});
102+
});

‎packages/foundation/types/src/index.ts‎

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,52 @@ export * from './repository';
4040
// ============================================================================
4141
// These types are defined in @objectstack but re-exported here for backward
4242
// compatibility. They will be removed in v5.0.0.
43+
//
44+
// Migration Guide:
45+
// - Old: import { FilterCondition } from '@objectql/types';
46+
// - New: import { FilterCondition } from '@objectstack/spec';
4347

44-
/** @deprecated Use @objectstack/spec directly. Will be removed in v5.0 */
48+
/**
49+
* @deprecated Import from @objectstack/spec directly.
50+
*
51+
* This re-export will be removed in v5.0.0.
52+
*
53+
* @example
54+
* ```typescript
55+
* // Old (v3.x - deprecated)
56+
* import { FilterCondition } from '@objectql/types';
57+
*
58+
* // New (v4.0+ - recommended)
59+
* import { FilterCondition } from '@objectstack/spec';
60+
* ```
61+
*/
4562
export type { FilterCondition } from '@objectstack/spec';
4663

47-
/** @deprecated Use @objectstack/runtime directly. Will be removed in v5.0 */
64+
/**
65+
* @deprecated Import from @objectstack/runtime directly.
66+
*
67+
* This re-export will be removed in v5.0.0.
68+
*
69+
* @example
70+
* ```typescript
71+
* // Old (v3.x - deprecated)
72+
* import { RuntimePlugin } from '@objectql/types';
73+
*
74+
* // New (v4.0+ - recommended)
75+
* import { RuntimePlugin } from '@objectstack/runtime';
76+
* ```
77+
*/
4878
export type { RuntimePlugin } from '@objectstack/runtime';
4979

80+
// TODO: Add remaining re-exports in future commits
81+
// - DriverInterface from @objectstack/spec
82+
// - MetadataRegistry from @objectstack/types (when available)
83+
// - ObjectConfig from @objectstack/types (when available)
84+
// - FieldConfig from @objectstack/types (when available)
85+
// - ObjectQLContext from @objectstack/types (when available)
86+
// - HookHandler from @objectstack/runtime (when available)
87+
// - ActionHandler from @objectstack/runtime (when available)
88+
5089

5190
// ============================================================================
5291
// OBJECTQL-OWNED TYPES (Kept for now, may migrate later)

0 commit comments

Comments
 (0)