Merge pull request #946 from objectstack-ai/copilot/implement-service-analytics-plugin

Author: hotlong

CHANGELOG.md

@@ -32,6 +32,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   now return proper metadata responses instead of throwing 500 errors.
 
 ### Added
+- **`@objectstack/service-analytics`** — New multi-driver analytics service implementing `IAnalyticsService`.
+  Uses a **Strategy Pattern** with priority-ordered chain: **P1 NativeSQLStrategy** (pushes queries as
+  native SQL to Postgres/MySQL drivers), **P2 ObjectQLStrategy** (translates to ObjectQL `aggregate()` AST),
+  **P3 InMemoryStrategy** (delegates to existing `MemoryAnalyticsService` for dev/test). Includes
+  `CubeRegistry` for auto-discovery of cubes from manifest definitions and object schema inference,
+  `AnalyticsServicePlugin` for kernel plugin lifecycle, `generateSql()` dry-run capability, and
+  `queryCapabilities()` driver probing for dynamic strategy selection. 34 unit tests covering all
+  strategy branches.
 - **Studio system objects visibility** — Studio now auto-registers all system objects (sys_user,
   sys_role, sys_audit_log, etc.) from plugin-auth, plugin-security, and plugin-audit at kernel
   initialization. The sidebar "System" group dynamically lists all `isSystem=true` objects

ROADMAP.md

@@ -532,13 +532,13 @@ Objects now declare `namespace: 'sys'` and a short `name` (e.g., `name: 'user'`)
 | `IWorkflowService` | **P2** | `@objectstack/service-workflow` | State machine + approval processes |
 | `IGraphQLService` | **P2** | `@objectstack/service-graphql` | Auto-generated GraphQL from objects |
 | `IAIService` | **P2** | `@objectstack/service-ai` | LLM integration (OpenAI/Anthropic/local) |
-| `IAnalyticsService` | **P3** | `@objectstack/service-analytics` | BI/OLAP queries |
+| `IAnalyticsService` | **P3** | `@objectstack/service-analytics` | ✅ Multi-driver analytics with strategy pattern (NativeSQL/ObjectQL/InMemory), CubeRegistry, generateSql (34 tests) |
 
 - [x] `service-automation` — Implement `IAutomationService` with plugin-based DAG flow engine (CRUD/Logic/HTTP nodes, fault edges, parallel branches, cycle detection, safe eval, timeout, versioning), HTTP API CRUD (9 routes), Client SDK (10 methods), execution history with step-level logging
 - [ ] `service-workflow` — Implement `IWorkflowService` with state machine runtime
 - [ ] `service-graphql` — Implement `IGraphQLService` with auto-schema generation
 - [ ] `service-ai` — Implement `IAIService` with multi-provider LLM routing
-- [ ] `service-analytics` — Implement full `IAnalyticsService` beyond memory reference
+- [x] `service-analytics` — Implement full `IAnalyticsService` with multi-driver strategy pattern (NativeSQLStrategy P1, ObjectQLStrategy P2, InMemoryStrategy P3), CubeRegistry with auto-inference from object schemas, generateSql dry-run, kernel plugin lifecycle
 
 ---
 
@@ -855,7 +855,7 @@ Final polish and advanced features.
 | 5 | HTTP Server | `IHttpServer` | ✅ | `@objectstack/plugin-hono-server` → `@objectstack/service-http` in v4.0 | Hono-based server |
 | 6 | Logger | `Logger` | ✅ | `@objectstack/core` | Pino-based structured logging |
 | 7 | Service Registry | `IServiceRegistry` | ✅ | `@objectstack/core` | Built into ObjectKernel |
-| 8 | Analytics Service | `IAnalyticsService` | 🟡 | `@objectstack/driver-memory` | Memory reference only |
+| 8 | Analytics Service | `IAnalyticsService` | ✅ | `@objectstack/service-analytics` | Multi-driver strategy pattern (NativeSQL/ObjectQL/InMemory), CubeRegistry, generateSql (34 tests) |
 | 9 | Plugin Lifecycle | `IPluginLifecycleEvents` | 🟡 | `@objectstack/core` | Partial in kernel |
 | 10 | Cache Service | `ICacheService` | ✅ | `@objectstack/service-cache` | Memory + Redis skeleton |
 | 11 | Queue Service | `IQueueService` | ✅ | `@objectstack/service-queue` | Memory + BullMQ skeleton |

packages/plugins/driver-memory/src/in-memory-strategy.ts

@@ -0,0 +1,47 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { AnalyticsQuery, AnalyticsResult, AnalyticsStrategy, StrategyContext } from '@objectstack/spec/contracts';
+
+/**
+ * InMemoryStrategy — Priority 3
+ *
+ * Delegates to an existing `IAnalyticsService` instance that was registered
+ * as a fallback (typically `MemoryAnalyticsService` from this package).
+ *
+ * This is the lowest-priority strategy, used in:
+ * - `dev` / `test` environments
+ * - Any runtime where the backing driver is in-memory
+ */
+export class InMemoryStrategy implements AnalyticsStrategy {
+  readonly name = 'InMemoryStrategy';
+  readonly priority = 30;
+
+  canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean {
+    if (!query.cube) return false;
+    // Can handle when a fallback service exists
+    if (ctx.fallbackService) return true;
+    // Or when the driver is flagged as in-memory
+    const caps = ctx.queryCapabilities(query.cube);
+    return caps.inMemory;
+  }
+
+  async execute(query: AnalyticsQuery, ctx: StrategyContext): Promise<AnalyticsResult> {
+    if (!ctx.fallbackService) {
+      throw new Error(
+        `[InMemoryStrategy] No fallback analytics service available for cube "${query.cube}". ` +
+        'Register a MemoryAnalyticsService or configure a driver with analytics support.'
+      );
+    }
+    return ctx.fallbackService.query(query);
+  }
+
+  async generateSql(query: AnalyticsQuery, ctx: StrategyContext): Promise<{ sql: string; params: unknown[] }> {
+    if (ctx.fallbackService?.generateSql) {
+      return ctx.fallbackService.generateSql(query);
+    }
+    return {
+      sql: `-- InMemoryStrategy: SQL generation not supported for cube "${query.cube}"`,
+      params: [],
+    };
+  }
+}

packages/plugins/driver-memory/src/index.ts

@@ -11,6 +11,8 @@ export { LocalStoragePersistenceAdapter } from './persistence/local-storage-adap
 export { MemoryAnalyticsService } from './memory-analytics.js';
 export type { MemoryAnalyticsConfig } from './memory-analytics.js';
 
+export { InMemoryStrategy } from './in-memory-strategy.js';
+
 export default {
   id: 'com.objectstack.driver.memory',
   version: '1.0.0',

packages/services/service-analytics/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — @objectstack/service-analytics
+
+All notable changes to this package will be documented in this file.
+
+## [3.2.9] — 2026-03-22
+
+### Added
+
+- Initial implementation of `@objectstack/service-analytics`
+- `AnalyticsService` orchestrator implementing `IAnalyticsService`
+- Strategy pattern with priority chain:
+  - **P1 — NativeSQLStrategy**: Pushes queries as native SQL to SQL-capable drivers (Postgres, MySQL, etc.)
+  - **P2 — ObjectQLStrategy**: Translates analytics queries into ObjectQL `engine.aggregate()` calls
+  - **P3 — InMemoryStrategy**: Delegates to any registered `IAnalyticsService` (e.g., `MemoryAnalyticsService`)
+- `CubeRegistry` for auto-discovery and registration of cubes from manifest definitions and object schema inference
+- `AnalyticsServicePlugin` for kernel plugin lifecycle integration
+- `queryCapabilities()` driver capability probing for strategy selection
+- `generateSql()` dry-run SQL generation across all strategies
+- Unit tests covering all strategy branches

packages/services/service-analytics/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@objectstack/service-analytics",
+  "version": "3.2.9",
+  "license": "Apache-2.0",
+  "description": "Analytics Service for ObjectStack — implements IAnalyticsService with multi-driver strategy pattern (NativeSQL, ObjectQL, InMemory)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@objectstack/core": "workspace:*",
+    "@objectstack/spec": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.0",
+    "@types/node": "^25.5.0"
+  }
+}