@c9up/atom 0.1.12 → 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

@@ -0,0 +1,86 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export function add(a: string, b: string): string;
+
+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 {
+    readonly memory: WebAssembly.Memory;
+    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 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;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;