rowpipe 2.0.0 → 2.1.0

package/dist/planner/executor.js

@@ -0,0 +1,86 @@
+import { reduceRows } from "../analytics/reduce.js";
+import { createPipeline } from "../core/pipeline.js";
+import { castColumns } from "../transforms/cast.js";
+import { filterRows } from "../transforms/filter.js";
+import { limitRows } from "../transforms/limit.js";
+import { mapRows } from "../transforms/map.js";
+import { offsetRows } from "../transforms/offset.js";
+import { renameColumns } from "../transforms/rename.js";
+import { selectColumns } from "../transforms/select.js";
+import { sortRows } from "../transforms/sort/index.js";
+import { tailRows } from "../transforms/tail.js";
+import { topRows } from "../transforms/top.js";
+import { uniqueRows } from "../transforms/unique.js";
+/**
+ * Builds and executes a Pipeline from an optimized PlannedPipeline.
+ */
+export function executePlannedPipeline(source, plan, readerOptions) {
+    const mergedReaderOpts = {
+        ...readerOptions,
+        maxRows: plan.effectiveReadLimit,
+    };
+    const pipeline = createPipeline(source, mergedReaderOpts);
+    for (const op of plan.operations) {
+        switch (op.type) {
+            case "filter":
+                pipeline.pipe(filterRows(op.expression));
+                break;
+            case "select":
+                pipeline.pipe(selectColumns(op.columns));
+                break;
+            case "rename":
+                pipeline.pipe(renameColumns(op.specs));
+                break;
+            case "cast":
+                pipeline.pipe(castColumns(op.specs, { onError: op.onError }));
+                break;
+            case "map":
+                pipeline.pipe(mapRows(op.specs));
+                break;
+            case "sort":
+                pipeline.pipe(sortRows({
+                    by: op.specs,
+                    nulls: op.nulls,
+                    ignoreCase: op.ignoreCase,
+                    natural: op.natural,
+                    memoryLimit: op.memoryLimit,
+                }));
+                break;
+            case "top":
+                pipeline.pipe(topRows({
+                    by: op.specs,
+                    count: op.count,
+                    order: op.order,
+                    smallest: op.smallest,
+                    nulls: op.nulls,
+                    ignoreCase: op.ignoreCase,
+                    natural: op.natural,
+                }));
+                break;
+            case "limit":
+                pipeline.pipe(limitRows(op.count));
+                break;
+            case "offset":
+                pipeline.pipe(offsetRows(op.count));
+                break;
+            case "tail":
+                pipeline.pipe(tailRows(op.count));
+                break;
+            case "unique":
+                pipeline.pipe(uniqueRows({
+                    by: op.by,
+                    keep: op.keep,
+                    memoryLimit: op.memoryLimit,
+                }));
+                break;
+            case "group":
+                pipeline.pipe(reduceRows({
+                    by: op.by,
+                    aggregations: op.aggregations,
+                }));
+                break;
+        }
+    }
+    return pipeline;
+}
+//# sourceMappingURL=executor.js.map

package/dist/planner/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/planner/executor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAY,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAGrD;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAkC,EAClC,IAAqB,EACrB,aAA6B;IAE7B,MAAM,gBAAgB,GAAkB;QACtC,GAAG,aAAa;QAChB,OAAO,EAAE,IAAI,CAAC,kBAAkB;KACjC,CAAC;IAEF,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAE1D,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACjC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;YAChB,KAAK,QAAQ;gBACX,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;gBACzC,MAAM;YAER,KAAK,QAAQ;gBACX,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;gBACzC,MAAM;YAER,KAAK,QAAQ;gBACX,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;gBACvC,MAAM;YAER,KAAK,MAAM;gBACT,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,OAAc,EAAE,CAAC,CAAC,CAAC;gBACrE,MAAM;YAER,KAAK,KAAK;gBACR,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;gBACjC,MAAM;YAER,KAAK,MAAM;gBACT,QAAQ,CAAC,IAAI,CACX,QAAQ,CAAC;oBACP,EAAE,EAAE,EAAE,CAAC,KAAK;oBACZ,KAAK,EAAE,EAAE,CAAC,KAAK;oBACf,UAAU,EAAE,EAAE,CAAC,UAAU;oBACzB,OAAO,EAAE,EAAE,CAAC,OAAO;oBACnB,WAAW,EAAE,EAAE,CAAC,WAAW;iBAC5B,CAAC,CACH,CAAC;gBACF,MAAM;YAER,KAAK,KAAK;gBACR,QAAQ,CAAC,IAAI,CACX,OAAO,CAAC;oBACN,EAAE,EAAE,EAAE,CAAC,KAAK;oBACZ,KAAK,EAAE,EAAE,CAAC,KAAK;oBACf,KAAK,EAAE,EAAE,CAAC,KAAK;oBACf,QAAQ,EAAE,EAAE,CAAC,QAAQ;oBACrB,KAAK,EAAE,EAAE,CAAC,KAAK;oBACf,UAAU,EAAE,EAAE,CAAC,UAAU;oBACzB,OAAO,EAAE,EAAE,CAAC,OAAO;iBACpB,CAAC,CACH,CAAC;gBACF,MAAM;YAER,KAAK,OAAO;gBACV,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;gBACnC,MAAM;YAER,KAAK,QAAQ;gBACX,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;gBACpC,MAAM;YAER,KAAK,MAAM;gBACT,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;gBAClC,MAAM;YAER,KAAK,QAAQ;gBACX,QAAQ,CAAC,IAAI,CACX,UAAU,CAAC;oBACT,EAAE,EAAE,EAAE,CAAC,EAAE;oBACT,IAAI,EAAE,EAAE,CAAC,IAAI;oBACb,WAAW,EAAE,EAAE,CAAC,WAAW;iBAC5B,CAAC,CACH,CAAC;gBACF,MAAM;YAER,KAAK,OAAO;gBACV,QAAQ,CAAC,IAAI,CACX,UAAU,CAAC;oBACT,EAAE,EAAE,EAAE,CAAC,EAAE;oBACT,YAAY,EAAE,EAAE,CAAC,YAAY;iBAC9B,CAAC,CACH,CAAC;gBACF,MAAM;QACV,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/planner/explain.d.ts

@@ -0,0 +1,6 @@
+import { PlannedPipeline } from "./types.js";
+/**
+ * Formats a clean ASCII representation of the planned execution pipeline.
+ */
+export declare function formatExecutionPlan(plan: PlannedPipeline, inputDescription?: string, outputDescription?: string): string;
+//# sourceMappingURL=explain.d.ts.map

package/dist/planner/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../src/planner/explain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,eAAe,EACrB,gBAAgB,SAAiB,EACjC,iBAAiB,SAAkB,GAClC,MAAM,CAuGR"}

package/dist/planner/explain.js

@@ -0,0 +1,91 @@
+/**
+ * Formats a clean ASCII representation of the planned execution pipeline.
+ */
+export function formatExecutionPlan(plan, inputDescription = "Input Stream", outputDescription = "Output Stream") {
+    const steps = [inputDescription];
+    for (const op of plan.operations) {
+        switch (op.type) {
+            case "filter":
+                steps.push(`Filter (${op.expression})`);
+                break;
+            case "select":
+                steps.push(`Select (${op.columns.join(", ")})`);
+                break;
+            case "rename":
+                const renames = Object.entries(op.specs).map(([o, n]) => `${o}->${n}`).join(", ");
+                steps.push(`Rename (${renames})`);
+                break;
+            case "cast":
+                const casts = Object.entries(op.specs).map(([c, t]) => `${c}:${t}`).join(", ");
+                steps.push(`Cast (${casts})`);
+                break;
+            case "map":
+                const maps = Object.entries(op.specs).map(([k, v]) => `${k}=${v}`).join(", ");
+                steps.push(`Map (${maps})`);
+                break;
+            case "sort":
+                const sorts = op.specs.map((s) => `${s.column} ${(s.direction || "asc").toUpperCase()}`).join(", ");
+                steps.push(`ExternalSort (${sorts}) [Spillable]`);
+                break;
+            case "top":
+                const topCols = op.specs.map((s) => `${s.column} ${(s.direction || (op.order === "asc" ? "ASC" : "DESC")).toUpperCase()}`).join(", ");
+                steps.push(`TopK (${topCols}, ${op.count}) [Bounded Heap]`);
+                break;
+            case "limit":
+                steps.push(`Limit (${op.count}) [Early Stream Termination]`);
+                break;
+            case "offset":
+                steps.push(`Offset (skip ${op.count})`);
+                break;
+            case "tail":
+                steps.push(`Tail (last ${op.count}) [Bounded RingBuffer]`);
+                break;
+            case "unique":
+                const byStr = op.by ? op.by.join(", ") : "whole row";
+                steps.push(`Unique (by: ${byStr}, keep: ${op.keep || "first"}) [Spillable]`);
+                break;
+            case "group":
+                const gByStr = op.by ? op.by.join(", ") : "global";
+                const aggsStr = op.aggregations.map((a) => `${a.targetField}=${a.func}(${a.sourceExpr || ""})`).join(", ");
+                steps.push(`Group (by: ${gByStr}, aggs: ${aggsStr}) [Spillable]`);
+                break;
+        }
+    }
+    steps.push(outputDescription);
+    let output = "\n======================================================\n";
+    output += "              Rowpipe Execution Plan                  \n";
+    output += "======================================================\n\n";
+    for (let i = 0; i < steps.length; i++) {
+        output += `  ${steps[i]}\n`;
+        if (i < steps.length - 1) {
+            output += "    ↓\n";
+        }
+    }
+    output += "\n------------------------------------------------------\n";
+    if (plan.optimizationsApplied.length > 0) {
+        output += "Optimizations Applied:\n";
+        for (const opt of plan.optimizationsApplied) {
+            output += `  • ${opt}\n`;
+        }
+    }
+    else {
+        output += "Optimizations Applied:\n  (none)\n";
+    }
+    output += "------------------------------------------------------\n";
+    output += "Memory Classification:\n";
+    if (plan.memoryClassification === "streaming") {
+        output += "  Fully Streaming (O(1) constant memory)\n";
+    }
+    else if (plan.memoryClassification === "bounded-state") {
+        output += "  Bounded State (O(K) fixed memory bound)\n";
+    }
+    else {
+        output += "  Spillable Global State (O(1) RAM threshold + Disk Spill)\n";
+    }
+    if (plan.effectiveReadLimit !== undefined) {
+        output += `Upstream Read Cap: ${plan.effectiveReadLimit} rows\n`;
+    }
+    output += "======================================================\n\n";
+    return output;
+}
+//# sourceMappingURL=explain.js.map

package/dist/planner/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../src/planner/explain.ts"],"names":[],"mappings":"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"}

package/dist/planner/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./optimizer.js";
+export * from "./executor.js";
+export * from "./explain.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/planner/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/planner/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/dist/planner/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./optimizer.js";
+export * from "./executor.js";
+export * from "./explain.js";
+//# sourceMappingURL=index.js.map

package/dist/planner/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/planner/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/dist/planner/optimizer.d.ts

@@ -0,0 +1,9 @@
+import { PipelineOperation, PlannedPipeline } from "./types.js";
+/**
+ * Optimizes an operations sequence with rule-based transformations:
+ * 1. Sort + Limit -> TopK rewrite (converting O(N log N) external sort to O(K) heap)
+ * 2. Offset + Limit bound calculation for early upstream cancellation
+ * 3. Memory classification assessment
+ */
+export declare function optimizePipeline(operations: PipelineOperation[]): PlannedPipeline;
+//# sourceMappingURL=optimizer.d.ts.map

package/dist/planner/optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../../src/planner/optimizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,iBAAiB,EACjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,iBAAiB,EAAE,GAAG,eAAe,CAgFjF"}

package/dist/planner/optimizer.js

@@ -0,0 +1,78 @@
+/**
+ * Optimizes an operations sequence with rule-based transformations:
+ * 1. Sort + Limit -> TopK rewrite (converting O(N log N) external sort to O(K) heap)
+ * 2. Offset + Limit bound calculation for early upstream cancellation
+ * 3. Memory classification assessment
+ */
+export function optimizePipeline(operations) {
+    const optimized = [];
+    const optimizationsApplied = [];
+    let i = 0;
+    while (i < operations.length) {
+        const current = operations[i];
+        const nextOp = operations[i + 1];
+        // Optimization Rule 1: Sort + Limit -> TopK
+        if (current.type === "sort" && nextOp && nextOp.type === "limit") {
+            const primarySpec = current.specs[0];
+            const isDesc = primarySpec ? primarySpec.direction === "desc" : false;
+            optimized.push({
+                type: "top",
+                specs: current.specs,
+                count: nextOp.count,
+                order: isDesc ? "desc" : "asc",
+                smallest: !isDesc,
+                nulls: current.nulls,
+                ignoreCase: current.ignoreCase,
+                natural: current.natural,
+            });
+            const sortSummary = current.specs.map((s) => `${s.column} ${s.direction || "asc"}`).join(", ");
+            optimizationsApplied.push(`sort(${sortSummary}) + limit(${nextOp.count}) -> top-k (${nextOp.count})`);
+            i += 2;
+            continue;
+        }
+        optimized.push(current);
+        i++;
+    }
+    // Calculate upstream cancellation limit
+    let effectiveReadLimit;
+    let offsetAmount = 0;
+    let hasOffset = false;
+    for (const op of optimized) {
+        if (op.type === "offset") {
+            offsetAmount += op.count;
+            hasOffset = true;
+        }
+        else if (op.type === "limit") {
+            const totalNeeded = (hasOffset ? offsetAmount : 0) + op.count;
+            effectiveReadLimit = effectiveReadLimit !== undefined ? Math.min(effectiveReadLimit, totalNeeded) : totalNeeded;
+        }
+        else if (op.type === "sort" || op.type === "tail" || op.type === "group") {
+            // Global operations need all rows, cannot stop early before them
+            effectiveReadLimit = undefined;
+            break;
+        }
+    }
+    if (hasOffset && effectiveReadLimit !== undefined) {
+        optimizationsApplied.push(`offset(${offsetAmount}) + limit -> upstream stream capped at ${effectiveReadLimit} rows`);
+    }
+    // Assess memory classification
+    let memoryClassification = "streaming";
+    for (const op of optimized) {
+        if (op.type === "sort" || op.type === "unique" || op.type === "group") {
+            memoryClassification = "spillable-global";
+            break;
+        }
+        if (op.type === "top" || op.type === "tail") {
+            if (memoryClassification === "streaming") {
+                memoryClassification = "bounded-state";
+            }
+        }
+    }
+    return {
+        operations: optimized,
+        optimizationsApplied,
+        memoryClassification,
+        effectiveReadLimit,
+    };
+}
+//# sourceMappingURL=optimizer.js.map

package/dist/planner/optimizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimizer.js","sourceRoot":"","sources":["../../src/planner/optimizer.ts"],"names":[],"mappings":"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"}

package/dist/planner/types.d.ts

@@ -0,0 +1,63 @@
+import type { AggregationSpec } from "../analytics/reduce.js";
+import type { SortKeySpec } from "../transforms/sort/comparator.js";
+export type MemoryClassification = "streaming" | "bounded-state" | "spillable-global";
+export type PipelineOperation = {
+    type: "filter";
+    expression: string;
+} | {
+    type: "select";
+    columns: string[];
+} | {
+    type: "rename";
+    specs: Record<string, string>;
+} | {
+    type: "cast";
+    specs: Record<string, string>;
+    onError?: string;
+} | {
+    type: "map";
+    specs: Record<string, string>;
+} | {
+    type: "sort";
+    specs: SortKeySpec[];
+    nulls?: "first" | "last";
+    ignoreCase?: boolean;
+    natural?: boolean;
+    memoryLimit?: number | string;
+} | {
+    type: "top";
+    specs: SortKeySpec[];
+    count: number;
+    order?: "asc" | "desc";
+    smallest?: boolean;
+    nulls?: "first" | "last";
+    ignoreCase?: boolean;
+    natural?: boolean;
+} | {
+    type: "limit";
+    count: number;
+} | {
+    type: "offset";
+    count: number;
+} | {
+    type: "tail";
+    count: number;
+} | {
+    type: "unique";
+    by?: string[];
+    keep?: "first" | "last";
+    approx?: boolean;
+    memoryLimit?: number | string;
+} | {
+    type: "group";
+    by?: string[];
+    aggregations: AggregationSpec[];
+    memoryLimit?: number | string;
+};
+export interface PlannedPipeline {
+    operations: PipelineOperation[];
+    optimizationsApplied: string[];
+    memoryClassification: MemoryClassification;
+    effectiveReadLimit?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/planner/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/planner/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEpE,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,eAAe,GACf,kBAAkB,CAAC;AAEvB,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC9C;IACE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B,GACD;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IACd,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B,CAAC;AAEN,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B"}

package/dist/planner/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/planner/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/planner/types.ts"],"names":[],"mappings":""}

package/dist/transforms/count.d.ts

@@ -0,0 +1,21 @@
+import type { DataStream } from "../core/types.js";
+export interface CountOptions {
+    by?: string | string[];
+    distinct?: string;
+    approx?: boolean;
+    json?: boolean;
+}
+export interface CountResult {
+    totalRows: number;
+    distinctCount?: number;
+    isApproximate?: boolean;
+    groups?: Array<{
+        key: Record<string, unknown>;
+        count: number;
+    }>;
+}
+/**
+ * Executes high-performance streaming count analysis over DataStream.
+ */
+export declare function countStream(stream: DataStream, options?: CountOptions): Promise<CountResult>;
+//# sourceMappingURL=count.d.ts.map

package/dist/transforms/count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"count.d.ts","sourceRoot":"","sources":["../../src/transforms/count.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAO,MAAM,kBAAkB,CAAC;AAKxD,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjE;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CA+DtB"}

package/dist/transforms/count.js

@@ -0,0 +1,65 @@
+import { HyperLogLog } from "../analytics/stats.js";
+import { encodeCompositeKey } from "../diff/key.js";
+/**
+ * Executes high-performance streaming count analysis over DataStream.
+ */
+export async function countStream(stream, options = {}) {
+    const byCols = options.by
+        ? (Array.isArray(options.by) ? options.by : options.by.split(",").map((s) => s.trim()).filter(Boolean))
+        : undefined;
+    let totalRows = 0;
+    const distinctCol = options.distinct;
+    const useApprox = options.approx ?? false;
+    const hll = distinctCol && useApprox ? new HyperLogLog(12) : null;
+    const exactDistinctSet = distinctCol && !useApprox ? new Set() : null;
+    const groupCounts = byCols ? new Map() : null;
+    for await (const batch of stream) {
+        totalRows += batch.rows.length;
+        if (distinctCol) {
+            for (let i = 0; i < batch.rows.length; i++) {
+                const val = batch.rows[i][distinctCol];
+                if (val !== null && val !== undefined) {
+                    if (hll) {
+                        hll.add(val);
+                    }
+                    else if (exactDistinctSet) {
+                        exactDistinctSet.add(String(val));
+                    }
+                }
+            }
+        }
+        if (byCols && groupCounts) {
+            for (let i = 0; i < batch.rows.length; i++) {
+                const row = batch.rows[i];
+                const { encoded, rawKey } = encodeCompositeKey(row, byCols);
+                const existing = groupCounts.get(encoded);
+                if (existing) {
+                    existing.count++;
+                }
+                else {
+                    groupCounts.set(encoded, { key: rawKey, count: 1 });
+                }
+            }
+        }
+    }
+    let distinctCount;
+    if (distinctCol) {
+        if (hll) {
+            distinctCount = hll.count();
+        }
+        else if (exactDistinctSet) {
+            distinctCount = exactDistinctSet.size;
+        }
+    }
+    let groups;
+    if (groupCounts) {
+        groups = Array.from(groupCounts.values()).sort((a, b) => b.count - a.count);
+    }
+    return {
+        totalRows,
+        distinctCount,
+        isApproximate: useApprox && Boolean(distinctCol),
+        groups,
+    };
+}
+//# sourceMappingURL=count.js.map

package/dist/transforms/count.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"count.js","sourceRoot":"","sources":["../../src/transforms/count.ts"],"names":[],"mappings":"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"}

package/dist/transforms/group.d.ts

@@ -0,0 +1,25 @@
+import { AggregationSpec } from "../analytics/reduce.js";
+import type { TransformFunction } from "../core/types.js";
+export interface GroupOptions {
+    by?: string | string[];
+    count?: boolean;
+    sum?: string | string[];
+    avg?: string | string[];
+    min?: string | string[];
+    max?: string | string[];
+    first?: string | string[];
+    last?: string | string[];
+    agg?: string | string[];
+    memoryLimit?: number | string;
+    tempDir?: string;
+    batchSize?: number;
+}
+/**
+ * Builds reduce specifications from group flags and explicit specs.
+ */
+export declare function buildGroupReduceSpecs(options: GroupOptions): AggregationSpec[];
+/**
+ * Groups and aggregates tabular stream with streaming single-pass accumulation.
+ */
+export declare function groupRows(options?: GroupOptions): TransformFunction;
+//# sourceMappingURL=group.d.ts.map

package/dist/transforms/group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/transforms/group.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACvF,OAAO,KAAK,EAA8B,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEtF,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,eAAe,EAAE,CAuC9E;AAkBD;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,YAAiB,GAAG,iBAAiB,CAWvE"}

package/dist/transforms/group.js

@@ -0,0 +1,71 @@
+import { parseReduceSpecs, reduceRows } from "../analytics/reduce.js";
+/**
+ * Builds reduce specifications from group flags and explicit specs.
+ */
+export function buildGroupReduceSpecs(options) {
+    const rawSpecs = [];
+    if (options.count) {
+        rawSpecs.push("count=count()");
+    }
+    const addFieldAggs = (func, fields, suffix) => {
+        if (!fields)
+            return;
+        const list = Array.isArray(fields) ? fields : fields.split(",").map((s) => s.trim()).filter(Boolean);
+        for (const f of list) {
+            const alias = suffix ? `${f}_${suffix}` : `${f}_${func}`;
+            rawSpecs.push(`${alias}=${func}(${f})`);
+        }
+    };
+    addFieldAggs("sum", options.sum, "sum");
+    addFieldAggs("avg", options.avg, "avg");
+    addFieldAggs("min", options.min, "min");
+    addFieldAggs("max", options.max, "max");
+    addFieldAggs("first", options.first, "first");
+    addFieldAggs("last", options.last, "last");
+    if (options.agg) {
+        if (Array.isArray(options.agg)) {
+            for (const a of options.agg) {
+                rawSpecs.push(...parseRawAggStrings(a));
+            }
+        }
+        else {
+            rawSpecs.push(...parseRawAggStrings(options.agg));
+        }
+    }
+    if (rawSpecs.length === 0) {
+        // Default to count() if grouped without explicit aggregations
+        rawSpecs.push("count=count()");
+    }
+    return parseReduceSpecs(rawSpecs);
+}
+function parseRawAggStrings(input) {
+    const parts = input.split(",").map((s) => s.trim()).filter(Boolean);
+    return parts.map((p) => {
+        if (p.includes("="))
+            return p;
+        // Auto-generate alias: sum(revenue) -> revenue_sum=sum(revenue), count() -> count=count()
+        const match = /^([a-zA-Z0-9_]+)\((.*)\)$/.exec(p);
+        if (match) {
+            const fn = match[1];
+            const col = match[2]?.trim();
+            if (!col)
+                return `${fn}=${p}`;
+            return `${col}_${fn}=${p}`;
+        }
+        return p;
+    });
+}
+/**
+ * Groups and aggregates tabular stream with streaming single-pass accumulation.
+ */
+export function groupRows(options = {}) {
+    const byCols = options.by
+        ? (Array.isArray(options.by) ? options.by : options.by.split(",").map((s) => s.trim()).filter(Boolean))
+        : undefined;
+    const aggregations = buildGroupReduceSpecs(options);
+    return reduceRows({
+        by: byCols,
+        aggregations,
+    });
+}
+//# sourceMappingURL=group.js.map

package/dist/transforms/group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.js","sourceRoot":"","sources":["../../src/transforms/group.ts"],"names":[],"mappings":"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"}

package/dist/transforms/limit.d.ts

@@ -0,0 +1,7 @@
+import type { TransformFunction } from "../core/types.js";
+/**
+ * Limits the number of rows emitted to `maxCount` and cancels the upstream stream immediately.
+ * Zero memory overhead ($O(1)$) and true early cancellation.
+ */
+export declare function limitRows(maxCount: number): TransformFunction;
+//# sourceMappingURL=limit.d.ts.map

package/dist/transforms/limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limit.d.ts","sourceRoot":"","sources":["../../src/transforms/limit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8B,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEtF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAqC7D"}