@hypequery/datasets 0.15.0 → 0.17.0

package/dist/utils/derived-measure-validation.js

@@ -0,0 +1,138 @@
+import { isSafeSQLIdentifier } from '../sql-utils.js';
+import { isBaseMeasure, isDerivedMeasure } from './dataset-measures.js';
+function fail(datasetName, measureName, detail) {
+    throw new Error(`Invalid dataset "${datasetName}": derived measure "${measureName}" ${detail}`);
+}
+const BINARY_OPERATORS = new Set(['add', 'subtract', 'multiply', 'divide']);
+const FUNCTION_ARITIES = {
+    nullIfZero: [1],
+    coalesce: [2],
+    round: [2],
+    floor: [1],
+    ceil: [1],
+};
+function collectReferences(datasetName, measureName, expression, references, budget, depth = 0) {
+    budget.nodes += 1;
+    if (depth > 16 || budget.nodes > 256) {
+        fail(datasetName, measureName, 'formula exceeds the expression limits.');
+    }
+    if (typeof expression !== 'object' || expression === null) {
+        fail(datasetName, measureName, 'formula contains an invalid expression.');
+    }
+    switch (expression.kind) {
+        case 'ref':
+            if (typeof expression.name !== 'string' || !isSafeSQLIdentifier(expression.name)) {
+                fail(datasetName, measureName, 'formula contains an invalid input reference.');
+            }
+            references.add(expression.name);
+            return;
+        case 'literal':
+            if (expression.value !== null
+                && typeof expression.value !== 'string'
+                && typeof expression.value !== 'boolean'
+                && (typeof expression.value !== 'number' || !Number.isFinite(expression.value))) {
+                fail(datasetName, measureName, 'formula contains an invalid literal.');
+            }
+            return;
+        case 'binary':
+            if (!BINARY_OPERATORS.has(expression.operator)) {
+                fail(datasetName, measureName, 'formula contains an unsupported binary operator.');
+            }
+            collectReferences(datasetName, measureName, expression.left, references, budget, depth + 1);
+            collectReferences(datasetName, measureName, expression.right, references, budget, depth + 1);
+            return;
+        case 'function':
+            if (!Array.isArray(expression.args)
+                || !FUNCTION_ARITIES[expression.name]?.includes(expression.args.length)) {
+                fail(datasetName, measureName, 'formula contains an unsupported function or arity.');
+            }
+            expression.args.forEach(argument => collectReferences(datasetName, measureName, argument, references, budget, depth + 1));
+            return;
+        default:
+            fail(datasetName, measureName, 'formula contains an unsupported expression kind.');
+    }
+}
+function evaluateFormula(datasetName, measureName, definition) {
+    const aliases = Object.keys(definition.uses);
+    let formula;
+    try {
+        formula = definition.formula(Object.fromEntries(aliases.map(alias => [alias, alias])));
+    }
+    catch (error) {
+        fail(datasetName, measureName, `formula threw: ${error instanceof Error ? error.message : String(error)}.`);
+    }
+    if (typeof formula !== 'object'
+        || formula === null
+        || formula.__type !== 'formula_expr'
+        || typeof formula.toSQL !== 'function'
+        || typeof formula.expression !== 'object'
+        || formula.expression === null) {
+        fail(datasetName, measureName, 'formula must return a FormulaExpr.');
+    }
+    return formula;
+}
+function assertAcyclic(datasetName, derivedMeasures) {
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (name) => {
+        if (visiting.has(name))
+            fail(datasetName, name, 'contains a dependency cycle.');
+        if (visited.has(name))
+            return;
+        if (!Object.hasOwn(derivedMeasures, name))
+            return;
+        const definition = derivedMeasures[name];
+        visiting.add(name);
+        Object.values(definition.uses).forEach(dependency => visit(dependency));
+        visiting.delete(name);
+        visited.add(name);
+    };
+    Object.keys(derivedMeasures).forEach(visit);
+}
+export function validateDerivedMeasures(datasetName, measures) {
+    const baseMeasures = Object.fromEntries(Object.entries(measures).filter(([, definition]) => definition && isBaseMeasure(definition)));
+    const derivedMeasures = Object.fromEntries(Object.entries(measures).filter(([, definition]) => definition && isDerivedMeasure(definition)));
+    for (const [measureName, definition] of Object.entries(derivedMeasures)) {
+        if (!isSafeSQLIdentifier(measureName)) {
+            fail(datasetName, measureName, 'name is not a safe identifier.');
+        }
+        if (typeof definition !== 'object' || definition === null || definition.__type !== 'derived_measure_definition') {
+            fail(datasetName, measureName, 'must be created with measure.derived().');
+        }
+        if (typeof definition.uses !== 'object' || definition.uses === null || Array.isArray(definition.uses)) {
+            fail(datasetName, measureName, 'must declare an input map.');
+        }
+    }
+    assertAcyclic(datasetName, derivedMeasures);
+    for (const [measureName, definition] of Object.entries(derivedMeasures)) {
+        const uses = Object.entries(definition.uses);
+        if (uses.length === 0)
+            fail(datasetName, measureName, 'must reference at least one base measure.');
+        if (typeof definition.formula !== 'function')
+            fail(datasetName, measureName, 'must define a formula function.');
+        for (const [alias, dependencyName] of uses) {
+            if (!isSafeSQLIdentifier(alias))
+                fail(datasetName, measureName, `has invalid input alias "${alias}".`);
+            if (typeof dependencyName !== 'string' || dependencyName.includes('.')) {
+                fail(datasetName, measureName, `references cross-dataset measure "${String(dependencyName)}".`);
+            }
+            if (Object.hasOwn(derivedMeasures, dependencyName)) {
+                fail(datasetName, measureName, `references derived measure "${dependencyName}"; v1 inputs must be base measures.`);
+            }
+            if (!Object.hasOwn(baseMeasures, dependencyName))
+                fail(datasetName, measureName, `references missing measure "${dependencyName}".`);
+        }
+        const references = new Set();
+        collectReferences(datasetName, measureName, evaluateFormula(datasetName, measureName, definition).expression, references, { nodes: 0 });
+        for (const reference of references) {
+            if (!Object.hasOwn(definition.uses, reference)) {
+                fail(datasetName, measureName, `formula references undeclared input alias "${reference}".`);
+            }
+        }
+        for (const [alias] of uses) {
+            if (!references.has(alias)) {
+                fail(datasetName, measureName, `declares unused input alias "${alias}".`);
+            }
+        }
+    }
+}

package/dist/utils/protocol-metric-expressions.d.ts

@@ -1,6 +1,7 @@
 import { type ProtocolExpression, type ProtocolMetricDerivation } from '@hypequery/protocol';
-import type { AggregationSpec, DerivedMetricSpec, MetricFilter } from '../types.js';
+import type { AggregationSpec, DerivedMeasureDefinition, DerivedMetricSpec, MetricFilter } from '../types.js';
 export declare function filterExpression(filter: MetricFilter): ProtocolExpression;
+export declare function derivedMeasureExpression(definition: DerivedMeasureDefinition): ProtocolExpression;
 export declare function metricExpression(spec: AggregationSpec | DerivedMetricSpec): ProtocolExpression;
 /**
  * The formula in the shape it was authored in, beside the inlined form.

package/dist/utils/protocol-metric-expressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsCpF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AA+CD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}
+{"version":3,"file":"protocol-metric-expressions.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-metric-expressions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEgB,KAAK,kBAAkB,EAAE,KAAK,wBAAwB,EAC5E,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsC9G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAgBzE;AA+CD,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,wBAAwB,GAAG,kBAAkB,CAGjG;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,iBAAiB,GAAG,kBAAkB,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CASlF"}

package/dist/utils/protocol-metric-expressions.js

@@ -85,6 +85,10 @@ function semanticExpression(expression, references = {}) {
             };
     }
 }
+export function derivedMeasureExpression(definition) {
+    const aliases = Object.fromEntries(Object.keys(definition.uses).map(alias => [alias, alias]));
+    return semanticExpression(definition.formula(aliases).expression);
+}
 export function metricExpression(spec) {
     if (spec.__type === 'aggregation_spec')
         return aggregationExpression(spec);

package/dist/utils/semantic-metadata-validation.d.ts

@@ -1,4 +1,4 @@
-import type { DatasetConfig, DimensionDefinition, MeasureDefinition, RelationshipDefinition, SemanticMetadata } from '../types.js';
+import type { DatasetConfig, DatasetMeasureDefinition, DimensionDefinition, RelationshipDefinition, SemanticMetadata } from '../types.js';
 export declare function validateSemanticMetadata(datasetName: string, location: string, metadata: SemanticMetadata): void;
-export declare function validateDatasetAgentMetadata<TDimensions extends Record<string, DimensionDefinition>, TMeasures extends Record<string, MeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition>>(datasetName: string, config: DatasetConfig<TDimensions, TMeasures, TRelationships>): void;
+export declare function validateDatasetAgentMetadata<TDimensions extends Record<string, DimensionDefinition>, TMeasures extends Record<string, DatasetMeasureDefinition>, TRelationships extends Record<string, RelationshipDefinition>>(datasetName: string, config: DatasetConfig<TDimensions, TMeasures, TRelationships>): void;
 //# sourceMappingURL=semantic-metadata-validation.d.ts.map

package/dist/utils/semantic-metadata-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-metadata-validation.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAoBrB,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CA8BN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACnD,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAE7D,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,IAAI,CAuDN"}
+{"version":3,"file":"semantic-metadata-validation.d.ts","sourceRoot":"","sources":["../../src/utils/semantic-metadata-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAoBrB,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CA8BN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACvD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1D,cAAc,SAAS,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAE7D,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,GAC5D,IAAI,CAuDN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Code-first TypeScript semantic layer for ClickHouse datasets, metrics, multi-tenancy, and AI agents",
   "keywords": [
     "semantic-layer",
@@ -42,7 +42,7 @@
     "dist"
   ],
   "dependencies": {
-    "@hypequery/protocol": "^0.13.0",
+    "@hypequery/protocol": "^0.14.0",
     "@noble/hashes": "^1.8.0",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.23.5"
@@ -60,7 +60,7 @@
     "typescript": "^5.7.3",
     "@vitest/coverage-v8": "^3.2.6",
     "vitest": "^3.2.6",
-    "@hypequery/protocol-conformance": "^0.11.1"
+    "@hypequery/protocol-conformance": "^0.11.2"
   },
   "repository": {
     "type": "git",