@ls-stack/utils 3.17.0 → 3.18.0

package/lib/dedent.cjs

@@ -23,33 +23,52 @@ __export(dedent_exports, {
   dedent: () => dedent
 });
 module.exports = __toCommonJS(dedent_exports);
-function dedent(strings, ...values) {
-  const raw = typeof strings === "string" ? [strings] : strings.raw;
-  let result = "";
-  for (let i = 0; i < raw.length; i++) {
-    result += raw[i].replace(/\\\n[ \t]*/g, "").replace(/\\`/g, "`");
-    if (i < values.length) {
-      result += values[i];
+var dedent = createDedent({});
+function createDedent(options) {
+  d.withOptions = (newOptions) => createDedent({ ...options, ...newOptions });
+  return d;
+  function d(strings, ...values) {
+    const raw = typeof strings === "string" ? [strings] : strings.raw;
+    const {
+      escapeSpecialCharacters = Array.isArray(strings),
+      trimWhitespace = true
+    } = options;
+    let result = "";
+    for (let i = 0; i < raw.length; i++) {
+      let next = raw[i];
+      if (escapeSpecialCharacters) {
+        next = next.replace(/\\\n[ \t]*/g, "").replace(/\\`/g, "`").replace(/\\\$/g, "$").replace(/\\\{/g, "{");
+      }
+      result += next;
+      if (i < values.length) {
+        result += values[i];
+      }
     }
-  }
-  const lines = result.split("\n");
-  let mindent = null;
-  lines.forEach((l) => {
-    const m = l.match(/^(\s+)\S+/);
-    if (m) {
-      const indent = m[1].length;
-      if (!mindent) {
-        mindent = indent;
-      } else {
-        mindent = Math.min(mindent, indent);
+    const lines = result.split("\n");
+    let mindent = null;
+    for (const l of lines) {
+      const m = l.match(/^(\s+)\S+/);
+      if (m) {
+        const indent = m[1].length;
+        if (!mindent) {
+          mindent = indent;
+        } else {
+          mindent = Math.min(mindent, indent);
+        }
       }
     }
-  });
-  if (mindent !== null) {
-    const m = mindent;
-    result = lines.map((l) => l.startsWith(" ") ? l.slice(m) : l).join("\n");
+    if (mindent !== null) {
+      const m = mindent;
+      result = lines.map((l) => l[0] === " " || l[0] === "	" ? l.slice(m) : l).join("\n");
+    }
+    if (trimWhitespace) {
+      result = result.trim();
+    }
+    if (escapeSpecialCharacters) {
+      result = result.replace(/\\n/g, "\n");
+    }
+    return result;
   }
-  return result.trim().replace(/\\n/g, "\n");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/lib/dedent.d.cts

@@ -1,5 +1,13 @@
-type InterpolateValue = string | number | boolean;
-declare function dedent(strings: TemplateStringsArray, ...values: InterpolateValue[]): string;
-declare function dedent(strings: string): string;
+interface DedentOptions {
+    escapeSpecialCharacters?: boolean;
+    trimWhitespace?: boolean;
+}
+interface Dedent {
+    (literals: string): string;
+    (strings: TemplateStringsArray, ...values: unknown[]): string;
+    withOptions: CreateDedent;
+}
+type CreateDedent = (options: DedentOptions) => Dedent;
+declare const dedent: Dedent;
 
-export { dedent };
+export { type CreateDedent, type Dedent, type DedentOptions, dedent };

package/lib/dedent.d.ts

@@ -1,5 +1,13 @@
-type InterpolateValue = string | number | boolean;
-declare function dedent(strings: TemplateStringsArray, ...values: InterpolateValue[]): string;
-declare function dedent(strings: string): string;
+interface DedentOptions {
+    escapeSpecialCharacters?: boolean;
+    trimWhitespace?: boolean;
+}
+interface Dedent {
+    (literals: string): string;
+    (strings: TemplateStringsArray, ...values: unknown[]): string;
+    withOptions: CreateDedent;
+}
+type CreateDedent = (options: DedentOptions) => Dedent;
+declare const dedent: Dedent;
 
-export { dedent };
+export { type CreateDedent, type Dedent, type DedentOptions, dedent };

package/lib/dedent.js

@@ -1,31 +1,50 @@
 // src/dedent.ts
-function dedent(strings, ...values) {
-  const raw = typeof strings === "string" ? [strings] : strings.raw;
-  let result = "";
-  for (let i = 0; i < raw.length; i++) {
-    result += raw[i].replace(/\\\n[ \t]*/g, "").replace(/\\`/g, "`");
-    if (i < values.length) {
-      result += values[i];
+var dedent = createDedent({});
+function createDedent(options) {
+  d.withOptions = (newOptions) => createDedent({ ...options, ...newOptions });
+  return d;
+  function d(strings, ...values) {
+    const raw = typeof strings === "string" ? [strings] : strings.raw;
+    const {
+      escapeSpecialCharacters = Array.isArray(strings),
+      trimWhitespace = true
+    } = options;
+    let result = "";
+    for (let i = 0; i < raw.length; i++) {
+      let next = raw[i];
+      if (escapeSpecialCharacters) {
+        next = next.replace(/\\\n[ \t]*/g, "").replace(/\\`/g, "`").replace(/\\\$/g, "$").replace(/\\\{/g, "{");
+      }
+      result += next;
+      if (i < values.length) {
+        result += values[i];
+      }
     }
-  }
-  const lines = result.split("\n");
-  let mindent = null;
-  lines.forEach((l) => {
-    const m = l.match(/^(\s+)\S+/);
-    if (m) {
-      const indent = m[1].length;
-      if (!mindent) {
-        mindent = indent;
-      } else {
-        mindent = Math.min(mindent, indent);
+    const lines = result.split("\n");
+    let mindent = null;
+    for (const l of lines) {
+      const m = l.match(/^(\s+)\S+/);
+      if (m) {
+        const indent = m[1].length;
+        if (!mindent) {
+          mindent = indent;
+        } else {
+          mindent = Math.min(mindent, indent);
+        }
       }
     }
-  });
-  if (mindent !== null) {
-    const m = mindent;
-    result = lines.map((l) => l.startsWith(" ") ? l.slice(m) : l).join("\n");
+    if (mindent !== null) {
+      const m = mindent;
+      result = lines.map((l) => l[0] === " " || l[0] === "	" ? l.slice(m) : l).join("\n");
+    }
+    if (trimWhitespace) {
+      result = result.trim();
+    }
+    if (escapeSpecialCharacters) {
+      result = result.replace(/\\n/g, "\n");
+    }
+    return result;
   }
-  return result.trim().replace(/\\n/g, "\n");
 }
 export {
   dedent

package/lib/timers.cjs

@@ -0,0 +1,93 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/timers.ts
+var timers_exports = {};
+__export(timers_exports, {
+  createDebouncedTimeout: () => createDebouncedTimeout,
+  createInterval: () => createInterval,
+  createTimeout: () => createTimeout,
+  createWaitUntil: () => createWaitUntil
+});
+module.exports = __toCommonJS(timers_exports);
+function createTimeout(ms, callback) {
+  const timeoutId = setTimeout(callback, ms);
+  let isCleaned = false;
+  return () => {
+    if (isCleaned) return;
+    clearTimeout(timeoutId);
+    isCleaned = true;
+  };
+}
+function createInterval(ms, callback) {
+  const intervalId = setInterval(callback, ms);
+  let isCleaned = false;
+  return () => {
+    if (isCleaned) return;
+    clearInterval(intervalId);
+    isCleaned = true;
+  };
+}
+function createDebouncedTimeout(ms, callback) {
+  let cleanupTimer = null;
+  return {
+    clean: () => {
+      cleanupTimer?.();
+    },
+    call: () => {
+      cleanupTimer?.();
+      cleanupTimer = createTimeout(ms, () => {
+        callback();
+      });
+    }
+  };
+}
+function createWaitUntil({
+  condition,
+  maxWaitMs,
+  callback,
+  checkIntervalMs = 20
+}) {
+  let cleanCheckTimeout = null;
+  let cleanMaxWaitTimeout = null;
+  cleanMaxWaitTimeout = createTimeout(maxWaitMs, () => {
+    cleanCheckTimeout?.();
+  });
+  function check() {
+    const result = condition();
+    if (result) {
+      cleanMaxWaitTimeout?.();
+      callback(result);
+    } else {
+      cleanCheckTimeout = createTimeout(checkIntervalMs, check);
+    }
+  }
+  check();
+  return () => {
+    cleanMaxWaitTimeout();
+    cleanCheckTimeout?.();
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDebouncedTimeout,
+  createInterval,
+  createTimeout,
+  createWaitUntil
+});

package/lib/timers.d.cts

@@ -0,0 +1,110 @@
+type CleanupTimer = () => void;
+/**
+ * Creates a timeout with automatic cleanup capability.
+ *
+ * Returns a cleanup function that can be called to cancel the timeout.
+ * The cleanup function is idempotent - calling it multiple times is safe.
+ *
+ * @param ms - The timeout duration in milliseconds
+ * @param callback - The function to execute when the timeout completes
+ * @returns A cleanup function that cancels the timeout when called
+ *
+ * @example
+ * ```typescript
+ * const cleanup = createTimeout(1000, () => {
+ *   console.log('Timeout completed');
+ * });
+ *
+ * // Cancel the timeout before it completes
+ * cleanup();
+ * ```
+ */
+declare function createTimeout(ms: number, callback: () => void): CleanupTimer;
+/**
+ * Creates an interval with automatic cleanup capability.
+ *
+ * Returns a cleanup function that can be called to cancel the interval.
+ * The cleanup function is idempotent - calling it multiple times is safe.
+ *
+ * @param ms - The interval duration in milliseconds
+ * @param callback - The function to execute on each interval tick
+ * @returns A cleanup function that cancels the interval when called
+ *
+ * @example
+ * ```typescript
+ * const cleanup = createInterval(1000, () => {
+ *   console.log('Interval tick');
+ * });
+ *
+ * // Stop the interval
+ * cleanup();
+ * ```
+ */
+declare function createInterval(ms: number, callback: () => void): CleanupTimer;
+/**
+ * Creates a timeout that prevents concurrent executions.
+ *
+ * Each call to the `call` function will cancel any previous pending timeout
+ * and start a new one. This is useful for debouncing or ensuring only the
+ * last call executes after a delay.
+ *
+ * @param ms - The timeout duration in milliseconds
+ * @param callback - The function to execute when the timeout completes
+ * @returns An object with `call` to trigger the timeout and `clean` to cancel it
+ *
+ * @example
+ * ```typescript
+ * const { call, clean } = createDebouncedTimeout(1000, () => {
+ *   console.log('Only the last call executes');
+ * });
+ *
+ * call(); // This will be cancelled
+ * call(); // This will be cancelled
+ * call(); // Only this one will execute after 1000ms
+ *
+ * // Or cancel all pending timeouts
+ * clean();
+ * ```
+ */
+declare function createDebouncedTimeout(ms: number, callback: () => void): {
+    call: () => void;
+    clean: CleanupTimer;
+};
+/**
+ * Creates a timeout that waits for a condition to become true.
+ *
+ * Polls the condition function at regular intervals until it returns a truthy value,
+ * then calls the callback with that value. If the condition doesn't become true
+ * within the maximum wait time, the timeout expires without calling the callback.
+ *
+ * @template T - The type of value returned by the condition function when true
+ * @param options - Configuration options
+ * @param options.condition - Function that returns false or a truthy value when the condition is met
+ * @param options.maxWaitMs - Maximum time to wait for the condition in milliseconds
+ * @param options.callback - Function to call when the condition becomes true
+ * @param options.checkIntervalMs - How often to check the condition in milliseconds (default: 20)
+ * @returns A cleanup function that cancels the condition timeout
+ *
+ * @example
+ * ```typescript
+ * const cleanup = createWaitUntil({
+ *   condition: () => document.getElementById('myElement'),
+ *   maxWaitMs: 5000,
+ *   callback: (element) => {
+ *     console.log('Element found:', element);
+ *   },
+ *   checkIntervalMs: 50
+ * });
+ *
+ * // Cancel the condition check
+ * cleanup();
+ * ```
+ */
+declare function createWaitUntil<T extends NonNullable<unknown>>({ condition, maxWaitMs, callback, checkIntervalMs, }: {
+    condition: () => false | T;
+    maxWaitMs: number;
+    callback: (value: T) => void;
+    checkIntervalMs?: number;
+}): CleanupTimer;
+
+export { type CleanupTimer, createDebouncedTimeout, createInterval, createTimeout, createWaitUntil };

package/lib/timers.d.ts

@@ -0,0 +1,110 @@
+type CleanupTimer = () => void;
+/**
+ * Creates a timeout with automatic cleanup capability.
+ *
+ * Returns a cleanup function that can be called to cancel the timeout.
+ * The cleanup function is idempotent - calling it multiple times is safe.
+ *
+ * @param ms - The timeout duration in milliseconds
+ * @param callback - The function to execute when the timeout completes
+ * @returns A cleanup function that cancels the timeout when called
+ *
+ * @example
+ * ```typescript
+ * const cleanup = createTimeout(1000, () => {
+ *   console.log('Timeout completed');
+ * });
+ *
+ * // Cancel the timeout before it completes
+ * cleanup();
+ * ```
+ */
+declare function createTimeout(ms: number, callback: () => void): CleanupTimer;
+/**
+ * Creates an interval with automatic cleanup capability.
+ *
+ * Returns a cleanup function that can be called to cancel the interval.
+ * The cleanup function is idempotent - calling it multiple times is safe.
+ *
+ * @param ms - The interval duration in milliseconds
+ * @param callback - The function to execute on each interval tick
+ * @returns A cleanup function that cancels the interval when called
+ *
+ * @example
+ * ```typescript
+ * const cleanup = createInterval(1000, () => {
+ *   console.log('Interval tick');
+ * });
+ *
+ * // Stop the interval
+ * cleanup();
+ * ```
+ */
+declare function createInterval(ms: number, callback: () => void): CleanupTimer;
+/**
+ * Creates a timeout that prevents concurrent executions.
+ *
+ * Each call to the `call` function will cancel any previous pending timeout
+ * and start a new one. This is useful for debouncing or ensuring only the
+ * last call executes after a delay.
+ *
+ * @param ms - The timeout duration in milliseconds
+ * @param callback - The function to execute when the timeout completes
+ * @returns An object with `call` to trigger the timeout and `clean` to cancel it
+ *
+ * @example
+ * ```typescript
+ * const { call, clean } = createDebouncedTimeout(1000, () => {
+ *   console.log('Only the last call executes');
+ * });
+ *
+ * call(); // This will be cancelled
+ * call(); // This will be cancelled
+ * call(); // Only this one will execute after 1000ms
+ *
+ * // Or cancel all pending timeouts
+ * clean();
+ * ```
+ */
+declare function createDebouncedTimeout(ms: number, callback: () => void): {
+    call: () => void;
+    clean: CleanupTimer;
+};
+/**
+ * Creates a timeout that waits for a condition to become true.
+ *
+ * Polls the condition function at regular intervals until it returns a truthy value,
+ * then calls the callback with that value. If the condition doesn't become true
+ * within the maximum wait time, the timeout expires without calling the callback.
+ *
+ * @template T - The type of value returned by the condition function when true
+ * @param options - Configuration options
+ * @param options.condition - Function that returns false or a truthy value when the condition is met
+ * @param options.maxWaitMs - Maximum time to wait for the condition in milliseconds
+ * @param options.callback - Function to call when the condition becomes true
+ * @param options.checkIntervalMs - How often to check the condition in milliseconds (default: 20)
+ * @returns A cleanup function that cancels the condition timeout
+ *
+ * @example
+ * ```typescript
+ * const cleanup = createWaitUntil({
+ *   condition: () => document.getElementById('myElement'),
+ *   maxWaitMs: 5000,
+ *   callback: (element) => {
+ *     console.log('Element found:', element);
+ *   },
+ *   checkIntervalMs: 50
+ * });
+ *
+ * // Cancel the condition check
+ * cleanup();
+ * ```
+ */
+declare function createWaitUntil<T extends NonNullable<unknown>>({ condition, maxWaitMs, callback, checkIntervalMs, }: {
+    condition: () => false | T;
+    maxWaitMs: number;
+    callback: (value: T) => void;
+    checkIntervalMs?: number;
+}): CleanupTimer;
+
+export { type CleanupTimer, createDebouncedTimeout, createInterval, createTimeout, createWaitUntil };

package/lib/timers.js

@@ -0,0 +1,65 @@
+// src/timers.ts
+function createTimeout(ms, callback) {
+  const timeoutId = setTimeout(callback, ms);
+  let isCleaned = false;
+  return () => {
+    if (isCleaned) return;
+    clearTimeout(timeoutId);
+    isCleaned = true;
+  };
+}
+function createInterval(ms, callback) {
+  const intervalId = setInterval(callback, ms);
+  let isCleaned = false;
+  return () => {
+    if (isCleaned) return;
+    clearInterval(intervalId);
+    isCleaned = true;
+  };
+}
+function createDebouncedTimeout(ms, callback) {
+  let cleanupTimer = null;
+  return {
+    clean: () => {
+      cleanupTimer?.();
+    },
+    call: () => {
+      cleanupTimer?.();
+      cleanupTimer = createTimeout(ms, () => {
+        callback();
+      });
+    }
+  };
+}
+function createWaitUntil({
+  condition,
+  maxWaitMs,
+  callback,
+  checkIntervalMs = 20
+}) {
+  let cleanCheckTimeout = null;
+  let cleanMaxWaitTimeout = null;
+  cleanMaxWaitTimeout = createTimeout(maxWaitMs, () => {
+    cleanCheckTimeout?.();
+  });
+  function check() {
+    const result = condition();
+    if (result) {
+      cleanMaxWaitTimeout?.();
+      callback(result);
+    } else {
+      cleanCheckTimeout = createTimeout(checkIntervalMs, check);
+    }
+  }
+  check();
+  return () => {
+    cleanMaxWaitTimeout();
+    cleanCheckTimeout?.();
+  };
+}
+export {
+  createDebouncedTimeout,
+  createInterval,
+  createTimeout,
+  createWaitUntil
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Typescript utils",
-  "version": "3.17.0",
+  "version": "3.18.0",
   "license": "MIT",
   "files": [
     "lib"
@@ -18,6 +18,10 @@
       "import": "./lib/main.js",
       "require": "./lib/main.cjs"
     },
+    "./__snapshots__": {
+      "import": "./lib/__snapshots__.js",
+      "require": "./lib/__snapshots__.cjs"
+    },
     "./arrayUtils": {
       "import": "./lib/arrayUtils.js",
       "require": "./lib/arrayUtils.cjs"
@@ -150,6 +154,10 @@
       "import": "./lib/time.js",
       "require": "./lib/time.cjs"
     },
+    "./timers": {
+      "import": "./lib/timers.js",
+      "require": "./lib/timers.cjs"
+    },
     "./tsResult": {
       "import": "./lib/tsResult.js",
       "require": "./lib/tsResult.cjs"