@spine-event-engine/core 2.0.0-snapshot.16 → 2.0.0-snapshot.18

package/dist/index.js

@@ -181,13 +181,30 @@ export class ValidationException extends Error {
         return this.#messageData;
     }
 }
+/**
+ * Constructs a rejection after its generated message has been validated.
+ *
+ * @typeParam Schema Generated rejection message schema.
+ * @param schema Schema used to snapshot the message.
+ * @param messageData Validated rejection message.
+ * @returns Nominal rejection throwable.
+ */
 let instantiateRejection;
 /**
  * A nominal domain rejection carrying its generated Protobuf message.
+ *
+ * @typeParam Schema Generated schema of the rejection message.
  */
 export class RejectionThrowable extends Error {
     #schema;
     #messageData;
+    /**
+     * Captures a validated rejection through the private factory token.
+     *
+     * @param schema Generated rejection message schema.
+     * @param messageData Validated rejection message to snapshot.
+     * @param token Token restricting construction to the factory.
+     */
     constructor(schema, messageData, token) {
         super(`Rejected: ${schema.typeName}`);
         if (token !== REJECTION_CONSTRUCTOR) {
@@ -201,7 +218,18 @@ export class RejectionThrowable extends Error {
         Object.preventExtensions(this);
     }
     static {
-        instantiateRejection = (schema, messageData) => new RejectionThrowable(schema, messageData, REJECTION_CONSTRUCTOR);
+        instantiateRejection = (schema, messageData) => RejectionThrowable.instantiate(schema, messageData);
+    }
+    /**
+     * Creates a typed rejection through the private constructor.
+     *
+     * @typeParam CreatedSchema Generated rejection message schema.
+     * @param schema Schema used to snapshot the message.
+     * @param messageData Validated rejection message.
+     * @returns Nominal rejection throwable.
+     */
+    static instantiate(schema, messageData) {
+        return new RejectionThrowable(schema, messageData, REJECTION_CONSTRUCTOR);
     }
     /**
      * Returns the generated Protobuf-ES schema for the rejected domain signal.
@@ -226,6 +254,7 @@ export class RejectionThrowable extends Error {
     }
     /**
      * Creates a nominal throwable from a validated generated rejection message.
+     * @typeParam Schema Generated rejection message schema.
      * @param schema The generated rejection schema.
      * @param input The rejection message fields.
      * @returns The validated nominal rejection throwable.
@@ -242,6 +271,11 @@ export class RejectionThrowable extends Error {
     static is(value) {
         return typeof value === "object" && value !== null && REJECTION_THROWABLES.has(value);
     }
+    /**
+     * Validates that a schema is a top-level message from a rejection schema file.
+     *
+     * @param schema Candidate generated rejection schema.
+     */
     static assertSchema(schema) {
         const basename = schema.file.proto.name.split("/").at(-1);
         const rejectionSource = basename === "rejections.proto" || basename?.endsWith("_rejections.proto") === true;
@@ -249,6 +283,14 @@ export class RejectionThrowable extends Error {
             throw new TypeError(`Rejection schema "${schema.typeName}" must be a top-level message declared in a rejections.proto file.`);
         }
     }
+    /**
+     * Copies a rejection message through its binary representation.
+     *
+     * @typeParam Schema Generated rejection message schema.
+     * @param schema Schema used to encode and decode the message.
+     * @param message Rejection message to copy.
+     * @returns Independent message snapshot.
+     */
     static snapshot(schema, message) {
         return fromBinary(schema, toBinary(schema, message));
     }
@@ -268,6 +310,7 @@ export const Validate = {
     },
     /**
      * Validates one Protobuf message through the Spine TS validation facade.
+     * @typeParam Schema Generated schema of the message being validated.
      * @param schema The message schema.
      * @param message The message to validate.
      * @returns The sanitized validation result.
@@ -284,6 +327,7 @@ export const Validate = {
     },
     /**
      * Validates one Protobuf message and throws for constraint violations.
+     * @typeParam Schema Generated schema of the message being validated.
      * @param schema The message schema.
      * @param message The message to validate.
      * @returns The validated message.
@@ -296,6 +340,7 @@ export const Validate = {
     },
     /**
      * Validates a previous/next state pair with framework-owned transition rules.
+     * @typeParam Schema Generated schema shared by both states.
      * @param request The state transition.
      * @param rules The rules to apply.
      * @returns The sanitized transition result.
@@ -378,6 +423,7 @@ export const AnyMessages = {
     // prettier-ignore
     /**
      * Packs a message into `Any`, omitting unknown fields from binary output.
+     * @typeParam Schema Generated schema of the enclosed message.
      * @param schema The message schema.
      * @param message The message to pack.
      * @param options The packing options.
@@ -393,6 +439,7 @@ export const AnyMessages = {
     },
     /**
      * Unpacks an `Any` when its type URL exactly matches the requested schema.
+     * @typeParam Schema Generated schema expected in the envelope.
      * @param packed The packed message.
      * @param schema The expected schema.
      * @returns The unpacked message, when valid.
@@ -429,8 +476,23 @@ Object.freeze(AnyMessages);
 function isProtobufRegistry(types) {
     return "kind" in types;
 }
+/**
+ * Creates reversible compact Proto JSON conversion for a generated message.
+ *
+ * @typeParam Schema Generated schema used for conversion.
+ * @param schema Message schema used for Proto JSON.
+ * @param registry Optional registry for expanding packed Any messages.
+ * @param typeUrls Canonical URLs restored on parsed Any messages.
+ * @returns Schema-bound stringifier.
+ */
 function defaultMessageStringifier(schema, registry, typeUrls) {
     return Object.freeze({
+        /**
+         * Parses compact Proto JSON and restores canonical Any type URLs.
+         *
+         * @param value Compact Proto JSON text.
+         * @returns Parsed generated message.
+         */
         fromString(value) {
             const message = registry === undefined
                 ? fromJsonString(schema, value)
@@ -438,6 +500,12 @@ function defaultMessageStringifier(schema, registry, typeUrls) {
             restoreAnyTypeUrls(message, typeUrls);
             return message;
         },
+        /**
+         * Serializes a generated message as compact Proto JSON.
+         *
+         * @param value Generated message to serialize.
+         * @returns Compact Proto JSON text.
+         */
         toString(value) {
             return registry === undefined
                 ? toJsonString(schema, value)
@@ -466,6 +534,13 @@ function restoreAnyTypeUrls(value, typeUrls) {
         restoreAnyTypeUrls(item, typeUrls);
 }
 const FieldStringifiers = Object.freeze({
+    /**
+     * Returns reversible conversion for one singular message, enum, or scalar field.
+     *
+     * @param field Generated descriptor of the field.
+     * @param messageStringifier Resolves conversion for message-valued fields.
+     * @returns Stringifier for the field's runtime value.
+     */
     create(field, messageStringifier) {
         switch (field.fieldKind) {
             case "message":
@@ -479,13 +554,31 @@ const FieldStringifiers = Object.freeze({
                 throw new Error("Stringifiers support only singular Protobuf fields.");
         }
     },
+    /**
+     * Creates enum conversion using declared names and valid numeric values.
+     *
+     * @param field Generated enum field descriptor.
+     * @returns Reversible enum stringifier.
+     */
     enum(field) {
         return Object.freeze({
+            /**
+             * Parses a declared enum name or valid integer text.
+             *
+             * @param value Enum name or canonical numeric text.
+             * @returns Enum numeric value.
+             */
             fromString(value) {
                 const named = field.enum.values.find((candidate) => candidate.name === value);
                 return (named?.number ??
                     Number(FieldStringifiers.integerText(value, -(2n ** 31n), 2n ** 31n - 1n)));
             },
+            /**
+             * Formats an enum number as its declared name or integer text.
+             *
+             * @param value Valid enum numeric value.
+             * @returns Declared name when available, otherwise numeric text.
+             */
             toString(value) {
                 if (typeof value !== "number" || !Number.isInteger(value)) {
                     throw new TypeError("Enum field value must be an integer number.");
@@ -495,6 +588,12 @@ const FieldStringifiers = Object.freeze({
             },
         });
     },
+    /**
+     * Returns conversion and range rules for a Protobuf scalar field.
+     *
+     * @param field Generated scalar field descriptor.
+     * @returns Reversible scalar stringifier.
+     */
     scalar(field) {
         switch (field.scalar) {
             case ScalarType.STRING:
@@ -524,9 +623,21 @@ const FieldStringifiers = Object.freeze({
         }
     },
     string: Object.freeze({
+        /**
+         * Accepts a string field without changing its text.
+         *
+         * @param value Stored string text.
+         * @returns The same string value.
+         */
         fromString(value) {
             return value;
         },
+        /**
+         * Checks and returns a string field value.
+         *
+         * @param value Runtime string field value.
+         * @returns The same string text.
+         */
         toString(value) {
             if (typeof value !== "string")
                 throw new TypeError("Field value must be a string.");
@@ -534,6 +645,12 @@ const FieldStringifiers = Object.freeze({
         },
     }),
     boolean: Object.freeze({
+        /**
+         * Parses canonical boolean text.
+         *
+         * @param value Text required to be `true` or `false`.
+         * @returns Decoded boolean value.
+         */
         fromString(value) {
             if (value === "true")
                 return true;
@@ -541,6 +658,12 @@ const FieldStringifiers = Object.freeze({
                 return false;
             throw new Error("Field value must be a canonical boolean.");
         },
+        /**
+         * Formats a boolean as canonical text.
+         *
+         * @param value Runtime boolean field value.
+         * @returns `true` or `false`.
+         */
         toString(value) {
             if (typeof value !== "boolean")
                 throw new TypeError("Field value must be a boolean.");
@@ -548,6 +671,12 @@ const FieldStringifiers = Object.freeze({
         },
     }),
     bytes: Object.freeze({
+        /**
+         * Decodes a canonical standard-base64 byte field.
+         *
+         * @param value Canonical base64 text.
+         * @returns Decoded bytes.
+         */
         fromString(value) {
             let decoded;
             try {
@@ -561,6 +690,12 @@ const FieldStringifiers = Object.freeze({
             }
             return decoded;
         },
+        /**
+         * Encodes a byte field as standard base64.
+         *
+         * @param value Runtime byte array.
+         * @returns Canonical base64 text.
+         */
         toString(value) {
             if (!(value instanceof Uint8Array)) {
                 throw new TypeError("Field value must be a byte array.");
@@ -569,6 +704,12 @@ const FieldStringifiers = Object.freeze({
         },
     }),
     number: Object.freeze({
+        /**
+         * Parses canonical finite numeric text, preserving negative zero.
+         *
+         * @param value Canonical finite number text.
+         * @returns Parsed finite number.
+         */
         fromString(value) {
             const parsed = Number(value);
             if (!Number.isFinite(parsed))
@@ -578,6 +719,12 @@ const FieldStringifiers = Object.freeze({
                 throw new Error("Field value must be a canonical number.");
             return parsed;
         },
+        /**
+         * Formats a finite number canonically, preserving negative zero.
+         *
+         * @param value Runtime finite number.
+         * @returns Canonical numeric text.
+         */
         toString(value) {
             if (typeof value !== "number" || !Number.isFinite(value)) {
                 throw new TypeError("Field value must be a finite number.");
@@ -586,6 +733,12 @@ const FieldStringifiers = Object.freeze({
         },
     }),
     float: Object.freeze({
+        /**
+         * Parses canonical binary32 text and rejects values outside its range.
+         *
+         * @param value Canonical binary32 number text.
+         * @returns Rounded binary32 number.
+         */
         fromString(value) {
             const parsed = Number(value);
             if (!Number.isFinite(parsed))
@@ -599,6 +752,12 @@ const FieldStringifiers = Object.freeze({
             }
             return restored;
         },
+        /**
+         * Converts a finite number to canonical binary32 text.
+         *
+         * @param value Runtime finite number.
+         * @returns Canonical binary32 number text.
+         */
         toString(value) {
             if (typeof value !== "number" || !Number.isFinite(value)) {
                 throw new TypeError("Field value must be a finite number.");
@@ -610,6 +769,12 @@ const FieldStringifiers = Object.freeze({
             return FieldStringifiers.floatText(normalized);
         },
     }),
+    /**
+     * Finds the shortest decimal text that round-trips to a binary32 value.
+     *
+     * @param value Finite binary32 number to format.
+     * @returns Canonical short decimal text.
+     */
     floatText(value) {
         if (Object.is(value, -0))
             return "-0";
@@ -622,8 +787,22 @@ const FieldStringifiers = Object.freeze({
         }
         throw new Error("Unable to format the float32 field value.");
     },
+    /**
+     * Creates range-checked integer conversion for a declared runtime representation.
+     *
+     * @param min Smallest integer accepted by the field.
+     * @param max Largest integer accepted by the field.
+     * @param representation Runtime number, bigint, or string representation.
+     * @returns Reversible bounded integer stringifier.
+     */
     integer(min, max, representation) {
         return Object.freeze({
+            /**
+             * Parses bounded canonical integer text into the declared runtime form.
+             *
+             * @param value Canonical integer text.
+             * @returns Number, bigint, or string required by the field.
+             */
             fromString(value) {
                 const restored = FieldStringifiers.integerText(value, min, max);
                 switch (representation) {
@@ -635,12 +814,26 @@ const FieldStringifiers = Object.freeze({
                         return restored.toString();
                 }
             },
+            /**
+             * Checks a runtime integer and formats it as canonical decimal text.
+             *
+             * @param value Integer in the field's runtime representation.
+             * @returns Canonical decimal text.
+             */
             toString(value) {
                 const restored = FieldStringifiers.integerValue(value, min, max, representation);
                 return restored.toString();
             },
         });
     },
+    /**
+     * Parses canonical decimal integer text within the field's bounds.
+     *
+     * @param value Canonical integer text.
+     * @param min Smallest allowed integer.
+     * @param max Largest allowed integer.
+     * @returns Parsed bounded integer.
+     */
     integerText(value, min, max) {
         if (!/^(?:0|-?[1-9]\d*)$/u.test(value)) {
             throw new Error("Field value must be a canonical integer.");
@@ -652,6 +845,15 @@ const FieldStringifiers = Object.freeze({
         }
         return restored;
     },
+    /**
+     * Converts a runtime integer to bigint after representation and range checks.
+     *
+     * @param value Integer value to validate.
+     * @param min Smallest allowed integer.
+     * @param max Largest allowed integer.
+     * @param representation Required runtime representation.
+     * @returns Bounded bigint value.
+     */
     integerValue(value, min, max, representation) {
         let converted;
         if (representation === "string") {
@@ -684,6 +886,7 @@ export const Stringifiers = {
     // prettier-ignore
     /**
      * Creates the default compact Proto JSON stringifier for a message schema.
+     * @typeParam Schema Generated schema used for Proto JSON conversion.
      * @param schema The generated message schema.
      * @param types The optional generated-type registry used to expand `Any` values.
      * @returns A reversible schema-bound stringifier.
@@ -738,6 +941,7 @@ export class StringifierRegistry {
     }
     /**
      * Registers or replaces the stringifier for one generated message type.
+     * @typeParam Schema Generated schema of the custom stringifier's message.
      * @param schema The generated message schema.
      * @param stringifier The reversible stringifier.
      */
@@ -756,6 +960,7 @@ export class StringifierRegistry {
     }
     /**
      * Returns the custom stringifier or the default compact Proto JSON mapping.
+     * @typeParam Schema Generated schema of the requested stringifier.
      * @param schema The generated message schema.
      * @returns The schema-bound stringifier.
      */
@@ -796,6 +1001,12 @@ export const Identifiers = {
 };
 Object.freeze(Identifiers);
 const IdentifierValues = Object.freeze({
+    /**
+     * Validates a signed 32-bit numeric identifier.
+     *
+     * @param value Candidate numeric identifier.
+     * @returns Integer within the signed 32-bit range.
+     */
     int32(value) {
         if (typeof value !== "number" ||
             !Number.isInteger(value) ||
@@ -805,6 +1016,12 @@ const IdentifierValues = Object.freeze({
         }
         return value;
     },
+    /**
+     * Validates a signed 64-bit bigint identifier.
+     *
+     * @param value Candidate bigint identifier.
+     * @returns Bigint within the signed 64-bit range.
+     */
     int64(value) {
         if (typeof value !== "bigint" || value < -(1n << 63n) || value >= 1n << 63n) {
             throw new RangeError("Identifier is outside the int64 range.");
@@ -867,6 +1084,7 @@ export const SignalEnvelopes = {
     // prettier-ignore
     /**
      * Packs a generated Spine command envelope with a fresh secure ID.
+     * @typeParam Schema Generated schema of the domain command.
      * @param input The command envelope input.
      * @returns The packed command.
      */
@@ -879,6 +1097,7 @@ export const SignalEnvelopes = {
     },
     /**
      * Packs a generated Spine event envelope with a fresh secure ID.
+     * @typeParam Schema Generated schema of the domain event.
      * @param input The event envelope input.
      * @returns The packed event.
      */
@@ -962,6 +1181,7 @@ export class TypeRegistry {
     }
     /**
      * Registers one schema and returns its immutable metadata.
+     * @typeParam Schema Generated schema to register.
      * @param schema The generated message schema.
      * @param options Optional explicit type URL.
      * @returns The registered schema metadata.
@@ -1013,6 +1233,7 @@ export class TypeRegistry {
     }
     /**
      * Finds metadata by generated schema identity.
+     * @typeParam Schema Generated schema used as the lookup key.
      * @param schema The generated message schema.
      * @returns Matching metadata, if registered.
      */
@@ -1045,6 +1266,7 @@ export class TypeRegistry {
     }
     /**
      * Gets metadata by generated schema identity or throws a descriptive error.
+     * @typeParam Schema Generated schema used as the lookup key.
      * @param schema The generated message schema.
      * @returns The registered metadata.
      */
@@ -1067,6 +1289,12 @@ const RegistryLookups = {
     // prettier-ignore
     /**
      * Composes modules in deterministic dependency-first order.
+     *
+     * @param root Module whose dependency graph is traversed.
+     * @param definitions Seen module definitions keyed by name.
+     * @param visiting Names on the current dependency path for cycle detection.
+     * @param verified Module objects already checked and appended.
+     * @param schemas Output list of schemas in dependency-first order.
      */
     compose(root, definitions, visiting, verified, schemas) {
         const frames = [{ module: root, appendSchemas: false }];
@@ -1109,6 +1337,10 @@ const RegistryLookups = {
     },
     /**
      * Compares two module definitions for same-name conflicts.
+     *
+     * @param left Previously seen module definition.
+     * @param right Candidate definition with the same name.
+     * @returns True when names, schemas, and dependency names agree.
      */
     sameModule(left, right) {
         if (left === right) {
@@ -1124,6 +1356,11 @@ const RegistryLookups = {
     },
     /**
      * Creates immutable descriptor-backed schema metadata.
+     *
+     * @typeParam Schema Generated schema represented by the metadata.
+     * @param schema Generated message schema being registered.
+     * @param typeUrl Canonical URL assigned to the schema.
+     * @returns Frozen descriptor-backed metadata.
      */
     metadata(schema, typeUrl) {
         const firstField = schema.fields[0];
@@ -1137,9 +1374,23 @@ const RegistryLookups = {
             typeUrlPrefix: typeUrl.slice(0, typeUrl.length - schema.typeName.length - 1),
             firstField,
             firstFieldName: firstField?.name,
+            /**
+             * Checks whether the schema file declares a given option.
+             *
+             * @typeParam Value Value type declared by the extension.
+             * @param option File-option extension to test.
+             * @returns True when the option is present.
+             */
             hasFileOption(option) {
                 return hasOption(schema.file, option);
             },
+            /**
+             * Reads a declared option from the schema file.
+             *
+             * @typeParam Value Value type declared by the extension.
+             * @param option File-option extension to read.
+             * @returns Decoded option value.
+             */
             getFileOption(option) {
                 return getOption(schema.file, option);
             },
@@ -1147,15 +1398,36 @@ const RegistryLookups = {
     },
     /**
      * Creates an immutable registry lookup view.
+     *
+     * @param registry Mutable registry exposed through read-only operations.
+     * @returns Frozen lookup facade.
      */
     lookup(registry) {
         return Object.freeze({
             findByFullName: (fullTypeName) => registry.findByFullName(fullTypeName),
             findByTypeUrl: (typeUrl) => registry.findByTypeUrl(typeUrl),
-            findBySchema: (schema) => registry.findBySchema(schema),
+            /**
+             * Finds registered metadata by generated schema identity.
+             *
+             * @typeParam Schema Generated schema used as the lookup key.
+             * @param schema Generated schema to find.
+             * @returns Matching metadata, if registered.
+             */
+            findBySchema(schema) {
+                return registry.findBySchema(schema);
+            },
             getByFullName: (fullTypeName) => registry.getByFullName(fullTypeName),
             getByTypeUrl: (typeUrl) => registry.getByTypeUrl(typeUrl),
-            getBySchema: (schema) => registry.getBySchema(schema),
+            /**
+             * Gets registered metadata by generated schema identity.
+             *
+             * @typeParam Schema Generated schema used as the lookup key.
+             * @param schema Generated schema to require.
+             * @returns Registered metadata.
+             */
+            getBySchema(schema) {
+                return registry.getBySchema(schema);
+            },
             list: () => registry.list(),
         });
     },
@@ -1168,21 +1440,46 @@ export const spineCoreRegistry = RegistryLookups.lookup(TypeRegistry.spineCore()
  * Constructs and sanitizes internal message-validation results.
  */
 const ValidationResults = {
+    /**
+     * Builds a structured validation result from sanitized violations.
+     *
+     * @param violations Sanitized constraint violations.
+     * @returns Valid result when empty, otherwise an error with violations.
+     */
     from(violations) {
         if (violations.length === 0)
             return { valid: true, violations: EMPTY_VIOLATIONS, error: undefined };
         const nonEmpty = violations;
         return { valid: false, violations: nonEmpty, error: ValidationResults.error(nonEmpty) };
     },
+    /**
+     * Packs constraint violations into a generated validation error.
+     *
+     * @param violations Violations to include in the error.
+     * @returns Generated validation error message.
+     */
     error(violations) {
         return create(ValidationErrorSchema, { constraintViolation: [...violations] });
     },
+    /**
+     * Creates a runtime-failure violation without exposing the caught error.
+     *
+     * @param typeName Protobuf type being validated.
+     * @param message Stable public failure text.
+     * @returns Generated constraint violation.
+     */
     failure(typeName, message) {
         return create(ConstraintViolationSchema, {
             typeName,
             message: create(TemplateStringSchema, { withPlaceholders: message }),
         });
     },
+    /**
+     * Copies a violation while redacting placeholder values.
+     *
+     * @param violation Violation supplied by a validation rule.
+     * @returns Sanitized generated constraint violation.
+     */
     violation(violation) {
         return create(ConstraintViolationSchema, {
             message: violation.message === undefined
@@ -1197,6 +1494,12 @@ const ValidationResults = {
                 : create(FieldPathSchema, { fieldName: [...violation.fieldPath.fieldName] }),
         });
     },
+    /**
+     * Replaces every template placeholder value with stable redaction text.
+     *
+     * @param values Placeholder values to suppress.
+     * @returns Placeholder keys mapped to redaction text.
+     */
     redact(values) {
         return Object.fromEntries(Object.keys(values ?? {}).map((key) => [key, REDACTED_VALIDATION_DETAIL]));
     },