Skip to content

OBJECTQL_PLUGIN_QUICKSTART.md

Latest commit

 

History

History
225 lines (162 loc) · 4.55 KB

OBJECTQL_PLUGIN_QUICKSTART.md

File metadata and controls

225 lines (162 loc) · 4.55 KB

ObjectQL Plugin - Quick Reference

Installation

npm install @objectstack/runtime

Basic Usage

Default ObjectQL (Recommended)

import { ObjectStackKernel, ObjectQLPlugin } from '@objectstack/runtime';

const kernel = new ObjectStackKernel([
  new ObjectQLPlugin(),
  // ... other plugins
]);

await kernel.start();

Custom ObjectQL Instance

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)

// Still works without ObjectQLPlugin, but shows warning
const kernel = new ObjectStackKernel([
  // ... plugins
]);

API Reference

ObjectQLPlugin Constructor

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

// 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:

const kernel = new ObjectStackKernel([appConfig, driver]);

After:

const kernel = new ObjectStackKernel([
  new ObjectQLPlugin(),  // Add this line
  appConfig,
  driver
]);

Common Patterns

Testing with Mock ObjectQL

import { ObjectQLPlugin } from '@objectstack/runtime';
import { MockObjectQL } from './mocks';

const mockQL = new MockObjectQL();
const kernel = new ObjectStackKernel([
  new ObjectQLPlugin(mockQL),
  // ... test config
]);

Multiple Environments

// 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

// 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:

new ObjectStackKernel([
  new ObjectQLPlugin(),  // Add this
  // ... other plugins
]);

Warning: "Both ql and hostContext provided..."

You passed both a custom ObjectQL instance and host context:

// ❌ 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

Symbol-Based Detection

ObjectQLPlugin uses a symbol for reliable detection:

import { OBJECTQL_PLUGIN_MARKER } from '@objectstack/runtime';

// Check if a plugin is an ObjectQL plugin
const isObjectQLPlugin = OBJECTQL_PLUGIN_MARKER in plugin;

Type Safety

The kernel's ql property is typed as optional:

export class ObjectStackKernel {
  public ql?: ObjectQL;
  
  private ensureObjectQL(): ObjectQL {
    if (!this.ql) {
      throw new Error('ObjectQL engine not initialized');
    }
    return this.ql;
  }
}

Resources

License

Apache-2.0