@carbonenginejs/runtime-utils 0.1.4 → 0.1.6

package/package.json

@@ -1,139 +1,140 @@
-{
-  "name": "@carbonenginejs/runtime-utils",
-  "version": "0.1.4",
-  "description": "Browser-safe shared utilities, math, constants, Carbon types, schemas, documents, and runtime model primitives.",
-  "type": "module",
-  "main": "src/index.js",
-  "exports": {
-    ".": "./src/index.js",
-    "./arrays": "./src/arrays.js",
-    "./bytes": "./src/bytes.js",
-    "./compression": "./src/compression.js",
-    "./const": "./src/constants/index.js",
-    "./const/trinity": "./src/constants/trinity.js",
-    "./const/media": "./src/media/index.js",
-    "./const/graphics": "./src/graphics/index.js",
-    "./const/render-context": "./src/renderContext/index.js",
-    "./const/audio": "./src/audio/index.js",
-    "./const/shader": "./src/shader/index.js",
-    "./const/d3d": "./src/d3d/index.js",
-    "./const/webgpu": "./src/webgpu/index.js",
-    "./media": "./src/media/index.js",
-    "./graphics": "./src/graphics/index.js",
-    "./render-context": "./src/renderContext/index.js",
-    "./audio": "./src/audio/index.js",
-    "./shader": "./src/shader/index.js",
-    "./d3d": "./src/d3d/index.js",
-    "./webgpu": "./src/webgpu/index.js",
-    "./document": "./src/document/index.js",
-    "./errors": "./src/errors/index.js",
-    "./hydration": "./src/document/hydrationAdapter.js",
-    "./lifecycle": "./src/lifecycle/index.js",
-    "./schema": "./src/schema/index.js",
-    "./types": "./src/types/index.js",
-    "./model": "./src/model/index.js",
-    "./is": "./src/is.js",
-    "./json": "./src/json.js",
-    "./lookup": "./src/lookup.js",
-    "./object": "./src/object.js",
-    "./math": "./src/math/index.js",
-    "./math/scalar": "./src/math/scalar.js",
-    "./math/num": "./src/num.js",
-    "./math/vec2": "./src/vec2.js",
-    "./math/vec3": "./src/vec3.js",
-    "./math/vec4": "./src/vec4.js",
-    "./math/quat": "./src/quat.js",
-    "./math/mat3": "./src/mat3.js",
-    "./math/mat4": "./src/mat4.js",
-    "./math/box3": "./src/box3.js",
-    "./math/tri3": "./src/tri3.js",
-    "./math/lne3": "./src/lne3.js",
-    "./math/pln": "./src/pln.js",
-    "./math/ray3": "./src/ray3.js",
-    "./math/sph3": "./src/sph3.js",
-    "./math/pool": "./src/pool.js",
-    "./math/utils": "./src/utils.js",
-    "./math/noise": "./src/noise.js",
-    "./math/curve": "./src/curve.js",
-    "./math/vertex": "./src/vertex.js",
-    "./math/mesh": "./src/mesh.js",
-    "./math/tangent": "./src/tangent.js",
-    "./math/geometry": "./src/geometry/index.js",
-    "./num": "./src/num.js",
-    "./vec2": "./src/vec2.js",
-    "./vec3": "./src/vec3.js",
-    "./vec4": "./src/vec4.js",
-    "./quat": "./src/quat.js",
-    "./mat3": "./src/mat3.js",
-    "./mat4": "./src/mat4.js",
-    "./box3": "./src/box3.js",
-    "./tri3": "./src/tri3.js",
-    "./lne3": "./src/lne3.js",
-    "./pln": "./src/pln.js",
-    "./ray3": "./src/ray3.js",
-    "./sph3": "./src/sph3.js",
-    "./pool": "./src/pool.js",
-    "./utils": "./src/utils.js",
-    "./noise": "./src/noise.js",
-    "./curve": "./src/curve.js",
-    "./vertex": "./src/vertex.js",
-    "./mesh": "./src/mesh.js",
-    "./tangent": "./src/tangent.js",
-    "./geometry": "./src/geometry/index.js",
-    "./path": "./src/path.js",
-    "./text": "./src/text.js",
-    "./validation": "./src/validation.js"
-  },
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test",
-    "lint": "eslint --ext .js,.mjs src test",
-    "lint:fix": "eslint --fix --ext .js,.mjs src test",
-    "check": "npm run lint && npm test"
-  },
-  "keywords": [
-    "carbonenginejs",
-    "runtime",
-    "utilities",
-    "gl-matrix",
-    "constants",
-    "schema",
-    "types",
-    "errors",
-    "geometry",
-    "tangent",
-    "browser"
-  ],
-  "files": [
-    "src",
-    "docs",
-    "README.md",
-    "LICENSE",
-    "NOTICE",
-    "THIRD-PARTY-NOTICES.md"
-  ],
-  "license": "MIT",
-  "dependencies": {
-    "gl-matrix": "^3.4.4"
-  },
-  "devDependencies": {
-    "eslint": "^8.57.1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/carbonenginejs/runtime-utils.git"
-  },
-  "homepage": "https://github.com/carbonenginejs/runtime-utils#readme",
-  "bugs": {
-    "url": "https://github.com/carbonenginejs/runtime-utils/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "overrides": {
-    "brace-expansion": "^5.0.8"
-  }
-}
+{
+  "name": "@carbonenginejs/runtime-utils",
+  "version": "0.1.6",
+  "description": "Browser-safe shared utilities, math, constants, Carbon types, schemas, documents, and runtime model primitives.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./arrays": "./src/arrays.js",
+    "./bytes": "./src/bytes.js",
+    "./compression": "./src/compression.js",
+    "./const": "./src/constants/index.js",
+    "./const/trinity": "./src/constants/trinity.js",
+    "./const/media": "./src/media/index.js",
+    "./const/graphics": "./src/graphics/index.js",
+    "./const/render-context": "./src/renderContext/index.js",
+    "./const/audio": "./src/audio/index.js",
+    "./const/shader": "./src/shader/index.js",
+    "./const/d3d": "./src/d3d/index.js",
+    "./const/webgpu": "./src/webgpu/index.js",
+    "./media": "./src/media/index.js",
+    "./graphics": "./src/graphics/index.js",
+    "./render-context": "./src/renderContext/index.js",
+    "./audio": "./src/audio/index.js",
+    "./shader": "./src/shader/index.js",
+    "./d3d": "./src/d3d/index.js",
+    "./webgpu": "./src/webgpu/index.js",
+    "./document": "./src/document/index.js",
+    "./errors": "./src/errors/index.js",
+    "./hydration": "./src/document/hydrationAdapter.js",
+    "./lifecycle": "./src/lifecycle/index.js",
+    "./schema": "./src/schema/index.js",
+    "./types": "./src/types/index.js",
+    "./model": "./src/model/index.js",
+    "./is": "./src/is.js",
+    "./json": "./src/json.js",
+    "./lookup": "./src/lookup.js",
+    "./object": "./src/object.js",
+    "./math": "./src/math/index.js",
+    "./math/scalar": "./src/math/scalar.js",
+    "./math/num": "./src/num.js",
+    "./math/vec2": "./src/vec2.js",
+    "./math/vec3": "./src/vec3.js",
+    "./math/vec4": "./src/vec4.js",
+    "./math/quat": "./src/quat.js",
+    "./math/mat3": "./src/mat3.js",
+    "./math/mat4": "./src/mat4.js",
+    "./math/box3": "./src/box3.js",
+    "./math/tri3": "./src/tri3.js",
+    "./math/lne3": "./src/lne3.js",
+    "./math/pln": "./src/pln.js",
+    "./math/ray3": "./src/ray3.js",
+    "./math/sph3": "./src/sph3.js",
+    "./math/pool": "./src/pool.js",
+    "./math/utils": "./src/utils.js",
+    "./math/noise": "./src/noise.js",
+    "./math/curve": "./src/curve.js",
+    "./math/vertex": "./src/vertex.js",
+    "./math/mesh": "./src/mesh.js",
+    "./math/tangent": "./src/tangent.js",
+    "./math/geometry": "./src/geometry/index.js",
+    "./num": "./src/num.js",
+    "./vec2": "./src/vec2.js",
+    "./vec3": "./src/vec3.js",
+    "./vec4": "./src/vec4.js",
+    "./quat": "./src/quat.js",
+    "./mat3": "./src/mat3.js",
+    "./mat4": "./src/mat4.js",
+    "./box3": "./src/box3.js",
+    "./tri3": "./src/tri3.js",
+    "./lne3": "./src/lne3.js",
+    "./pln": "./src/pln.js",
+    "./ray3": "./src/ray3.js",
+    "./sph3": "./src/sph3.js",
+    "./pool": "./src/pool.js",
+    "./utils": "./src/utils.js",
+    "./noise": "./src/noise.js",
+    "./curve": "./src/curve.js",
+    "./vertex": "./src/vertex.js",
+    "./mesh": "./src/mesh.js",
+    "./tangent": "./src/tangent.js",
+    "./geometry": "./src/geometry/index.js",
+    "./path": "./src/path.js",
+    "./resfile": "./src/resFile.js",
+    "./text": "./src/text.js",
+    "./validation": "./src/validation.js"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint --ext .js,.mjs src test",
+    "lint:fix": "eslint --fix --ext .js,.mjs src test",
+    "check": "npm run lint && npm test"
+  },
+  "keywords": [
+    "carbonenginejs",
+    "runtime",
+    "utilities",
+    "gl-matrix",
+    "constants",
+    "schema",
+    "types",
+    "errors",
+    "geometry",
+    "tangent",
+    "browser"
+  ],
+  "files": [
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "gl-matrix": "^3.4.4"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carbonenginejs/runtime-utils.git"
+  },
+  "homepage": "https://github.com/carbonenginejs/runtime-utils#readme",
+  "bugs": {
+    "url": "https://github.com/carbonenginejs/runtime-utils/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "overrides": {
+    "brace-expansion": "^5.0.8"
+  }
+}

package/src/index.js

@@ -60,3 +60,4 @@ export * as tangent from "./tangent.js";
  * TypedArray
  * @typedef {Float64Array|Float32Array|Uint32Array|Uint16Array|Uint8Array|Uint8ClampedArray|Int32Array|Int16Array|Int8Array} TypedArray
  */
+export * from "./resFile.js";

package/src/resFile.js

@@ -0,0 +1,149 @@
+/**
+ * EVE resource file addressing.
+ *
+ * A resource's stored name IS its identity: a hash of its logical path, then
+ * the md5 of its contents. Two builds either carry the same address for a path
+ * or they do not, which makes address comparison - not file hashing - the way
+ * to tell whether anything changed.
+ *
+ * Deliberately no md5 here. Computing it is I/O, and the shape of that I/O
+ * differs per environment: a file stream in Node, an ArrayBuffer in a browser.
+ * The digest is passed in, so this module stays environment-neutral and every
+ * consumer shares one derivation instead of keeping its own.
+ */
+
+const ADDRESS = /^([a-f0-9]{2})\/([a-f0-9]{16})_([a-f0-9]{32})$/u;
+
+/** Lazily built byte-to-hex table. */
+let hex = null;
+
+/**
+ * FNV-1 (64-bit) over a resource's logical path.
+ *
+ * FNV-**1**, not 1a: the multiply happens before the XOR. Offset basis
+ * 0xcbf29ce484222325, prime 0x100000001b3, emitted as 16 lowercase hex digits.
+ *
+ * Verified against 1718 content-addressed entries from a real resfileindex.
+ *
+ * ONLY DEFINED FOR ASCII PATHS. Two implementations exist in the wild - one
+ * hashing UTF-8 bytes, one hashing UTF-16 code units - and they agree on every
+ * ASCII string and disagree beyond it. No real resource path has ever been
+ * non-ASCII, so no evidence exists for which is correct, and guessing would
+ * turn a dormant difference into a live wrong answer. A non-ASCII path
+ * therefore throws rather than returning something plausible.
+ *
+ * @param {String} logicalPath - the prefixed path, e.g. "res:/graphics/x.dds"
+ * @returns {String} 16 lowercase hex digits
+ */
+export function fnv164(logicalPath)
+{
+    const value = String(logicalPath);
+
+    if (!hex)
+    {
+        hex = [];
+        for (let i = 0; i < 256; i++) hex[i] = ((i >> 4) & 15).toString(16) + (i & 15).toString(16);
+    }
+
+    // 16-bit limbs, so the 64-bit multiply stays inside the safe integer range.
+    let v0 = 0x2325;
+    let v1 = 0x8422;
+    let v2 = 0x9ce4;
+    let v3 = 0xcbf2;
+
+    for (let i = 0; i < value.length; i++)
+    {
+        const code = value.charCodeAt(i);
+
+        if (code > 0x7f)
+        {
+            throw new RangeError(
+                `Resource path hashing is only defined for ASCII: ${JSON.stringify(value)}`,
+            );
+        }
+
+        // Multiply by 0x100000001b3: the low limb contributes 0x1b3 (435) to
+        // every limb, and the 0x100000000 term shifts two limbs left.
+        let t0 = v0 * 435;
+        let t1 = v1 * 435;
+        let t2 = v2 * 435 + (v0 << 8);
+        const t3 = v3 * 435 + (v1 << 8);
+
+        t1 += t0 >>> 16;
+        v0 = t0 & 0xffff;
+        t2 += t1 >>> 16;
+        v1 = t1 & 0xffff;
+        v3 = (t3 + (t2 >>> 16)) & 0xffff;
+        v2 = t2 & 0xffff;
+
+        v0 ^= code;
+    }
+
+    return hex[v3 >> 8] + hex[v3 & 255]
+        + hex[v2 >> 8] + hex[v2 & 255]
+        + hex[v1 >> 8] + hex[v1 & 255]
+        + hex[v0 >> 8] + hex[v0 & 255];
+}
+
+/**
+ * Builds a resource's stored address from its path and its content digest.
+ *
+ * The shard directory is the first two characters of the path hash itself, not
+ * a separate value - a detail that is easy to reimplement wrongly.
+ *
+ * @param {String} logicalPath
+ * @param {String} md5 - 32 hex digits, the md5 of the file's contents
+ * @returns {String} "<shard>/<pathHash>_<md5>"
+ */
+export function resFileAddress(logicalPath, md5)
+{
+    const digest = String(md5).toLowerCase();
+
+    if (!/^[a-f0-9]{32}$/u.test(digest))
+    {
+        throw new TypeError(`Resource content digest must be 32 hex digits: ${md5}`);
+    }
+
+    const pathHash = fnv164(logicalPath);
+
+    return `${pathHash.slice(0, 2)}/${pathHash}_${digest}`;
+}
+
+/**
+ * Splits a stored address into its parts, or null when it is not one.
+ *
+ * Null rather than throwing: an index legitimately carries plain paths for
+ * overlay entries alongside content-addressed ones, so "not an address" is an
+ * ordinary answer rather than an error.
+ *
+ * @param {String} address
+ * @returns {{shard: String, pathHash: String, checksum: String}|null}
+ */
+export function parseResFileAddress(address)
+{
+    const match = String(address ?? "").toLowerCase().match(ADDRESS);
+
+    return match ? { shard: match[1], pathHash: match[2], checksum: match[3] } : null;
+}
+
+/**
+ * Checks a stored address against the path it claims to be for.
+ *
+ * Only the path half can be checked without reading the file; the content half
+ * is verifiable only against the bytes. Returns false rather than throwing so a
+ * caller can survey an index without exception handling - except for a
+ * non-ASCII path, where the answer is genuinely unknown.
+ *
+ * @param {String} address
+ * @param {String} logicalPath
+ * @returns {Boolean}
+ */
+export function isResFileAddressFor(address, logicalPath)
+{
+    const parts = parseResFileAddress(address);
+
+    if (!parts) return false;
+
+    return parts.pathHash === fnv164(logicalPath)
+        && parts.shard === parts.pathHash.slice(0, 2);
+}

package/src/schema/CjsSchema.js

@@ -232,7 +232,19 @@ export class CjsSchema
         unknown: fieldDecorator("type", { kind: "unknown" }),
         vec2: fieldDecorator("type", { kind: "vec2" }),
         vec3: fieldDecorator("type", { kind: "vec3" }),
-        vec4: fieldDecorator("type", { kind: "vec4" })
+        vec4: fieldDecorator("type", { kind: "vec4" }),
+
+        // An enum names the vocabulary a field's values are drawn from, which
+        // is part of its type - it belongs here beside int32 and string rather
+        // than under a separate namespace. define and hideInherited show this
+        // namespace already carries class decorators as well as field ones.
+        enum: values => fieldDecorator("enum", normalizeEnumDefinition(values)),
+
+        /**
+         * Hides named inherited fields from a subclass's schema, for a subclass
+         * that genuinely does not carry part of its parent's shape.
+         */
+        hideInherited: fieldNames => hiddenInheritedFieldsDecorator(normalizeHiddenInheritedFields(fieldNames))
     });
 
     static io = Object.freeze({