@fulcro/types 0.1.0

package/dist/numericType/index.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The runtime side of a numeric type: how a value becomes one, how one is
+ * recognised, and the arithmetic that keeps it one.
+ *
+ * A type is erased on the way to JavaScript, so `SignedInteger<32>` alone cannot
+ * check anything. Each numeric type therefore comes with a descriptor
+ * implementing this contract, and the descriptor carries the same name as the
+ * type:
+ *
+ * ```ts
+ * const Int32 = SignedInteger(32);
+ * const total: SignedInteger<32> = Int32.add(Int32.from(1), Int32.from(2));
+ * ```
+ *
+ * The arithmetic is here, rather than left to the operators, because the
+ * operators cannot keep the type's promise: `a + b` on two 32-bit integers is a
+ * `number` that may no longer fit in 32 bits, and on two single precision
+ * floats it is a double precision result nobody rounded. Every operation below
+ * returns a value of the type or throws.
+ *
+ * @template T Type of the values this descriptor produces.
+ * @template TSource What `from` accepts.
+ */
+export interface NumericType<T, TSource> {
+    /** Name of the type, as it reads in an error message. */
+    readonly name: string;
+    /**
+     * Converts a value into this type.
+     *
+     * @param value Value to convert.
+     * @returns The value, as this type.
+     * @throws {RangeError} When the value cannot be represented, for the types
+     * that refuse rather than round.
+     * @throws {TypeError} When the value is not of an accepted kind.
+     */
+    from(value: TSource): T;
+    /**
+     * Tells whether a value already is of this type.
+     *
+     * @param value Value to inspect.
+     * @returns `true` when `from` would return the value unchanged.
+     */
+    is(value: unknown): value is T;
+    /**
+     * Adds two values.
+     *
+     * @param left First operand.
+     * @param right Second operand.
+     * @returns The sum, as this type.
+     */
+    add(left: T, right: T): T;
+    /**
+     * Subtracts one value from another.
+     *
+     * @param left Value subtracted from.
+     * @param right Value subtracted.
+     * @returns The difference, as this type.
+     */
+    subtract(left: T, right: T): T;
+    /**
+     * Multiplies two values.
+     *
+     * @param left First operand.
+     * @param right Second operand.
+     * @returns The product, as this type.
+     */
+    multiply(left: T, right: T): T;
+    /**
+     * Divides one value by another.
+     *
+     * @param left Dividend.
+     * @param right Divisor.
+     * @returns The quotient, as this type.
+     */
+    divide(left: T, right: T): T;
+    /**
+     * The remainder of a division, carrying the sign of the dividend as `%`
+     * does.
+     *
+     * @param left Dividend.
+     * @param right Divisor.
+     * @returns The remainder, as this type.
+     */
+    remainder(left: T, right: T): T;
+    /**
+     * Raises a value to a power, as `**` does.
+     *
+     * @param base Value raised.
+     * @param exponent Power it is raised to, of the same type.
+     * @returns The power, as this type.
+     * @throws {RangeError} For an integer type, on a negative exponent or a
+     * result outside the range.
+     */
+    power(base: T, exponent: T): T;
+    /**
+     * The value with its sign flipped, as unary `-` does.
+     *
+     * @param value Value negated.
+     * @returns The negation, as this type.
+     * @throws {RangeError} For an integer type whose range cannot hold it: the
+     * minimum of a signed type, and anything but zero of an unsigned one.
+     */
+    negate(value: T): T;
+    /**
+     * The value plus one, as `++` computes it.
+     *
+     * @param value Value incremented.
+     * @returns The next value, as this type.
+     */
+    increment(value: T): T;
+    /**
+     * The value minus one, as `--` computes it.
+     *
+     * @param value Value decremented.
+     * @returns The previous value, as this type.
+     */
+    decrement(value: T): T;
+    /**
+     * Tells whether two values are equal, as `===` does: `NaN` equals nothing,
+     * and `0` equals `-0`.
+     *
+     * @param left First operand.
+     * @param right Second operand.
+     * @returns `true` when they are equal.
+     */
+    equals(left: T, right: T): boolean;
+    /**
+     * @param left First operand.
+     * @param right Second operand.
+     * @returns `true` when `left` is smaller, as `<` answers.
+     */
+    lessThan(left: T, right: T): boolean;
+    /**
+     * @param left First operand.
+     * @param right Second operand.
+     * @returns `true` when `left` is smaller or equal, as `<=` answers.
+     */
+    lessThanOrEqual(left: T, right: T): boolean;
+    /**
+     * @param left First operand.
+     * @param right Second operand.
+     * @returns `true` when `left` is larger, as `>` answers.
+     */
+    greaterThan(left: T, right: T): boolean;
+    /**
+     * @param left First operand.
+     * @param right Second operand.
+     * @returns `true` when `left` is larger or equal, as `>=` answers.
+     */
+    greaterThanOrEqual(left: T, right: T): boolean;
+}
+/**
+ * A numeric type with a largest and a smallest value: every type here except
+ * `BigInteger`, whose values are as large as memory allows.
+ *
+ * `minimum` is the most negative finite value, not the smallest positive one —
+ * the meaning `Number.MIN_VALUE` gives the name, and the one that makes a
+ * range check with it wrong. For an unsigned integer it is zero.
+ *
+ * ```ts
+ * HalfPrecisionFloat.maximum; // 65504
+ * HalfPrecisionFloat.minimum; // -65504
+ * UnsignedInteger(8).minimum; // 0
+ * ```
+ *
+ * @template T Type of the values this descriptor produces.
+ * @template TSource What `from` accepts.
+ */
+export interface BoundedNumericType<T, TSource> extends NumericType<T, TSource> {
+    /** Smallest finite value of the type. */
+    readonly minimum: T;
+    /** Largest finite value of the type. */
+    readonly maximum: T;
+}

package/dist/numericType/index.js

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

package/dist/roundingMode/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How a value that falls between two representable ones is resolved.
+ *
+ * The five rounding directions IEEE 754 defines, spelled out:
+ *
+ * | Mode                 | Resolves to                                     | IEEE 754                 |
+ * | -------------------- | ----------------------------------------------- | ------------------------ |
+ * | `'ceiling'`          | the neighbour towards +∞                        | roundTowardPositive      |
+ * | `'floor'`            | the neighbour towards −∞                        | roundTowardNegative      |
+ * | `'truncate'`         | the neighbour towards zero                      | roundTowardZero          |
+ * | `'halfEven'`         | the nearest, and on a tie the even neighbour    | roundTiesToEven          |
+ * | `'halfAwayFromZero'` | the nearest, and on a tie the one further out   | roundTiesToAway          |
+ *
+ * `'halfEven'` is the default wherever a mode is optional. It is the IEEE
+ * default and the one that does not drift: rounding many ties the same way
+ * biases a sum, and alternating them by parity does not.
+ */
+export type RoundingMode = 'ceiling' | 'floor' | 'truncate' | 'halfEven' | 'halfAwayFromZero';
+/**
+ * Refuses a mode that is not one of {@link RoundingMode}.
+ *
+ * A caller passing `'halfUp'` from untyped code would otherwise be rounded by
+ * whichever branch happened to be the default, silently.
+ *
+ * @param operation Operation being performed, for the message.
+ * @param mode Mode it was handed.
+ * @returns The mode, typed.
+ * @throws {RangeError} When the mode is not recognised.
+ */
+export declare const requireRoundingMode: (operation: string, mode: unknown) => RoundingMode;

package/dist/roundingMode/index.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireRoundingMode = void 0;
+/** Every mode, for validating one that arrived from outside the type system. */
+const ROUNDING_MODES = new Set([
+    'ceiling',
+    'floor',
+    'truncate',
+    'halfEven',
+    'halfAwayFromZero',
+]);
+/**
+ * Refuses a mode that is not one of {@link RoundingMode}.
+ *
+ * A caller passing `'halfUp'` from untyped code would otherwise be rounded by
+ * whichever branch happened to be the default, silently.
+ *
+ * @param operation Operation being performed, for the message.
+ * @param mode Mode it was handed.
+ * @returns The mode, typed.
+ * @throws {RangeError} When the mode is not recognised.
+ */
+const requireRoundingMode = (operation, mode) => {
+    if (typeof mode === 'string' && ROUNDING_MODES.has(mode)) {
+        return mode;
+    }
+    throw new RangeError(`${operation}: expected a rounding mode of ${[...ROUNDING_MODES].join(', ')}, received ${JSON.stringify(mode) ?? String(mode)}.`);
+};
+exports.requireRoundingMode = requireRoundingMode;

package/dist/signedInteger/index.d.ts

@@ -0,0 +1,40 @@
+import type { Branded } from '../brand/index.js';
+import { type ByteSize, type IntegerRepresentation, type IntegerType, type IntegerWidth } from '../integer/index.js';
+import type { Layout } from '../layout/index.js';
+/**
+ * A two's complement integer of `N` bits: from -2^(N-1) to 2^(N-1) - 1.
+ *
+ * ```ts
+ * const index: SignedInteger<32> = SignedInteger(32).from(42);
+ * ```
+ *
+ * Carried by a `number` up to 32 bits and by a `bigint` from 64, so the type of
+ * the value already says which operators it takes. Widths are a parameter, not
+ * a list of names: there is no `SignedInteger32`, and no `i32`.
+ *
+ * A `SignedInteger<8>` is not a `SignedInteger<32>`, even though every value of
+ * one fits in the other. Widening goes through `from`, where it is visible.
+ *
+ * @template N Width, in bits.
+ */
+export type SignedInteger<N extends IntegerWidth> = Branded<IntegerRepresentation<N>, `SignedInteger${N}`> & Layout<ByteSize<N>, ByteSize<N>>;
+/**
+ * The descriptor of a signed integer width: conversion, recognition and checked
+ * arithmetic.
+ *
+ * ```ts
+ * const Int32 = SignedInteger(32);
+ *
+ * Int32.from(2 ** 31); // RangeError: outside [-2147483648, 2147483647]
+ * Int32.wrap(2 ** 31); // -2147483648
+ * Int32.add(Int32.maximum, Int32.from(1)); // RangeError
+ * ```
+ *
+ * Calling it twice with the same width returns the same object.
+ *
+ * @template N Width, in bits.
+ * @param width Width, in bits.
+ * @returns The descriptor of that width.
+ * @throws {RangeError} When the width is not 8, 16, 32, 64 or 128.
+ */
+export declare const SignedInteger: <N extends IntegerWidth>(width: N) => IntegerType<SignedInteger<N>>;

package/dist/signedInteger/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignedInteger = void 0;
+const integer_1 = require("../integer/index.js");
+/** Descriptors already built, so a width is described by one object. */
+const descriptors = new Map();
+/**
+ * The descriptor of a signed integer width: conversion, recognition and checked
+ * arithmetic.
+ *
+ * ```ts
+ * const Int32 = SignedInteger(32);
+ *
+ * Int32.from(2 ** 31); // RangeError: outside [-2147483648, 2147483647]
+ * Int32.wrap(2 ** 31); // -2147483648
+ * Int32.add(Int32.maximum, Int32.from(1)); // RangeError
+ * ```
+ *
+ * Calling it twice with the same width returns the same object.
+ *
+ * @template N Width, in bits.
+ * @param width Width, in bits.
+ * @returns The descriptor of that width.
+ * @throws {RangeError} When the width is not 8, 16, 32, 64 or 128.
+ */
+const SignedInteger = (width) => {
+    let descriptor = descriptors.get(width);
+    if (descriptor === undefined) {
+        descriptor = (0, integer_1.createIntegerType)(true, width, `SignedInteger<${width}>`);
+        descriptors.set(width, descriptor);
+    }
+    return descriptor;
+};
+exports.SignedInteger = SignedInteger;

package/dist/singlePrecisionFloat/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 binary32 value: 24 bits of precision, 8 of exponent.
+ *
+ * Carried by a `number` holding a value the format can represent exactly, so it
+ * reads, compares and prints like any other number. Converting rounds to the
+ * nearest such value, ties to even, as `Math.fround` does.
+ */
+export type SinglePrecisionFloat = Branded<number, 'SinglePrecisionFloat'> & Layout<4, 4>;
+/**
+ * The descriptor of {@link SinglePrecisionFloat}.
+ *
+ * ```ts
+ * SinglePrecisionFloat.from(0.1); // 0.10000000149011612
+ * SinglePrecisionFloat.from(1e39); // Infinity
+ * ```
+ */
+export declare const SinglePrecisionFloat: BoundedNumericType<SinglePrecisionFloat, number>;

package/dist/singlePrecisionFloat/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SinglePrecisionFloat = void 0;
+const float_1 = require("../float/index.js");
+/**
+ * The descriptor of {@link SinglePrecisionFloat}.
+ *
+ * ```ts
+ * SinglePrecisionFloat.from(0.1); // 0.10000000149011612
+ * SinglePrecisionFloat.from(1e39); // Infinity
+ * ```
+ */
+exports.SinglePrecisionFloat = (0, float_1.createFloatType)('SinglePrecisionFloat', 
+// (2 - 2^-23) × 2^127
+3.4028234663852886e38, Math.fround);

package/dist/transformer/classify/index.d.ts

@@ -0,0 +1,39 @@
+import typescript from 'typescript';
+/**
+ * Which of this package's numeric types a checker type is, if any.
+ *
+ * The rewrite of the operators must claim only this package's types. A
+ * consumer's own `number` and `bigint` arithmetic is none of its business, and
+ * a brand that merely looks like ours — a property with the same name in some
+ * other library — is not ours either. So a type is recognised by where its
+ * brand was **declared**: the `brand` module of this package, as source in this
+ * repository and as `dist` in a consumer's `node_modules`.
+ */
+/** How the operators of one numeric type are written out. */
+export type NumericKind = {
+    /** Called through a descriptor: `SignedInteger(32).add(a, b)`. */
+    readonly family: 'descriptor';
+    /** The descriptor, as an expression under the namespace import. */
+    readonly descriptor: string;
+    /** Whether the bit operators apply. */
+    readonly integer: boolean;
+    /** Name of the brand, which tells two kinds apart. */
+    readonly name: string;
+} | {
+    /** Called as methods of the value: `a.add(b)`. */
+    readonly family: 'decimal';
+    readonly name: 'Decimal';
+};
+/**
+ * Classifies a type.
+ *
+ * A union is never one of ours, even a union of our types: `SignedInteger<8> |
+ * SignedInteger<16>` has no one descriptor to call, and `Decimal | undefined`
+ * has to be narrowed first, which the checker already insists on.
+ *
+ * @param type Type to classify.
+ * @param checker Checker of the program.
+ * @param location Node the type was read at.
+ * @returns The kind, or `null` when the type is not one of this package's.
+ */
+export declare const classify: (type: typescript.Type, checker: typescript.TypeChecker, location: typescript.Node) => NumericKind | null;

package/dist/transformer/classify/index.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classify = void 0;
+/** The module declaring the brand every primitive-backed type carries. */
+const BRAND_MODULE = /\/types\/(?:dist|src)\/brand\/index\.(?:d\.)?ts$/;
+/** The module declaring `Decimal`. */
+const DECIMAL_MODULE = /\/types\/(?:dist|src)\/decimal\/index\.(?:d\.)?ts$/;
+/** A brand of a fixed-width integer, and its parts. */
+const INTEGER_BRAND = /^(Signed|Unsigned)Integer(8|16|32|64|128)$/;
+/** Brands whose descriptor is a value of the same name. */
+const NAMED_BRANDS = new Set([
+    'HalfPrecisionFloat',
+    'SinglePrecisionFloat',
+    'DoublePrecisionFloat',
+    'BigInteger',
+]);
+/**
+ * Tells whether a declaration was made in a module of this package.
+ *
+ * @param declaration Declaration of a symbol.
+ * @param module Pattern of the module.
+ * @returns `true` when it was.
+ */
+const declaredIn = (declaration, module) => module.test(declaration.getSourceFile().fileName.replace(/\\/g, '/'));
+/**
+ * The kind a brand stands for.
+ *
+ * @param brand Value of the brand property.
+ * @returns The kind, or `null` for a brand this rewrite does not know.
+ */
+const kindOfBrand = (brand) => {
+    const integer = INTEGER_BRAND.exec(brand);
+    if (integer !== null) {
+        return {
+            family: 'descriptor',
+            descriptor: `${integer[1]}Integer(${integer[2]})`,
+            integer: true,
+            name: brand,
+        };
+    }
+    if (NAMED_BRANDS.has(brand)) {
+        return {
+            family: 'descriptor',
+            descriptor: brand,
+            integer: false,
+            name: brand,
+        };
+    }
+    return null;
+};
+/**
+ * Classifies a type.
+ *
+ * A union is never one of ours, even a union of our types: `SignedInteger<8> |
+ * SignedInteger<16>` has no one descriptor to call, and `Decimal | undefined`
+ * has to be narrowed first, which the checker already insists on.
+ *
+ * @param type Type to classify.
+ * @param checker Checker of the program.
+ * @param location Node the type was read at.
+ * @returns The kind, or `null` when the type is not one of this package's.
+ */
+const classify = (type, checker, location) => {
+    if (type.isUnion())
+        return null;
+    const symbol = type.getSymbol();
+    if (symbol?.getName() === 'Decimal' &&
+        (symbol.declarations ?? []).some((declaration) => declaredIn(declaration, DECIMAL_MODULE))) {
+        return { family: 'decimal', name: 'Decimal' };
+    }
+    for (const property of checker.getPropertiesOfType(type)) {
+        // The brand is keyed by a unique symbol, which the checker names
+        // `__@brand@<id>`; the declaration settles whose it is.
+        if (!String(property.escapedName).startsWith('__@'))
+            continue;
+        const ours = (property.declarations ?? []).some((declaration) => declaredIn(declaration, BRAND_MODULE));
+        if (!ours)
+            continue;
+        const brand = checker.getTypeOfSymbolAtLocation(property, location);
+        return brand.isStringLiteral() ? kindOfBrand(brand.value) : null;
+    }
+    return null;
+};
+exports.classify = classify;

package/dist/transformer/index.d.ts

@@ -0,0 +1,27 @@
+import { type ProgramTransformer } from '@fulcro/transform-core';
+/**
+ * The `tsc` plugin giving the operators their meaning on this package's
+ * numeric types.
+ *
+ * A program transformer, not an ordinary one, and the tsconfig entry has to say
+ * so: the rewrite must happen before the program is type checked, or
+ * `decimal * decimal` has been reported as an error before anything could
+ * rewrite it. Wire it through `ts-patch`:
+ *
+ * ```json
+ * {
+ * 	"compilerOptions": {
+ * 		"plugins": [{ "transform": "@fulcro/types/transformer", "transformProgram": true }]
+ * 	}
+ * }
+ * ```
+ *
+ * For a bundler use `@fulcro/types/unplugin`, and for the editor
+ * `@fulcro/types/language-service`.
+ *
+ * Without it, the operators are the language's own: a primitive-backed type
+ * does plain, unchecked arithmetic on its `number` or `bigint`, and a `Decimal`
+ * is refused by the checker and throws at runtime.
+ */
+declare const transformer: ProgramTransformer;
+export default transformer;

package/dist/transformer/index.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const transform_core_1 = require("@fulcro/transform-core");
+const rewriter_1 = require("./rewriter/index.js");
+/**
+ * The `tsc` plugin giving the operators their meaning on this package's
+ * numeric types.
+ *
+ * A program transformer, not an ordinary one, and the tsconfig entry has to say
+ * so: the rewrite must happen before the program is type checked, or
+ * `decimal * decimal` has been reported as an error before anything could
+ * rewrite it. Wire it through `ts-patch`:
+ *
+ * ```json
+ * {
+ * 	"compilerOptions": {
+ * 		"plugins": [{ "transform": "@fulcro/types/transformer", "transformProgram": true }]
+ * 	}
+ * }
+ * ```
+ *
+ * For a bundler use `@fulcro/types/unplugin`, and for the editor
+ * `@fulcro/types/language-service`.
+ *
+ * Without it, the operators are the language's own: a primitive-backed type
+ * does plain, unchecked arithmetic on its `number` or `bigint`, and a `Decimal`
+ * is refused by the checker and throws at runtime.
+ */
+const transformer = (0, transform_core_1.createProgramTransformer)(rewriter_1.OPERATOR_REWRITER);
+exports.default = transformer;

package/dist/transformer/rewriter/index.d.ts

@@ -0,0 +1,3 @@
+import { type ExpressionRewriter } from '@fulcro/transform-core';
+/** The rewriter of the operators on this package's numeric types. */
+export declare const OPERATOR_REWRITER: ExpressionRewriter;