@adaptabletools/adaptable 23.1.0-canary.2 → 24.0.0-canary.0

package/vendor/aql/plan/operators.js

@@ -0,0 +1,771 @@
+import { isAfter } from 'date-fns';
+import { parseDateValue } from '../functions/dateUtils.js';
+import { isDefinedValue, isUndefinedValue, toFiniteNumber } from '../functions/utils.js';
+/** Sentinel: a running variant emits no per-row value for this row. */
+export const SKIP_ROW = Symbol('aql.plan.skipRow');
+// --- shared numeric helpers ---------------------------------------------------
+const numericOutput = () => 'number';
+const inputOutput = (inputType) => inputType;
+const finiteOrSkip = (value) => isUndefinedValue(value) ? undefined : toFiniteNumber(value);
+export const cumulativeSum = () => ({
+    init: () => ({ currentValue: 0 }),
+    step: (s, value) => {
+        const numeric = finiteOrSkip(value);
+        if (numeric !== undefined) {
+            s.currentValue += numeric;
+        }
+    },
+    current: (s) => s.currentValue,
+});
+export const cumulativeCount = () => ({
+    init: () => ({ currentValue: 0 }),
+    step: (s, value) => {
+        if (isDefinedValue(value)) {
+            s.currentValue += 1;
+        }
+    },
+    current: (s) => s.currentValue,
+});
+/**
+ * Legacy-parity note (`mapAggregationToCumulation`): the DATE branch
+ * replaces the sentinel unconditionally on the first defined value (even an
+ * unparseable one) and otherwise compares via `isAfter` without parse guards
+ * (unparseable → no replacement).
+ *
+ * The NUMERIC branch must also replace the sentinel on the first value:
+ * `Number.MIN_VALUE` is the smallest *positive* number, so a running MAX over
+ * zero / negative values would otherwise never beat it.
+ */
+export const cumulativeExtremum = (spec, mode, sentinel) => {
+    const isDate = spec.inputType === 'date';
+    return {
+        init: () => ({ currentValue: sentinel }),
+        step: (s, value) => {
+            const st = s;
+            if (!isDefinedValue(value)) {
+                return;
+            }
+            if (isDate) {
+                if (st.currentValue === sentinel) {
+                    st.currentValue = value;
+                    return;
+                }
+                const current = parseDateValue(st.currentValue);
+                const parsed = parseDateValue(value);
+                const replace = mode === 'max'
+                    ? isAfter(parsed, current)
+                    : isAfter(current, parsed);
+                if (replace) {
+                    st.currentValue = value;
+                }
+                return;
+            }
+            const numeric = toFiniteNumber(value);
+            if (numeric === undefined) {
+                return;
+            }
+            if (st.currentValue === sentinel) {
+                st.currentValue = numeric;
+                return;
+            }
+            if (mode === 'min'
+                ? numeric < st.currentValue
+                : numeric > st.currentValue) {
+                st.currentValue = numeric;
+            }
+        },
+        current: (s) => {
+            const st = s;
+            return st.currentValue === sentinel ? SKIP_ROW : st.currentValue;
+        },
+    };
+};
+export const cumulativeAvg = (spec) => ({
+    init: () => ({ sum: 0, weightSum: 0 }),
+    step: (s, value, rowCtx) => {
+        const st = s;
+        const numeric = finiteOrSkip(value);
+        if (numeric === undefined) {
+            return;
+        }
+        if (spec.hasWeight) {
+            const weight = toFiniteNumber(rowCtx.weightValue) ?? 0;
+            st.sum += numeric * weight;
+            st.weightSum += weight;
+        }
+        else {
+            st.sum += numeric;
+            st.weightSum += 1;
+        }
+    },
+    current: (s) => {
+        const st = s;
+        return st.weightSum === 0 ? SKIP_ROW : st.sum / st.weightSum;
+    },
+});
+/** Cumulative PERCENTAGE: running sum per row, divided by the total post-pass. */
+export const cumulativePercentage = () => ({
+    init: () => ({ currentValue: 0 }),
+    step: (s, value) => {
+        const numeric = finiteOrSkip(value);
+        if (numeric !== undefined) {
+            s.currentValue += numeric;
+        }
+    },
+    current: (s) => s.currentValue,
+    finalizeRow: (recorded, s) => {
+        const total = s.currentValue;
+        return (recorded / total) * 100;
+    },
+});
+// --- static schema helpers ------------------------------------------------------
+const anyInput = {};
+const numericParameters = {
+    subject: 'column-or-field',
+    list: [{ types: ['number'] }],
+};
+const comparableParameters = {
+    subject: 'column-or-field',
+    list: [{ types: ['number', 'text', 'date'] }],
+};
+const anyParameters = { subject: 'column-or-field', list: [anyInput] };
+// --- reducer operators ---------------------------------------------------------
+const SUM_OPERATOR = {
+    name: 'SUM',
+    kind: 'reducer',
+    init: () => 0,
+    step: (_spec, acc, value) => {
+        const numeric = finiteOrSkip(value);
+        return numeric === undefined ? acc : acc + numeric;
+    },
+    capabilities: {
+        cumulative: cumulativeSum,
+        delta: (acc, oldValue, newValue) => acc - (finiteOrSkip(oldValue) ?? 0) + (finiteOrSkip(newValue) ?? 0),
+    },
+    outputType: numericOutput,
+    parameters: numericParameters,
+    resultType: 'number',
+    docs: {
+        description: 'Returns the sum of non-empty values in a numeric column. Optional GROUP_BY computes the sum within each partition.',
+        signatures: ['SUM{[numCol]}', 'SUM{[numCol], GROUP_BY([stringCol])}'],
+        examples: ['SUM{[numCol]}', 'SUM{[numCol], GROUP_BY([stringCol])}'],
+        category: 'aggregation',
+    },
+};
+const AVG_OPERATOR = {
+    name: 'AVG',
+    kind: 'reducer',
+    init: () => ({ sumOfValues: 0, numberOfValues: 0 }),
+    step: (spec, acc, value, rowCtx) => {
+        const avgAcc = acc;
+        const numeric = finiteOrSkip(value);
+        if (numeric === undefined) {
+            return avgAcc;
+        }
+        if (spec.hasWeight) {
+            const weight = toFiniteNumber(rowCtx.weightValue);
+            if (weight === undefined) {
+                return avgAcc;
+            }
+            avgAcc.sumOfValues += numeric * weight;
+            avgAcc.numberOfValues += weight;
+        }
+        else {
+            avgAcc.sumOfValues += numeric;
+            avgAcc.numberOfValues += 1;
+        }
+        return avgAcc;
+    },
+    done: (_spec, acc) => {
+        const avgAcc = acc;
+        return avgAcc.numberOfValues === 0 ? 0 : avgAcc.sumOfValues / avgAcc.numberOfValues;
+    },
+    capabilities: {
+        weight: true,
+        cumulative: cumulativeAvg,
+        // Unweighted only (delta plans never carry WEIGHT).
+        delta: (acc, oldValue, newValue) => {
+            const avgAcc = acc;
+            const previous = finiteOrSkip(oldValue);
+            const next = finiteOrSkip(newValue);
+            return {
+                sumOfValues: avgAcc.sumOfValues - (previous ?? 0) + (next ?? 0),
+                numberOfValues: avgAcc.numberOfValues - (previous === undefined ? 0 : 1) + (next === undefined ? 0 : 1),
+            };
+        },
+    },
+    outputType: numericOutput,
+    parameters: numericParameters,
+    resultType: 'number',
+    docs: {
+        description: 'Returns the arithmetic mean of non-empty values in a numeric column. Optional WEIGHT uses another numeric column for a weighted average. Optional GROUP_BY computes within each partition.',
+        signatures: [
+            'AVG{[numCol]}',
+            'AVG{[numCol], GROUP_BY([stringCol])}',
+            'AVG{[numCol], WEIGHT([weightCol])}',
+            'AVG{[numCol], WEIGHT([weightCol]), GROUP_BY([stringCol])}',
+        ],
+        examples: [
+            'AVG{[numCol]}',
+            'AVG{[numCol], GROUP_BY([stringCol])}',
+            'AVG{[numCol], WEIGHT([weightCol])}',
+            'AVG{[numCol], WEIGHT([weightCol]), GROUP_BY([stringCol])}',
+        ],
+        category: 'aggregation',
+    },
+};
+const extremumReducer = (name) => {
+    const sentinel = name === 'MIN' ? Number.MAX_VALUE : Number.MIN_VALUE;
+    return {
+        name,
+        kind: 'reducer',
+        init: () => sentinel,
+        step: (spec, acc, value) => {
+            if (isUndefinedValue(value)) {
+                return acc;
+            }
+            if (spec.inputType === 'date') {
+                const parsed = parseDateValue(value);
+                if (!parsed) {
+                    return acc;
+                }
+                if (acc === sentinel) {
+                    return value;
+                }
+                const current = parseDateValue(acc);
+                if (!current) {
+                    return value;
+                }
+                if (name === 'MIN') {
+                    return isAfter(parsed, current) ? acc : value;
+                }
+                return isAfter(parsed, current) ? value : acc;
+            }
+            const numeric = toFiniteNumber(value);
+            if (numeric === undefined) {
+                return acc;
+            }
+            if (acc === sentinel) {
+                return numeric;
+            }
+            if (name === 'MIN') {
+                return numeric < acc ? numeric : acc;
+            }
+            return numeric > acc ? numeric : acc;
+        },
+        done: (_spec, acc) => (acc === sentinel ? undefined : acc),
+        capabilities: {
+            cumulative: (spec) => cumulativeExtremum(spec, name === 'MIN' ? 'min' : 'max', sentinel),
+        },
+        outputType: inputOutput,
+        parameters: comparableParameters,
+        resultType: 'input',
+        docs: {
+            description: `Returns the ${name === 'MIN' ? 'minimum' : 'maximum'} value in a numeric or date column. Optional GROUP_BY computes within each partition.`,
+            signatures: [
+                `${name}{[numCol]}`,
+                `${name}{[dateCol]}`,
+                `${name}{[numCol], GROUP_BY([stringCol])}`,
+            ],
+            examples: [
+                `${name}{[numCol]}`,
+                `${name}{[dateCol]}`,
+                `${name}{[numCol], GROUP_BY([stringCol])}`,
+            ],
+            category: 'aggregation',
+        },
+    };
+};
+const COUNT_OPERATOR = {
+    name: 'COUNT',
+    kind: 'reducer',
+    init: () => 0,
+    step: (_spec, acc, value) => (isUndefinedValue(value) ? acc : acc + 1),
+    capabilities: {
+        cumulative: cumulativeCount,
+        delta: (acc, oldValue, newValue) => acc - (isUndefinedValue(oldValue) ? 0 : 1) + (isUndefinedValue(newValue) ? 0 : 1),
+    },
+    outputType: numericOutput,
+    parameters: anyParameters,
+    resultType: 'number',
+    docs: {
+        description: 'Returns the count of non-empty values in a column. Optional GROUP_BY computes within each partition.',
+        signatures: ['COUNT{[numCol]}', 'COUNT{[stringCol]}', 'COUNT{[numCol], GROUP_BY([stringCol])}'],
+        examples: ['COUNT{[numCol]}', 'COUNT{[stringCol]}', 'COUNT{[numCol], GROUP_BY([stringCol])}'],
+        category: 'aggregation',
+    },
+};
+const PRODUCT_OPERATOR = {
+    name: 'PRODUCT',
+    kind: 'reducer',
+    // Multiplicative identity — empty / all-blank sets stay 1.
+    init: () => 1,
+    step: (_spec, acc, value) => {
+        const numeric = finiteOrSkip(value);
+        return numeric === undefined ? acc : acc * numeric;
+    },
+    capabilities: {},
+    outputType: numericOutput,
+    parameters: numericParameters,
+    resultType: 'number',
+    docs: {
+        description: 'Returns the product of non-empty values in a numeric column. Optional GROUP_BY computes the product within each partition. An empty set returns 1.',
+        signatures: [
+            'PRODUCT{[numCol]}',
+            'PRODUCT{[numCol], GROUP_BY([stringCol])}',
+        ],
+        examples: ['PRODUCT{[numCol]}', 'PRODUCT{[numCol], GROUP_BY([stringCol])}'],
+        category: 'aggregation',
+    },
+};
+const MEDIAN_OPERATOR = {
+    name: 'MEDIAN',
+    kind: 'reducer',
+    init: () => [],
+    step: (_spec, acc, value) => {
+        const values = acc;
+        const numeric = finiteOrSkip(value);
+        if (numeric !== undefined) {
+            values.push(numeric);
+        }
+        return values;
+    },
+    done: (_spec, acc) => {
+        const values = acc;
+        if (values.length === 0) {
+            return null;
+        }
+        const sorted = [...values].sort((a, b) => a - b);
+        const middle = Math.floor((sorted.length - 1) / 2);
+        return sorted.length % 2 ? sorted[middle] : (sorted[middle] + sorted[middle + 1]) / 2.0;
+    },
+    capabilities: {},
+    outputType: numericOutput,
+    parameters: numericParameters,
+    resultType: 'number',
+    docs: {
+        description: 'Returns the median of values in a numeric column. Optional GROUP_BY computes within each partition.',
+        signatures: [
+            'MEDIAN{[numCol]}',
+            'MEDIAN{[numCol], GROUP_BY([stringCol])}',
+        ],
+        examples: ['MEDIAN{[numCol]}', 'MEDIAN{[numCol], GROUP_BY([stringCol])}'],
+        category: 'aggregation',
+    },
+};
+const MODE_OPERATOR = {
+    name: 'MODE',
+    kind: 'reducer',
+    init: () => new Map(),
+    step: (_spec, acc, value) => {
+        const counts = acc;
+        if (typeof value !== 'number' && typeof value !== 'string') {
+            return counts;
+        }
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+        return counts;
+    },
+    done: (_spec, acc) => {
+        const counts = acc;
+        // Legacy parity: same (quirky) comparator as the pool MODE.
+        const sorted = [...counts.entries()].sort(([aVal, aFreq], [bVal, bFreq]) => {
+            if (aFreq < bFreq) {
+                return 1;
+            }
+            else if (aFreq > bFreq || aVal < bVal) {
+                return -1;
+            }
+            else {
+                return aVal === bVal ? 0 : 1;
+            }
+        });
+        return sorted?.[0]?.[0];
+    },
+    capabilities: {},
+    outputType: inputOutput,
+    parameters: comparableParameters,
+    resultType: 'input',
+    docs: {
+        description: 'Returns the most frequent value in a number, text, or date column. Optional GROUP_BY computes within each partition.',
+        signatures: ['MODE{[numCol]}', 'MODE{[stringCol]}', 'MODE{[numCol], GROUP_BY([stringCol])}'],
+        examples: ['MODE{[numCol]}', 'MODE{[stringCol]}', 'MODE{[stringCol], GROUP_BY([stringCol])}'],
+        category: 'aggregation',
+    },
+};
+const DISTINCT_OPERATOR = {
+    name: 'DISTINCT',
+    kind: 'reducer',
+    init: () => new Set(),
+    step: (_spec, acc, value) => {
+        const seen = acc;
+        if (typeof value === 'number' || typeof value === 'string') {
+            seen.add(value);
+        }
+        return seen;
+    },
+    done: (_spec, acc) => acc.size,
+    capabilities: {},
+    outputType: numericOutput,
+    parameters: comparableParameters,
+    resultType: 'number',
+    docs: {
+        description: 'Returns how many distinct values appear in a column. Optional GROUP_BY computes within each partition.',
+        signatures: [
+            'DISTINCT{[numCol]}',
+            'DISTINCT{[stringCol]}',
+            'DISTINCT{[numCol], GROUP_BY([stringCol])}',
+        ],
+        examples: [
+            'DISTINCT{[numCol]}',
+            'DISTINCT{[stringCol]}',
+            'DISTINCT{[stringCol], GROUP_BY([stringCol])}',
+        ],
+        category: 'aggregation',
+    },
+};
+const ONLY_OPERATOR = {
+    name: 'ONLY',
+    kind: 'reducer',
+    init: () => new Set(),
+    step: (_spec, acc, value) => {
+        const seen = acc;
+        if (typeof value === 'number' || typeof value === 'string') {
+            seen.add(value);
+        }
+        return seen;
+    },
+    done: (_spec, acc) => {
+        const seen = acc;
+        return seen.size === 1 ? seen.values().next().value : null;
+    },
+    capabilities: {},
+    outputType: inputOutput,
+    parameters: comparableParameters,
+    resultType: 'input',
+    docs: {
+        description: 'Returns the column value when every non-empty row shares the same value; otherwise returns null. Works with number and text columns. Optional GROUP_BY computes within each partition.',
+        signatures: ['ONLY{[numCol]}', 'ONLY{[stringCol]}', 'ONLY{[stringCol], GROUP_BY([stringCol])}'],
+        examples: ['ONLY{[numCol]}', 'ONLY{[stringCol]}', 'ONLY{[stringCol], GROUP_BY([stringCol])}'],
+        category: 'aggregation',
+    },
+};
+const STD_DEVIATION_OPERATOR = {
+    name: 'STD_DEVIATION',
+    kind: 'reducer',
+    init: () => ({ sumOfValues: 0, values: [] }),
+    step: (_spec, acc, value) => {
+        const stdAcc = acc;
+        // Legacy parity: strictly-number inputs only (no numeric-string coercion).
+        if (typeof value !== 'number' || isNaN(value)) {
+            return stdAcc;
+        }
+        stdAcc.sumOfValues += value;
+        stdAcc.values.push(value);
+        return stdAcc;
+    },
+    done: (_spec, acc) => {
+        const { sumOfValues, values } = acc;
+        if (values.length === 0) {
+            return 0;
+        }
+        const mean = sumOfValues / values.length;
+        const variance = values.reduce((total, value) => total + Math.pow(value - mean, 2), 0) / values.length;
+        return Math.sqrt(variance);
+    },
+    capabilities: {},
+    outputType: numericOutput,
+    parameters: numericParameters,
+    resultType: 'number',
+    docs: {
+        description: 'Returns the population standard deviation of values in a numeric column. Optional GROUP_BY computes within each partition.',
+        signatures: [
+            'STD_DEVIATION{[numCol]}',
+            'STD_DEVIATION{[numCol], GROUP_BY([stringCol])}',
+        ],
+        examples: ['STD_DEVIATION{[numCol]}', 'STD_DEVIATION{[numCol], GROUP_BY([stringCol])}'],
+        category: 'aggregation',
+    },
+};
+/**
+ * Deprecation-era: the reduction behind the legacy `PERCENTAGE` wrapper —
+ * a SUM over the denominator column. The per-row `cell/total*100` reading
+ * comes from the plan's `percentage` projection (non-cumulative) or from
+ * the running variant's post-pass division (cumulative). Dissolves into
+ * scalar math when the wrapper's sugar expansion lands.
+ */
+const PERCENTAGE_OPERATOR = {
+    name: 'PERCENTAGE',
+    kind: 'reducer',
+    init: () => 0,
+    step: (_spec, acc, value) => {
+        const numeric = finiteOrSkip(value);
+        return numeric === undefined ? acc : acc + numeric;
+    },
+    capabilities: { cumulative: cumulativePercentage },
+    outputType: numericOutput,
+    callForm: 'paren',
+    parameters: {
+        subject: 'column-or-field',
+        list: [
+            { types: ['number'] },
+            { optional: true, ui: { label: 'Denominator (SUM{…} or GROUP_BY)' } },
+        ],
+    },
+    resultType: 'number',
+    docs: {
+        description: "Returns each row's value as a percentage of a column sum (×100). By default the denominator is SUM of the same column; pass SUM{[otherCol]} to use another column's sum. Optional GROUP_BY scopes the denominator to each partition. Pass either GROUP_BY or SUM{...}, not both.",
+        signatures: [
+            'PERCENTAGE([numCol])',
+            'PERCENTAGE([numCol], GROUP_BY([stringCol]))',
+            'PERCENTAGE([numCol], SUM{[numCol]})',
+            'PERCENTAGE([numCol], SUM{[numCol], GROUP_BY([stringCol])})',
+        ],
+        examples: [
+            'PERCENTAGE([numCol])',
+            'PERCENTAGE([numCol], GROUP_BY([stringCol]))',
+            'PERCENTAGE([numCol], SUM{[weightCol]})',
+            'PERCENTAGE([numCol], SUM{[weightCol], GROUP_BY([stringCol])})',
+        ],
+        category: 'aggregation',
+    },
+};
+const orderedSeriesDocs = (name) => ({
+    description: `Returns the ${name.toLowerCase()} value of the given column when rows are ordered by OVER. Optional GROUP_BY computes that ${name.toLowerCase()} value within each partition.`,
+    signatures: [
+        `${name}{[numCol], OVER([dateCol])}`,
+        `${name}{[numCol], OVER([dateCol]), GROUP_BY([stringCol])}`,
+    ],
+    examples: [
+        `${name}{[numCol], OVER([dateCol])}`,
+        `${name}{[stringCol], OVER([dateCol]), GROUP_BY([stringCol])}`,
+    ],
+    category: 'reference',
+});
+const FIRST_OPERATOR = {
+    name: 'FIRST',
+    kind: 'reducer',
+    requiresOver: true,
+    init: () => undefined,
+    step: (_spec, acc, value) => (isDefinedValue(acc) ? acc : value),
+    capabilities: {},
+    outputType: inputOutput,
+    parameters: comparableParameters,
+    resultType: 'input',
+    docs: orderedSeriesDocs('FIRST'),
+};
+const LAST_OPERATOR = {
+    name: 'LAST',
+    kind: 'reducer',
+    requiresOver: true,
+    init: () => undefined,
+    step: (_spec, acc, value) => (isDefinedValue(value) ? value : acc),
+    capabilities: {},
+    outputType: inputOutput,
+    parameters: comparableParameters,
+    resultType: 'input',
+    docs: orderedSeriesDocs('LAST'),
+};
+// --- window operators ------------------------------------------------------------
+const requireOffset = (spec) => {
+    const offset = spec.params.find((param) => typeof param === 'number');
+    if (typeof offset !== 'number' || !Number.isInteger(offset) || offset < 1) {
+        throw new Error('LAG/LEAD requires a positive integer offset parameter');
+    }
+    return offset;
+};
+const offsetParameters = {
+    subject: 'column-or-field',
+    list: [anyInput, { types: ['number'], optional: true, ui: { label: 'Offset' } }],
+};
+const offsetWindowDocs = (name) => ({
+    description: `Returns the value from a ${name === 'LAG' ? 'previous' : 'later'} row in the given column when ordered by OVER (SQL ${name}). Offset is a required positive integer. Optional GROUP_BY computes within each partition. See also ${name === 'LAG' ? 'LEAD' : 'LAG'}.`,
+    signatures: [
+        `${name}{[numCol], offset: number, OVER([dateCol])}`,
+        `${name}{[numCol], offset: number, OVER([dateCol]), GROUP_BY([stringCol])}`,
+    ],
+    examples: [
+        `${name}{[numCol], 1, OVER([dateCol])}`,
+        `${name}{[numCol], 2, OVER([dateCol]), GROUP_BY([stringCol])}`,
+    ],
+    category: 'reference',
+});
+const LAG_OPERATOR = {
+    name: 'LAG',
+    kind: 'window',
+    requiresOver: true,
+    run: (spec, partition) => {
+        const offset = requireOffset(spec);
+        const rowValues = new Map();
+        for (let index = offset; index < partition.rowRefs.length; index++) {
+            const lagged = partition.getValue(index - offset);
+            if (isDefinedValue(lagged)) {
+                rowValues.set(partition.getRowId(index), lagged);
+            }
+        }
+        return { rowValues };
+    },
+    capabilities: {},
+    outputType: inputOutput,
+    parameters: offsetParameters,
+    resultType: 'input',
+    docs: offsetWindowDocs('LAG'),
+};
+const LEAD_OPERATOR = {
+    name: 'LEAD',
+    kind: 'window',
+    requiresOver: true,
+    run: (spec, partition) => {
+        const offset = requireOffset(spec);
+        const rowValues = new Map();
+        for (let index = 0; index + offset < partition.rowRefs.length; index++) {
+            const ahead = partition.getValue(index + offset);
+            if (isDefinedValue(ahead)) {
+                rowValues.set(partition.getRowId(index), ahead);
+            }
+        }
+        return { rowValues };
+    },
+    capabilities: {},
+    outputType: inputOutput,
+    parameters: offsetParameters,
+    resultType: 'input',
+    docs: offsetWindowDocs('LEAD'),
+};
+const RANK_OPERATOR = {
+    name: 'RANK',
+    kind: 'window',
+    requiresOver: true,
+    run: (_spec, partition) => {
+        const rowValues = new Map();
+        let currentRank = 0;
+        let previousOrderValue;
+        let hasPrevious = false;
+        for (let index = 0; index < partition.rowRefs.length; index++) {
+            const orderValue = partition.getValue(index);
+            if (!hasPrevious || previousOrderValue !== orderValue) {
+                currentRank = index + 1;
+                previousOrderValue = orderValue;
+                hasPrevious = true;
+            }
+            rowValues.set(partition.getRowId(index), currentRank);
+        }
+        return { rowValues };
+    },
+    capabilities: {},
+    outputType: numericOutput,
+    // The ordering ref comes from OVER — no positional input.
+    parameters: { subject: 'none', list: [] },
+    requiresInput: false,
+    resultType: 'number',
+    docs: {
+        description: "Returns the 1-based rank of each row when ordered by OVER (ties share a rank; the next distinct value skips ranks). Rank 1 is the smallest value; use OVER([numCol], 'DESC') to make rank 1 the largest. Optional GROUP_BY ranks within each partition.",
+        signatures: [
+            'RANK{OVER([dateCol])}',
+            'RANK{OVER([numCol])}',
+            "RANK{OVER([numCol], 'DESC')}",
+            'RANK{OVER([dateCol]), GROUP_BY([stringCol])}',
+        ],
+        examples: [
+            'RANK{OVER([dateCol])}',
+            "RANK{OVER([numCol], 'DESC')}",
+            'RANK{OVER([numCol]), GROUP_BY([stringCol])}',
+        ],
+        category: 'reference',
+    },
+};
+const isQuantileCell = (value) => !isUndefinedValue(value) && toFiniteNumber(value) !== undefined;
+const QUANT_OPERATOR = {
+    name: 'QUANT',
+    kind: 'window',
+    sortsBySelf: true,
+    partitionRowFilter: isQuantileCell,
+    run: (spec, partition) => {
+        const qNumber = spec.params.find((param) => typeof param === 'number');
+        if (typeof qNumber !== 'number') {
+            throw new Error('QUANT requires a numeric q parameter');
+        }
+        const populationSize = partition.rowRefs.length;
+        const bucketThresholds = new Map();
+        for (let step = 1; step <= qNumber; step++) {
+            bucketThresholds.set(step, populationSize * (step / qNumber));
+        }
+        const indexBucketMap = new Map();
+        for (let populationIndex = 0; populationIndex < populationSize; populationIndex++) {
+            for (let quantIndex = 1; quantIndex <= qNumber; quantIndex++) {
+                if (bucketThresholds.get(quantIndex) < populationIndex + 1) {
+                    continue;
+                }
+                indexBucketMap.set(populationIndex, quantIndex);
+                break;
+            }
+        }
+        // Buckets are keyed by row value, so tied values share one bucket: the
+        // first tied row's (the bucket the value first reaches in sort order).
+        const valueBucketMap = {};
+        for (let index = 0; index < populationSize; index++) {
+            const valueKey = String(partition.getValue(index));
+            if (!(valueKey in valueBucketMap)) {
+                valueBucketMap[valueKey] = indexBucketMap.get(index);
+            }
+        }
+        const rowValues = new Map();
+        for (let index = 0; index < populationSize; index++) {
+            rowValues.set(partition.getRowId(index), valueBucketMap[String(partition.getValue(index))]);
+        }
+        return { rowValues };
+    },
+    capabilities: {},
+    outputType: numericOutput,
+    parameters: {
+        subject: 'column-or-field',
+        list: [
+            { types: ['number'] },
+            { types: ['number'], ui: { label: 'Buckets' } },
+            { types: ['text'], optional: true, ui: { label: 'Direction' } },
+        ],
+    },
+    resultType: 'number',
+    docs: {
+        description: "Returns which q-quantile bucket each row falls into for the given numeric column (1…q). Common values: 4 (quartiles), 5 (quintiles), 10 (deciles), 100 (percentiles). Prefer QUARTILE / PERCENTILE for those fixed cases. Bucket 1 holds the smallest values; pass 'DESC' to make bucket 1 hold the largest. Tied values share the lowest bucket any of them reaches. Optional GROUP_BY partitions the ranking.",
+        signatures: [
+            'QUANT{[numCol], q: number}',
+            "QUANT{[numCol], q: number, 'ASC' | 'DESC'}",
+            'QUANT{[numCol], q: number, GROUP_BY([stringCol])}',
+        ],
+        examples: [
+            'QUANT{[numCol], 4}',
+            'QUANT{[numCol], 5}',
+            'QUANT{[numCol], 10}',
+            'QUANT{[numCol], 100}',
+            "QUANT{[numCol], 10, 'DESC'}",
+            'QUANT{[numCol], 4, GROUP_BY([stringCol])}',
+        ],
+        category: 'aggregation',
+    },
+};
+// --- system operator list ----------------------------------------------------------
+/**
+ * The operators shipped with the language. The registry / catalogue over
+ * them (system + custom) is built by `catalogue.ts`.
+ */
+export const SYSTEM_OPERATORS = [
+    SUM_OPERATOR,
+    AVG_OPERATOR,
+    extremumReducer('MIN'),
+    extremumReducer('MAX'),
+    COUNT_OPERATOR,
+    PRODUCT_OPERATOR,
+    MEDIAN_OPERATOR,
+    MODE_OPERATOR,
+    DISTINCT_OPERATOR,
+    ONLY_OPERATOR,
+    STD_DEVIATION_OPERATOR,
+    PERCENTAGE_OPERATOR,
+    FIRST_OPERATOR,
+    LAST_OPERATOR,
+    LAG_OPERATOR,
+    LEAD_OPERATOR,
+    RANK_OPERATOR,
+    QUANT_OPERATOR,
+];
+//# sourceMappingURL=operators.js.map