refactor: migrate throw new Error to throw new ObjectQLError across 8 source files

Copilot · hotlong · Copilot · commit 04ae4ab8363e · 2026-02-09T16:17:06.000Z
Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/packages/foundation/edge-adapter/src/plugin.ts b/packages/foundation/edge-adapter/src/plugin.ts
@@ -6,6 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import { ObjectQLError } from '@objectql/types';
 import type { RuntimePlugin, RuntimeContext, EdgeAdapterConfig } from '@objectql/types';
 import { detectRuntime } from './detector.js';
 import { validateCapabilities, getCapabilities, type CapabilityRequirement } from './capabilities.js';
@@ -52,9 +53,10 @@ export class EdgeAdapterPlugin implements RuntimePlugin {
         if (this.config.requirements) {
             const validation = validateCapabilities(runtime, this.config.requirements);
             if (!validation.valid) {
-                throw new Error(
-                    `[${this.name}] Runtime '${runtime}' missing capabilities: ${validation.missing.join(', ')}`,
-                );
+                throw new ObjectQLError({
+                    code: 'CONFIG_ERROR',
+                    message: `[${this.name}] Runtime '${runtime}' missing capabilities: ${validation.missing.join(', ')}`,
+                });
             }
         }
 
diff --git a/packages/foundation/platform-node/src/driver.ts b/packages/foundation/platform-node/src/driver.ts
@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { Driver } from '@objectql/types';
+import { Driver, ObjectQLError } from '@objectql/types';
 
 export function createDriverFromConnection(connection: string): Driver {
     let driverPackage = '';
@@ -45,18 +45,18 @@ export function createDriverFromConnection(connection: string): Driver {
         };
     }
     else {
-        throw new Error(`Unsupported connection protocol: ${connection}`);
+        throw new ObjectQLError({ code: 'DRIVER_UNSUPPORTED_OPERATION', message: `Unsupported connection protocol: ${connection}` });
     }
 
     try {
          
         const pkg = require(driverPackage);
         const DriverClass = pkg[driverClass];
         if (!DriverClass) {
-            throw new Error(`${driverClass} not found in ${driverPackage}`);
+            throw new ObjectQLError({ code: 'DRIVER_ERROR', message: `${driverClass} not found in ${driverPackage}` });
         }
         return new DriverClass(driverConfig);
     } catch (e: any) {
-        throw new Error(`Failed to load driver ${driverPackage}. Please install it: npm install ${driverPackage}. Error: ${e.message}`);
+        throw new ObjectQLError({ code: 'DRIVER_ERROR', message: `Failed to load driver ${driverPackage}. Please install it: npm install ${driverPackage}. Error: ${e.message}` });
     }
 }
diff --git a/packages/foundation/platform-node/src/plugin.ts b/packages/foundation/platform-node/src/plugin.ts
@@ -7,6 +7,7 @@
  */
 
 import { Kernel } from '@objectstack/spec';
+import { ObjectQLError } from '@objectql/types';
 type PluginDefinition = Kernel.PluginDefinition;
 
 export function loadPlugin(packageName: string): PluginDefinition {
@@ -15,7 +16,7 @@ export function loadPlugin(packageName: string): PluginDefinition {
         const modulePath = require.resolve(packageName, { paths: [process.cwd()] });
         mod = require(modulePath);
     } catch (e) {
-        throw new Error(`Failed to resolve plugin '${packageName}': ${e}`);
+        throw new ObjectQLError({ code: 'CONFIG_ERROR', message: `Failed to resolve plugin '${packageName}': ${e}` });
     }
 
     // Helper to check if candidate is a PluginDefinition
@@ -74,6 +75,6 @@ export function loadPlugin(packageName: string): PluginDefinition {
         return instance;
     } else {
         console.error(`[PluginLoader] Failed to find plugin in '${packageName}'. Exports:`, Object.keys(mod));
-        throw new Error(`Plugin '${packageName}' must export a PluginDefinition with lifecycle hooks (onEnable, onDisable, etc.).`);
+        throw new ObjectQLError({ code: 'CONFIG_ERROR', message: `Plugin '${packageName}' must export a PluginDefinition with lifecycle hooks (onEnable, onDisable, etc.).` });
     }
 }
diff --git a/packages/foundation/plugin-security/src/query-trimmer.ts b/packages/foundation/plugin-security/src/query-trimmer.ts
@@ -6,6 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import { ObjectQLError } from '@objectql/types';
 import type { PermissionConfig, RecordRuleCondition } from '@objectql/types';
 import type { SecurityContext } from './types';
 import { PermissionLoader } from './permission-loader';
@@ -279,7 +280,7 @@ export class QueryTrimmer {
     }
     
     // Unable to convert formula to filter
-    throw new Error(`Unsupported formula pattern: ${formula}`);
+    throw new ObjectQLError({ code: 'INTERNAL_ERROR', message: `Unsupported formula pattern: ${formula}` });
   }
   
   /**
@@ -353,7 +354,7 @@ export class QueryTrimmer {
     const nestedFilter = this.conditionToFilter(nestedCondition, user);
     
     if (Object.keys(nestedFilter).length === 0) {
-      throw new Error('Unable to convert nested lookup condition');
+      throw new ObjectQLError({ code: 'INTERNAL_ERROR', message: 'Unable to convert nested lookup condition' });
     }
     
     // Create a lookup filter
diff --git a/packages/foundation/plugin-workflow/src/engine/action-executor.ts b/packages/foundation/plugin-workflow/src/engine/action-executor.ts
@@ -13,6 +13,7 @@
  * Actions are side effects that occur during state transitions.
  */
 
+import { ObjectQLError } from '@objectql/types';
 import type { ExecutionContext, ActionResult } from '../types';
 
 /**
@@ -167,7 +168,7 @@ export class ActionExecutor {
   private executeFieldUpdate(expr: string, record: Record<string, any>): void {
     const equalIndex = expr.indexOf('=');
     if (equalIndex === -1) {
-      throw new Error(`Invalid field update expression: ${expr}`);
+      throw new ObjectQLError({ code: 'WORKFLOW_TRANSITION_DENIED', message: `Invalid field update expression: ${expr}` });
     }
 
     const fieldName = expr.substring(0, equalIndex).trim();
diff --git a/packages/tools/cli/src/commands/migrate.ts b/packages/tools/cli/src/commands/migrate.ts
@@ -9,6 +9,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
+import { ObjectQLError } from '@objectql/types';
 import { resolveConfigFile } from '../utils/config-loader';
 
 interface MigrateOptions {
@@ -274,7 +275,7 @@ async function loadObjectQLInstance(configPath?: string): Promise<any> {
     const app = configModule.default || configModule.app || configModule.objectql || configModule.db;
 
     if (!app) {
-        throw new Error('Config file must export an ObjectQL instance');
+        throw new ObjectQLError({ code: 'CONFIG_ERROR', message: 'Config file must export an ObjectQL instance' });
     }
 
     await app.init();
diff --git a/packages/tools/cli/src/commands/sync.ts b/packages/tools/cli/src/commands/sync.ts
@@ -10,7 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
 import * as yaml from 'js-yaml';
-import { IntrospectedSchema, IntrospectedTable, IntrospectedColumn, ObjectConfig, IObjectQL, FieldConfig, FieldType } from '@objectql/types';
+import { IntrospectedSchema, IntrospectedTable, IntrospectedColumn, ObjectConfig, IObjectQL, FieldConfig, FieldType, ObjectQLError } from '@objectql/types';
 import { resolveConfigFile } from '../utils/config-loader';
 
 interface SyncOptions {
@@ -45,7 +45,7 @@ export async function syncDatabase(options: SyncOptions) {
         if (!driver || !driver.introspectSchema) {
             const errorMsg = 'The configured driver does not support schema introspection. Only SQL drivers (PostgreSQL, MySQL, SQLite) support this feature.';
             console.error(chalk.red(`❌ ${errorMsg}`));
-            throw new Error(errorMsg);
+            throw new ObjectQLError({ code: 'DRIVER_UNSUPPORTED_OPERATION', message: errorMsg });
         }
 
         // Introspect database schema
@@ -291,7 +291,7 @@ async function loadObjectQLInstance(configPath?: string): Promise<IObjectQL> {
                 }
             });
         } catch (err) {
-            throw new Error('TypeScript config file detected but ts-node is not installed. Please run: npm install --save-dev ts-node');
+            throw new ObjectQLError({ code: 'CONFIG_ERROR', message: 'TypeScript config file detected but ts-node is not installed. Please run: npm install --save-dev ts-node' });
         }
     }
 
@@ -309,7 +309,7 @@ async function loadObjectQLInstance(configPath?: string): Promise<IObjectQL> {
     const app = configModule.default || configModule.app || configModule.objectql || configModule.db;
 
     if (!app) {
-        throw new Error('Config file must export an ObjectQL instance as default export or named export (app/objectql/db)');
+        throw new ObjectQLError({ code: 'CONFIG_ERROR', message: 'Config file must export an ObjectQL instance as default export or named export (app/objectql/db)' });
     }
 
     // Initialize app (but don't sync schema - we're reading it)
diff --git a/packages/tools/cli/src/utils/config-loader.ts b/packages/tools/cli/src/utils/config-loader.ts
@@ -8,6 +8,7 @@
 
 import * as path from 'path';
 import * as fs from 'fs';
+import { ObjectQLError } from '@objectql/types';
 
 /**
  * Config file search order:
@@ -36,7 +37,7 @@ export function resolveConfigFile(configPath?: string, cwd: string = process.cwd
     if (configPath) {
         const resolved = path.isAbsolute(configPath) ? configPath : path.join(cwd, configPath);
         if (!fs.existsSync(resolved)) {
-            throw new Error(`Configuration file not found: ${resolved}`);
+            throw new ObjectQLError({ code: 'CONFIG_ERROR', message: `Configuration file not found: ${resolved}` });
         }
         return resolved;
     }
@@ -48,11 +49,12 @@ export function resolveConfigFile(configPath?: string, cwd: string = process.cwd
         }
     }
 
-    throw new Error(
-        'No configuration file found. Expected one of:\n' +
-        CONFIG_FILE_NAMES.map(f => `  - ${f}`).join('\n') +
-        '\n\nRun `objectstack create` to scaffold a new project.'
-    );
+    throw new ObjectQLError({
+        code: 'CONFIG_ERROR',
+        message: 'No configuration file found. Expected one of:\n' +
+            CONFIG_FILE_NAMES.map(f => `  - ${f}`).join('\n') +
+            '\n\nRun `objectstack create` to scaffold a new project.',
+    });
 }
 
 /**

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`* LICENSE file in the root directory of this source tree.`
`7`	`7`	`*/`
`8`	`8`
`9`		`-import { Driver } from '@objectql/types';`
	`9`	`+import { Driver, ObjectQLError } from '@objectql/types';`
`10`	`10`
`11`	`11`	`export function createDriverFromConnection(connection: string): Driver {`
`12`	`12`	`let driverPackage = '';`
`@@ -45,18 +45,18 @@ export function createDriverFromConnection(connection: string): Driver {`
`45`	`45`	`};`
`46`	`46`	`}`
`47`	`47`	`else {`
`48`		- throw new Error(`Unsupported connection protocol: ${connection}`);
	`48`	+ throw new ObjectQLError({ code: 'DRIVER_UNSUPPORTED_OPERATION', message: `Unsupported connection protocol: ${connection}` });
`49`	`49`	`}`
`50`	`50`
`51`	`51`	`try {`
`52`	`52`
`53`	`53`	`const pkg = require(driverPackage);`
`54`	`54`	`const DriverClass = pkg[driverClass];`
`55`	`55`	`if (!DriverClass) {`
`56`		- throw new Error(`${driverClass} not found in ${driverPackage}`);
	`56`	+ throw new ObjectQLError({ code: 'DRIVER_ERROR', message: `${driverClass} not found in ${driverPackage}` });
`57`	`57`	`}`
`58`	`58`	`return new DriverClass(driverConfig);`
`59`	`59`	`} catch (e: any) {`
`60`		- throw new Error(`Failed to load driver ${driverPackage}. Please install it: npm install ${driverPackage}. Error: ${e.message}`);
	`60`	+ throw new ObjectQLError({ code: 'DRIVER_ERROR', message: `Failed to load driver ${driverPackage}. Please install it: npm install ${driverPackage}. Error: ${e.message}` });
`61`	`61`	`}`
`62`	`62`	`}`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@`
`6`	`6`	`* LICENSE file in the root directory of this source tree.`
`7`	`7`	`*/`
`8`	`8`
	`9`	`+import { ObjectQLError } from '@objectql/types';`
`9`	`10`	`import type { PermissionConfig, RecordRuleCondition } from '@objectql/types';`
`10`	`11`	`import type { SecurityContext } from './types';`
`11`	`12`	`import { PermissionLoader } from './permission-loader';`
`@@ -279,7 +280,7 @@ export class QueryTrimmer {`
`279`	`280`	`}`
`280`	`281`
`281`	`282`	`// Unable to convert formula to filter`
`282`		- throw new Error(`Unsupported formula pattern: ${formula}`);
	`283`	+ throw new ObjectQLError({ code: 'INTERNAL_ERROR', message: `Unsupported formula pattern: ${formula}` });
`283`	`284`	`}`
`284`	`285`
`285`	`286`	`/**`
`@@ -353,7 +354,7 @@ export class QueryTrimmer {`
`353`	`354`	`const nestedFilter = this.conditionToFilter(nestedCondition, user);`
`354`	`355`
`355`	`356`	`if (Object.keys(nestedFilter).length === 0) {`
`356`		`- throw new Error('Unable to convert nested lookup condition');`
	`357`	`+ throw new ObjectQLError({ code: 'INTERNAL_ERROR', message: 'Unable to convert nested lookup condition' });`
`357`	`358`	`}`
`358`	`359`
`359`	`360`	`// Create a lookup filter`
Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@ import * as fs from 'fs';`
`10`	`10`	`import * as path from 'path';`
`11`	`11`	`import chalk from 'chalk';`
`12`	`12`	`import * as yaml from 'js-yaml';`
`13`		`-import { IntrospectedSchema, IntrospectedTable, IntrospectedColumn, ObjectConfig, IObjectQL, FieldConfig, FieldType } from '@objectql/types';`
	`13`	`+import { IntrospectedSchema, IntrospectedTable, IntrospectedColumn, ObjectConfig, IObjectQL, FieldConfig, FieldType, ObjectQLError } from '@objectql/types';`
`14`	`14`	`import { resolveConfigFile } from '../utils/config-loader';`
`15`	`15`
`16`	`16`	`interface SyncOptions {`
`@@ -45,7 +45,7 @@ export async function syncDatabase(options: SyncOptions) {`
`45`	`45`	`if (!driver \|\| !driver.introspectSchema) {`
`46`	`46`	`const errorMsg = 'The configured driver does not support schema introspection. Only SQL drivers (PostgreSQL, MySQL, SQLite) support this feature.';`
`47`	`47`	console.error(chalk.red(`❌ ${errorMsg}`));
`48`		`- throw new Error(errorMsg);`
	`48`	`+ throw new ObjectQLError({ code: 'DRIVER_UNSUPPORTED_OPERATION', message: errorMsg });`
`49`	`49`	`}`
`50`	`50`
`51`	`51`	`// Introspect database schema`
`@@ -291,7 +291,7 @@ async function loadObjectQLInstance(configPath?: string): Promise<IObjectQL> {`
`291`	`291`	`}`
`292`	`292`	`});`
`293`	`293`	`} catch (err) {`
`294`		`- throw new Error('TypeScript config file detected but ts-node is not installed. Please run: npm install --save-dev ts-node');`
	`294`	`+ throw new ObjectQLError({ code: 'CONFIG_ERROR', message: 'TypeScript config file detected but ts-node is not installed. Please run: npm install --save-dev ts-node' });`
`295`	`295`	`}`
`296`	`296`	`}`
`297`	`297`
`@@ -309,7 +309,7 @@ async function loadObjectQLInstance(configPath?: string): Promise<IObjectQL> {`
`309`	`309`	`const app = configModule.default \|\| configModule.app \|\| configModule.objectql \|\| configModule.db;`
`310`	`310`
`311`	`311`	`if (!app) {`
`312`		`- throw new Error('Config file must export an ObjectQL instance as default export or named export (app/objectql/db)');`
	`312`	`+ throw new ObjectQLError({ code: 'CONFIG_ERROR', message: 'Config file must export an ObjectQL instance as default export or named export (app/objectql/db)' });`
`313`	`313`	`}`
`314`	`314`
`315`	`315`	`// Initialize app (but don't sync schema - we're reading it)`
Original file line number	Diff line number	Diff line change
`@@ -8,6 +8,7 @@`
`8`	`8`
`9`	`9`	`import * as path from 'path';`
`10`	`10`	`import * as fs from 'fs';`
	`11`	`+import { ObjectQLError } from '@objectql/types';`
`11`	`12`
`12`	`13`	`/**`
`13`	`14`	`* Config file search order:`
`@@ -36,7 +37,7 @@ export function resolveConfigFile(configPath?: string, cwd: string = process.cwd`
`36`	`37`	`if (configPath) {`
`37`	`38`	`const resolved = path.isAbsolute(configPath) ? configPath : path.join(cwd, configPath);`
`38`	`39`	`if (!fs.existsSync(resolved)) {`
`39`		- throw new Error(`Configuration file not found: ${resolved}`);
	`40`	+ throw new ObjectQLError({ code: 'CONFIG_ERROR', message: `Configuration file not found: ${resolved}` });
`40`	`41`	`}`
`41`	`42`	`return resolved;`
`42`	`43`	`}`
`@@ -48,11 +49,12 @@ export function resolveConfigFile(configPath?: string, cwd: string = process.cwd`
`48`	`49`	`}`
`49`	`50`	`}`
`50`	`51`
`51`		`- throw new Error(`
`52`		`- 'No configuration file found. Expected one of:\n' +`
`53`		- CONFIG_FILE_NAMES.map(f => ` - ${f}`).join('\n') +
`54`		- '\n\nRun `objectstack create` to scaffold a new project.'
`55`		`- );`
	`52`	`+ throw new ObjectQLError({`
	`53`	`+ code: 'CONFIG_ERROR',`
	`54`	`+ message: 'No configuration file found. Expected one of:\n' +`
	`55`	+ CONFIG_FILE_NAMES.map(f => ` - ${f}`).join('\n') +
	`56`	+ '\n\nRun `objectstack create` to scaffold a new project.',
	`57`	`+ });`
`56`	`58`	`}`
`57`	`59`
`58`	`60`	`/**`