qznt 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 # qznt
 
-**qznt** (pronounced as in _ex-quisite_) is a strictly-typed, high-performant utility toolkit for modern TypeScript/Javascript and Node.js environments.
+**qznt** (pronounced as in _ex-quisite_) is a lightweight, typed, high-performant utility toolkit for modern TypeScript/JavaScript and Node.js environments.
 
 ## 🚀 Installation
 
@@ -23,20 +23,21 @@ import { $ } from "qznt";
 // or
 import { obj, Loop, date } from "qznt";
 
-// Deep object access (defaults to "dark" if mode is undefined)
+// Nested object access (defaults to "dark" if mode is undefined)
 const theme = qznt.obj.get(settings, "ui.theme.mode", "dark");
 
-// Human-readable durations
-const timeRemaining = $.date.duration(Date.now() + 5000); // "5 seconds"
+// Readable durations
+const time = $.date.duration(Date.now() + 5000); // "in 5 seconds"
 ```
 
 ## 📦 Namespaces
 
-- **`qznt.arr` (Lists)**: Advanced `chunk`, `cluster`, `shuffle`, `unique`, and `seqMap`
+- **`qznt.arr` (Arrays)**: Advanced `chunk`, `cluster`, `shuffle`, `unique`, and `seqMap`
 - **`qznt.async` (Promises)**: `retry` logic with exponential backoff and delay
 - **`qznt.date` (Time)**: Shorthand parsing (`"1h 30m"`), `duration` (digital/hms), and `eta`
 - **`qznt.fn` (Functions)**: `memoize` with TTL and custom resolvers
 - **`qznt.format` (Strings)**: `currency`, `memory` (bytes), `ordinal`, and `compactNumber`
+- **`qznt.fs` (File System)**: Efficient recursive directory scanning with `readDir`
 - **`qznt.is` (Predicates)**: Type guards: `is.today`, `is.empty`, `is.object`, and `is.sorted`
 - **`qznt.math` (Calculations)**: `lerp`, `invLerp`, `remap`, `percent`, and `sum`
 - **`qznt.num` (Numbers)**: Essential logic like `clamp` and range handling
@@ -45,11 +46,13 @@ const timeRemaining = $.date.duration(Date.now() + 5000); // "5 seconds"
 - **`qznt.timing` (Execution)**: `debounce`, `throttle`, and promise-based `wait`
 - **`qznt.to` (Transformations)**: Powerful data mappers like `to.record`
 
+_These are just the highlights, there's more inside._
+
 ## ✨ Featured Utilities
 
 ### The Smart `Loop`
 
-The `qznt.Loop` ensures asynchronous tasks never overlap. It waits for execution to finish before scheduling the next interval and supports precise pausing/resuming based on remaining time.
+`qznt.Loop` ensures async tasks never overlap. It waits for execution to finish before scheduling the next interval, and supports precise pausing/resuming. _This is usually more efficient than `node-cron` for tasks that don't need scheduling._
 
 ```ts
 import qznt from "qznt";
@@ -69,8 +72,8 @@ heartbeat.resume(); // Resumes with the exact remaining delay
 
 `qznt` provides high-performant data persistence and memory management.
 
-- `qznt.Cache`: An in-memory TTL cache with Sampled Passive/Active Eviction. It automatically cleans up expired entries to prevent memory leaks without blocking the event loop.
-- `qznt.Storage`: A universal persistence layer. It automatically uses `localStorage` in the browser and falls back to a local JSON file in Node.js environments.
+- `qznt.Cache`: An in-memory TTL cache with Sampled Passive/Active Eviction. It automatically purges expired entries to prevent memory leaks without blocking the event loop.
+- `qznt.Storage`: A persistent cache. It automatically uses `localStorage` in browsers and falls back to local JSON files in Node.js environments. Think a mini, smart-Redis cache.
 
 ```ts
 // Cache with a 1-minute global TTL
@@ -84,7 +87,7 @@ settings.set("theme", "dark");
 
 ### Seedable Randomness
 
-Every random utility in `qznt` accepts an optional seed. This allows you to generate predictable random data for testing, games, or procedural generation.
+Every random utility in `qznt.rnd` accepts an optional seed. This allows you to generate predictable random data for testing, games, or procedural generation.
 
 ```ts
 // Always returns the same item for seed 12345
@@ -93,7 +96,7 @@ const item = qznt.rnd.choice(["Sword", "Shield", "Potion"], 12345);
 
 ### Object Merging
 
-A deep, recursive merge that maintains TypeScript's type safety across multiple sources.
+A deep, recursive merge that maintains type safety across multiple sources.
 
 ```ts
 const config = qznt.obj.merge(defaultConfig, userConfig, envOverrides);
@@ -101,7 +104,7 @@ const config = qznt.obj.merge(defaultConfig, userConfig, envOverrides);
 
 ### Type Guards
 
-The `is` namespace provides predicates that act as TypeScript type guards, ensuring safety across your application.
+The `qznt.is` namespace provides predicates that act as type guards, ensuring type safety across your app.
 
 ```ts
 if (qznt.is.today(user.lastLogin)) {
@@ -115,7 +118,7 @@ if (qznt.is.empty(results)) {
 
 ### Type-Safe Transformations
 
-The `to` and `arr` namespaces provide _exquisite_ ways to transform data structures while maintaining total type safety.
+The `qznt.to` and `qznt.arr` namespaces also provide _✨ exquisite ✨_ ways to transform data structures while maintaining type safety.
 
 ```ts
 const userRecord = qznt.to.record(usersArray, u => ({

package/dist/index.cjs

@@ -41,6 +41,7 @@ __export(index_exports, {
   default: () => index_default,
   fn: () => fn,
   format: () => format,
+  fs: () => fs,
   is: () => is,
   math: () => math,
   obj: () => obj,
@@ -71,9 +72,19 @@ function chance(percent2 = 0.5, seed) {
   const random = seed !== void 0 ? prng(seed) : Math.random;
   return random() < percent2;
 }
-function choice(array, seed) {
+function choice(array, options = {}) {
+  const { seed, not, maxRerolls = 10 } = options;
   const random = seed !== void 0 ? prng(seed) : Math.random;
-  return array[Math.floor(random() * array.length)];
+  const rnd2 = () => array[Math.floor(random() * array.length)];
+  let result = rnd2();
+  if (seed !== void 0 && array.length > 1) {
+    let rerolls = 0;
+    while (not !== void 0 && result === not && rerolls < maxRerolls) {
+      result = rnd2();
+      rerolls++;
+    }
+  }
+  return result;
 }
 function weighted(array, selector, seed) {
   const random = seed !== void 0 ? prng(seed) : Math.random;
@@ -85,9 +96,9 @@ function weighted(array, selector, seed) {
     cumulativeWeights.push(currentSum);
   }
   const decider = random() * currentSum;
-  let index2 = cumulativeWeights.findIndex((w) => w >= decider);
+  let index2;
   if (array.length < 20) {
-    cumulativeWeights.findIndex((w) => w >= decider);
+    index2 = cumulativeWeights.findIndex((w) => w >= decider);
   } else {
     let low = 0;
     let high = cumulativeWeights.length - 1;
@@ -148,9 +159,19 @@ function float(min, max, seed) {
   const random = seed !== void 0 ? prng(seed) : Math.random;
   return random() * (max - min) + min;
 }
-function index(array, seed) {
+function index(array, options = {}) {
+  const { seed, not, maxRerolls = 10 } = options;
   const random = seed !== void 0 ? prng(seed) : Math.random;
-  return Math.floor(random() * array.length);
+  const rnd2 = () => Math.floor(random() * array.length);
+  let result = rnd2();
+  if (seed !== void 0 && array.length > 1) {
+    let rerolls = 0;
+    while (not !== void 0 && result === not && rerolls < maxRerolls) {
+      result = rnd2();
+      rerolls++;
+    }
+  }
+  return result;
 }
 function int(min, max, seed) {
   const random = seed !== void 0 ? prng(seed) : Math.random;
@@ -510,6 +531,41 @@ var format = {
   compactNumber
 };
 
+// src/fs.ts
+var fs_exports = {};
+__export(fs_exports, {
+  fs: () => fs
+});
+var import_node_fs = __toESM(require("fs"));
+var import_node_path = require("path");
+function readDir(path2, options = {}) {
+  const { recursive = true } = options;
+  if (!import_node_fs.default.existsSync(path2)) return [];
+  if (!recursive) {
+    return import_node_fs.default.readdirSync(path2).filter((fn2) => {
+      return import_node_fs.default.statSync((0, import_node_path.join)(path2, fn2)).isFile();
+    });
+  }
+  const walk = (dir, base = "") => {
+    const results = [];
+    const entries = import_node_fs.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const relativePath = base ? (0, import_node_path.join)(base, entry.name) : entry.name;
+      const fullPath = (0, import_node_path.join)(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...walk(fullPath, relativePath));
+      } else if (entry.isFile()) {
+        results.push(relativePath);
+      }
+    }
+    return results;
+  };
+  return walk(path2);
+}
+var fs = {
+  readDir
+};
+
 // src/is.ts
 var is_exports = {};
 __export(is_exports, {
@@ -590,10 +646,12 @@ function remap(value, inMin, inMax, outMin, outMax) {
 function secs(num) {
   return Math.floor(num / 1e3);
 }
-function sum(array, selector, ignoreNaN) {
-  return array.map(selector).reduce((a, b) => {
-    const invalid = isNaN(b) && !ignoreNaN;
-    if (invalid) throw new TypeError(`sum: '${b}' is not a valid number.`);
+function sum(array, selector) {
+  const _array = selector ? array.map(selector) : array;
+  if (!_array.every((v) => typeof v === "number")) {
+    throw new TypeError(`sum: Array must only contain numbers.`);
+  }
+  return _array.reduce((a, b) => {
     return (isNaN(b) ? 0 : b) < 0 ? a - -b : a + (b || 0);
   }, 0);
 }
@@ -821,16 +879,16 @@ function Pipe(value, ...fns) {
 }
 
 // src/Storage.ts
-var import_node_fs = __toESM(require("fs"));
-var import_node_path = __toESM(require("path"));
+var import_node_fs2 = __toESM(require("fs"));
+var import_node_path2 = __toESM(require("path"));
 var Storage = class {
   isNode = typeof window === "undefined";
   filePath = null;
   memoryCache = /* @__PURE__ */ new Map();
   loadFromFile() {
-    if (this.filePath && import_node_fs.default.existsSync(this.filePath)) {
+    if (this.filePath && import_node_fs2.default.existsSync(this.filePath)) {
       try {
-        const data = JSON.parse(import_node_fs.default.readFileSync(this.filePath, "utf-8"));
+        const data = JSON.parse(import_node_fs2.default.readFileSync(this.filePath, "utf-8"));
         Object.entries(data).forEach(([k, v]) => this.memoryCache.set(k, JSON.stringify(v)));
       } catch (err) {
         console.error(`Store: Failed to load file '${this.filePath}'`, err);
@@ -841,7 +899,7 @@ var Storage = class {
     if (this.isNode && this.filePath) {
       const out = {};
       this.memoryCache.forEach((v, k) => out[k] = JSON.parse(v));
-      import_node_fs.default.writeFileSync(this.filePath, JSON.stringify(out, null, 2));
+      import_node_fs2.default.writeFileSync(this.filePath, JSON.stringify(out, null, 2));
     }
   }
   /**
@@ -852,7 +910,7 @@ var Storage = class {
    */
   constructor(fileName, directory = process.cwd()) {
     if (this.isNode && fileName) {
-      this.filePath = import_node_path.default.join(directory, fileName.endsWith(".json") ? fileName : `${fileName}.json`);
+      this.filePath = import_node_path2.default.join(directory, fileName.endsWith(".json") ? fileName : `${fileName}.json`);
       this.loadFromFile();
     }
   }
@@ -1059,6 +1117,7 @@ var qznt = {
   ...fn_exports,
   ...date_exports,
   ...format_exports,
+  ...fs_exports,
   ...is_exports,
   ...math_exports,
   ...obj_exports,
@@ -1085,6 +1144,7 @@ var index_default = qznt;
   date,
   fn,
   format,
+  fs,
   is,
   math,
   obj,