@fulcro/types 0.1.0

package/dist/decimal/parse.d.ts

@@ -0,0 +1,15 @@
+import { type DecimalParts } from './parts';
+/**
+ * Parses a decimal literal into normalised parts, rounding half to even when it
+ * carries more than thirty-four significant digits.
+ *
+ * Linear in the length of the input. The digits past the thirty-fifth are only
+ * scanned for a non-zero one, never converted, because turning a long string
+ * into a `bigint` costs more than linear time and the digits would be discarded
+ * by the rounding immediately afterwards anyway.
+ *
+ * @param text Literal to parse.
+ * @returns The parts.
+ * @throws {SyntaxError} When the text is not a decimal literal.
+ */
+export declare const parseDecimal: (text: string) => DecimalParts;

package/dist/decimal/parse.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDecimal = void 0;
+const parts_1 = require("./parts");
+const round_1 = require("./round");
+/**
+ * A decimal literal: an optional sign, digits with at most one point and at
+ * least one digit, and an optional exponent. The same grammar as a JavaScript
+ * numeric string, less the hexadecimal, octal and binary forms, and without
+ * surrounding whitespace.
+ */
+const DECIMAL_LITERAL = /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/;
+/**
+ * Exponents beyond this are clamped to it. Any exponent this large already
+ * overflows or underflows whatever digits come with it, and clamping keeps the
+ * arithmetic on it exact in a `number`.
+ */
+const EXPONENT_LIMIT = 1_000_000_000;
+/**
+ * Significant digits kept from the input before the rest is summarised: the
+ * format's thirty-four, and one more to decide the rounding. A thirty-sixth
+ * digit then stands for everything after, as 1 when any of it is non-zero —
+ * which is all a rounding can ask of it.
+ */
+const KEPT_DIGITS = parts_1.PRECISION + 1;
+/**
+ * Describes a rejected input for an error message, without printing a
+ * megabyte of it.
+ *
+ * @param text Input that was rejected.
+ * @returns A quoted, shortened copy.
+ */
+const describeInput = (text) => JSON.stringify(text.length > 40 ? `${text.slice(0, 40)}…` : text);
+/**
+ * Parses a decimal literal into normalised parts, rounding half to even when it
+ * carries more than thirty-four significant digits.
+ *
+ * Linear in the length of the input. The digits past the thirty-fifth are only
+ * scanned for a non-zero one, never converted, because turning a long string
+ * into a `bigint` costs more than linear time and the digits would be discarded
+ * by the rounding immediately afterwards anyway.
+ *
+ * @param text Literal to parse.
+ * @returns The parts.
+ * @throws {SyntaxError} When the text is not a decimal literal.
+ */
+const parseDecimal = (text) => {
+    switch (text) {
+        case 'NaN':
+            return parts_1.NOT_A_NUMBER;
+        case 'Infinity':
+        case '+Infinity':
+            return (0, parts_1.infinity)(false);
+        case '-Infinity':
+            return (0, parts_1.infinity)(true);
+    }
+    const match = DECIMAL_LITERAL.exec(text);
+    const [, sign = '', whole = '', fraction = '', exponentText] = match ?? [];
+    if (match === null || whole.length + fraction.length === 0) {
+        throw new SyntaxError(`Decimal.from: expected a decimal literal, received ${describeInput(text)}.`);
+    }
+    const negative = sign === '-';
+    const digits = whole + fraction;
+    let exponent = exponentText === undefined
+        ? 0
+        : Math.max(-EXPONENT_LIMIT, Math.min(EXPONENT_LIMIT, Number(exponentText)));
+    exponent -= fraction.length;
+    const leading = digits.search(/[1-9]/);
+    if (leading === -1)
+        return (0, parts_1.zero)(negative);
+    const significant = digits.slice(leading);
+    if (significant.length <= KEPT_DIGITS + 1) {
+        return (0, round_1.finish)(negative, BigInt(significant), exponent, 'halfEven');
+    }
+    const sticky = /[1-9]/.test(significant.slice(KEPT_DIGITS))
+        ? '1'
+        : '0';
+    return (0, round_1.finish)(negative, BigInt(significant.slice(0, KEPT_DIGITS) + sticky), exponent + significant.length - (KEPT_DIGITS + 1), 'halfEven');
+};
+exports.parseDecimal = parseDecimal;

package/dist/decimal/parts.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The value a `Decimal` holds, taken apart.
+ *
+ * Every operation of `Decimal` works on these, and the class only wraps them.
+ * They are kept **normalised**: a finite coefficient never ends in a zero
+ * unless it is zero, and a zero or a special value has an exponent of zero.
+ * That makes equality structural and printing unambiguous, and it is the
+ * representation the TC39 proposal's "normalise on the way out" implies — no
+ * operation can observe a trailing zero, so none has to carry one.
+ */
+/** Which of the three kinds of value the parts describe. */
+export type DecimalKind = 'finite' | 'infinity' | 'nan';
+/** A decimal value: (-1)^negative × coefficient × 10^exponent. */
+export interface DecimalParts {
+    /** Whether the value is finite, an infinity, or not a number. */
+    readonly kind: DecimalKind;
+    /** The sign bit, set for negative values, `-0` and `-Infinity`. */
+    readonly negative: boolean;
+    /** The significant digits, as an integer with no trailing zero. */
+    readonly coefficient: bigint;
+    /** Power of ten the coefficient is scaled by. */
+    readonly exponent: number;
+}
+/** Significant decimal digits a decimal128 value holds. */
+export declare const PRECISION = 34;
+/**
+ * Largest exponent of the leading digit, emax in IEEE 754: the largest finite
+ * value is 9.999…9 × 10^6144.
+ */
+export declare const MAXIMUM_ADJUSTED_EXPONENT = 6144;
+/**
+ * Smallest exponent of the last digit, the quantum of the smallest subnormal:
+ * 1 × 10^-6176. Anything finer rounds.
+ */
+export declare const MINIMUM_EXPONENT = -6176;
+/** Not a number. Its sign is never observed, so it is always clear. */
+export declare const NOT_A_NUMBER: DecimalParts;
+/**
+ * An infinity.
+ *
+ * @param negative Whether it is negative.
+ * @returns The parts.
+ */
+export declare const infinity: (negative: boolean) => DecimalParts;
+/**
+ * A zero.
+ *
+ * @param negative Whether it is `-0`.
+ * @returns The parts.
+ */
+export declare const zero: (negative: boolean) => DecimalParts;
+/**
+ * Tells whether finite parts are zero.
+ *
+ * @param parts Parts to inspect.
+ * @returns `true` for `0` and `-0`.
+ */
+export declare const isZero: (parts: DecimalParts) => boolean;
+/**
+ * 10 to a power.
+ *
+ * Cached up to what the arithmetic actually uses — about a hundred, since no
+ * aligned operand is allowed past that — and computed beyond it.
+ *
+ * @param exponent Non-negative power.
+ * @returns 10^exponent.
+ */
+export declare const powerOfTen: (exponent: number) => bigint;
+/**
+ * Number of decimal digits in a non-negative integer.
+ *
+ * @param value Integer to measure.
+ * @returns Its digit count, 1 for zero.
+ */
+export declare const digitCount: (value: bigint) => number;
+/**
+ * Exponent of the leading digit of finite, non-zero parts: 2 for 123, -1 for
+ * 0.5. Two values compare in magnitude by this first.
+ *
+ * @param parts Parts to inspect.
+ * @returns The adjusted exponent.
+ */
+export declare const adjustedExponent: (parts: DecimalParts) => number;

package/dist/decimal/parts.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * The value a `Decimal` holds, taken apart.
+ *
+ * Every operation of `Decimal` works on these, and the class only wraps them.
+ * They are kept **normalised**: a finite coefficient never ends in a zero
+ * unless it is zero, and a zero or a special value has an exponent of zero.
+ * That makes equality structural and printing unambiguous, and it is the
+ * representation the TC39 proposal's "normalise on the way out" implies — no
+ * operation can observe a trailing zero, so none has to carry one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adjustedExponent = exports.digitCount = exports.powerOfTen = exports.isZero = exports.zero = exports.infinity = exports.NOT_A_NUMBER = exports.MINIMUM_EXPONENT = exports.MAXIMUM_ADJUSTED_EXPONENT = exports.PRECISION = void 0;
+/** Significant decimal digits a decimal128 value holds. */
+exports.PRECISION = 34;
+/**
+ * Largest exponent of the leading digit, emax in IEEE 754: the largest finite
+ * value is 9.999…9 × 10^6144.
+ */
+exports.MAXIMUM_ADJUSTED_EXPONENT = 6144;
+/**
+ * Smallest exponent of the last digit, the quantum of the smallest subnormal:
+ * 1 × 10^-6176. Anything finer rounds.
+ */
+exports.MINIMUM_EXPONENT = -6176;
+/** Not a number. Its sign is never observed, so it is always clear. */
+exports.NOT_A_NUMBER = {
+    kind: 'nan',
+    negative: false,
+    coefficient: 0n,
+    exponent: 0,
+};
+/**
+ * An infinity.
+ *
+ * @param negative Whether it is negative.
+ * @returns The parts.
+ */
+const infinity = (negative) => ({
+    kind: 'infinity',
+    negative,
+    coefficient: 0n,
+    exponent: 0,
+});
+exports.infinity = infinity;
+/**
+ * A zero.
+ *
+ * @param negative Whether it is `-0`.
+ * @returns The parts.
+ */
+const zero = (negative) => ({
+    kind: 'finite',
+    negative,
+    coefficient: 0n,
+    exponent: 0,
+});
+exports.zero = zero;
+/**
+ * Tells whether finite parts are zero.
+ *
+ * @param parts Parts to inspect.
+ * @returns `true` for `0` and `-0`.
+ */
+const isZero = (parts) => parts.kind === 'finite' && parts.coefficient === 0n;
+exports.isZero = isZero;
+/** Powers of ten already computed, since every operation reaches for them. */
+const POWERS_OF_TEN = [1n];
+/**
+ * 10 to a power.
+ *
+ * Cached up to what the arithmetic actually uses — about a hundred, since no
+ * aligned operand is allowed past that — and computed beyond it.
+ *
+ * @param exponent Non-negative power.
+ * @returns 10^exponent.
+ */
+const powerOfTen = (exponent) => {
+    if (exponent > 128)
+        return 10n ** BigInt(exponent);
+    while (POWERS_OF_TEN.length <= exponent) {
+        POWERS_OF_TEN.push(POWERS_OF_TEN[POWERS_OF_TEN.length - 1] * 10n);
+    }
+    return POWERS_OF_TEN[exponent];
+};
+exports.powerOfTen = powerOfTen;
+/**
+ * Number of decimal digits in a non-negative integer.
+ *
+ * @param value Integer to measure.
+ * @returns Its digit count, 1 for zero.
+ */
+const digitCount = (value) => value.toString().length;
+exports.digitCount = digitCount;
+/**
+ * Exponent of the leading digit of finite, non-zero parts: 2 for 123, -1 for
+ * 0.5. Two values compare in magnitude by this first.
+ *
+ * @param parts Parts to inspect.
+ * @returns The adjusted exponent.
+ */
+const adjustedExponent = (parts) => parts.exponent + (0, exports.digitCount)(parts.coefficient) - 1;
+exports.adjustedExponent = adjustedExponent;

package/dist/decimal/round.d.ts

@@ -0,0 +1,32 @@
+import type { RoundingMode } from '../roundingMode/index.js';
+import { type DecimalParts } from './parts';
+/**
+ * Divides a magnitude by 10^digits, rounding the quotient by a mode.
+ *
+ * The number of digits may be far larger than the magnitude has — rounding
+ * 1 × 10^-6000 to two places drops six thousand of them — so that case is
+ * answered without ever building the power: every digit is discarded, and
+ * together they are below a tenth of a unit.
+ *
+ * @param magnitude Non-negative integer to shorten.
+ * @param digits How many trailing digits to discard, at least one.
+ * @param mode Rounding mode.
+ * @param negative Sign of the value.
+ * @returns The rounded quotient.
+ */
+export declare const discardDigits: (magnitude: bigint, digits: number, mode: RoundingMode, negative: boolean) => bigint;
+/**
+ * Turns an exact result into a decimal128 value: rounded to thirty-four
+ * digits, rounded again if it is finer than the smallest subnormal, stripped
+ * of trailing zeros, and sent to infinity if it no longer fits.
+ *
+ * Every operation ends here, which is what keeps every result inside the format
+ * whatever the operation computed on the way.
+ *
+ * @param negative Sign of the result.
+ * @param magnitude Exact magnitude, as an integer.
+ * @param exponent Power of ten the magnitude is scaled by.
+ * @param mode Rounding mode.
+ * @returns The parts of the result.
+ */
+export declare const finish: (negative: boolean, magnitude: bigint, exponent: number, mode: RoundingMode) => DecimalParts;

package/dist/decimal/round.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.finish = exports.discardDigits = void 0;
+const parts_1 = require("./parts");
+/**
+ * Settles a truncated quotient according to a mode.
+ *
+ * @param quotient Magnitude with the discarded digits removed.
+ * @param discarded What those digits amounted to.
+ * @param mode Rounding mode.
+ * @param negative Sign of the value, which the directed modes depend on.
+ * @returns The rounded magnitude.
+ */
+const settle = (quotient, discarded, mode, negative) => {
+    if (discarded === 'nothing')
+        return quotient;
+    switch (mode) {
+        case 'truncate':
+            return quotient;
+        case 'floor':
+            return negative ? quotient + 1n : quotient;
+        case 'ceiling':
+            return negative ? quotient : quotient + 1n;
+        case 'halfAwayFromZero':
+            return discarded === 'belowHalf' ? quotient : quotient + 1n;
+        case 'halfEven':
+            if (discarded === 'belowHalf')
+                return quotient;
+            if (discarded === 'aboveHalf')
+                return quotient + 1n;
+            return quotient % 2n === 0n ? quotient : quotient + 1n;
+    }
+};
+/**
+ * Divides a magnitude by 10^digits, rounding the quotient by a mode.
+ *
+ * The number of digits may be far larger than the magnitude has — rounding
+ * 1 × 10^-6000 to two places drops six thousand of them — so that case is
+ * answered without ever building the power: every digit is discarded, and
+ * together they are below a tenth of a unit.
+ *
+ * @param magnitude Non-negative integer to shorten.
+ * @param digits How many trailing digits to discard, at least one.
+ * @param mode Rounding mode.
+ * @param negative Sign of the value.
+ * @returns The rounded quotient.
+ */
+const discardDigits = (magnitude, digits, mode, negative) => {
+    if (digits > (0, parts_1.digitCount)(magnitude)) {
+        return settle(0n, magnitude === 0n ? 'nothing' : 'belowHalf', mode, negative);
+    }
+    const divisor = (0, parts_1.powerOfTen)(digits);
+    const quotient = magnitude / divisor;
+    const remainder = magnitude % divisor;
+    const half = divisor / 2n;
+    const discarded = remainder === 0n
+        ? 'nothing'
+        : remainder < half
+            ? 'belowHalf'
+            : remainder === half
+                ? 'half'
+                : 'aboveHalf';
+    return settle(quotient, discarded, mode, negative);
+};
+exports.discardDigits = discardDigits;
+/**
+ * The result of an overflow, which IEEE 754 makes depend on the mode: the
+ * modes that round to nearest go to infinity, and a directed mode goes to
+ * infinity only in its own direction, stopping at the largest finite value in
+ * the other.
+ *
+ * @param negative Sign of the value that overflowed.
+ * @param mode Rounding mode.
+ * @returns The parts of the result.
+ */
+const overflow = (negative, mode) => {
+    const toInfinity = mode === 'halfEven' ||
+        mode === 'halfAwayFromZero' ||
+        (mode === 'ceiling' && !negative) ||
+        (mode === 'floor' && negative);
+    if (toInfinity)
+        return (0, parts_1.infinity)(negative);
+    // 9.999…9 × 10^6144: thirty-four nines, with the last one at 10^6111.
+    return {
+        kind: 'finite',
+        negative,
+        coefficient: (0, parts_1.powerOfTen)(parts_1.PRECISION) - 1n,
+        exponent: parts_1.MAXIMUM_ADJUSTED_EXPONENT - parts_1.PRECISION + 1,
+    };
+};
+/**
+ * Turns an exact result into a decimal128 value: rounded to thirty-four
+ * digits, rounded again if it is finer than the smallest subnormal, stripped
+ * of trailing zeros, and sent to infinity if it no longer fits.
+ *
+ * Every operation ends here, which is what keeps every result inside the format
+ * whatever the operation computed on the way.
+ *
+ * @param negative Sign of the result.
+ * @param magnitude Exact magnitude, as an integer.
+ * @param exponent Power of ten the magnitude is scaled by.
+ * @param mode Rounding mode.
+ * @returns The parts of the result.
+ */
+const finish = (negative, magnitude, exponent, mode) => {
+    if (magnitude === 0n)
+        return (0, parts_1.zero)(negative);
+    let coefficient = magnitude;
+    let scale = exponent;
+    const excess = Math.max((0, parts_1.digitCount)(coefficient) - parts_1.PRECISION, parts_1.MINIMUM_EXPONENT - scale);
+    if (excess > 0) {
+        coefficient = (0, exports.discardDigits)(coefficient, excess, mode, negative);
+        scale += excess;
+        // Rounded away entirely: an underflow keeps its sign.
+        if (coefficient === 0n)
+            return (0, parts_1.zero)(negative);
+        // 99…9 rounded up to 10^34 has one digit too many, and it is a zero.
+        if (coefficient === (0, parts_1.powerOfTen)(parts_1.PRECISION)) {
+            coefficient /= 10n;
+            scale += 1;
+        }
+    }
+    while (coefficient % 10n === 0n) {
+        coefficient /= 10n;
+        scale += 1;
+    }
+    if (scale + (0, parts_1.digitCount)(coefficient) - 1 > parts_1.MAXIMUM_ADJUSTED_EXPONENT) {
+        return overflow(negative, mode);
+    }
+    return { kind: 'finite', negative, coefficient, exponent: scale };
+};
+exports.finish = finish;

package/dist/doublePrecisionFloat/index.d.ts

@@ -0,0 +1,19 @@
+import type { Branded } from '../brand/index.js';
+import type { Layout } from '../layout/index.js';
+import type { BoundedNumericType } from '../numericType/index.js';
+/**
+ * An IEEE 754 binary64 value: 53 bits of precision, 11 of exponent.
+ *
+ * Every JavaScript `number` already is one, so conversion never rounds. The type
+ * exists so that a double is named as a choice rather than left as the default
+ * nobody chose, and so that it carries a layout like the other formats.
+ */
+export type DoublePrecisionFloat = Branded<number, 'DoublePrecisionFloat'> & Layout<8, 8>;
+/**
+ * The descriptor of {@link DoublePrecisionFloat}.
+ *
+ * ```ts
+ * DoublePrecisionFloat.from(0.1); // 0.1
+ * ```
+ */
+export declare const DoublePrecisionFloat: BoundedNumericType<DoublePrecisionFloat, number>;

package/dist/doublePrecisionFloat/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DoublePrecisionFloat = void 0;
+const float_1 = require("../float/index.js");
+/**
+ * The descriptor of {@link DoublePrecisionFloat}.
+ *
+ * ```ts
+ * DoublePrecisionFloat.from(0.1); // 0.1
+ * ```
+ */
+exports.DoublePrecisionFloat = (0, float_1.createFloatType)('DoublePrecisionFloat', Number.MAX_VALUE, (value) => value);

package/dist/float/index.d.ts

@@ -0,0 +1,25 @@
+import type { BoundedNumericType } from '../numericType/index.js';
+/**
+ * Machinery shared by the three binary floating point types.
+ *
+ * A float type is fully described by one function: the rounding from a double
+ * to its own format. Everything else follows from a result proved by Figueroa
+ * (1995): when the wider format has at least 2p + 2 bits of precision, an
+ * addition, subtraction, multiplication or division computed in the wider
+ * format and then rounded to the narrower one is correctly rounded. A double
+ * carries 53 bits; single precision needs 2·24 + 2 = 50 and half precision
+ * 2·11 + 2 = 24. So each operation below is the double operation, rounded once.
+ *
+ * The remainder needs no such argument — it is always exact.
+ */
+/**
+ * Builds the descriptor of a float format.
+ *
+ * @param name Name of the type, as it reads in an error message.
+ * @param maximum Largest finite value of the format. The smallest is its
+ * negation, since a float's range is symmetric about zero.
+ * @param round Rounding of a double to the nearest value of the format, ties to
+ * even.
+ * @returns The descriptor.
+ */
+export declare const createFloatType: <T>(name: string, maximum: number, round: (value: number) => number) => BoundedNumericType<T, number>;

package/dist/float/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFloatType = void 0;
+/**
+ * Machinery shared by the three binary floating point types.
+ *
+ * A float type is fully described by one function: the rounding from a double
+ * to its own format. Everything else follows from a result proved by Figueroa
+ * (1995): when the wider format has at least 2p + 2 bits of precision, an
+ * addition, subtraction, multiplication or division computed in the wider
+ * format and then rounded to the narrower one is correctly rounded. A double
+ * carries 53 bits; single precision needs 2·24 + 2 = 50 and half precision
+ * 2·11 + 2 = 24. So each operation below is the double operation, rounded once.
+ *
+ * The remainder needs no such argument — it is always exact.
+ */
+/**
+ * Builds the descriptor of a float format.
+ *
+ * @param name Name of the type, as it reads in an error message.
+ * @param maximum Largest finite value of the format. The smallest is its
+ * negation, since a float's range is symmetric about zero.
+ * @param round Rounding of a double to the nearest value of the format, ties to
+ * even.
+ * @returns The descriptor.
+ */
+const createFloatType = (name, maximum, round) => ({
+    name,
+    minimum: -maximum,
+    maximum: maximum,
+    from: (value) => {
+        // A `bigint` is refused rather than converted: turning it into a double
+        // first and then into the format rounds twice, and the second rounding
+        // can land on the wrong neighbour.
+        if (typeof value !== 'number') {
+            throw new TypeError(`${name}.from: expected a number, received ${typeof value}.`);
+        }
+        return round(value);
+    },
+    is: (value) => typeof value === 'number' &&
+        (Number.isNaN(value) || Object.is(round(value), value)),
+    add: (left, right) => round(left + right),
+    subtract: (left, right) => round(left - right),
+    multiply: (left, right) => round(left * right),
+    divide: (left, right) => round(left / right),
+    remainder: (left, right) => round(left % right),
+    // Unlike the four above, `Math.pow` is not correctly rounded even in double
+    // precision, so the result is the platform's double power rounded once into
+    // the format: faithful, and not promised to be the nearest.
+    power: (base, exponent) => round(base ** exponent),
+    // Exact in every format: only the sign bit changes.
+    negate: (value) => -value,
+    increment: (value) => round(value + 1),
+    decrement: (value) => round(value - 1),
+    equals: (left, right) => left === right,
+    lessThan: (left, right) => left < right,
+    lessThanOrEqual: (left, right) => left <= right,
+    greaterThan: (left, right) => left > right,
+    greaterThanOrEqual: (left, right) => left >= right,
+});
+exports.createFloatType = createFloatType;

package/dist/halfPrecisionFloat/index.d.ts

@@ -0,0 +1,20 @@
+import type { Branded } from '../brand/index.js';
+import type { Layout } from '../layout/index.js';
+import type { BoundedNumericType } from '../numericType/index.js';
+/**
+ * An IEEE 754 binary16 value: 11 bits of precision, 5 of exponent, finite from
+ * -65504 to 65504.
+ *
+ * Carried by a `number` holding a value the format can represent exactly.
+ * Converting rounds to the nearest such value, ties to even.
+ */
+export type HalfPrecisionFloat = Branded<number, 'HalfPrecisionFloat'> & Layout<2, 2>;
+/**
+ * The descriptor of {@link HalfPrecisionFloat}.
+ *
+ * ```ts
+ * HalfPrecisionFloat.from(0.1); // 0.0999755859375
+ * HalfPrecisionFloat.from(65520); // Infinity
+ * ```
+ */
+export declare const HalfPrecisionFloat: BoundedNumericType<HalfPrecisionFloat, number>;

package/dist/halfPrecisionFloat/index.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HalfPrecisionFloat = void 0;
+const float_1 = require("../float/index.js");
+/**
+ * The point from which a double rounds to infinity rather than to 65504, the
+ * largest finite value: halfway to 65536, which is where the next value would be if
+ * the exponent had room. Exactly halfway is a tie, and it goes to 65536 —
+ * whose significand is even — and therefore to infinity.
+ */
+const OVERFLOW_THRESHOLD = 65520;
+/** Exponent of the smallest normal half precision value, 2^-14. */
+const MINIMUM_NORMAL_EXPONENT = -14;
+/** Bits of the significand after the leading one. */
+const FRACTION_BITS = 10;
+/**
+ * Rounds a double to the nearest half precision value, ties to even.
+ *
+ * Written here rather than delegated to `Math.f16round`, which Node 22 — the
+ * oldest line this package supports — does not have. The method is the one the
+ * format implies: find the spacing of half precision values around the input,
+ * which is a power of two, express the input in units of it, and round that to
+ * an integer. Dividing by a power of two is exact in a double, so the only
+ * rounding is the one being performed.
+ *
+ * @param value Double to round.
+ * @returns The nearest half precision value, as a double.
+ */
+const roundToHalfPrecision = (value) => {
+    // NaN, both infinities and both zeros are their own half precision value.
+    if (!Number.isFinite(value) || value === 0)
+        return value;
+    const magnitude = Math.abs(value);
+    const sign = value < 0 ? -1 : 1;
+    if (magnitude >= OVERFLOW_THRESHOLD)
+        return sign * Infinity;
+    // `Math.log2` is not exact next to a power of two, so the estimate is
+    // corrected against the power itself.
+    let exponent = Math.floor(Math.log2(magnitude));
+    if (2 ** exponent > magnitude)
+        exponent--;
+    else if (2 ** (exponent + 1) <= magnitude)
+        exponent++;
+    // Below the normal range the spacing stops shrinking: that is what makes
+    // the subnormals evenly spaced at 2^-24.
+    const spacing = 2 ** (Math.max(exponent, MINIMUM_NORMAL_EXPONENT) - FRACTION_BITS);
+    const units = magnitude / spacing;
+    // `Math.round` breaks a tie upwards; a tie on an odd count goes back down,
+    // which is what makes it ties to even.
+    let rounded = Math.round(units);
+    if (rounded - units === 0.5 && rounded % 2 !== 0)
+        rounded--;
+    return sign * rounded * spacing;
+};
+/**
+ * The descriptor of {@link HalfPrecisionFloat}.
+ *
+ * ```ts
+ * HalfPrecisionFloat.from(0.1); // 0.0999755859375
+ * HalfPrecisionFloat.from(65520); // Infinity
+ * ```
+ */
+exports.HalfPrecisionFloat = (0, float_1.createFloatType)('HalfPrecisionFloat', 65504, roundToHalfPrecision);

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Public entry point of the package, matching the `main` and `types` fields of
+ * `package.json`.
+ *
+ * Listed one by one rather than re-exported wholesale, so that adding an export
+ * to a module below is never enough on its own to put it in front of consumers.
+ * The modules export more than this — `createIntegerType`, the parts and the
+ * rounding of `Decimal` — and none of it is a promise.
+ *
+ * Every type here has a value of the same name beside it. A consumer who wants
+ * only the types imports them with `import type` and takes no code at all.
+ */
+export { BigInteger } from './bigInteger/index.js';
+export { Decimal } from './decimal/index.js';
+export { DoublePrecisionFloat } from './doublePrecisionFloat/index.js';
+export { HalfPrecisionFloat } from './halfPrecisionFloat/index.js';
+export type { IntegerType, IntegerWidth } from './integer/index.js';
+export type { BoundedNumericType, NumericType } from './numericType/index.js';
+export type { RoundingMode } from './roundingMode/index.js';
+export { SignedInteger } from './signedInteger/index.js';
+export { SinglePrecisionFloat } from './singlePrecisionFloat/index.js';
+export { UnsignedInteger } from './unsignedInteger/index.js';