@fulcro/types 0.2.0 → 0.4.0

package/README.md

@@ -2,8 +2,8 @@
 
 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.
+the semantics of IEEE 754 decimal128. Nothing to configure: every operation is
+a typed method.
 
 ```sh
 npm install @fulcro/types
@@ -34,27 +34,9 @@ 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`.
+The JavaScript operators are the language's own: `a + b` on two
+`SignedInteger<32>` is a plain, unchecked `number`, and on a `Decimal` it
+throws. Use the methods, which keep the type and its checks.
 
 Every type but `BigInteger` declares a size and alignment, which
 `sizeOf<T>()` and `alignOf<T>()` from `@fulcro/reflect` read at compile time.
@@ -82,5 +64,5 @@ 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.
+special values, the layout table and structs.
 🇧🇷 [Leia em português](../../docs/pt-BR/types.md).

package/dist/bigInteger/index.d.ts

@@ -5,9 +5,8 @@ import type { NumericType } from '../numericType/index.js';
  *
  * 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.
+ * {@link BigInteger.from}, not any `bigint` at all, so an unchecked `bigint`
+ * cannot be passed where one is expected.
  *
  * 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.

package/dist/integer/index.d.ts

@@ -39,9 +39,8 @@ export type IntegerRepresentation<N extends IntegerWidth> = N extends 64 | 128 ?
  * Descriptor of a fixed-width integer type.
  *
  * Every operation is checked: a result outside the range throws a `RangeError`
- * naming the operation, the value and the range, as a C# `checked` context
- * does. `wrap` is the one exception, and the explicit way to ask for the
- * modular behaviour of an `unchecked` conversion.
+ * naming the operation, the value and the range. `wrap` is the one exception,
+ * and the explicit way to ask for modular arithmetic.
  *
  * @template T Type of the values this descriptor produces.
  */
@@ -65,8 +64,7 @@ export interface IntegerType<T> extends BoundedNumericType<T, number | bigint> {
      */
     wrap(value: number | bigint): T;
     /**
-     * Divides, truncating the quotient towards zero as integer division does in
-     * C#, Java and `BigInt`.
+     * Divides, truncating the quotient towards zero as `BigInt` division does.
      *
      * @param left Dividend.
      * @param right Divisor.
@@ -130,7 +128,7 @@ export interface IntegerType<T> extends BoundedNumericType<T, number | bigint> {
     /**
      * Shifts the bits towards the least significant end with zeros coming in,
      * as `>>>` does — on a signed type, over the bits of its own width, and read
-     * back as signed, as Java's `>>>` does.
+     * back as signed.
      *
      * ```ts
      * const Int32 = SignedInteger(32);

package/dist/struct/index.d.ts

@@ -12,6 +12,12 @@ interface FieldDescriptor {
 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;
@@ -44,10 +50,16 @@ type StructAlignment<TFields extends StructFields> = LargestAlignment<{
  * not promise an order for its keys.
  */
 type StructSize<TFields extends StructFields> = RoundUp<SumOfSizes<TFields, UnionToTuple<keyof TFields>>, StructAlignment<TFields>>;
-/** A value of a struct. */
-type StructValue<TFields extends StructFields> = {
+/** 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]>;
@@ -57,8 +69,9 @@ type StructSource<TFields extends StructFields> = {
  * 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> {
+export interface StructType<TFields extends StructFields, TMethods extends StructMethods = NoMethods> {
     /** Name of the struct, as it reads in an error message. */
     readonly name: string;
     /**
@@ -85,40 +98,42 @@ export interface StructType<TFields extends StructFields> {
      * 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.
+     * @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>;
+    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.
+     * 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>;
+    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#.
+     * `NaN` field makes a value unequal to itself, as `NaN` is.
      *
      * @param left First value.
      * @param right Second value.
      * @returns `true` when every field is equal.
      */
-    equals(left: StructValue<TFields>, right: StructValue<TFields>): boolean;
+    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.
+     * @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>;
+    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.
@@ -129,7 +144,7 @@ export interface StructType<TFields extends StructFields> {
      * @throws {RangeError} When the struct does not fit in the view at that
      * offset.
      */
-    write(view: DataView, offset: number, value: StructValue<TFields>): void;
+    write(view: DataView, offset: number, value: StructValue<TFields, TMethods>): void;
 }
 /**
  * The type of the values of a struct, named from its descriptor.
@@ -141,7 +156,7 @@ export interface StructType<TFields extends StructFields> {
  *
  * @template TDescriptor Type of the descriptor `struct` returned.
  */
-export type Struct<TDescriptor extends StructType<StructFields>> = TDescriptor extends StructType<infer TFields> ? StructValue<TFields> : never;
+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.
  *
@@ -164,11 +179,28 @@ export type Struct<TDescriptor extends StructType<StructFields>> = TDescriptor e
  * 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, or a field is named like an array index or `~layout`.
+ * 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>(name: string, fields: TFields) => StructType<TFields>;
+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 {};

package/dist/struct/index.js

@@ -36,6 +36,48 @@ const rethrowForField = (name, key, error) => {
     }
     throw error;
 };
+/**
+ * Builds the prototype every value of a struct with methods is made on.
+ *
+ * The methods sit on it, not on each value: a value is its fields and nothing
+ * else of its own, so a thousand values cost no function object each, and
+ * `Object.keys` still lists exactly the fields that `is` counts. The methods
+ * are not enumerable, so spreading a value copies its fields and not them.
+ *
+ * @param name Name of the struct.
+ * @param fields Its fields, which no method may be named like.
+ * @param methods The methods.
+ * @returns The prototype, frozen.
+ * @throws {TypeError} When `methods` is not an object, a method is not a
+ * function, or a method is named like a field, an array index or `~layout`.
+ */
+const methodPrototype = (name, fields, methods) => {
+    if (typeof methods !== 'object' || methods === null) {
+        throw new TypeError(`struct ${name}: expected an object of methods, received ${describeKind(methods)}.`);
+    }
+    const prototype = {};
+    for (const key of Reflect.ownKeys(methods)) {
+        const method = methods[key];
+        const label = String(key);
+        if (typeof key === 'string' && Object.hasOwn(fields, key)) {
+            throw new TypeError(`struct ${name}: method '${label}' has the name of a field; a value could not hold both.`);
+        }
+        if (typeof key === 'string' &&
+            (ARRAY_INDEX.test(key) || key === '~layout')) {
+            throw new TypeError(`struct ${name}: '${label}' cannot name a method; an array index would be reordered, and '~layout' is the layout itself.`);
+        }
+        if (typeof method !== 'function') {
+            throw new TypeError(`struct ${name}: method '${label}' must be a function, received ${describeKind(method)}.`);
+        }
+        Object.defineProperty(prototype, key, {
+            value: method,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    }
+    return Object.freeze(prototype);
+};
 /**
  * Declares a struct: a value type with a fixed layout.
  *
@@ -58,13 +100,30 @@ const rethrowForField = (name, key, error) => {
  * 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, or a field is named like an array index or `~layout`.
+ * 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`.
  */
-const struct = (name, fields) => {
+const struct = (name, fields, methods) => {
     if (typeof name !== 'string' || name === '') {
         throw new TypeError(`struct: expected a name, received ${describeKind(name)}.`);
     }
@@ -85,6 +144,15 @@ const struct = (name, fields) => {
         }
         return { key, descriptor: fields[key], codec };
     });
+    const prototype = methods === undefined ? undefined : methodPrototype(name, fields, methods);
+    /**
+     * Makes the object a value is built on: one carrying the methods, when the
+     * struct has any, and a plain one otherwise — so a struct without methods
+     * makes exactly the values it made before methods existed.
+     *
+     * @returns The object, still empty and not yet frozen.
+     */
+    const blank = () => prototype === undefined ? {} : Object.create(prototype);
     // Largest alignment first, so that every field lands aligned without padding
     // before it: each size is a multiple of its own alignment. `sort` is stable,
     // which keeps declaration order among equals.
@@ -132,7 +200,7 @@ const struct = (name, fields) => {
         }
     };
     const readFields = (view, offset) => {
-        const value = {};
+        const value = blank();
         for (const field of plan) {
             value[field.key] = field.codec.read(view, offset + field.offset);
         }
@@ -156,7 +224,7 @@ const struct = (name, fields) => {
                     throw new TypeError(`${name}.from: '${key}' is not a field; the fields are ${keys.join(', ')}.`);
                 }
             }
-            const value = {};
+            const value = blank();
             for (const field of plan) {
                 if (!Object.hasOwn(source, field.key)) {
                     throw new TypeError(`${name}.from: missing field '${field.key}'.`);
@@ -172,6 +240,7 @@ const struct = (name, fields) => {
         },
         is: (value) => typeof value === 'object' &&
             value !== null &&
+            (prototype === undefined || Object.getPrototypeOf(value) === prototype) &&
             Object.isFrozen(value) &&
             Object.keys(value).length === plan.length &&
             plan.every((field) => Object.hasOwn(value, field.key) &&

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fulcro/types",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "Numeric types with a defined range and layout: fixed-width integers, half, single and double precision floats, and a decimal128 Decimal.",
 	"keywords": [
 		"integer",
@@ -19,35 +19,12 @@
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
 		},
-		"./transformer": {
-			"types": "./dist/transformer/index.d.ts",
-			"default": "./dist/transformer/index.js"
-		},
-		"./unplugin": {
-			"types": "./dist/unplugin/index.d.mts",
-			"default": "./dist/unplugin/index.mjs"
-		},
-		"./language-service": {
-			"types": "./dist/languageService/index.d.ts",
-			"default": "./dist/languageService/index.js"
-		},
 		"./package.json": "./package.json"
 	},
 	"files": [
 		"dist"
 	],
 	"sideEffects": false,
-	"dependencies": {
-		"@fulcro/transform-core": "^0.10.0"
-	},
-	"peerDependencies": {
-		"typescript": ">=5.3.3 <7"
-	},
-	"peerDependenciesMeta": {
-		"typescript": {
-			"optional": true
-		}
-	},
 	"engines": {
 		"node": ">=22"
 	},

package/dist/languageService/index.d.ts

@@ -1,21 +0,0 @@
-import { type LanguageServicePlugin } from '@fulcro/transform-core';
-/**
- * The editor plugin giving the operators their meaning on this package's
- * numeric types: the types, the hover, the completions and the errors an editor
- * shows are those of the rewritten code, mapped back onto the code as written.
- *
- * ```json
- * {
- * 	"compilerOptions": {
- * 		"plugins": [{ "name": "@fulcro/types/language-service" }]
- * 	}
- * }
- * ```
- *
- * VS Code loads it only from the workspace's own TypeScript: select it with
- * **TypeScript: Select TypeScript Version → Use Workspace Version**. An editor
- * that does not load it shows what `tsc` alone would — the operators on a
- * `Decimal` underlined, the others typed as `number`.
- */
-declare const plugin: LanguageServicePlugin;
-export = plugin;

package/dist/languageService/index.js

@@ -1,23 +0,0 @@
-"use strict";
-const transform_core_1 = require("@fulcro/transform-core");
-const rewriter_1 = require("../transformer/rewriter/index.js");
-/**
- * The editor plugin giving the operators their meaning on this package's
- * numeric types: the types, the hover, the completions and the errors an editor
- * shows are those of the rewritten code, mapped back onto the code as written.
- *
- * ```json
- * {
- * 	"compilerOptions": {
- * 		"plugins": [{ "name": "@fulcro/types/language-service" }]
- * 	}
- * }
- * ```
- *
- * VS Code loads it only from the workspace's own TypeScript: select it with
- * **TypeScript: Select TypeScript Version → Use Workspace Version**. An editor
- * that does not load it shows what `tsc` alone would — the operators on a
- * `Decimal` underlined, the others typed as `number`.
- */
-const plugin = (0, transform_core_1.createLanguageServicePlugin)(rewriter_1.OPERATOR_REWRITER);
-module.exports = plugin;

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

@@ -1,39 +0,0 @@
-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

@@ -1,84 +0,0 @@
-"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

@@ -1,27 +0,0 @@
-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

@@ -1,30 +0,0 @@
-"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

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

package/dist/transformer/rewriter/index.js

@@ -1,374 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OPERATOR_REWRITER = void 0;
-const typescript_1 = __importDefault(require("typescript"));
-const classify_1 = require("../classify/index.js");
-/**
- * The rewrite of the JavaScript operators on this package's numeric types.
- *
- * Every operator becomes a call to the operation that means it for the type —
- * `a + b` on two `SignedInteger<32>` becomes `SignedInteger(32).add(a, b)`,
- * checked for overflow; on two `Decimal`, `a.add(b)`. The call is what the
- * checker then sees, so the result keeps its type, and an operand of any other
- * type fails to type check as an argument: that is how "the same type only" is
- * enforced, with the checker's own message at the site.
- *
- * | Written                                          | Becomes                        |
- * | ------------------------------------------------ | ------------------------------ |
- * | `a + b`, `-`, `*`, `/`, `%`, `**`                | `T.add(a, b)` …                |
- * | `a & b`, `\|`, `^`, `<<`, `>>`, `>>>`            | `T.bitwiseAnd(a, b)` …         |
- * | `a < b`, `<=`, `>`, `>=`                         | `T.lessThan(a, b)` …           |
- * | `a === b`, `==`, `!==`, `!=`                     | `T.equals(a, b)`, negated      |
- * | `-a`, `+a`, `~a`                                 | `T.negate(a)`, `a`, `T.bitwiseNot(a)` |
- * | `++a`, `a++`, `--a`, `a--`                       | `T.increment` / `T.decrement`  |
- * | `a += b` and every compound assignment           | `a = T.add(a, b)` …            |
- *
- * Evaluation order and the value of each expression are those of the operator
- * it replaces: a compound assignment evaluates its target once, and a postfix
- * operator evaluates to the value before the change.
- */
-/** Module every rewritten file imports, and the name it is imported under. */
-const MODULE = '@fulcro/types';
-const NAMESPACE = '__fulcroTypes';
-/** The operation each binary operator stands for. */
-const BINARY_OPERATIONS = new Map([
-    [typescript_1.default.SyntaxKind.PlusToken, 'add'],
-    [typescript_1.default.SyntaxKind.MinusToken, 'subtract'],
-    [typescript_1.default.SyntaxKind.AsteriskToken, 'multiply'],
-    [typescript_1.default.SyntaxKind.SlashToken, 'divide'],
-    [typescript_1.default.SyntaxKind.PercentToken, 'remainder'],
-    [typescript_1.default.SyntaxKind.AsteriskAsteriskToken, 'power'],
-    [typescript_1.default.SyntaxKind.AmpersandToken, 'bitwiseAnd'],
-    [typescript_1.default.SyntaxKind.BarToken, 'bitwiseOr'],
-    [typescript_1.default.SyntaxKind.CaretToken, 'bitwiseXor'],
-    [typescript_1.default.SyntaxKind.LessThanLessThanToken, 'shiftLeft'],
-    [typescript_1.default.SyntaxKind.GreaterThanGreaterThanToken, 'shiftRight'],
-    [
-        typescript_1.default.SyntaxKind.GreaterThanGreaterThanGreaterThanToken,
-        'shiftRightLogical',
-    ],
-    [typescript_1.default.SyntaxKind.LessThanToken, 'lessThan'],
-    [typescript_1.default.SyntaxKind.LessThanEqualsToken, 'lessThanOrEqual'],
-    [typescript_1.default.SyntaxKind.GreaterThanToken, 'greaterThan'],
-    [typescript_1.default.SyntaxKind.GreaterThanEqualsToken, 'greaterThanOrEqual'],
-]);
-/** The operation each compound assignment applies before assigning. */
-const COMPOUND_OPERATIONS = new Map([
-    [typescript_1.default.SyntaxKind.PlusEqualsToken, 'add'],
-    [typescript_1.default.SyntaxKind.MinusEqualsToken, 'subtract'],
-    [typescript_1.default.SyntaxKind.AsteriskEqualsToken, 'multiply'],
-    [typescript_1.default.SyntaxKind.SlashEqualsToken, 'divide'],
-    [typescript_1.default.SyntaxKind.PercentEqualsToken, 'remainder'],
-    [typescript_1.default.SyntaxKind.AsteriskAsteriskEqualsToken, 'power'],
-    [typescript_1.default.SyntaxKind.AmpersandEqualsToken, 'bitwiseAnd'],
-    [typescript_1.default.SyntaxKind.BarEqualsToken, 'bitwiseOr'],
-    [typescript_1.default.SyntaxKind.CaretEqualsToken, 'bitwiseXor'],
-    [typescript_1.default.SyntaxKind.LessThanLessThanEqualsToken, 'shiftLeft'],
-    [typescript_1.default.SyntaxKind.GreaterThanGreaterThanEqualsToken, 'shiftRight'],
-    [
-        typescript_1.default.SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken,
-        'shiftRightLogical',
-    ],
-]);
-/** Equality operators, and whether each is negated. */
-const EQUALITY = new Map([
-    [typescript_1.default.SyntaxKind.EqualsEqualsEqualsToken, false],
-    [typescript_1.default.SyntaxKind.EqualsEqualsToken, false],
-    [typescript_1.default.SyntaxKind.ExclamationEqualsEqualsToken, true],
-    [typescript_1.default.SyntaxKind.ExclamationEqualsToken, true],
-]);
-/**
- * The call applying an operation to operands, in the form the kind uses.
- *
- * @param kind Kind the operation belongs to.
- * @param operation Name of the operation.
- * @param operands Its operands, in order.
- * @param separator What goes between two operands, line breaks included.
- * @param leftIsOurs Whether the first operand is of the kind — for a decimal,
- * whether the method can be called on it.
- * @returns The replacement.
- */
-const call = (kind, operation, operands, separator = ', ', leftIsOurs = true) => {
-    if (kind.family === 'descriptor') {
-        return [
-            `${NAMESPACE}.${kind.descriptor}.${operation}(`,
-            ...interleave(operands, separator),
-            ')',
-        ];
-    }
-    const [receiver, ...rest] = operands;
-    if (!leftIsOurs) {
-        // The method cannot be called on an operand that is not a decimal, and
-        // the checker has to say so at the site: a function taking two
-        // decimals makes it.
-        return [
-            `((__left: ${NAMESPACE}.Decimal, __right: ${NAMESPACE}.Decimal) => __left.${operation}(__right))(`,
-            ...interleave(operands, separator),
-            ')',
-        ];
-    }
-    return [
-        '(',
-        receiver,
-        `).${operation}(`,
-        ...interleave(rest, separator),
-        ')',
-    ];
-};
-/**
- * Puts a separator between operands.
- *
- * @param operands Operands, in order.
- * @param separator What goes between two of them.
- * @returns The operands with separators.
- */
-const interleave = (operands, separator) => operands.flatMap((operand, index) => index === 0 ? [operand] : [separator, operand]);
-/**
- * One, as the kind writes it, for `++` and `--` on a decimal.
- *
- * @returns The expression.
- */
-const decimalOne = () => `${NAMESPACE}.Decimal.from(1)`;
-/**
- * The increment or decrement of an operand, as the kind computes it.
- *
- * @param kind Kind of the operand.
- * @param increment Whether it goes up.
- * @param operand The operand.
- * @returns The replacement.
- */
-const step = (kind, increment, operand) => kind.family === 'descriptor'
-    ? call(kind, increment ? 'increment' : 'decrement', [operand])
-    : call(kind, increment ? 'add' : 'subtract', [operand, decimalOne()]);
-/**
- * Strips the parentheses around an expression.
- *
- * @param expression Expression, possibly parenthesized.
- * @returns The expression inside.
- */
-const unwrap = (expression) => typescript_1.default.isParenthesizedExpression(expression)
-    ? unwrap(expression.expression)
-    : expression;
-/**
- * Tells whether an expression can be evaluated twice without anything
- * observable happening: a name, `this`, or a literal.
- *
- * @param expression Expression to inspect.
- * @returns `true` when evaluating it again is harmless.
- */
-const isInert = (expression) => typescript_1.default.isIdentifier(expression) ||
-    expression.kind === typescript_1.default.SyntaxKind.ThisKeyword ||
-    typescript_1.default.isLiteralExpression(expression);
-/**
- * How an assignment target is written back to, evaluating its parts once.
- *
- * A name, or a member of a name, is written twice as it stands. Any other
- * member — `items[next()]`, `load().total` — is evaluated once into the
- * parameters of an arrow function called on the spot, which is also what keeps
- * the order of evaluation JavaScript's.
- *
- * @param target The target, parentheses stripped.
- * @returns How to wrap an assignment to it.
- */
-const assignmentForm = (target) => {
-    if (typescript_1.default.isPropertyAccessExpression(target) &&
-        !isInert(target.expression)) {
-        return {
-            reference: `__target.${target.name.text}`,
-            open: ['((__target) => ('],
-            close: ['))(', target.expression, ')'],
-        };
-    }
-    if (typescript_1.default.isElementAccessExpression(target) &&
-        !(isInert(target.expression) && isInert(target.argumentExpression))) {
-        return {
-            reference: '__target[__key]',
-            open: ['((__target, __key) => ('],
-            close: ['))(', target.expression, ', ', target.argumentExpression, ')'],
-        };
-    }
-    return { reference: target, open: ['('], close: [')'] };
-};
-/**
- * Tells whether a type is one a string concatenation would produce, which
- * `+` then means instead of addition.
- *
- * @param type Type of an operand.
- * @returns `true` for a string.
- */
-const isString = (type) => (type.flags & typescript_1.default.TypeFlags.StringLike) !== 0;
-/**
- * Tells whether a type is a plain number or bigint — the kind of operand an
- * equality with one of ours has to refuse, rather than leave to a comparison
- * that would quietly succeed.
- *
- * @param type Type of an operand.
- * @returns `true` for a number or a bigint.
- */
-const isNumeric = (type) => (type.flags &
-    (typescript_1.default.TypeFlags.NumberLike | typescript_1.default.TypeFlags.BigIntLike)) !==
-    0;
-/**
- * Rewrites a binary expression.
- *
- * @param node The expression.
- * @param context The file and its checker.
- * @returns The replacement, or `null`.
- */
-const rewriteBinary = (node, context) => {
-    const { checker } = context;
-    const operator = node.operatorToken.kind;
-    const leftType = checker.getTypeAtLocation(node.left);
-    const rightType = checker.getTypeAtLocation(node.right);
-    const left = (0, classify_1.classify)(leftType, checker, node.left);
-    const right = (0, classify_1.classify)(rightType, checker, node.right);
-    const kind = left ?? right;
-    if (kind === null)
-        return null;
-    const separator = `, ${context.lineBreaks(node.left.end, node.right.getStart(context.sourceFile))}`;
-    const compound = COMPOUND_OPERATIONS.get(operator);
-    if (compound !== undefined) {
-        const target = unwrap(node.left);
-        const form = assignmentForm(target);
-        return [
-            ...form.open,
-            form.reference,
-            ' = ',
-            ...call(kind, compound, [form.reference, node.right], separator, left !== null),
-            ...form.close,
-        ];
-    }
-    const negated = EQUALITY.get(operator);
-    if (negated !== undefined) {
-        // An equality with something that is not a number at all — `null`, an
-        // object — is a question about identity, and stays one.
-        const comparable = (left !== null || isNumeric(leftType)) &&
-            (right !== null || isNumeric(rightType));
-        if (!comparable)
-            return null;
-        const equals = call(kind, 'equals', [node.left, node.right], separator, left !== null);
-        return negated ? ['(!', ...equals, ')'] : equals;
-    }
-    const operation = BINARY_OPERATIONS.get(operator);
-    if (operation === undefined)
-        return null;
-    if (operator === typescript_1.default.SyntaxKind.PlusToken &&
-        (isString(leftType) || isString(rightType))) {
-        // Concatenation, not addition. A primitive-backed value concatenates as
-        // a number does; a decimal refuses the implicit conversion, so its text
-        // is asked for explicitly.
-        if (kind.family !== 'decimal')
-            return null;
-        const text = (operand, ours) => ours ? ['(', operand, ').toString()'] : [operand];
-        return [
-            ...text(node.left, left !== null),
-            ` + ${context.lineBreaks(node.left.end, node.right.getStart(context.sourceFile))}`,
-            ...text(node.right, right !== null),
-        ];
-    }
-    return call(kind, operation, [node.left, node.right], separator, left !== null);
-};
-/**
- * Rewrites an increment or a decrement, written before or after its operand.
- *
- * @param node The expression.
- * @param operand Its operand.
- * @param increment Whether it goes up.
- * @param postfix Whether it was written after the operand.
- * @param context The file and its checker.
- * @returns The replacement, or `null`.
- */
-const rewriteStep = (node, operand, increment, postfix, context) => {
-    const kind = (0, classify_1.classify)(context.checker.getTypeAtLocation(operand), context.checker, operand);
-    if (kind === null)
-        return null;
-    const target = unwrap(operand);
-    const form = assignmentForm(target);
-    // Where the value of the expression is thrown away — a statement of its
-    // own, the step of a `for` — the prefix form does the same work.
-    const valueUnused = typescript_1.default.isExpressionStatement(node.parent) ||
-        (typescript_1.default.isForStatement(node.parent) &&
-            node.parent.incrementor === node);
-    if (!postfix || valueUnused) {
-        return [
-            ...form.open,
-            form.reference,
-            ' = ',
-            ...step(kind, increment, form.reference),
-            ...form.close,
-        ];
-    }
-    // The value before the step is taken once, as a default parameter, so the
-    // target is read once and the expression still evaluates to it.
-    if (typeof form.reference === 'string') {
-        const [head] = form.open;
-        const parameters = head.replace(') => (', `, __previous = ${form.reference}) => (`);
-        return [
-            parameters,
-            '(',
-            form.reference,
-            ' = ',
-            ...step(kind, increment, '__previous'),
-            '), __previous',
-            ...form.close,
-        ];
-    }
-    return [
-        '((__previous) => ((',
-        target,
-        ' = ',
-        ...step(kind, increment, '__previous'),
-        '), __previous))(',
-        target,
-        ')',
-    ];
-};
-/**
- * Rewrites a unary expression written before its operand.
- *
- * @param node The expression.
- * @param context The file and its checker.
- * @returns The replacement, or `null`.
- */
-const rewritePrefix = (node, context) => {
-    switch (node.operator) {
-        case typescript_1.default.SyntaxKind.PlusPlusToken:
-            return rewriteStep(node, node.operand, true, false, context);
-        case typescript_1.default.SyntaxKind.MinusMinusToken:
-            return rewriteStep(node, node.operand, false, false, context);
-    }
-    const kind = (0, classify_1.classify)(context.checker.getTypeAtLocation(node.operand), context.checker, node.operand);
-    if (kind === null)
-        return null;
-    switch (node.operator) {
-        case typescript_1.default.SyntaxKind.MinusToken:
-            return call(kind, 'negate', [node.operand]);
-        case typescript_1.default.SyntaxKind.TildeToken:
-            return call(kind, 'bitwiseNot', [node.operand]);
-        case typescript_1.default.SyntaxKind.PlusToken:
-            // The identity, which on a `number` would still widen the type.
-            return ['(', node.operand, ')'];
-        default:
-            return null;
-    }
-};
-/** The rewriter of the operators on this package's numeric types. */
-exports.OPERATOR_REWRITER = {
-    module: MODULE,
-    namespace: NAMESPACE,
-    rewrite: (node, context) => {
-        if (typescript_1.default.isBinaryExpression(node)) {
-            return rewriteBinary(node, context);
-        }
-        if (typescript_1.default.isPrefixUnaryExpression(node)) {
-            return rewritePrefix(node, context);
-        }
-        if (typescript_1.default.isPostfixUnaryExpression(node)) {
-            return rewriteStep(node, node.operand, node.operator === typescript_1.default.SyntaxKind.PlusPlusToken, true, context);
-        }
-        return null;
-    },
-};

package/dist/unplugin/index.d.mts

@@ -1,15 +0,0 @@
-export type { PluginOptions } from '@fulcro/transform-core/unplugin';
-/** The factory itself, for a bundler not covered below. */
-export declare const unpluginFactory: import("unplugin").UnpluginFactory<import("@fulcro/transform-core").TransformCoreOptions | undefined>;
-/** Adapter for Vite, which is also what vitest runs on. */
-export declare const vite: (options?: import("@fulcro/transform-core").TransformCoreOptions | undefined) => import("vite").Plugin<any> | import("vite").Plugin<any>[];
-/** Adapter for Rollup. */
-export declare const rollup: (options?: import("@fulcro/transform-core").TransformCoreOptions | undefined) => any;
-/** Adapter for Webpack. */
-export declare const webpack: (options?: import("@fulcro/transform-core").TransformCoreOptions | undefined) => WebpackPluginInstance;
-/** Adapter for Rspack. */
-export declare const rspack: (options?: import("@fulcro/transform-core").TransformCoreOptions | undefined) => RspackPluginInstance;
-/** Adapter for esbuild. */
-export declare const esbuild: (options?: import("@fulcro/transform-core").TransformCoreOptions | undefined) => EsbuildPlugin;
-/** Adapter for Farm. */
-export declare const farm: (options?: import("@fulcro/transform-core").TransformCoreOptions | undefined) => JsPlugin;

package/dist/unplugin/index.mjs

@@ -1,31 +0,0 @@
-import { createRewriterUnplugin } from '@fulcro/transform-core/unplugin';
-import { OPERATOR_REWRITER } from '../transformer/rewriter/index.js';
-/**
- * Bundler plugin giving the operators their meaning on this package's numeric
- * types, for Vite, Rollup, Webpack, esbuild, Rspack and Farm:
- *
- * ```ts
- * import { vite as fulcroTypes } from '@fulcro/types/unplugin';
- *
- * export default defineConfig({ plugins: [fulcroTypes()] });
- * ```
- *
- * It runs before the bundler erases the types, and it reads the whole program:
- * whether `c + d` in one file is ours depends on how `c` was declared in
- * another.
- */
-const plugins = createRewriterUnplugin(OPERATOR_REWRITER, 'fulcro-types');
-/** The factory itself, for a bundler not covered below. */
-export const unpluginFactory = plugins.unpluginFactory;
-/** Adapter for Vite, which is also what vitest runs on. */
-export const vite = plugins.vite;
-/** Adapter for Rollup. */
-export const rollup = plugins.rollup;
-/** Adapter for Webpack. */
-export const webpack = plugins.webpack;
-/** Adapter for Rspack. */
-export const rspack = plugins.rspack;
-/** Adapter for esbuild. */
-export const esbuild = plugins.esbuild;
-/** Adapter for Farm. */
-export const farm = plugins.farm;