Merge pull request #326 from objectstack-ai/copilot/implement-objectql-plugin-registration

Author: hotlong

OBJECTQL_PLUGIN_QUICKSTART.md

@@ -0,0 +1,225 @@
+# ObjectQL Plugin - Quick Reference
+
+## Installation
+
+```bash
+npm install @objectstack/runtime
+```
+
+## Basic Usage
+
+### Default ObjectQL (Recommended)
+
+```typescript
+import { ObjectStackKernel, ObjectQLPlugin } from '@objectstack/runtime';
+
+const kernel = new ObjectStackKernel([
+  new ObjectQLPlugin(),
+  // ... other plugins
+]);
+
+await kernel.start();
+```
+
+### Custom ObjectQL Instance
+
+```typescript
+import { ObjectStackKernel, ObjectQLPlugin, ObjectQL } from '@objectstack/runtime';
+
+// Create custom instance
+const customQL = new ObjectQL({ 
+  env: 'production',
+  // custom options
+});
+
+// Configure as needed
+customQL.registerHook('beforeInsert', async (ctx) => {
+  console.log(`Inserting into ${ctx.object}`);
+});
+
+// Use in kernel
+const kernel = new ObjectStackKernel([
+  new ObjectQLPlugin(customQL),
+  // ... other plugins
+]);
+
+await kernel.start();
+```
+
+### Backward Compatible (Legacy)
+
+```typescript
+// Still works without ObjectQLPlugin, but shows warning
+const kernel = new ObjectStackKernel([
+  // ... plugins
+]);
+```
+
+## API Reference
+
+### ObjectQLPlugin Constructor
+
+```typescript
+new ObjectQLPlugin(ql?: ObjectQL, hostContext?: Record<string, any>)
+```
+
+**Parameters:**
+- `ql` (optional): Custom ObjectQL instance to use
+- `hostContext` (optional): Configuration for new ObjectQL instance (ignored if `ql` provided)
+
+**Note:** If both parameters are provided, `hostContext` is ignored with a warning.
+
+### Examples
+
+```typescript
+// Create with default settings
+new ObjectQLPlugin()
+
+// Use custom instance
+const custom = new ObjectQL({ env: 'prod' });
+new ObjectQLPlugin(custom)
+
+// Create with custom context
+new ObjectQLPlugin(undefined, { env: 'prod', debug: true })
+```
+
+## Migration Guide
+
+### From Hardcoded to Plugin-Based
+
+**Before:**
+```typescript
+const kernel = new ObjectStackKernel([appConfig, driver]);
+```
+
+**After:**
+```typescript
+const kernel = new ObjectStackKernel([
+  new ObjectQLPlugin(),  // Add this line
+  appConfig,
+  driver
+]);
+```
+
+## Common Patterns
+
+### Testing with Mock ObjectQL
+
+```typescript
+import { ObjectQLPlugin } from '@objectstack/runtime';
+import { MockObjectQL } from './mocks';
+
+const mockQL = new MockObjectQL();
+const kernel = new ObjectStackKernel([
+  new ObjectQLPlugin(mockQL),
+  // ... test config
+]);
+```
+
+### Multiple Environments
+
+```typescript
+// Production
+const prodQL = new ObjectQL({ env: 'production', cache: true });
+const prodKernel = new ObjectStackKernel([
+  new ObjectQLPlugin(prodQL),
+  // ... production plugins
+]);
+
+// Development
+const devKernel = new ObjectStackKernel([
+  new ObjectQLPlugin(undefined, { env: 'development', debug: true }),
+  // ... dev plugins
+]);
+```
+
+### Custom ObjectQL from Separate Project
+
+```typescript
+// Your custom implementation
+import { MyCustomObjectQL } from '@mycompany/custom-objectql';
+
+const customQL = new MyCustomObjectQL({
+  specialFeature: true,
+  // custom options
+});
+
+const kernel = new ObjectStackKernel([
+  new ObjectQLPlugin(customQL),
+  // ... other plugins
+]);
+```
+
+## Troubleshooting
+
+### Error: "ObjectQL engine not initialized"
+
+This means the kernel tried to use ObjectQL before it was set up. Make sure:
+1. You include `ObjectQLPlugin` in your plugins array, OR
+2. The kernel has backward compatibility enabled
+
+### Warning: "No ObjectQL plugin found..."
+
+This is a deprecation warning. Your code will work, but consider migrating to:
+
+```typescript
+new ObjectStackKernel([
+  new ObjectQLPlugin(),  // Add this
+  // ... other plugins
+]);
+```
+
+### Warning: "Both ql and hostContext provided..."
+
+You passed both a custom ObjectQL instance and host context:
+
+```typescript
+// ❌ Don't do this
+new ObjectQLPlugin(customQL, { env: 'prod' })  // hostContext ignored
+
+// ✅ Do this instead
+new ObjectQLPlugin(customQL)  // Use custom instance
+
+// ✅ Or this
+new ObjectQLPlugin(undefined, { env: 'prod' })  // Create with context
+```
+
+## Advanced
+
+### Type-Based Detection
+
+ObjectQLPlugin uses a `type` field for reliable detection:
+
+```typescript
+// Check if a plugin is an ObjectQL plugin
+const isObjectQLPlugin = plugin && plugin.type === 'objectql';
+```
+
+The plugin sets `type = 'objectql'` which aligns with the manifest schema that supports package types: 'app', 'plugin', 'driver', 'module', 'objectql', 'gateway', 'adapter'.
+
+### Type Safety
+
+The kernel's `ql` property is typed as optional:
+
+```typescript
+export class ObjectStackKernel {
+  public ql?: ObjectQL;
+  
+  private ensureObjectQL(): ObjectQL {
+    if (!this.ql) {
+      throw new Error('ObjectQL engine not initialized');
+    }
+    return this.ql;
+  }
+}
+```
+
+## Resources
+
+- [Full Documentation](./packages/runtime/README.md)
+- [Implementation Summary](./OBJECTQL_PLUGIN_SUMMARY.md)
+- [Custom ObjectQL Example](./examples/custom-objectql-example.ts)
+
+## License
+
+Apache-2.0

content/docs/references/system/manifest/Manifest.mdx

@@ -9,7 +9,7 @@ description: Manifest Schema Reference
 | :--- | :--- | :--- | :--- |
 | **id** | `string` | ✅ | Unique package identifier (reverse domain style) |
 | **version** | `string` | ✅ | Package version (semantic versioning) |
-| **type** | `Enum<'app' \| 'plugin' \| 'driver' \| 'module'>` | ✅ | Type of package |
+| **type** | `Enum<'app' \| 'plugin' \| 'driver' \| 'module' \| 'objectql' \| 'gateway' \| 'adapter'>` | ✅ | Type of package |
 | **name** | `string` | ✅ | Human-readable package name |
 | **description** | `string` | optional | Package description |
 | **permissions** | `string[]` | optional | Array of required permission strings |

examples/custom-objectql-example.ts

@@ -0,0 +1,44 @@
+/**
+ * Example: Custom ObjectQL Instance
+ * 
+ * This demonstrates how to use a custom ObjectQL instance with the kernel.
+ * This is useful when you have a separate ObjectQL implementation or need
+ * custom configuration.
+ */
+
+import { ObjectStackKernel, ObjectQLPlugin, ObjectQL } from '@objectstack/runtime';
+import { InMemoryDriver } from '@objectstack/driver-memory';
+
+(async () => {
+  console.log('🚀 Example: Custom ObjectQL Instance...');
+
+  // Create a custom ObjectQL instance with specific configuration
+  const customQL = new ObjectQL({
+    env: 'development',
+    // Add any custom host context here
+    customFeature: true,
+    debug: true
+  });
+
+  // You can also pre-configure the ObjectQL instance
+  // For example, register custom hooks
+  customQL.registerHook('beforeInsert', async (ctx) => {
+    console.log(`[Custom Hook] Before inserting into ${ctx.object}`);
+  });
+
+  // Create kernel with the custom ObjectQL instance
+  const kernel = new ObjectStackKernel([
+    // Register your custom ObjectQL instance
+    new ObjectQLPlugin(customQL),
+    
+    // Add your driver
+    new InMemoryDriver(),
+    
+    // Add other plugins and app configs as needed
+  ]);
+
+  await kernel.start();
+
+  console.log('✅ Kernel started with custom ObjectQL instance');
+  console.log('ObjectQL instance:', kernel.ql);
+})();

examples/host/debug-registry.ts

@@ -1,5 +1,5 @@
 
-import { ObjectStackKernel } from '@objectstack/runtime';
+import { ObjectStackKernel, ObjectQLPlugin } from '@objectstack/runtime';
 import { SchemaRegistry, ObjectQL } from '@objectstack/objectql';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 
@@ -11,6 +11,7 @@ import TodoApp from '@objectstack/example-todo/objectstack.config';
     console.log('Objects inside App:', TodoApp.objects?.map((o: any) => o.name));
 
     const kernel = new ObjectStackKernel([
+        new ObjectQLPlugin(),
         TodoApp,
         new InMemoryDriver()
     ]);

examples/host/src/index.ts

@@ -1,4 +1,4 @@
-import { ObjectStackKernel } from '@objectstack/runtime';
+import { ObjectStackKernel, ObjectQLPlugin, ObjectQL } from '@objectstack/runtime';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 import { HonoServerPlugin } from '@objectstack/plugin-hono-server';
 
@@ -9,10 +9,17 @@ import BiPluginManifest from '@objectstack/plugin-bi/objectstack.config';
 (async () => {
   console.log('🚀 Booting Kernel...');
 
+  // Option 1: Use default ObjectQL via plugin (recommended)
   const kernel = new ObjectStackKernel([
+      // Register ObjectQL engine explicitly via plugin
+      new ObjectQLPlugin(),
+      
+      // App manifests
       CrmApp, 
       TodoApp, 
       BiPluginManifest,
+      
+      // Database driver
       new InMemoryDriver(),
 
       // Load the Hono Server Plugin
@@ -22,5 +29,12 @@ import BiPluginManifest from '@objectstack/plugin-bi/objectstack.config';
       }) 
   ]);
 
+  // Option 2: Use custom ObjectQL instance
+  // const customQL = new ObjectQL({ env: 'production', customConfig: true });
+  // const kernel = new ObjectStackKernel([
+  //     new ObjectQLPlugin(customQL),
+  //     ...other plugins
+  // ]);
+
   await kernel.start();
 })();

examples/msw-react-crud/src/mocks/browser.ts

@@ -5,7 +5,7 @@
  * and the MSW Plugin which automatically exposes the API.
  */
 
-import { ObjectStackKernel } from '@objectstack/runtime';
+import { ObjectStackKernel, ObjectQLPlugin } from '@objectstack/runtime';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 import { MSWPlugin } from '@objectstack/plugin-msw';
 // import appConfig from '../../objectstack.config';
@@ -24,6 +24,9 @@ export async function startMockServer() {
   // We use the data defined in the Todo App config
 
   kernel = new ObjectStackKernel([
+    // Register ObjectQL engine explicitly
+    new ObjectQLPlugin(),
+    
     // Todo App Config (contains objects and data)
     todoConfig,