@objectstack/service-analytics 10.2.0 → 11.0.0

package/dist/index.d.cts

@@ -63,8 +63,9 @@ interface CompiledDataset {
     /** The Cube the dataset compiles to (consumed by the strategy chain). */
     cube: Cube;
     /**
-     * Relationship names declared in `include`. The join allowlist (D-C):
-     * the NativeSQLStrategy rejects any join alias not in this set.
+     * Every join alias the dataset may use — each declared `include` path AND its
+     * intermediate prefixes (ADR-0071). The join allowlist (D-C): the
+     * NativeSQLStrategy rejects any join alias not in this set.
      */
     allowedRelationships: Set<string>;
     /** Derived measures, computed post-aggregation by the executor (Q1). */
@@ -75,12 +76,26 @@ interface CompiledDataset {
     measureFilters: Record<string, FilterCondition>;
 }
 /**
- * Resolves a relationship name on a base object to the related object/table
- * name, using the runtime's object graph. Optional: when omitted the compiler
- * trusts the declared `include` names (the NativeSQLStrategy convention assumes
- * the relationship name equals the related table name).
+ * The related object reached by traversing a relationship: its logical object
+ * name (used to resolve the NEXT hop in a multi-hop chain — ADR-0071) and its
+ * physical table name (the join target).
  */
-type RelationshipResolver = (baseObject: string, relationshipName: string) => string | undefined;
+interface RelationshipTarget {
+    object: string;
+    table: string;
+}
+/**
+ * Resolves a relationship name on a base object to the related object/table,
+ * using the runtime's object graph. Optional: when omitted the compiler trusts
+ * the declared `include` names (the NativeSQLStrategy convention assumes the
+ * relationship name equals the related table name).
+ *
+ * May return a bare table-name `string` (legacy single-hop: object name is
+ * assumed equal to the table) or a {@link RelationshipTarget} (required to
+ * traverse further along a multi-hop path, where object differs from table for
+ * namespaced objects).
+ */
+type RelationshipResolver = (baseObject: string, relationshipName: string) => string | RelationshipTarget | undefined;
 declare function compileDataset(dataset: Dataset, resolver?: RelationshipResolver): CompiledDataset;
 
 /**
@@ -554,14 +569,19 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
      * responsible for isolation — see contract note).
      */
     private applyReadScope;
+    /** SQL-safe join alias for a relationship path (dots → `__`); single-segment
+     *  paths are unchanged. Mirrors the dataset compiler's `cube.joins` keying so
+     *  alias, allowlist, and per-hop RLS all agree on one valid identifier. */
+    private joinAlias;
     /**
      * Resolve a dimension/measure/filter SQL expression that may reference a
      * related table via dot notation (e.g. `account.industry`).
      *
-     * When the resolved `sql` contains a dot, treat the prefix as a lookup
-     * field on the cube's table and synthesise a `LEFT JOIN` against the
-     * related table. The convention (matching the auto-cube generator and
-     * ObjectStack object schemas) is:
+     * A dotted `sql` is a relationship PATH (ADR-0071 multi-hop): every segment
+     * but the last is a to-one relationship hop, the last is the column. Each hop
+     * synthesises a `LEFT JOIN` aliased by its full path prefix, chained
+     * parent→child. The convention (matching the auto-cube generator and
+     * ObjectStack object schemas) for a single hop is:
      *
      *   <parentTable>.<lookupField> = <lookupField>.id
      *
@@ -656,4 +676,4 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private buildFieldMeta;
 }
 
-export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type RelationshipResolver, combineFilters, compileDataset, compileScopedFilterToSql, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange };
+export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type RelationshipResolver, type RelationshipTarget, combineFilters, compileDataset, compileScopedFilterToSql, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange };

package/dist/index.d.ts

@@ -63,8 +63,9 @@ interface CompiledDataset {
     /** The Cube the dataset compiles to (consumed by the strategy chain). */
     cube: Cube;
     /**
-     * Relationship names declared in `include`. The join allowlist (D-C):
-     * the NativeSQLStrategy rejects any join alias not in this set.
+     * Every join alias the dataset may use — each declared `include` path AND its
+     * intermediate prefixes (ADR-0071). The join allowlist (D-C): the
+     * NativeSQLStrategy rejects any join alias not in this set.
      */
     allowedRelationships: Set<string>;
     /** Derived measures, computed post-aggregation by the executor (Q1). */
@@ -75,12 +76,26 @@ interface CompiledDataset {
     measureFilters: Record<string, FilterCondition>;
 }
 /**
- * Resolves a relationship name on a base object to the related object/table
- * name, using the runtime's object graph. Optional: when omitted the compiler
- * trusts the declared `include` names (the NativeSQLStrategy convention assumes
- * the relationship name equals the related table name).
+ * The related object reached by traversing a relationship: its logical object
+ * name (used to resolve the NEXT hop in a multi-hop chain — ADR-0071) and its
+ * physical table name (the join target).
  */
-type RelationshipResolver = (baseObject: string, relationshipName: string) => string | undefined;
+interface RelationshipTarget {
+    object: string;
+    table: string;
+}
+/**
+ * Resolves a relationship name on a base object to the related object/table,
+ * using the runtime's object graph. Optional: when omitted the compiler trusts
+ * the declared `include` names (the NativeSQLStrategy convention assumes the
+ * relationship name equals the related table name).
+ *
+ * May return a bare table-name `string` (legacy single-hop: object name is
+ * assumed equal to the table) or a {@link RelationshipTarget} (required to
+ * traverse further along a multi-hop path, where object differs from table for
+ * namespaced objects).
+ */
+type RelationshipResolver = (baseObject: string, relationshipName: string) => string | RelationshipTarget | undefined;
 declare function compileDataset(dataset: Dataset, resolver?: RelationshipResolver): CompiledDataset;
 
 /**
@@ -554,14 +569,19 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
      * responsible for isolation — see contract note).
      */
     private applyReadScope;
+    /** SQL-safe join alias for a relationship path (dots → `__`); single-segment
+     *  paths are unchanged. Mirrors the dataset compiler's `cube.joins` keying so
+     *  alias, allowlist, and per-hop RLS all agree on one valid identifier. */
+    private joinAlias;
     /**
      * Resolve a dimension/measure/filter SQL expression that may reference a
      * related table via dot notation (e.g. `account.industry`).
      *
-     * When the resolved `sql` contains a dot, treat the prefix as a lookup
-     * field on the cube's table and synthesise a `LEFT JOIN` against the
-     * related table. The convention (matching the auto-cube generator and
-     * ObjectStack object schemas) is:
+     * A dotted `sql` is a relationship PATH (ADR-0071 multi-hop): every segment
+     * but the last is a to-one relationship hop, the last is the column. Each hop
+     * synthesises a `LEFT JOIN` aliased by its full path prefix, chained
+     * parent→child. The convention (matching the auto-cube generator and
+     * ObjectStack object schemas) for a single hop is:
      *
      *   <parentTable>.<lookupField> = <lookupField>.id
      *
@@ -656,4 +676,4 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private buildFieldMeta;
 }
 
-export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type RelationshipResolver, combineFilters, compileDataset, compileScopedFilterToSql, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange };
+export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type RelationshipResolver, type RelationshipTarget, combineFilters, compileDataset, compileScopedFilterToSql, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange };

package/dist/index.js

@@ -132,7 +132,7 @@ var MONGO_TO_CUBE_OP = {
 };
 function stringifyForCube(v) {
   if (v == null) return "";
-  if (typeof v === "boolean") return v ? "1" : "0";
+  if (typeof v === "boolean") return v ? "true" : "false";
   if (v instanceof Date) return v.toISOString();
   if (typeof v === "object") return JSON.stringify(v);
   return String(v);
@@ -187,19 +187,24 @@ function normalizeAnalyticsFilters(query) {
   }
   return out;
 }
+function recoverNumber(s) {
+  if (/^-?\d+(\.\d+)?$/.test(s)) {
+    const n = Number(s);
+    if (Number.isFinite(n)) return n;
+  }
+  return void 0;
+}
 function coerceFilterValueForSql(s) {
   if (s === "true") return 1;
   if (s === "false") return 0;
   if (s === "null") return null;
-  if (/^-?\d+$/.test(s)) {
-    const n = Number(s);
-    if (Number.isFinite(n)) return n;
-  }
-  if (/^-?\d+\.\d+$/.test(s)) {
-    const n = Number(s);
-    if (Number.isFinite(n)) return n;
-  }
-  return s;
+  return recoverNumber(s) ?? s;
+}
+function coerceFilterValueForObjectQL(s) {
+  if (s === "true") return true;
+  if (s === "false") return false;
+  if (s === "null") return null;
+  return recoverNumber(s) ?? s;
 }
 
 // src/read-scope-sql.ts
@@ -451,14 +456,21 @@ var NativeSQLStrategy = class {
     });
     whereClauses.push(`(${rendered})`);
   }
+  /** SQL-safe join alias for a relationship path (dots → `__`); single-segment
+   *  paths are unchanged. Mirrors the dataset compiler's `cube.joins` keying so
+   *  alias, allowlist, and per-hop RLS all agree on one valid identifier. */
+  joinAlias(path) {
+    return path.replace(/\./g, "__");
+  }
   /**
    * Resolve a dimension/measure/filter SQL expression that may reference a
    * related table via dot notation (e.g. `account.industry`).
    *
-   * When the resolved `sql` contains a dot, treat the prefix as a lookup
-   * field on the cube's table and synthesise a `LEFT JOIN` against the
-   * related table. The convention (matching the auto-cube generator and
-   * ObjectStack object schemas) is:
+   * A dotted `sql` is a relationship PATH (ADR-0071 multi-hop): every segment
+   * but the last is a to-one relationship hop, the last is the column. Each hop
+   * synthesises a `LEFT JOIN` aliased by its full path prefix, chained
+   * parent→child. The convention (matching the auto-cube generator and
+   * ObjectStack object schemas) for a single hop is:
    *
    *   <parentTable>.<lookupField> = <lookupField>.id
    *
@@ -470,19 +482,33 @@ var NativeSQLStrategy = class {
    * Pure column references (no dot) are returned as-is.
    */
   qualifyAndRegisterJoin(rawSql, parentTable, joins, cube) {
-    if (!rawSql.includes(".")) return rawSql;
-    const [alias, ...rest] = rawSql.split(".");
-    if (!alias || rest.length === 0) return rawSql;
-    const column = rest.join(".");
-    if (!joins.has(alias)) {
-      const joinTable = cube?.joins?.[alias]?.name ?? alias;
-      const tableRef = joinTable === alias ? `"${alias}"` : `"${joinTable}" "${alias}"`;
-      joins.set(
-        alias,
-        `LEFT JOIN ${tableRef} ON "${parentTable}"."${alias}" = "${alias}"."id"`
-      );
+    if (!rawSql.includes(".")) {
+      const canJoin = !!cube?.joins && Object.keys(cube.joins).length > 0;
+      if (canJoin && /^[A-Za-z_][A-Za-z0-9_]*$/.test(rawSql)) {
+        return `"${parentTable}"."${rawSql}"`;
+      }
+      return rawSql;
+    }
+    const segments = rawSql.split(".");
+    const column = segments[segments.length - 1];
+    const hops = segments.slice(0, -1);
+    if (hops.length === 0 || !column) return rawSql;
+    let parentAlias = parentTable;
+    let prefix = "";
+    for (const seg of hops) {
+      prefix = prefix ? `${prefix}.${seg}` : seg;
+      const alias = this.joinAlias(prefix);
+      if (!joins.has(alias)) {
+        const joinTable = cube?.joins?.[alias]?.name ?? alias;
+        const tableRef = joinTable === alias ? `"${alias}"` : `"${joinTable}" "${alias}"`;
+        joins.set(
+          alias,
+          `LEFT JOIN ${tableRef} ON "${parentAlias}"."${seg}" = "${alias}"."id"`
+        );
+      }
+      parentAlias = alias;
     }
-    return `"${alias}"."${column}"`;
+    return `"${parentAlias}"."${column}"`;
   }
   /**
    * Resolve a member reference (dimension, measure, or filter field) to its
@@ -568,9 +594,11 @@ var NativeSQLStrategy = class {
     const measure = dim ? void 0 : this.lookupMember(cube, member, "measure");
     const rawSql = dim?.sql ?? measure?.sql ?? (member.includes(".") ? member.split(".").slice(1).join(".") : member);
     if (rawSql.includes(".")) {
-      const [alias, ...rest] = rawSql.split(".");
-      const object = cube.joins?.[alias]?.name ?? alias;
-      return { object, field: rest.join(".") };
+      const segments = rawSql.split(".");
+      const field = segments[segments.length - 1];
+      const relPath = segments.slice(0, -1).join(".");
+      const object = cube.joins?.[this.joinAlias(relPath)]?.name ?? relPath;
+      return { object, field };
     }
     return { object: baseTable, field: rawSql };
   }
@@ -815,8 +843,8 @@ var ObjectQLStrategy = class {
     if (operator === "set") return { $ne: null };
     if (operator === "notSet") return null;
     if (!values || values.length === 0) return void 0;
-    const v0 = coerceFilterValueForSql(values[0]);
-    const all = values.map(coerceFilterValueForSql);
+    const v0 = coerceFilterValueForObjectQL(values[0]);
+    const all = values.map(coerceFilterValueForObjectQL);
     switch (operator) {
       case "equals":
         return v0;
@@ -863,6 +891,9 @@ var ObjectQLStrategy = class {
 // src/dataset-compiler.ts
 var UNSUPPORTED_AGGREGATES = /* @__PURE__ */ new Set(["array_agg", "string_agg"]);
 function aggregateToMetricType(m) {
+  if (!m.aggregate) {
+    throw new Error(`[dataset-compiler] non-derived measure "${m.name}" has no aggregate`);
+  }
   if (UNSUPPORTED_AGGREGATES.has(m.aggregate)) {
     throw new Error(
       `[dataset-compiler] measure "${m.name}" uses aggregate "${m.aggregate}" which is not supported by the v1 dataset runtime (supported: count, sum, avg, min, max, count_distinct).`
@@ -886,36 +917,56 @@ function dimensionType(d) {
       return "string";
   }
 }
-function relationshipPrefix(field) {
-  const idx = field.indexOf(".");
+function fieldRelationshipPath(field) {
+  const idx = field.lastIndexOf(".");
   return idx > 0 ? field.slice(0, idx) : null;
 }
+var MAX_JOIN_HOPS = 3;
+var joinAlias = (path) => path.replace(/\./g, "__");
 function compileDataset(dataset, resolver) {
   const include = dataset.include ?? [];
-  const allowedRelationships = new Set(include);
+  const resolveHop = (fromObject, rel) => {
+    if (!resolver) return { object: rel, table: rel };
+    const resolved = resolver(fromObject, rel);
+    if (!resolved) {
+      throw new Error(
+        `[dataset-compiler] dataset "${dataset.name}" includes relationship "${rel}" which does not exist on object "${fromObject}".`
+      );
+    }
+    return typeof resolved === "string" ? { object: resolved, table: resolved } : resolved;
+  };
   const joins = {};
-  for (const rel of include) {
-    let targetTable = rel;
-    if (resolver) {
-      const resolved = resolver(dataset.object, rel);
-      if (!resolved) {
-        throw new Error(
-          `[dataset-compiler] dataset "${dataset.name}" includes relationship "${rel}" which does not exist on object "${dataset.object}".`
-        );
+  for (const path of include) {
+    const segments = path.split(".");
+    if (segments.length > MAX_JOIN_HOPS) {
+      throw new Error(
+        `[dataset-compiler] dataset "${dataset.name}" include path "${path}" exceeds the ${MAX_JOIN_HOPS}-hop limit (${segments.length} hops). Deeper traversal is not supported.`
+      );
+    }
+    let fromObject = dataset.object;
+    let parentAlias = dataset.object;
+    let prefix = "";
+    for (const seg of segments) {
+      prefix = prefix ? `${prefix}.${seg}` : seg;
+      const target = resolveHop(fromObject, seg);
+      const alias = joinAlias(prefix);
+      if (!joins[alias]) {
+        joins[alias] = {
+          name: target.table,
+          relationship: "many_to_one",
+          sql: `${parentAlias}.${seg} = ${prefix}.id`
+        };
       }
-      targetTable = resolved;
+      fromObject = target.object;
+      parentAlias = prefix;
     }
-    joins[rel] = {
-      name: targetTable,
-      relationship: "many_to_one",
-      sql: `${dataset.object}.${rel} = ${rel}.id`
-    };
   }
+  const allowedRelationships = new Set(Object.keys(joins));
   const assertDeclared = (field, ownerKind, ownerName) => {
-    const prefix = relationshipPrefix(field);
-    if (prefix && !allowedRelationships.has(prefix)) {
+    const relPath = fieldRelationshipPath(field);
+    if (relPath && !joins[joinAlias(relPath)]) {
       throw new Error(
-        `[dataset-compiler] ${ownerKind} "${ownerName}" references relationship "${prefix}" via "${field}", but "${prefix}" is not declared in the dataset's \`include\`. v1 only joins along declared relationships.`
+        `[dataset-compiler] ${ownerKind} "${ownerName}" references relationship path "${relPath}" via "${field}", but "${relPath}" is not declared in the dataset's \`include\`. Only fields along a declared relationship path are joinable.`
       );
     }
   };
@@ -1757,9 +1808,10 @@ var AnalyticsService = class {
     if (!cube) {
       cube = this.inferCubeFromQuery(query);
       this.cubeRegistry.register(cube);
-      this.logger.warn(
-        `[Analytics] No cube registered for "${name}"; auto-inferred a minimal cube (sql="${name}", measures=${Object.keys(cube.measures).join(",") || "(none)"}, dimensions=${Object.keys(cube.dimensions).join(",") || "(none)"}). Define an explicit Cube in your stack for full control.`
-      );
+      const isScalarMetric = (query.dimensions?.length ?? 0) === 0 && (query.timeDimensions?.length ?? 0) === 0;
+      const message = `[Analytics] No cube registered for "${name}"; auto-inferred a minimal cube (sql="${name}", measures=${Object.keys(cube.measures).join(",") || "(none)"}, dimensions=${Object.keys(cube.dimensions).join(",") || "(none)"}). Define an explicit Cube in your stack for full control.`;
+      if (isScalarMetric) this.logger.debug(message);
+      else this.logger.warn(message);
       return;
     }
     const stripPrefix = (m) => m.includes(".") ? m.split(".").slice(1).join(".") : m;