@hypequery/datasets 0.1.0 → 0.2.1

package/dist/utils/derived-cte-validation.d.ts

@@ -0,0 +1,3 @@
+export declare function extractGroupByExpressions(sql: string): string[];
+export declare function validateDerivedCteGrouping(sql: string, aggregateAliases: string[], intendedGroupBy: string[]): string[];
+//# sourceMappingURL=derived-cte-validation.d.ts.map

package/dist/utils/derived-cte-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-cte-validation.d.ts","sourceRoot":"","sources":["../../src/utils/derived-cte-validation.ts"],"names":[],"mappings":"AAAA,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/D;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,EAAE,EAC1B,eAAe,EAAE,MAAM,EAAE,GACxB,MAAM,EAAE,CAgCV"}

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

@@ -0,0 +1,32 @@
+export function extractGroupByExpressions(sql) {
+    const match = sql.match(/\bGROUP BY\b\s+(.+?)(?:\bHAVING\b|\bORDER BY\b|\bLIMIT\b|\bOFFSET\b|$)/is);
+    if (!match) {
+        return [];
+    }
+    return match[1]
+        .split(',')
+        .map(part => part.trim())
+        .filter(Boolean);
+}
+export function validateDerivedCteGrouping(sql, aggregateAliases, intendedGroupBy) {
+    const errors = [];
+    const actualGroupBy = extractGroupByExpressions(sql);
+    if (intendedGroupBy.length === 0 && actualGroupBy.length > 0) {
+        errors.push('Derived metric planner emitted GROUP BY for an ungrouped query.');
+    }
+    const duplicates = actualGroupBy.filter((expression, index) => actualGroupBy.indexOf(expression) !== index);
+    if (duplicates.length > 0) {
+        errors.push(`Derived metric planner emitted duplicate GROUP BY expressions: ${Array.from(new Set(duplicates)).join(', ')}`);
+    }
+    const aggregateAliasSet = new Set(aggregateAliases);
+    const aggregateAliasesInGroupBy = actualGroupBy.filter(expression => aggregateAliasSet.has(expression));
+    if (aggregateAliasesInGroupBy.length > 0) {
+        errors.push(`Derived metric planner emitted aggregate aliases in GROUP BY: ${Array.from(new Set(aggregateAliasesInGroupBy)).join(', ')}`);
+    }
+    const intendedGroupBySet = new Set(intendedGroupBy);
+    const unexpectedGroupBy = actualGroupBy.filter(expression => !intendedGroupBySet.has(expression));
+    if (unexpectedGroupBy.length > 0) {
+        errors.push(`Derived metric planner emitted unexpected GROUP BY expressions: ${Array.from(new Set(unexpectedGroupBy)).join(', ')}`);
+    }
+    return errors;
+}

package/dist/utils/filtered-aggregation-sql.d.ts

@@ -0,0 +1,5 @@
+import type { AggregationSpec, AnyDatasetInstance } from '../types.js';
+type DatasetShape = AnyDatasetInstance;
+export declare function applyFilteredAggregationExpression(ds: DatasetShape, spec: AggregationSpec, fieldOrExpr: string): string;
+export {};
+//# sourceMappingURL=filtered-aggregation-sql.d.ts.map

package/dist/utils/filtered-aggregation-sql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filtered-aggregation-sql.d.ts","sourceRoot":"","sources":["../../src/utils/filtered-aggregation-sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAgB,MAAM,aAAa,CAAC;AAGrF,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAiEvC,wBAAgB,kCAAkC,CAChD,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,eAAe,EACrB,WAAW,EAAE,MAAM,GAClB,MAAM,CAsBR"}

package/dist/utils/filtered-aggregation-sql.js

@@ -0,0 +1,73 @@
+import { resolveFilterField } from '../query-planner.js';
+function renderMeasureFilterLiteral(value) {
+    if (value === null) {
+        return 'NULL';
+    }
+    if (typeof value === 'string') {
+        return `'${value.replace(/'/g, "''")}'`;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error(`Invalid non-finite numeric literal in measure filter: ${value}`);
+        }
+        return String(value);
+    }
+    if (typeof value === 'boolean') {
+        return value ? '1' : '0';
+    }
+    throw new Error(`Unsupported literal type in measure filter: ${typeof value}`);
+}
+function renderMeasureFilterCondition(ds, filter) {
+    const field = resolveFilterField(ds, filter.field);
+    switch (filter.operator) {
+        case 'eq':
+            return `${field} = ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'neq':
+            return `${field} != ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'gt':
+            return `${field} > ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'gte':
+            return `${field} >= ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'lt':
+            return `${field} < ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'lte':
+            return `${field} <= ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'like':
+            return `${field} LIKE ${renderMeasureFilterLiteral(filter.value)}`;
+        case 'in':
+        case 'notIn': {
+            if (!Array.isArray(filter.value) || filter.value.length === 0) {
+                throw new Error(`"${filter.operator}" measure filters require a non-empty array.`);
+            }
+            const values = filter.value.map(renderMeasureFilterLiteral).join(', ');
+            return `${field} ${filter.operator === 'in' ? 'IN' : 'NOT IN'} (${values})`;
+        }
+        case 'between': {
+            if (!Array.isArray(filter.value) || filter.value.length !== 2) {
+                throw new Error('"between" measure filters require a two-item array.');
+            }
+            return `${field} BETWEEN ${renderMeasureFilterLiteral(filter.value[0])} AND ${renderMeasureFilterLiteral(filter.value[1])}`;
+        }
+    }
+}
+export function applyFilteredAggregationExpression(ds, spec, fieldOrExpr) {
+    if (!spec.filters?.length) {
+        return fieldOrExpr;
+    }
+    const combinedCondition = spec.filters
+        .map(filter => renderMeasureFilterCondition(ds, filter))
+        .map(condition => `(${condition})`)
+        .join(' AND ');
+    switch (spec.aggregation) {
+        case 'sum':
+            return `if(${combinedCondition}, ${fieldOrExpr}, 0)`;
+        case 'count':
+        case 'countDistinct':
+        case 'avg':
+        case 'min':
+        case 'max':
+            return `if(${combinedCondition}, ${fieldOrExpr}, NULL)`;
+        default:
+            return fieldOrExpr;
+    }
+}

package/dist/utils/metric-handle.d.ts

@@ -0,0 +1,11 @@
+import type { AnyDatasetInstance, ExecutionContext, GrainedMetricRef, MetricFilter, MetricQuery, MetricRef, TimeGrain } from '../types.js';
+type DatasetShape = AnyDatasetInstance;
+export type MetricHandle = MetricRef | GrainedMetricRef;
+export declare function isMetricHandle(value: unknown): value is MetricHandle;
+export declare function assertMetricHandle(value: unknown): asserts value is MetricHandle;
+export declare function getMetricRef(metric: MetricHandle): MetricRef;
+export declare function getMetricGrain(metric: MetricHandle, query: MetricQuery): TimeGrain | undefined;
+export declare function getTenantRuntimeColumn(ds: DatasetShape, context?: ExecutionContext): string | undefined;
+export declare function isTenantScopedFilter(ds: DatasetShape, filter: MetricFilter, context?: ExecutionContext): boolean;
+export {};
+//# sourceMappingURL=metric-handle.d.ts.map

package/dist/utils/metric-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-handle.d.ts","sourceRoot":"","sources":["../../src/utils/metric-handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACV,MAAM,aAAa,CAAC;AAGrB,KAAK,YAAY,GAAG,kBAAkB,CAAC;AAMvC,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,gBAAgB,CAAC;AAExD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAKpE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAOhF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAE5D;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAE9F;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,YAAY,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAMpB;AAED,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAOT"}

package/dist/utils/metric-handle.js

@@ -0,0 +1,36 @@
+import { resolveDimensionExpression, resolveFilterField, resolveTenantFilterColumn } from '../query-planner.js';
+import { getRuntimeTenantPredicate } from './tenant-runtime.js';
+function isMetricHandleType(value) {
+    return value === 'metric_ref' || value === 'grained_metric_ref';
+}
+export function isMetricHandle(value) {
+    return typeof value === 'object'
+        && value !== null
+        && '__type' in value
+        && isMetricHandleType(value.__type);
+}
+export function assertMetricHandle(value) {
+    if (!isMetricHandle(value)) {
+        throw new Error('Metric queries only support MetricRef and GrainedMetricRef. ' +
+            'dataset.query(...) is not part of the public execution API.');
+    }
+}
+export function getMetricRef(metric) {
+    return metric.__type === 'grained_metric_ref' ? metric.metric : metric;
+}
+export function getMetricGrain(metric, query) {
+    return metric.__type === 'grained_metric_ref' ? metric.grain : query.by ?? undefined;
+}
+export function getTenantRuntimeColumn(ds, context) {
+    if (!getRuntimeTenantPredicate(context)) {
+        return undefined;
+    }
+    return resolveTenantFilterColumn(ds, context);
+}
+export function isTenantScopedFilter(ds, filter, context) {
+    const tenantColumn = getTenantRuntimeColumn(ds, context);
+    if (!tenantColumn) {
+        return false;
+    }
+    return resolveFilterField(ds, filter.field) === resolveDimensionExpression(ds, tenantColumn);
+}

package/dist/utils/pagination.d.ts

@@ -0,0 +1,17 @@
+import type { MetricResultMeta } from '../types.js';
+export type PaginationMeta = NonNullable<MetricResultMeta['pagination']>;
+/**
+ * When a limit is set, request one extra row so the executor can report
+ * `hasMore` without issuing a separate COUNT query. Returns `undefined` when
+ * no limit is set (unbounded query — there is no "next page").
+ */
+export declare function overfetchLimit(limit?: number): number | undefined;
+/**
+ * Trim an over-fetched result set back to `limit` rows and derive pagination
+ * metadata. The extra row (if present) signals that another page exists.
+ */
+export declare function applyPagination<T>(rows: T[], limit?: number, offset?: number): {
+    data: T[];
+    pagination?: PaginationMeta;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/utils/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/utils/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC,CAAC;AAEzE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,IAAI,EAAE,CAAC,EAAE,EACT,KAAK,CAAC,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,cAAc,CAAA;CAAE,CAU5C"}

package/dist/utils/pagination.js

@@ -0,0 +1,23 @@
+/**
+ * When a limit is set, request one extra row so the executor can report
+ * `hasMore` without issuing a separate COUNT query. Returns `undefined` when
+ * no limit is set (unbounded query — there is no "next page").
+ */
+export function overfetchLimit(limit) {
+    return limit != null ? limit + 1 : undefined;
+}
+/**
+ * Trim an over-fetched result set back to `limit` rows and derive pagination
+ * metadata. The extra row (if present) signals that another page exists.
+ */
+export function applyPagination(rows, limit, offset) {
+    if (limit == null) {
+        return { data: rows };
+    }
+    const hasMore = rows.length > limit;
+    const data = hasMore ? rows.slice(0, limit) : rows;
+    return {
+        data,
+        pagination: { limit, offset: offset ?? 0, hasMore },
+    };
+}

package/dist/utils/tenant-runtime.d.ts

@@ -0,0 +1,14 @@
+import type { AnyDatasetInstance, ExecutionContext } from '../types.js';
+export type TenantPredicate = {
+    operator: 'eq';
+    value: string;
+} | {
+    operator: 'in';
+    value: string[];
+};
+export declare function getRuntimeTenantPredicate(context?: ExecutionContext): TenantPredicate | undefined;
+export declare function getRuntimeTenantId(context?: ExecutionContext): string | undefined;
+export declare function isCrossTenantRuntime(context?: ExecutionContext): boolean;
+export declare function hasTenantRuntime(context?: ExecutionContext): boolean;
+export declare function validateTenantRuntime(ds: AnyDatasetInstance, context?: ExecutionContext): string | undefined;
+//# sourceMappingURL=tenant-runtime.d.ts.map

package/dist/utils/tenant-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-runtime.d.ts","sourceRoot":"","sources":["../../src/utils/tenant-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAExC,wBAAgB,yBAAyB,CACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,GAAG,SAAS,CAe7B;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAGjF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAGxE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAEpE;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,kBAAkB,EACtB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,GAAG,SAAS,CAQpB"}

package/dist/utils/tenant-runtime.js

@@ -0,0 +1,36 @@
+export function getRuntimeTenantPredicate(context) {
+    const tenant = context?.runtime?.tenant;
+    if (!tenant) {
+        return undefined;
+    }
+    if (typeof tenant === 'string') {
+        return { operator: 'eq', value: tenant };
+    }
+    if ('id' in tenant) {
+        return { operator: 'eq', value: tenant.id };
+    }
+    if ('in' in tenant && tenant.in.length > 0) {
+        return { operator: 'in', value: tenant.in };
+    }
+    return undefined;
+}
+export function getRuntimeTenantId(context) {
+    const predicate = getRuntimeTenantPredicate(context);
+    return predicate?.operator === 'eq' ? predicate.value : undefined;
+}
+export function isCrossTenantRuntime(context) {
+    const tenant = context?.runtime?.tenant;
+    return !!tenant && typeof tenant === 'object' && 'scope' in tenant && tenant.scope === 'all';
+}
+export function hasTenantRuntime(context) {
+    return !!getRuntimeTenantPredicate(context) || isCrossTenantRuntime(context);
+}
+export function validateTenantRuntime(ds, context) {
+    if (!ds.tenantKey) {
+        return undefined;
+    }
+    if (!hasTenantRuntime(context)) {
+        return `Dataset "${ds.name}" requires runtime tenant scoping.`;
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/datasets",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Semantic layer for defining datasets, metrics, and semantic queries",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,18 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js",
+      "require": "./dist/internal.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "internal": [
+        "./dist/internal.d.ts"
+      ]
     }
   },
   "license": "Apache-2.0",
@@ -41,7 +53,7 @@
     "dev": "tsc --watch",
     "test": "npm run test:types && npm run test:unit",
     "test:unit": "vitest run",
-    "test:integration": "vitest run",
+    "test:integration": "node scripts/run-integration-tests.js",
     "test:types": "tsc --project tsconfig.type-tests.json",
     "test:watch": "vitest watch",
     "test:coverage": "vitest run --coverage"