@heavybit/shared-lib 1.3.2 → 2.7.0

package/dist/cjs/common/internal-client.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeUnavailableError = makeUnavailableError;
+exports.createInternalClient = createInternalClient;
+const async_js_1 = require("./async.js");
+const circuit_breaker_js_1 = require("./circuit-breaker.js");
+const errors_js_1 = require("./errors.js");
+const internal_service_auth_js_1 = require("./internal-service-auth.js");
+const index_js_1 = require("../config/index.js");
+const index_js_2 = require("../context/index.js");
+const index_js_3 = require("../identity/index.js");
+const unavailableClasses = new Map();
+const pascalCase = (value) => value.split(/[^A-Za-z0-9]+/).filter(Boolean).map((part) => part[0].toUpperCase() + part.slice(1)).join('');
+/**
+ * Returns the `{Target}UnavailableError` class for a target service (the same class on every call, so
+ * `instanceof` works anywhere in the process).
+ *
+ * @param target The target service name, e.g. `records-service`.
+ * @returns A class named e.g. `RecordsServiceUnavailableError`, extending `ServiceUnavailableError` (503).
+ * @example
+ * const RecordsUnavailable = makeUnavailableError('records-service');
+ * try { await records.get('/records/1'); } catch (e) { if (e instanceof RecordsUnavailable) useCachedCopy(); }
+ */
+function makeUnavailableError(target) {
+    const existing = unavailableClasses.get(target);
+    if (existing)
+        return existing;
+    const TargetUnavailableError = class extends errors_js_1.ServiceUnavailableError {
+        target = target;
+        constructor(message = `${target} is unavailable`, options = {}) {
+            super(message, { cause: options.cause });
+        }
+    };
+    // AppError takes `name` from the constructor, so naming the class names every instance.
+    Object.defineProperty(TargetUnavailableError, 'name', { value: `${pascalCase(target)}UnavailableError` });
+    unavailableClasses.set(target, TargetUnavailableError);
+    return TargetUnavailableError;
+}
+const RETRYABLE_METHODS = new Set(['GET']);
+const RETRYABLE_STATUS = new Set([502, 503, 504]);
+/** Why an attempt counted as unavailable; logged, never sent to the end user. */
+class AttemptFailure extends Error {
+    reason;
+    retryable;
+    constructor(reason, retryable, options) {
+        super(reason, options);
+        this.reason = reason;
+        this.retryable = retryable;
+    }
+}
+/**
+ * Creates a client for one target service.
+ *
+ * @param options Target, base URL, caller credential, timeout, retry, breaker and logger settings.
+ * @returns An {@link InternalClient}.
+ * @throws ConfigError when the caller name or credential is missing.
+ * @example
+ * // src/clients/records.client.ts
+ * const http = createInternalClient({ target: 'records-service', baseUrl: config.RECORDS_INTERNAL_URL, logger });
+ * export const getRecord = (id: string) => http.get(`/records/${id}`, { schema: recordSchema });
+ */
+function createInternalClient(options) {
+    const caller = options.caller ?? (() => {
+        const env = (0, internal_service_auth_js_1.internalServiceAuthConfigFromEnv)();
+        return { name: env.name, secret: env.credential };
+    })();
+    if (!caller.name || !caller.secret) {
+        throw new index_js_1.ConfigError(`createInternalClient(${options.target}): INTERNAL_SERVICE_NAME and INTERNAL_SERVICE_CREDENTIAL are required`);
+    }
+    const UnavailableError = makeUnavailableError(options.target);
+    const breaker = new circuit_breaker_js_1.CircuitBreaker(options.breaker);
+    const doFetch = options.fetch ?? fetch;
+    const base = options.baseUrl.replace(/\/+$/, '');
+    const backoff = options.backoffMs?.length ? options.backoffMs : [100, 400];
+    const buildUrl = (path, query) => {
+        const url = new URL(base + (path.startsWith('/') ? path : `/${path}`));
+        for (const [key, value] of Object.entries(query ?? {}))
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        return url;
+    };
+    const buildHeaders = (opts) => {
+        const correlationId = opts.correlationId ?? (0, index_js_2.getRequestContext)()?.correlationId;
+        return {
+            accept: 'application/json',
+            ...(opts.body !== undefined ? { 'content-type': 'application/json' } : {}),
+            ...opts.identityHeaders,
+            ...(correlationId ? { [index_js_3.CONTEXT_HEADERS.CORRELATION_ID]: correlationId } : {}),
+            ...(opts.idempotencyKey ? { [index_js_3.CONTEXT_HEADERS.IDEMPOTENCY_KEY]: opts.idempotencyKey } : {}),
+            // Last, so nothing passed in can replace the caller's own credential.
+            ...(0, internal_service_auth_js_1.internalServiceHeaders)(caller),
+        };
+    };
+    /** One HTTP attempt: resolves with status + body text for any answer below 500, throws AttemptFailure otherwise. */
+    const attempt = async (method, url, init, timeoutMs) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await doFetch(url, { ...init, method, signal: controller.signal });
+            const text = await response.text();
+            if (response.status >= 500)
+                throw new AttemptFailure(`status ${response.status}`, RETRYABLE_STATUS.has(response.status));
+            return { status: response.status, text };
+        }
+        catch (error) {
+            if (error instanceof AttemptFailure)
+                throw error;
+            throw new AttemptFailure(controller.signal.aborted ? 'timeout' : 'network error', true, { cause: error });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    /** Runs attempts with GET-only retries; throws AttemptFailure when the target never answered below 500. */
+    const send = async (method, url, init, timeoutMs) => {
+        const retries = RETRYABLE_METHODS.has(method) ? options.retries ?? 2 : 0;
+        for (let n = 0;; n += 1) {
+            try {
+                return await attempt(method, url, init, timeoutMs);
+            }
+            catch (error) {
+                const failure = error;
+                if (!failure.retryable || n >= retries)
+                    throw failure;
+                await (0, async_js_1.sleep)(backoff[Math.min(n, backoff.length - 1)] ?? 0);
+            }
+        }
+    };
+    const unavailable = (method, url, reason, cause) => {
+        options.logger?.warn('Internal call unavailable', { target: options.target, method, path: url.pathname, reason });
+        return new UnavailableError(`${options.target} unavailable: ${reason}`, { cause });
+    };
+    async function request(method, path, opts = {}) {
+        const url = buildUrl(path, opts.query);
+        if (!breaker.tryAcquire())
+            throw unavailable(method, url, 'circuit open');
+        const init = { headers: buildHeaders(opts), body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined };
+        let answer;
+        try {
+            answer = await send(method, url, init, opts.timeoutMs ?? options.timeoutMs ?? 3000);
+        }
+        catch (error) {
+            breaker.onFailure();
+            throw unavailable(method, url, error.reason, error);
+        }
+        breaker.onSuccess();
+        let payload = {};
+        try {
+            payload = answer.text ? JSON.parse(answer.text) : {};
+        }
+        catch (error) {
+            // A 4xx without a JSON body still maps to a plain AppError below; a 2xx must be readable.
+            if (answer.status < 400)
+                throw unavailable(method, url, 'unreadable response body', error);
+        }
+        if (answer.status >= 400) {
+            throw new errors_js_1.AppError(answer.status, payload.message || `${options.target} rejected the request`, { code: payload.code, errors: payload.errors });
+        }
+        if (!opts.schema)
+            return payload.data;
+        const parsed = opts.schema.safeParse(payload.data);
+        if (!parsed.success)
+            throw unavailable(method, url, 'response did not match the expected schema', parsed.error);
+        return parsed.data;
+    }
+    return {
+        target: options.target,
+        UnavailableError,
+        get circuitState() { return breaker.state; },
+        get: (path, opts) => request('GET', path, opts),
+        post: (path, opts) => request('POST', path, opts),
+        put: (path, opts) => request('PUT', path, opts),
+        patch: (path, opts) => request('PATCH', path, opts),
+        delete: (path, opts) => request('DELETE', path, opts),
+    };
+}
+//# sourceMappingURL=internal-client.js.map

package/dist/cjs/common/internal-client.js.map

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

package/dist/cjs/common/internal-constants.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Leaf constants for internal-service auth, shared by `common/internal-service-auth` and the `config` env blocks
+ * (kept dependency-free so neither module imports the other).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_NAME_PATTERN = exports.MIN_INTERNAL_CREDENTIAL_LENGTH = void 0;
+/** Shortest internal credential accepted in staging and production. */
+exports.MIN_INTERNAL_CREDENTIAL_LENGTH = 32;
+/** Service names are compose-style: lower-case letters, digits and hyphens, starting with a letter. */
+exports.SERVICE_NAME_PATTERN = /^[a-z][a-z0-9-]{0,62}$/;
+//# sourceMappingURL=internal-constants.js.map

package/dist/cjs/common/internal-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-constants.js","sourceRoot":"","sources":["../../../src/common/internal-constants.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,uEAAuE;AAC1D,QAAA,8BAA8B,GAAG,EAAE,CAAC;AACjD,uGAAuG;AAC1F,QAAA,oBAAoB,GAAG,wBAAwB,CAAC"}

package/dist/cjs/common/internal-service-auth.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_NAME_PATTERN = exports.MIN_INTERNAL_CREDENTIAL_LENGTH = exports.INTERNAL_SERVICE_SECRET_HEADER = exports.INTERNAL_SERVICE_NAME_HEADER = void 0;
+exports.parseInternalServiceCredentials = parseInternalServiceCredentials;
+exports.internalServiceAuthConfigFromEnv = internalServiceAuthConfigFromEnv;
+exports.internalServiceHeaders = internalServiceHeaders;
+exports.assertInternalServiceAuthConfigured = assertInternalServiceAuthConfigured;
+exports.verifyInternalCaller = verifyInternalCaller;
+/**
+ * Per-caller service-to-service credentials.
+ *
+ * Layer: plumbing (no HTTP framework). Key rules:
+ * - Every calling service has its **own** secret (`INTERNAL_SERVICE_CREDENTIAL`) and sends it with its name
+ *   (`INTERNAL_SERVICE_NAME`). A receiving service holds `INTERNAL_SERVICE_CREDENTIALS`, a JSON map of
+ *   caller name → the secret it accepts from that caller, and each internal route lists the callers it allows.
+ *   One leaked credential therefore reaches only the routes meant for that one caller.
+ * - Secrets are compared in constant time (SHA-256 digests + `timingSafeEqual`, so lengths don't leak) and
+ *   are never logged or put in error messages.
+ * - Staging and production refuse to start without the credentials a service needs
+ *   ({@link assertInternalServiceAuthConfigured}); development and test may run without them.
+ *
+ * App-independent: caller names are whatever the app's compose service names are.
+ */
+const node_crypto_1 = require("node:crypto");
+const index_js_1 = require("../config/index.js");
+const index_js_2 = require("../identity/index.js");
+const internal_constants_js_1 = require("./internal-constants.js");
+/** Header carrying the calling service's name. */
+exports.INTERNAL_SERVICE_NAME_HEADER = index_js_2.CONTEXT_HEADERS.INTERNAL_SERVICE_NAME;
+/** Header carrying the calling service's own secret. */
+exports.INTERNAL_SERVICE_SECRET_HEADER = index_js_2.CONTEXT_HEADERS.INTERNAL_SECRET;
+var internal_constants_js_2 = require("./internal-constants.js");
+Object.defineProperty(exports, "MIN_INTERNAL_CREDENTIAL_LENGTH", { enumerable: true, get: function () { return internal_constants_js_2.MIN_INTERNAL_CREDENTIAL_LENGTH; } });
+Object.defineProperty(exports, "SERVICE_NAME_PATTERN", { enumerable: true, get: function () { return internal_constants_js_2.SERVICE_NAME_PATTERN; } });
+/** Environments where missing or weak internal credentials stop the service from starting. */
+const STRICT_ENVIRONMENTS = new Set(['staging', 'production']);
+const read = (env, key) => {
+    const value = env[key];
+    return typeof value === 'string' ? value.trim() : '';
+};
+/**
+ * Parses `INTERNAL_SERVICE_CREDENTIALS` (a JSON object of caller name → secret).
+ *
+ * @param raw The env value; empty or undefined gives `{}`.
+ * @returns A frozen map of caller name → secret.
+ * @throws ConfigError when the JSON is malformed, not an object, a name is not a valid service name, or a
+ *   secret is not a non-empty string. The message names the bad key, never a secret.
+ * @example parseInternalServiceCredentials('{"alpha-service":"<secret>"}') // { 'alpha-service': '<secret>' }
+ */
+function parseInternalServiceCredentials(raw) {
+    if (!raw?.trim())
+        return Object.freeze({});
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new index_js_1.ConfigError('INTERNAL_SERVICE_CREDENTIALS must be a JSON object of service name to secret');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new index_js_1.ConfigError('INTERNAL_SERVICE_CREDENTIALS must be a JSON object of service name to secret');
+    }
+    const credentials = {};
+    for (const [name, secret] of Object.entries(parsed)) {
+        if (!internal_constants_js_1.SERVICE_NAME_PATTERN.test(name))
+            throw new index_js_1.ConfigError(`INTERNAL_SERVICE_CREDENTIALS has an invalid service name: "${name}"`);
+        if (typeof secret !== 'string' || !secret)
+            throw new index_js_1.ConfigError(`INTERNAL_SERVICE_CREDENTIALS has an empty or non-string secret for "${name}"`);
+        credentials[name] = secret;
+    }
+    return Object.freeze(credentials);
+}
+/**
+ * Reads `INTERNAL_SERVICE_NAME`, `INTERNAL_SERVICE_CREDENTIAL` and `INTERNAL_SERVICE_CREDENTIALS`.
+ *
+ * @param env process.env (default) or a parsed config object.
+ * @returns The settings; missing values are empty.
+ * @throws ConfigError when `INTERNAL_SERVICE_CREDENTIALS` is malformed.
+ * @example const internalAuth = internalServiceAuthConfigFromEnv();
+ */
+function internalServiceAuthConfigFromEnv(env = process.env) {
+    return {
+        name: read(env, 'INTERNAL_SERVICE_NAME'),
+        credential: read(env, 'INTERNAL_SERVICE_CREDENTIAL'),
+        credentials: parseInternalServiceCredentials(read(env, 'INTERNAL_SERVICE_CREDENTIALS')),
+    };
+}
+/**
+ * The headers a service adds to every internal call it makes.
+ *
+ * @param caller This service's name and secret.
+ * @returns `{ 'x-internal-service-name', 'x-internal-service-secret' }`.
+ * @example fetch(url, { headers: { ...internalServiceHeaders({ name, secret }) } });
+ */
+function internalServiceHeaders(caller) {
+    return { [exports.INTERNAL_SERVICE_NAME_HEADER]: caller.name, [exports.INTERNAL_SERVICE_SECRET_HEADER]: caller.secret };
+}
+/**
+ * Startup guard. In staging and production it refuses to start when a calling service lacks a valid name or a
+ * credential of at least 32 characters, or when a serving service has no accepted callers or any accepted
+ * secret shorter than 32 characters. In other environments it only checks that what is set parses.
+ *
+ * @param options Whether the service calls and/or serves internal routes.
+ * @throws ConfigError listing every problem (names only, never secret values).
+ * @example assertInternalServiceAuthConfigured({ calls: true, serves: true });
+ */
+function assertInternalServiceAuthConfigured(options) {
+    const env = options.env ?? process.env;
+    const config = internalServiceAuthConfigFromEnv(env);
+    if (!STRICT_ENVIRONMENTS.has(options.nodeEnv ?? read(env, 'NODE_ENV')))
+        return;
+    const problems = [];
+    if (options.calls) {
+        if (!internal_constants_js_1.SERVICE_NAME_PATTERN.test(config.name))
+            problems.push('INTERNAL_SERVICE_NAME is missing or not a valid service name');
+        if (config.credential.length < internal_constants_js_1.MIN_INTERNAL_CREDENTIAL_LENGTH) {
+            problems.push(`INTERNAL_SERVICE_CREDENTIAL must be at least ${internal_constants_js_1.MIN_INTERNAL_CREDENTIAL_LENGTH} characters`);
+        }
+    }
+    if (options.serves) {
+        const callers = Object.keys(config.credentials);
+        if (!callers.length)
+            problems.push('INTERNAL_SERVICE_CREDENTIALS is empty: no internal caller can authenticate');
+        const weak = callers.filter((name) => (config.credentials[name] ?? '').length < internal_constants_js_1.MIN_INTERNAL_CREDENTIAL_LENGTH);
+        if (weak.length)
+            problems.push(`INTERNAL_SERVICE_CREDENTIALS has secrets shorter than ${internal_constants_js_1.MIN_INTERNAL_CREDENTIAL_LENGTH} characters for: ${weak.join(', ')}`);
+    }
+    if (problems.length)
+        throw new index_js_1.ConfigError(`Refusing to start: ${problems.join('; ')}`);
+}
+const digest = (value) => (0, node_crypto_1.createHash)('sha256').update(value).digest();
+/** A fixed value to compare against when the caller is unknown, so unknown and known callers take the same time. */
+const UNKNOWN_CALLER_DIGEST = digest('unknown-caller');
+const header = (headers, name) => {
+    const value = headers[name];
+    return typeof value === 'string' ? value : '';
+};
+/**
+ * Checks the internal headers against the accepted credentials and the route's caller list.
+ * 401 when the name or secret is missing, the name is unknown or the secret is wrong; 403 when a correctly
+ * authenticated caller is not in `allowed`.
+ *
+ * @param input Request headers, accepted credentials and the route's allowed callers.
+ * @returns A verdict; the caller name is included when one was sent (safe to log), the secret never is.
+ * @example verifyInternalCaller({ headers: req.headers, credentials, allowed: ['alpha-service'] });
+ */
+function verifyInternalCaller(input) {
+    const caller = header(input.headers, exports.INTERNAL_SERVICE_NAME_HEADER);
+    const secret = header(input.headers, exports.INTERNAL_SERVICE_SECRET_HEADER);
+    if (!caller || !secret)
+        return { ok: false, status: 401, reason: 'missing-credentials', caller: caller || undefined };
+    const expected = Object.prototype.hasOwnProperty.call(input.credentials, caller) ? input.credentials[caller] : undefined;
+    const matches = (0, node_crypto_1.timingSafeEqual)(digest(secret), expected ? digest(expected) : UNKNOWN_CALLER_DIGEST) && expected !== undefined;
+    if (!matches)
+        return { ok: false, status: 401, reason: 'invalid-credentials', caller };
+    if (!input.allowed.includes(caller))
+        return { ok: false, status: 403, reason: 'caller-not-allowed', caller };
+    return { ok: true, caller };
+}
+//# sourceMappingURL=internal-service-auth.js.map

package/dist/cjs/common/internal-service-auth.js.map

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

package/dist/cjs/common/money.js

@@ -0,0 +1,215 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Money = void 0;
+exports.resolveCurrency = resolveCurrency;
+const decimal_js_1 = __importDefault(require("decimal.js"));
+/**
+ * Exact money arithmetic. Amounts travel and persist as decimal strings (`"1250.00"`) and are only ever
+ * computed with a decimal type, never JS numbers. The currency is always passed in: shared-lib has no
+ * default currency.
+ *
+ * Rounding is half-up (half away from zero) to the currency's minor unit, after every operation that can
+ * produce extra digits (`mul`), so a `Money` value always holds a whole number of minor units.
+ */
+/** A decimal.js constructor with enough precision for any realistic amount and half-up rounding. */
+const Dec = decimal_js_1.default.clone({ precision: 40, rounding: decimal_js_1.default.ROUND_HALF_UP, toExpNeg: -40, toExpPos: 40 });
+const CODE_PATTERN = /^[A-Z]{3}$/;
+const AMOUNT_PATTERN = /^-?\d+(\.\d+)?$/;
+/**
+ * Resolves a currency code or spec, validating both.
+ *
+ * @param currency ISO 4217 code (minor units from `Intl`) or `{ code, minorUnits }`.
+ * @returns The spec.
+ * @throws RangeError for a malformed code or minor-unit count.
+ * @example resolveCurrency('USD') // { code: 'USD', minorUnits: 2 }
+ */
+function resolveCurrency(currency) {
+    if (typeof currency !== 'string') {
+        if (!CODE_PATTERN.test(currency.code))
+            throw new RangeError(`Invalid currency code "${currency.code}"`);
+        if (!Number.isInteger(currency.minorUnits) || currency.minorUnits < 0 || currency.minorUnits > 6) {
+            throw new RangeError(`Invalid minor units ${currency.minorUnits} for ${currency.code}`);
+        }
+        return { code: currency.code, minorUnits: currency.minorUnits };
+    }
+    if (!CODE_PATTERN.test(currency))
+        throw new RangeError(`Invalid currency code "${currency}"`);
+    const minorUnits = new Intl.NumberFormat('en', { style: 'currency', currency }).resolvedOptions().maximumFractionDigits ?? 2;
+    return { code: currency, minorUnits };
+}
+function toDecimal(value, what) {
+    if (typeof value === 'number' && !Number.isFinite(value))
+        throw new RangeError(`${what} must be finite`);
+    const text = String(value).trim();
+    if (!AMOUNT_PATTERN.test(text))
+        throw new RangeError(`${what} must be a decimal number, got "${value}"`);
+    return new Dec(text);
+}
+/** An immutable amount of one currency, always a whole number of minor units. */
+class Money {
+    value;
+    currency;
+    constructor(value, 
+    /** The amount's currency. */
+    currency) {
+        this.value = value;
+        this.currency = currency;
+        Object.freeze(this);
+    }
+    /**
+     * Parses a decimal string. Strict: no thousands separators, symbols or more decimals than the
+     * currency allows (D5), so a stored value is never silently rounded on the way in.
+     *
+     * @param amount e.g. `"1250.5"` or `"-3.25"`.
+     * @param currency Code or spec.
+     * @returns The amount.
+     * @throws RangeError for anything else.
+     * @example Money.fromDecimalString('19.99', 'USD')
+     */
+    static fromDecimalString(amount, currency) {
+        const spec = resolveCurrency(currency);
+        if (typeof amount !== 'string')
+            throw new RangeError('Amount must be a decimal string');
+        const value = toDecimal(amount, 'Amount');
+        if (value.decimalPlaces() > spec.minorUnits) {
+            throw new RangeError(`Amount "${amount}" has more than ${spec.minorUnits} decimal places for ${spec.code}`);
+        }
+        return new Money(value, spec);
+    }
+    /**
+     * Builds an amount from an integer count of minor units (e.g. cents).
+     *
+     * @param units Integer (number within the safe range, or bigint).
+     * @param currency Code or spec.
+     * @returns The amount.
+     * @example Money.fromMinorUnits(1999, 'USD').toDecimalString() // '19.99'
+     */
+    static fromMinorUnits(units, currency) {
+        const spec = resolveCurrency(currency);
+        if (typeof units === 'number' && !Number.isSafeInteger(units))
+            throw new RangeError('Minor units must be a safe integer');
+        return new Money(new Dec(units.toString()).div(new Dec(10).pow(spec.minorUnits)), spec);
+    }
+    /**
+     * Zero in a currency.
+     *
+     * @param currency Code or spec.
+     * @returns `0` of that currency.
+     */
+    static zero(currency) {
+        return new Money(new Dec(0), resolveCurrency(currency));
+    }
+    /** The amount with exactly the currency's decimal places, e.g. `"1250.00"` — the wire and storage form. */
+    toDecimalString() {
+        return this.value.toFixed(this.currency.minorUnits);
+    }
+    /** The amount as an integer count of minor units. */
+    toMinorUnits() {
+        return BigInt(this.value.times(new Dec(10).pow(this.currency.minorUnits)).toFixed(0));
+    }
+    /** Serialises as the decimal string, so an amount never becomes a JSON number by accident. */
+    toJSON() {
+        return this.toDecimalString();
+    }
+    /** Same as {@link toDecimalString}. */
+    toString() {
+        return this.toDecimalString();
+    }
+    /** Sum of two amounts of the same currency. */
+    add(other) {
+        return new Money(this.value.plus(this.same(other).value), this.currency);
+    }
+    /** Difference of two amounts of the same currency. */
+    sub(other) {
+        return new Money(this.value.minus(this.same(other).value), this.currency);
+    }
+    /**
+     * Multiplies by a rate (tax, fee, quantity), rounding half-up to the minor unit.
+     *
+     * @param rate e.g. `"0.16"` or `3`.
+     * @returns The rounded product.
+     * @example Money.fromDecimalString('10.05', 'USD').mul('0.5').toDecimalString() // '5.03'
+     */
+    mul(rate) {
+        return new Money(this.round(this.value.times(toDecimal(rate, 'Rate'))), this.currency);
+    }
+    /**
+     * Splits the amount in proportion to `ratios`; the parts always sum to the amount exactly. Each part is
+     * rounded down to the minor unit and the left-over units go, one each, to the parts with the largest
+     * remainders (earlier parts win ties). A negative amount is split like its absolute value, then negated.
+     *
+     * @param ratios Non-negative weights with a positive sum, e.g. `['1', '1', '1']` or `[70, 30]`.
+     * @returns One amount per ratio, in order.
+     * @throws RangeError for an empty list, a negative ratio or a zero sum.
+     * @example Money.fromDecimalString('100.00', 'USD').allocate([1, 1, 1]).map(String) // ['33.34', '33.33', '33.33']
+     */
+    allocate(ratios) {
+        if (ratios.length === 0)
+            throw new RangeError('allocate needs at least one ratio');
+        const weights = ratios.map((r) => toDecimal(r, 'Ratio'));
+        if (weights.some((w) => w.isNegative()))
+            throw new RangeError('Ratios must not be negative');
+        const sum = weights.reduce((acc, w) => acc.plus(w), new Dec(0));
+        if (sum.isZero())
+            throw new RangeError('Ratios must not all be zero');
+        const scale = new Dec(10).pow(this.currency.minorUnits);
+        const total = this.value.abs().times(scale);
+        const exact = weights.map((w) => total.times(w).div(sum));
+        const floors = exact.map((e) => e.floor());
+        let leftover = total.minus(floors.reduce((acc, f) => acc.plus(f), new Dec(0))).toNumber();
+        const order = exact.map((e, i) => ({ i, rem: e.minus(floors[i]) })).sort((a, b) => b.rem.comparedTo(a.rem) || a.i - b.i);
+        for (const { i } of order) {
+            if (leftover <= 0)
+                break;
+            floors[i] = floors[i].plus(1);
+            leftover -= 1;
+        }
+        const sign = this.value.isNegative() ? -1 : 1;
+        return floors.map((units) => new Money(units.div(scale).times(sign), this.currency));
+    }
+    /**
+     * Rounds up (toward +∞) to a multiple of `unit`, e.g. whole units for a payment rail that rejects cents.
+     *
+     * @param unit Positive step in major units, e.g. `"1"` or `"0.05"`; defaults to `"1"`.
+     * @returns The rounded-up amount.
+     * @example Money.fromDecimalString('99.01', 'USD').ceilToUnit().toDecimalString() // '100.00'
+     */
+    ceilToUnit(unit = '1') {
+        const step = toDecimal(unit, 'Unit');
+        if (step.lte(0))
+            throw new RangeError('Unit must be positive');
+        if (step.decimalPlaces() > this.currency.minorUnits)
+            throw new RangeError(`Unit is finer than the ${this.currency.code} minor unit`);
+        return new Money(this.value.div(step).ceil().times(step), this.currency);
+    }
+    /** -1, 0 or 1 comparing this amount with `other` (same currency). */
+    compare(other) {
+        return this.value.comparedTo(this.same(other).value);
+    }
+    /** True when both amounts have the same currency and value. */
+    equals(other) {
+        return this.currency.code === other.currency.code && this.value.equals(other.value);
+    }
+    /** True for zero. */
+    isZero() {
+        return this.value.isZero();
+    }
+    /** True below zero. */
+    isNegative() {
+        return this.value.isNegative() && !this.value.isZero();
+    }
+    same(other) {
+        if (other.currency.code !== this.currency.code) {
+            throw new RangeError(`Currency mismatch: ${this.currency.code} vs ${other.currency.code}`);
+        }
+        return other;
+    }
+    round(value) {
+        return value.toDecimalPlaces(this.currency.minorUnits, decimal_js_1.default.ROUND_HALF_UP);
+    }
+}
+exports.Money = Money;
+//# sourceMappingURL=money.js.map

package/dist/cjs/common/money.js.map

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