feat: Create @objectql/types v4.0.0 with plugin interfaces

Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

Author: Copilot

packages/core/types/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+*.tsbuildinfo
+coverage
+.DS_Store

packages/core/types/CHANGELOG.md

@@ -0,0 +1,67 @@
+# @objectql/types v4.0.0
+
+## [4.0.0] - 2026-01-21
+
+### Breaking Changes
+
+- Complete rewrite of type system for plugin-based architecture
+- Removed types now in @objectstack/spec:
+  - `Driver` interface (use `DriverInterface` from @objectstack/spec)
+- Removed types now in @objectstack/runtime:
+  - `MetadataRegistry` class
+  - `Context` types
+  - `Hook` types
+  - `Action` types
+
+### Added
+
+- New plugin interfaces:
+  - `QueryProcessorPlugin` - For query validation, optimization, and transformation
+  - `RepositoryPlugin` - For extending repository with batch operations, audit tracking
+  - `BasePlugin` - Base interface for all plugins
+- Query-specific types:
+  - `UnifiedQuery` - Core query structure
+  - `FilterExpression` - Type-safe filter expressions
+  - `QueryResult` - Query result wrapper with pagination
+  - `QueryOptions` - Query execution options
+- Runtime types:
+  - `RuntimeContext` - Context available to plugins during execution
+  - `ValidationResult` - Query validation result
+  - `ValidationError` - Validation error details
+
+### Dependencies
+
+- Added `@objectstack/spec` ^0.2.0
+- Added `@objectstack/runtime` ^0.2.0
+
+### Migration Guide
+
+If you were using types that are now removed:
+
+```typescript
+// Old (v3.x)
+import { Driver, MetadataRegistry, Hook } from '@objectql/types';
+
+// New (v4.x)
+import { DriverInterface } from '@objectstack/spec';
+// MetadataRegistry, Hook, Action are now part of @objectstack/runtime
+```
+
+For plugin development:
+
+```typescript
+// New in v4.x
+import { QueryProcessorPlugin, RepositoryPlugin } from '@objectql/types';
+
+export function myPlugin(): QueryProcessorPlugin {
+  return {
+    name: '@myorg/plugin',
+    version: '1.0.0',
+    type: 'query-processor',
+    async beforeQuery(ast, context) {
+      // Transform query
+      return ast;
+    }
+  };
+}
+```

packages/core/types/README.md

@@ -0,0 +1,56 @@
+# @objectql/types
+
+Type definitions and plugin interfaces for ObjectQL v4.0.
+
+## Overview
+
+This package provides the core TypeScript type definitions for ObjectQL's plugin architecture. It includes:
+
+- **Plugin Interfaces**: Define custom query plugins, repository extensions, and query processors
+- **Query Types**: Type-safe query construction and manipulation
+- **Helper Types**: Utility types for working with ObjectQL queries
+
+## Key Principles
+
+1. **Zero Dependencies on Internal Packages**: This package depends only on `@objectstack/spec` and `@objectstack/runtime`
+2. **Protocol-Driven**: Types define the contract, implementation follows
+3. **Strict Type Safety**: All types use TypeScript strict mode
+
+## Installation
+
+```bash
+npm install @objectql/types
+```
+
+## Usage
+
+```typescript
+import { QueryPlugin, RepositoryPlugin, UnifiedQuery } from '@objectql/types';
+
+// Define a custom query plugin
+export function myQueryPlugin(): QueryPlugin {
+  return {
+    name: '@myorg/query-plugin',
+    version: '1.0.0',
+    type: 'query-processor',
+    async beforeQuery(ast, context) {
+      // Transform query before execution
+      return ast;
+    }
+  };
+}
+```
+
+## Migration from v3.x
+
+In v4.0, ObjectQL has transitioned to a plugin-based architecture built on `@objectstack/runtime`:
+
+- **Driver Interface**: Now uses `DriverInterface` from `@objectstack/spec`
+- **Metadata & Context**: Now managed by `@objectstack/runtime`
+- **Hooks & Actions**: Now part of `@objectstack/runtime`
+
+This package focuses exclusively on query-specific types and plugin interfaces.
+
+## License
+
+MIT © ObjectStack Inc.

packages/core/types/jest.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+  ],
+};

packages/core/types/package-lock.json

@@ -0,0 +1,28 @@
+{
+  "name": "@objectql/types",
+  "version": "4.0.0",
+  "description": "Type definitions and plugin interfaces for ObjectQL - Query-specific types and plugin architecture",
+  "keywords": [
+    "objectql",
+    "types",
+    "typescript",
+    "interfaces",
+    "plugin",
+    "query",
+    "ai-native"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --passWithNoTests"
+  },
+  "dependencies": {
+    "@objectstack/spec": "^0.2.0",
+    "@objectstack/runtime": "^0.2.0"
+  }
+}

packages/core/types/package.json

@@ -0,0 +1,61 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @objectql/types - Type definitions for ObjectQL v4.0
+ * 
+ * This package provides the core TypeScript type definitions for ObjectQL's
+ * plugin-based architecture. It includes:
+ * 
+ * - Plugin interfaces (QueryProcessorPlugin, RepositoryPlugin)
+ * - Query types (UnifiedQuery, FilterExpression)
+ * - Runtime context and options
+ * 
+ * Key principles:
+ * - Zero dependencies on other @objectql packages
+ * - Depends only on @objectstack/spec and @objectstack/runtime
+ * - Strict type safety
+ * - Protocol-driven design
+ */
+
+// ============================================================================
+// Plugin System
+// ============================================================================
+
+export * from './plugin';
+export * from './query-processor';
+export * from './repository';
+
+// ============================================================================
+// Query System
+// ============================================================================
+
+export * from './query';
+
+// ============================================================================
+// Re-exports from @objectstack packages
+// ============================================================================
+
+/**
+ * Re-export commonly used types from @objectstack/spec
+ * This provides a convenient import path for ObjectQL users.
+ */
+export type { 
+    DriverInterface,
+    // Add other spec types as needed
+} from '@objectstack/spec';
+
+/**
+ * Re-export commonly used types from @objectstack/runtime
+ * This provides a convenient import path for ObjectQL users.
+ */
+export type {
+    // RuntimePlugin,
+    // Runtime,
+    // Add other runtime types as needed
+} from '@objectstack/runtime';

packages/core/types/src/index.ts

@@ -0,0 +1,67 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Base plugin metadata required by all ObjectQL plugins.
+ * 
+ * This extends the RuntimePlugin from @objectstack/runtime with
+ * ObjectQL-specific plugin types.
+ */
+export interface PluginMetadata {
+    /** Unique plugin identifier (e.g., '@objectql/query-validation') */
+    name: string;
+    
+    /** Semantic version (e.g., '4.0.0') */
+    version: string;
+    
+    /** Plugin type discriminator */
+    type: PluginType;
+    
+    /** Required plugin dependencies */
+    dependencies?: string[];
+    
+    /** Optional plugin dependencies that enhance functionality */
+    optionalDependencies?: string[];
+    
+    /** Plugins that conflict with this one */
+    conflicts?: string[];
+}
+
+/**
+ * Supported ObjectQL plugin types.
+ */
+export type PluginType = 
+    | 'driver'
+    | 'query-processor'
+    | 'repository'
+    | 'feature'
+    | 'custom';
+
+/**
+ * Plugin lifecycle methods.
+ */
+export interface PluginLifecycle {
+    /**
+     * Called when the plugin is registered with the runtime.
+     * Use this to initialize resources, register handlers, etc.
+     */
+    setup?(runtime: any): Promise<void>;
+    
+    /**
+     * Called when the runtime is shutting down.
+     * Use this to cleanup resources, close connections, etc.
+     */
+    teardown?(runtime: any): Promise<void>;
+}
+
+/**
+ * Base plugin interface that all ObjectQL plugins must implement.
+ * 
+ * This is a minimal interface that can be extended by specific plugin types.
+ */
+export interface BasePlugin extends PluginMetadata, PluginLifecycle {}