@c9up/atom 0.1.13 → 0.1.14

package/src/index.ts

@@ -4,6 +4,8 @@
  * pure TypeScript BigInt fallback for unsupported platforms.
  */
 
+export type { BulkDivOptions, BulkStddevOptions } from "./bulk.js";
+export { Bulk, BulkColumn, BulkScalar, bulk } from "./bulk.js";
 export type { AtomContext, AtomContextOptions } from "./context.js";
 export {
 	configureAtomContext,
@@ -34,6 +36,7 @@ export type {
 export { Money, money } from "./Money.js";
 export { isNativeAvailable } from "./native.js";
 
+import { bulk as bulkFn } from "./bulk.js";
 import { defaultPrecision, defaultRoundMode } from "./context.js";
 import type { MedianOptions, StddevOptions } from "./Decimal.js";
 import { Decimal, type DecimalInput } from "./Decimal.js";
@@ -82,21 +85,28 @@ function resolveValues(args: readonly unknown[]): Iterable<DecimalInput> {
 	return args.map(toDecimalValue);
 }
 
+/**
+ * Exact sum — through the engine's BATCH entry point, not a fold.
+ *
+ * The result is identical either way; the cost is not. Every `plus` from
+ * JavaScript serialises both operands, crosses into the native engine and
+ * comes back with a string, and that crossing is where the time goes — around
+ * a microsecond an operation, against nanoseconds for the arithmetic itself.
+ * `Decimal.sum` hands the whole list over once, so summing a column of a
+ * hundred thousand figures costs one crossing rather than a hundred thousand.
+ *
+ * Nothing changed for callers: this is what `Atom.sum` always meant.
+ */
 function sumImpl(values: Iterable<DecimalInput>): Decimal {
-	let total = Decimal.zero();
-	for (const value of values) {
-		total = total.plus(value);
-	}
-	return total;
+	return Decimal.sum(values);
 }
 
 function avgImpl(values: Iterable<DecimalInput>): Decimal {
-	let total = Decimal.zero();
-	let count = 0;
-	for (const value of values) {
-		total = total.plus(value);
-		count++;
-	}
+	// Materialised so the count and the batch see the same values: an iterable
+	// consumed by one is not there for the other.
+	const list = [...values];
+	const total = Decimal.sum(list);
+	const count = list.length;
 	if (count === 0) {
 		throw new Error("Atom.avg requires at least one value");
 	}
@@ -183,11 +193,10 @@ function stddevImpl(
 		throw new Error("Atom.stddev sample mode requires at least two values");
 	}
 	const mean = avgImpl(list);
-	let sumSquares = Decimal.zero();
-	for (const value of list) {
-		const diff = value.minus(mean);
-		sumSquares = sumSquares.plus(diff.times(diff));
-	}
+	// `Σ diff²` is a dot product of the deviations with themselves: one
+	// crossing, where the fold made two per value — a multiply and an add.
+	const deviations = list.map((value) => value.minus(mean));
+	const sumSquares = Decimal.dot(deviations, deviations);
 	const variance = sumSquares.div(String(divisor), {
 		precision: precision + 8,
 	});
@@ -278,6 +287,15 @@ function stddevFn(
 export const Atom = {
 	/** Construct a `Decimal` from a string / number / bigint / Decimal. Alias for `Decimal.from`. */
 	decimal,
+	/**
+	 * Plan a computation and run it in one crossing.
+	 *
+	 * For chains of dependent operations — a schedule, a rate solver, a
+	 * statistic over a column — where the cost is the boundary rather than the
+	 * arithmetic. Not for a lone sum: below about three operations per element a
+	 * plain loop wins.
+	 */
+	bulk: bulkFn,
 	/** Exact sum of N values. Empty input → `Decimal('0')`. */
 	sum: sumFn,
 	/** Arithmetic mean of N values. Throws on empty input. */

package/src/native/generated.ts

@@ -4,6 +4,25 @@
 // output. Editing this file by hand puts it back where it started: a
 // description that can disagree with the code it describes.
 
+/**
+ * Run a bulk program over a resident column buffer.
+ *
+ * `values` holds every column laid end to end, `rows` values each, followed by
+ * the scalar literals the program refers to by absolute index. `program` is
+ * six-word bytecode. Returns the scalars the program emitted, in order.
+ *
+ * An overflow of the 128-bit working width is reported with a message opening
+ * `[ATOM_BULK_OVERFLOW]`, which is the caller's signal to re-run the same
+ * program on the BigInt executor rather than to give up: the fast path is
+ * allowed to be too narrow, never to be wrong.
+ */
+
+export declare function runBulk(
+	values: BigInt64Array,
+	rows: number,
+	program: Int32Array,
+): Array<string>;
+
 export declare function add(a: string, b: string): string;
 
 export declare function sub(a: string, b: string): string;
@@ -18,4 +37,18 @@ export declare function pow(a: string, exp: number, precision: number): string;
 
 export declare function sqrt(a: string, precision: number): string;
 
+/**
+ * Batch addition — one crossing for the whole list.
+ *
+ * `Vec<String>` rather than a stream of calls, because the crossing IS the
+ * cost: parsing and formatting a decimal is cheap, and doing it once per
+ * pair from JavaScript is what makes a long fold expensive.
+ */
+
+export declare function sum(values: Array<string>): string;
+
+/** Batch `Σ aᵢ·bᵢ` — the shape of every valuation, in one crossing. */
+
+export declare function dot(a: Array<string>, b: Array<string>): string;
+
 export declare function cmp(a: string, b: string): number;

package/wasm/atom_engine_wasm.d.ts

@@ -7,16 +7,37 @@ export function cmp(a: string, b: string): number;
 
 export function div(a: string, b: string, precision: number): string;
 
+export function dot(a: string[], b: string[]): string;
+
 export function mul(a: string, b: string): string;
 
 export function pow(a: string, exp: number, precision: number): string;
 
 export function rem(a: string, b: string): string;
 
+/**
+ * Run a bulk program over a resident column buffer.
+ *
+ * Held to the same shape as the N-API build so the two engines cannot quietly
+ * diverge — the browser has to export what Node does. `Vec<i64>` and `Vec<i32>`
+ * cross as `BigInt64Array` and `Int32Array`, which is what the compiler in
+ * TypeScript produces anyway.
+ */
+export function runBulk(values: BigInt64Array, rows: number, program: Int32Array): string[];
+
 export function sqrt(a: string, precision: number): string;
 
 export function sub(a: string, b: string): string;
 
+/**
+ * The batch pair, held to the same shape as the NAPI build so the two
+ * engines cannot quietly diverge — the browser has to export what Node does.
+ *
+ * `Vec<String>` crosses the wasm boundary as a JS array of strings, which is
+ * exactly what the facade holds anyway.
+ */
+export function sum(values: string[]): string;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
@@ -24,16 +45,21 @@ export interface InitOutput {
     readonly add: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly cmp: (a: number, b: number, c: number, d: number) => [number, number, number];
     readonly div: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+    readonly dot: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly mul: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly pow: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly rem: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly runBulk: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly sqrt: (a: number, b: number, c: number) => [number, number, number, number];
     readonly sub: (a: number, b: number, c: number, d: number) => [number, number, number, number];
-    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly sum: (a: number, b: number) => [number, number, number, number];
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __externref_table_dealloc: (a: number) => void;
     readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __externref_drop_slice: (a: number, b: number) => void;
     readonly __wbindgen_start: () => void;
 }
 

package/wasm/atom_engine_wasm.js

@@ -74,6 +74,34 @@ export function div(a, b, precision) {
     }
 }
 
+/**
+ * @param {string[]} a
+ * @param {string[]} b
+ * @returns {string}
+ */
+export function dot(a, b) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const ptr0 = passArrayJsValueToWasm0(a, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passArrayJsValueToWasm0(b, wasm.__wbindgen_malloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.dot(ptr0, len0, ptr1, len1);
+        var ptr3 = ret[0];
+        var len3 = ret[1];
+        if (ret[3]) {
+            ptr3 = 0; len3 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
+    }
+}
+
 /**
  * @param {string} a
  * @param {string} b
@@ -157,6 +185,32 @@ export function rem(a, b) {
     }
 }
 
+/**
+ * Run a bulk program over a resident column buffer.
+ *
+ * Held to the same shape as the N-API build so the two engines cannot quietly
+ * diverge — the browser has to export what Node does. `Vec<i64>` and `Vec<i32>`
+ * cross as `BigInt64Array` and `Int32Array`, which is what the compiler in
+ * TypeScript produces anyway.
+ * @param {BigInt64Array} values
+ * @param {number} rows
+ * @param {Int32Array} program
+ * @returns {string[]}
+ */
+export function runBulk(values, rows, program) {
+    const ptr0 = passArray64ToWasm0(values, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passArray32ToWasm0(program, wasm.__wbindgen_malloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.runBulk(ptr0, len0, rows, ptr1, len1);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v3 = getArrayJsValueFromWasm0(ret[0], ret[1]);
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v3;
+}
+
 /**
  * @param {string} a
  * @param {number} precision
@@ -210,9 +264,50 @@ export function sub(a, b) {
         wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
     }
 }
+
+/**
+ * The batch pair, held to the same shape as the NAPI build so the two
+ * engines cannot quietly diverge — the browser has to export what Node does.
+ *
+ * `Vec<String>` crosses the wasm boundary as a JS array of strings, which is
+ * exactly what the facade holds anyway.
+ * @param {string[]} values
+ * @returns {string}
+ */
+export function sum(values) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passArrayJsValueToWasm0(values, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.sum(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
+        __wbg___wbindgen_string_get_d154f1e671052120: function(arg0, arg1) {
+            const obj = arg1;
+            const ret = typeof(obj) === 'string' ? obj : undefined;
+            var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            var len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        },
+        __wbg___wbindgen_throw_bb96b2010945f0bc: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
@@ -234,10 +329,51 @@ function __wbg_get_imports() {
     };
 }
 
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
+function getArrayJsValueFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    const mem = getDataViewMemory0();
+    const result = [];
+    for (let i = ptr; i < ptr + 4 * len; i += 4) {
+        result.push(wasm.__wbindgen_externrefs.get(mem.getUint32(i, true)));
+    }
+    wasm.__externref_drop_slice(ptr, len);
+    return result;
+}
+
+let cachedBigUint64ArrayMemory0 = null;
+function getBigUint64ArrayMemory0() {
+    if (cachedBigUint64ArrayMemory0 === null || cachedBigUint64ArrayMemory0.byteLength === 0) {
+        cachedBigUint64ArrayMemory0 = new BigUint64Array(wasm.memory.buffer);
+    }
+    return cachedBigUint64ArrayMemory0;
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
 function getStringFromWasm0(ptr, len) {
     return decodeText(ptr >>> 0, len);
 }
 
+let cachedUint32ArrayMemory0 = null;
+function getUint32ArrayMemory0() {
+    if (cachedUint32ArrayMemory0 === null || cachedUint32ArrayMemory0.byteLength === 0) {
+        cachedUint32ArrayMemory0 = new Uint32Array(wasm.memory.buffer);
+    }
+    return cachedUint32ArrayMemory0;
+}
+
 let cachedUint8ArrayMemory0 = null;
 function getUint8ArrayMemory0() {
     if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
@@ -246,6 +382,34 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passArray32ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 4, 4) >>> 0;
+    getUint32ArrayMemory0().set(arg, ptr / 4);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
+function passArray64ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 8, 8) >>> 0;
+    getBigUint64ArrayMemory0().set(arg, ptr / 8);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
+function passArrayJsValueToWasm0(array, malloc) {
+    const ptr = malloc(array.length * 4, 4) >>> 0;
+    for (let i = 0; i < array.length; i++) {
+        const add = addToExternrefTable0(array[i]);
+        getDataViewMemory0().setUint32(ptr + 4 * i, add, true);
+    }
+    WASM_VECTOR_LEN = array.length;
+    return ptr;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);
@@ -323,6 +487,9 @@ function __wbg_finalize_init(instance, module) {
     wasmInstance = instance;
     wasm = instance.exports;
     wasmModule = module;
+    cachedBigUint64ArrayMemory0 = null;
+    cachedDataViewMemory0 = null;
+    cachedUint32ArrayMemory0 = null;
     cachedUint8ArrayMemory0 = null;
     wasm.__wbindgen_start();
     return wasm;

package/wasm/atom_engine_wasm_bg.wasm.d.ts

@@ -4,14 +4,19 @@ export const memory: WebAssembly.Memory;
 export const add: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const cmp: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const div: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+export const dot: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const mul: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const pow: (a: number, b: number, c: number, d: number) => [number, number, number, number];
 export const rem: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const runBulk: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
 export const sqrt: (a: number, b: number, c: number) => [number, number, number, number];
 export const sub: (a: number, b: number, c: number, d: number) => [number, number, number, number];
-export const __wbindgen_externrefs: WebAssembly.Table;
+export const sum: (a: number, b: number) => [number, number, number, number];
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
 export const __externref_table_dealloc: (a: number) => void;
 export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __externref_table_alloc: () => number;
+export const __externref_drop_slice: (a: number, b: number) => void;
 export const __wbindgen_start: () => void;