@endgame45/nodescript 1.1.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 horizonstudios
+
+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

@@ -0,0 +1,85 @@
+# nodescript
+
+Node.js logging and scheduling utility with easy chalk styling.
+
+Features
+- Simple styled logging: nsc.log, nsc.info, nsc.warn, nsc.error, nsc.debug
+- Namespaced loggers: nsc.create(namespace, opts)
+- Auto color detection (respects NO_COLOR and TTY)
+- Timestamping (ISO/local/custom)
+- Color parsing: hex, rgb/rgba, hsl/hsla, CSS keywords (alpha blended)
+- Themes and tagged-template styling
+- Flow control utilities: debounce, throttle, retry/backoff, pLimit
+- Looping helpers with concurrency
+
+Installation
+
+npm install nodescript
+
+Quick examples
+
+Basic logging
+
+```javascript
+const nsc = require('nodescript');
+nsc.info('Hello %s', 'world');
+nsc.warn('This is a warning');
+nsc.error('Oops: %s', 'failure');
+
+// change global level
+nsc.level = 'debug';
+```
+
+Namespaced logger
+
+```javascript
+const db = nsc.create('db', { textColor: 'cyan', level: 'debug', timestamp: { enabled: true } });
+db.debug('Connected to %s', 'postgres://...');
+```
+
+Themes
+
+```javascript
+nsc.registerTheme('errorTheme', { textColor: '#ff4444', font: 'bold', level: 'error' });
+const err = nsc.useTheme('errorTheme');
+err.error('Fatal: %s', 'something broke');
+```
+
+Tagged template styling
+
+```javascript
+const name = 'Alice';
+console.log(nsc.style`Hello, ${name}!`);
+nsc.tagLog`Processed ${42} items for ${() => name}`;
+```
+
+Looping and concurrency
+
+```javascript
+// run task 50 times with up to 5 concurrent executions
+await nsc.loop.duration('200ms').call(asyncTask).concurrency(5).times(50);
+
+// start infinite loop with 2 workers
+const ctl = nsc.loop.duration('1s').call(task).concurrency(2).start();
+// stop
+ctl.stop();
+await ctl.done;
+```
+
+Utilities
+
+```javascript
+const deb = nsc.debounce(() => console.log('debounced'), 200);
+deb();
+
+const safe = await nsc.retry(async () => fetchSomething(), { retries: 5 });
+await safe();
+
+const limit = nsc.pLimit(3);
+const limited = limit(async (id) => fetch(id));
+await Promise.all(ids.map(id => limited(id)));
+```
+
+License
+
+MIT — see LICENSE file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endgame45/nodescript",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "main": "src/nodescript.js",
   "files": [
     "src"

package/src/nodescript.js

@@ -1,5 +1,6 @@
 const util = require('util');
 const chalk = require('chalk');
+const utils = require('./utils');
 
 const SUPPORTED_FONTS = new Set([
     'bold', 'dim', 'italic', 'underline', 'inverse', 'hidden', 'strikethrough'
@@ -161,6 +162,7 @@ class LoopBuilder {
         this.fn = null;
         this.fnArgs = [];
         this._stopped = false;
+        this.concurrency = 1;
     }
 
     // set duration (accepts same inputs as parseDuration)
@@ -170,6 +172,12 @@ class LoopBuilder {
     }
     every(d) { return this.duration(d); }
 
+    // set concurrency for parallel execution (for times/start)
+    concurrency(n) {
+        this.concurrency = Math.max(1, Math.floor(Number(n) || 1));
+        return this;
+    }
+
     // set target function to call; fn can be sync or async
     call(fn, ...args) {
         if (typeof fn !== 'function') {
@@ -196,12 +204,41 @@ class LoopBuilder {
         if (!Number.isFinite(n) || n < 0) throw new TypeError('times(n) expects a non-negative number');
 
         this._stopped = false;
-        for (let i = 0; i < n; i++) {
-            if (this._stopped) break;
-            const res = this.fn(...this.fnArgs);
-            if (res && typeof res.then === 'function') await res;
-            if (i < n - 1 && this.durationMs > 0) await sleep(this.durationMs);
+        if (!this.concurrency || this.concurrency <= 1) {
+            for (let i = 0; i < n; i++) {
+                if (this._stopped) break;
+                const res = this.fn(...this.fnArgs);
+                if (res && typeof res.then === 'function') await res;
+                if (i < n - 1 && this.durationMs > 0) await sleep(this.durationMs);
+            }
+            return this;
         }
+
+        // concurrency > 1: launch up to concurrency parallel runners
+        let launched = 0;
+        const errors = [];
+
+        const runner = async () => {
+            while (!this._stopped) {
+                const idx = launched++;
+                if (idx >= n) break;
+                try {
+                    const res = this.fn(...this.fnArgs);
+                    if (res && typeof res.then === 'function') await res;
+                } catch (err) {
+                    errors.push(err);
+                    this._stopped = true;
+                    break;
+                }
+                if (this.durationMs > 0 && launched < n) await sleep(this.durationMs);
+            }
+        };
+
+        const runners = [];
+        const concurrency = Math.min(this.concurrency, n);
+        for (let i = 0; i < concurrency; i++) runners.push(runner());
+        await Promise.all(runners);
+        if (errors.length) throw errors[0];
         return this;
     }
 
@@ -249,9 +286,10 @@ class LoopBuilder {
     start() {
         if (!this.fn) throw new Error('No function set. Use .call(fn) before .start()');
         this._stopped = false;
-        const done = (async () => {
-            try {
-                // run forever until stopped
+        const runners = [];
+        const concurrency = Math.max(1, this.concurrency || 1);
+        for (let i = 0; i < concurrency; i++) {
+            const p = (async () => {
                 while (!this._stopped) {
                     const res = this.fn(...this.fnArgs);
                     if (res && typeof res.then === 'function') await res;
@@ -259,14 +297,12 @@ class LoopBuilder {
                         await Promise.race([sleep(this.durationMs), new Promise(r => { this._stopResolve = r; })]);
                     }
                 }
-            } finally {
-                // noop
-            }
-        })();
-        return {
-            stop: () => this.stop(),
-            done
-        };
+            })();
+            runners.push(p);
+        }
+
+        const done = Promise.all(runners).then(() => undefined);
+        return { stop: () => this.stop(), done };
     }
 }
 
@@ -481,6 +517,12 @@ const nsc = {
         console.log(s);
     },
 
+    // utilities: debounce/throttle/retry/pLimit
+    debounce: utils.debounce,
+    throttle: utils.throttle,
+    retry: utils.retry,
+    pLimit: utils.pLimit,
+
     /**
      * Wait for the given duration and resolve the returned Promise.
      * - numeric values are treated as seconds

package/src/utils.js

@@ -0,0 +1,135 @@
+// Utility helpers: debounce, throttle, retry/backoff, pLimit
+'use strict';
+
+function debounce(fn, wait = 0, options = {}) {
+  let timer = null;
+  let lastArgs = null;
+  let lastThis = null;
+  let resolveFlush = null;
+
+  const debounced = function (...args) {
+    lastArgs = args;
+    lastThis = this;
+    if (timer) clearTimeout(timer);
+    if (options.leading && !timer) {
+      fn.apply(lastThis, lastArgs);
+    }
+    return new Promise((resolve) => {
+      resolveFlush = resolve;
+      timer = setTimeout(() => {
+        timer = null;
+        if (!options.leading) fn.apply(lastThis, lastArgs);
+        if (resolveFlush) {
+          resolveFlush();
+          resolveFlush = null;
+        }
+      }, wait);
+    });
+  };
+  debounced.cancel = () => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    lastArgs = null;
+    lastThis = null;
+    if (resolveFlush) { resolveFlush(); resolveFlush = null; }
+  };
+  debounced.flush = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+      if (!options.leading && lastArgs) fn.apply(lastThis, lastArgs);
+      if (resolveFlush) { resolveFlush(); resolveFlush = null; }
+    }
+  };
+  return debounced;
+}
+
+function throttle(fn, wait = 0, options = {}) {
+  let lastCall = 0;
+  let timer = null;
+  let lastArgs = null;
+  let lastThis = null;
+
+  const throttled = function (...args) {
+    const now = Date.now();
+    const remaining = wait - (now - lastCall);
+    lastArgs = args;
+    lastThis = this;
+    if (remaining <= 0 || remaining > wait) {
+      if (timer) { clearTimeout(timer); timer = null; }
+      lastCall = now;
+      fn.apply(lastThis, lastArgs);
+    } else if (!timer && options.trailing !== false) {
+      timer = setTimeout(() => {
+        lastCall = Date.now();
+        timer = null;
+        fn.apply(lastThis, lastArgs);
+      }, remaining);
+    }
+  };
+  throttled.cancel = () => { if (timer) clearTimeout(timer); timer = null; };
+  return throttled;
+}
+
+async function retry(fn, opts = {}) {
+  const retries = Number(opts.retries == null ? 3 : opts.retries);
+  const minDelay = Number(opts.minDelay == null ? 100 : opts.minDelay);
+  const maxDelay = Number(opts.maxDelay == null ? 1000 : opts.maxDelay);
+  const factor = Number(opts.factor == null ? 2 : opts.factor);
+  const jitter = opts.jitter !== false;
+
+  let attempt = 0;
+  const exec = async (...args) => {
+    let lastErr;
+    while (attempt <= retries) {
+      try {
+        return await fn(...args);
+      } catch (err) {
+        lastErr = err;
+        if (attempt === retries) break;
+        attempt += 1;
+        let delay = Math.min(maxDelay, minDelay * Math.pow(factor, attempt - 1));
+        if (jitter) delay = Math.random() * delay;
+        await new Promise(r => setTimeout(r, delay));
+      }
+    }
+    throw lastErr;
+  };
+  return exec;
+}
+
+function pLimit(concurrency = 1) {
+  const queue = [];
+  let activeCount = 0;
+
+  const next = () => {
+    if (queue.length === 0) return;
+    if (activeCount >= concurrency) return;
+    activeCount += 1;
+    const item = queue.shift();
+    const { fn, resolve, reject } = item;
+    (async () => {
+      try {
+        const result = await fn();
+        resolve(result);
+      } catch (e) {
+        reject(e);
+      } finally {
+        activeCount -= 1;
+        next();
+      }
+    })();
+  };
+
+  return (fn) => (...args) => new Promise((resolve, reject) => {
+    queue.push({ fn: () => fn(...args), resolve, reject });
+    next();
+  });
+}
+
+module.exports = {
+  debounce,
+  throttle,
+  retry,
+  pLimit
+};