Add custom driver tutorial example for ObjectStack

[Copilot]

Custom Driver Support for ObjectStack

Integrated @objectstack/objectql for Driver Management

Following team feedback, I've modified existing packages to use @objectstack/objectql for driver management instead of creating a tutorial example.

Implementation Complete ✅

• Remove tutorial example approach
• Integrate @objectstack/objectql.ObjectQL class for driver management in @objectql/core
• Update @objectql/core to delegate driver management to ObjectStack engine
• Add driver wrapping to convert @objectql/types.Driver to @objectstack/spec.DriverInterface
• Add registerDriver() method for dynamic driver registration
• Add getStackEngine() method to access ObjectStack engine
• Update init() to initialize ObjectStack engine
• Update close() to destroy ObjectStack engine
• Export DriverInterface, DriverOptions, QueryAST types for driver development
• Update RUNTIME_INTEGRATION.md with integration details and custom driver guide
• Test integration with existing drivers
• Run code review and security checks

Key Changes

1. Driver Management Integration (packages/foundation/core/src/app.ts)

// ObjectStack engine instance for driver management
private stackEngine: ObjectStackEngine;

constructor(config: ObjectQLConfig) {
    // Initialize ObjectStack engine
    this.stackEngine = new ObjectStackEngine({});
    
    // Wrap and register drivers
    for (const [name, driver] of Object.entries(config.datasources)) {
        const wrappedDriver = this.wrapDriver(name, driver);
        this.stackEngine.registerDriver(wrappedDriver, name === 'default');
    }
}

2. Driver Wrapping

• Converts @objectql/types.Driver → @objectstack/spec.DriverInterface
• Maintains backward compatibility with existing drivers

3. New Public APIs

• app.getStackEngine() - Access ObjectStack engine for advanced features
• app.registerDriver(name, driver, isDefault) - Dynamic driver registration

4. Type Exports (packages/foundation/core/src/index.ts)

export type { DriverInterface, DriverOptions, QueryAST } from '@objectstack/spec';

5. Updated Documentation (RUNTIME_INTEGRATION.md)

• Custom driver development guide
• Integration architecture
• Usage examples

Benefits

✅ Standardized driver interface across ObjectStack ecosystem
✅ Plugin system for extending driver capabilities
✅ Unified driver management across packages
✅ Backward compatible - existing drivers continue to work
✅ Future-ready for driver marketplace and discovery

Original prompt

自定义驱动支持接入objectstack

构建自定义驱动
学习如何使用驱动接口为 ObjectStack 实现自定义数据库驱动。

构建自定义驱动

驱动程序（Driver）是 ObjectQL 引擎与底层数据存储（SQL、NoSQL、API 等）之间的桥梁。通过实现 DriverInterface，您可以将 ObjectStack 连接到任何数据源。

本指南将以创建一个简单的 内存驱动（In-Memory Driver） 为例进行讲解。

先决条件

现有的 ObjectStack 工作区或插件包。
依赖 @objectstack/objectql 和 @objectstack/spec。

1. 驱动接口 (Driver Interface)

所有驱动程序必须实现规范中定义的 DriverInterface。

import { DriverInterface, DriverOptions } from '@objectstack/spec';
import { QueryAST, QueryResult } from '@objectstack/objectql';
export class MyCustomDriver implements DriverInterface {
name = 'MyCustomDriver';
async connect() {
// 初始化连接
}
async disconnect() {
// 关闭连接
}

// ... CRUD 方法

}
2. 实现 CRUD 操作

您需要实现 find（查询）、insert（插入）、update（更新）和 delete（删除）方法。

Find (查询)

find 方法接收一个 QueryAST 对象，其中包含结构化的查询信息（过滤、排序、分页）。

async find(object: string, query: QueryAST, options?: DriverOptions): Promise {
// 1. 将 QueryAST 转换为数据库的查询语言（例如 SQL）
// 2. 执行查询
// 3. 返回对象数组结果
return [];
}
Insert (插入)

async insert(object: string, data: Record<string, any>, options?: DriverOptions) {
// 将数据插入存储
return data;
}
Update (更新)

async update(object: string, id: string, data: Record<string, any>, options?: DriverOptions) {
// 更新由 id 标识的记录
return { id, ...data };
}
Delete (删除)

async delete(object: string, id: string, options?: DriverOptions) {
// 删除记录
}
3. 类型处理

使用 @objectstack/objectql 提供的类型以确保兼容性。

QueryAST: 通用的查询抽象语法树。
QueryResult: Record<string, any>[].
4. 注册驱动

在插件的运行时入口点（例如 index.ts）导出驱动程序，以便引擎使用。

import { MyCustomDriver } from './my-driver';
export default {
drivers: [new MyCustomDriver()]
};
示例：内存驱动

请参考 examples/plugin-driver-memory 中的参考实现。

// examples/plugin-driver-memory/src/memory-driver.ts
export class InMemoryDriver implements DriverInterface {
name = 'InMemory';
private store = new Map<string, Map<string, any>>();
async find(object: string, query: QueryAST) {
const table = this.store.get(object) || new Map();
// 简单的过滤实现...
return Array.from(table.values());
}
// ...
}

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
objectql-site	Ready	Preview, Comment	Jan 21, 2026 2:34am

[huangyiirene]

@copilot 不是要做例子，下一步的规范就是用objectstack

[hotlong]

@copilot 继续

[Copilot]

@copilot 继续

I understand the feedback. Instead of creating a tutorial example, I should integrate custom driver support using @objectstack/objectql.

Could you clarify the specific integration needed:

1. Should I create driver registration/plugin system in @objectstack/objectql?
2. Should I document how to extend @objectstack/objectql with custom drivers?
3. Should I modify existing packages to use @objectstack/objectql for driver management?

Please provide guidance on the specific changes needed.

[huangyiirene]

modify existing packages to use @objectstack/objectql for driver management? @copilot

[hotlong]

@copilot 继续