@carbonenginejs/runtime-utils 0.1.0 → 0.1.2

package/src/errors/CjsError.js

@@ -0,0 +1,286 @@
+import { isPlainObject } from "../is.js";
+
+const
+    ERROR_CODE_PATTERN = /^CJS_[A-Z][A-Z0-9]*(?:_[A-Z][A-Z0-9]*)*$/u,
+    DEFAULT_CANCELLATION_MESSAGE = "The operation was cancelled.";
+
+export const CJS_OPERATION_CANCELLED = "CJS_OPERATION_CANCELLED";
+
+/**
+ * Represents one structured operational failure with a stable CarbonEngineJS code.
+ *
+ * Programmer-contract violations should continue to use native error classes
+ * such as `TypeError`, `RangeError`, and `SyntaxError`.
+ */
+export class CjsError extends Error
+{
+
+    /**
+     * Creates an operational error.
+     *
+     * Details are detached and deeply frozen JSON-safe data. Cause identity is
+     * preserved through the native `Error` cause property when supplied.
+     *
+     * @param {string} code Stable uppercase `CJS_*` machine-readable code.
+     * @param {string} message Human-readable failure description.
+     * @param {{cause?: *, details?: object|null}} [options]
+     */
+    constructor(code, message, options = {})
+    {
+        const
+            normalizedCode = CjsError.#NormalizeCode(code),
+            normalizedMessage = CjsError.#NormalizeMessage(message),
+            normalizedOptions = CjsError.#NormalizeOptions(options),
+            errorOptions = Object.hasOwn(normalizedOptions, "cause")
+                ? { cause: normalizedOptions.cause }
+                : undefined;
+
+        super(normalizedMessage, errorOptions);
+
+        this.name = new.target.name;
+
+        Object.defineProperties(this, {
+            code: {
+                value: normalizedCode,
+                enumerable: true,
+                configurable: false,
+                writable: false
+            },
+            details: {
+                value: CjsError.#NormalizeDetails(normalizedOptions.details),
+                enumerable: true,
+                configurable: false,
+                writable: false
+            }
+        });
+    }
+
+    /**
+     * Checks a structured or legacy error for an exact stable code.
+     *
+     * Invalid candidate codes and inaccessible error properties return false
+     * so this helper remains safe inside failure handling.
+     */
+    static hasCode(error, code)
+    {
+        if (!CjsError.#IsCode(code) || error === null || error === undefined)
+        {
+            return false;
+        }
+
+        try
+        {
+            return error.code === code;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    /** Reports whether a value is one valid stable error code. */
+    static #IsCode(value)
+    {
+        return typeof value === "string" && ERROR_CODE_PATTERN.test(value);
+    }
+
+    /** Validates and returns one stable error code. */
+    static #NormalizeCode(value)
+    {
+        if (!CjsError.#IsCode(value))
+        {
+            throw new TypeError("code must be an uppercase CJS_* identifier.");
+        }
+
+        return value;
+    }
+
+    /** Validates and returns one non-empty error message. */
+    static #NormalizeMessage(value)
+    {
+        if (typeof value !== "string" || value.trim() === "")
+        {
+            throw new TypeError("message must be a non-empty string.");
+        }
+
+        return value;
+    }
+
+    /** Validates and returns one plain constructor-options record. */
+    static #NormalizeOptions(value)
+    {
+        if (!isPlainObject(value))
+        {
+            throw new TypeError("options must be a plain object.");
+        }
+
+        return value;
+    }
+
+    /** Converts optional details into detached deeply frozen data. */
+    static #NormalizeDetails(value)
+    {
+        if (value === undefined || value === null)
+        {
+            return null;
+        }
+
+        if (!isPlainObject(value))
+        {
+            throw new TypeError("details must be a JSON-safe plain object or null.");
+        }
+
+        return CjsError.#CloneDetailsValue(value, "details", new Set());
+    }
+
+    /** Clones one JSON-safe details value while detecting active cycles. */
+    static #CloneDetailsValue(value, path, active)
+    {
+        if (value === null || typeof value === "string" || typeof value === "boolean")
+        {
+            return value;
+        }
+
+        if (typeof value === "number")
+        {
+            if (!Number.isFinite(value))
+            {
+                throw new TypeError(`${path} must contain only finite numbers.`);
+            }
+
+            return value;
+        }
+
+        if (!Array.isArray(value) && !isPlainObject(value))
+        {
+            throw new TypeError(`${path} must contain only JSON-safe values.`);
+        }
+
+        if (active.has(value))
+        {
+            throw new TypeError(`${path} must not contain a circular reference.`);
+        }
+
+        active.add(value);
+
+        const clone = Array.isArray(value)
+            ? CjsError.#CloneDetailsArray(value, path, active)
+            : CjsError.#CloneDetailsRecord(value, path, active);
+
+        active.delete(value);
+        return Object.freeze(clone);
+    }
+
+    /** Clones one dense JSON-safe details array. */
+    static #CloneDetailsArray(value, path, active)
+    {
+        const clone = [];
+
+        for (const key of Reflect.ownKeys(value))
+        {
+            if (key === "length")
+            {
+                continue;
+            }
+
+            if (typeof key !== "string"
+                || !/^(?:0|[1-9]\d*)$/u.test(key)
+                || Number(key) >= value.length)
+            {
+                throw new TypeError(`${path} arrays must contain only indexed values.`);
+            }
+        }
+
+        for (let i = 0; i < value.length; i++)
+        {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
+
+            if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value"))
+            {
+                throw new TypeError(`${path} arrays must contain dense data properties.`);
+            }
+
+            clone.push(CjsError.#CloneDetailsValue(
+                descriptor.value,
+                `${path}[${i}]`,
+                active
+            ));
+        }
+
+        return clone;
+    }
+
+    /** Clones one plain JSON-safe details record. */
+    static #CloneDetailsRecord(value, path, active)
+    {
+        const clone = {};
+
+        for (const key of Reflect.ownKeys(value))
+        {
+            if (typeof key !== "string")
+            {
+                throw new TypeError(`${path} must not contain symbol keys.`);
+            }
+
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+
+            if (!descriptor?.enumerable || !Object.hasOwn(descriptor, "value"))
+            {
+                throw new TypeError(`${path} must contain only enumerable data properties.`);
+            }
+
+            Object.defineProperty(clone, key, {
+                value: CjsError.#CloneDetailsValue(
+                    descriptor.value,
+                    `${path}[${JSON.stringify(key)}]`,
+                    active
+                ),
+                enumerable: true,
+                configurable: false,
+                writable: false
+            });
+        }
+
+        return clone;
+    }
+
+}
+
+/** Represents one cancelled operation using Web-compatible abort identity. */
+export class CjsCancellationError extends CjsError
+{
+
+    /**
+     * Creates a cancellation error with stable code `CJS_OPERATION_CANCELLED`.
+     *
+     * @param {string} [message]
+     * @param {{cause?: *, details?: object|null}} [options]
+     */
+    constructor(message = DEFAULT_CANCELLATION_MESSAGE, options = {})
+    {
+        super(CJS_OPERATION_CANCELLED, message, options);
+        this.name = "AbortError";
+    }
+
+    /**
+     * Checks for this cancellation type, its stable code, or a platform
+     * `AbortError` name.
+     */
+    static is(error)
+    {
+        if (CjsError.hasCode(error, CJS_OPERATION_CANCELLED))
+        {
+            return true;
+        }
+
+        try
+        {
+            return error?.name === "AbortError";
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+}

package/src/errors/index.js

@@ -0,0 +1,5 @@
+export {
+    CJS_OPERATION_CANCELLED,
+    CjsCancellationError,
+    CjsError
+} from "./CjsError.js";

package/src/index.js

@@ -11,6 +11,8 @@ export * as json from "./json.js";
 export * from "./json.js";
 export * as lookup from "./lookup.js";
 export * from "./lookup.js";
+export * as object from "./object.js";
+export * from "./object.js";
 export * as path from "./path.js";
 export * from "./path.js";
 export * as text from "./text.js";
@@ -21,6 +23,8 @@ export {
     assertNonEmptyString,
     assertSupportedVersion
 } from "./validation.js";
+export * as errors from "./errors/index.js";
+export * from "./errors/index.js";
 
 export * as constants from "./constants/index.js";
 export * from "./constants/index.js";

package/src/is.js

@@ -143,15 +143,77 @@ export function isError(a)
  * @param {*} a
  * @returns {Boolean}
  */
-export function isNumber(a)
-{
-    return isTag(a, "[object Number]");
-}
-
-/**
- * Checks if a value is a function
- * @param {*} a
- * @returns {Boolean}
+export function isNumber(a)
+{
+    return isTag(a, "[object Number]");
+}
+
+/**
+ * Checks if a value fits a signed 8-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isInt8(value)
+{
+    return Number.isInteger(value) && value >= -0x80 && value <= 0x7f;
+}
+
+/**
+ * Checks if a value fits an unsigned 8-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isUint8(value)
+{
+    return Number.isInteger(value) && value >= 0 && value <= 0xff;
+}
+
+/**
+ * Checks if a value fits a signed 16-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isInt16(value)
+{
+    return Number.isInteger(value) && value >= -0x8000 && value <= 0x7fff;
+}
+
+/**
+ * Checks if a value fits an unsigned 16-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isUint16(value)
+{
+    return Number.isInteger(value) && value >= 0 && value <= 0xffff;
+}
+
+/**
+ * Checks if a value fits a signed 32-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isInt32(value)
+{
+    return Number.isInteger(value)
+        && value >= -0x80000000
+        && value <= 0x7fffffff;
+}
+
+/**
+ * Checks if a value fits an unsigned 32-bit integer.
+ * @param {*} value
+ * @returns {Boolean}
+ */
+export function isUint32(value)
+{
+    return Number.isInteger(value) && value >= 0 && value <= 0xffffffff;
+}
+
+/**
+ * Checks if a value is a function
+ * @param {*} a
+ * @returns {Boolean}
  */
 export function isFunction(a)
 {

package/src/mesh.js

@@ -45,13 +45,42 @@ function validateIndices(indices, vertexCount)
  */
 export function triangleNormal(a, b, c)
 {
-    const normal = [ 0, 0, 0 ];
-    cross(
-        normal,
-        [ b[0] - a[0], b[1] - a[1], b[2] - a[2] ],
-        [ c[0] - a[0], c[1] - a[1], c[2] - a[2] ]
-    );
-    return normalize(normal, normal);
+    return triangleNormalTo([ 0, 0, 0 ], a, b, c);
+}
+
+/**
+ * Calculate a unit face normal into caller-owned storage.
+ *
+ * @param {ArrayLike<number>} out Receiving xyz vector.
+ * @param {ArrayLike<number>} a First xyz vertex.
+ * @param {ArrayLike<number>} b Second xyz vertex.
+ * @param {ArrayLike<number>} c Third xyz vertex.
+ * @returns {ArrayLike<number>} The receiving vector.
+ */
+export function triangleNormalTo(out, a, b, c)
+{
+    const
+        abX = b[0] - a[0],
+        abY = b[1] - a[1],
+        abZ = b[2] - a[2],
+        acX = c[0] - a[0],
+        acY = c[1] - a[1],
+        acZ = c[2] - a[2];
+
+    out[0] = abY * acZ - abZ * acY;
+    out[1] = abZ * acX - abX * acZ;
+    out[2] = abX * acY - abY * acX;
+
+    const length = Math.hypot(out[0], out[1], out[2]);
+
+    if (length > 0)
+    {
+        out[0] /= length;
+        out[1] /= length;
+        out[2] /= length;
+    }
+
+    return out;
 }
 
 /**
@@ -383,6 +412,7 @@ export function generateBiNormals(normals, tangents, options = {})
 
 export const mesh = Object.freeze({
     triangleNormal,
+    triangleNormalTo,
     triangleArea2,
     isDegenerateTriangle,
     computeBoundsFromPositions,

package/src/model/CjsModel.js

@@ -13,6 +13,15 @@ const MAX_UPDATE_PASSES = 32;
  */
 export class CjsModel extends CjsEventEmitter
 {
+    /**
+     * Identifies this class as a schema-backed model.
+     *
+     * Declared statically so CjsSchema can recognise a model class from a field
+     * declaration alone, without importing CjsModel - which it cannot do, since
+     * this module already imports CjsSchema. Mirrors `CjsResource.isResource`.
+     */
+    static isModel = true;
+
     /**
      * Creates a schema-backed model with initialized runtime state.
      */
@@ -208,16 +217,18 @@ export class CjsModel extends CjsEventEmitter
 
             if (descend)
             {
-                const fields = getModelFields(model);
-                const start = reverse ? fields.length - 1 : 0;
-                const end = reverse ? -1 : fields.length;
+                // Only the fields declared to hold child models, precomputed per
+                // class - not every field, type-tested per value per visit.
+                const children = CjsSchema.getSchema(model.constructor).children;
+                const start = reverse ? children.length - 1 : 0;
+                const end = reverse ? -1 : children.length;
                 const step = reverse ? -1 : 1;
 
                 for (let i = start; i !== end; i += step)
                 {
-                    const field = fields[i];
-                    if (options.ownedOnly === true && field.io?.ownership !== "owned") continue;
-                    const value = model[field.name];
+                    const child = children[i];
+                    if (options.ownedOnly === true && !child.owned) continue;
+                    const value = model[child.name];
 
                     if (Array.isArray(value))
                     {
@@ -242,19 +253,47 @@ export class CjsModel extends CjsEventEmitter
     /**
      * Collects unique resources reported by this model graph into an array.
      *
+     * Every model in the graph is visited: reporting resources does not hide a
+     * model's descendants, because an under-reported dependency set would let
+     * readiness checks pass while a child's resources were still loading.
+     *
+     * Resources held in schema fields are collected automatically - they are
+     * already declared, as `@type.objectRef("TriGeometryRes")` and friends, so
+     * restating them in a hook would be the hand-written relay chain this
+     * traversal exists to replace.
+     *
+     * `OnGetResources()` is the escape hatch for resources a model holds
+     * outside its schema, such as private fields. It takes no arguments and
+     * always returns an iterable of resources - never a bare resource and never
+     * nothing. Most models do not implement it.
+     *
      * @param {Array<*>} [out=[]] Output array, whose contents are replaced.
      * @returns {Array<*>} The supplied output array.
      */
     GetResources(out = [])
     {
         const resources = new Set();
-        AddResources(resources, out);
 
         this.Traverse(model =>
         {
-            if (typeof model.OnGetResources !== "function") return true;
-            AddResources(resources, model.OnGetResources(resources));
-            return false;
+            for (const field of CjsSchema.getSchema(model.constructor).resources)
+            {
+                const value = model[field.name];
+                if (Array.isArray(value))
+                {
+                    for (const item of value) AddResource(resources, item);
+                }
+                else
+                {
+                    AddResource(resources, value);
+                }
+            }
+
+            if (typeof model.OnGetResources === "function")
+            {
+                AddResources(resources, model.OnGetResources());
+            }
+            return true;
         });
 
         out.length = 0;
@@ -776,17 +815,23 @@ function initializeOwnedGraph(root, options = {})
     return root;
 }
 
+function AddResource(target, value)
+{
+    if (value?.isResource === true) target.add(value);
+}
+
+
 function AddResources(target, values)
 {
-    if (values === null || values === undefined) return;
-    if (values?.isResource === true)
+    if (typeof values === "string" || typeof values?.[Symbol.iterator] !== "function")
     {
-        target.add(values);
-        return;
+        throw new TypeError("CjsModel.OnGetResources must return an iterable of resources.");
     }
-    if (typeof values !== "string" && typeof values[Symbol.iterator] === "function")
+
+    // Empty slots are the model's own unset fields, not a contract violation.
+    for (const value of values)
     {
-        for (const value of values) AddResources(target, value);
+        if (value !== null && value !== undefined) target.add(value);
     }
 }
 

package/src/object.js

@@ -0,0 +1,39 @@
+/**
+ * Invokes handlers for keys explicitly owned by a source object.
+ *
+ * @param {object|Function} source Source values.
+ * @param {object} handlers Property-keyed handler functions.
+ * @param {*} [context=null] Optional `this` value for handlers.
+ * @returns {number} Number of invoked handlers.
+ */
+export function hasOwnThen(source, handlers, context = null)
+{
+    if (!source || (typeof source !== "object" && typeof source !== "function"))
+    {
+        throw new TypeError("hasOwnThen source must be an object or function.");
+    }
+
+    if (!handlers || typeof handlers !== "object" || Array.isArray(handlers))
+    {
+        throw new TypeError("hasOwnThen handlers must be an object.");
+    }
+
+    let invoked = 0;
+
+    for (const property of Reflect.ownKeys(handlers))
+    {
+        if (!Object.hasOwn(source, property)) continue;
+
+        const handler = handlers[property];
+
+        if (typeof handler !== "function")
+        {
+            throw new TypeError(`hasOwnThen handler must be a function: ${String(property)}.`);
+        }
+
+        handler.call(context, source[property], source, property);
+        invoked++;
+    }
+
+    return invoked;
+}

package/src/path.js

@@ -19,3 +19,35 @@ export function normalizePath(value, options = {})
 
     return options.lowerCase ? result.toLowerCase() : result;
 }
+
+/** Normalizes a case-insensitive URI-style resource path. */
+export function normalizeResourcePath(value)
+{
+    return normalizePath(value, { lowerCase: true });
+}
+
+/** Returns the normalized extension of a URI-style resource path. */
+export function getResourceExtension(value)
+{
+    const path = normalizeResourcePath(value);
+    const queryIndex = path.search(/[?#]/u);
+    const cleanPath = queryIndex === -1 ? path : path.slice(0, queryIndex);
+    const slashIndex = cleanPath.lastIndexOf("/");
+    const dotIndex = cleanPath.lastIndexOf(".");
+
+    if (dotIndex === -1 || dotIndex < slashIndex)
+    {
+        return "";
+    }
+
+    return cleanPath.slice(dotIndex + 1);
+}
+
+/** Normalizes a resource extension without its optional leading dot. */
+export function normalizeResourceExtension(value)
+{
+    return String(value ?? "")
+        .trim()
+        .replace(/^\./u, "")
+        .toLowerCase();
+}