@hypequery/clickhouse 1.6.0 → 1.6.2

package/dist/core/types/select-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select-types.d.ts","sourceRoot":"","sources":["../../../src/core/types/select-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"select-types.d.ts","sourceRoot":"","sources":["../../../src/core/types/select-types.ts"],"names":[],"mappings":"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"}

package/dist/core/utils/streaming-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streaming-helpers.d.ts","sourceRoot":"","sources":["../../../src/core/utils/streaming-helpers.ts"],"names":[],"mappings":"AAoIA,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,cAAc,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAwCnH"}
+{"version":3,"file":"streaming-helpers.d.ts","sourceRoot":"","sources":["../../../src/core/utils/streaming-helpers.ts"],"names":[],"mappings":"AA8IA,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,cAAc,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAwCnH"}

package/dist/core/utils/streaming-helpers.js

@@ -47,6 +47,14 @@ async function normalizeChunk(chunk, flush, append) {
         append(chunk);
         return flush();
     }
+    if (chunk instanceof Uint8Array) {
+        append(Buffer.from(chunk));
+        return flush();
+    }
+    if (chunk instanceof ArrayBuffer) {
+        append(Buffer.from(chunk));
+        return flush();
+    }
     if (typeof chunk === 'string') {
         append(chunk);
         return flush();

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAa9C;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAavE"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,CAa9C;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAgBvE"}

package/dist/core/utils.js

@@ -16,6 +16,9 @@ export function escapeValue(value) {
     }
 }
 export function substituteParameters(sql, params) {
+    if (!params.length) {
+        return sql;
+    }
     const parts = sql.split('?');
     if (parts.length - 1 !== params.length) {
         throw new Error(`Mismatch between placeholders and parameters. Found ${parts.length - 1} placeholders but ${params.length} parameters.`);

package/dist/dataset/definition.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Dataset Definition Utilities
+ *
+ * Provides utilities for creating and managing dataset definitions:
+ * - Dataset validation
+ * - Dimension/metric normalization
+ * - Type inference helpers
+ */
+import type { DatasetDefinition, DatasetsMap, DimensionsMap, Dimension, DimensionDefinition, DimensionType } from './types.js';
+import { type SQLExpression } from './sql-tag.js';
+/**
+ * Validate a complete dataset definition
+ *
+ * @param name - Dataset name
+ * @param definition - Dataset definition
+ * @throws Error if validation fails
+ */
+export declare function validateDatasetDefinition(name: string, definition: DatasetDefinition): void;
+/**
+ * Validate all datasets in a datasets map
+ *
+ * @param datasets - Map of dataset definitions
+ * @throws Error if any dataset is invalid
+ */
+export declare function validateDatasets(datasets: DatasetsMap): void;
+/**
+ * Normalize a dimension definition to full DimensionDefinition object
+ *
+ * @param dimension - Dimension definition (simple or complex)
+ * @returns Normalized DimensionDefinition
+ */
+export declare function normalizeDimension(dimension: Dimension): DimensionDefinition;
+/**
+ * Normalize all dimensions in a dimensions map
+ *
+ * @param dimensions - Map of dimension definitions
+ * @returns Map of normalized dimension definitions
+ */
+export declare function normalizeDimensions(dimensions: DimensionsMap): Record<string, DimensionDefinition>;
+/**
+ * Infer the TypeScript type from a dimension definition
+ *
+ * @param dimension - Dimension definition
+ * @returns Inferred type name
+ */
+export declare function inferDimensionType(dimension: Dimension): DimensionType;
+/**
+ * Get the SQL string from a dimension definition
+ *
+ * @param dimension - Dimension definition
+ * @returns SQL string
+ */
+export declare function getDimensionSQL(dimension: Dimension): string;
+/**
+ * Get the SQL string from a metric definition
+ *
+ * @param metric - Metric definition
+ * @returns SQL string
+ */
+export declare function getMetricSQL(metric: {
+    sql: string | SQLExpression;
+}): string;
+/**
+ * Get a dataset definition by name
+ *
+ * @param datasets - Map of dataset definitions
+ * @param name - Dataset name
+ * @returns Dataset definition
+ * @throws Error if dataset not found
+ */
+export declare function getDataset(datasets: DatasetsMap, name: string): DatasetDefinition;
+/**
+ * List all dataset names
+ *
+ * @param datasets - Map of dataset definitions
+ * @returns Array of dataset names
+ */
+export declare function listDatasets(datasets: DatasetsMap): string[];
+/**
+ * Check if a dataset exists
+ *
+ * @param datasets - Map of dataset definitions
+ * @param name - Dataset name
+ * @returns True if dataset exists
+ */
+export declare function hasDataset(datasets: DatasetsMap, name: string): boolean;
+/**
+ * Get dimension names for a dataset
+ *
+ * @param dataset - Dataset definition
+ * @returns Array of dimension names
+ */
+export declare function getDimensionNames(dataset: DatasetDefinition): string[];
+/**
+ * Get metric names for a dataset
+ *
+ * @param dataset - Dataset definition
+ * @returns Array of metric names
+ */
+export declare function getMetricNames(dataset: DatasetDefinition): string[];
+/**
+ * Check if a dimension exists in a dataset
+ *
+ * @param dataset - Dataset definition
+ * @param dimensionName - Dimension name
+ * @returns True if dimension exists
+ */
+export declare function hasDimension(dataset: DatasetDefinition, dimensionName: string): boolean;
+/**
+ * Check if a metric exists in a dataset
+ *
+ * @param dataset - Dataset definition
+ * @param metricName - Metric name
+ * @returns True if metric exists
+ */
+export declare function hasMetric(dataset: DatasetDefinition, metricName: string): boolean;
+/**
+ * Get a dimension definition from a dataset
+ *
+ * @param dataset - Dataset definition
+ * @param dimensionName - Dimension name
+ * @returns Normalized dimension definition
+ * @throws Error if dimension not found
+ */
+export declare function getDimension(dataset: DatasetDefinition, dimensionName: string): DimensionDefinition;
+/**
+ * Get a metric definition from a dataset
+ *
+ * @param dataset - Dataset definition
+ * @param metricName - Metric name
+ * @returns Metric definition
+ * @throws Error if metric not found
+ */
+export declare function getMetric(dataset: DatasetDefinition, metricName: string): import("./types.js").MetricDefinition;
+//# sourceMappingURL=definition.d.ts.map

package/dist/dataset/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/dataset/definition.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,SAAS,EACT,mBAAmB,EACnB,aAAa,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAgC,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAUhF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,iBAAiB,GAC5B,IAAI,CA8EN;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAU5D;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,mBAAmB,CAqB5E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,aAAa,GACxB,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAQrC;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,aAAa,CAGtE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAG5D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IACnC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC;CAC7B,GAAG,MAAM,CAET;AAMD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,WAAW,EACrB,IAAI,EAAE,MAAM,GACX,iBAAiB,CAWnB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,EAAE,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAEtE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,EAAE,CAEnE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,iBAAiB,EAC1B,aAAa,EAAE,MAAM,GACpB,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,GACjB,OAAO,CAET;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,iBAAiB,EAC1B,aAAa,EAAE,MAAM,GACpB,mBAAmB,CASrB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,yCAUnB"}

package/dist/dataset/definition.js

@@ -0,0 +1,265 @@
+/**
+ * Dataset Definition Utilities
+ *
+ * Provides utilities for creating and managing dataset definitions:
+ * - Dataset validation
+ * - Dimension/metric normalization
+ * - Type inference helpers
+ */
+import { isSQLExpression, toSQLString } from './sql-tag.js';
+import { validateDimensionDefinition, validateMetricDefinition, } from './helpers.js';
+// =============================================================================
+// DATASET VALIDATION
+// =============================================================================
+/**
+ * Validate a complete dataset definition
+ *
+ * @param name - Dataset name
+ * @param definition - Dataset definition
+ * @throws Error if validation fails
+ */
+export function validateDatasetDefinition(name, definition) {
+    // Validate required fields
+    if (!definition.name) {
+        throw new Error(`Dataset '${name}' is missing 'name' property.`);
+    }
+    if (!definition.description) {
+        console.warn(`⚠️  Dataset '${name}' is missing 'description'. ` +
+            `Descriptions help AI agents understand your data.`);
+    }
+    if (!definition.table) {
+        throw new Error(`Dataset '${name}' is missing 'table' property.`);
+    }
+    // Validate dimensions
+    if (!definition.dimensions || Object.keys(definition.dimensions).length === 0) {
+        throw new Error(`Dataset '${name}' must have at least one dimension. ` +
+            `Dimensions define the grouping keys for your data.`);
+    }
+    for (const [dimName, dimDef] of Object.entries(definition.dimensions)) {
+        validateDimensionDefinition(dimName, dimDef);
+    }
+    // Validate metrics
+    if (!definition.metrics || Object.keys(definition.metrics).length === 0) {
+        throw new Error(`Dataset '${name}' must have at least one metric. ` +
+            `Metrics define the aggregations for your data.`);
+    }
+    for (const [metricName, metricDef] of Object.entries(definition.metrics)) {
+        validateMetricDefinition(metricName, metricDef);
+    }
+    // Validate tenant config
+    if (definition.tenant) {
+        if (!definition.tenant.column) {
+            throw new Error(`Dataset '${name}' tenant config is missing 'column' property.`);
+        }
+    }
+    // Validate limits
+    if (definition.limits) {
+        const limits = definition.limits;
+        if (limits.maxDimensions !== undefined && limits.maxDimensions < 1) {
+            throw new Error(`Dataset '${name}' limits.maxDimensions must be at least 1.`);
+        }
+        if (limits.maxMetrics !== undefined && limits.maxMetrics < 1) {
+            throw new Error(`Dataset '${name}' limits.maxMetrics must be at least 1.`);
+        }
+        if (limits.maxFilters !== undefined && limits.maxFilters < 0) {
+            throw new Error(`Dataset '${name}' limits.maxFilters must be non-negative.`);
+        }
+        if (limits.maxResultSize !== undefined && limits.maxResultSize < 1) {
+            throw new Error(`Dataset '${name}' limits.maxResultSize must be at least 1.`);
+        }
+    }
+}
+/**
+ * Validate all datasets in a datasets map
+ *
+ * @param datasets - Map of dataset definitions
+ * @throws Error if any dataset is invalid
+ */
+export function validateDatasets(datasets) {
+    if (!datasets || Object.keys(datasets).length === 0) {
+        throw new Error('No datasets defined. Please define at least one dataset.');
+    }
+    for (const [name, definition] of Object.entries(datasets)) {
+        validateDatasetDefinition(name, definition);
+    }
+}
+// =============================================================================
+// DIMENSION NORMALIZATION
+// =============================================================================
+/**
+ * Normalize a dimension definition to full DimensionDefinition object
+ *
+ * @param dimension - Dimension definition (simple or complex)
+ * @returns Normalized DimensionDefinition
+ */
+export function normalizeDimension(dimension) {
+    // Simple string column reference
+    if (typeof dimension === 'string') {
+        return {
+            sql: dimension,
+            type: 'string', // Default type for simple columns
+            description: '', // Empty description (should be filled by user)
+        };
+    }
+    // SQLExpression
+    if (isSQLExpression(dimension)) {
+        return {
+            sql: dimension,
+            type: 'string', // Default type for SQL expressions
+            description: '', // Empty description (should be filled by user)
+        };
+    }
+    // Already a full DimensionDefinition
+    return dimension;
+}
+/**
+ * Normalize all dimensions in a dimensions map
+ *
+ * @param dimensions - Map of dimension definitions
+ * @returns Map of normalized dimension definitions
+ */
+export function normalizeDimensions(dimensions) {
+    const normalized = {};
+    for (const [name, dimension] of Object.entries(dimensions)) {
+        normalized[name] = normalizeDimension(dimension);
+    }
+    return normalized;
+}
+// =============================================================================
+// TYPE INFERENCE HELPERS
+// =============================================================================
+/**
+ * Infer the TypeScript type from a dimension definition
+ *
+ * @param dimension - Dimension definition
+ * @returns Inferred type name
+ */
+export function inferDimensionType(dimension) {
+    const normalized = normalizeDimension(dimension);
+    return normalized.type;
+}
+/**
+ * Get the SQL string from a dimension definition
+ *
+ * @param dimension - Dimension definition
+ * @returns SQL string
+ */
+export function getDimensionSQL(dimension) {
+    const normalized = normalizeDimension(dimension);
+    return toSQLString(normalized.sql);
+}
+/**
+ * Get the SQL string from a metric definition
+ *
+ * @param metric - Metric definition
+ * @returns SQL string
+ */
+export function getMetricSQL(metric) {
+    return toSQLString(metric.sql);
+}
+// =============================================================================
+// DATASET UTILITIES
+// =============================================================================
+/**
+ * Get a dataset definition by name
+ *
+ * @param datasets - Map of dataset definitions
+ * @param name - Dataset name
+ * @returns Dataset definition
+ * @throws Error if dataset not found
+ */
+export function getDataset(datasets, name) {
+    const dataset = datasets[name];
+    if (!dataset) {
+        throw new Error(`Dataset '${name}' not found. ` +
+            `Available datasets: ${Object.keys(datasets).join(', ')}`);
+    }
+    return dataset;
+}
+/**
+ * List all dataset names
+ *
+ * @param datasets - Map of dataset definitions
+ * @returns Array of dataset names
+ */
+export function listDatasets(datasets) {
+    return Object.keys(datasets);
+}
+/**
+ * Check if a dataset exists
+ *
+ * @param datasets - Map of dataset definitions
+ * @param name - Dataset name
+ * @returns True if dataset exists
+ */
+export function hasDataset(datasets, name) {
+    return name in datasets;
+}
+/**
+ * Get dimension names for a dataset
+ *
+ * @param dataset - Dataset definition
+ * @returns Array of dimension names
+ */
+export function getDimensionNames(dataset) {
+    return Object.keys(dataset.dimensions);
+}
+/**
+ * Get metric names for a dataset
+ *
+ * @param dataset - Dataset definition
+ * @returns Array of metric names
+ */
+export function getMetricNames(dataset) {
+    return Object.keys(dataset.metrics);
+}
+/**
+ * Check if a dimension exists in a dataset
+ *
+ * @param dataset - Dataset definition
+ * @param dimensionName - Dimension name
+ * @returns True if dimension exists
+ */
+export function hasDimension(dataset, dimensionName) {
+    return dimensionName in dataset.dimensions;
+}
+/**
+ * Check if a metric exists in a dataset
+ *
+ * @param dataset - Dataset definition
+ * @param metricName - Metric name
+ * @returns True if metric exists
+ */
+export function hasMetric(dataset, metricName) {
+    return metricName in dataset.metrics;
+}
+/**
+ * Get a dimension definition from a dataset
+ *
+ * @param dataset - Dataset definition
+ * @param dimensionName - Dimension name
+ * @returns Normalized dimension definition
+ * @throws Error if dimension not found
+ */
+export function getDimension(dataset, dimensionName) {
+    if (!hasDimension(dataset, dimensionName)) {
+        throw new Error(`Dimension '${dimensionName}' not found in dataset '${dataset.name}'. ` +
+            `Available dimensions: ${getDimensionNames(dataset).join(', ')}`);
+    }
+    return normalizeDimension(dataset.dimensions[dimensionName]);
+}
+/**
+ * Get a metric definition from a dataset
+ *
+ * @param dataset - Dataset definition
+ * @param metricName - Metric name
+ * @returns Metric definition
+ * @throws Error if metric not found
+ */
+export function getMetric(dataset, metricName) {
+    if (!hasMetric(dataset, metricName)) {
+        throw new Error(`Metric '${metricName}' not found in dataset '${dataset.name}'. ` +
+            `Available metrics: ${getMetricNames(dataset).join(', ')}`);
+    }
+    return dataset.metrics[metricName];
+}

package/dist/dataset/helpers.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Dataset Helper Functions
+ *
+ * Provides declarative helper functions for defining dimensions and metrics:
+ * - dimension.string(), dimension.number(), dimension.date(), dimension.boolean()
+ * - metric.count(), metric.sum(), metric.avg(), metric.min(), metric.max(), metric.countDistinct(), metric.custom()
+ */
+import type { DimensionDefinition, MetricDefinition, MetricFormat } from './types.js';
+import { type SQLExpression } from './sql-tag.js';
+/**
+ * Options for dimension helpers
+ */
+export interface DimensionOptions {
+    /** Human-readable description (for AI agents) */
+    description: string;
+    /** Example values (for AI context) */
+    examples?: string[];
+    /** Join name (if dimension requires a join) */
+    join?: string;
+}
+/**
+ * Dimension helper namespace
+ *
+ * @example
+ * ```typescript
+ * dimensions: {
+ *   region: dimension.string('region', {
+ *     description: 'Geographic region',
+ *     examples: ['US', 'EU', 'APAC']
+ *   }),
+ *   orderDate: dimension.date(sql`DATE(created_at)`, {
+ *     description: 'Order date'
+ *   }),
+ *   amount: dimension.number('amount', {
+ *     description: 'Order amount'
+ *   })
+ * }
+ * ```
+ */
+export declare const dimension: {
+    /**
+     * Create a string dimension
+     */
+    string: (columnOrExpression: string | SQLExpression, options: DimensionOptions) => DimensionDefinition;
+    /**
+     * Create a number dimension
+     */
+    number: (columnOrExpression: string | SQLExpression, options: DimensionOptions) => DimensionDefinition;
+    /**
+     * Create a date dimension
+     */
+    date: (columnOrExpression: string | SQLExpression, options: DimensionOptions) => DimensionDefinition;
+    /**
+     * Create a boolean dimension
+     */
+    boolean: (columnOrExpression: string | SQLExpression, options: DimensionOptions) => DimensionDefinition;
+};
+/**
+ * Options for metric helpers
+ */
+export interface MetricOptions {
+    /** Human-readable description (for AI agents) */
+    description: string;
+    /** Format hint for display */
+    format?: MetricFormat;
+    /** Join name (if metric requires a join) */
+    join?: string;
+    /** Allow fan-out (for oneToMany joins) - advanced use only */
+    allowFanout?: boolean;
+}
+/**
+ * Metric helper namespace
+ *
+ * @example
+ * ```typescript
+ * metrics: {
+ *   revenue: metric.sum('amount', {
+ *     description: 'Total revenue',
+ *     format: 'currency'
+ *   }),
+ *   orderCount: metric.count({
+ *     description: 'Total number of orders'
+ *   }),
+ *   avgOrderValue: metric.avg('total_amount', {
+ *     description: 'Average order value',
+ *     format: 'currency'
+ *   }),
+ *   revenuePerCustomer: metric.custom(
+ *     sql`sum(total_amount) / count(DISTINCT customer_id)`,
+ *     {
+ *       description: 'Average revenue per customer',
+ *       format: 'currency'
+ *     }
+ *   )
+ * }
+ * ```
+ */
+export declare const metric: {
+    /**
+     * Create a COUNT(*) metric
+     */
+    count: (options: MetricOptions) => MetricDefinition;
+    /**
+     * Create a SUM() metric
+     */
+    sum: (columnOrExpression: string | SQLExpression, options: MetricOptions) => MetricDefinition;
+    /**
+     * Create an AVG() metric
+     */
+    avg: (columnOrExpression: string | SQLExpression, options: MetricOptions) => MetricDefinition;
+    /**
+     * Create a MIN() metric
+     */
+    min: (columnOrExpression: string | SQLExpression, options: MetricOptions) => MetricDefinition;
+    /**
+     * Create a MAX() metric
+     */
+    max: (columnOrExpression: string | SQLExpression, options: MetricOptions) => MetricDefinition;
+    /**
+     * Create a COUNT(DISTINCT) metric
+     */
+    countDistinct: (columnOrExpression: string | SQLExpression, options: MetricOptions) => MetricDefinition;
+    /**
+     * Create a custom metric with a SQL expression
+     */
+    custom: (columnOrExpression: string | SQLExpression, options: MetricOptions) => MetricDefinition;
+};
+/**
+ * Validate that a dimension definition has required metadata
+ */
+export declare function validateDimensionDefinition(name: string, definition: unknown): void;
+/**
+ * Validate that a metric definition has required metadata
+ */
+export declare function validateMetricDefinition(name: string, definition: unknown): void;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/dataset/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/dataset/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,mBAAmB,EAEnB,gBAAgB,EAEhB,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAO,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAMvD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAoBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,SAAS;IACpB;;OAEG;iCAnCmB,MAAM,GAAG,aAAa,WACjC,gBAAgB,KACxB,mBAAmB;IAoCtB;;OAEG;iCAxCmB,MAAM,GAAG,aAAa,WACjC,gBAAgB,KACxB,mBAAmB;IAyCtB;;OAEG;+BA7CmB,MAAM,GAAG,aAAa,WACjC,gBAAgB,KACxB,mBAAmB;IA8CtB;;OAEG;kCAlDmB,MAAM,GAAG,aAAa,WACjC,gBAAgB,KACxB,mBAAmB;CAkDvB,CAAC;AAMF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,MAAM;IACjB;;OAEG;qBACc,aAAa,KAAG,gBAAgB;IAWjD;;OAEG;8BA1DmB,MAAM,GAAG,aAAa,WACjC,aAAa,KACrB,gBAAgB;IA2DnB;;OAEG;8BA/DmB,MAAM,GAAG,aAAa,WACjC,aAAa,KACrB,gBAAgB;IAgEnB;;OAEG;8BApEmB,MAAM,GAAG,aAAa,WACjC,aAAa,KACrB,gBAAgB;IAqEnB;;OAEG;8BAzEmB,MAAM,GAAG,aAAa,WACjC,aAAa,KACrB,gBAAgB;IA0EnB;;OAEG;wCA9EmB,MAAM,GAAG,aAAa,WACjC,aAAa,KACrB,gBAAgB;IA+EnB;;OAEG;iCAnFmB,MAAM,GAAG,aAAa,WACjC,aAAa,KACrB,gBAAgB;CAmFpB,CAAC;AAMF;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,OAAO,GAClB,IAAI,CA8BN;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,OAAO,GAClB,IAAI,CA8BN"}