@objectstack/service-analytics 4.0.4 → 4.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/service-analytics",
-  "version": "4.0.4",
+  "version": "4.0.5",
   "license": "Apache-2.0",
   "description": "Analytics Service for ObjectStack — implements IAnalyticsService with multi-driver strategy pattern (NativeSQL, ObjectQL, InMemory)",
   "type": "module",
@@ -14,13 +14,38 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "4.0.4",
-    "@objectstack/spec": "4.0.4"
+    "@objectstack/core": "4.0.5",
+    "@objectstack/spec": "4.0.5"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.4"
+    "@types/node": "^25.6.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "keywords": [
+    "objectstack",
+    "service",
+    "analytics",
+    "metrics",
+    "events"
+  ],
+  "author": "ObjectStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/framework.git",
+    "directory": "packages/services/service-analytics"
+  },
+  "homepage": "https://objectstack.ai/docs",
+  "bugs": "https://github.com/objectstack-ai/framework/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @objectstack/service-analytics@4.0.4 build /home/runner/work/framework/framework/packages/services/service-analytics
-> tsup --config ../../../tsup.config.ts
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/framework/framework/tsup.config.ts
-CLI Target: es2020
-CLI Cleaning output folder
-ESM Build start
-CJS Build start
-CJS dist/index.cjs     20.02 KB
-CJS dist/index.cjs.map 44.22 KB
-CJS ⚡️ Build success in 115ms
-ESM dist/index.js     18.81 KB
-ESM dist/index.js.map 43.38 KB
-ESM ⚡️ Build success in 118ms
-DTS Build start
-DTS ⚡️ Build success in 15849ms
-DTS dist/index.d.ts  9.26 KB
-DTS dist/index.d.cts 9.26 KB

package/CHANGELOG.md

@@ -1,65 +0,0 @@
-# Changelog — @objectstack/service-analytics
-
-## 4.0.4
-
-### Patch Changes
-
-- Updated dependencies [326b66b]
-  - @objectstack/spec@4.0.4
-  - @objectstack/core@4.0.4
-
-## 4.0.3
-
-### Patch Changes
-
-- @objectstack/spec@4.0.3
-- @objectstack/core@4.0.3
-
-## 4.0.2
-
-### Patch Changes
-
-- Updated dependencies [5f659e9]
-  - @objectstack/spec@4.0.2
-  - @objectstack/core@4.0.2
-
-## 4.0.0
-
-### Patch Changes
-
-- Updated dependencies [f08ffc3]
-- Updated dependencies [e0b0a78]
-  - @objectstack/spec@4.0.0
-  - @objectstack/core@4.0.0
-
-## 3.3.1
-
-### Patch Changes
-
-- @objectstack/spec@3.3.1
-- @objectstack/core@3.3.1
-
-## 3.2.10
-
-### Patch Changes
-
-- @objectstack/spec@3.3.0
-- @objectstack/core@3.3.0
-
-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

package/src/__tests__/analytics-service.test.ts

@@ -1,469 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import type { Cube } from '@objectstack/spec/data';
-import type { AnalyticsQuery, AnalyticsResult, IAnalyticsService } from '@objectstack/spec/contracts';
-import { AnalyticsService } from '../analytics-service.js';
-import { CubeRegistry } from '../cube-registry.js';
-import { NativeSQLStrategy } from '../strategies/native-sql-strategy.js';
-import { ObjectQLStrategy } from '../strategies/objectql-strategy.js';
-import type { DriverCapabilities } from '../strategies/types.js';
-
-// ─────────────────────────────────────────────────────────────────
-// Test fixtures
-// ─────────────────────────────────────────────────────────────────
-
-const ordersCube: Cube = {
-  name: 'orders',
-  title: 'Orders',
-  sql: 'orders',
-  measures: {
-    count: { name: 'count', label: 'Count', type: 'count', sql: '*' },
-    total_amount: { name: 'total_amount', label: 'Total Amount', type: 'sum', sql: 'amount' },
-    avg_amount: { name: 'avg_amount', label: 'Avg Amount', type: 'avg', sql: 'amount' },
-  },
-  dimensions: {
-    status: { name: 'status', label: 'Status', type: 'string', sql: 'status' },
-    created_at: {
-      name: 'created_at',
-      label: 'Created At',
-      type: 'time',
-      sql: 'created_at',
-      granularities: ['day', 'week', 'month'],
-    },
-  },
-  public: false,
-};
-
-const baseQuery: AnalyticsQuery = {
-  cube: 'orders',
-  measures: ['orders.count', 'orders.total_amount'],
-  dimensions: ['orders.status'],
-};
-
-// Suppress logger output in tests
-const silentLogger = {
-  info: vi.fn(),
-  debug: vi.fn(),
-  warn: vi.fn(),
-  error: vi.fn(),
-  child: vi.fn().mockReturnThis(),
-} as any;
-
-// ─────────────────────────────────────────────────────────────────
-// CubeRegistry
-// ─────────────────────────────────────────────────────────────────
-
-describe('CubeRegistry', () => {
-  let registry: CubeRegistry;
-
-  beforeEach(() => {
-    registry = new CubeRegistry();
-  });
-
-  it('should register and retrieve a cube', () => {
-    registry.register(ordersCube);
-    expect(registry.get('orders')).toEqual(ordersCube);
-    expect(registry.has('orders')).toBe(true);
-    expect(registry.size).toBe(1);
-  });
-
-  it('should register multiple cubes at once', () => {
-    const cube2: Cube = { ...ordersCube, name: 'products', sql: 'products' };
-    registry.registerAll([ordersCube, cube2]);
-    expect(registry.size).toBe(2);
-    expect(registry.names()).toEqual(['orders', 'products']);
-  });
-
-  it('should return undefined for unknown cube', () => {
-    expect(registry.get('nonexistent')).toBeUndefined();
-    expect(registry.has('nonexistent')).toBe(false);
-  });
-
-  it('should clear all cubes', () => {
-    registry.register(ordersCube);
-    registry.clear();
-    expect(registry.size).toBe(0);
-  });
-
-  it('should infer a cube from object fields', () => {
-    const cube = registry.inferFromObject('tasks', [
-      { name: 'title', type: 'text', label: 'Title' },
-      { name: 'hours', type: 'number', label: 'Hours' },
-      { name: 'due_date', type: 'date', label: 'Due Date' },
-      { name: 'active', type: 'boolean', label: 'Active' },
-    ]);
-
-    expect(cube.name).toBe('tasks');
-    expect(cube.measures.count).toBeDefined();
-    expect(cube.measures.hours_sum).toBeDefined();
-    expect(cube.measures.hours_avg).toBeDefined();
-    expect(cube.dimensions.title.type).toBe('string');
-    expect(cube.dimensions.hours.type).toBe('number');
-    expect(cube.dimensions.due_date.type).toBe('time');
-    expect(cube.dimensions.active.type).toBe('boolean');
-
-    // Should also be registered automatically
-    expect(registry.get('tasks')).toBe(cube);
-  });
-});
-
-// ─────────────────────────────────────────────────────────────────
-// NativeSQLStrategy
-// ─────────────────────────────────────────────────────────────────
-
-describe('NativeSQLStrategy', () => {
-  const strategy = new NativeSQLStrategy();
-
-  it('should have correct name and priority', () => {
-    expect(strategy.name).toBe('NativeSQLStrategy');
-    expect(strategy.priority).toBe(10);
-  });
-
-  it('should handle when nativeSql capability is true', () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: true, objectqlAggregate: false, inMemory: false }),
-      executeRawSql: vi.fn(),
-    };
-    expect(strategy.canHandle(baseQuery, ctx)).toBe(true);
-  });
-
-  it('should not handle when nativeSql is false', () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }),
-    };
-    expect(strategy.canHandle(baseQuery, ctx)).toBe(false);
-  });
-
-  it('should not handle when cube is missing', () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: true, objectqlAggregate: false, inMemory: false }),
-      executeRawSql: vi.fn(),
-    };
-    expect(strategy.canHandle({ measures: ['count'] }, ctx)).toBe(false);
-  });
-
-  it('should generate SQL with dimensions, measures, and filters', async () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: true, objectqlAggregate: false, inMemory: false }),
-      executeRawSql: vi.fn(),
-    };
-
-    const query: AnalyticsQuery = {
-      cube: 'orders',
-      measures: ['orders.count', 'orders.total_amount'],
-      dimensions: ['orders.status'],
-      filters: [{ member: 'orders.status', operator: 'equals', values: ['completed'] }],
-      limit: 10,
-    };
-
-    const { sql, params } = await strategy.generateSql(query, ctx);
-
-    expect(sql).toContain('SELECT');
-    expect(sql).toContain('COUNT(*)');
-    expect(sql).toContain('SUM(amount)');
-    expect(sql).toContain('GROUP BY');
-    expect(sql).toContain('LIMIT 10');
-    expect(params).toContain('completed');
-  });
-
-  it('should execute query and return structured result', async () => {
-    const mockRows = [
-      { 'orders.status': 'completed', 'orders.count': 5, 'orders.total_amount': 500 },
-    ];
-    const executeRawSql = vi.fn().mockResolvedValue(mockRows);
-
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: true, objectqlAggregate: false, inMemory: false }),
-      executeRawSql,
-    };
-
-    const result = await strategy.execute(baseQuery, ctx);
-
-    expect(executeRawSql).toHaveBeenCalled();
-    expect(result.rows).toEqual(mockRows);
-    expect(result.fields).toHaveLength(3); // 1 dimension + 2 measures
-    expect(result.sql).toBeDefined();
-  });
-});
-
-// ─────────────────────────────────────────────────────────────────
-// ObjectQLStrategy
-// ─────────────────────────────────────────────────────────────────
-
-describe('ObjectQLStrategy', () => {
-  const strategy = new ObjectQLStrategy();
-
-  it('should have correct name and priority', () => {
-    expect(strategy.name).toBe('ObjectQLStrategy');
-    expect(strategy.priority).toBe(20);
-  });
-
-  it('should handle when objectqlAggregate capability is true', () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }),
-      executeAggregate: vi.fn(),
-    };
-    expect(strategy.canHandle(baseQuery, ctx)).toBe(true);
-  });
-
-  it('should not handle without executeAggregate', () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }),
-    };
-    expect(strategy.canHandle(baseQuery, ctx)).toBe(false);
-  });
-
-  it('should execute an aggregate query', async () => {
-    const mockRows = [
-      { status: 'pending', 'orders.count': 3, 'orders.total_amount': 150 },
-    ];
-    const executeAggregate = vi.fn().mockResolvedValue(mockRows);
-
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }),
-      executeAggregate,
-    };
-
-    const result = await strategy.execute(baseQuery, ctx);
-
-    expect(executeAggregate).toHaveBeenCalledWith('orders', expect.objectContaining({
-      groupBy: ['status'],
-      aggregations: expect.arrayContaining([
-        expect.objectContaining({ method: 'count' }),
-        expect.objectContaining({ method: 'sum' }),
-      ]),
-    }));
-    expect(result.rows).toHaveLength(1);
-    expect(result.fields).toHaveLength(3);
-  });
-
-  it('should generate representative SQL', async () => {
-    const ctx = {
-      getCube: () => ordersCube,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }),
-      executeAggregate: vi.fn(),
-    };
-
-    const { sql } = await strategy.generateSql(baseQuery, ctx);
-    expect(sql).toContain('SELECT');
-    expect(sql).toContain('COUNT(*)');
-    expect(sql).toContain('GROUP BY');
-  });
-});
-
-// ─────────────────────────────────────────────────────────────────
-// FallbackDelegateStrategy (internal, tested via AnalyticsService)
-// ─────────────────────────────────────────────────────────────────
-
-describe('FallbackDelegateStrategy (via AnalyticsService)', () => {
-  it('should auto-add FallbackDelegateStrategy when fallbackService is configured', async () => {
-    const mockResult: AnalyticsResult = { rows: [{ count: 10 }], fields: [{ name: 'count', type: 'number' }] };
-    const fallback: IAnalyticsService = {
-      query: vi.fn().mockResolvedValue(mockResult),
-      getMeta: vi.fn().mockResolvedValue([]),
-    };
-
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-      fallbackService: fallback,
-    });
-
-    const result = await service.query(baseQuery);
-    expect(fallback.query).toHaveBeenCalledWith(baseQuery);
-    expect(result).toEqual(mockResult);
-  });
-
-  it('should NOT add FallbackDelegateStrategy when no fallbackService', async () => {
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: false, inMemory: false }),
-    });
-
-    await expect(service.query(baseQuery)).rejects.toThrow('No strategy can handle');
-  });
-
-  it('should delegate generateSql to fallback service', async () => {
-    const fallback: IAnalyticsService = {
-      query: vi.fn(),
-      getMeta: vi.fn(),
-      generateSql: vi.fn().mockResolvedValue({ sql: 'SELECT 1', params: [] }),
-    };
-
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-      fallbackService: fallback,
-    });
-
-    const { sql } = await service.generateSql(baseQuery);
-    expect(sql).toBe('SELECT 1');
-  });
-
-  it('should return placeholder SQL when fallback has no generateSql', async () => {
-    const fallback: IAnalyticsService = {
-      query: vi.fn().mockResolvedValue({ rows: [], fields: [] }),
-      getMeta: vi.fn(),
-    };
-
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-      fallbackService: fallback,
-    });
-
-    const { sql } = await service.generateSql(baseQuery);
-    expect(sql).toContain('FallbackDelegateStrategy');
-  });
-});
-
-// ─────────────────────────────────────────────────────────────────
-// AnalyticsService (Orchestrator)
-// ─────────────────────────────────────────────────────────────────
-
-describe('AnalyticsService', () => {
-  it('should use NativeSQLStrategy when driver supports native SQL', async () => {
-    const mockRows = [{ count: 42 }];
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-      queryCapabilities: () => ({ nativeSql: true, objectqlAggregate: true, inMemory: false }),
-      executeRawSql: vi.fn().mockResolvedValue(mockRows),
-    });
-
-    const result = await service.query(baseQuery);
-    expect(result.rows).toEqual(mockRows);
-    expect(result.sql).toBeDefined(); // NativeSQL always includes sql
-  });
-
-  it('should fall back to ObjectQLStrategy when nativeSql is false', async () => {
-    const mockRows = [{ status: 'pending', 'orders.count': 3, 'orders.total_amount': 100 }];
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }),
-      executeAggregate: vi.fn().mockResolvedValue(mockRows),
-    });
-
-    const result = await service.query(baseQuery);
-    expect(result.rows).toHaveLength(1);
-  });
-
-  it('should fall back to FallbackDelegateStrategy with fallback service', async () => {
-    const mockResult: AnalyticsResult = {
-      rows: [{ count: 100 }],
-      fields: [{ name: 'count', type: 'number' }],
-    };
-    const fallback: IAnalyticsService = {
-      query: vi.fn().mockResolvedValue(mockResult),
-      getMeta: vi.fn().mockResolvedValue([]),
-    };
-
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-      fallbackService: fallback,
-    });
-
-    const result = await service.query(baseQuery);
-    expect(result).toEqual(mockResult);
-    expect(fallback.query).toHaveBeenCalled();
-  });
-
-  it('should throw when no strategy can handle the query', async () => {
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-      queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: false, inMemory: false }),
-    });
-
-    await expect(service.query(baseQuery)).rejects.toThrow('No strategy can handle');
-  });
-
-  it('should throw when cube name is missing', async () => {
-    const service = new AnalyticsService({ logger: silentLogger });
-    await expect(service.query({ measures: ['count'] })).rejects.toThrow('Cube name is required');
-  });
-
-  it('should return cube metadata via getMeta()', async () => {
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-    });
-
-    const meta = await service.getMeta();
-    expect(meta).toHaveLength(1);
-    expect(meta[0].name).toBe('orders');
-    expect(meta[0].measures.length).toBeGreaterThan(0);
-    expect(meta[0].dimensions.length).toBeGreaterThan(0);
-  });
-
-  it('should filter getMeta() by cube name', async () => {
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-    });
-
-    const meta = await service.getMeta('orders');
-    expect(meta).toHaveLength(1);
-    expect(meta[0].name).toBe('orders');
-
-    const empty = await service.getMeta('nonexistent');
-    expect(empty).toHaveLength(0);
-  });
-
-  it('should generate SQL via generateSql()', async () => {
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-      queryCapabilities: () => ({ nativeSql: true, objectqlAggregate: false, inMemory: false }),
-      executeRawSql: vi.fn(),
-    });
-
-    const { sql } = await service.generateSql(baseQuery);
-    expect(sql).toContain('SELECT');
-    expect(sql).toContain('COUNT(*)');
-  });
-
-  it('should expose cubeRegistry for external cube registration', () => {
-    const service = new AnalyticsService({ logger: silentLogger });
-    expect(service.cubeRegistry).toBeInstanceOf(CubeRegistry);
-    expect(service.cubeRegistry.size).toBe(0);
-
-    service.cubeRegistry.register(ordersCube);
-    expect(service.cubeRegistry.size).toBe(1);
-  });
-
-  it('should support strategy priority ordering', async () => {
-    // Custom strategy at priority 5 (before NativeSQL at 10)
-    const customStrategy = {
-      name: 'CustomStrategy',
-      priority: 5,
-      canHandle: () => true,
-      execute: vi.fn().mockResolvedValue({ rows: [{ custom: true }], fields: [] }),
-      generateSql: vi.fn().mockResolvedValue({ sql: 'CUSTOM', params: [] }),
-    };
-
-    const service = new AnalyticsService({
-      cubes: [ordersCube],
-      logger: silentLogger,
-      strategies: [customStrategy],
-      queryCapabilities: () => ({ nativeSql: true, objectqlAggregate: true, inMemory: false }),
-      executeRawSql: vi.fn(),
-    });
-
-    const result = await service.query(baseQuery);
-    expect(customStrategy.execute).toHaveBeenCalled();
-    expect(result.rows[0]).toEqual({ custom: true });
-  });
-});