@useless-engineer/utils 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 saurabh bandkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+
+# 🛠️ @useless-engineer/utils
+
+**Small, typed utilities distilled from real production bugs.**
+One package. Multiple entry points. Only pay for what you import.
+
+[![npm version](https://img.shields.io/npm/v/@useless-engineer/utils?style=for-the-badge&logo=npm&color=CB3837&labelColor=1a1a1a)](https://www.npmjs.com/package/@useless-engineer/utils)
+[![npm downloads](https://img.shields.io/npm/dm/@useless-engineer/utils?style=for-the-badge&color=7c3aed&labelColor=1a1a1a)](https://www.npmjs.com/package/@useless-engineer/utils)
+[![license](https://img.shields.io/npm/l/@useless-engineer/utils?style=for-the-badge&color=22c55e&labelColor=1a1a1a)](./LICENSE)
+
+![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178C6?style=flat-square&logo=typescript&logoColor=white)
+![Tree-shakeable](https://img.shields.io/badge/tree--shakeable-yes-10b981?style=flat-square)
+![Zero deps](https://img.shields.io/badge/dependencies-0-f59e0b?style=flat-square)
+![ESM + CJS](https://img.shields.io/badge/ESM%20%2B%20CJS-both-0ea5e9?style=flat-square)
+![React Native](https://img.shields.io/badge/React%20Native-supported-61DAFB?style=flat-square&logo=react&logoColor=black)
+
+[**📦 Install**](#-install) ·
+[**⚡ Quick start**](#-quick-start) ·
+[**📚 API**](#-api) ·
+[**🗺️ Roadmap**](#️-roadmap) ·
+[**📸 Follow**](https://www.instagram.com/useless_engineer.dev/)
+
+</div>
+
+---
+
+## ✨ Why this exists
+
+Every utility here started as an [Instagram post](https://www.instagram.com/useless_engineer.dev/) about a bug that actually shipped. The post explains the problem; this package is the fix, typed and tested, so you never copy-paste it again.
+
+|                          |                                                        |
+| ------------------------ | ------------------------------------------------------ |
+| 🎯 **Focused**           | Each function does one thing and has tests             |
+| 🌲 **Tree-shakeable**    | `sideEffects: false`, import only what you use         |
+| 🧩 **Split by platform** | Core, React Native, and more, each its own import path |
+| 🔒 **Strictly typed**    | Written in TypeScript with strict mode on              |
+
+---
+
+## 📦 Install
+
+```bash
+npm install @useless-engineer/utils
+```
+
+<details>
+<summary><b>pnpm / yarn / bun</b></summary>
+
+```bash
+pnpm add @useless-engineer/utils
+yarn add @useless-engineer/utils
+bun add @useless-engineer/utils
+```
+
+</details>
+
+---
+
+## ⚡ Quick start
+
+```ts
+import { debounce, throttle } from "@useless-engineer/utils";
+
+const onSearch = debounce((query: string) => fetchResults(query), 300);
+const onScroll = throttle(() => updateHeader(), 100);
+```
+
+```ts
+import { isIOS, isAndroid } from "@useless-engineer/utils/react-native";
+
+const padding = isIOS ? 20 : 16;
+```
+
+> 💡 `react` and `react-native` are **optional** peer dependencies. If you only use the core entry, you never need to install either.
+
+---
+
+## 🧭 Entry points
+
+| Import path                            | For                       | Status                                                                        |
+| -------------------------------------- | ------------------------- | ----------------------------------------------------------------------------- |
+| `@useless-engineer/utils`              | Platform-agnostic helpers | ![live](https://img.shields.io/badge/-live-22c55e?style=flat-square)          |
+| `@useless-engineer/utils/react-native` | React Native helpers      | ![live](https://img.shields.io/badge/-live-22c55e?style=flat-square)          |
+| `@useless-engineer/utils/react`        | React hooks               | ![soon](https://img.shields.io/badge/-coming%20soon-f59e0b?style=flat-square) |
+
+---
+
+## 📚 API
+
+### 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>
+
+<br>
+
+Waits for quiet. Every call resets the timer, and only the last call fires. Good for search inputs and autosave.
+
+```ts
+const save = debounce((text: string) => api.save(text), 500);
+
+save("h");
+save("he");
+save("hello"); // only this one runs, 500ms after the last call
+
+// In a React effect cleanup, so nothing fires after unmount:
+save.cancel();
+```
+
+| Param       | Type                | Description                         |
+| ----------- | ------------------- | ----------------------------------- |
+| `fn`        | `(...args) => void` | Function to debounce                |
+| `delay`     | `number`            | Milliseconds of quiet before firing |
+| **returns** | `Debounced`         | Callable with a `.cancel()` method  |
+
+</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>
+
+<br>
+
+Keeps a steady beat. Runs at most once per interval, however often it's called. Good for scroll, drag, and resize.
+
+```ts
+const onScroll = throttle(() => updateHeader(), 100);
+
+// Skip the immediate first call:
+throttle(fn, 100, { leading: false });
+
+// Skip the final catch-up call:
+throttle(fn, 100, { trailing: false });
+```
+
+| Option     | Default | Description                                         |
+| ---------- | ------- | --------------------------------------------------- |
+| `leading`  | `true`  | Fire right away on the first call of a burst        |
+| `trailing` | `true`  | Fire once more at the end with the latest arguments |
+
+Returns a function with `.cancel()`.
+
+</details>
+
+<details>
+<summary><b>debounce or throttle?</b></summary>
+
+<br>
+
+|              | `debounce`                        | `throttle`                       |
+| ------------ | --------------------------------- | -------------------------------- |
+| Fires        | Once, after calls **stop**        | On a fixed beat **during** calls |
+| Use for      | Search box, autosave, validation  | Scroll, drag, resize             |
+| Ask yourself | "Do I only need the final state?" | "Does it need to stay live?"     |
+
+</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>
+
+<br>
+
+Plain booleans derived from `Platform.OS`.
+
+```ts
+import { isIOS, isAndroid } from "@useless-engineer/utils/react-native";
+
+const behavior = isIOS ? "padding" : "height";
+```
+
+</details>
+
+---
+
+## 🗺️ Roadmap
+
+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      |
+
+---
+
+## 🤝 Contributing
+
+Found a bug or have a post idea that deserves a utility? [Open an issue](https://github.com/<your-username>/useless-engineer/issues).
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+---
+
+<div align="center">
+
+**Built from real bugs, one post at a time.**
+
+[![Instagram](https://img.shields.io/badge/Follow-@useless__engineer.dev-E4405F?style=for-the-badge&logo=instagram&logoColor=white)](https://www.instagram.com/useless_engineer.dev/)
+
+MIT © Saurabh Bandkar
+
+</div>

package/dist/index.cjs

@@ -0,0 +1,60 @@
+'use strict';
+
+// src/async/debounce.ts
+function debounce(fn, delay) {
+  let timer;
+  const debounced = (...args) => {
+    if (timer !== void 0) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = void 0;
+      fn(...args);
+    }, delay);
+  };
+  debounced.cancel = () => {
+    if (timer !== void 0) clearTimeout(timer);
+    timer = void 0;
+  };
+  return debounced;
+}
+
+// src/async/throttle.ts
+function throttle(fn, interval, { leading = true, trailing = true } = {}) {
+  let timer;
+  let lastArgs;
+  let lastRun = 0;
+  const run = (args) => {
+    lastRun = Date.now();
+    fn(...args);
+  };
+  const throttled = (...args) => {
+    const now = Date.now();
+    if (lastRun === 0 && !leading) lastRun = now;
+    const remaining = interval - (now - lastRun);
+    if (remaining <= 0) {
+      if (timer !== void 0) clearTimeout(timer);
+      timer = void 0;
+      lastArgs = void 0;
+      run(args);
+    } else if (trailing) {
+      lastArgs = args;
+      if (timer === void 0) {
+        timer = setTimeout(() => {
+          timer = void 0;
+          const a = lastArgs;
+          lastArgs = void 0;
+          if (a) run(a);
+        }, remaining);
+      }
+    }
+  };
+  throttled.cancel = () => {
+    if (timer !== void 0) clearTimeout(timer);
+    timer = void 0;
+    lastArgs = void 0;
+    lastRun = 0;
+  };
+  return throttled;
+}
+
+exports.debounce = debounce;
+exports.throttle = throttle;

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+interface Debounced<A extends unknown[]> {
+    (...args: A): void;
+    /** Drop any pending call. Call this from your effect cleanup. */
+    cancel: () => void;
+}
+/**
+ * Delays `fn` until `delay` ms have passed with no new calls.
+ * Every call resets the timer; only the last one fires.
+ */
+declare function debounce<A extends unknown[]>(fn: (...args: A) => void, delay: number): Debounced<A>;
+
+interface ThrottleOptions {
+    /** Fire immediately on the first call of a burst. Default: true */
+    leading?: boolean;
+    /** Fire once more at the end of the burst with the latest args. Default: true */
+    trailing?: boolean;
+}
+interface Throttled<A extends unknown[]> {
+    (...args: A): void;
+    /** Drop any pending trailing call and reset. */
+    cancel: () => void;
+}
+/**
+ * Runs `fn` at most once per `interval` ms, however often it's called.
+ * Leading edge keeps UI snappy; trailing edge preserves the final update.
+ */
+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 };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+interface Debounced<A extends unknown[]> {
+    (...args: A): void;
+    /** Drop any pending call. Call this from your effect cleanup. */
+    cancel: () => void;
+}
+/**
+ * Delays `fn` until `delay` ms have passed with no new calls.
+ * Every call resets the timer; only the last one fires.
+ */
+declare function debounce<A extends unknown[]>(fn: (...args: A) => void, delay: number): Debounced<A>;
+
+interface ThrottleOptions {
+    /** Fire immediately on the first call of a burst. Default: true */
+    leading?: boolean;
+    /** Fire once more at the end of the burst with the latest args. Default: true */
+    trailing?: boolean;
+}
+interface Throttled<A extends unknown[]> {
+    (...args: A): void;
+    /** Drop any pending trailing call and reset. */
+    cancel: () => void;
+}
+/**
+ * Runs `fn` at most once per `interval` ms, however often it's called.
+ * Leading edge keeps UI snappy; trailing edge preserves the final update.
+ */
+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 };

package/dist/index.js

@@ -0,0 +1,57 @@
+// src/async/debounce.ts
+function debounce(fn, delay) {
+  let timer;
+  const debounced = (...args) => {
+    if (timer !== void 0) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = void 0;
+      fn(...args);
+    }, delay);
+  };
+  debounced.cancel = () => {
+    if (timer !== void 0) clearTimeout(timer);
+    timer = void 0;
+  };
+  return debounced;
+}
+
+// src/async/throttle.ts
+function throttle(fn, interval, { leading = true, trailing = true } = {}) {
+  let timer;
+  let lastArgs;
+  let lastRun = 0;
+  const run = (args) => {
+    lastRun = Date.now();
+    fn(...args);
+  };
+  const throttled = (...args) => {
+    const now = Date.now();
+    if (lastRun === 0 && !leading) lastRun = now;
+    const remaining = interval - (now - lastRun);
+    if (remaining <= 0) {
+      if (timer !== void 0) clearTimeout(timer);
+      timer = void 0;
+      lastArgs = void 0;
+      run(args);
+    } else if (trailing) {
+      lastArgs = args;
+      if (timer === void 0) {
+        timer = setTimeout(() => {
+          timer = void 0;
+          const a = lastArgs;
+          lastArgs = void 0;
+          if (a) run(a);
+        }, remaining);
+      }
+    }
+  };
+  throttled.cancel = () => {
+    if (timer !== void 0) clearTimeout(timer);
+    timer = void 0;
+    lastArgs = void 0;
+    lastRun = 0;
+  };
+  return throttled;
+}
+
+export { debounce, throttle };

package/dist/react-native/index.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+var reactNative = require('react-native');
+
+// src/react-native/index.ts
+var isIOS = reactNative.Platform.OS === "ios";
+var isAndroid = reactNative.Platform.OS === "android";
+
+exports.isAndroid = isAndroid;
+exports.isIOS = isIOS;

package/dist/react-native/index.d.cts

@@ -0,0 +1,4 @@
+declare const isIOS: boolean;
+declare const isAndroid: boolean;
+
+export { isAndroid, isIOS };

package/dist/react-native/index.d.ts

@@ -0,0 +1,4 @@
+declare const isIOS: boolean;
+declare const isAndroid: boolean;
+
+export { isAndroid, isIOS };

package/dist/react-native/index.js

@@ -0,0 +1,7 @@
+import { Platform } from 'react-native';
+
+// src/react-native/index.ts
+var isIOS = Platform.OS === "ios";
+var isAndroid = Platform.OS === "android";
+
+export { isAndroid, isIOS };

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "@useless-engineer/utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "repo for small, utility functions by useless engineer",
+  "author": "Useless Engineer",
+  "keywords": [
+    "utils",
+    "typescript",
+    "react-native",
+    "debounce",
+    "throttle"
+  ],
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saurabhbandkar/useless-engineer.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/saurabhbandkar/useless-engineer/issues"
+  },
+  "homepage": "https://github.com/saurabhbandkar/useless-engineer#readme",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./react-native": {
+      "import": {
+        "types": "./dist/react-native/index.d.ts",
+        "default": "./dist/react-native/index.js"
+      },
+      "require": {
+        "types": "./dist/react-native/index.d.cts",
+        "default": "./dist/react-native/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "react-native": [
+        "./dist/react-native/index.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.72"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "allowScripts": {
+    "esbuild": true
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
+  }
+}