@fulcro/types 0.1.0 → 0.3.0

package/dist/struct/codec.js

@@ -0,0 +1,325 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codecOf = exports.registerStructCodec = void 0;
+const decimal_1 = require("../decimal/index.js");
+const format_1 = require("../decimal/format.js");
+const parse_1 = require("../decimal/parse.js");
+const parts_1 = require("../decimal/parts.js");
+const doublePrecisionFloat_1 = require("../doublePrecisionFloat/index.js");
+const halfPrecisionFloat_1 = require("../halfPrecisionFloat/index.js");
+const signedInteger_1 = require("../signedInteger/index.js");
+const singlePrecisionFloat_1 = require("../singlePrecisionFloat/index.js");
+const unsignedInteger_1 = require("../unsignedInteger/index.js");
+/** Bits of a 64-bit half of a 128-bit value. */
+const HALF_WIDTH = 64n;
+/**
+ * The codec of a 128-bit integer, as two 64-bit halves, low half first.
+ *
+ * @param descriptor Descriptor of the width.
+ * @returns The codec.
+ */
+const integer128Codec = (descriptor) => ({
+    size: 16,
+    alignment: 16,
+    read: (view, offset) => {
+        const low = view.getBigUint64(offset, true);
+        const high = descriptor.signed
+            ? view.getBigInt64(offset + 8, true)
+            : view.getBigUint64(offset + 8, true);
+        return (high << HALF_WIDTH) | low;
+    },
+    write: (view, offset, value) => {
+        view.setBigUint64(offset, BigInt.asUintN(64, value), true);
+        view.setBigUint64(offset + 8, BigInt.asUintN(64, value >> HALF_WIDTH), true);
+    },
+    equals: (left, right) => descriptor.equals(left, right),
+});
+/**
+ * The codec of a fixed-width integer, through the `DataView` accessor of its
+ * width, or two of them at 128 bits.
+ *
+ * @param descriptor Descriptor of the width.
+ * @returns The codec.
+ */
+const integerCodec = (descriptor) => {
+    const { signed, width } = descriptor;
+    if (width === 128)
+        return integer128Codec(descriptor);
+    const size = width / 8;
+    const equals = (left, right) => descriptor.equals(left, right);
+    switch (width) {
+        case 8:
+            return {
+                size,
+                alignment: size,
+                read: (view, offset) => signed ? view.getInt8(offset) : view.getUint8(offset),
+                write: (view, offset, value) => signed
+                    ? view.setInt8(offset, value)
+                    : view.setUint8(offset, value),
+                equals,
+            };
+        case 16:
+            return {
+                size,
+                alignment: size,
+                read: (view, offset) => signed ? view.getInt16(offset, true) : view.getUint16(offset, true),
+                write: (view, offset, value) => signed
+                    ? view.setInt16(offset, value, true)
+                    : view.setUint16(offset, value, true),
+                equals,
+            };
+        case 32:
+            return {
+                size,
+                alignment: size,
+                read: (view, offset) => signed ? view.getInt32(offset, true) : view.getUint32(offset, true),
+                write: (view, offset, value) => signed
+                    ? view.setInt32(offset, value, true)
+                    : view.setUint32(offset, value, true),
+                equals,
+            };
+        default:
+            return {
+                size,
+                alignment: size,
+                read: (view, offset) => signed
+                    ? view.getBigInt64(offset, true)
+                    : view.getBigUint64(offset, true),
+                write: (view, offset, value) => signed
+                    ? view.setBigInt64(offset, value, true)
+                    : view.setBigUint64(offset, value, true),
+                equals,
+            };
+    }
+};
+/** Exponent of the smallest normal half precision value. */
+const HALF_MINIMUM_NORMAL_EXPONENT = -14;
+/** Spacing of the half precision subnormals, 2^-24. */
+const HALF_SUBNORMAL_SPACING = 2 ** -24;
+/**
+ * The binary16 bit pattern of a half precision value.
+ *
+ * Written here rather than delegated to `DataView.prototype.setFloat16`, which
+ * Node 22 — the oldest line this package supports — does not have. The value
+ * is already exactly representable, so every division below is exact and
+ * nothing is rounded: this only rearranges bits.
+ *
+ * @param value A half precision value.
+ * @returns Its sixteen bits.
+ */
+const encodeHalf = (value) => {
+    if (Number.isNaN(value))
+        return 0x7e00;
+    const sign = value < 0 || Object.is(value, -0) ? 0x8000 : 0;
+    const magnitude = Math.abs(value);
+    if (magnitude === Infinity)
+        return sign | 0x7c00;
+    if (magnitude < 2 ** HALF_MINIMUM_NORMAL_EXPONENT) {
+        return sign | (magnitude / HALF_SUBNORMAL_SPACING);
+    }
+    // `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++;
+    return (sign | ((exponent + 15) << 10) | ((magnitude / 2 ** exponent - 1) * 1024));
+};
+/**
+ * The half precision value of a binary16 bit pattern.
+ *
+ * @param bits Sixteen bits.
+ * @returns The value they encode.
+ */
+const decodeHalf = (bits) => {
+    const sign = bits & 0x8000 ? -1 : 1;
+    const exponent = (bits >> 10) & 0x1f;
+    const fraction = bits & 0x3ff;
+    if (exponent === 0)
+        return sign * fraction * HALF_SUBNORMAL_SPACING;
+    if (exponent === 0x1f)
+        return fraction === 0 ? sign * Infinity : NaN;
+    return sign * (1 + fraction / 1024) * 2 ** (exponent - 15);
+};
+/** The codecs of the three binary float formats, by descriptor. */
+const floatCodecs = new Map([
+    [
+        halfPrecisionFloat_1.HalfPrecisionFloat,
+        {
+            size: 2,
+            alignment: 2,
+            read: (view, offset) => decodeHalf(view.getUint16(offset, true)),
+            write: (view, offset, value) => view.setUint16(offset, encodeHalf(value), true),
+            equals: (left, right) => halfPrecisionFloat_1.HalfPrecisionFloat.equals(left, right),
+        },
+    ],
+    [
+        singlePrecisionFloat_1.SinglePrecisionFloat,
+        {
+            size: 4,
+            alignment: 4,
+            read: (view, offset) => view.getFloat32(offset, true),
+            write: (view, offset, value) => view.setFloat32(offset, value, true),
+            equals: (left, right) => singlePrecisionFloat_1.SinglePrecisionFloat.equals(left, right),
+        },
+    ],
+    [
+        doublePrecisionFloat_1.DoublePrecisionFloat,
+        {
+            size: 8,
+            alignment: 8,
+            read: (view, offset) => view.getFloat64(offset, true),
+            write: (view, offset, value) => view.setFloat64(offset, value, true),
+            equals: (left, right) => doublePrecisionFloat_1.DoublePrecisionFloat.equals(left, right),
+        },
+    ],
+]);
+/** Bias of the decimal128 exponent: the stored field is `exponent + 6176`. */
+const DECIMAL_EXPONENT_BIAS = 6176;
+/**
+ * Largest exponent a decimal128 coefficient can be scaled by: the largest
+ * value, thirty-four nines, has its last digit at 10^6111.
+ */
+const DECIMAL_MAXIMUM_EXPONENT = 6111;
+/** Bits of the decimal128 coefficient field. */
+const DECIMAL_COEFFICIENT_BITS = 113n;
+/** The coefficients a decimal128 holds are below this; above it is non-canonical. */
+const DECIMAL_COEFFICIENT_LIMIT = (0, parts_1.powerOfTen)(34);
+/**
+ * The decimal128 bits of a decimal, in the binary integer decimal encoding
+ * IEEE 754-2008 defines: a sign bit, fourteen bits of biased exponent and a
+ * 113-bit binary coefficient.
+ *
+ * The parts are normalised, which can leave a large value with a short
+ * coefficient and an exponent past the one the format stores — 1 × 10^6144.
+ * Those are scaled back into range by moving digits into the coefficient,
+ * which always has room for them because the value is within range.
+ *
+ * @param parts The value.
+ * @returns Its 128 bits.
+ */
+const encodeDecimal = (parts) => {
+    const sign = parts.negative ? 1n << 127n : 0n;
+    if (parts.kind === 'nan')
+        return 0x7c00000000000000n << HALF_WIDTH;
+    if (parts.kind === 'infinity') {
+        return sign | (0x7800000000000000n << HALF_WIDTH);
+    }
+    let { coefficient, exponent } = parts;
+    if (exponent > DECIMAL_MAXIMUM_EXPONENT) {
+        coefficient *= (0, parts_1.powerOfTen)(exponent - DECIMAL_MAXIMUM_EXPONENT);
+        exponent = DECIMAL_MAXIMUM_EXPONENT;
+    }
+    return (sign |
+        (BigInt(exponent + DECIMAL_EXPONENT_BIAS) << DECIMAL_COEFFICIENT_BITS) |
+        coefficient);
+};
+/**
+ * The decimal of decimal128 bits.
+ *
+ * A coefficient past thirty-four digits — including every one written in the
+ * encoding's second form, whose leading bits are `11` — is non-canonical, and
+ * IEEE 754 reads it as zero. Trailing zeros are moved into the exponent, which
+ * is the normalised form every `Decimal` holds.
+ *
+ * @param bits 128 bits.
+ * @returns The parts they encode.
+ */
+const decodeDecimal = (bits) => {
+    const negative = bits >> 127n === 1n;
+    const combination = (bits >> 122n) & 0x1fn;
+    if (combination === 0x1fn) {
+        return { kind: 'nan', negative: false, coefficient: 0n, exponent: 0 };
+    }
+    if (combination === 0x1en) {
+        return { kind: 'infinity', negative, coefficient: 0n, exponent: 0 };
+    }
+    let coefficient = ((bits >> 125n) & 0x3n) === 0x3n
+        ? 0n
+        : bits & ((1n << DECIMAL_COEFFICIENT_BITS) - 1n);
+    if (coefficient >= DECIMAL_COEFFICIENT_LIMIT)
+        coefficient = 0n;
+    if (coefficient === 0n) {
+        return { kind: 'finite', negative, coefficient: 0n, exponent: 0 };
+    }
+    let exponent = Number((bits >> DECIMAL_COEFFICIENT_BITS) & 0x3fffn) -
+        DECIMAL_EXPONENT_BIAS;
+    while (coefficient % 10n === 0n) {
+        coefficient /= 10n;
+        exponent++;
+    }
+    return { kind: 'finite', negative, coefficient, exponent };
+};
+/**
+ * The codec of `Decimal`, as decimal128.
+ *
+ * Its parts are private to the class, so they travel through its text, which
+ * reads back exactly: the shortest text of a normalised value names exactly
+ * that value.
+ */
+const decimalCodec = {
+    size: 16,
+    alignment: 16,
+    read: (view, offset) => {
+        const bits = (view.getBigUint64(offset + 8, true) << HALF_WIDTH) |
+            view.getBigUint64(offset, true);
+        return decimal_1.Decimal.from((0, format_1.formatDecimal)(decodeDecimal(bits)));
+    },
+    write: (view, offset, value) => {
+        const bits = encodeDecimal((0, parse_1.parseDecimal)(String(value)));
+        view.setBigUint64(offset, BigInt.asUintN(64, bits), true);
+        view.setBigUint64(offset + 8, bits >> HALF_WIDTH, true);
+    },
+    equals: (left, right) => left.equals(right),
+};
+/** Codecs registered by the structs themselves, so one can nest in another. */
+const structCodecs = new WeakMap();
+/** Widths a fixed-width integer comes in. */
+const INTEGER_WIDTHS = [8, 16, 32, 64, 128];
+/**
+ * Tells whether a value is the descriptor `SignedInteger` or `UnsignedInteger`
+ * returns for its width — the same object, not one shaped like it.
+ *
+ * @param descriptor Value to inspect.
+ * @returns `true` for an integer descriptor of this package.
+ */
+const isIntegerDescriptor = (descriptor) => {
+    const { signed, width } = descriptor;
+    if (typeof signed !== 'boolean' || !INTEGER_WIDTHS.includes(width)) {
+        return false;
+    }
+    const factory = signed ? signedInteger_1.SignedInteger : unsignedInteger_1.UnsignedInteger;
+    return factory(width) === descriptor;
+};
+/**
+ * Registers the codec of a struct, so that another struct can hold it as a
+ * field.
+ *
+ * @param descriptor Descriptor of the struct.
+ * @param codec How it is stored.
+ */
+const registerStructCodec = (descriptor, codec) => {
+    structCodecs.set(descriptor, codec);
+};
+exports.registerStructCodec = registerStructCodec;
+/**
+ * The codec of a field's descriptor.
+ *
+ * @param descriptor What the field was declared with.
+ * @returns Its codec, or `undefined` for a descriptor with no fixed layout.
+ */
+const codecOf = (descriptor) => {
+    if (typeof descriptor !== 'object' && typeof descriptor !== 'function') {
+        return undefined;
+    }
+    if (descriptor === null)
+        return undefined;
+    if (descriptor === decimal_1.Decimal)
+        return decimalCodec;
+    const known = floatCodecs.get(descriptor) ?? structCodecs.get(descriptor);
+    if (known !== undefined)
+        return known;
+    return isIntegerDescriptor(descriptor) ? integerCodec(descriptor) : undefined;
+};
+exports.codecOf = codecOf;

package/dist/struct/index.d.ts

@@ -0,0 +1,206 @@
+import type { Layout } from '../layout/index.js';
+import type { Add, LargestAlignment, RoundUp } from './arithmetic.js';
+/**
+ * What a field of a struct may be declared with: the descriptor of a type that
+ * declares a fixed layout — a numeric type of this package other than
+ * `BigInteger`, or another struct.
+ */
+interface FieldDescriptor {
+    is(value: unknown): value is Layout<number, number>;
+}
+/** The fields of a struct, by name, in declaration order. */
+type StructFields = {
+    readonly [field: string]: FieldDescriptor;
+};
+/** The methods of a struct, by name. */
+type StructMethods = {
+    readonly [method: string]: (...parameters: never[]) => unknown;
+};
+/** What a struct declared without methods has: none. */
+type NoMethods = Record<never, never>;
+/** The type of the values a descriptor recognises. */
+type ValueOf<TDescriptor> = TDescriptor extends {
+    is(value: unknown): value is infer T;
+} ? T : never;
+/** What a descriptor's `from` accepts. */
+type SourceOf<TDescriptor> = TDescriptor extends {
+    from(value: infer TSource): unknown;
+} ? TSource : never;
+/** The layout a field's type declares. */
+type FieldLayout<TDescriptor> = ValueOf<TDescriptor> extends Layout<infer TSize, infer TAlignment> ? {
+    readonly size: TSize;
+    readonly alignment: TAlignment;
+} : never;
+/** A union, as a tuple in no particular order — enough to sum over it. */
+type UnionToTuple<TUnion, TTuple extends unknown[] = []> = [TUnion] extends [
+    never
+] ? TTuple : UnionToTuple<Exclude<TUnion, LastOf<TUnion>>, [LastOf<TUnion>, ...TTuple]>;
+/** One member of a union, picked by how TypeScript orders overloads. */
+type LastOf<TUnion> = (TUnion extends unknown ? (member: () => TUnion) => void : never) extends (member: infer TIntersection) => void ? TIntersection extends () => infer TMember ? TMember : never : never;
+/** The sizes of some fields, added up. */
+type SumOfSizes<TFields extends StructFields, TKeys extends unknown[], TSum extends number = 0> = TKeys extends [infer TKey extends keyof TFields, ...infer TRest] ? SumOfSizes<TFields, TRest, Add<TSum, FieldLayout<TFields[TKey]>['size']>> : TSum;
+/** Alignment of a struct: the largest alignment of its fields. */
+type StructAlignment<TFields extends StructFields> = LargestAlignment<{
+    [TKey in keyof TFields]: FieldLayout<TFields[TKey]>['alignment'];
+}[keyof TFields]>;
+/**
+ * Size of a struct: its fields, which pack without padding once ordered by
+ * alignment, rounded up to its alignment. Independent of the order the fields
+ * were declared in, which is why it can be computed here at all — a type does
+ * not promise an order for its keys.
+ */
+type StructSize<TFields extends StructFields> = RoundUp<SumOfSizes<TFields, UnionToTuple<keyof TFields>>, StructAlignment<TFields>>;
+/** The fields of a value of a struct, and its layout. */
+type StructData<TFields extends StructFields> = {
+    readonly [TKey in keyof TFields]: ValueOf<TFields[TKey]>;
+} & Layout<StructSize<TFields>, StructAlignment<TFields>>;
+/**
+ * A value of a struct: its fields, and its methods when it declares any. A
+ * struct without methods is its fields alone, exactly as before methods
+ * existed, so nothing it inferred changes.
+ */
+type StructValue<TFields extends StructFields, TMethods extends StructMethods = NoMethods> = [keyof TMethods] extends [never] ? StructData<TFields> : StructData<TFields> & Readonly<TMethods>;
+/** What a struct's `from` accepts: each field in what its own `from` accepts. */
+type StructSource<TFields extends StructFields> = {
+    readonly [TKey in keyof TFields]: SourceOf<TFields[TKey]>;
+};
+/**
+ * The descriptor of a struct: its layout, and how its values are made,
+ * recognised, compared and stored.
+ *
+ * @template TFields Descriptors of the fields, by name.
+ * @template TMethods Methods every value carries, by name; none by default.
+ */
+export interface StructType<TFields extends StructFields, TMethods extends StructMethods = NoMethods> {
+    /** Name of the struct, as it reads in an error message. */
+    readonly name: string;
+    /**
+     * Where each field sits and how much room the struct takes.
+     *
+     * Fields are placed by alignment, largest first, and in declaration order
+     * among equals — so no field needs padding before it, and only the end of
+     * the struct is padded, up to its alignment, so that the next one in an
+     * array starts aligned. `size` and `alignment` are the numbers
+     * `sizeOf<T>()` and `alignOf<T>()` report.
+     */
+    readonly layout: {
+        readonly size: StructSize<TFields>;
+        readonly alignment: StructAlignment<TFields>;
+        readonly fields: {
+            readonly [TKey in keyof TFields]: {
+                readonly offset: number;
+                readonly size: FieldLayout<TFields[TKey]>['size'];
+                readonly alignment: FieldLayout<TFields[TKey]>['alignment'];
+            };
+        };
+    };
+    /**
+     * Makes a value, converting each field with its own type's `from`.
+     *
+     * @param source One entry per field, and nothing else.
+     * @returns The value, frozen, carrying the struct's methods.
+     * @throws {TypeError} When a field is missing or not a field of the struct.
+     * @throws {RangeError} When a field's own conversion refuses its value; the
+     * message names the field, and `cause` is the original error.
+     */
+    from(source: StructSource<TFields>): StructValue<TFields, TMethods>;
+    /**
+     * Tells whether a value is one of this struct's: frozen, with exactly its
+     * fields, each of its type — and, when the struct declares methods, made by
+     * this struct, since an object with the right fields alone would not carry
+     * them.
+     *
+     * @param value Value to inspect.
+     * @returns `true` when it is.
+     */
+    is(value: unknown): value is StructValue<TFields, TMethods>;
+    /**
+     * Compares two values field by field, each as its own type compares — so a
+     * `NaN` field makes a value unequal to itself, as it does in C#.
+     *
+     * @param left First value.
+     * @param right Second value.
+     * @returns `true` when every field is equal.
+     */
+    equals(left: StructValue<TFields, TMethods>, right: StructValue<TFields, TMethods>): boolean;
+    /**
+     * Reads a value from bytes, in the layout of {@link StructType.layout},
+     * little-endian.
+     *
+     * @param view Bytes to read from.
+     * @param offset Where the value starts.
+     * @returns The value, frozen, carrying the struct's methods.
+     * @throws {RangeError} When the struct does not fit in the view at that
+     * offset.
+     */
+    read(view: DataView, offset: number): StructValue<TFields, TMethods>;
+    /**
+     * Writes a value into bytes, in the layout of {@link StructType.layout},
+     * little-endian. Padding bytes are left as they were.
+     *
+     * @param view Bytes to write into.
+     * @param offset Where the value starts.
+     * @param value Value to write.
+     * @throws {RangeError} When the struct does not fit in the view at that
+     * offset.
+     */
+    write(view: DataView, offset: number, value: StructValue<TFields, TMethods>): void;
+}
+/**
+ * The type of the values of a struct, named from its descriptor.
+ *
+ * ```ts
+ * export const Vector3 = struct('Vector3', { x: SinglePrecisionFloat, … });
+ * export type Vector3 = Struct<typeof Vector3>;
+ * ```
+ *
+ * @template TDescriptor Type of the descriptor `struct` returned.
+ */
+export type Struct<TDescriptor extends StructType<StructFields, StructMethods>> = TDescriptor extends StructType<infer TFields, infer TMethods> ? StructValue<TFields, TMethods> : never;
+/**
+ * Declares a struct: a value type with a fixed layout.
+ *
+ * ```ts
+ * export const Vector3 = struct('Vector3', {
+ * 	x: SinglePrecisionFloat,
+ * 	y: SinglePrecisionFloat,
+ * 	z: SinglePrecisionFloat,
+ * });
+ * export type Vector3 = Struct<typeof Vector3>;
+ *
+ * const up: Vector3 = Vector3.from({ x: 0, y: 1, z: 0 });
+ *
+ * Vector3.layout.size; // 12
+ * Vector3.write(new DataView(buffer), 0, up);
+ * ```
+ *
+ * A value has no identity: it is frozen, two values with the same fields are
+ * equal by {@link StructType.equals}, and it can be written into bytes and
+ * read back as the same value. It is still a JavaScript object while it is
+ * held as one; the layout is what it occupies when it is stored.
+ *
+ * Methods, when given, are shared by every value through one prototype: they
+ * take no bytes and are not fields, so the layout, `equals` and the bytes are
+ * the same as without them. `this` is the value, which is frozen — a method
+ * that changes something returns a new value:
+ *
+ * ```ts
+ * const Vector3 = struct('Vector3', { x: SinglePrecisionFloat, … }, {
+ * 	length() {
+ * 		return Math.hypot(this.x, this.y, this.z);
+ * 	},
+ * });
+ *
+ * Vector3.from({ x: 3, y: 4, z: 0 }).length(); // 5
+ * ```
+ *
+ * @param name Name of the struct, for error messages.
+ * @param fields Descriptor of each field, by name.
+ * @param methods Function of each method, by name.
+ * @returns The descriptor of the struct.
+ * @throws {TypeError} When there is no field, a field's type has no fixed
+ * layout, a field is named like an array index or `~layout`, or a method is
+ * not a function or is named like a field, an array index or `~layout`.
+ */
+export declare const struct: <TFields extends StructFields, TMethods extends StructMethods = NoMethods>(name: string, fields: TFields, methods?: TMethods & ThisType<StructValue<TFields, TMethods>>) => StructType<TFields, TMethods>;
+export {};