idchunk 2.2.0 → 2.4.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Garv Thakral
-
-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
+MIT License
+
+Copyright (c) 2025 Garv Thakral
+
+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,100 +1,132 @@
-# ⚡ idchunk — Tiny, Fast & Customizable ID Generator
-
-<table width="100%">
-  <tr>
-    <td>
-      <a href="https://www.npmjs.com/package/idchunk">
-        <img src="https://img.shields.io/npm/v/idchunk.svg" alt="npm version"/>
-      </a>
-      <a href="https://www.npmjs.com/package/idchunk">
-        <img src="https://img.shields.io/npm/dt/idchunk.svg" alt="downloads"/>
-      </a>
-      <a href="https://github.com/garvthakral/idchunk/blob/main/LICENSE">
-        <img src="https://img.shields.io/npm/l/idchunk.svg" alt="license"/>
-      </a>
-    </td>
-    <td>
-      <a href="https://idchunk.netlify.app/">
-        <img src="https://i.pinimg.com/736x/d0/68/64/d06864b8b20b18921e465d401fa605e4.jpg" alt="idchunk barcode" width="60"/>
-      </a>
-    </td>
-  </tr>
-</table>
-
-> Generate short, secure, and customizable IDs for your applications in **milliseconds**.
-
----
-
-## ✨ Features
-- **Tiny:** Zero dependencies, minimal footprint.
-- **Secure & Fast:** Uses Node.js [`crypto`](https://nodejs.org/api/crypto.html).
-- **Customizable:** Choose length *and* your own character set.
-- **Reliable:** Collision-resistant random IDs.
-
----
-
-## 📦 Installation
-
-```bash
-npm install idchunk
-```
-
----
-
-## Usage
-
-By default, `idchunk()` generates a random ID of length **10**:
-
-```js
-const idchunk = require("idchunk");
-
-console.log(idchunk()); 
-// Example: "aZ8_-kL2pQ"
-```
-
-You can specify a custom length:
-
-```js
-console.log(idchunk(16)); 
-// Example: "bQ9pL2_-aZ8kL2pQ"
-```
-
-Custom character set:
-
-```js
-const customValues = "ABC123";
-console.log(idchunk(8, customValues)); 
-// Example: "1A23BCAB"
-```
-
-
-
----
-
-## API
-
-### `idchunk(length?: number, customValues?: string): string`
-
-- `length` (optional) → Length of the ID (default: 10).
-
-- `customValues` (optional) → String of allowed characters (default: a-zA-Z0-9_-).
-
-- Returns: Random string ID.
----
-
-## How It Works
-
-- Uses Node.js [`crypto`](https://nodejs.org/api/crypto.html) for secure random number generation.
-- Character set: `a-z`, `A-Z`, `0-9`, `_`, `-`.
-
----
-
-## 📄 License
-
-MIT © [Garv Thakral](https://github.com/codebygarv)
-
----
-
-## Documentation
-
+# ⚡ idchunk — Tiny, Blazingly Fast & Customizable ID Generator
+
+<table width="100%">
+  <tr>
+    <td>
+      <a href="https://www.npmjs.com/package/idchunk">
+        <img src="https://img.shields.io/npm/v/idchunk.svg" alt="npm version"/>
+      </a>
+      <a href="https://www.npmjs.com/package/idchunk">
+        <img src="https://img.shields.io/npm/dt/idchunk.svg" alt="downloads"/>
+      </a>
+      <a href="https://github.com/garvthakral/idchunk/blob/main/LICENSE">
+        <img src="https://img.shields.io/npm/l/idchunk.svg" alt="license"/>
+      </a>
+      <a href="https://www.npmjs.com/package/idchunk">
+        <img src="https://img.shields.io/npm/types/idchunk.svg" alt="types included"/>
+      </a>
+    </td>
+    <td>
+      <a href="https://idchunk.netlify.app/">
+        <img src="https://i.pinimg.com/736x/d0/68/64/d06864b8b20b18921e465d401fa605e4.jpg" alt="idchunk barcode" width="60"/>
+      </a>
+    </td>
+  </tr>
+</table>
+
+> Generate short, secure, and customizable IDs for your applications in **milliseconds**.
+
+---
+
+## ✨ Features
+- **🚀 Blazingly Fast:** Uses optimized bulk random-byte generation for maximum performance.
+- **🛡️ TypeScript Ready:** Native `.d.ts` definitions included out of the box.
+- **🧩 Built-in Presets:** Instantly generate OTP numbers, hex tokens, and more.
+- **📦 Tiny:** Zero dependencies, incredibly minimal footprint.
+- **🔒 Secure:** Uses Node.js [`crypto`](https://nodejs.org/api/crypto.html) for cryptographically secure randomness.
+- **🛠️ Customizable:** Choose the exact length *and* your own custom character set.
+
+---
+
+## 🏎️ Benchmark
+*Recorded on June 21, 2026 (1,000,000 iterations generating 10-character IDs).*
+
+**`idchunk` is ~40% faster than NanoID** when using custom alphabets!
+
+| Library | Standard (10 chars) | Custom Alphabet (10 chars) |
+| :--- | :--- | :--- |
+| `crypto.randomUUID()` | 101.69 ms | N/A |
+| `uuid v4` | 184.39 ms | N/A |
+| **`nanoid`** | 211.22 ms | 472.50 ms |
+| **`idchunk`** | 235.55 ms | **288.59 ms** 🏆 |
+
+---
+
+## 📦 Installation
+
+```bash
+npm install idchunk
+```
+
+---
+
+## Usage
+
+By default, `idchunk()` generates a random ID of length **10**:
+
+```js
+const idchunk = require("idchunk");
+
+console.log(idchunk()); 
+// Example: "aZ8_-kL2pQ"
+```
+
+You can specify a custom length:
+
+```js
+console.log(idchunk(16)); 
+// Example: "bQ9pL2_-aZ8kL2pQ"
+```
+
+Custom character set:
+
+```js
+const customValues = "ABC123";
+console.log(idchunk(8, customValues)); 
+// Example: "1A23BCAB"
+```
+
+### 🎯 Built-in Presets
+Don't want to define custom alphabets? Use the built-in presets:
+
+```js
+const idchunk = require("idchunk");
+
+console.log(idchunk.numbers(6));   // "829103" - Great for OTPs and 2FA
+console.log(idchunk.hex(12));      // "e4368746a829" - Great for tokens
+console.log(idchunk.lowercase(8)); // "ymddmahe"
+console.log(idchunk.uppercase(8)); // "WFKVFGSW"
+```
+
+---
+
+## API
+
+### `idchunk(length?: number, customValues?: string): string`
+- `length` (optional) → Length of the ID (default: 10).
+- `customValues` (optional) → String of allowed characters (default: a-zA-Z0-9_-).
+- Returns: Random string ID.
+
+### `idchunk.numbers(length?: number): string`
+### `idchunk.hex(length?: number): string`
+### `idchunk.lowercase(length?: number): string`
+### `idchunk.uppercase(length?: number): string`
+
+---
+
+## How It Works
+
+- Pre-allocates an array of secure random bytes using Node.js [`crypto.randomBytes`](https://nodejs.org/api/crypto.html) or `crypto.getRandomValues()` for a massive performance boost over single-character generation.
+- Default character set: `a-z`, `A-Z`, `0-9`, `_`, `-`.
+
+---
+
+## 📄 License
+
+MIT © [Garv Thakral](https://github.com/codebygarv)
+
+---
+
+## Documentation
+
 Read full documentation here : [**Read Docs**](https://idchunk.netlify.app/)

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "idchunk",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Tiny, Fast & Customizable ID Generator",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "files": [
     "src",
     "README.md",
@@ -25,5 +26,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/codebygarv/idchunk.git"
+  },
+  "devDependencies": {
+    "nanoid": "^3.3.14",
+    "uuid": "^14.0.1"
   }
-}
+}

package/src/index.d.ts

@@ -0,0 +1,25 @@
+declare module "idchunk" {
+  /**
+   * Generates a random ID of the specified length using the provided custom values.
+   * @param length The length of the ID to generate (default: 10).
+   * @param customValues A string of characters to use for the ID (default: a-zA-Z0-9_-).
+   * @returns A string representing the generated ID.
+   */
+  function idchunk(length?: number, customValues?: string): string;
+
+  namespace idchunk {
+    /** Generates a random ID consisting only of numbers (0-9). */
+    export function numbers(length?: number): string;
+    
+    /** Generates a random ID consisting of lowercase hex characters (0-9, a-f). */
+    export function hex(length?: number): string;
+    
+    /** Generates a random ID consisting only of lowercase letters (a-z). */
+    export function lowercase(length?: number): string;
+    
+    /** Generates a random ID consisting only of uppercase letters (A-Z). */
+    export function uppercase(length?: number): string;
+  }
+
+  export = idchunk;
+}

package/src/index.js

@@ -1,43 +1,61 @@
-let nodeCrypto;
-try {
-  nodeCrypto = require("crypto");
-} catch {
-  nodeCrypto = null;
-}
-
-const DEFAULT_VALUES =
-  "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-";
-
-function getRandomInt(max) {
-  if (nodeCrypto) {
-    if (typeof nodeCrypto.randomInt === "function") {
-      return nodeCrypto.randomInt(0, max);
-    }
-    if (typeof nodeCrypto.randomBytes === "function") {
-      return nodeCrypto.randomBytes(1)[0] % max;
-    }
-  }
-
-  if (typeof globalThis.crypto !== "undefined" && globalThis.crypto.getRandomValues) {
-    const arr = new Uint32Array(1);
-    globalThis.crypto.getRandomValues(arr);
-    return arr[0] % max;
-  }
-
-  return Math.floor(Math.random() * max);
-}
-
-function idchunk(length = 10, customValues = DEFAULT_VALUES) {
-  if (typeof customValues !== "string" || customValues.length === 0) {
-    throw new Error("customValues must be a non-empty string");
-  }
-
-  let result = "";
-  for (let i = 0; i < length; i++) {
-    const randomIndex = getRandomInt(customValues.length);
-    result += customValues[randomIndex];
-  }
-  return result;
-}
-
-module.exports = idchunk;
+let nodeCrypto;
+try {
+  nodeCrypto = require("crypto");
+} catch {
+  nodeCrypto = null;
+}
+
+const DEFAULT_VALUES =
+  "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-";
+
+const POOL_SIZE = 4096;
+let pool;
+let poolOffset = POOL_SIZE;
+
+function fillPool() {
+  if (nodeCrypto && typeof nodeCrypto.randomFillSync === "function") {
+    if (!pool || pool.length !== POOL_SIZE) {
+      pool = typeof Buffer !== "undefined" ? Buffer.allocUnsafe(POOL_SIZE) : new Uint8Array(POOL_SIZE);
+    }
+    nodeCrypto.randomFillSync(pool);
+  } else if (typeof globalThis.crypto !== "undefined" && globalThis.crypto.getRandomValues) {
+    if (!pool || pool.length !== POOL_SIZE) {
+      pool = new Uint8Array(POOL_SIZE);
+    }
+    globalThis.crypto.getRandomValues(pool);
+  } else {
+    if (!pool || pool.length !== POOL_SIZE) {
+      pool = new Uint8Array(POOL_SIZE);
+    }
+    for (let i = 0; i < POOL_SIZE; i++) {
+      pool[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  poolOffset = 0;
+}
+
+function idchunk(length = 10, customValues = DEFAULT_VALUES) {
+  if (typeof customValues !== "string" || customValues.length === 0) {
+    throw new Error("customValues must be a non-empty string");
+  }
+
+  const limit = customValues.length;
+  let result = "";
+
+  for (let i = 0; i < length; i++) {
+    if (poolOffset >= POOL_SIZE) {
+      fillPool();
+    }
+    result += customValues[pool[poolOffset++] % limit];
+  }
+
+  return result;
+}
+
+// Presets
+idchunk.numbers = (length = 10) => idchunk(length, "0123456789");
+idchunk.hex = (length = 10) => idchunk(length, "0123456789abcdef");
+idchunk.lowercase = (length = 10) => idchunk(length, "abcdefghijklmnopqrstuvwxyz");
+idchunk.uppercase = (length = 10) => idchunk(length, "ABCDEFGHIJKLMNOPQRSTUVWXYZ");
+
+module.exports = idchunk;