@hypequery/datasets 0.14.0 → 0.16.0

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

@@ -0,0 +1,118 @@
+import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, validateCanonicalValue, } from '@hypequery/protocol';
+function canonicalValue(input) {
+    if (Array.isArray(input)) {
+        return validateCanonicalValue({
+            $hypequery: {
+                type: 'array',
+                version: 1,
+                values: input.map(canonicalValue),
+            },
+        });
+    }
+    if (typeof input === 'object' && input !== null) {
+        if ('$hypequery' in input)
+            return validateCanonicalValue(input);
+        const prototype = Object.getPrototypeOf(input);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError('Dataset protocol adapter only accepts plain filter values.');
+        }
+        return validateCanonicalValue({
+            $hypequery: {
+                type: 'map',
+                version: 1,
+                entries: Object.entries(input)
+                    .sort(([left], [right]) => left.localeCompare(right))
+                    .map(([key, value]) => [key, canonicalValue(value)]),
+            },
+        });
+    }
+    return validateCanonicalValue(input);
+}
+export function filterExpression(filter) {
+    const left = {
+        kind: 'reference',
+        name: parseProtocolQualifiedIdentifier(filter.field),
+    };
+    const right = {
+        kind: 'literal',
+        value: canonicalValue(filter.value),
+    };
+    const result = {
+        kind: 'comparison',
+        operator: filter.operator,
+        left,
+        right,
+    };
+    return result;
+}
+function aggregationExpression(spec) {
+    const result = {
+        kind: 'aggregate',
+        aggregation: spec.aggregation,
+        field: parseProtocolQualifiedIdentifier(spec.field),
+        ...(spec.argField !== undefined
+            ? { argField: parseProtocolQualifiedIdentifier(spec.argField) }
+            : {}),
+        ...(spec.level !== undefined ? { level: spec.level } : {}),
+        ...(spec.filters?.length
+            ? { filters: spec.filters.map(filterExpression) }
+            : {}),
+    };
+    return result;
+}
+function semanticExpression(expression, references = {}) {
+    switch (expression.kind) {
+        case 'ref':
+            return references[expression.name]
+                ?? {
+                    kind: 'reference',
+                    name: parseProtocolQualifiedIdentifier(expression.name),
+                };
+        case 'literal':
+            return { kind: 'literal', value: canonicalValue(expression.value) };
+        case 'binary':
+            return {
+                kind: 'binary',
+                operator: expression.operator,
+                left: semanticExpression(expression.left, references),
+                right: semanticExpression(expression.right, references),
+            };
+        case 'function':
+            return {
+                kind: 'call',
+                function: expression.name,
+                args: expression.args.map(argument => semanticExpression(argument, references)),
+            };
+    }
+}
+export function metricExpression(spec) {
+    if (spec.__type === 'aggregation_spec')
+        return aggregationExpression(spec);
+    const aliases = Object.fromEntries(Object.keys(spec.uses).map(alias => [alias, alias]));
+    const references = Object.fromEntries(Object.entries(spec.uses).map(([alias, metric]) => [
+        alias,
+        aggregationExpression(metric.spec),
+    ]));
+    return semanticExpression(spec.formula(aliases).expression, references);
+}
+/**
+ * The formula in the shape it was authored in, beside the inlined form.
+ *
+ * `metricExpression` above substitutes each input's aggregate where the formula
+ * named it, which states what the metric means but drops the aliases. Those
+ * aliases are the column names of the intermediate aggregate, so a catalog
+ * rebuilt without them computes the same number through different SQL.
+ *
+ * Input order follows `uses` and is not sorted: each entry becomes a column of
+ * that intermediate result in this order.
+ */
+export function metricDerivation(spec) {
+    const aliases = Object.fromEntries(Object.keys(spec.uses).map(alias => [alias, alias]));
+    return {
+        inputs: Object.entries(spec.uses).map(([alias, metric]) => ({
+            alias: parseProtocolIdentifier(alias),
+            expression: aggregationExpression(metric.spec),
+        })),
+        expression: semanticExpression(spec.formula(aliases).expression),
+    };
+}

package/dist/utils/protocol-rehydrate-derivation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Rebuilds a derived metric's formula from the contract's authored form.
+ *
+ * The formula is reconstructed by calling the same helpers in `formulas.ts`
+ * that authored it, rather than by compiling the expression to SQL here. That
+ * is deliberate: those helpers carry the `toSQL` closures that decide spacing,
+ * parenthesisation, and function spelling, so reusing them makes byte-identity
+ * structural. A second compiler would be a second place for that spelling to
+ * live, and the two would drift the first time either changed.
+ */
+import type { ProtocolMetricDerivation } from '@hypequery/protocol';
+import type { FormulaExpr } from '../types.js';
+type Unsupported = (reason: string) => Error;
+/**
+ * The formula function a derived metric spec expects.
+ *
+ * The returned function maps each declared alias through the caller-supplied
+ * `inputs` record, exactly as an authored formula does — both the plan builder
+ * and the query-builder path pass alias-to-alias, so the emitted column names
+ * are the ones the contract declared.
+ *
+ * The formula is built once here as well, so a malformed one is refused when
+ * the metric is rebuilt rather than on the first query that reaches it.
+ */
+export declare function rehydrateDerivedFormula(derivation: ProtocolMetricDerivation, unsupported: Unsupported): (inputs: Record<string, string>) => FormulaExpr;
+export {};
+//# sourceMappingURL=protocol-rehydrate-derivation.d.ts.map

package/dist/utils/protocol-rehydrate-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-rehydrate-derivation.d.ts","sourceRoot":"","sources":["../../src/utils/protocol-rehydrate-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAsB,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAYxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAQ/C,KAAK,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,KAAK,CAAC;AA8G7C;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,wBAAwB,EACpC,WAAW,EAAE,WAAW,GACvB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,WAAW,CAGjD"}

package/dist/utils/protocol-rehydrate-derivation.js

@@ -0,0 +1,104 @@
+/**
+ * Rebuilds a derived metric's formula from the contract's authored form.
+ *
+ * The formula is reconstructed by calling the same helpers in `formulas.ts`
+ * that authored it, rather than by compiling the expression to SQL here. That
+ * is deliberate: those helpers carry the `toSQL` closures that decide spacing,
+ * parenthesisation, and function spelling, so reusing them makes byte-identity
+ * structural. A second compiler would be a second place for that spelling to
+ * live, and the two would drift the first time either changed.
+ */
+import { add, ceil, coalesce, divide, floor, multiply, nullIfZero, round, subtract, } from '../formulas.js';
+const BINARY = {
+    add, subtract, multiply, divide,
+};
+function arity(args, expected, name, unsupported) {
+    if (args.length !== expected) {
+        throw unsupported(`"${name}" takes ${expected} argument(s), received ${args.length}`);
+    }
+}
+function literalNumber(expression, unsupported) {
+    if (expression.kind !== 'literal' || typeof expression.value !== 'number') {
+        throw unsupported('expected a numeric literal argument');
+    }
+    return expression.value;
+}
+/**
+ * A `coalesce` fallback, the one position that accepts a bare value.
+ *
+ * `formulas.ts` renders a number through `String(...)` and anything else
+ * through the operand path, so both round-trip to the same SQL.
+ */
+function fallback(expression, resolve, unsupported) {
+    if (expression.kind !== 'literal')
+        return operand(expression, resolve, unsupported);
+    if (typeof expression.value !== 'number') {
+        throw unsupported('a "coalesce" fallback literal must be numeric');
+    }
+    return expression.value;
+}
+function operand(expression, resolve, unsupported) {
+    switch (expression.kind) {
+        case 'reference':
+            // An alias, or a column the formula named directly. `resolveArg` in
+            // `formulas.ts` passes a string through unchanged, which is what the
+            // authored form did with the same name.
+            return resolve(String(expression.name));
+        case 'binary': {
+            const build = BINARY[expression.operator];
+            if (build === undefined)
+                throw unsupported(`unsupported operator "${expression.operator}"`);
+            return build(operand(expression.left, resolve, unsupported), operand(expression.right, resolve, unsupported));
+        }
+        case 'call':
+            switch (expression.function) {
+                case 'nullIfZero':
+                    arity(expression.args, 1, 'nullIfZero', unsupported);
+                    return nullIfZero(operand(expression.args[0], resolve, unsupported));
+                case 'floor':
+                    arity(expression.args, 1, 'floor', unsupported);
+                    return floor(operand(expression.args[0], resolve, unsupported));
+                case 'ceil':
+                    arity(expression.args, 1, 'ceil', unsupported);
+                    return ceil(operand(expression.args[0], resolve, unsupported));
+                case 'round':
+                    arity(expression.args, 2, 'round', unsupported);
+                    return round(operand(expression.args[0], resolve, unsupported), literalNumber(expression.args[1], unsupported));
+                case 'coalesce':
+                    arity(expression.args, 2, 'coalesce', unsupported);
+                    return coalesce(operand(expression.args[0], resolve, unsupported), fallback(expression.args[1], resolve, unsupported));
+                default:
+                    throw unsupported(`unsupported function "${String(expression.function)}"`);
+            }
+        default:
+            // A literal outside a `round` precision or `coalesce` fallback, or an
+            // aggregate that should have been carried as a named input. Either way
+            // the authoring API cannot express it, so rebuilding would be a guess.
+            throw unsupported(`a formula cannot contain a "${expression.kind}" expression here`);
+    }
+}
+function buildFormula(derivation, resolve, unsupported) {
+    const built = operand(derivation.expression, resolve, unsupported);
+    if (typeof built === 'string') {
+        // `spec.formula(...)` must return a `FormulaExpr`. A formula that is a bare
+        // reference names one of its inputs instead of combining them, which the
+        // authoring API cannot produce.
+        throw unsupported('a formula must combine its inputs rather than name one');
+    }
+    return built;
+}
+/**
+ * The formula function a derived metric spec expects.
+ *
+ * The returned function maps each declared alias through the caller-supplied
+ * `inputs` record, exactly as an authored formula does — both the plan builder
+ * and the query-builder path pass alias-to-alias, so the emitted column names
+ * are the ones the contract declared.
+ *
+ * The formula is built once here as well, so a malformed one is refused when
+ * the metric is rebuilt rather than on the first query that reaches it.
+ */
+export function rehydrateDerivedFormula(derivation, unsupported) {
+    buildFormula(derivation, name => name, unsupported);
+    return inputs => buildFormula(derivation, name => inputs[name] ?? name, unsupported);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.14.0",
+  "version": "0.16.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.12.0",
+    "@hypequery/protocol": "^0.13.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.0"
+    "@hypequery/protocol-conformance": "^0.11.1"
   },
   "repository": {
     "type": "git",