@ahoo-wang/wow-client 9.2.0-rc.0

package/dist/dsl/aggregation/builders.d.cts

@@ -0,0 +1,309 @@
+import { ElementFilterExpression, ExpressionFilter } from '../filter/index.cjs';
+import { DerivedExpressionDsl } from './derived.cjs';
+import { DateDiffUnit, AggregationElement, AggregationExpression, DateDiffAggregationExpression, AggregationMetricOptions, AggregationQuery, AnyAggregationMetric, EdgeAggregationMetric, EdgeAggregationOptions, BinaryAggregationExpression, ConstantAggregationExpression, CountAggregationMetric, DateHistogramAggregationGroup, DateHistogramAggregationOptions, DatePartAggregationGroup, DatePartAggregationOptions, DerivedAggregationMetric, DerivedExpression, DistinctCountAggregationMetric, FieldAggregationExpression, HistogramAggregationGroup, HistogramAggregationOptions, NumericAggregationMetric, PercentileAggregationMetric, PercentileAggregationOptions, TermsAggregationGroup, TermsAggregationOptions } from './types.cjs';
+/**
+ * Builders of an `AggregationQuery`: its elements, groups, metrics and the
+ * arithmetic expressions metrics compute over. Each builder checks its own
+ * part and throws a `TypeError` naming what is wrong; {@link aggregation.query}
+ * checks the parts against each other.
+ *
+ * Every group and metric takes its target first, its alias second, and any
+ * further options as a trailing object.
+ */
+export declare const aggregation: {
+    /**
+     * Aggregates over the elements of an array field instead of the root
+     * documents. `{ path, filter? }`.
+     *
+     * @param path - The array field, a query field path.
+     * @param predicate - Keeps only the elements that match; may not contain
+     *   root filters (id, owner, tenant, space, deletion) or any search, even
+     *   one that names its fields. An `EXPRESSION` filter is allowed.
+     * @throws TypeError when `path` is not a valid field path or `predicate`
+     *   contains a root filter.
+     * @example
+     * ```typescript
+     * aggregation.element('items', filter.gt('quantity', 0));
+     * ```
+     */
+    element(path: string, predicate?: ElementFilterExpression | ExpressionFilter): AggregationElement;
+    /**
+     * The value of a field, as an operand. `{ type: 'FIELD', field }`.
+     *
+     * @throws TypeError when `field` is not a valid field path.
+     * @example
+     * ```typescript
+     * aggregation.sum(aggregation.field('state.amount'), 'amount');
+     * ```
+     */
+    field<FIELDS extends string>(field: FIELDS): FieldAggregationExpression<FIELDS>;
+    /**
+     * A number, as an operand. `{ type: 'CONSTANT', value }`.
+     *
+     * @throws TypeError when `value` is not finite.
+     * @example
+     * ```typescript
+     * aggregation.multiply(aggregation.field('price'), aggregation.constant(100));
+     * ```
+     */
+    constant(value: number): ConstantAggregationExpression;
+    /**
+     * The time from the instant in `from` to the instant in `to`, `to − from`,
+     * in `unit`, as a signed decimal: negative when `to` is earlier, and no
+     * value when either instant is absent. A `DAY` is exactly 24 hours.
+     * `{ type: 'DATE_DIFF', from, to, unit }`. Both fields must be
+     * single-valued time fields, those whose `aggregate.groups` list
+     * `DATE_HISTOGRAM` in the descriptor, and `unit` one of its
+     * `analysis.dateDiffUnits`. Wow 9.2 and later.
+     *
+     * @throws TypeError when `from` or `to` is not a valid field path, or
+     *   `unit` is not a {@link DateDiffUnit}.
+     * @example
+     * ```typescript
+     * // Hours from payment to shipping, averaged per warehouse.
+     * aggregation.avg(
+     *   aggregation.dateDiff('state.paidAt', 'state.shippedAt', DateDiffUnit.HOUR),
+     *   'hoursToShip',
+     * );
+     * ```
+     */
+    dateDiff<FIELDS extends string>(from: FIELDS, to: FIELDS, unit: DateDiffUnit): DateDiffAggregationExpression<FIELDS>;
+    /** `left + right`. `{ type: 'BINARY', operator: 'ADD', left, right }`. */
+    add: <FIELDS extends string>(left: AggregationExpression<FIELDS>, right: AggregationExpression<FIELDS>) => BinaryAggregationExpression<FIELDS>;
+    /** `left - right`. `{ type: 'BINARY', operator: 'SUBTRACT', left, right }`. */
+    subtract: <FIELDS extends string>(left: AggregationExpression<FIELDS>, right: AggregationExpression<FIELDS>) => BinaryAggregationExpression<FIELDS>;
+    /** `left * right`. `{ type: 'BINARY', operator: 'MULTIPLY', left, right }`. */
+    multiply: <FIELDS extends string>(left: AggregationExpression<FIELDS>, right: AggregationExpression<FIELDS>) => BinaryAggregationExpression<FIELDS>;
+    /** `left / right`. `{ type: 'BINARY', operator: 'DIVIDE', left, right }`. */
+    divide: <FIELDS extends string>(left: AggregationExpression<FIELDS>, right: AggregationExpression<FIELDS>) => BinaryAggregationExpression<FIELDS>;
+    /**
+     * Groups by each distinct value of a field, or of a computed expression.
+     * `{ type: 'TERMS', field, alias, missingKey? }`, or
+     * `{ type: 'TERMS', expression, alias }`.
+     *
+     * @param input - The field to group by, or an expression in its place
+     *   (Wow 9.2 and later, an expensive computation).
+     * @param alias - The name of the group column in the result rows.
+     * @param options.missingKey - The key of the rows without a value; only
+     *   with a field.
+     * @throws TypeError when `input` or `alias` is invalid, `missingKey` is
+     *   blank, or `missingKey` is given with an expression.
+     * @example
+     * ```typescript
+     * aggregation.terms('state.status', 'status', { missingKey: 'NONE' });
+     * aggregation.terms(
+     *   aggregation.dateDiff('state.paidAt', 'state.shippedAt', DateDiffUnit.DAY),
+     *   'daysToShip',
+     * );
+     * ```
+     */
+    terms<FIELDS extends string>(input: FIELDS | AggregationExpression<FIELDS>, alias: string, { missingKey }?: TermsAggregationOptions): TermsAggregationGroup<FIELDS>;
+    /**
+     * Groups a number field, or a computed expression, into buckets of equal
+     * width. `{ type: 'HISTOGRAM', field | expression, interval, alias }`.
+     *
+     * @param input - The number field to bucket, or an expression in its
+     *   place (Wow 9.2 and later, an expensive computation).
+     * @param alias - The name of the bucket column in the result rows.
+     * @param options.interval - The bucket width.
+     * @throws TypeError when `interval` is not finite and greater than 0, or
+     *   `field` or `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.histogram('state.amount', 'amountBand', { interval: 100 });
+     * ```
+     */
+    histogram<FIELDS extends string>(input: FIELDS | AggregationExpression<FIELDS>, alias: string, { interval }: HistogramAggregationOptions): HistogramAggregationGroup<FIELDS>;
+    /**
+     * Groups a time field into calendar buckets.
+     * `{ type: 'DATE_HISTOGRAM', field, unit, alias, timeZone, dense? }`.
+     *
+     * @param field - The time field (epoch milliseconds) to bucket.
+     * @param alias - The name of the bucket column in the result rows.
+     * @param options.unit - The calendar unit of a bucket.
+     * @param options.timeZone - The zone buckets are cut in. Defaults to `UTC`.
+     * @param options.dense - Whether the empty buckets of the range are filled
+     *   in.
+     * @throws TypeError when `unit` is not an `AggregationDateUnit`,
+     *   `timeZone` is blank, `dense` is not a boolean, or `field` or `alias` is
+     *   invalid.
+     * @example
+     * ```typescript
+     * aggregation.dateHistogram('createTime', 'day', {
+     *   unit: AggregationDateUnit.DAY,
+     *   timeZone: 'Asia/Shanghai',
+     * });
+     * ```
+     */
+    dateHistogram<FIELDS extends string>(field: FIELDS, alias: string, { unit, timeZone, dense }: DateHistogramAggregationOptions): DateHistogramAggregationGroup<FIELDS>;
+    /**
+     * Groups a time field by one calendar part of each instant, such as the
+     * weekday or the hour, so records from different days share a bucket.
+     * `{ type: 'DATE_PART', field, part, alias, timeZone, dense? }`.
+     *
+     * The group's keys in the result rows are integers: `DAY_OF_WEEK` is the
+     * ISO weekday, 1 (Monday) to 7 (Sunday); `DAY_OF_MONTH` 1 to 31;
+     * `HOUR_OF_DAY` 0 to 23 on the wall clock of `timeZone`; `MONTH_OF_YEAR`
+     * 1 to 12. With `dense`, every key of that domain comes back, those
+     * without records carrying each metric's empty value; `dense` needs the
+     * group to be the query's only one. Wow 9.2 and later.
+     *
+     * @param field - The time field (epoch milliseconds) to read the part of.
+     * @param alias - The name of the part column in the result rows.
+     * @param options.part - The calendar part to group by.
+     * @param options.timeZone - The zone the part is read in. Defaults to
+     *   `UTC`.
+     * @param options.dense - Whether every key of the part's domain is
+     *   returned.
+     * @throws TypeError when `part` is not an `AggregationDatePart`,
+     *   `timeZone` is blank, `dense` is not a boolean, or `field` or `alias` is
+     *   invalid.
+     * @example
+     * ```typescript
+     * aggregation.datePart('createTime', 'weekday', {
+     *   part: AggregationDatePart.DAY_OF_WEEK,
+     *   timeZone: 'Asia/Shanghai',
+     * });
+     * ```
+     */
+    datePart<FIELDS extends string>(field: FIELDS, alias: string, { part, timeZone, dense }: DatePartAggregationOptions): DatePartAggregationGroup<FIELDS>;
+    /**
+     * Any one value of a field within each group, of any type.
+     * `{ type: 'ANY', field, alias, filter? }`.
+     *
+     * @throws TypeError when `field` or `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.any('state.customerName', 'customer');
+     * ```
+     */
+    any<FIELDS extends string>(field: FIELDS, alias: string, { filter: predicate }?: AggregationMetricOptions<FIELDS>): AnyAggregationMetric<FIELDS>;
+    /**
+     * The value of `field` on each group's earliest record by `orderBy`.
+     * `{ type: 'FIRST', field, alias, orderBy?, filter? }`.
+     *
+     * The value comes back in the field's own type, or `null` when no record
+     * of the group has both a value and an `orderBy` position. Without
+     * `orderBy` the server orders by the model's event time, which the
+     * descriptor names as `analysis.firstLastOrderBy`. Neither a derived
+     * metric nor `having` may refer to it. Wow 9.2 and later.
+     *
+     * @throws TypeError when `field`, `orderBy` or `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.first('state.price', 'open', { orderBy: 'createTime' });
+     * ```
+     */
+    first<FIELDS extends string>(field: FIELDS, alias: string, options?: EdgeAggregationOptions<FIELDS>): EdgeAggregationMetric<FIELDS>;
+    /**
+     * The value of `field` on each group's latest record by `orderBy`.
+     * `{ type: 'LAST', field, alias, orderBy?, filter? }`. As
+     * {@link aggregation.first}, from the other end.
+     *
+     * @throws TypeError when `field`, `orderBy` or `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.last('state.price', 'close', { orderBy: 'createTime' });
+     * ```
+     */
+    last<FIELDS extends string>(field: FIELDS, alias: string, options?: EdgeAggregationOptions<FIELDS>): EdgeAggregationMetric<FIELDS>;
+    /**
+     * The number of rows in each group. `{ type: 'COUNT', alias, filter? }`.
+     *
+     * @param alias - The name of the metric column in the result rows.
+     * @param options.filter - Counts only the rows that match.
+     * @throws TypeError when `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.count('paid', { filter: filter.eq('state.status', 'PAID') });
+     * ```
+     */
+    count<FIELDS extends string = string>(alias: string, { filter: predicate }?: AggregationMetricOptions<FIELDS>): CountAggregationMetric<FIELDS>;
+    /**
+     * The sum of an expression. `{ type: 'NUMERIC', function: 'SUM',
+     * expression, alias, filter? }`.
+     *
+     * @example
+     * ```typescript
+     * aggregation.sum(aggregation.field('state.amount'), 'revenue');
+     * ```
+     */
+    sum: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /** The average of an expression; see {@link aggregation.sum}. */
+    avg: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /** The least value of an expression; see {@link aggregation.sum}. */
+    min: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /** The greatest value of an expression; see {@link aggregation.sum}. */
+    max: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /** The standard deviation of an expression; see {@link aggregation.sum}. */
+    stddev: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /** The variance of an expression; see {@link aggregation.sum}. */
+    variance: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /**
+     * The number of distinct values of an expression.
+     * `{ type: 'DISTINCT_COUNT', expression, alias, filter? }`.
+     *
+     * @example
+     * ```typescript
+     * aggregation.distinctCount(aggregation.field('ownerId'), 'customers');
+     * ```
+     */
+    distinctCount<FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, { filter: predicate }?: AggregationMetricOptions<FIELDS>): DistinctCountAggregationMetric<FIELDS>;
+    /**
+     * A percentile of an expression.
+     * `{ type: 'PERCENTILE', expression, percentile, alias, filter? }`.
+     *
+     * @param options.percentile - Which percentile, within (0, 100).
+     * @throws TypeError when `percentile` is not finite and within (0, 100), or
+     *   `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.percentile(aggregation.field('latency'), 'p95', { percentile: 95 });
+     * ```
+     */
+    percentile<FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, { percentile, filter: predicate }: PercentileAggregationOptions<FIELDS>): PercentileAggregationMetric<FIELDS>;
+    /**
+     * A metric computed from other metrics of the same row, by their aliases.
+     * `{ type: 'DERIVED', expression, alias }`. `aggregation.query()` checks
+     * that it refers only to metrics declared before it.
+     *
+     * @param expression - The arithmetic: a callback that builds it from the
+     *   {@link DerivedExpressionDsl} it is handed (`ref`, `constant`, `add`,
+     *   `subtract`, `multiply`, `divide`), or an already-built tree.
+     * @throws TypeError when `alias` is invalid, or a `constant` is not finite.
+     * @example
+     * ```typescript
+     * aggregation.derived(
+     *   d => d.divide(d.ref('revenue'), d.ref('orders')),
+     *   'averageOrder',
+     * );
+     * ```
+     */
+    derived(expression: DerivedExpression | ((d: DerivedExpressionDsl) => DerivedExpression), alias: string): DerivedAggregationMetric;
+    /**
+     * The builders of the query's `having`: conditions on the metric columns of
+     * the grouped rows (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `isIn`,
+     * `isNull`, `isNotNull`) and their `and`/`or`. See `HavingDsl`.
+     *
+     * @example
+     * ```typescript
+     * aggregation.query({
+     *   groupBy: [aggregation.terms('state.status', 'status')],
+     *   metrics: [aggregation.count('orders')],
+     *   having: aggregation.having.gt('orders', 10),
+     * });
+     * ```
+     */
+    having: import('./having.cjs').HavingDsl;
+    /**
+     * Admits a whole aggregation query against the rules Wow enforces on arrival.
+     *
+     * The factories above each check their own part; only the assembled query
+     * can answer the questions that span parts — whether two aliases collide,
+     * whether a sort names one of them, whether `having` has rows to filter.
+     * Wow checks all of it in `AggregationQuery`'s constructor and answers a
+     * query that fails with a 400, so the same rules run here against the object
+     * about to be sent.
+     */
+    query<ROOT_FIELDS extends string = string, AGGREGATION_FIELDS extends string = ROOT_FIELDS>(query: AggregationQuery<ROOT_FIELDS, AGGREGATION_FIELDS>): AggregationQuery<ROOT_FIELDS, AGGREGATION_FIELDS>;
+};

package/dist/dsl/aggregation/builders.d.ts

@@ -0,0 +1,309 @@
+import { ElementFilterExpression, ExpressionFilter } from '../filter/index.js';
+import { DerivedExpressionDsl } from './derived.js';
+import { DateDiffUnit, AggregationElement, AggregationExpression, DateDiffAggregationExpression, AggregationMetricOptions, AggregationQuery, AnyAggregationMetric, EdgeAggregationMetric, EdgeAggregationOptions, BinaryAggregationExpression, ConstantAggregationExpression, CountAggregationMetric, DateHistogramAggregationGroup, DateHistogramAggregationOptions, DatePartAggregationGroup, DatePartAggregationOptions, DerivedAggregationMetric, DerivedExpression, DistinctCountAggregationMetric, FieldAggregationExpression, HistogramAggregationGroup, HistogramAggregationOptions, NumericAggregationMetric, PercentileAggregationMetric, PercentileAggregationOptions, TermsAggregationGroup, TermsAggregationOptions } from './types.js';
+/**
+ * Builders of an `AggregationQuery`: its elements, groups, metrics and the
+ * arithmetic expressions metrics compute over. Each builder checks its own
+ * part and throws a `TypeError` naming what is wrong; {@link aggregation.query}
+ * checks the parts against each other.
+ *
+ * Every group and metric takes its target first, its alias second, and any
+ * further options as a trailing object.
+ */
+export declare const aggregation: {
+    /**
+     * Aggregates over the elements of an array field instead of the root
+     * documents. `{ path, filter? }`.
+     *
+     * @param path - The array field, a query field path.
+     * @param predicate - Keeps only the elements that match; may not contain
+     *   root filters (id, owner, tenant, space, deletion) or any search, even
+     *   one that names its fields. An `EXPRESSION` filter is allowed.
+     * @throws TypeError when `path` is not a valid field path or `predicate`
+     *   contains a root filter.
+     * @example
+     * ```typescript
+     * aggregation.element('items', filter.gt('quantity', 0));
+     * ```
+     */
+    element(path: string, predicate?: ElementFilterExpression | ExpressionFilter): AggregationElement;
+    /**
+     * The value of a field, as an operand. `{ type: 'FIELD', field }`.
+     *
+     * @throws TypeError when `field` is not a valid field path.
+     * @example
+     * ```typescript
+     * aggregation.sum(aggregation.field('state.amount'), 'amount');
+     * ```
+     */
+    field<FIELDS extends string>(field: FIELDS): FieldAggregationExpression<FIELDS>;
+    /**
+     * A number, as an operand. `{ type: 'CONSTANT', value }`.
+     *
+     * @throws TypeError when `value` is not finite.
+     * @example
+     * ```typescript
+     * aggregation.multiply(aggregation.field('price'), aggregation.constant(100));
+     * ```
+     */
+    constant(value: number): ConstantAggregationExpression;
+    /**
+     * The time from the instant in `from` to the instant in `to`, `to − from`,
+     * in `unit`, as a signed decimal: negative when `to` is earlier, and no
+     * value when either instant is absent. A `DAY` is exactly 24 hours.
+     * `{ type: 'DATE_DIFF', from, to, unit }`. Both fields must be
+     * single-valued time fields, those whose `aggregate.groups` list
+     * `DATE_HISTOGRAM` in the descriptor, and `unit` one of its
+     * `analysis.dateDiffUnits`. Wow 9.2 and later.
+     *
+     * @throws TypeError when `from` or `to` is not a valid field path, or
+     *   `unit` is not a {@link DateDiffUnit}.
+     * @example
+     * ```typescript
+     * // Hours from payment to shipping, averaged per warehouse.
+     * aggregation.avg(
+     *   aggregation.dateDiff('state.paidAt', 'state.shippedAt', DateDiffUnit.HOUR),
+     *   'hoursToShip',
+     * );
+     * ```
+     */
+    dateDiff<FIELDS extends string>(from: FIELDS, to: FIELDS, unit: DateDiffUnit): DateDiffAggregationExpression<FIELDS>;
+    /** `left + right`. `{ type: 'BINARY', operator: 'ADD', left, right }`. */
+    add: <FIELDS extends string>(left: AggregationExpression<FIELDS>, right: AggregationExpression<FIELDS>) => BinaryAggregationExpression<FIELDS>;
+    /** `left - right`. `{ type: 'BINARY', operator: 'SUBTRACT', left, right }`. */
+    subtract: <FIELDS extends string>(left: AggregationExpression<FIELDS>, right: AggregationExpression<FIELDS>) => BinaryAggregationExpression<FIELDS>;
+    /** `left * right`. `{ type: 'BINARY', operator: 'MULTIPLY', left, right }`. */
+    multiply: <FIELDS extends string>(left: AggregationExpression<FIELDS>, right: AggregationExpression<FIELDS>) => BinaryAggregationExpression<FIELDS>;
+    /** `left / right`. `{ type: 'BINARY', operator: 'DIVIDE', left, right }`. */
+    divide: <FIELDS extends string>(left: AggregationExpression<FIELDS>, right: AggregationExpression<FIELDS>) => BinaryAggregationExpression<FIELDS>;
+    /**
+     * Groups by each distinct value of a field, or of a computed expression.
+     * `{ type: 'TERMS', field, alias, missingKey? }`, or
+     * `{ type: 'TERMS', expression, alias }`.
+     *
+     * @param input - The field to group by, or an expression in its place
+     *   (Wow 9.2 and later, an expensive computation).
+     * @param alias - The name of the group column in the result rows.
+     * @param options.missingKey - The key of the rows without a value; only
+     *   with a field.
+     * @throws TypeError when `input` or `alias` is invalid, `missingKey` is
+     *   blank, or `missingKey` is given with an expression.
+     * @example
+     * ```typescript
+     * aggregation.terms('state.status', 'status', { missingKey: 'NONE' });
+     * aggregation.terms(
+     *   aggregation.dateDiff('state.paidAt', 'state.shippedAt', DateDiffUnit.DAY),
+     *   'daysToShip',
+     * );
+     * ```
+     */
+    terms<FIELDS extends string>(input: FIELDS | AggregationExpression<FIELDS>, alias: string, { missingKey }?: TermsAggregationOptions): TermsAggregationGroup<FIELDS>;
+    /**
+     * Groups a number field, or a computed expression, into buckets of equal
+     * width. `{ type: 'HISTOGRAM', field | expression, interval, alias }`.
+     *
+     * @param input - The number field to bucket, or an expression in its
+     *   place (Wow 9.2 and later, an expensive computation).
+     * @param alias - The name of the bucket column in the result rows.
+     * @param options.interval - The bucket width.
+     * @throws TypeError when `interval` is not finite and greater than 0, or
+     *   `field` or `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.histogram('state.amount', 'amountBand', { interval: 100 });
+     * ```
+     */
+    histogram<FIELDS extends string>(input: FIELDS | AggregationExpression<FIELDS>, alias: string, { interval }: HistogramAggregationOptions): HistogramAggregationGroup<FIELDS>;
+    /**
+     * Groups a time field into calendar buckets.
+     * `{ type: 'DATE_HISTOGRAM', field, unit, alias, timeZone, dense? }`.
+     *
+     * @param field - The time field (epoch milliseconds) to bucket.
+     * @param alias - The name of the bucket column in the result rows.
+     * @param options.unit - The calendar unit of a bucket.
+     * @param options.timeZone - The zone buckets are cut in. Defaults to `UTC`.
+     * @param options.dense - Whether the empty buckets of the range are filled
+     *   in.
+     * @throws TypeError when `unit` is not an `AggregationDateUnit`,
+     *   `timeZone` is blank, `dense` is not a boolean, or `field` or `alias` is
+     *   invalid.
+     * @example
+     * ```typescript
+     * aggregation.dateHistogram('createTime', 'day', {
+     *   unit: AggregationDateUnit.DAY,
+     *   timeZone: 'Asia/Shanghai',
+     * });
+     * ```
+     */
+    dateHistogram<FIELDS extends string>(field: FIELDS, alias: string, { unit, timeZone, dense }: DateHistogramAggregationOptions): DateHistogramAggregationGroup<FIELDS>;
+    /**
+     * Groups a time field by one calendar part of each instant, such as the
+     * weekday or the hour, so records from different days share a bucket.
+     * `{ type: 'DATE_PART', field, part, alias, timeZone, dense? }`.
+     *
+     * The group's keys in the result rows are integers: `DAY_OF_WEEK` is the
+     * ISO weekday, 1 (Monday) to 7 (Sunday); `DAY_OF_MONTH` 1 to 31;
+     * `HOUR_OF_DAY` 0 to 23 on the wall clock of `timeZone`; `MONTH_OF_YEAR`
+     * 1 to 12. With `dense`, every key of that domain comes back, those
+     * without records carrying each metric's empty value; `dense` needs the
+     * group to be the query's only one. Wow 9.2 and later.
+     *
+     * @param field - The time field (epoch milliseconds) to read the part of.
+     * @param alias - The name of the part column in the result rows.
+     * @param options.part - The calendar part to group by.
+     * @param options.timeZone - The zone the part is read in. Defaults to
+     *   `UTC`.
+     * @param options.dense - Whether every key of the part's domain is
+     *   returned.
+     * @throws TypeError when `part` is not an `AggregationDatePart`,
+     *   `timeZone` is blank, `dense` is not a boolean, or `field` or `alias` is
+     *   invalid.
+     * @example
+     * ```typescript
+     * aggregation.datePart('createTime', 'weekday', {
+     *   part: AggregationDatePart.DAY_OF_WEEK,
+     *   timeZone: 'Asia/Shanghai',
+     * });
+     * ```
+     */
+    datePart<FIELDS extends string>(field: FIELDS, alias: string, { part, timeZone, dense }: DatePartAggregationOptions): DatePartAggregationGroup<FIELDS>;
+    /**
+     * Any one value of a field within each group, of any type.
+     * `{ type: 'ANY', field, alias, filter? }`.
+     *
+     * @throws TypeError when `field` or `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.any('state.customerName', 'customer');
+     * ```
+     */
+    any<FIELDS extends string>(field: FIELDS, alias: string, { filter: predicate }?: AggregationMetricOptions<FIELDS>): AnyAggregationMetric<FIELDS>;
+    /**
+     * The value of `field` on each group's earliest record by `orderBy`.
+     * `{ type: 'FIRST', field, alias, orderBy?, filter? }`.
+     *
+     * The value comes back in the field's own type, or `null` when no record
+     * of the group has both a value and an `orderBy` position. Without
+     * `orderBy` the server orders by the model's event time, which the
+     * descriptor names as `analysis.firstLastOrderBy`. Neither a derived
+     * metric nor `having` may refer to it. Wow 9.2 and later.
+     *
+     * @throws TypeError when `field`, `orderBy` or `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.first('state.price', 'open', { orderBy: 'createTime' });
+     * ```
+     */
+    first<FIELDS extends string>(field: FIELDS, alias: string, options?: EdgeAggregationOptions<FIELDS>): EdgeAggregationMetric<FIELDS>;
+    /**
+     * The value of `field` on each group's latest record by `orderBy`.
+     * `{ type: 'LAST', field, alias, orderBy?, filter? }`. As
+     * {@link aggregation.first}, from the other end.
+     *
+     * @throws TypeError when `field`, `orderBy` or `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.last('state.price', 'close', { orderBy: 'createTime' });
+     * ```
+     */
+    last<FIELDS extends string>(field: FIELDS, alias: string, options?: EdgeAggregationOptions<FIELDS>): EdgeAggregationMetric<FIELDS>;
+    /**
+     * The number of rows in each group. `{ type: 'COUNT', alias, filter? }`.
+     *
+     * @param alias - The name of the metric column in the result rows.
+     * @param options.filter - Counts only the rows that match.
+     * @throws TypeError when `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.count('paid', { filter: filter.eq('state.status', 'PAID') });
+     * ```
+     */
+    count<FIELDS extends string = string>(alias: string, { filter: predicate }?: AggregationMetricOptions<FIELDS>): CountAggregationMetric<FIELDS>;
+    /**
+     * The sum of an expression. `{ type: 'NUMERIC', function: 'SUM',
+     * expression, alias, filter? }`.
+     *
+     * @example
+     * ```typescript
+     * aggregation.sum(aggregation.field('state.amount'), 'revenue');
+     * ```
+     */
+    sum: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /** The average of an expression; see {@link aggregation.sum}. */
+    avg: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /** The least value of an expression; see {@link aggregation.sum}. */
+    min: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /** The greatest value of an expression; see {@link aggregation.sum}. */
+    max: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /** The standard deviation of an expression; see {@link aggregation.sum}. */
+    stddev: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /** The variance of an expression; see {@link aggregation.sum}. */
+    variance: <FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, options?: AggregationMetricOptions<FIELDS>) => NumericAggregationMetric<FIELDS>;
+    /**
+     * The number of distinct values of an expression.
+     * `{ type: 'DISTINCT_COUNT', expression, alias, filter? }`.
+     *
+     * @example
+     * ```typescript
+     * aggregation.distinctCount(aggregation.field('ownerId'), 'customers');
+     * ```
+     */
+    distinctCount<FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, { filter: predicate }?: AggregationMetricOptions<FIELDS>): DistinctCountAggregationMetric<FIELDS>;
+    /**
+     * A percentile of an expression.
+     * `{ type: 'PERCENTILE', expression, percentile, alias, filter? }`.
+     *
+     * @param options.percentile - Which percentile, within (0, 100).
+     * @throws TypeError when `percentile` is not finite and within (0, 100), or
+     *   `alias` is invalid.
+     * @example
+     * ```typescript
+     * aggregation.percentile(aggregation.field('latency'), 'p95', { percentile: 95 });
+     * ```
+     */
+    percentile<FIELDS extends string>(expression: AggregationExpression<FIELDS>, alias: string, { percentile, filter: predicate }: PercentileAggregationOptions<FIELDS>): PercentileAggregationMetric<FIELDS>;
+    /**
+     * A metric computed from other metrics of the same row, by their aliases.
+     * `{ type: 'DERIVED', expression, alias }`. `aggregation.query()` checks
+     * that it refers only to metrics declared before it.
+     *
+     * @param expression - The arithmetic: a callback that builds it from the
+     *   {@link DerivedExpressionDsl} it is handed (`ref`, `constant`, `add`,
+     *   `subtract`, `multiply`, `divide`), or an already-built tree.
+     * @throws TypeError when `alias` is invalid, or a `constant` is not finite.
+     * @example
+     * ```typescript
+     * aggregation.derived(
+     *   d => d.divide(d.ref('revenue'), d.ref('orders')),
+     *   'averageOrder',
+     * );
+     * ```
+     */
+    derived(expression: DerivedExpression | ((d: DerivedExpressionDsl) => DerivedExpression), alias: string): DerivedAggregationMetric;
+    /**
+     * The builders of the query's `having`: conditions on the metric columns of
+     * the grouped rows (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `isIn`,
+     * `isNull`, `isNotNull`) and their `and`/`or`. See `HavingDsl`.
+     *
+     * @example
+     * ```typescript
+     * aggregation.query({
+     *   groupBy: [aggregation.terms('state.status', 'status')],
+     *   metrics: [aggregation.count('orders')],
+     *   having: aggregation.having.gt('orders', 10),
+     * });
+     * ```
+     */
+    having: import('./having.js').HavingDsl;
+    /**
+     * Admits a whole aggregation query against the rules Wow enforces on arrival.
+     *
+     * The factories above each check their own part; only the assembled query
+     * can answer the questions that span parts — whether two aliases collide,
+     * whether a sort names one of them, whether `having` has rows to filter.
+     * Wow checks all of it in `AggregationQuery`'s constructor and answers a
+     * query that fails with a 400, so the same rules run here against the object
+     * about to be sent.
+     */
+    query<ROOT_FIELDS extends string = string, AGGREGATION_FIELDS extends string = ROOT_FIELDS>(query: AggregationQuery<ROOT_FIELDS, AGGREGATION_FIELDS>): AggregationQuery<ROOT_FIELDS, AGGREGATION_FIELDS>;
+};