Skip to content

Commit e82305d

Browse files
Copilothotlong
Copilot
and
hotlong
committed
docs: add deprecation notice to @objectql/core docs and migration guide
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
1 parent db48f14 commit e82305d

4 files changed

Lines changed: 152 additions & 4 deletions

File tree

‎content/docs/architecture/core.mdx‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
11
---
2-
title: "@objectql/core"
2+
title: "@objectql/core (Deprecated)"
33
description: The Runtime Engine - Core ORM, validation, and business logic compiler for ObjectQL
44
---
55

66
# @objectql/core
77

8+
<Callout type="warn" title="Deprecated">
9+
`@objectql/core` is deprecated. All core functionality is now available in [`@objectstack/objectql`](https://www.npmjs.com/package/@objectstack/objectql).
10+
See the [Migration Guide](/docs/guides/objectql-migration) for step-by-step instructions.
11+
</Callout>
12+
813
**The Runtime Engine**: The core ORM and business logic compiler for ObjectQL. This package transforms abstract metadata (defined in `@objectql/types`) into executable database operations, validations, and business rules.
914

1015
## Overview

‎content/docs/guides/meta.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
"pages": [
44
"error-handling",
55
"architecture",
6-
"migration-v5"
6+
"migration-v5",
7+
"objectql-migration"
78
]
89
}

‎content/docs/guides/objectql-migration.mdx‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
title: "Migrating from @objectql/core"
3+
description: "Step-by-step guide for migrating from @objectql/core to @objectstack/objectql"
4+
---
5+
6+
# Migrating from `@objectql/core` to `@objectstack/objectql`
7+
8+
All core functionality previously provided by `@objectql/core` is now available upstream in `@objectstack/objectql`. This guide walks you through migrating your project so that `@objectql/core` can be removed.
9+
10+
## Why Migrate?
11+
12+
| | `@objectql/core` (deprecated) | `@objectstack/objectql` (recommended) |
13+
| :--- | :--- | :--- |
14+
| **Engine** | Bridge class extending upstream `ObjectQL` | Canonical `ObjectQL` engine |
15+
| **Kernel Factory** | `createObjectQLKernel()` | `createObjectQLKernel()` (identical API) |
16+
| **Introspection** | `toTitleCase`, `convertIntrospectedSchemaToObjects` | Same functions, same signatures |
17+
| **Registry** | Re-exports from upstream | Direct exports |
18+
| **MetadataRegistry** | `@objectql/types` `MetadataRegistry` class | `MetadataFacade` (async `IMetadataService`) |
19+
| **Maintenance** | Planned deprecation | Actively maintained |
20+
21+
## Step 1 — Update Dependencies
22+
23+
```diff
24+
// package.json
25+
{
26+
"dependencies": {
27+
- "@objectql/core": "^4.x",
28+
- "@objectql/types": "^4.x",
29+
+ "@objectstack/objectql": "^3.1.0"
30+
}
31+
}
32+
```
33+
34+
Then re-install:
35+
36+
```bash
37+
pnpm install
38+
```
39+
40+
## Step 2 — Update Imports
41+
42+
### Engine, Repository & Context
43+
44+
```diff
45+
- import { ObjectQL, ObjectRepository, ScopedContext } from '@objectql/core';
46+
+ import { ObjectQL, ObjectRepository, ScopedContext } from '@objectstack/objectql';
47+
```
48+
49+
```diff
50+
- import type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from '@objectql/core';
51+
+ import type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from '@objectstack/objectql';
52+
```
53+
54+
### Schema Registry
55+
56+
```diff
57+
- import { SchemaRegistry } from '@objectql/core';
58+
+ import { SchemaRegistry } from '@objectstack/objectql';
59+
```
60+
61+
### Kernel Factory
62+
63+
```diff
64+
- import { createObjectQLKernel } from '@objectql/core';
65+
+ import { createObjectQLKernel } from '@objectstack/objectql';
66+
```
67+
68+
### Utility Functions
69+
70+
```diff
71+
- import { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectql/core';
72+
+ import { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectstack/objectql';
73+
```
74+
75+
### Introspection Types
76+
77+
```diff
78+
- import type { IntrospectedSchema, IntrospectedTable } from '@objectql/types';
79+
+ import type { IntrospectedSchema, IntrospectedTable } from '@objectstack/objectql';
80+
```
81+
82+
## Step 3 — API Differences
83+
84+
### `createObjectQLKernel()`
85+
86+
The function signature is identical. The only change is the return type uses the upstream `ObjectKernel`:
87+
88+
```typescript
89+
import { createObjectQLKernel } from '@objectstack/objectql';
90+
91+
const kernel = await createObjectQLKernel({
92+
plugins: [myDriverPlugin],
93+
});
94+
await kernel.bootstrap();
95+
```
96+
97+
### MetadataRegistry → MetadataFacade
98+
99+
If you were using `MetadataRegistry` from `@objectql/types`, the upstream equivalent is `MetadataFacade`. The key difference is that `MetadataFacade` methods are **async** (returns `Promise`):
100+
101+
```diff
102+
- import { MetadataRegistry } from '@objectql/types';
103+
- const registry = new MetadataRegistry();
104+
- registry.register('object', myObject);
105+
- const obj = registry.get('object', 'account');
106+
+ import { MetadataFacade } from '@objectstack/objectql';
107+
+ const facade = new MetadataFacade();
108+
+ await facade.register('object', 'account', myObject);
109+
+ const obj = await facade.get('object', 'account');
110+
```
111+
112+
### ObjectQLPlugin
113+
114+
Both packages export an `ObjectQLPlugin`, but they serve different roles:
115+
116+
| | `@objectql/core` `ObjectQLPlugin` | `@objectstack/objectql` `ObjectQLPlugin` |
117+
| :--- | :--- | :--- |
118+
| Interface | `RuntimePlugin` (from `@objectql/types`) | `Plugin` (from `@objectstack/core`) |
119+
| Role | Orchestrator composing sub-plugins (validator, formula, query) | Kernel plugin registering ObjectQL as core services |
120+
121+
If you were using the `@objectql/core` `ObjectQLPlugin` to compose sub-plugins (`ValidatorPlugin`, `FormulaPlugin`, `QueryPlugin`), those downstream plugins are **not** part of this migration — they remain in the `@objectql` ecosystem.
122+
123+
## Step 4 — Remove `@objectql/core`
124+
125+
Once all imports are updated and tests pass:
126+
127+
```bash
128+
pnpm remove @objectql/core @objectql/types
129+
```
130+
131+
## Checklist
132+
133+
- [ ] Replace `@objectql/core` dependency with `@objectstack/objectql` in `package.json`
134+
- [ ] Update all `import` statements (engine, registry, kernel factory, utilities, types)
135+
- [ ] Replace `MetadataRegistry` usage with `MetadataFacade` (add `await`)
136+
- [ ] Verify `ObjectQLPlugin` usage matches the upstream interface
137+
- [ ] Run `pnpm build` and fix any remaining type errors
138+
- [ ] Run `pnpm test` to verify behavior
139+
- [ ] Remove `@objectql/core` and `@objectql/types` from dependencies

‎packages/foundation/core/README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
# @objectql/core
22

3-
> **Implementation Status**: ✅ **Production Ready** - All core features fully implemented and tested. See [Implementation Status](https://github.com/objectstack-ai/objectql/blob/main/IMPLEMENTATION_STATUS.md) for complete details.
3+
> ⚠️ **DEPRECATED**: This package is deprecated. Use [`@objectstack/objectql`](https://www.npmjs.com/package/@objectstack/objectql) instead.
4+
> See the [Migration Guide](https://github.com/objectstack-ai/spec/blob/main/content/docs/guides/objectql-migration.mdx) for step-by-step instructions.
45
5-
The core ORM and runtime engine for ObjectQL. This package handles object querying, CRUD operations, database driver coordination, transaction management, and **metadata-driven validation**. As of version 4.0.0, it wraps the **ObjectKernel** for plugin architecture and lifecycle management.
6+
The core ORM and runtime engine for ObjectQL. All core functionality (ObjectQL engine, SchemaRegistry, createObjectQLKernel, utilities) is now available directly from `@objectstack/objectql`.
7+
8+
The `ObjectQLPlugin` (orchestrator composing sub-plugins like ValidatorPlugin, FormulaPlugin, QueryPlugin) remains in this package as it is specific to the `@objectql` ecosystem.
69

710
## Features
811

0 commit comments

Comments
 (0)