@c9up/atom 0.1.6 → 0.1.8

package/src/Money.ts

@@ -0,0 +1,179 @@
+import { defaultQuantizeMode } from "./context.js";
+import { Decimal, type DecimalInput, type RoundMode } from "./Decimal.js";
+
+export interface MoneyOptions {
+	scale?: number;
+	exact?: boolean;
+	mode?: RoundMode;
+}
+
+export interface MoneyFormatOptions
+	extends Omit<Intl.NumberFormatOptions, "style" | "currency"> {
+	locale?: Intl.LocalesArgument;
+}
+
+const ISO_MINOR_UNITS: Record<string, number> = Object.freeze({
+	BHD: 3,
+	CLF: 4,
+	CLP: 0,
+	DJF: 0,
+	EUR: 2,
+	GBP: 2,
+	JPY: 0,
+	KMF: 0,
+	KRW: 0,
+	KWD: 3,
+	LYD: 3,
+	OMR: 3,
+	PYG: 0,
+	TND: 3,
+	USD: 2,
+	VND: 0,
+	XAF: 0,
+	XOF: 0,
+	XPF: 0,
+});
+
+export class Money {
+	#amount: Decimal;
+	#currency: string;
+	#scale: number;
+
+	constructor(
+		amount: DecimalInput,
+		currency: string,
+		options: MoneyOptions = {},
+	) {
+		this.#currency = normalizeCurrency(currency);
+		this.#scale = options.scale ?? ISO_MINOR_UNITS[this.#currency] ?? 2;
+		const mode = options.mode ?? defaultQuantizeMode();
+		const exact = options.exact ?? true;
+		const decimal = new Decimal(amount);
+		this.#amount = exact
+			? Decimal.fromMinorUnits(decimal.toMinorUnits(this.#scale), this.#scale)
+			: decimal.toScale(this.#scale, mode);
+	}
+
+	static fromMajor(
+		amount: DecimalInput,
+		currency: string,
+		options: MoneyOptions = {},
+	): Money {
+		return new Money(amount, currency, options);
+	}
+
+	static fromMinorUnits(
+		minorUnits: string | number | bigint,
+		currency: string,
+		options: Omit<MoneyOptions, "exact"> = {},
+	): Money {
+		const normalized = normalizeCurrency(currency);
+		const scale = options.scale ?? ISO_MINOR_UNITS[normalized] ?? 2;
+		return new Money(Decimal.fromMinorUnits(minorUnits, scale), normalized, {
+			...options,
+			scale,
+			exact: true,
+		});
+	}
+
+	get amount(): Decimal {
+		return this.#amount;
+	}
+
+	get currency(): string {
+		return this.#currency;
+	}
+
+	get scale(): number {
+		return this.#scale;
+	}
+
+	plus(other: Money): Money {
+		this.assertSameCurrency(other);
+		return new Money(this.#amount.plus(other.#amount), this.#currency, {
+			scale: this.#scale,
+		});
+	}
+
+	minus(other: Money): Money {
+		this.assertSameCurrency(other);
+		return new Money(this.#amount.minus(other.#amount), this.#currency, {
+			scale: this.#scale,
+		});
+	}
+
+	times(multiplier: DecimalInput, options: MoneyOptions = {}): Money {
+		return new Money(this.#amount.times(multiplier), this.#currency, {
+			scale: this.#scale,
+			exact: false,
+			mode: options.mode,
+		});
+	}
+
+	div(divisor: DecimalInput, options: MoneyOptions = {}): Money {
+		return new Money(this.#amount.div(divisor), this.#currency, {
+			scale: this.#scale,
+			exact: false,
+			mode: options.mode,
+		});
+	}
+
+	allocate(ratios: Array<string | number | bigint>): Money[] {
+		return this.#amount.allocate(ratios).map(
+			(part) =>
+				new Money(part, this.#currency, {
+					scale: this.#scale,
+				}),
+		);
+	}
+
+	toMinorUnits(): bigint {
+		return this.#amount.toMinorUnits(this.#scale);
+	}
+
+	format(options: MoneyFormatOptions = {}): string {
+		const { locale, ...intlOptions } = options;
+		return this.#amount.toLocale(locale, {
+			style: "currency",
+			currency: this.#currency,
+			minimumFractionDigits: this.#scale,
+			maximumFractionDigits: this.#scale,
+			...intlOptions,
+		});
+	}
+
+	toString(): string {
+		return `${this.#amount.toFixed(this.#scale)} ${this.#currency}`;
+	}
+
+	toJSON(): { amount: string; currency: string } {
+		return {
+			amount: this.#amount.toFixed(this.#scale),
+			currency: this.#currency,
+		};
+	}
+
+	private assertSameCurrency(other: Money): void {
+		if (this.#currency !== other.#currency || this.#scale !== other.#scale) {
+			throw new Error(
+				`Currency mismatch: ${this.#currency}/${this.#scale} !== ${other.#currency}/${other.#scale}`,
+			);
+		}
+	}
+}
+
+export function money(
+	amount: DecimalInput,
+	currency: string,
+	options: MoneyOptions = {},
+): Money {
+	return new Money(amount, currency, options);
+}
+
+function normalizeCurrency(currency: string): string {
+	const normalized = currency.trim().toUpperCase();
+	if (!/^[A-Z]{3}$/.test(normalized)) {
+		throw new Error(`Invalid currency code: ${currency}`);
+	}
+	return normalized;
+}

package/src/atlas.ts

@@ -23,7 +23,29 @@
  * @implements Story 35.10
  */
 
-import { Decimal } from "./Decimal.js";
+import { Decimal, type RoundMode } from "./Decimal.js";
+
+export interface DecimalColumnOptions {
+	scale?: number;
+	exact?: boolean;
+	mode?: RoundMode;
+	nullable?: boolean;
+	columnType?: "decimal" | "numeric";
+}
+
+export interface DecimalAtlasAdapter {
+	consume(raw: unknown): Decimal | null;
+	prepare(value: unknown): string | null;
+}
+
+export interface DecimalAtlasColumn extends DecimalAtlasAdapter {
+	meta: {
+		atomDecimal: true;
+		columnType: "decimal" | "numeric";
+		scale?: number;
+		nullable: boolean;
+	};
+}
 
 /**
  * Atlas adapter for postgres `numeric` / `decimal` (and equivalent on mysql /
@@ -55,7 +77,7 @@ import { Decimal } from "./Decimal.js";
  * plugin cannot monkey-patch `prepare` / `consume` at runtime and silently
  * corrupt every repository sharing this import.
  */
-export const decimalAtlasAdapter = Object.freeze({
+export const decimalAtlasAdapter: DecimalAtlasAdapter = Object.freeze({
 	consume(raw: unknown): Decimal | null {
 		if (raw === null || raw === undefined) return null;
 		if (raw instanceof Decimal) return raw;
@@ -81,3 +103,57 @@ export const decimalAtlasAdapter = Object.freeze({
 		return value.toString();
 	},
 });
+
+export function decimalColumn(
+	options: DecimalColumnOptions = {},
+): DecimalAtlasColumn {
+	const columnType = options.columnType ?? "decimal";
+	const nullable = options.nullable ?? true;
+	const adapter: DecimalAtlasColumn = {
+		meta: {
+			atomDecimal: true,
+			columnType,
+			scale: options.scale,
+			nullable,
+		},
+		consume(raw: unknown): Decimal | null {
+			const value = decimalAtlasAdapter.consume(raw);
+			if (value === null) {
+				if (!nullable) {
+					throw new TypeError(
+						"decimalColumn.consume: non-nullable column got null",
+					);
+				}
+				return null;
+			}
+			return normalizeColumnDecimal(value, options);
+		},
+		prepare(value: unknown): string | null {
+			const prepared = decimalAtlasAdapter.prepare(value);
+			if (prepared === null) {
+				if (!nullable) {
+					throw new TypeError(
+						"decimalColumn.prepare: non-nullable column got null",
+					);
+				}
+				return null;
+			}
+			return normalizeColumnDecimal(new Decimal(prepared), options).toString();
+		},
+	};
+	return Object.freeze(adapter);
+}
+
+function normalizeColumnDecimal(
+	value: Decimal,
+	options: DecimalColumnOptions,
+): Decimal {
+	if (options.scale === undefined) return value;
+	if (options.exact ?? true) {
+		return Decimal.fromMinorUnits(
+			value.toMinorUnits(options.scale),
+			options.scale,
+		);
+	}
+	return value.toScale(options.scale, options.mode ?? "half-up");
+}

package/src/context.ts

@@ -0,0 +1,67 @@
+import type { RoundMode } from "./Decimal.js";
+
+export interface AtomContext {
+	precision: number;
+	roundMode: RoundMode;
+	quantizeMode: RoundMode;
+}
+
+export type AtomContextOptions = Partial<AtomContext>;
+
+const DEFAULT_CONTEXT: AtomContext = Object.freeze({
+	precision: 18,
+	roundMode: "trunc",
+	quantizeMode: "half-up",
+});
+
+let currentContext: AtomContext = DEFAULT_CONTEXT;
+
+export function getAtomContext(): AtomContext {
+	return { ...currentContext };
+}
+
+export function configureAtomContext(options: AtomContextOptions): AtomContext {
+	currentContext = normalizeContext({ ...currentContext, ...options });
+	return getAtomContext();
+}
+
+export function resetAtomContext(): AtomContext {
+	currentContext = DEFAULT_CONTEXT;
+	return getAtomContext();
+}
+
+export function withAtomContext<T>(
+	options: AtomContextOptions,
+	callback: () => T,
+): T {
+	const previous = currentContext;
+	currentContext = normalizeContext({ ...currentContext, ...options });
+	try {
+		return callback();
+	} finally {
+		currentContext = previous;
+	}
+}
+
+export function defaultPrecision(): number {
+	return currentContext.precision;
+}
+
+export function defaultRoundMode(): RoundMode {
+	return currentContext.roundMode;
+}
+
+export function defaultQuantizeMode(): RoundMode {
+	return currentContext.quantizeMode;
+}
+
+function normalizeContext(context: AtomContext): AtomContext {
+	assertContextPrecision(context.precision);
+	return Object.freeze({ ...context });
+}
+
+function assertContextPrecision(precision: number): void {
+	if (!Number.isInteger(precision) || precision < 0 || precision > 10_000) {
+		throw new Error(`Invalid Atom context precision: ${precision}`);
+	}
+}

package/src/index.ts

@@ -1,11 +1,20 @@
 /**
  * @c9up/atom — exact decimal arithmetic.
- * The Rust engine is required (NAPI in Node, WASM in browser) — there is no JS/TS fallback.
+ * The Rust engine is preferred (NAPI in Node, WASM in browser), with a
+ * pure TypeScript BigInt fallback for unsupported platforms.
  */
 
+export type { AtomContext, AtomContextOptions } from "./context.js";
+export {
+	configureAtomContext,
+	getAtomContext,
+	resetAtomContext,
+	withAtomContext,
+} from "./context.js";
 export type {
 	BetweenOptions,
 	DecimalInput,
+	DecimalSafeParseResult,
 	DecimalScaled,
 	DivOptions,
 	MedianOptions,
@@ -17,10 +26,14 @@ export type {
 	ToMinorUnitsOptions,
 } from "./Decimal.js";
 export { Decimal } from "./Decimal.js";
+export type { MoneyFormatOptions, MoneyOptions } from "./Money.js";
+export { Money, money } from "./Money.js";
 export { isNativeAvailable } from "./native.js";
 
+import { defaultPrecision, defaultRoundMode } from "./context.js";
 import type { MedianOptions, StddevOptions } from "./Decimal.js";
 import { Decimal, type DecimalInput } from "./Decimal.js";
+import { money } from "./Money.js";
 
 export function decimal(value: DecimalInput): Decimal {
 	return Decimal.from(value);
@@ -98,7 +111,7 @@ function medianImpl(
 	list.sort((a, b) => a.cmp(b));
 	const mid = Math.floor(list.length / 2);
 	if (list.length % 2 === 1) return list[mid];
-	const precision = options.precision ?? 18;
+	const precision = options.precision ?? defaultPrecision();
 	return list[mid - 1].plus(list[mid]).div("2", { precision });
 }
 
@@ -109,7 +122,7 @@ function modeImpl(values: Iterable<DecimalInput>): Decimal[] {
 		frequencies.set(key, (frequencies.get(key) ?? 0) + 1);
 	}
 	if (frequencies.size === 0) {
-		throw new Error("Atom.mode requires at least one value");
+		return [];
 	}
 	let maxCount = 0;
 	for (const count of frequencies.values()) {
@@ -131,8 +144,8 @@ function stddevImpl(
 		throw new Error("Atom.stddev requires at least one value");
 	}
 	const sample = options.sample ?? false;
-	const precision = options.precision ?? 18;
-	const mode = options.mode ?? "trunc";
+	const precision = options.precision ?? defaultPrecision();
+	const mode = options.mode ?? defaultRoundMode();
 	const divisor = sample ? list.length - 1 : list.length;
 	if (divisor <= 0) {
 		throw new Error("Atom.stddev sample mode requires at least two values");
@@ -256,6 +269,8 @@ export const Atom = {
 	/** Parse a locale-formatted decimal string (e.g. `'1.234,56'` in `fr-FR`). */
 	parseLocale: (value: string, locales?: Intl.LocalesArgument) =>
 		Decimal.parseLocale(value, locales),
+	/** Construct a currency-bound `Money` value. */
+	money,
 };
 
 export const sum = sumFn;

package/src/math.ts

@@ -3,11 +3,61 @@ export interface ParsedDecimal {
 	scale: number;
 }
 
+/**
+ * How far an exponent may move the decimal point.
+ *
+ * An expression like `1E1000000` is syntactically fine and would expand to a
+ * megabyte of zeroes before anything could reject it. The bound is far past any
+ * real monetary or measurement scale, and refuses the pathological input as
+ * input rather than as an out-of-memory later.
+ */
+const MAX_EXPONENT = 10_000;
+
+/**
+ * Expand scientific notation into plain decimal text.
+ *
+ * `1E-10` is what `JSON.stringify` emits for a small number and what many APIs
+ * return, so a value that survives as a `number` has to survive as the string
+ * carrying it too — otherwise the same amount parses or throws depending on
+ * which side of a JSON boundary it arrived from.
+ */
+function expandScientific(input: string): string {
+	const matched = /^([+-]?)(\d*)(?:\.(\d*))?[eE]([+-]?\d+)$/.exec(input);
+	if (!matched) {
+		throw new Error(`Invalid decimal: ${input}`);
+	}
+	const [, sign, wholeRaw = "", fracRaw = "", exponentRaw = "0"] = matched;
+	if (wholeRaw.length === 0 && fracRaw.length === 0) {
+		throw new Error(`Invalid decimal: ${input}`);
+	}
+
+	const exponent = Number(exponentRaw);
+	if (!Number.isInteger(exponent) || Math.abs(exponent) > MAX_EXPONENT) {
+		throw new Error(`Invalid decimal: ${input}`);
+	}
+
+	const digits = `${wholeRaw}${fracRaw}`;
+	const pointIndex = wholeRaw.length + exponent;
+
+	let expanded: string;
+	if (pointIndex <= 0) {
+		expanded = `0.${"0".repeat(-pointIndex)}${digits}`;
+	} else if (pointIndex >= digits.length) {
+		expanded = `${digits}${"0".repeat(pointIndex - digits.length)}`;
+	} else {
+		expanded = `${digits.slice(0, pointIndex)}.${digits.slice(pointIndex)}`;
+	}
+	return sign === "-" ? `-${expanded}` : expanded;
+}
+
 export function parseDecimal(input: string): ParsedDecimal {
-	const s = input.trim();
+	let s = input.trim();
 	if (!s) {
 		throw new Error("Invalid decimal: empty string");
 	}
+	if (/[eE]/.test(s)) {
+		s = expandScientific(s);
+	}
 
 	let sign = 1n;
 	let body = s;
@@ -27,6 +77,9 @@ export function parseDecimal(input: string): ParsedDecimal {
 	if (!/^\d*$/.test(whole) || !/^\d*$/.test(frac)) {
 		throw new Error(`Invalid decimal: ${input}`);
 	}
+	if (whole.length + frac.length === 0) {
+		throw new Error(`Invalid decimal: ${input}`);
+	}
 
 	const digits = `${whole}${frac}` || "0";
 	const int = BigInt(digits) * sign;
@@ -154,11 +207,11 @@ export function powTs(a: string, exp: number, precision: number): string {
 	let e = exp;
 
 	while (e > 0) {
-		if (e & 1) {
+		if (e % 2 === 1) {
 			resultInt *= currentInt;
 			resultScale += currentScale;
 		}
-		e >>= 1;
+		e = Math.floor(e / 2);
 		if (e > 0) {
 			currentInt *= currentInt;
 			currentScale *= 2;

package/src/native.ts

@@ -5,8 +5,8 @@
  * - **Browser**: loads the `.wasm` binary via the wasm-pack JS glue (async init on
  *   first module import via top-level await, then sync function calls)
  *
- * The consumer imports `nativeAtom()` and gets the same `NativeAtom` interface
- * regardless of the environment. No conditional imports needed at the call site.
+ * The Decimal facade prefers this engine when available and falls back to the
+ * pure TypeScript BigInt implementation when unavailable.
  */
 
 export interface NativeAtom {
@@ -94,6 +94,13 @@ export function nativeAtom(): NativeAtom {
 	return native;
 }
 
+export function tryNativeAtom(): NativeAtom | undefined {
+	if (overrideNative !== undefined) {
+		return overrideNative ?? undefined;
+	}
+	return native;
+}
+
 // Test override (unchanged from before)
 let overrideNative: NativeAtom | null | undefined;