@fulcro/types 0.1.0 → 0.3.0

package/LICENSE

@@ -1,15 +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.
+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

@@ -1,66 +1,86 @@
-# @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).
+# @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.
+
+## Structs
+
+Value types with a fixed layout, built from the types above and from each
+other — frozen, compared by field, and stored in a `DataView` without an object
+per value:
+
+```ts
+import { SinglePrecisionFloat, struct, type Struct } from '@fulcro/types';
+
+const Vector3 = struct('Vector3', {
+	x: SinglePrecisionFloat,
+	y: SinglePrecisionFloat,
+	z: SinglePrecisionFloat,
+});
+type Vector3 = Struct<typeof Vector3>;
+
+Vector3.layout.size; // 12, and sizeOf<Vector3>() at compile time
+Vector3.write(view, 0, Vector3.from({ x: 0, y: 1, z: 0 }));
+```
+
+---
+
+**Full guide:** [docs/types.md](../../docs/types.md) — ranges, rounding, the
+operators, the special values, the layout table and structs.
+🇧🇷 [Leia em português](../../docs/pt-BR/types.md).

package/dist/index.d.ts

@@ -19,4 +19,6 @@ 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 type { Struct, StructType } from './struct/index.js';
+export { struct } from './struct/index.js';
 export { UnsignedInteger } from './unsignedInteger/index.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnsignedInteger = exports.SinglePrecisionFloat = exports.SignedInteger = exports.HalfPrecisionFloat = exports.DoublePrecisionFloat = exports.Decimal = exports.BigInteger = void 0;
+exports.UnsignedInteger = exports.struct = exports.SinglePrecisionFloat = exports.SignedInteger = exports.HalfPrecisionFloat = exports.DoublePrecisionFloat = exports.Decimal = exports.BigInteger = void 0;
 /**
  * Public entry point of the package, matching the `main` and `types` fields of
  * `package.json`.
@@ -25,5 +25,7 @@ var signedInteger_1 = require("./signedInteger/index.js");
 Object.defineProperty(exports, "SignedInteger", { enumerable: true, get: function () { return signedInteger_1.SignedInteger; } });
 var singlePrecisionFloat_1 = require("./singlePrecisionFloat/index.js");
 Object.defineProperty(exports, "SinglePrecisionFloat", { enumerable: true, get: function () { return singlePrecisionFloat_1.SinglePrecisionFloat; } });
+var struct_1 = require("./struct/index.js");
+Object.defineProperty(exports, "struct", { enumerable: true, get: function () { return struct_1.struct; } });
 var unsignedInteger_1 = require("./unsignedInteger/index.js");
 Object.defineProperty(exports, "UnsignedInteger", { enumerable: true, get: function () { return unsignedInteger_1.UnsignedInteger; } });

package/dist/struct/arithmetic.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Arithmetic on number literals, at the type level, for the layout a struct
+ * type declares.
+ *
+ * `sizeOf<T>()` answers from the literal in `T['~layout']`, so a struct type
+ * has to carry its size as a literal, and that literal is a sum of its fields
+ * rounded up to its alignment. TypeScript has no arithmetic on literals; this
+ * module is the smallest amount of it the layout needs.
+ *
+ * Addition works digit by digit on the decimal text of a number, so it is not
+ * bounded by the recursion limit the way counting a tuple up to the sum would
+ * be. Rounding needs a remainder, and the remainder by an alignment — a power
+ * of two up to sixteen — depends only on the last four digits, since sixteen
+ * divides ten thousand; so no tuple built here is ever longer than 9,999.
+ *
+ * Wherever an input is `number` rather than a literal, the answer is `number`:
+ * `sizeOf` then refuses the type rather than report a wrong size.
+ */
+/** A decimal digit, as text. */
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+/** The value of each digit. */
+interface DigitValues {
+    readonly '0': 0;
+    readonly '1': 1;
+    readonly '2': 2;
+    readonly '3': 3;
+    readonly '4': 4;
+    readonly '5': 5;
+    readonly '6': 6;
+    readonly '7': 7;
+    readonly '8': 8;
+    readonly '9': 9;
+}
+/**
+ * A tuple of `N` elements, for the small `N` a digit or an alignment needs.
+ *
+ * @template N Length, from 0 to 19.
+ */
+type Units<N extends number, TAccumulated extends unknown[] = []> = TAccumulated['length'] extends N ? TAccumulated : Units<N, [...TAccumulated, unknown]>;
+/** Ten elements, the carry out of a digit. */
+type Ten = Units<10>;
+/**
+ * Adds two digits and a carry.
+ *
+ * @template TLeft First digit.
+ * @template TRight Second digit.
+ * @template TCarry Carry into this digit.
+ * @returns `[digit, carry]` of the sum.
+ */
+type AddDigits<TLeft extends Digit, TRight extends Digit, TCarry extends 0 | 1> = [
+    ...Units<DigitValues[TLeft]>,
+    ...Units<DigitValues[TRight]>,
+    ...Units<TCarry>
+] extends infer TAll extends unknown[] ? TAll extends [...Ten, ...infer TRest] ? [`${TRest['length']}`, 1] : [`${TAll['length']}`, 0] : never;
+/** First character of a text, `'0'` once it is empty. */
+type Head<TText extends string> = TText extends `${infer THead extends Digit}${string}` ? THead : '0';
+/** A text without its first character. */
+type Tail<TText extends string> = TText extends `${Digit}${infer TTail}` ? TTail : '';
+/**
+ * Adds two numbers written least significant digit first.
+ *
+ * @returns The sum, least significant digit first.
+ */
+type AddReversed<TLeft extends string, TRight extends string, TCarry extends 0 | 1 = 0, TSum extends string = ''> = TLeft extends '' ? TRight extends '' ? TCarry extends 1 ? `${TSum}1` : TSum : AddStep<TLeft, TRight, TCarry, TSum> : AddStep<TLeft, TRight, TCarry, TSum>;
+/** One digit of {@link AddReversed}. */
+type AddStep<TLeft extends string, TRight extends string, TCarry extends 0 | 1, TSum extends string> = AddDigits<Head<TLeft>, Head<TRight>, TCarry> extends [
+    infer TDigit extends string,
+    infer TNext extends 0 | 1
+] ? AddReversed<Tail<TLeft>, Tail<TRight>, TNext, `${TSum}${TDigit}`> : never;
+/** A text, backwards. */
+type Reverse<TText extends string, TReversed extends string = ''> = TText extends `${infer THead}${infer TTail}` ? Reverse<TTail, `${THead}${TReversed}`> : TReversed;
+/** The number a text of digits spells. */
+type ToNumber<TText extends string> = TText extends `${infer N extends number}` ? N : never;
+/**
+ * The sum of two number literals; `number` when either is not a literal.
+ *
+ * @template TLeft First operand, a non-negative integer.
+ * @template TRight Second operand, a non-negative integer.
+ */
+export type Add<TLeft extends number, TRight extends number> = number extends TLeft | TRight ? number : ToNumber<Reverse<AddReversed<Reverse<`${TLeft}`>, Reverse<`${TRight}`>>>>;
+/**
+ * A tuple as long as a number of up to four digits, built one digit at a time
+ * — ten copies of what came before, and the digit — so its depth is the number
+ * of digits rather than the number itself.
+ */
+type TupleOf<TDigits extends string, TAccumulated extends unknown[] = []> = TDigits extends `${infer THead extends Digit}${infer TTail}` ? TupleOf<TTail, [
+    ...TAccumulated,
+    ...TAccumulated,
+    ...TAccumulated,
+    ...TAccumulated,
+    ...TAccumulated,
+    ...TAccumulated,
+    ...TAccumulated,
+    ...TAccumulated,
+    ...TAccumulated,
+    ...TAccumulated,
+    ...Units<DigitValues[THead]>
+]> : TAccumulated;
+/** The last `N` characters of a text written least significant first. */
+type Take<TText extends string, N extends number, TTaken extends string = '', TCount extends unknown[] = []> = TCount['length'] extends N ? TTaken : TText extends `${infer THead}${infer TTail}` ? Take<TTail, N, `${THead}${TTaken}`, [...TCount, unknown]> : TTaken;
+/** Digits of a number that decide its remainder by each alignment. */
+interface RemainderDigits {
+    readonly 2: 1;
+    readonly 4: 2;
+    readonly 8: 3;
+    readonly 16: 4;
+}
+/** How many elements are left of a tuple once whole chunks are taken off it. */
+type Leftover<TTuple extends unknown[], TChunk extends unknown[]> = TTuple extends [...TChunk, ...infer TRest] ? Leftover<TRest, TChunk> : TTuple['length'];
+/**
+ * The remainder of a number by an alignment.
+ *
+ * @template N A non-negative integer literal.
+ * @template TAlignment 2, 4, 8 or 16.
+ */
+type Remainder<N extends number, TAlignment extends keyof RemainderDigits> = Leftover<TupleOf<Take<Reverse<`${N}`>, RemainderDigits[TAlignment]>>, Units<TAlignment>>;
+/**
+ * A number rounded up to a multiple of an alignment: the size of a struct once
+ * its tail padding is added.
+ *
+ * @template N Size before padding.
+ * @template TAlignment Alignment of the struct, a power of two up to 16.
+ */
+export type RoundUp<N extends number, TAlignment extends number> = number extends N | TAlignment ? number : TAlignment extends keyof RemainderDigits ? Remainder<N, TAlignment> extends infer TRemainder extends number ? TRemainder extends 0 ? N : Units<TAlignment> extends [...Units<TRemainder>, ...infer TPadding] ? Add<N, TPadding['length']> : never : never : N;
+/**
+ * The largest of a union of alignments.
+ *
+ * @template TAlignments Alignments of the fields, each a power of two up to 16.
+ */
+export type LargestAlignment<TAlignments extends number> = number extends TAlignments ? number : 16 extends TAlignments ? 16 : 8 extends TAlignments ? 8 : 4 extends TAlignments ? 4 : 2 extends TAlignments ? 2 : 1;
+export {};

package/dist/struct/arithmetic.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Arithmetic on number literals, at the type level, for the layout a struct
+ * type declares.
+ *
+ * `sizeOf<T>()` answers from the literal in `T['~layout']`, so a struct type
+ * has to carry its size as a literal, and that literal is a sum of its fields
+ * rounded up to its alignment. TypeScript has no arithmetic on literals; this
+ * module is the smallest amount of it the layout needs.
+ *
+ * Addition works digit by digit on the decimal text of a number, so it is not
+ * bounded by the recursion limit the way counting a tuple up to the sum would
+ * be. Rounding needs a remainder, and the remainder by an alignment — a power
+ * of two up to sixteen — depends only on the last four digits, since sixteen
+ * divides ten thousand; so no tuple built here is ever longer than 9,999.
+ *
+ * Wherever an input is `number` rather than a literal, the answer is `number`:
+ * `sizeOf` then refuses the type rather than report a wrong size.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/struct/codec.d.ts

@@ -0,0 +1,58 @@
+/**
+ * How a field of a struct is laid out in bytes, and how it is compared.
+ *
+ * Internal. A struct is built from descriptors, and a descriptor says how a
+ * value is checked but not how it is stored — `SinglePrecisionFloat` has no
+ * byte order. The codec is what a struct looks up for each field, by the
+ * identity of its descriptor, so the numeric types did not have to grow a
+ * public byte encoding for this.
+ *
+ * Every multi-byte value is little-endian, whatever the platform: bytes a
+ * struct writes on one machine read back the same on any other, and it is the
+ * order of every platform a JavaScript engine runs on in practice.
+ */
+export interface FieldCodec {
+    /** Size, in bytes. */
+    readonly size: number;
+    /** Alignment, in bytes. */
+    readonly alignment: number;
+    /**
+     * Reads a value.
+     *
+     * @param view Bytes to read from.
+     * @param offset Where the value starts.
+     * @returns The value.
+     */
+    read(view: DataView, offset: number): unknown;
+    /**
+     * Writes a value.
+     *
+     * @param view Bytes to write into.
+     * @param offset Where the value starts.
+     * @param value The value, already of the field's type.
+     */
+    write(view: DataView, offset: number, value: unknown): void;
+    /**
+     * Compares two values as the field's own type does.
+     *
+     * @param left First value.
+     * @param right Second value.
+     * @returns `true` when they are equal.
+     */
+    equals(left: unknown, right: unknown): boolean;
+}
+/**
+ * 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.
+ */
+export declare const registerStructCodec: (descriptor: object, codec: FieldCodec) => void;
+/**
+ * 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.
+ */
+export declare const codecOf: (descriptor: unknown) => FieldCodec | undefined;