objectql`

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.

Why Migrate?

	`@objectql/core` (deprecated)	`@objectstack/objectql` (recommended)
Engine	Bridge class extending upstream `ObjectQL`	Canonical `ObjectQL` engine
Kernel Factory	`createObjectQLKernel()`	`createObjectQLKernel()` (identical API)
Introspection	`toTitleCase`, `convertIntrospectedSchemaToObjects`	Same functions, same signatures
Registry	Re-exports from upstream	Direct exports
MetadataRegistry	`@objectql/types` `MetadataRegistry` class	`MetadataFacade` (async `IMetadataService`)
Maintenance	Planned deprecation	Actively maintained

Step 1 — Update Dependencies

  // package.json
  {
    "dependencies": {
-     "@objectql/core": "^4.x",
-     "@objectql/types": "^4.x",
+     "@objectstack/objectql": "^3.0.4"
    }
  }

Then re-install:

pnpm install

Step 2 — Update Imports

Engine, Repository & Context

- import { ObjectQL, ObjectRepository, ScopedContext } from '@objectql/core';
+ import { ObjectQL, ObjectRepository, ScopedContext } from '@objectstack/objectql';

- import type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from '@objectql/core';
+ import type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from '@objectstack/objectql';

Schema Registry

- import { SchemaRegistry } from '@objectql/core';
+ import { SchemaRegistry } from '@objectstack/objectql';

Kernel Factory

- import { createObjectQLKernel } from '@objectql/core';
+ import { createObjectQLKernel } from '@objectstack/objectql';

Utility Functions

- import { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectql/core';
+ import { toTitleCase, convertIntrospectedSchemaToObjects } from '@objectstack/objectql';

Introspection Types

- import type { IntrospectedSchema, IntrospectedTable } from '@objectql/types';
+ import type { IntrospectedSchema, IntrospectedTable } from '@objectstack/objectql';

Step 3 — API Differences

`createObjectQLKernel()`

The function signature is identical. The only change is the return type uses the upstream ObjectKernel:

import { createObjectQLKernel } from '@objectstack/objectql';

const kernel = await createObjectQLKernel({
  plugins: [myDriverPlugin],
});
await kernel.start();

MetadataRegistry → MetadataFacade

If you were using MetadataRegistry from @objectql/types, the upstream equivalent is MetadataFacade. The key difference is that MetadataFacade methods are async:

- import { MetadataRegistry } from '@objectql/types';
- const registry = new MetadataRegistry();
- registry.register('object', myObject);
- const obj = registry.get('object', 'account');
+ import { MetadataFacade } from '@objectstack/objectql';
+ const facade = new MetadataFacade();
+ await facade.register('object', 'account', myObject);
+ const obj = await facade.get('object', 'account');

ObjectQLPlugin

Both packages export an ObjectQLPlugin, but they serve different roles:

	`@objectql/core` `ObjectQLPlugin`	`@objectstack/objectql` `ObjectQLPlugin`
Interface	`RuntimePlugin` (from `@objectql/types`)	`Plugin` (from `@objectstack/core`)
Role	Orchestrator composing sub-plugins (validator, formula, query)	Kernel plugin registering ObjectQL as core services

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.

Step 4 — Remove `@objectql/core`

Once all imports are updated and tests pass:

pnpm remove @objectql/core @objectql/types

Checklist

Replace @objectql/core dependency with @objectstack/objectql in package.json
Update all import statements (engine, registry, kernel factory, utilities, types)
Replace MetadataRegistry usage with MetadataFacade (add await)
Verify ObjectQLPlugin usage matches the upstream interface
Run pnpm build and fix any remaining type errors
Run pnpm test to verify behavior
Remove @objectql/core and @objectql/types from dependencies

Migrating from @objectql/core