@axi-engine/utils 0.1.3 → 0.1.5

package/README.md

@@ -30,7 +30,7 @@ const isSame = haveSameElements(['a', 'b'], ['b', 'a']); // Returns true
 ```
 
 
-API Reference
+## API Reference
 
 Will be available when code and repository will be fully published 
 

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;
@@ -96,6 +120,37 @@ declare const axiSettings: AxiEngineConfig;
  */
 declare function configure(newConfig: Partial<AxiEngineConfig>): void;
 
+/**
+ * A minimal, type-safe event emitter for a single event.
+ * It does not manage state, it only manages subscribers and event dispatching.
+ * @template T A tuple representing the types of the event arguments.
+ */
+declare class Emitter<T extends any[]> {
+    private listeners;
+    /**
+     * Subscribes a listener to this event.
+     * @returns A function to unsubscribe the listener.
+     */
+    subscribe(listener: (...args: T) => void): () => void;
+    /**
+     * Manually unsubscribe by listener
+     * @returns returns true if an listener has been removed, or false if the listener does not exist.
+     */
+    unsubscribe(listener: (...args: T) => void): boolean;
+    /**
+     * Dispatches the event to all subscribed listeners.
+     */
+    emit(...args: T): void;
+    /**
+     * Clears all listeners.
+     */
+    clear(): void;
+    /**
+     * Returns the number of listeners.
+     */
+    get listenerCount(): number;
+}
+
 declare function isNullOrUndefined(val: unknown): val is null | undefined;
 declare function isUndefined(val: unknown): val is undefined;
 declare function isNumber(val: unknown): val is number;
@@ -155,4 +210,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, Emitter, 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;
@@ -96,6 +120,37 @@ declare const axiSettings: AxiEngineConfig;
  */
 declare function configure(newConfig: Partial<AxiEngineConfig>): void;
 
+/**
+ * A minimal, type-safe event emitter for a single event.
+ * It does not manage state, it only manages subscribers and event dispatching.
+ * @template T A tuple representing the types of the event arguments.
+ */
+declare class Emitter<T extends any[]> {
+    private listeners;
+    /**
+     * Subscribes a listener to this event.
+     * @returns A function to unsubscribe the listener.
+     */
+    subscribe(listener: (...args: T) => void): () => void;
+    /**
+     * Manually unsubscribe by listener
+     * @returns returns true if an listener has been removed, or false if the listener does not exist.
+     */
+    unsubscribe(listener: (...args: T) => void): boolean;
+    /**
+     * Dispatches the event to all subscribed listeners.
+     */
+    emit(...args: T): void;
+    /**
+     * Clears all listeners.
+     */
+    clear(): void;
+    /**
+     * Returns the number of listeners.
+     */
+    get listenerCount(): number;
+}
+
 declare function isNullOrUndefined(val: unknown): val is null | undefined;
 declare function isUndefined(val: unknown): val is undefined;
 declare function isNumber(val: unknown): val is number;
@@ -155,4 +210,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, Emitter, 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

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Emitter: () => Emitter,
   areArraysEqual: () => areArraysEqual,
   axiSettings: () => axiSettings,
   clampNumber: () => clampNumber,
@@ -43,6 +44,7 @@ __export(index_exports, {
   randInt: () => randInt,
   shuffleArray: () => shuffleArray,
   throwIf: () => throwIf,
+  throwIfEmpty: () => throwIfEmpty,
   unique: () => unique
 });
 module.exports = __toCommonJS(index_exports);
@@ -93,22 +95,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 +115,68 @@ 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/emitter.ts
+var Emitter = class {
+  constructor() {
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Subscribes a listener to this event.
+   * @returns A function to unsubscribe the listener.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * Manually unsubscribe by listener
+   * @returns returns true if an listener has been removed, or false if the listener does not exist.
+   */
+  unsubscribe(listener) {
+    return this.listeners.delete(listener);
+  }
+  /**
+   * Dispatches the event to all subscribed listeners.
+   */
+  emit(...args) {
+    this.listeners.forEach((listener) => listener(...args));
+  }
+  /**
+   * Clears all listeners.
+   */
+  clear() {
+    this.listeners.clear();
+  }
+  /**
+   * Returns the number of listeners.
+   */
+  get listenerCount() {
+    return this.listeners.size;
+  }
+};
+
 // src/math.ts
 function clampNumber(val, min, max) {
   if (!isNullOrUndefined(min)) val = Math.max(val, min);
@@ -164,6 +212,7 @@ function randId() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Emitter,
   areArraysEqual,
   axiSettings,
   clampNumber,
@@ -187,5 +236,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,68 @@ 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/emitter.ts
+var Emitter = class {
+  constructor() {
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Subscribes a listener to this event.
+   * @returns A function to unsubscribe the listener.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * Manually unsubscribe by listener
+   * @returns returns true if an listener has been removed, or false if the listener does not exist.
+   */
+  unsubscribe(listener) {
+    return this.listeners.delete(listener);
+  }
+  /**
+   * Dispatches the event to all subscribed listeners.
+   */
+  emit(...args) {
+    this.listeners.forEach((listener) => listener(...args));
+  }
+  /**
+   * Clears all listeners.
+   */
+  clear() {
+    this.listeners.clear();
+  }
+  /**
+   * Returns the number of listeners.
+   */
+  get listenerCount() {
+    return this.listeners.size;
+  }
+};
+
 // src/math.ts
 function clampNumber(val, min, max) {
   if (!isNullOrUndefined(min)) val = Math.max(val, min);
@@ -114,6 +160,7 @@ function randId() {
   return uuidv4();
 }
 export {
+  Emitter,
   areArraysEqual,
   axiSettings,
   clampNumber,
@@ -137,5 +184,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.5",
   "description": "Core utility library for Axi Engine, providing common functions for arrays, math, type guards, and more.",
   "license": "MIT",
   "keywords": [
@@ -9,14 +9,14 @@
     "gamedev",
     "utils"
   ],
+  "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     }
   },
   "scripts": {