@fulcro/types 0.1.0 → 0.3.0

package/dist/struct/index.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.struct = void 0;
+const codec_1 = require("./codec.js");
+/**
+ * Keys an object lists before every other, in numeric order, whatever order
+ * they were written in. A field named like one would silently move, so it is
+ * refused.
+ */
+const ARRAY_INDEX = /^(?:0|[1-9]\d*)$/;
+/**
+ * Describes a value for an error message.
+ *
+ * @param value Value being reported.
+ * @returns Its kind.
+ */
+const describeKind = (value) => value === null ? 'null' : typeof value;
+/**
+ * Re-throws the error a field's own conversion raised, naming the field.
+ *
+ * @param name Name of the struct.
+ * @param key Field being converted.
+ * @param error What the conversion threw.
+ * @returns Never.
+ */
+const rethrowForField = (name, key, error) => {
+    const message = (original) => `${name}.from: field '${key}': ${original.message}`;
+    if (error instanceof RangeError) {
+        throw new RangeError(message(error), { cause: error });
+    }
+    if (error instanceof TypeError) {
+        throw new TypeError(message(error), { cause: error });
+    }
+    if (error instanceof SyntaxError) {
+        throw new SyntaxError(message(error), { cause: 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.
+ *
+ * ```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`.
+ */
+const struct = (name, fields, methods) => {
+    if (typeof name !== 'string' || name === '') {
+        throw new TypeError(`struct: expected a name, received ${describeKind(name)}.`);
+    }
+    if (typeof fields !== 'object' || fields === null) {
+        throw new TypeError(`struct ${name}: expected an object of fields, received ${describeKind(fields)}.`);
+    }
+    const keys = Object.keys(fields);
+    if (keys.length === 0) {
+        throw new TypeError(`struct ${name}: expected at least one field.`);
+    }
+    const declared = keys.map((key) => {
+        if (ARRAY_INDEX.test(key) || key === '~layout') {
+            throw new TypeError(`struct ${name}: '${key}' cannot name a field; an array index would be reordered, and '~layout' is the layout itself.`);
+        }
+        const codec = (0, codec_1.codecOf)(fields[key]);
+        if (codec === undefined) {
+            throw new TypeError(`struct ${name}: field '${key}' has no fixed layout. Declare it with a numeric type of @fulcro/types other than BigInteger, or with another struct.`);
+        }
+        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.
+    const offsets = new Map();
+    let end = 0;
+    for (const field of [...declared].sort((left, right) => right.codec.alignment - left.codec.alignment)) {
+        offsets.set(field.key, end);
+        end += field.codec.size;
+    }
+    const alignment = Math.max(...declared.map((field) => field.codec.alignment));
+    const size = Math.ceil(end / alignment) * alignment;
+    const plan = declared.map((field) => ({
+        ...field,
+        descriptor: field.descriptor,
+        offset: offsets.get(field.key),
+    }));
+    const layout = Object.freeze({
+        size,
+        alignment,
+        fields: Object.freeze(Object.fromEntries(plan.map((field) => [
+            field.key,
+            Object.freeze({
+                offset: field.offset,
+                size: field.codec.size,
+                alignment: field.codec.alignment,
+            }),
+        ]))),
+    });
+    /**
+     * Refuses a view and an offset the struct does not fit in, before a byte is
+     * touched — so a failed write leaves the view as it was.
+     *
+     * @param operation Operation being performed.
+     * @param view View handed in.
+     * @param offset Offset handed in.
+     */
+    const requireRoom = (operation, view, offset) => {
+        if (!(view instanceof DataView)) {
+            throw new TypeError(`${name}.${operation}: expected a DataView, received ${describeKind(view)}.`);
+        }
+        if (!Number.isInteger(offset) ||
+            offset < 0 ||
+            offset + size > view.byteLength) {
+            throw new RangeError(`${name}.${operation}: ${size} bytes at offset ${offset} do not fit in a view of ${view.byteLength} bytes.`);
+        }
+    };
+    const readFields = (view, offset) => {
+        const value = blank();
+        for (const field of plan) {
+            value[field.key] = field.codec.read(view, offset + field.offset);
+        }
+        return Object.freeze(value);
+    };
+    const writeFields = (view, offset, value) => {
+        for (const field of plan) {
+            field.codec.write(view, offset + field.offset, value[field.key]);
+        }
+    };
+    const equals = (left, right) => plan.every((field) => field.codec.equals(left[field.key], right[field.key]));
+    const descriptor = {
+        name,
+        layout: layout,
+        from: (source) => {
+            if (typeof source !== 'object' || source === null) {
+                throw new TypeError(`${name}.from: expected an object, received ${describeKind(source)}.`);
+            }
+            for (const key of Object.keys(source)) {
+                if (!Object.hasOwn(fields, key)) {
+                    throw new TypeError(`${name}.from: '${key}' is not a field; the fields are ${keys.join(', ')}.`);
+                }
+            }
+            const value = blank();
+            for (const field of plan) {
+                if (!Object.hasOwn(source, field.key)) {
+                    throw new TypeError(`${name}.from: missing field '${field.key}'.`);
+                }
+                try {
+                    value[field.key] = field.descriptor.from(source[field.key]);
+                }
+                catch (error) {
+                    rethrowForField(name, field.key, error);
+                }
+            }
+            return Object.freeze(value);
+        },
+        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) &&
+                field.descriptor.is(value[field.key])),
+        equals,
+        read: (view, offset) => {
+            requireRoom('read', view, offset);
+            return readFields(view, offset);
+        },
+        write: (view, offset, value) => {
+            requireRoom('write', view, offset);
+            writeFields(view, offset, value);
+        },
+    };
+    (0, codec_1.registerStructCodec)(descriptor, {
+        size,
+        alignment,
+        read: readFields,
+        write: writeFields,
+        equals,
+    });
+    return descriptor;
+};
+exports.struct = struct;

package/package.json

@@ -1,71 +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"
-	}
-}
+{
+	"name": "@fulcro/types",
+	"version": "0.3.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"
+	}
+}