@tixyel/streamelements 5.5.0 → 6.0.1

package/dist/index.d.ts

@@ -1919,7 +1919,7 @@ type QueueProps = {
 type QueueItem<T> = {
     value: T;
 } & QueueProps;
-type QueueProcessor<T> = (item: T, queue: useQueue<T>) => Promise<any>;
+type QueueProcessor<T> = (this: useQueue<T>, item: T, queue: useQueue<T>) => Promise<any>;
 type QueueDuration = number | boolean | undefined;
 interface QueueOptions<T> {
     /**
@@ -1939,7 +1939,7 @@ interface QueueOptions<T> {
  * ```javascript
  * const myQueue = new useQueue({
  *   duration: 1000,
- *   processor: async (item) => {
+ *   processor: async function (item) {
  *    console.log('Processing item:', item);
  *  },
  * });
@@ -1958,12 +1958,59 @@ declare class useQueue<T> extends EventProvider<QueueEvents<T>> {
     private loaded;
     processor: QueueProcessor<T>;
     constructor(options: QueueOptions<T>);
+    /**
+     * Enqueue an item or multiple items into the queue with optional processing options.
+     * @param value - The item or items to be enqueued. Can be a single value of type T or an array of objects containing the value and options.
+     * @param options - Optional processing options for the item(s) being enqueued. Ignored if an array of items is provided, as each item can have its own options.
+     * @returns The instance of the queue for chaining.
+     * @example
+     * ```javascript
+     * myQueue.enqueue('Single Item', { isPriority: true });
+     * myQueue.enqueue([
+     *   { value: 'Item 1', options: { isPriority: true } },
+     *   { value: 'Item 2', options: { isLoop: true } }
+     * ]);
+     * ```
+     */
     enqueue(value: T, options?: Partial<QueueProps>): this;
+    enqueue(items: {
+        value: T;
+        options?: Partial<QueueProps>;
+    }[]): this;
     private run;
     private next;
+    /**
+     * Resume processing the queue if it is paused. If the queue is already running, it will be restarted, which can be useful if new items have been added or if you want to reset the processing timer.
+     * If the queue was empty before, it will start processing immediately.
+     * @returns - The instance of the queue for chaining.
+     * @example
+     * ```javascript
+     * myQueue.resume();
+     * ```
+     */
     resume(): this;
+    /**
+     * Update the queue's state with new values. This can be used to replace the current queue, priority queue, history, or timeouts with new data. If the queue is not currently running and there are items in the queue after the update, it will start processing immediately.
+     * @param save - An object containing the new state for the queue, priority queue, history, and timeouts. Each property is optional, and if not provided, the current state will be retained.
+     * @returns - The instance of the queue for chaining.
+     * @example
+     * ```javascript
+     * myQueue.update({
+     *   queue: newQueueItems,
+     *   priorityQueue: newPriorityItems,
+     *   history: newHistory,
+     * });
+     * ```
+     */
     update(save: Partial<useQueue<T>>): this;
+    /**
+     * Cancel all pending timeouts and stop the queue from processing further items. This will clear any scheduled processing and prevent any new items from being processed until `resume()` is called again. The current state of the queue, priority queue, and history will be retained, allowing you to resume processing later without losing any data.
+     */
     cancel(): void;
+    /**
+     * Check if there are any items in the queue or priority queue. This method returns `true` if there are items waiting to be processed in either the main queue or the priority queue, and `false` if both queues are empty.
+     * @returns - A boolean indicating whether there are items in the queue or priority queue.
+     */
     hasItems(): boolean;
     on<K extends keyof QueueEvents<T>>(eventName: K, callback: (this: useQueue<T>, ...args: QueueEvents<T>[K]) => void): this;
 }
@@ -2248,6 +2295,7 @@ declare namespace Helper {
             amount?: number;
             count?: number;
         }) => string;
+        const PRESETS: Record<string, string>;
         /**
          * Replaces occurrences in a string based on a pattern with the result of an asynchronous callback function.
          * @param string - The input string to perform replacements on.
@@ -2282,15 +2330,69 @@ declare namespace Helper {
          * @returns The composed string with placeholders replaced and modifiers applied.
          * @example
          * ```javascript
-         * const template = "Hello, {username}! You have {amount} [UPPERCASE=messages] and your name is [CAPITALIZE=name].";
-         * const values = { username: "john_doe", amount: 5, name: "john" };
-         * const result = string.compose(template, values);
-         * console.log(result); // Output: "Hello, john_doe! You have 5 MESSAGES and your name is John."
+         * const { string } = Tixyel.Helper;
+         *
+         * // Basic usage with placeholders and simple modifiers
+         * const template1 = "Hello, {username}! You have {amount} [UPC=messages] and your name is [CAP=name].";
+         * const values1 = { username: "john_doe", amount: 5, name: "john" };
+         * const result1 = string.compose(template1, values1);
+         * // "Hello, john_doe! You have 5 MESSAGES and your name is John."
+         *
+         * // Multiple modifiers in a single block (HTML enabled)
+         * const template2 = "[COLOR:#ff0056,BOLD={username}]";
+         * const values2 = { username: "john_doe" };
+         * const result2 = string.compose(template2, values2, { html: true });
+         * // '<span class="color bold" style="color: #ff0056; font-weight: bold;">john_doe</span>'
+         *
+         * // Conditional rendering with IF (supports ===, >=, &&, ||, !, etc.)
+         * const template3 = "[IF=vip && status === 'live'?VIP Online|Offline]";
+         * const values3 = { status: 'live', vip: true };
+         * const result3 = string.compose(template3, values3);
+         * // "VIP Online"
+         *
+         * // Pluralization using amount / count or an explicit key
+         * const template4 = "You have {amount} [PLURAL=message|messages].";
+         * const values4 = { amount: 1 };
+         * const values5 = { amount: 3 };
+         * const result4a = string.compose(template4, values4); // "You have 1 message."
+         * const result4b = string.compose(template4, values5); // "You have 3 messages."
+         *
+         * // Number formatting
+         * const template5 = "Total: [NUMBER:2=amount] {currency}";
+         * const values6 = { amount: 1234.5, currency: '$' };
+         * const result5 = string.compose(template5, values6);
+         * // e.g. "Total: 1,234.50 $" (locale dependent)
+         *
+         * // Date and time formatting
+         * const template6 = "Created at: [DATE:iso=createdAt] ([DATE:relative=createdAt])";
+         * const values7 = { createdAt: new Date('2020-01-02T03:04:05.000Z') };
+         * const result6 = string.compose(template6, values7);
+         * // e.g. "Created at: 2020-01-02T03:04:05.000Z (Xs ago)"
+         *
+         * // MAP / SWITCH style mapping
+         * const template7 = "Status: [MAP:status=live:Online|offline:Offline|default:Unknown]";
+         * const values8 = { status: 'offline' };
+         * const result7 = string.compose(template7, values8);
+         * // "Status: Offline"
+         *
+         * // Escaping HTML
+         * const template8 = "[ESCAPE={message}]";
+         * const values9 = { message: '<b>Danger & "HTML"</b>' };
+         * const result8 = string.compose(template8, values9);
+         * // "&lt;b&gt;Danger &amp; &quot;HTML&quot;&lt;/b&gt;"
+         *
+         * // Using global presets
+         * Helper.string.PRESETS['alert'] = 'BOLD,COLOR:#ff0056';
+         * const template10 = "[PRESET:alert={username}]";
+         * const values11 = { username: 'john_doe' };
+         * const result10 = string.compose(template10, values11, { html: true });
+         * // '<span class="color bold" style="color: #ff0056; font-weight: bold;">john_doe</span>'
          * ```
          */
         function compose(template: string, values?: Record<string, any>, options?: {
             method?: 'loop' | 'index';
             html?: boolean;
+            debug?: boolean;
             modifiers?: Record<string, Modifier>;
             aliases?: Record<string, string[]>;
         }): string;