objectql-migration.mdx

title	Migrating from @objectql/core
description	Step-by-step guide for migrating from @objectql/core to @objectstack/objectql

Migrating from @objectql/core to @objectstack/objectql

Starting with @objectstack/objectql v3.1, all core functionality previously provided by @objectql/core is now available upstream. 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.1.0"
    }
  }

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 type { ObjectQLKernelOptions } from '@objectql/core';
+ import { createObjectQLKernel } from '@objectstack/objectql';
+ import type { ObjectQLKernelOptions } 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';

- import type { IntrospectedColumn, IntrospectedForeignKey } from '@objectql/types';
+ import type { IntrospectedColumn, IntrospectedForeignKey } 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.bootstrap();

convertIntrospectedSchemaToObjects()

Same signature and behavior:

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

const objects = convertIntrospectedSchemaToObjects(schema, {
  excludeTables: ['migrations'],
  includeTables: undefined,      // optional: whitelist
  skipSystemColumns: true,       // default: skips id, created_at, updated_at
});

MetadataRegistry → MetadataFacade

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

- 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
Methods	install(), onStart(), init(), start()	init(), start()

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 — Type Mapping Reference

The convertIntrospectedSchemaToObjects() utility maps database column types as follows:

Database Type	ObjectStack FieldType
varchar, char	text
text	textarea
integer, int, bigint, smallint	number
float, double, decimal, numeric, real	number
boolean, bool	boolean
timestamp, datetime	datetime
date	date
time	time
json, jsonb	json
Foreign key column	lookup (with reference set to target table)
anything else	text (fallback)

Step 5 — 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