@hotmeshio/hotmesh 0.14.1 → 0.14.3

package/build/services/pipe/functions/bitwise.js

@@ -1,22 +1,116 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BitwiseHandler = void 0;
+/**
+ * Provides bitwise operation functions for use in HotMesh mapping rules.
+ * Although inspired by JavaScript, they have been adapted to follow a
+ * functional approach. Each transformation is a function that expects
+ * one or more input parameters from the prior row in the `@pipe` structure.
+ *
+ * @remarks
+ * Invoked in mapping rules using `{@bitwise.<method>}` syntax.
+ */
 class BitwiseHandler {
+    /**
+     * Performs a bitwise AND operation on two numbers.
+     *
+     * @param {number} a - The first operand
+     * @param {number} b - The second operand
+     * @returns {number} The result of `a & b`
+     * @example
+     * ```yaml
+     * bitwise_and_result:
+     *   "@pipe":
+     *     - ["{a.numbers.a}", "{a.numbers.b}"]
+     *     - ["{@bitwise.and}"]
+     * ```
+     */
     and(a, b) {
         return a & b;
     }
+    /**
+     * Performs a bitwise OR operation on two numbers.
+     *
+     * @param {number} a - The first operand
+     * @param {number} b - The second operand
+     * @returns {number} The result of `a | b`
+     * @example
+     * ```yaml
+     * bitwise_or_result:
+     *   "@pipe":
+     *     - ["{a.numbers.a}", "{a.numbers.b}"]
+     *     - ["{@bitwise.or}"]
+     * ```
+     */
     or(a, b) {
         return a | b;
     }
+    /**
+     * Performs a bitwise XOR operation on two numbers.
+     *
+     * @param {number} a - The first operand
+     * @param {number} b - The second operand
+     * @returns {number} The result of `a ^ b`
+     * @example
+     * ```yaml
+     * bitwise_xor_result:
+     *   "@pipe":
+     *     - ["{a.numbers.a}", "{a.numbers.b}"]
+     *     - ["{@bitwise.xor}"]
+     * ```
+     */
     xor(a, b) {
         return a ^ b;
     }
+    /**
+     * Performs a bitwise left shift operation on a number.
+     *
+     * @param {number} a - The number to shift
+     * @param {number} b - The number of positions to shift left
+     * @returns {number} The result of `a << b`
+     * @example
+     * ```yaml
+     * bitwise_left_shift_result:
+     *   "@pipe":
+     *     - ["{a.numbers.a}", "{a.numbers.shift}"]
+     *     - ["{@bitwise.leftShift}"]
+     * ```
+     */
     leftShift(a, b) {
         return a << b;
     }
+    /**
+     * Performs a bitwise right shift operation on a number,
+     * preserving the sign bit.
+     *
+     * @param {number} a - The number to shift
+     * @param {number} b - The number of positions to shift right
+     * @returns {number} The result of `a >> b`
+     * @example
+     * ```yaml
+     * bitwise_right_shift_result:
+     *   "@pipe":
+     *     - ["{a.numbers.a}", "{a.numbers.shift}"]
+     *     - ["{@bitwise.rightShift}"]
+     * ```
+     */
     rightShift(a, b) {
         return a >> b;
     }
+    /**
+     * Performs a bitwise unsigned right shift operation on a number.
+     *
+     * @param {number} a - The number to shift
+     * @param {number} b - The number of positions to shift right
+     * @returns {number} The result of `a >>> b`
+     * @example
+     * ```yaml
+     * bitwise_unsigned_right_shift_result:
+     *   "@pipe":
+     *     - ["{a.numbers.a}", "{a.numbers.shift}"]
+     *     - ["{@bitwise.unsignedRightShift}"]
+     * ```
+     */
     unsignedRightShift(a, b) {
         return a >>> b;
     }

package/build/services/pipe/functions/conditional.d.ts

@@ -1,13 +1,174 @@
+/**
+ * Provides conditional logic functions for use within HotMesh mapping
+ * rules. Although inspired by JavaScript operators, these methods have
+ * been adapted to follow a functional approach. Each transformation is
+ * a function that expects one or more input parameters from the prior
+ * row in the `@pipe` structure.
+ *
+ * @remarks Invoked via `{@conditional.<method>}` in YAML mapping rules.
+ */
 declare class ConditionalHandler {
+    /**
+     * Evaluates a condition and returns one of two provided values based
+     * on the result. Equivalent to the JavaScript ternary operator
+     * (`condition ? valueIfTrue : valueIfFalse`).
+     *
+     * @param {boolean} condition - The condition to evaluate
+     * @param {any} valueIfTrue - The value to return if the condition is true
+     * @param {any} valueIfFalse - The value to return if the condition is false
+     * @returns {any} The value corresponding to the condition result
+     * @example
+     * ```yaml
+     * status_label:
+     *   "@pipe":
+     *     - ["{a.data.isActive}", "{a.data.activeLabel}", "{a.data.inactiveLabel}"]
+     *     - ["{@conditional.ternary}"]
+     * ```
+     */
     ternary(condition: boolean, valueIfTrue: any, valueIfFalse: any): any;
+    /**
+     * Checks whether two values are equal using non-strict equality (`==`).
+     * Type coercion is applied, so `42 == "42"` returns true.
+     *
+     * @param {any} value1 - The first value to compare
+     * @param {any} value2 - The second value to compare
+     * @returns {boolean} True if the values are loosely equal, otherwise false
+     * @example
+     * ```yaml
+     * are_values_equal:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.equality}"]
+     * ```
+     */
     equality(value1: any, value2: any): boolean;
+    /**
+     * Checks whether two values are equal using strict equality (`===`).
+     * No type coercion is applied, so `42 === "42"` returns false.
+     *
+     * @param {any} value1 - The first value to compare
+     * @param {any} value2 - The second value to compare
+     * @returns {boolean} True if the values are strictly equal, otherwise false
+     * @example
+     * ```yaml
+     * are_values_strictly_equal:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.strict_equality}"]
+     * ```
+     */
     strict_equality(value1: any, value2: any): boolean;
+    /**
+     * Checks whether two values are not equal using non-strict inequality
+     * (`!=`). Type coercion is applied, so `42 != "42"` returns false.
+     *
+     * @param {any} value1 - The first value to compare
+     * @param {any} value2 - The second value to compare
+     * @returns {boolean} True if the values are not loosely equal, otherwise false
+     * @example
+     * ```yaml
+     * are_values_not_equal:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.inequality}"]
+     * ```
+     */
     inequality(value1: any, value2: any): boolean;
+    /**
+     * Checks whether two values are not equal using strict inequality
+     * (`!==`). No type coercion is applied, so `42 !== "42"` returns true.
+     *
+     * @param {any} value1 - The first value to compare
+     * @param {any} value2 - The second value to compare
+     * @returns {boolean} True if the values are strictly not equal, otherwise false
+     * @example
+     * ```yaml
+     * are_values_strictly_not_equal:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.strict_inequality}"]
+     * ```
+     */
     strict_inequality(value1: any, value2: any): boolean;
+    /**
+     * Checks whether the first value is greater than the second value.
+     *
+     * @param {number} value1 - The first number to compare
+     * @param {number} value2 - The second number to compare
+     * @returns {boolean} True if value1 is greater than value2, otherwise false
+     * @example
+     * ```yaml
+     * is_greater:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.greater_than}"]
+     * ```
+     */
     greater_than(value1: number, value2: number): boolean;
+    /**
+     * Checks whether the first value is less than the second value.
+     *
+     * @param {number} value1 - The first number to compare
+     * @param {number} value2 - The second number to compare
+     * @returns {boolean} True if value1 is less than value2, otherwise false
+     * @example
+     * ```yaml
+     * is_less:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.less_than}"]
+     * ```
+     */
     less_than(value1: number, value2: number): boolean;
+    /**
+     * Checks whether the first value is greater than or equal to the
+     * second value.
+     *
+     * @param {number} value1 - The first number to compare
+     * @param {number} value2 - The second number to compare
+     * @returns {boolean} True if value1 is greater than or equal to value2, otherwise false
+     * @example
+     * ```yaml
+     * is_gte:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.greater_than_or_equal}"]
+     * ```
+     */
     greater_than_or_equal(value1: number, value2: number): boolean;
+    /**
+     * Checks whether the first value is less than or equal to the second
+     * value.
+     *
+     * @param {number} value1 - The first number to compare
+     * @param {number} value2 - The second number to compare
+     * @returns {boolean} True if value1 is less than or equal to value2, otherwise false
+     * @example
+     * ```yaml
+     * is_lte:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.less_than_or_equal}"]
+     * ```
+     */
     less_than_or_equal(value1: number, value2: number): boolean;
+    /**
+     * Returns the first value if it is not null or undefined, otherwise
+     * returns the second value. Equivalent to the JavaScript nullish
+     * coalescing operator (`??`). Unlike logical OR, this allows falsy
+     * values like `0` and `false` to pass through.
+     *
+     * @param {any} value1 - The value to test for null/undefined
+     * @param {any} value2 - The fallback value if value1 is null or undefined
+     * @returns {any} value1 if it is not null/undefined, otherwise value2
+     * @example
+     * ```yaml
+     * non_null_value:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.nullish}"]
+     * ```
+     */
     nullish(value1: any, value2: any): any;
 }
 export { ConditionalHandler };

package/build/services/pipe/functions/conditional.js

@@ -1,34 +1,195 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConditionalHandler = void 0;
+/**
+ * Provides conditional logic functions for use within HotMesh mapping
+ * rules. Although inspired by JavaScript operators, these methods have
+ * been adapted to follow a functional approach. Each transformation is
+ * a function that expects one or more input parameters from the prior
+ * row in the `@pipe` structure.
+ *
+ * @remarks Invoked via `{@conditional.<method>}` in YAML mapping rules.
+ */
 class ConditionalHandler {
+    /**
+     * Evaluates a condition and returns one of two provided values based
+     * on the result. Equivalent to the JavaScript ternary operator
+     * (`condition ? valueIfTrue : valueIfFalse`).
+     *
+     * @param {boolean} condition - The condition to evaluate
+     * @param {any} valueIfTrue - The value to return if the condition is true
+     * @param {any} valueIfFalse - The value to return if the condition is false
+     * @returns {any} The value corresponding to the condition result
+     * @example
+     * ```yaml
+     * status_label:
+     *   "@pipe":
+     *     - ["{a.data.isActive}", "{a.data.activeLabel}", "{a.data.inactiveLabel}"]
+     *     - ["{@conditional.ternary}"]
+     * ```
+     */
     ternary(condition, valueIfTrue, valueIfFalse) {
         return condition ? valueIfTrue : valueIfFalse;
     }
+    /**
+     * Checks whether two values are equal using non-strict equality (`==`).
+     * Type coercion is applied, so `42 == "42"` returns true.
+     *
+     * @param {any} value1 - The first value to compare
+     * @param {any} value2 - The second value to compare
+     * @returns {boolean} True if the values are loosely equal, otherwise false
+     * @example
+     * ```yaml
+     * are_values_equal:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.equality}"]
+     * ```
+     */
     equality(value1, value2) {
         return value1 == value2;
     }
+    /**
+     * Checks whether two values are equal using strict equality (`===`).
+     * No type coercion is applied, so `42 === "42"` returns false.
+     *
+     * @param {any} value1 - The first value to compare
+     * @param {any} value2 - The second value to compare
+     * @returns {boolean} True if the values are strictly equal, otherwise false
+     * @example
+     * ```yaml
+     * are_values_strictly_equal:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.strict_equality}"]
+     * ```
+     */
     strict_equality(value1, value2) {
         return value1 === value2;
     }
+    /**
+     * Checks whether two values are not equal using non-strict inequality
+     * (`!=`). Type coercion is applied, so `42 != "42"` returns false.
+     *
+     * @param {any} value1 - The first value to compare
+     * @param {any} value2 - The second value to compare
+     * @returns {boolean} True if the values are not loosely equal, otherwise false
+     * @example
+     * ```yaml
+     * are_values_not_equal:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.inequality}"]
+     * ```
+     */
     inequality(value1, value2) {
         return value1 != value2;
     }
+    /**
+     * Checks whether two values are not equal using strict inequality
+     * (`!==`). No type coercion is applied, so `42 !== "42"` returns true.
+     *
+     * @param {any} value1 - The first value to compare
+     * @param {any} value2 - The second value to compare
+     * @returns {boolean} True if the values are strictly not equal, otherwise false
+     * @example
+     * ```yaml
+     * are_values_strictly_not_equal:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.strict_inequality}"]
+     * ```
+     */
     strict_inequality(value1, value2) {
         return value1 !== value2;
     }
+    /**
+     * Checks whether the first value is greater than the second value.
+     *
+     * @param {number} value1 - The first number to compare
+     * @param {number} value2 - The second number to compare
+     * @returns {boolean} True if value1 is greater than value2, otherwise false
+     * @example
+     * ```yaml
+     * is_greater:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.greater_than}"]
+     * ```
+     */
     greater_than(value1, value2) {
         return value1 > value2;
     }
+    /**
+     * Checks whether the first value is less than the second value.
+     *
+     * @param {number} value1 - The first number to compare
+     * @param {number} value2 - The second number to compare
+     * @returns {boolean} True if value1 is less than value2, otherwise false
+     * @example
+     * ```yaml
+     * is_less:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.less_than}"]
+     * ```
+     */
     less_than(value1, value2) {
         return value1 < value2;
     }
+    /**
+     * Checks whether the first value is greater than or equal to the
+     * second value.
+     *
+     * @param {number} value1 - The first number to compare
+     * @param {number} value2 - The second number to compare
+     * @returns {boolean} True if value1 is greater than or equal to value2, otherwise false
+     * @example
+     * ```yaml
+     * is_gte:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.greater_than_or_equal}"]
+     * ```
+     */
     greater_than_or_equal(value1, value2) {
         return value1 >= value2;
     }
+    /**
+     * Checks whether the first value is less than or equal to the second
+     * value.
+     *
+     * @param {number} value1 - The first number to compare
+     * @param {number} value2 - The second number to compare
+     * @returns {boolean} True if value1 is less than or equal to value2, otherwise false
+     * @example
+     * ```yaml
+     * is_lte:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.less_than_or_equal}"]
+     * ```
+     */
     less_than_or_equal(value1, value2) {
         return value1 <= value2;
     }
+    /**
+     * Returns the first value if it is not null or undefined, otherwise
+     * returns the second value. Equivalent to the JavaScript nullish
+     * coalescing operator (`??`). Unlike logical OR, this allows falsy
+     * values like `0` and `false` to pass through.
+     *
+     * @param {any} value1 - The value to test for null/undefined
+     * @param {any} value2 - The fallback value if value1 is null or undefined
+     * @returns {any} value1 if it is not null/undefined, otherwise value2
+     * @example
+     * ```yaml
+     * non_null_value:
+     *   "@pipe":
+     *     - ["{a.data.value1}", "{a.data.value2}"]
+     *     - ["{@conditional.nullish}"]
+     * ```
+     */
     nullish(value1, value2) {
         return value1 ?? value2;
     }

package/build/services/pipe/functions/cron.d.ts

@@ -1,12 +1,31 @@
 import { ILogger } from '../../../types/logger';
 /**
- * Safely calculates the delay in seconds until the next execution of a cron job.
- * Fails silently and returns -1 if the cron expression is invalid.
- * @param cronExpression The cron expression to parse (e.g. '0 0 * * *').
- * @returns The delay in seconds until the next cron job execution (minimum 5 seconds).
+ * Provides cron-related utility functions based on the
+ * [cron](https://en.wikipedia.org/wiki/Cron) format for use
+ * in HotMesh mapping rules.
+ *
+ * @remarks
+ * Invoked in mapping rules using `{@cron.<method>}` syntax.
  */
 declare class CronHandler {
     static logger: ILogger;
+    /**
+     * Safely calculates the delay in seconds until the next execution
+     * of a cron job. Calculates the next date and time (per the system
+     * clock) that satisfies the cron expression, then returns the value
+     * in seconds from now. Fails silently and returns `-1` if the cron
+     * expression is invalid or the next execution time is in the past.
+     *
+     * @param {string} cronExpression - The cron expression to parse (e.g. `'0 0 * * *'`)
+     * @returns {number} The delay in seconds until the next cron job execution (minimum `HMSH_FIDELITY_SECONDS`), or `-1` on error
+     * @example
+     * ```yaml
+     * cron_next_result:
+     *   "@pipe":
+     *     - ["{a.expressions.cron}"]
+     *     - ["{@cron.nextDelay}"]
+     * ```
+     */
     nextDelay(cronExpression: string): number;
 }
 export { CronHandler };

package/build/services/pipe/functions/cron.js

@@ -6,12 +6,31 @@ const enums_1 = require("../../../modules/enums");
 const utils_1 = require("../../../modules/utils");
 const logger_1 = require("../../logger");
 /**
- * Safely calculates the delay in seconds until the next execution of a cron job.
- * Fails silently and returns -1 if the cron expression is invalid.
- * @param cronExpression The cron expression to parse (e.g. '0 0 * * *').
- * @returns The delay in seconds until the next cron job execution (minimum 5 seconds).
+ * Provides cron-related utility functions based on the
+ * [cron](https://en.wikipedia.org/wiki/Cron) format for use
+ * in HotMesh mapping rules.
+ *
+ * @remarks
+ * Invoked in mapping rules using `{@cron.<method>}` syntax.
  */
 class CronHandler {
+    /**
+     * Safely calculates the delay in seconds until the next execution
+     * of a cron job. Calculates the next date and time (per the system
+     * clock) that satisfies the cron expression, then returns the value
+     * in seconds from now. Fails silently and returns `-1` if the cron
+     * expression is invalid or the next execution time is in the past.
+     *
+     * @param {string} cronExpression - The cron expression to parse (e.g. `'0 0 * * *'`)
+     * @returns {number} The delay in seconds until the next cron job execution (minimum `HMSH_FIDELITY_SECONDS`), or `-1` on error
+     * @example
+     * ```yaml
+     * cron_next_result:
+     *   "@pipe":
+     *     - ["{a.expressions.cron}"]
+     *     - ["{@cron.nextDelay}"]
+     * ```
+     */
     nextDelay(cronExpression) {
         try {
             if (!(0, utils_1.isValidCron)(cronExpression)) {