@fulcro/types 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 diguu <rodrigogeribola@hotmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @fulcro/types
+
+Numeric types with a declared range and layout: fixed-width integers, half,
+single and double precision floats, an integer of any size, and a `Decimal` with
+the semantics of IEEE 754 decimal128 — with the JavaScript operators working on
+every one of them once the plugin is wired up.
+
+```sh
+npm install @fulcro/types
+```
+
+```ts
+import { Decimal, SignedInteger, UnsignedInteger } from '@fulcro/types';
+
+const Int32 = SignedInteger(32);
+
+Int32.add(Int32.from(2), Int32.from(3)); // 5
+Int32.add(Int32.maximum, Int32.from(1)); // RangeError: outside [-2147483648, 2147483647]
+UnsignedInteger(8).wrap(-1); // 255, when modular arithmetic is what you mean
+
+Decimal.from('0.1').add(Decimal.from('0.2')).toString(); // '0.3'
+Decimal.from('19.99').multiply(Decimal.from(3)).toString(); // '59.97'
+```
+
+| Type                                         | What it is                                         |
+| -------------------------------------------- | -------------------------------------------------- |
+| `SignedInteger<N>`, `UnsignedInteger<N>`     | 8 to 128 bits, checked arithmetic, `wrap`          |
+| `HalfPrecisionFloat`, `SinglePrecisionFloat` | binary16 and binary32, each operation rounded once |
+| `DoublePrecisionFloat`                       | binary64, the `number` named as a choice           |
+| `BigInteger`                                 | an integer of any size                             |
+| `Decimal`                                    | 34 decimal digits, five rounding modes             |
+
+Each type has a value of the same name that converts, recognises and computes,
+and every type but `BigInteger` reports its `minimum` and `maximum`. If you only
+need the types, `import type` them and no code is loaded.
+
+## Operators
+
+With the plugin, the operators mean what the type means — checked on an
+integer, rounded on a float, decimal128 on a `Decimal` — and the result keeps
+its type. Both operands have to be the same type, or it is a type error at the
+line:
+
+```ts
+const total = price * Decimal.from(3); // Decimal
+count++; // SignedInteger<32>.increment, checked
+a + 1; // type error: 'number' is not 'SignedInteger<32>'
+```
+
+| Tool       | Wire in                                                                                  |
+| ---------- | ---------------------------------------------------------------------------------------- |
+| `tsc`      | `{ "transform": "@fulcro/types/transformer", "transformProgram": true }`, via `ts-patch` |
+| A bundler  | `vite` (or `rollup`, `webpack`, `esbuild`, …) from `@fulcro/types/unplugin`              |
+| The editor | `{ "name": "@fulcro/types/language-service" }` in the tsconfig `plugins`                 |
+
+Without it, the operators are the language's own: unchecked on the
+`number`-backed types, refused on a `Decimal`.
+
+Every type but `BigInteger` declares a size and alignment, which
+`sizeOf<T>()` and `alignOf<T>()` from `@fulcro/reflect` read at compile time.
+
+---
+
+**Full guide:** [docs/types.md](../../docs/types.md) — ranges, rounding, the
+operators, the special values and the layout table.
+🇧🇷 [Leia em português](../../docs/pt-BR/types.md).

package/dist/bigInteger/index.d.ts

@@ -0,0 +1,27 @@
+import type { Branded } from '../brand/index.js';
+import type { NumericType } from '../numericType/index.js';
+/**
+ * An integer of any size.
+ *
+ * Carried by a `bigint`, which is exact at every magnitude, and branded like
+ * every other numeric type here: a `BigInteger` is a `bigint` that went through
+ * {@link BigInteger.from}, not any `bigint` at all. That is what lets the
+ * operators be rewritten for this type and left alone on every other `bigint`
+ * of a program.
+ *
+ * It is also the one numeric type here with no fixed layout — its size is the
+ * size of its value — which is why `sizeOf<BigInteger>()` is a type error.
+ */
+export type BigInteger = Branded<bigint, 'BigInteger'>;
+/**
+ * The descriptor of {@link BigInteger}.
+ *
+ * ```ts
+ * BigInteger.from('123456789012345678901234567890'); // 123456789012345678901234567890n
+ * BigInteger.from(1.5); // RangeError: expected an integer
+ * ```
+ *
+ * Nothing overflows, so the arithmetic throws only on a zero divisor and on a
+ * negative exponent.
+ */
+export declare const BigInteger: NumericType<BigInteger, number | bigint | string>;

package/dist/bigInteger/index.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BigInteger = void 0;
+/** Integer literal accepted by {@link BigInteger.from}: decimal digits only. */
+const INTEGER_LITERAL = /^[+-]?\d+$/;
+/**
+ * Refuses a zero divisor with the operation named.
+ *
+ * @param operation Operation being performed.
+ * @param divisor Divisor it was handed.
+ */
+const requireDivisor = (operation, divisor) => {
+    if (divisor === 0n) {
+        throw new RangeError(`BigInteger.${operation}: division by zero.`);
+    }
+};
+/**
+ * The descriptor of {@link BigInteger}.
+ *
+ * ```ts
+ * BigInteger.from('123456789012345678901234567890'); // 123456789012345678901234567890n
+ * BigInteger.from(1.5); // RangeError: expected an integer
+ * ```
+ *
+ * Nothing overflows, so the arithmetic throws only on a zero divisor and on a
+ * negative exponent.
+ */
+exports.BigInteger = {
+    name: 'BigInteger',
+    from: (value) => {
+        if (typeof value === 'bigint')
+            return value;
+        if (typeof value === 'number') {
+            if (!Number.isInteger(value)) {
+                throw new RangeError(`BigInteger.from: expected an integer, received ${value}.`);
+            }
+            return BigInt(value);
+        }
+        if (typeof value === 'string') {
+            // `BigInt` alone would also take `0x1f`, `0b101` and surrounding
+            // whitespace. A decimal type accepting a hexadecimal string is a
+            // surprise nobody reading `from('0x10')` expects to be 16.
+            if (!INTEGER_LITERAL.test(value)) {
+                throw new SyntaxError(`BigInteger.from: expected decimal digits with an optional sign, received ${JSON.stringify(value)}.`);
+            }
+            return BigInt(value);
+        }
+        throw new TypeError(`BigInteger.from: expected a number, a bigint or a string, received ${typeof value}.`);
+    },
+    is: (value) => typeof value === 'bigint',
+    add: (left, right) => (left + right),
+    subtract: (left, right) => (left - right),
+    multiply: (left, right) => (left * right),
+    divide: (left, right) => {
+        requireDivisor('divide', right);
+        return (left / right);
+    },
+    remainder: (left, right) => {
+        requireDivisor('remainder', right);
+        return (left % right);
+    },
+    power: (base, exponent) => {
+        if (exponent < 0n) {
+            throw new RangeError(`BigInteger.power: expected an exponent of zero or more, received ${exponent}n.`);
+        }
+        return (base ** exponent);
+    },
+    negate: (value) => -value,
+    increment: (value) => (value + 1n),
+    decrement: (value) => (value - 1n),
+    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,
+};

package/dist/brand/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Key of the brand, declared and never defined.
+ *
+ * A `unique symbol` rather than a string so that no consumer can spell the
+ * brand by hand: the only way to hold a `SignedInteger<32>` is to be given one
+ * by the function that checked it.
+ */
+declare const brand: unique symbol;
+/**
+ * A primitive tagged, at the type level only, with the name of the numeric type
+ * it was checked against.
+ *
+ * Nothing of this exists at runtime — a branded `number` is a `number` — which is
+ * what lets a consumer take only the types of this package and pay for no code.
+ * The price is that the brand does not survive arithmetic written with the
+ * operators: `a + b` is a plain `number` again, and has to go back through the
+ * type's own `add` to be one of ours.
+ *
+ * @template TBase Primitive that carries the value.
+ * @template TName Name of the numeric type the value was checked against.
+ */
+export type Branded<TBase, TName extends string> = TBase & {
+    readonly [brand]: TName;
+};
+export {};

package/dist/brand/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/decimal/arithmetic.d.ts

@@ -0,0 +1,99 @@
+import type { RoundingMode } from '../roundingMode/index.js';
+import { type DecimalParts } from './parts';
+/**
+ * The operations of `Decimal`, on parts.
+ *
+ * Each one computes an exact result on integers and hands it to `finish`, which
+ * rounds it into the format once. The care is in keeping "exact" affordable: a
+ * decimal128 exponent spans more than twelve thousand powers of ten, and an
+ * operation that aligned two operands by multiplying one of them out would
+ * build a twelve-thousand-digit integer to add 1 to 10^6000. None of the
+ * operations below lets an intermediate grow past about a hundred digits,
+ * whatever the exponents, and the performance suite holds them to it.
+ */
+/**
+ * Adds two values.
+ *
+ * @param left First operand.
+ * @param right Second operand.
+ * @param mode Rounding mode.
+ * @returns The rounded sum.
+ */
+export declare const addParts: (left: DecimalParts, right: DecimalParts, mode: RoundingMode) => DecimalParts;
+/**
+ * Multiplies two values.
+ *
+ * The product of two coefficients has at most sixty-eight digits, and the
+ * exponents simply add, so nothing here needs guarding.
+ *
+ * @param left First operand.
+ * @param right Second operand.
+ * @param mode Rounding mode.
+ * @returns The rounded product.
+ */
+export declare const multiplyParts: (left: DecimalParts, right: DecimalParts, mode: RoundingMode) => DecimalParts;
+/**
+ * Divides one value by another.
+ *
+ * The dividend is scaled so that the quotient has thirty-five digits — one
+ * more than the format keeps — and a non-zero remainder is recorded as a
+ * thirty-sixth digit of 1. Those two digits are all the rounding reads, so the
+ * quotient is rounded exactly as the infinitely precise one would be.
+ *
+ * Division by zero follows IEEE 754 rather than throwing: a non-zero value over
+ * zero is an infinity, and zero over zero is not a number.
+ *
+ * @param left Dividend.
+ * @param right Divisor.
+ * @param mode Rounding mode.
+ * @returns The rounded quotient.
+ */
+export declare const divideParts: (left: DecimalParts, right: DecimalParts, mode: RoundingMode) => DecimalParts;
+/**
+ * The remainder of a division truncated towards zero, carrying the sign of the
+ * dividend — what `%` computes on numbers.
+ *
+ * Always exact: the remainder is smaller than the divisor and no finer than the
+ * finer of the two operands, so it always fits the format.
+ *
+ * @param left Dividend.
+ * @param right Divisor.
+ * @returns The remainder.
+ */
+export declare const remainderParts: (left: DecimalParts, right: DecimalParts) => DecimalParts;
+/**
+ * Compares two values in magnitude and sign.
+ *
+ * @param left First operand.
+ * @param right Second operand.
+ * @returns -1, 0 or 1, or `undefined` when either is not a number, which is
+ * ordered against nothing.
+ */
+export declare const compareParts: (left: DecimalParts, right: DecimalParts) => -1 | 0 | 1 | undefined;
+/**
+ * Raises a value to an integer power, with the special cases of IEEE 754's
+ * `pown`: anything to the power zero is one, `NaN` included; a zero or an
+ * infinity to a negative power swaps with the other; and the sign is negative
+ * only for a negative base and an odd power.
+ *
+ * The finite case is computed exactly and rounded once, so the result is the
+ * correctly rounded one — up to {@link EXACT_DIGIT_LIMIT} digits of exact
+ * power, past which it carries {@link GUARD_DIGITS} guard digits instead. A
+ * result that plainly overflows or underflows is settled from its logarithm,
+ * without building a number only to discard it.
+ *
+ * @param base Value raised.
+ * @param power Integer exponent.
+ * @param mode Rounding mode.
+ * @returns The rounded power.
+ */
+export declare const powerParts: (base: DecimalParts, power: bigint, mode: RoundingMode) => DecimalParts;
+/**
+ * Rounds a value to a number of places after the point.
+ *
+ * @param parts Value to round.
+ * @param places Places after the point; negative to round to tens, hundreds…
+ * @param mode Rounding mode.
+ * @returns The rounded value.
+ */
+export declare const roundParts: (parts: DecimalParts, places: number, mode: RoundingMode) => DecimalParts;