@axi-engine/utils 0.2.3 → 0.2.5

package/dist/index.d.mts

@@ -155,6 +155,11 @@ declare function throwIf(condition: boolean, exceptionMessage: string): asserts
  * console.log('First item:', items[0]);
  */
 declare function throwIfEmpty<T>(value: T, exceptionMessage: string): asserts value is NonNullable<T>;
+/**
+ * Throws an error unconditionally.
+ * @param message The message for the error.
+ */
+declare function throwError(message: string): never;
 
 interface AxiEngineConfig {
     pathSeparator: string;
@@ -210,14 +215,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;
 }
 /**
@@ -324,4 +369,4 @@ declare function randInt(min: number, max: number): number;
  */
 declare function randId(): string;
 
-export { type AxiEngineConfig, type Constructor, ConstructorRegistry, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, type ScalarType, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNull, isNullOrUndefined, isNumber, isPercentageString, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };
+export { type AxiEngineConfig, type Constructor, ConstructorRegistry, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, type ScalarType, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNull, isNullOrUndefined, isNumber, isPercentageString, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, unique };

package/dist/index.d.ts

@@ -155,6 +155,11 @@ declare function throwIf(condition: boolean, exceptionMessage: string): asserts
  * console.log('First item:', items[0]);
  */
 declare function throwIfEmpty<T>(value: T, exceptionMessage: string): asserts value is NonNullable<T>;
+/**
+ * Throws an error unconditionally.
+ * @param message The message for the error.
+ */
+declare function throwError(message: string): never;
 
 interface AxiEngineConfig {
     pathSeparator: string;
@@ -210,14 +215,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;
 }
 /**
@@ -324,4 +369,4 @@ declare function randInt(min: number, max: number): number;
  */
 declare function randId(): string;
 
-export { type AxiEngineConfig, type Constructor, ConstructorRegistry, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, type ScalarType, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNull, isNullOrUndefined, isNumber, isPercentageString, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };
+export { type AxiEngineConfig, type Constructor, ConstructorRegistry, type DataSink, type DataSource, type DataStorage, Emitter, type PathType, type ScalarType, type Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNull, isNullOrUndefined, isNumber, isPercentageString, isScalar, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwError, throwIf, throwIfEmpty, unique };

package/dist/index.js

@@ -46,6 +46,7 @@ __export(index_exports, {
   randId: () => randId,
   randInt: () => randInt,
   shuffleArray: () => shuffleArray,
+  throwError: () => throwError,
   throwIf: () => throwIf,
   throwIfEmpty: () => throwIfEmpty,
   unique: () => unique
@@ -137,6 +138,9 @@ function throwIfEmpty(value, exceptionMessage) {
     throw new Error(exceptionMessage);
   }
 }
+function throwError(message) {
+  throw new Error(message);
+}
 
 // src/config.ts
 var defaultConfig = {
@@ -290,6 +294,7 @@ function randId() {
   randId,
   randInt,
   shuffleArray,
+  throwError,
   throwIf,
   throwIfEmpty,
   unique

package/dist/index.mjs

@@ -83,6 +83,9 @@ function throwIfEmpty(value, exceptionMessage) {
     throw new Error(exceptionMessage);
   }
 }
+function throwError(message) {
+  throw new Error(message);
+}
 
 // src/config.ts
 var defaultConfig = {
@@ -235,6 +238,7 @@ export {
   randId,
   randInt,
   shuffleArray,
+  throwError,
   throwIf,
   throwIfEmpty,
   unique

package/package.json

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