@useless-engineer/utils 0.1.1 → 0.1.3

package/README.md

@@ -91,7 +91,7 @@ const padding = isIOS ? 20 : 16;
 ### Core
 
 <details>
-<summary><code>debounce(fn, delay)</code> &nbsp; ![live](https://img.shields.io/badge/-live-22c55e?style=flat-square) ![async](https://img.shields.io/badge/-async-6366f1?style=flat-square)</summary>
+<summary><code>debounce(fn, delay)</code> &nbsp; <img alt="live" src="https://img.shields.io/badge/-live-22c55e?style=flat-square"> <img alt="async" src="https://img.shields.io/badge/-async-6366f1?style=flat-square"></summary>
 
 <br>
 
@@ -117,7 +117,7 @@ save.cancel();
 </details>
 
 <details>
-<summary><code>throttle(fn, interval, options?)</code> &nbsp; ![live](https://img.shields.io/badge/-live-22c55e?style=flat-square) ![async](https://img.shields.io/badge/-async-6366f1?style=flat-square)</summary>
+<summary><code>throttle(fn, interval, options?)</code> &nbsp; <img alt="live" src="https://img.shields.io/badge/-live-22c55e?style=flat-square"> <img alt="async" src="https://img.shields.io/badge/-async-6366f1?style=flat-square"></summary>
 
 <br>
 
@@ -155,10 +155,82 @@ Returns a function with `.cancel()`.
 
 </details>
 
+<details>
+<summary><code>delay(ms, options?)</code> &nbsp; <img alt="live" src="https://img.shields.io/badge/-live-22c55e?style=flat-square"> <img alt="async" src="https://img.shields.io/badge/-async-6366f1?style=flat-square"></summary>
+
+<br>
+
+`await`-able sleep that rejects bad input (negative, `NaN`, `Infinity`) instead of silently firing instantly, and can be cancelled.
+
+```ts
+await delay(500);
+
+const ctrl = new AbortController();
+delay(5000, { signal: ctrl.signal }).catch(() => {});
+ctrl.abort(); // stops waiting; the promise rejects with the signal's reason
+```
+
+</details>
+
+<details>
+<summary><code>withTimeout(promise, ms, message?)</code> &nbsp; <img alt="live" src="https://img.shields.io/badge/-live-22c55e?style=flat-square"> <img alt="async" src="https://img.shields.io/badge/-async-6366f1?style=flat-square"></summary>
+
+<br>
+
+Rejects with a `TimeoutError` if the promise takes too long. Clears its timer once the promise settles.
+
+```ts
+try {
+  const user = await withTimeout(fetchUser(id), 3000);
+} catch (e) {
+  if (e instanceof TimeoutError) showRetry();
+}
+```
+
+> ⚠️ This stops _waiting_, not the work. A timed-out `fetch` keeps running unless you also pass it an `AbortSignal`.
+
+</details>
+
+<details>
+<summary><code>safeParseJSON(text, fallback?)</code> &nbsp; <img alt="live" src="https://img.shields.io/badge/-live-22c55e?style=flat-square"> <img alt="json" src="https://img.shields.io/badge/-json-f97316?style=flat-square"></summary>
+
+<br>
+
+`JSON.parse` that never throws. Returns the fallback for invalid JSON or for `null`/`undefined` input (like a missing `AsyncStorage` key).
+
+```ts
+const settings = safeParseJSON(raw, { theme: "light" });
+safeParseJSON("0", 99); // 0, valid falsy values are kept
+safeParseJSON("{oops", 1); // 1
+```
+
+> The type `T` is a promise from you, not a check. Validate untrusted data before relying on its shape.
+
+</details>
+
+<details>
+<summary><code>safeStringify(value, options?)</code> &nbsp; <img alt="live" src="https://img.shields.io/badge/-live-22c55e?style=flat-square"> <img alt="json" src="https://img.shields.io/badge/-json-f97316?style=flat-square"></summary>
+
+<br>
+
+`JSON.stringify` that never throws on circular references or `BigInt`.
+
+```ts
+const a = { name: "a" };
+a.self = a;
+safeStringify(a); // '{"name":"a","self":"[Circular]"}'
+safeStringify({ n: 10n }); // '{"n":"10"}'
+safeStringify(data, { space: 2 });
+```
+
+Shared (non-circular) references are kept as they are. Returns `undefined` when there's no JSON form, like `JSON.stringify`.
+
+</details>
+
 ### React Native
 
 <details>
-<summary><code>isIOS</code> / <code>isAndroid</code> &nbsp; ![live](https://img.shields.io/badge/-live-22c55e?style=flat-square) ![react native](https://img.shields.io/badge/-react%20native-61DAFB?style=flat-square&logoColor=black)</summary>
+<summary><code>isIOS</code> / <code>isAndroid</code> &nbsp; <img alt="live" src="https://img.shields.io/badge/-live-22c55e?style=flat-square"> <img alt="react native" src="https://img.shields.io/badge/-react%20native-61DAFB?style=flat-square&logoColor=black"></summary>
 
 <br>
 
@@ -178,12 +250,11 @@ const behavior = isIOS ? "padding" : "height";
 
 Released one or two at a time, each matching a post that's already live.
 
-| Next up                                                                                                                  | Entry        | Origin                                    |
-| ------------------------------------------------------------------------------------------------------------------------ | ------------ | ----------------------------------------- |
-| ![next](https://img.shields.io/badge/-next-f59e0b?style=flat-square) `delay`, `withTimeout`                              | core         | Validated timers, `Promise.race` timeouts |
-| ![planned](https://img.shields.io/badge/-planned-64748b?style=flat-square) `safeParseJSON`, `safeStringify`, `deepClone` | core         | JSON and shallow-copy gotchas             |
-| ![planned](https://img.shields.io/badge/-planned-64748b?style=flat-square) `getAccessibilityProps`, `createShadow`       | react-native | Accessibility and iOS-only shadows        |
-| ![planned](https://img.shields.io/badge/-planned-64748b?style=flat-square) `useInterval`, `useCountdown`, `useIsMounted` | react        | Stale closures and unmounted updates      |
+| Next up                                                                                                                  | Entry        | Origin                                 |
+| ------------------------------------------------------------------------------------------------------------------------ | ------------ | -------------------------------------- |
+| ![next](https://img.shields.io/badge/-next-f59e0b?style=flat-square) `deepClone`, `settle` helpers                       | core         | Shallow-copy and `Promise.all` gotchas |
+| ![planned](https://img.shields.io/badge/-planned-64748b?style=flat-square) `getAccessibilityProps`, `createShadow`       | react-native | Accessibility and iOS-only shadows     |
+| ![planned](https://img.shields.io/badge/-planned-64748b?style=flat-square) `useInterval`, `useCountdown`, `useIsMounted` | react        | Stale closures and unmounted updates   |
 
 ---
 

package/dist/index.cjs

@@ -1,14 +1,14 @@
 'use strict';
 
 // src/async/debounce.ts
-function debounce(fn, delay) {
+function debounce(fn, delay2) {
   let timer;
   const debounced = (...args) => {
     if (timer !== void 0) clearTimeout(timer);
     timer = setTimeout(() => {
       timer = void 0;
       fn(...args);
-    }, delay);
+    }, delay2);
   };
   debounced.cancel = () => {
     if (timer !== void 0) clearTimeout(timer);
@@ -56,5 +56,92 @@ function throttle(fn, interval, { leading = true, trailing = true } = {}) {
   return throttled;
 }
 
+// src/async/delay.ts
+function delay(ms, { signal } = {}) {
+  if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) {
+    return Promise.reject(
+      new RangeError(`delay: expected a finite, non-negative number of ms, got ${String(ms)}`)
+    );
+  }
+  if (signal?.aborted) return Promise.reject(signal.reason);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/async/withTimeout.ts
+var TimeoutError = class extends Error {
+  constructor(message = "Operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+function withTimeout(promise, ms, message) {
+  if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) {
+    return Promise.reject(
+      new RangeError(`withTimeout: expected a finite, non-negative number of ms, got ${String(ms)}`)
+    );
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new TimeoutError(message ?? `Timed out after ${ms}ms`)),
+      ms
+    );
+    Promise.resolve(promise).then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+// src/json/safeParseJSON.ts
+function safeParseJSON(text, fallback) {
+  if (typeof text !== "string") return fallback;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+
+// src/json/safeStringify.ts
+function safeStringify(value, { space } = {}) {
+  const ancestors = [];
+  function replacer(_key, val) {
+    if (typeof val === "bigint") return val.toString();
+    if (typeof val !== "object" || val === null) return val;
+    while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this) {
+      ancestors.pop();
+    }
+    if (ancestors.includes(val)) return "[Circular]";
+    ancestors.push(val);
+    return val;
+  }
+  try {
+    return JSON.stringify(value, replacer, space);
+  } catch {
+    return void 0;
+  }
+}
+
+exports.TimeoutError = TimeoutError;
 exports.debounce = debounce;
+exports.delay = delay;
+exports.safeParseJSON = safeParseJSON;
+exports.safeStringify = safeStringify;
 exports.throttle = throttle;
+exports.withTimeout = withTimeout;

package/dist/index.d.cts

@@ -26,4 +26,52 @@ interface Throttled<A extends unknown[]> {
  */
 declare function throttle<A extends unknown[]>(fn: (...args: A) => void, interval: number, { leading, trailing }?: ThrottleOptions): Throttled<A>;
 
-export { type Debounced, type ThrottleOptions, type Throttled, debounce, throttle };
+interface DelayOptions {
+    /** Abort to stop waiting early. The promise rejects with `signal.reason`. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolves after `ms` milliseconds.
+ *
+ * Unlike a bare `setTimeout`, it rejects bad input (NaN, negative, Infinity)
+ * instead of silently firing immediately, and it can be cancelled.
+ */
+declare function delay(ms: number, { signal }?: DelayOptions): Promise<void>;
+
+declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Rejects with `TimeoutError` if `promise` hasn't settled within `ms`.
+ *
+ * Note: this stops *waiting*, it does not stop the underlying work.
+ * To cancel a request too, pass an AbortSignal to it as well.
+ */
+declare function withTimeout<T>(promise: PromiseLike<T>, ms: number, message?: string): Promise<T>;
+
+/**
+ * Parses JSON without throwing. Returns `fallback` (or `undefined`) when the
+ * input is not a string or is not valid JSON.
+ *
+ * The result is NOT validated: `T` is a promise from you, not a check.
+ * Validate untrusted data before relying on its shape.
+ */
+declare function safeParseJSON<T>(text: string | null | undefined, fallback: T): T;
+declare function safeParseJSON<T = unknown>(text: string | null | undefined): T | undefined;
+
+interface SafeStringifyOptions {
+    /** Indentation, same as the third argument of JSON.stringify. */
+    space?: string | number;
+}
+/**
+ * Like JSON.stringify, but never throws:
+ * - circular references become "[Circular]" (shared, non-circular references are kept)
+ * - BigInt values become strings
+ * - anything else that throws (e.g. a failing toJSON) returns `undefined`
+ *
+ * Like JSON.stringify, returns `undefined` for top-level values with no JSON form
+ * (undefined, functions, symbols).
+ */
+declare function safeStringify(value: unknown, { space }?: SafeStringifyOptions): string | undefined;
+
+export { type Debounced, type DelayOptions, type SafeStringifyOptions, type ThrottleOptions, type Throttled, TimeoutError, debounce, delay, safeParseJSON, safeStringify, throttle, withTimeout };

package/dist/index.d.ts

@@ -26,4 +26,52 @@ interface Throttled<A extends unknown[]> {
  */
 declare function throttle<A extends unknown[]>(fn: (...args: A) => void, interval: number, { leading, trailing }?: ThrottleOptions): Throttled<A>;
 
-export { type Debounced, type ThrottleOptions, type Throttled, debounce, throttle };
+interface DelayOptions {
+    /** Abort to stop waiting early. The promise rejects with `signal.reason`. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolves after `ms` milliseconds.
+ *
+ * Unlike a bare `setTimeout`, it rejects bad input (NaN, negative, Infinity)
+ * instead of silently firing immediately, and it can be cancelled.
+ */
+declare function delay(ms: number, { signal }?: DelayOptions): Promise<void>;
+
+declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Rejects with `TimeoutError` if `promise` hasn't settled within `ms`.
+ *
+ * Note: this stops *waiting*, it does not stop the underlying work.
+ * To cancel a request too, pass an AbortSignal to it as well.
+ */
+declare function withTimeout<T>(promise: PromiseLike<T>, ms: number, message?: string): Promise<T>;
+
+/**
+ * Parses JSON without throwing. Returns `fallback` (or `undefined`) when the
+ * input is not a string or is not valid JSON.
+ *
+ * The result is NOT validated: `T` is a promise from you, not a check.
+ * Validate untrusted data before relying on its shape.
+ */
+declare function safeParseJSON<T>(text: string | null | undefined, fallback: T): T;
+declare function safeParseJSON<T = unknown>(text: string | null | undefined): T | undefined;
+
+interface SafeStringifyOptions {
+    /** Indentation, same as the third argument of JSON.stringify. */
+    space?: string | number;
+}
+/**
+ * Like JSON.stringify, but never throws:
+ * - circular references become "[Circular]" (shared, non-circular references are kept)
+ * - BigInt values become strings
+ * - anything else that throws (e.g. a failing toJSON) returns `undefined`
+ *
+ * Like JSON.stringify, returns `undefined` for top-level values with no JSON form
+ * (undefined, functions, symbols).
+ */
+declare function safeStringify(value: unknown, { space }?: SafeStringifyOptions): string | undefined;
+
+export { type Debounced, type DelayOptions, type SafeStringifyOptions, type ThrottleOptions, type Throttled, TimeoutError, debounce, delay, safeParseJSON, safeStringify, throttle, withTimeout };

package/dist/index.js

@@ -1,12 +1,12 @@
 // src/async/debounce.ts
-function debounce(fn, delay) {
+function debounce(fn, delay2) {
   let timer;
   const debounced = (...args) => {
     if (timer !== void 0) clearTimeout(timer);
     timer = setTimeout(() => {
       timer = void 0;
       fn(...args);
-    }, delay);
+    }, delay2);
   };
   debounced.cancel = () => {
     if (timer !== void 0) clearTimeout(timer);
@@ -54,4 +54,86 @@ function throttle(fn, interval, { leading = true, trailing = true } = {}) {
   return throttled;
 }
 
-export { debounce, throttle };
+// src/async/delay.ts
+function delay(ms, { signal } = {}) {
+  if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) {
+    return Promise.reject(
+      new RangeError(`delay: expected a finite, non-negative number of ms, got ${String(ms)}`)
+    );
+  }
+  if (signal?.aborted) return Promise.reject(signal.reason);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/async/withTimeout.ts
+var TimeoutError = class extends Error {
+  constructor(message = "Operation timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+function withTimeout(promise, ms, message) {
+  if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0) {
+    return Promise.reject(
+      new RangeError(`withTimeout: expected a finite, non-negative number of ms, got ${String(ms)}`)
+    );
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new TimeoutError(message ?? `Timed out after ${ms}ms`)),
+      ms
+    );
+    Promise.resolve(promise).then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+// src/json/safeParseJSON.ts
+function safeParseJSON(text, fallback) {
+  if (typeof text !== "string") return fallback;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+
+// src/json/safeStringify.ts
+function safeStringify(value, { space } = {}) {
+  const ancestors = [];
+  function replacer(_key, val) {
+    if (typeof val === "bigint") return val.toString();
+    if (typeof val !== "object" || val === null) return val;
+    while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this) {
+      ancestors.pop();
+    }
+    if (ancestors.includes(val)) return "[Circular]";
+    ancestors.push(val);
+    return val;
+  }
+  try {
+    return JSON.stringify(value, replacer, space);
+  } catch {
+    return void 0;
+  }
+}
+
+export { TimeoutError, debounce, delay, safeParseJSON, safeStringify, throttle, withTimeout };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useless-engineer/utils",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "repo for small, utility functions by useless engineer",
   "author": "Useless Engineer",
   "keywords": [