@axi-engine/utils 0.1.3 → 0.1.4

package/dist/index.d.mts

@@ -83,8 +83,32 @@ 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 exceptionMessage - The message for the error.
+ * @throws {Error} if the value is true
  */
 declare function throwIf(conditionForThrow: boolean, exceptionMessage: string): void | never;
+/**
+ * Throws an error if the value is null, undefined, or an empty array.
+ *
+ * @template T The type of the value being checked.
+ * @param value The value to check.
+ * @param exceptionMessage The message for the error.
+ * @throws {Error} if the value is null, undefined, or an empty array.
+ *
+ * @example
+ * // Example with a potentially undefined variable
+ * const user: { name: string } | undefined = findUser();
+ * throwIfEmpty(user, 'User not found');
+ * // From here, TypeScript knows `user` is not undefined.
+ * console.log(user.name);
+ *
+ * @example
+ * // Example with an array
+ * const items: string[] = getItems();
+ * throwIfEmpty(items, 'Items array cannot be empty');
+ * // From here, you can safely access items[0] without checking for an empty array again.
+ * console.log('First item:', items[0]);
+ */
+declare function throwIfEmpty<T>(value: T, exceptionMessage: string): asserts value is NonNullable<T>;
 
 interface AxiEngineConfig {
     pathSeparator: string;
@@ -155,4 +179,4 @@ declare function randInt(min: number, max: number): number;
  */
 declare function randId(): string;
 
-export { type AxiEngineConfig, type PathType, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, unique };
+export { type AxiEngineConfig, type PathType, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };

package/dist/index.d.ts

@@ -83,8 +83,32 @@ 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 exceptionMessage - The message for the error.
+ * @throws {Error} if the value is true
  */
 declare function throwIf(conditionForThrow: boolean, exceptionMessage: string): void | never;
+/**
+ * Throws an error if the value is null, undefined, or an empty array.
+ *
+ * @template T The type of the value being checked.
+ * @param value The value to check.
+ * @param exceptionMessage The message for the error.
+ * @throws {Error} if the value is null, undefined, or an empty array.
+ *
+ * @example
+ * // Example with a potentially undefined variable
+ * const user: { name: string } | undefined = findUser();
+ * throwIfEmpty(user, 'User not found');
+ * // From here, TypeScript knows `user` is not undefined.
+ * console.log(user.name);
+ *
+ * @example
+ * // Example with an array
+ * const items: string[] = getItems();
+ * throwIfEmpty(items, 'Items array cannot be empty');
+ * // From here, you can safely access items[0] without checking for an empty array again.
+ * console.log('First item:', items[0]);
+ */
+declare function throwIfEmpty<T>(value: T, exceptionMessage: string): asserts value is NonNullable<T>;
 
 interface AxiEngineConfig {
     pathSeparator: string;
@@ -155,4 +179,4 @@ declare function randInt(min: number, max: number): number;
  */
 declare function randId(): string;
 
-export { type AxiEngineConfig, type PathType, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, unique };
+export { type AxiEngineConfig, type PathType, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };

package/dist/index.js

@@ -43,6 +43,7 @@ __export(index_exports, {
   randInt: () => randInt,
   shuffleArray: () => shuffleArray,
   throwIf: () => throwIf,
+  throwIfEmpty: () => throwIfEmpty,
   unique: () => unique
 });
 module.exports = __toCommonJS(index_exports);
@@ -93,22 +94,6 @@ function getRandomElement(array) {
   return array[index];
 }
 
-// src/assertion.ts
-function throwIf(conditionForThrow, exceptionMessage) {
-  if (conditionForThrow) {
-    throw new Error(exceptionMessage);
-  }
-}
-
-// src/config.ts
-var defaultConfig = {
-  pathSeparator: "/"
-};
-var axiSettings = { ...defaultConfig };
-function configure(newConfig) {
-  Object.assign(axiSettings, newConfig);
-}
-
 // src/guards.ts
 function isNullOrUndefined(val) {
   return val === void 0 || val === null;
@@ -129,6 +114,28 @@ function isPercentageString(val) {
   return typeof val === "string" && val.endsWith("%");
 }
 
+// src/assertion.ts
+function throwIf(conditionForThrow, exceptionMessage) {
+  if (conditionForThrow) {
+    throw new Error(exceptionMessage);
+  }
+}
+function throwIfEmpty(value, exceptionMessage) {
+  const isArrayAndEmpty = Array.isArray(value) && value.length === 0;
+  if (isNullOrUndefined(value) || isArrayAndEmpty) {
+    throw new Error(exceptionMessage);
+  }
+}
+
+// src/config.ts
+var defaultConfig = {
+  pathSeparator: "/"
+};
+var axiSettings = { ...defaultConfig };
+function configure(newConfig) {
+  Object.assign(axiSettings, newConfig);
+}
+
 // src/math.ts
 function clampNumber(val, min, max) {
   if (!isNullOrUndefined(min)) val = Math.max(val, min);
@@ -187,5 +194,6 @@ function randId() {
   randInt,
   shuffleArray,
   throwIf,
+  throwIfEmpty,
   unique
 });

package/dist/index.mjs

@@ -44,22 +44,6 @@ function getRandomElement(array) {
   return array[index];
 }
 
-// src/assertion.ts
-function throwIf(conditionForThrow, exceptionMessage) {
-  if (conditionForThrow) {
-    throw new Error(exceptionMessage);
-  }
-}
-
-// src/config.ts
-var defaultConfig = {
-  pathSeparator: "/"
-};
-var axiSettings = { ...defaultConfig };
-function configure(newConfig) {
-  Object.assign(axiSettings, newConfig);
-}
-
 // src/guards.ts
 function isNullOrUndefined(val) {
   return val === void 0 || val === null;
@@ -80,6 +64,28 @@ function isPercentageString(val) {
   return typeof val === "string" && val.endsWith("%");
 }
 
+// src/assertion.ts
+function throwIf(conditionForThrow, exceptionMessage) {
+  if (conditionForThrow) {
+    throw new Error(exceptionMessage);
+  }
+}
+function throwIfEmpty(value, exceptionMessage) {
+  const isArrayAndEmpty = Array.isArray(value) && value.length === 0;
+  if (isNullOrUndefined(value) || isArrayAndEmpty) {
+    throw new Error(exceptionMessage);
+  }
+}
+
+// src/config.ts
+var defaultConfig = {
+  pathSeparator: "/"
+};
+var axiSettings = { ...defaultConfig };
+function configure(newConfig) {
+  Object.assign(axiSettings, newConfig);
+}
+
 // src/math.ts
 function clampNumber(val, min, max) {
   if (!isNullOrUndefined(min)) val = Math.max(val, min);
@@ -137,5 +143,6 @@ export {
   randInt,
   shuffleArray,
   throwIf,
+  throwIfEmpty,
   unique
 };

package/package.json

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