Skip to content

Commit 3a9d142

Browse files
hotlonghotlong
authored
Merge pull request #390 from objectstack-ai/copilot/remove-objectql-core
2 parents 2c39775 + 41f9510 commit 3a9d142

14 files changed

Lines changed: 185 additions & 24 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.0.4"
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.start();
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**:
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

‎examples/showcase/enterprise-erp/src/plugins/audit/audit.plugin.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@
66
* LICENSE file in the root directory of this source tree.
77
*/
88

9-
// Import ObjectQLPlugin types from @objectql/core instead of @objectstack/runtime
10-
// to avoid ESM/CJS compatibility issues
9+
// Plugin types defined locally to avoid ESM/CJS compatibility issues
1110
type RuntimeContext = any;
1211

1312
interface ObjectQLPlugin {

‎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

‎packages/foundation/core/package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
{
22
"name": "@objectql/core",
33
"version": "4.2.1",
4-
"description": "Universal runtime engine for ObjectQL - AI-native metadata-driven ORM with validation, repository pattern, and driver orchestration",
4+
"deprecated": "Use @objectstack/objectql instead. See https://github.com/objectstack-ai/spec/blob/main/content/docs/guides/objectql-migration.mdx",
5+
"description": "DEPRECATED — Use @objectstack/objectql. Plugin orchestrator for ObjectQL sub-plugins (validator, formula, query).",
56
"keywords": [
67
"objectql",
78
"orm",

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

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,29 @@
11
/**
2-
* ObjectQL
2+
* ObjectQL Core — DEPRECATED
33
* Copyright (c) 2026-present ObjectStack Inc.
44
*
55
* This source code is licensed under the MIT license found in the
66
* LICENSE file in the root directory of this source tree.
7+
*
8+
* @deprecated This package is deprecated. Migrate to `@objectstack/objectql`.
9+
* See: https://github.com/objectstack-ai/spec/blob/main/content/docs/guides/objectql-migration.mdx
710
*/
811

9-
// ── Convenience factory ──
10-
export { createObjectQLKernel, type ObjectQLKernelOptions } from './kernel-factory';
11-
12-
// ── Re-export bridge engine (extends upstream with MetadataRegistry + legacy config) ──
12+
// ── Bridge engine (deprecated — use @objectstack/objectql ObjectQL directly) ──
13+
/** @deprecated Import ObjectQL from `@objectstack/objectql` instead. This bridge class will be removed in a future version. */
1314
export { ObjectQL, type ObjectQLConfig } from './app';
15+
16+
// ── Convenience factory (local implementation — wraps upstream kernel) ──
17+
export { createObjectQLKernel } from './kernel-factory';
18+
export type { ObjectQLKernelOptions } from './kernel-factory';
19+
20+
// ── Re-exports from @objectstack/objectql (deprecated — import directly from upstream) ──
21+
/** @deprecated Import from `@objectstack/objectql` instead. */
1422
export { ObjectRepository, ScopedContext, SchemaRegistry } from '@objectstack/objectql';
23+
/** @deprecated Import from `@objectstack/objectql` instead. */
24+
export { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectstack/objectql';
25+
/** @deprecated Import from `@objectstack/objectql` instead. */
1526
export type { HookHandler, HookEntry, OperationContext, EngineMiddleware, ObjectQLHostContext } from '@objectstack/objectql';
1627

17-
// ── Plugin orchestration ──
28+
// ── Plugin orchestration (downstream — stays in @objectql ecosystem) ──
1829
export * from './plugin';
19-
20-
// ── Utilities ──
21-
export * from './util';

‎packages/foundation/platform-node/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
"test": "vitest run"
2828
},
2929
"dependencies": {
30-
"@objectql/core": "workspace:*",
30+
"@objectstack/objectql": "^3.0.4",
3131
"@objectql/types": "workspace:*",
3232
"@objectstack/spec": "^3.0.4",
3333
"fast-glob": "^3.3.2",

‎packages/foundation/platform-node/src/loader.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ import * as glob from 'fast-glob';
1111
import * as path from 'path';
1212
import { MetadataRegistry, ObjectConfig, LoaderPlugin, LoaderHandlerContext, FieldConfig } from '@objectql/types';
1313
import * as yaml from 'js-yaml';
14-
import { toTitleCase } from '@objectql/core';
14+
import { toTitleCase } from '@objectstack/objectql';
1515

1616
export class ObjectLoader {
1717
private plugins: LoaderPlugin[] = [];

‎packages/tools/cli/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
},
3131
"dependencies": {
3232
"@objectql/types": "workspace:*",
33+
"@objectstack/objectql": "^3.0.4",
3334
"@objectql/core": "workspace:*",
3435
"@objectql/plugin-validator": "workspace:*",
3536
"@objectql/driver-sql": "workspace:*",

0 commit comments

Comments
 (0)