@vworlds/vecs 1.0.61 → 1.0.62

package/dist/reflection/decorators.js

@@ -0,0 +1,129 @@
+var _a;
+import { assertMemberType } from "./member_types.js";
+const DECLARATIONS = Symbol("vecs.members");
+const declarationsByClass = new WeakMap();
+// Standard decorators store their declarations in `context.metadata`, which
+// TypeScript and esbuild provide only when `Symbol.metadata` exists. Defining it
+// here, before any decorated class can be evaluated, lets `world.component(C)`
+// read them without constructing an instance.
+(_a = Symbol).metadata ?? (_a.metadata = Symbol.for("Symbol.metadata"));
+/**
+ * Declare a member's type. Every member that carries metadata needs one.
+ *
+ * ```ts
+ * class Position {
+ *   @type("i32") @range(-100, 100) public x = 0;
+ * }
+ * ```
+ *
+ * @param memberType - A scalar type name, a nested component class, or an array `[type]`.
+ */
+export function type(memberType) {
+    assertMemberType(memberType, "@type");
+    return memberDecorator("@type", { type: memberType });
+}
+/**
+ * Declare a numeric member's inclusive `[min, max]` range.
+ *
+ * Ranges are metadata: nothing checks them on `set`. The default `validate`
+ * and `normalize` hooks check and clamp to them.
+ */
+export function range(min, max) {
+    return memberDecorator("@range", { range: [min, max] });
+}
+/** Declare a member's human-readable description. */
+export function description(text) {
+    return memberDecorator("@description", { description: text });
+}
+/** Declare a member's unit of measure, for example `"m"`. */
+export function unit(text) {
+    return memberDecorator("@unit", { unit: text });
+}
+/** Declare the allowed values of an `enum` member. */
+export function values(allowed) {
+    return memberDecorator("@values", { values: [...allowed] });
+}
+/** @internal Read the decorator declarations `Class` itself makes, in declaration order. */
+export function _ownDecoratedMembers(Class) {
+    return [...(declarationsByClass.get(Class) ?? []), ...(ownMetadataDeclarations(Class) ?? [])];
+}
+function memberDecorator(name, declaration) {
+    return ((target, key) => {
+        if (isStandardFieldContext(key)) {
+            declareStandard(name, key, declaration);
+            return;
+        }
+        if (typeof key !== "string") {
+            throw new TypeError(`${name} only supports string property keys`);
+        }
+        const Class = target.constructor;
+        let declarations = declarationsByClass.get(Class);
+        if (declarations === undefined) {
+            declarations = new Map();
+            declarationsByClass.set(Class, declarations);
+        }
+        addDeclaration(declarations, `${Class.name}.${key}`, key, declaration);
+    });
+}
+function declareStandard(name, context, declaration) {
+    if (context.kind !== "field" || context.static || context.private) {
+        throw new TypeError(`${name} only supports public instance fields`);
+    }
+    if (typeof context.name !== "string") {
+        throw new TypeError(`${name} only supports string property keys`);
+    }
+    const key = context.name;
+    const metadata = context.metadata;
+    if (metadata !== undefined) {
+        if (!Object.prototype.hasOwnProperty.call(metadata, DECLARATIONS)) {
+            metadata[DECLARATIONS] = new Map();
+        }
+        addDeclaration(metadata[DECLARATIONS], key, key, declaration);
+        return;
+    }
+    // Without metadata, fall back to registering on first construction.
+    context.addInitializer(function declareMember() {
+        const Class = this.constructor;
+        let declarations = declarationsByClass.get(Class);
+        if (declarations === undefined) {
+            declarations = new Map();
+            declarationsByClass.set(Class, declarations);
+        }
+        if (!declarations.has(key) || !hasFields(declarations.get(key), declaration)) {
+            addDeclaration(declarations, `${Class.name}.${key}`, key, declaration);
+        }
+    });
+}
+function addDeclaration(declarations, where, key, declaration) {
+    const current = declarations.get(key) ?? {};
+    for (const field of Object.keys(declaration)) {
+        if (current[field] !== undefined) {
+            throw new Error(`VecsStruct ${where}: ${field} is declared twice`);
+        }
+    }
+    declarations.set(key, { ...current, ...declaration });
+}
+function hasFields(current, declaration) {
+    return Object.keys(declaration).every((field) => current[field] !== undefined);
+}
+function ownMetadataDeclarations(constructor) {
+    const metadataKey = Symbol.metadata;
+    if (!Object.prototype.hasOwnProperty.call(constructor, metadataKey)) {
+        return undefined;
+    }
+    const metadata = constructor[metadataKey];
+    if (typeof metadata !== "object" ||
+        metadata === null ||
+        !Object.prototype.hasOwnProperty.call(metadata, DECLARATIONS)) {
+        return undefined;
+    }
+    return metadata[DECLARATIONS];
+}
+function isStandardFieldContext(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "kind" in value &&
+        "name" in value &&
+        "addInitializer" in value);
+}
+//# sourceMappingURL=decorators.js.map

package/dist/reflection/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../src/reflection/decorators.ts"],"names":[],"mappings":"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"}

package/dist/reflection/defaults.d.ts

@@ -0,0 +1,4 @@
+/** Violations returned by a failing `validate` hook: one message or a list of them. */
+export type Violations = string | readonly string[];
+/** What a `validate` hook returns: `true` when valid, otherwise the violations. */
+export type ValidationResult = true | Violations;

package/dist/reflection/defaults.js

@@ -0,0 +1,149 @@
+// Default `validate` / `normalize` hooks derived from member metadata.
+import { INTEGER_BOUNDS, elementType, isArrayType, isBigIntType, isIntegerType, isNumericType, } from "./member_types.js";
+import { _structMembers } from "./vecs_struct.js";
+/**
+ * @internal Whether the definition of `Class` declares a range or an integer
+ * type, so a default hook has something to check.
+ */
+export function _hasDefaultChecks(Class) {
+    return checks(Class).length > 0;
+}
+/**
+ * @internal Build the default `validate` hook. It derives its checks from the
+ * live definition on every call, so members declared later, in any world or on
+ * a base class, are checked too.
+ */
+export function _defaultValidate(Class) {
+    return (component) => {
+        const violations = [];
+        for (const check of checks(Class)) {
+            const value = component[check.name];
+            if (!check.array) {
+                validateValue(check, check.name, value, violations);
+            }
+            else if (!Array.isArray(value)) {
+                violations.push(`${check.name}: expected an array`);
+            }
+            else {
+                value.forEach((item, i) => validateValue(check, `${check.name}[${i}]`, item, violations));
+            }
+        }
+        return violations.length === 0 ? true : violations;
+    };
+}
+/**
+ * @internal Build the default `normalize` hook: truncate integers and clamp to
+ * bounds. Like the default `validate`, it reads the live definition.
+ */
+export function _defaultNormalize(Class) {
+    return (component) => {
+        const record = component;
+        for (const check of checks(Class)) {
+            const value = record[check.name];
+            if (!check.array) {
+                record[check.name] = normalizeValue(check, value);
+            }
+            else if (Array.isArray(value)) {
+                for (let i = 0; i < value.length; i++) {
+                    value[i] = normalizeValue(check, value[i]);
+                }
+            }
+        }
+    };
+}
+function checks(Class) {
+    const result = [];
+    for (const [name, member] of _structMembers(Class) ?? []) {
+        const check = checkFor(name, member);
+        if (check !== undefined) {
+            result.push(check);
+        }
+    }
+    return result;
+}
+function checkFor(name, member) {
+    const element = elementType(member.type);
+    if (!isNumericType(element) || (member.range === undefined && !isIntegerType(element))) {
+        return undefined;
+    }
+    const integer = isIntegerType(element);
+    const bigint = isBigIntType(element);
+    let min = bigint ? 0n : -Infinity;
+    let max = bigint ? 0n : Infinity;
+    if (integer) {
+        [min, max] = INTEGER_BOUNDS[element];
+    }
+    if (member.range !== undefined) {
+        const [rangeMin, rangeMax] = member.range;
+        if (!integer || rangeMin > min) {
+            min = rangeMin;
+        }
+        if (!integer || rangeMax < max) {
+            max = rangeMax;
+        }
+    }
+    if (integer && !bigint) {
+        // A fractional range bound leaves only the integers inside it.
+        min = Math.ceil(min);
+        max = Math.floor(max);
+    }
+    return {
+        name,
+        array: isArrayType(member.type),
+        integer,
+        bigint,
+        min,
+        max,
+        values: member.values,
+    };
+}
+function validateValue(check, path, value, violations) {
+    if (check.bigint) {
+        if (typeof value !== "bigint") {
+            violations.push(`${path}: expected a bigint`);
+            return;
+        }
+    }
+    else if (typeof value !== "number" || isNaN(value)) {
+        violations.push(`${path}: expected a number`);
+        return;
+    }
+    else if (check.integer && !Number.isInteger(value)) {
+        violations.push(`${path}: ${value} is not an integer`);
+        return;
+    }
+    if (check.values !== undefined && !check.values.includes(value)) {
+        violations.push(`${path}: ${value} is not one of [${check.values.join(", ")}]`);
+        return;
+    }
+    if (value < check.min) {
+        violations.push(`${path}: ${value} is below the minimum ${check.min}`);
+    }
+    else if (value > check.max) {
+        violations.push(`${path}: ${value} is above the maximum ${check.max}`);
+    }
+}
+function normalizeValue(check, value) {
+    if (check.bigint) {
+        let n;
+        if (typeof value === "bigint") {
+            n = value;
+        }
+        else if (typeof value === "number" && Number.isFinite(value)) {
+            n = BigInt(Math.trunc(value));
+        }
+        else {
+            return value;
+        }
+        return n < check.min ? check.min : n > check.max ? check.max : n;
+    }
+    if (typeof value !== "number") {
+        return value;
+    }
+    let n = isNaN(value) ? 0 : value;
+    if (check.integer) {
+        n = Math.trunc(n);
+    }
+    return n < check.min ? check.min : n > check.max ? check.max : n;
+}
+//# sourceMappingURL=defaults.js.map

package/dist/reflection/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/reflection/defaults.ts"],"names":[],"mappings":"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"}

package/dist/reflection/member_types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A scalar member type.
+ *
+ * Integer types (`u8` … `i64`, `enum`) have fixed bounds; `u64` and `i64` hold
+ * `bigint` values. `enum` is an `i32` whose allowed values a member may list.
+ * `entity` holds an entity reference.
+ */
+export type MemberScalarType = "bool" | "u8" | "i8" | "u16" | "i16" | "u32" | "i32" | "u64" | "i64" | "enum" | "f32" | "f64" | "string" | "bytes" | "any" | "entity";
+/** A nested component class used as a member type. */
+export type MemberClass<T = unknown> = new () => T;
+/** The type of one array element: a scalar or a nested component class. */
+export type MemberElementType = MemberScalarType | MemberClass;
+/** A member type: a scalar, a nested component class, or an array `[type]`. */
+export type MemberType = MemberElementType | readonly [MemberElementType];
+/** A range bound. `u64` and `i64` members accept `bigint` bounds. */
+export type RangeBound = number | bigint;
+/**
+ * Reflection metadata for one component member, as stored in
+ * {@link VecsStruct.members}.
+ */
+export interface VecsMember {
+    /** The member's type. */
+    readonly type: MemberType;
+    /** Inclusive `[min, max]` bounds. Metadata only: nothing checks it on `set`. */
+    readonly range?: readonly [min: RangeBound, max: RangeBound];
+    /** Human-readable description. */
+    readonly description?: string;
+    /** Unit of measure, for example `"m"` or `"deg"`. */
+    readonly unit?: string;
+    /** Allowed values of an `enum` member. */
+    readonly values?: readonly number[];
+}

package/dist/reflection/member_types.js

@@ -0,0 +1,86 @@
+// Member type vocabulary shared by reflection, decorators and default hooks.
+//
+// The names match `lib/vecs-wire/src/decorators.ts` (`WireScalarType`): until
+// vecs-wire reads them from core, both packages carry the same list.
+/** @internal Integer bounds per integer scalar type. */
+export const INTEGER_BOUNDS = {
+    u8: [0, 0xff],
+    i8: [-0x80, 0x7f],
+    u16: [0, 0xffff],
+    i16: [-0x8000, 0x7fff],
+    u32: [0, 0xffffffff],
+    i32: [-0x80000000, 0x7fffffff],
+    enum: [-0x80000000, 0x7fffffff],
+    u64: [0n, 0xffffffffffffffffn],
+    i64: [-0x8000000000000000n, 0x7fffffffffffffffn],
+};
+const SCALAR_TYPES = new Set([
+    "bool",
+    "u8",
+    "i8",
+    "u16",
+    "i16",
+    "u32",
+    "i32",
+    "u64",
+    "i64",
+    "enum",
+    "f32",
+    "f64",
+    "string",
+    "bytes",
+    "any",
+    "entity",
+]);
+/** @internal Whether `type` is an array member type. */
+export function isArrayType(type) {
+    return Array.isArray(type);
+}
+/** @internal The element type of an array member, or the type itself. */
+export function elementType(type) {
+    return isArrayType(type) ? type[0] : type;
+}
+/** @internal Whether `type` is a numeric scalar: an integer type, `f32` or `f64`. */
+export function isNumericType(type) {
+    return type === "f32" || type === "f64" || isIntegerType(type);
+}
+/** @internal Whether `type` is an integer scalar, including `enum`, `u64` and `i64`. */
+export function isIntegerType(type) {
+    return typeof type === "string" && INTEGER_BOUNDS[type] !== undefined;
+}
+/** @internal Whether `type` holds `bigint` values. */
+export function isBigIntType(type) {
+    return type === "u64" || type === "i64";
+}
+/** @internal Throw a `TypeError` unless `type` is a valid member type. */
+export function assertMemberType(type, where) {
+    if (Array.isArray(type)) {
+        if (type.length !== 1) {
+            throw new TypeError(`${where}: an array type must contain exactly one element type`);
+        }
+        assertElementType(type[0], where);
+        return;
+    }
+    assertElementType(type, where);
+}
+/** @internal Compare two member types: same scalar, same class, or arrays of the same element. */
+export function memberTypesEqual(left, right) {
+    if (isArrayType(left) || isArrayType(right)) {
+        return isArrayType(left) && isArrayType(right) && left[0] === right[0];
+    }
+    return left === right;
+}
+/** @internal Render a member type for error messages. */
+export function formatMemberType(type) {
+    if (isArrayType(type)) {
+        return `[${formatMemberType(type[0])}]`;
+    }
+    return typeof type === "function" ? type.name || "anonymous class" : type;
+}
+function assertElementType(type, where) {
+    if (typeof type === "function" || (typeof type === "string" && SCALAR_TYPES.has(type))) {
+        return;
+    }
+    throw new TypeError(`${where}: unsupported member type ${String(type)}`);
+}
+//# sourceMappingURL=member_types.js.map

package/dist/reflection/member_types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"member_types.js","sourceRoot":"","sources":["../../src/reflection/member_types.ts"],"names":[],"mappings":"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"}

package/dist/reflection/vecs_struct.d.ts

@@ -0,0 +1,31 @@
+import { type MemberType, type RangeBound, type VecsMember } from "./member_types.js";
+/**
+ * Core component holding a component class's member reflection metadata.
+ *
+ * `world.component(C)` attaches it to the **component entity** of `C` as soon
+ * as `C` or a base class declares a member, through decorators ({@link type},
+ * {@link range}, …) or the fluent {@link Component.member} API. Query it like
+ * any component:
+ *
+ * ```ts
+ * world.component(Position).get(VecsStruct)?.members.x; // { type: "i32", range: [-100, 100] }
+ * ```
+ *
+ * The definition is per class for the whole process: every world attaches the
+ * same frozen instance, so `getMut(VecsStruct, …)` on it throws. Members are
+ * inherited, whichever way the base class declared them, and are listed base
+ * class first, then in declaration order. A declaration that contradicts the
+ * definition throws, naming the class and the member.
+ */
+export declare class VecsStruct {
+    /** Member metadata keyed by member name. */
+    readonly members: Readonly<Record<string, VecsMember>>;
+}
+/** A member declaration whose fields may still be incomplete. */
+export interface MemberDeclaration {
+    type?: MemberType;
+    range?: readonly [RangeBound, RangeBound];
+    description?: string;
+    unit?: string;
+    values?: readonly number[];
+}