@objectstack/service-analytics 3.2.9

package/src/analytics-service.ts

@@ -0,0 +1,231 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  IAnalyticsService,
+  AnalyticsQuery,
+  AnalyticsResult,
+  CubeMeta,
+} from '@objectstack/spec/contracts';
+import type { Cube } from '@objectstack/spec/data';
+import type { Logger } from '@objectstack/spec/contracts';
+import { createLogger } from '@objectstack/core';
+import { CubeRegistry } from './cube-registry.js';
+import type { AnalyticsStrategy, DriverCapabilities, StrategyContext } from './strategies/types.js';
+import { NativeSQLStrategy } from './strategies/native-sql-strategy.js';
+import { ObjectQLStrategy } from './strategies/objectql-strategy.js';
+
+/**
+ * Configuration for AnalyticsService.
+ */
+export interface AnalyticsServiceConfig {
+  /** Pre-defined cube definitions (from manifest). */
+  cubes?: Cube[];
+  /** Logger instance. */
+  logger?: Logger;
+  /**
+   * Probe driver capabilities for the object that backs a cube.
+   * The service calls this function to decide which strategy can handle a query.
+   */
+  queryCapabilities?: (cubeName: string) => DriverCapabilities;
+  /**
+   * Execute raw SQL on the driver for a given object.
+   * Required for NativeSQLStrategy.
+   */
+  executeRawSql?: (objectName: string, sql: string, params: unknown[]) => Promise<Record<string, unknown>[]>;
+  /**
+   * Execute an ObjectQL aggregate query.
+   * Required for ObjectQLStrategy.
+   */
+  executeAggregate?: (objectName: string, options: {
+    groupBy?: string[];
+    aggregations?: Array<{ field: string; method: string; alias: string }>;
+    filter?: Record<string, unknown>;
+  }) => Promise<Record<string, unknown>[]>;
+  /**
+   * Fallback IAnalyticsService (e.g. MemoryAnalyticsService).
+   * Used by InMemoryStrategy.
+   */
+  fallbackService?: IAnalyticsService;
+  /**
+   * Custom strategies to add/replace the defaults.
+   * They are merged with the built-in strategies and sorted by priority.
+   */
+  strategies?: AnalyticsStrategy[];
+}
+
+/**
+ * Default capabilities when probing is not configured — assumes in-memory only.
+ */
+const DEFAULT_CAPABILITIES: DriverCapabilities = {
+  nativeSql: false,
+  objectqlAggregate: false,
+  inMemory: true,
+};
+
+/**
+ * AnalyticsService — Multi-driver analytics orchestrator.
+ *
+ * Implements `IAnalyticsService` by delegating to a priority-ordered
+ * strategy chain:
+ *
+ * | Priority | Strategy | Condition |
+ * |:---:|:---|:---|
+ * | P1 (10) | NativeSQLStrategy | Driver supports raw SQL |
+ * | P2 (20) | ObjectQLStrategy | Driver supports aggregate AST |
+ * | P3 (30) | (custom / InMemoryStrategy from driver-memory) | Injected by user |
+ *
+ * When `fallbackService` is configured, an internal delegate strategy
+ * is automatically appended at priority 30 as a safety net.
+ *
+ * The service also owns a `CubeRegistry` for metadata discovery and
+ * auto-inference from object schemas.
+ */
+export class AnalyticsService implements IAnalyticsService {
+  private readonly strategies: AnalyticsStrategy[];
+  private readonly strategyCtx: StrategyContext;
+  readonly cubeRegistry: CubeRegistry;
+  private readonly logger: Logger;
+
+  constructor(config: AnalyticsServiceConfig = {}) {
+    this.logger = config.logger || createLogger({ level: 'info', format: 'pretty' });
+    this.cubeRegistry = new CubeRegistry();
+
+    // Register pre-defined cubes
+    if (config.cubes) {
+      this.cubeRegistry.registerAll(config.cubes);
+    }
+
+    // Build strategy context
+    this.strategyCtx = {
+      getCube: (name) => this.cubeRegistry.get(name),
+      queryCapabilities: config.queryCapabilities || (() => DEFAULT_CAPABILITIES),
+      executeRawSql: config.executeRawSql,
+      executeAggregate: config.executeAggregate,
+      fallbackService: config.fallbackService,
+    };
+
+    // Build strategy chain (built-in + custom, sorted by priority)
+    // InMemoryStrategy is NOT built-in — it lives in @objectstack/driver-memory
+    // and should be passed via config.strategies when needed.
+    // When fallbackService is configured, an internal delegate is added at P3.
+    const builtIn: AnalyticsStrategy[] = [
+      new NativeSQLStrategy(),
+      new ObjectQLStrategy(),
+    ];
+
+    // Auto-add fallback delegate when fallbackService is provided
+    if (config.fallbackService) {
+      builtIn.push(new FallbackDelegateStrategy());
+    }
+
+    const custom = config.strategies || [];
+    this.strategies = [...builtIn, ...custom].sort((a, b) => a.priority - b.priority);
+
+    this.logger.info(
+      `[Analytics] Initialized with ${this.cubeRegistry.size} cubes, ` +
+      `${this.strategies.length} strategies: ${this.strategies.map(s => s.name).join(' → ')}`,
+    );
+  }
+
+  /**
+   * Execute an analytical query by delegating to the first capable strategy.
+   */
+  async query(query: AnalyticsQuery): Promise<AnalyticsResult> {
+    if (!query.cube) {
+      throw new Error('Cube name is required in analytics query');
+    }
+
+    const strategy = this.resolveStrategy(query);
+    this.logger.debug(`[Analytics] Query on cube "${query.cube}" → ${strategy.name}`);
+
+    return strategy.execute(query, this.strategyCtx);
+  }
+
+  /**
+   * Get cube metadata for discovery.
+   */
+  async getMeta(cubeName?: string): Promise<CubeMeta[]> {
+    // If a fallback service is configured, merge its metadata with the registry
+    const cubes = cubeName
+      ? [this.cubeRegistry.get(cubeName)].filter(Boolean) as Cube[]
+      : this.cubeRegistry.getAll();
+
+    return cubes.map(cube => ({
+      name: cube.name,
+      title: cube.title,
+      measures: Object.entries(cube.measures).map(([key, measure]) => ({
+        name: `${cube.name}.${key}`,
+        type: measure.type,
+        title: measure.label,
+      })),
+      dimensions: Object.entries(cube.dimensions).map(([key, dimension]) => ({
+        name: `${cube.name}.${key}`,
+        type: dimension.type,
+        title: dimension.label,
+      })),
+    }));
+  }
+
+  /**
+   * Generate SQL for a query without executing it (dry-run).
+   */
+  async generateSql(query: AnalyticsQuery): Promise<{ sql: string; params: unknown[] }> {
+    if (!query.cube) {
+      throw new Error('Cube name is required for SQL generation');
+    }
+
+    const strategy = this.resolveStrategy(query);
+    this.logger.debug(`[Analytics] generateSql on cube "${query.cube}" → ${strategy.name}`);
+
+    return strategy.generateSql(query, this.strategyCtx);
+  }
+
+  // ── Internal ─────────────────────────────────────────────────────
+
+  /**
+   * Walk the strategy chain and return the first strategy that can handle the query.
+   */
+  private resolveStrategy(query: AnalyticsQuery): AnalyticsStrategy {
+    for (const strategy of this.strategies) {
+      if (strategy.canHandle(query, this.strategyCtx)) {
+        return strategy;
+      }
+    }
+    throw new Error(
+      `[Analytics] No strategy can handle query for cube "${query.cube}". ` +
+      `Checked: ${this.strategies.map(s => s.name).join(', ')}. ` +
+      'Ensure a compatible driver is configured or a fallback service is registered.',
+    );
+  }
+}
+
+/**
+ * FallbackDelegateStrategy — Internal strategy for fallback service delegation.
+ *
+ * Automatically added to the strategy chain when `fallbackService` is configured.
+ * Not exported — consumers who need explicit in-memory support should use
+ * `InMemoryStrategy` from `@objectstack/driver-memory`.
+ */
+class FallbackDelegateStrategy implements AnalyticsStrategy {
+  readonly name = 'FallbackDelegateStrategy';
+  readonly priority = 30;
+
+  canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean {
+    if (!query.cube) return false;
+    return !!ctx.fallbackService;
+  }
+
+  async execute(query: AnalyticsQuery, ctx: StrategyContext): Promise<AnalyticsResult> {
+    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: `-- FallbackDelegateStrategy: SQL generation not supported for cube "${query.cube}"`,
+      params: [],
+    };
+  }
+}

package/src/cube-registry.ts

@@ -0,0 +1,147 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Cube } from '@objectstack/spec/data';
+
+/**
+ * CubeRegistry — Central registry for analytics cube definitions.
+ *
+ * Cubes can be registered from two sources:
+ * 1. **Manifest definitions** — Explicit cube definitions in `objectstack.config.ts`.
+ * 2. **Object schema inference** — Auto-generated cubes from ObjectQL object schemas.
+ *
+ * The registry is the single source of truth for cube metadata discovery
+ * (used by `getMeta()` and the strategy chain).
+ */
+export class CubeRegistry {
+  private cubes = new Map<string, Cube>();
+
+  /** Register a single cube definition. Overwrites if name already exists. */
+  register(cube: Cube): void {
+    this.cubes.set(cube.name, cube);
+  }
+
+  /** Register multiple cube definitions at once. */
+  registerAll(cubes: Cube[]): void {
+    for (const cube of cubes) {
+      this.register(cube);
+    }
+  }
+
+  /** Get a cube definition by name. */
+  get(name: string): Cube | undefined {
+    return this.cubes.get(name);
+  }
+
+  /** Check if a cube is registered. */
+  has(name: string): boolean {
+    return this.cubes.has(name);
+  }
+
+  /** Return all registered cubes. */
+  getAll(): Cube[] {
+    return Array.from(this.cubes.values());
+  }
+
+  /** Return all cube names. */
+  names(): string[] {
+    return Array.from(this.cubes.keys());
+  }
+
+  /** Number of registered cubes. */
+  get size(): number {
+    return this.cubes.size;
+  }
+
+  /** Remove all cubes. */
+  clear(): void {
+    this.cubes.clear();
+  }
+
+  /**
+   * Auto-generate a cube definition from an object schema.
+   *
+   * Heuristic rules:
+   * - `number` fields → `sum`, `avg`, `min`, `max` measures
+   * - `boolean` fields → `count` measure (count where true)
+   * - All non-computed fields → dimensions
+   * - `date`/`datetime` fields → time dimensions with standard granularities
+   * - A default `count` measure is always added
+   *
+   * @param objectName - The snake_case object name (used as table/cube name)
+   * @param fields - Array of field descriptors `{ name, type, label? }`
+   */
+  inferFromObject(
+    objectName: string,
+    fields: Array<{ name: string; type: string; label?: string }>,
+  ): Cube {
+    const measures: Record<string, any> = {
+      count: {
+        name: 'count',
+        label: 'Count',
+        type: 'count',
+        sql: '*',
+      },
+    };
+    const dimensions: Record<string, any> = {};
+
+    for (const field of fields) {
+      const label = field.label || field.name;
+
+      // All fields become dimensions
+      const dimType = this.fieldTypeToDimensionType(field.type);
+      dimensions[field.name] = {
+        name: field.name,
+        label,
+        type: dimType,
+        sql: field.name,
+        ...(dimType === 'time'
+          ? { granularities: ['day', 'week', 'month', 'quarter', 'year'] }
+          : {}),
+      };
+
+      // Numeric fields also become aggregation measures
+      if (field.type === 'number' || field.type === 'currency' || field.type === 'percent') {
+        measures[`${field.name}_sum`] = {
+          name: `${field.name}_sum`,
+          label: `${label} (Sum)`,
+          type: 'sum',
+          sql: field.name,
+        };
+        measures[`${field.name}_avg`] = {
+          name: `${field.name}_avg`,
+          label: `${label} (Avg)`,
+          type: 'avg',
+          sql: field.name,
+        };
+      }
+    }
+
+    const cube: Cube = {
+      name: objectName,
+      title: objectName,
+      sql: objectName,
+      measures,
+      dimensions,
+      public: false,
+    };
+
+    this.register(cube);
+    return cube;
+  }
+
+  private fieldTypeToDimensionType(fieldType: string): string {
+    switch (fieldType) {
+      case 'number':
+      case 'currency':
+      case 'percent':
+        return 'number';
+      case 'boolean':
+        return 'boolean';
+      case 'date':
+      case 'datetime':
+        return 'time';
+      default:
+        return 'string';
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+// Core service
+export { AnalyticsService } from './analytics-service.js';
+export type { AnalyticsServiceConfig } from './analytics-service.js';
+
+// Kernel plugin
+export { AnalyticsServicePlugin } from './plugin.js';
+export type { AnalyticsServicePluginOptions } from './plugin.js';
+
+// Cube registry
+export { CubeRegistry } from './cube-registry.js';
+
+// Strategies
+export { NativeSQLStrategy } from './strategies/native-sql-strategy.js';
+export { ObjectQLStrategy } from './strategies/objectql-strategy.js';
+export type { AnalyticsStrategy, StrategyContext, DriverCapabilities } from './strategies/types.js';
+
+// Note: InMemoryStrategy is exported from @objectstack/driver-memory

package/src/plugin.ts

@@ -0,0 +1,133 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import type { Cube } from '@objectstack/spec/data';
+import type { IAnalyticsService } from '@objectstack/spec/contracts';
+import { AnalyticsService } from './analytics-service.js';
+import type { AnalyticsServiceConfig } from './analytics-service.js';
+import type { DriverCapabilities } from './strategies/types.js';
+
+/**
+ * Configuration for AnalyticsServicePlugin.
+ */
+export interface AnalyticsServicePluginOptions {
+  /** Pre-defined cube definitions (from manifest). */
+  cubes?: Cube[];
+  /**
+   * Probe driver capabilities for a given cube.
+   * When omitted, defaults to in-memory only.
+   */
+  queryCapabilities?: (cubeName: string) => DriverCapabilities;
+  /**
+   * Execute raw SQL on a driver. Enables NativeSQLStrategy.
+   */
+  executeRawSql?: (objectName: string, sql: string, params: unknown[]) => Promise<Record<string, unknown>[]>;
+  /**
+   * Execute ObjectQL aggregate. Enables ObjectQLStrategy.
+   */
+  executeAggregate?: (objectName: string, options: {
+    groupBy?: string[];
+    aggregations?: Array<{ field: string; method: string; alias: string }>;
+    filter?: Record<string, unknown>;
+  }) => Promise<Record<string, unknown>[]>;
+  /** Enable debug logging. */
+  debug?: boolean;
+}
+
+/**
+ * AnalyticsServicePlugin — Kernel plugin for multi-driver analytics.
+ *
+ * Lifecycle:
+ * 1. **init** — Creates `AnalyticsService`, registers as `'analytics'` service.
+ *    If an existing analytics service is already registered (e.g. MemoryAnalyticsService
+ *    from dev-plugin), it is captured as the `fallbackService`.
+ * 2. **start** — Triggers `'analytics:ready'` hook so other plugins can
+ *    register cubes or extend the service.
+ * 3. **destroy** — Cleans up references.
+ *
+ * @example
+ * ```ts
+ * import { LiteKernel } from '@objectstack/core';
+ * import { AnalyticsServicePlugin } from '@objectstack/service-analytics';
+ *
+ * const kernel = new LiteKernel();
+ * kernel.use(new AnalyticsServicePlugin({
+ *   cubes: [ordersCube],
+ *   queryCapabilities: (cube) => ({ nativeSql: true, objectqlAggregate: true, inMemory: false }),
+ *   executeRawSql: async (obj, sql, params) => pgPool.query(sql, params).then(r => r.rows),
+ * }));
+ * await kernel.bootstrap();
+ *
+ * const analytics = kernel.getService<IAnalyticsService>('analytics');
+ * const result = await analytics.query({ cube: 'orders', measures: ['orders.count'] });
+ * ```
+ */
+export class AnalyticsServicePlugin implements Plugin {
+  name = 'com.objectstack.service-analytics';
+  version = '1.0.0';
+  type = 'standard' as const;
+  dependencies: string[] = [];
+
+  private service?: AnalyticsService;
+  private readonly options: AnalyticsServicePluginOptions;
+
+  constructor(options: AnalyticsServicePluginOptions = {}) {
+    this.options = options;
+  }
+
+  async init(ctx: PluginContext): Promise<void> {
+    // Check if there is an existing analytics service (e.g. from dev-plugin)
+    let fallbackService: IAnalyticsService | undefined;
+    try {
+      const existing = ctx.getService<IAnalyticsService>('analytics');
+      if (existing && typeof existing.query === 'function') {
+        fallbackService = existing;
+        ctx.logger.debug('[Analytics] Found existing analytics service, using as fallback');
+      }
+    } catch {
+      // No existing service — that's fine
+    }
+
+    const config: AnalyticsServiceConfig = {
+      cubes: this.options.cubes,
+      logger: ctx.logger,
+      queryCapabilities: this.options.queryCapabilities,
+      executeRawSql: this.options.executeRawSql,
+      executeAggregate: this.options.executeAggregate,
+      fallbackService,
+    };
+
+    this.service = new AnalyticsService(config);
+
+    // Register or replace the analytics service
+    if (fallbackService) {
+      ctx.replaceService('analytics', this.service);
+    } else {
+      ctx.registerService('analytics', this.service);
+    }
+
+    if (this.options.debug) {
+      ctx.hook('analytics:beforeQuery', async (query: unknown) => {
+        ctx.logger.debug('[Analytics] Before query', { query });
+      });
+    }
+
+    ctx.logger.info('[Analytics] Service initialized');
+  }
+
+  async start(ctx: PluginContext): Promise<void> {
+    if (!this.service) return;
+
+    // Notify other plugins that analytics is ready
+    await ctx.trigger('analytics:ready', this.service);
+
+    ctx.logger.info(
+      `[Analytics] Service started with ${this.service.cubeRegistry.size} cubes: ` +
+      `${this.service.cubeRegistry.names().join(', ') || '(none)'}`,
+    );
+  }
+
+  async destroy(): Promise<void> {
+    this.service = undefined;
+  }
+}