tiny-essentials 1.28.0 → 1.28.2

package/dist/v1/libs/TinyAdvancedRaffle.d.mts

@@ -1,15 +1,6 @@
-export default TinyAdvancedRaffle;
-/**
- * Defines the available normalization strategies for probability weight calculations.
- */
-export type Normalization = "relative" | "softmax";
-/**
- * Generates a pseudo-random number between 0 (inclusive) and 1 (exclusive).
- */
+import { EventEmitter } from 'events';
+export type Normalization = 'relative' | 'softmax';
 export type RngGenerator = () => number;
-/**
- * Represents a temporary weight modifier that is applied for a limited number of draws.
- */
 export type TempModifier = {
     /**
      * - Function that modifies the item weights.
@@ -20,9 +11,6 @@ export type TempModifier = {
      */
     uses: number;
 };
-/**
- * Represents the core data structure for an item in the raffle system.
- */
 export type ItemDataTemplate<TGroups extends Set<string> | string[]> = {
     /**
      * - Unique identifier for the item.
@@ -49,9 +37,6 @@ export type ItemDataTemplate<TGroups extends Set<string> | string[]> = {
      */
     meta: ItemMetadata;
 };
-/**
- * Represents the serialized state of the raffle system for export or persistence.
- */
 export type ExportedJson = {
     /**
      * - Array of item objects in their exported form.
@@ -74,39 +59,20 @@ export type ExportedJson = {
      */
     seed: number | null;
 };
-/**
- * A concrete version of ItemDataTemplate where groups is Set<string>.
- */
 export type ItemData = ItemDataTemplate<Set<string>>;
-/**
- * A concrete version of ItemDataTemplate where groups is string[].
- */
 export type ItemDataGetter = ItemDataTemplate<string[]>;
-/**
- * Arbitrary key-value metadata container for additional item information.
- * Keys can be strings, numbers, or symbols.
- */
 export type ItemMetadata = Record<string | number | symbol, any>;
-/**
- * Context object passed to weight modification functions during draw calculations.
- */
 export type ComputeEffectiveWeightsContext = {
     /**
      * - Metadata of the current raffle state or item.
      */
-    metadata?: ItemMetadata | undefined;
+    metadata?: ItemMetadata;
     /**
      * - History of previously drawn items.
      */
-    previousDraws?: DrawOne[] | undefined;
+    previousDraws?: DrawOne[];
 };
-/**
- * Maps each item ID to its computed effective weight.
- */
 export type Weights = Map<string, number>;
-/**
- * Pity system configuration and current state.
- */
 export type Pity = {
     /**
      * - Number of draws without a win before pity starts applying.
@@ -129,13 +95,7 @@ export type Pity = {
      */
     currentAdd: number;
 };
-/**
- * Function used to modify or override computed weights before a draw.
- */
 export type WeightsCallback = (weights: Weights, context: ComputeEffectiveWeightsContext) => Weights | null;
-/**
- * Represents the result of a single draw.
- */
 export type DrawOne = {
     /**
      * - Item ID.
@@ -154,9 +114,6 @@ export type DrawOne = {
      */
     prob: number;
 };
-/**
- * Generic event handler function for message or signal reception.
- */
 export type handler = (payload: any, event: any) => any;
 /**
  * Defines the available normalization strategies for probability weight calculations.
@@ -260,19 +217,8 @@ export type handler = (payload: any, event: any) => any;
  *
  * @class
  */
-declare class TinyAdvancedRaffle extends EventEmitter<any> {
-    /**
-     * Creates a new AdvancedRaffle instance.
-     * @param {Object} [opts] - Optional configuration.
-     * @param {RngGenerator|null} [opts.rng=null] - Custom RNG function. If null, an internal seeded RNG is used when a seed is provided.
-     * @param {number|null} [opts.seed=null] - Optional seed for deterministic results.
-     * @param {Normalization} [opts.normalization='relative'] - Probability normalization mode.
-     */
-    constructor(opts?: {
-        rng?: RngGenerator | null | undefined;
-        seed?: number | null | undefined;
-        normalization?: Normalization | undefined;
-    });
+declare class TinyAdvancedRaffle extends EventEmitter {
+    #private;
     /**
      * Indicates whether this instance has been destroyed.
      * @type {boolean}
@@ -289,6 +235,11 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      * @returns {number} Total count of items.
      */
     get size(): number;
+    /**
+     * Gets the current probability normalization strategy.
+     * @returns {Normalization} Current normalization mode.
+     */
+    get normalization(): Normalization;
     /**
      * Sets the probability normalization strategy.
      * @param {Normalization} value - Accepted values: `'relative'` or `'softmax'`.
@@ -296,10 +247,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      */
     set normalization(value: Normalization);
     /**
-     * Gets the current probability normalization strategy.
-     * @returns {Normalization} Current normalization mode.
+     * Gets the current RNG seed value, if any.
+     * @returns {number|null} Current seed or `null` if RNG is not seeded.
      */
-    get normalization(): Normalization;
+    get seed(): number | null;
     /**
      * Sets the RNG seed for deterministic randomization.
      * @param {number|null} value - Finite number or `null` to disable seeding.
@@ -307,10 +258,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      */
     set seed(value: number | null);
     /**
-     * Gets the current RNG seed value, if any.
-     * @returns {number|null} Current seed or `null` if RNG is not seeded.
+     * Gets all global weight modifier callbacks.
+     * @returns {WeightsCallback[]} Array of registered global modifier functions.
      */
-    get seed(): number | null;
+    get globalModifiers(): WeightsCallback[];
     /**
      * Replaces all global weight modifier callbacks.
      * @param {WeightsCallback[]} value - Array of modifier functions.
@@ -318,10 +269,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      */
     set globalModifiers(value: WeightsCallback[]);
     /**
-     * Gets all global weight modifier callbacks.
-     * @returns {WeightsCallback[]} Array of registered global modifier functions.
+     * Gets all temporary modifiers with usage counters.
+     * @returns {TempModifier[]} Array of temporary modifier entries.
      */
-    get globalModifiers(): WeightsCallback[];
+    get temporaryModifiers(): TempModifier[];
     /**
      * Replaces all temporary modifiers.
      * @param {TempModifier[]} value - Each object must have a function and a positive integer usage count.
@@ -329,10 +280,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      */
     set temporaryModifiers(value: TempModifier[]);
     /**
-     * Gets all temporary modifiers with usage counters.
-     * @returns {TempModifier[]} Array of temporary modifier entries.
+     * Gets all conditional rule callbacks.
+     * @returns {WeightsCallback[]} Array of conditional rule functions.
      */
-    get temporaryModifiers(): TempModifier[];
+    get conditionalRules(): WeightsCallback[];
     /**
      * Replaces all conditional rule callbacks.
      * @param {WeightsCallback[]} value - Array of functions.
@@ -340,10 +291,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      */
     set conditionalRules(value: WeightsCallback[]);
     /**
-     * Gets all conditional rule callbacks.
-     * @returns {WeightsCallback[]} Array of conditional rule functions.
+     * Gets a shallow copy of all configured pity systems.
+     * @returns {Record<string, Pity>} Object keyed by system name.
      */
-    get conditionalRules(): WeightsCallback[];
+    get pitySystems(): Record<string, Pity>;
     /**
      * Replaces all pity systems.
      * @param {Map<string, Pity>} value - Map of pity systems with numeric fields.
@@ -351,10 +302,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      */
     set pitySystems(value: Map<string, Pity>);
     /**
-     * Gets a shallow copy of all configured pity systems.
-     * @returns {Record<string, Pity>} Object keyed by system name.
+     * Gets a copy of all exclusion IDs.
+     * @returns {string[]} Array of item IDs excluded from draws.
      */
-    get pitySystems(): Record<string, Pity>;
+    get exclusions(): string[];
     /**
      * Replaces all exclusion IDs.
      * @param {Set<string>} value - Set of excluded item IDs.
@@ -362,10 +313,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      */
     set exclusions(value: Set<string>);
     /**
-     * Gets a copy of all exclusion IDs.
-     * @returns {string[]} Array of item IDs excluded from draws.
+     * Gets all group definitions.
+     * @returns {Record<string, string[]>} Object where each key is a group name and value is an array of item IDs.
      */
-    get exclusions(): string[];
+    get groups(): Record<string, string[]>;
     /**
      * Replaces all group definitions.
      * @param {Map<string, Set<string>>} value - Map of group names to item ID sets.
@@ -373,10 +324,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      */
     set groups(value: Map<string, Set<string>>);
     /**
-     * Gets all group definitions.
-     * @returns {Record<string, string[]>} Object where each key is a group name and value is an array of item IDs.
+     * Gets the current RNG function.
+     * @returns {RngGenerator} Function returning a floating-point number in [0, 1).
      */
-    get groups(): Record<string, string[]>;
+    get rng(): RngGenerator;
     /**
      * Sets the RNG function.
      * @param {RngGenerator} value - Function returning a number between 0 and 1.
@@ -384,10 +335,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      */
     set rng(value: RngGenerator);
     /**
-     * Gets the current RNG function.
-     * @returns {RngGenerator} Function returning a floating-point number in [0, 1).
+     * Gets all item definitions with group names expanded to arrays.
+     * @returns {Record<string, ItemDataGetter>} Object keyed by item ID.
      */
-    get rng(): RngGenerator;
+    get items(): Record<string, ItemDataGetter>;
     /**
      * Replaces all items (**and CLEAR OLD LIST**).
      * @param {Map<string, ItemData>} value - Map of item IDs to definitions.
@@ -395,16 +346,17 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      */
     set items(value: Map<string, ItemData>);
     /**
-     * Gets all item definitions with group names expanded to arrays.
-     * @returns {Record<string, ItemDataGetter>} Object keyed by item ID.
-     */
-    get items(): Record<string, ItemDataGetter>;
-    /**
-     * Checks if the instance has been destroyed and throws an error if so.
-     * @private
-     * @throws {Error} If the instance has already been destroyed.
+     * Creates a new AdvancedRaffle instance.
+     * @param {Object} [opts] - Optional configuration.
+     * @param {RngGenerator|null} [opts.rng=null] - Custom RNG function. If null, an internal seeded RNG is used when a seed is provided.
+     * @param {number|null} [opts.seed=null] - Optional seed for deterministic results.
+     * @param {Normalization} [opts.normalization='relative'] - Probability normalization mode.
      */
-    private _checkDestroyed;
+    constructor(opts?: {
+        rng?: RngGenerator | null;
+        seed?: number | null;
+        normalization?: Normalization;
+    });
     /**
      * Check if an item exists in the system.
      * @param {string} itemId - Item ID to check.
@@ -424,10 +376,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      * @throws {TypeError} If any parameter has an invalid type.
      */
     addItem(id: string, opts?: {
-        weight?: number | undefined;
-        label?: string | undefined;
-        meta?: ItemMetadata | undefined;
-        groups?: string[] | Set<string> | undefined;
+        weight?: number;
+        label?: string;
+        meta?: ItemMetadata;
+        groups?: string[] | Set<string>;
     }): ItemData;
     /**
      * Remove an item from the system.
@@ -548,7 +500,7 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
     configurePity(itemId: string, cfg: {
         threshold: number;
         increment: number;
-        cap?: number | undefined;
+        cap?: number;
     }): void;
     /**
      * Reset pity counters for a given item.
@@ -642,13 +594,9 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      * @param {Map<string, number>} weights - Map of item IDs to their weights.
      * @returns {Array<{id: string, weight: number, p: number, cumulative: number}>} Distribution array.
      * @throws {TypeError} If `weights` is not a Map.
+     * @private
      */
-    _weightsToDistribution(weights: Map<string, number>): Array<{
-        id: string;
-        weight: number;
-        p: number;
-        cumulative: number;
-    }>;
+    private _weightsToDistribution;
     /**
      * Draw a single item from the raffle using current configuration.
      * Uses previous draws and metadata to influence conditional rules and pity.
@@ -660,8 +608,8 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      * @throws {TypeError} If `opts` is not an object.
      */
     drawOne(opts?: {
-        previousDraws?: DrawOne[] | undefined;
-        metadata?: ItemMetadata | undefined;
+        previousDraws?: DrawOne[];
+        metadata?: ItemMetadata;
     }): DrawOne | null;
     /**
      * Internal helper to decrement usage counts of temporary modifiers,
@@ -683,10 +631,10 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      * @throws {TypeError} If `opts` is not an object.
      */
     drawMany(count?: number, opts?: {
-        metadata?: ItemMetadata | undefined;
-        withReplacement?: boolean | undefined;
-        ensureUnique?: boolean | undefined;
-        previousDraws?: DrawOne[] | undefined;
+        metadata?: ItemMetadata;
+        withReplacement?: boolean;
+        ensureUnique?: boolean;
+        previousDraws?: DrawOne[];
     }): DrawOne[];
     /**
      * Export the current configuration to a JSON-serializable object.
@@ -718,15 +666,15 @@ declare class TinyAdvancedRaffle extends EventEmitter<any> {
      * @param {number} seed - Seed value for PRNG (integer).
      * @returns {RngGenerator} A function that returns a pseudo-random number in [0, 1).
      * @throws {TypeError} If `seed` is not a finite number.
+     * @private
      */
-    _makeSeededRng(seed: number): RngGenerator;
+    private _makeSeededRng;
     /**
      * Completely destroys the raffle instance, clearing all data,
      * releasing references, and making the object unusable.
      * Once destroyed, any further method calls will throw errors.
      */
     destroy(): void;
-    #private;
 }
-import { EventEmitter } from 'events';
+export default TinyAdvancedRaffle;
 //# sourceMappingURL=TinyAdvancedRaffle.d.mts.map