@axi-engine/utils 0.2.2 → 0.2.4

package/dist/index.d.mts

@@ -127,11 +127,11 @@ declare function getRandomElement<T>(array: T[]): T | undefined;
 
 /**
  * Throws an error if the condition is true.
- * @param conditionForThrow - If true, an error will be thrown.
+ * @param condition  - If true, an error will be thrown.
  * @param exceptionMessage - The message for the error.
  * @throws {Error} if the value is true
  */
-declare function throwIf(conditionForThrow: boolean, exceptionMessage: string): void | never;
+declare function throwIf(condition: boolean, exceptionMessage: string): asserts condition is false;
 /**
  * Throws an error if the value is null, undefined, or an empty array.
  *
@@ -210,14 +210,54 @@ declare class ConstructorRegistry<T> {
  */
 interface DataSource {
     get(path: PathType): unknown;
+    /**
+     * Checks if a path valid.
+     * @param {PathType} path The path to the node.
+     * @returns {boolean} `true` if the node exists, otherwise `false`.
+     */
     has(path: PathType): boolean;
 }
 /**
- * A write-only contract for any system that can accept data by path.
+ * A write-only contract for any system that can accept or mutate data by path.
+ *
+ * This interface is the counterpart to `DataSource` and represents the "write" side
+ * of a complete data storage system. It provides a standard set of methods for
+ * creating, updating, and deleting data, abstracting away the underlying
+ * implementation details.
+ *
+ * @interface
  */
 interface DataSink {
+    /**
+     * Strictly updates the value at an *existing* path.
+     * This operation should typically fail or throw an error if no value exists at the path.
+     *
+     * @param path The path to the value to be updated.
+     * @param value The new value to set.
+     */
     set(path: PathType, value: unknown): void;
+    /**
+     * Strictly creates a new value at the specified path.
+     * This operation should typically fail or throw an error if a value already exists
+     * at the path.
+     *
+     * @param path The full path where the new value will be created.
+     * @param value The initial value to create.
+     */
     create(path: PathType, value: unknown): void;
+    /**
+     * Updates a value at a specified path if it exists, or creates it if it does not.
+     * This is a convenient and non-strict combination of the `set` and `create` operations.
+     *
+     * @param path The path to the value to be created or updated.
+     * @param value The value to set.
+     */
+    upset(path: PathType, value: unknown): void;
+    /**
+     * Deletes the value at the specified path.
+     *
+     * @param path The path to the value to be deleted.
+     */
     delete(path: PathType): void;
 }
 /**

package/dist/index.d.ts

@@ -127,11 +127,11 @@ declare function getRandomElement<T>(array: T[]): T | undefined;
 
 /**
  * Throws an error if the condition is true.
- * @param conditionForThrow - If true, an error will be thrown.
+ * @param condition  - If true, an error will be thrown.
  * @param exceptionMessage - The message for the error.
  * @throws {Error} if the value is true
  */
-declare function throwIf(conditionForThrow: boolean, exceptionMessage: string): void | never;
+declare function throwIf(condition: boolean, exceptionMessage: string): asserts condition is false;
 /**
  * Throws an error if the value is null, undefined, or an empty array.
  *
@@ -210,14 +210,54 @@ declare class ConstructorRegistry<T> {
  */
 interface DataSource {
     get(path: PathType): unknown;
+    /**
+     * Checks if a path valid.
+     * @param {PathType} path The path to the node.
+     * @returns {boolean} `true` if the node exists, otherwise `false`.
+     */
     has(path: PathType): boolean;
 }
 /**
- * A write-only contract for any system that can accept data by path.
+ * A write-only contract for any system that can accept or mutate data by path.
+ *
+ * This interface is the counterpart to `DataSource` and represents the "write" side
+ * of a complete data storage system. It provides a standard set of methods for
+ * creating, updating, and deleting data, abstracting away the underlying
+ * implementation details.
+ *
+ * @interface
  */
 interface DataSink {
+    /**
+     * Strictly updates the value at an *existing* path.
+     * This operation should typically fail or throw an error if no value exists at the path.
+     *
+     * @param path The path to the value to be updated.
+     * @param value The new value to set.
+     */
     set(path: PathType, value: unknown): void;
+    /**
+     * Strictly creates a new value at the specified path.
+     * This operation should typically fail or throw an error if a value already exists
+     * at the path.
+     *
+     * @param path The full path where the new value will be created.
+     * @param value The initial value to create.
+     */
     create(path: PathType, value: unknown): void;
+    /**
+     * Updates a value at a specified path if it exists, or creates it if it does not.
+     * This is a convenient and non-strict combination of the `set` and `create` operations.
+     *
+     * @param path The path to the value to be created or updated.
+     * @param value The value to set.
+     */
+    upset(path: PathType, value: unknown): void;
+    /**
+     * Deletes the value at the specified path.
+     *
+     * @param path The path to the value to be deleted.
+     */
     delete(path: PathType): void;
 }
 /**

package/dist/index.js

@@ -126,8 +126,8 @@ function isPercentageString(val) {
 }
 
 // src/assertion.ts
-function throwIf(conditionForThrow, exceptionMessage) {
-  if (conditionForThrow) {
+function throwIf(condition, exceptionMessage) {
+  if (condition) {
     throw new Error(exceptionMessage);
   }
 }

package/dist/index.mjs

@@ -72,8 +72,8 @@ function isPercentageString(val) {
 }
 
 // src/assertion.ts
-function throwIf(conditionForThrow, exceptionMessage) {
-  if (conditionForThrow) {
+function throwIf(condition, exceptionMessage) {
+  if (condition) {
     throw new Error(exceptionMessage);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axi-engine/utils",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Core utility library for Axi Engine, providing common functions for arrays, math, type guards, and more.",
   "license": "MIT",
   "repository": {