@fulcro/types 0.1.0

package/dist/transformer/rewriter/index.js

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

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

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

package/dist/unsignedInteger/index.d.ts

@@ -0,0 +1,36 @@
+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';
+/**
+ * An integer of `N` bits with no sign: from 0 to 2^N - 1.
+ *
+ * ```ts
+ * const count: UnsignedInteger<16> = UnsignedInteger(16).from(65_535);
+ * ```
+ *
+ * Carried by a `number` up to 32 bits and by a `bigint` from 64. Widths are a
+ * parameter, not a list of names: there is no `UnsignedInteger16`, and no `u16`.
+ *
+ * @template N Width, in bits.
+ */
+export type UnsignedInteger<N extends IntegerWidth> = Branded<IntegerRepresentation<N>, `UnsignedInteger${N}`> & Layout<ByteSize<N>, ByteSize<N>>;
+/**
+ * The descriptor of an unsigned integer width: conversion, recognition and
+ * checked arithmetic.
+ *
+ * ```ts
+ * const Byte = UnsignedInteger(8);
+ *
+ * Byte.from(-1); // RangeError: outside [0, 255]
+ * Byte.wrap(-1); // 255
+ * Byte.subtract(Byte.from(0), Byte.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 UnsignedInteger: <N extends IntegerWidth>(width: N) => IntegerType<UnsignedInteger<N>>;

package/dist/unsignedInteger/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsignedInteger = 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 an unsigned integer width: conversion, recognition and
+ * checked arithmetic.
+ *
+ * ```ts
+ * const Byte = UnsignedInteger(8);
+ *
+ * Byte.from(-1); // RangeError: outside [0, 255]
+ * Byte.wrap(-1); // 255
+ * Byte.subtract(Byte.from(0), Byte.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 UnsignedInteger = (width) => {
+    let descriptor = descriptors.get(width);
+    if (descriptor === undefined) {
+        descriptor = (0, integer_1.createIntegerType)(false, width, `UnsignedInteger<${width}>`);
+        descriptors.set(width, descriptor);
+    }
+    return descriptor;
+};
+exports.UnsignedInteger = UnsignedInteger;

package/package.json

@@ -0,0 +1,71 @@
+{
+	"name": "@fulcro/types",
+	"version": "0.1.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",
+		"float",
+		"decimal",
+		"decimal128",
+		"numeric",
+		"typescript"
+	],
+	"license": "ISC",
+	"author": "diguu <rodrigogeribola@hotmail.com>",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"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"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DigUu-RL/fulcro.git",
+		"directory": "packages/types"
+	},
+	"homepage": "https://github.com/DigUu-RL/fulcro/tree/main/packages/types#readme",
+	"bugs": {
+		"url": "https://github.com/DigUu-RL/fulcro/issues"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"prepublishOnly": "npm run build"
+	}
+}