@endgame45/nodescript 1.1.0 → 1.4.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,95 @@
+# nodescript
+
+Lightweight Node.js logging, styling and scheduling helpers.
+
+Features
+- Styled logging with sensible level colors: nsc.log / nsc.info / nsc.warn / nsc.error / nsc.debug
+- Namespaced instances: nsc.create(namespace, opts)
+- Auto color detection (respects NO_COLOR and TTY)
+- Timestamping (ISO, local, or custom formatter)
+- Color parsing: hex, rgb/rgba, hsl/hsla, CSS keywords (alpha blended)
+- Theme presets and tagged-template styling
+- Flow-control utilities: debounce, throttle, retry/backoff, pLimit
+- Loop helpers with concurrency and scheduling
+- Simple file sink (rotating by size) and writable stream support
+- TypeScript declarations included
+
+Installation
+
+npm install nodescript
+
+Quick start
+
+```javascript
+const nsc = require('nodescript');
+
+// basic
+nsc.info('Hello %s', 'world');
+nsc.warn('Low disk space: %d%%', 12);
+
+// change global level
+nsc.level = 'debug';
+
+// namespaced logger
+const db = nsc.create('db', { textColor: 'cyan', level: 'debug', timestamp: { enabled: true } });
+db.debug('Connected to %s', 'postgres://...');
+
+// themes
+nsc.registerTheme('errorTheme', { textColor: '#ff4444', font: 'bold', level: 'error' });
+const err = nsc.useTheme('errorTheme');
+err.error('Fatal: %s', 'something broke');
+
+// tagged-template
+const name = 'Alice';
+console.log(nsc.style`Hello, ${name}!`);
+// or log via tag
+nsc.tagLog`Processed ${42} items for ${() => name}`;
+
+// fluent style shortcuts
+console.log(nsc.red.bold('Important: %s', 'value'));
+nsc.red.bold.log('Important message');
+
+// file sink
+const sink = nsc.logToFile('./logs/app.log', { maxBytes: 5 * 1024 * 1024 });
+nsc.outStream = sink; // attach sink to instance
+nsc.info('This goes to the log file');
+
+// utilities
+const deb = nsc.debounce(() => console.log('debounced'), 200);
+deb();
+
+const limited = nsc.pLimit(3);
+// concurrency-controlled calls: limited(fn)(...)
+
+// loops with concurrency
+await nsc.loop.duration('200ms').call(asyncTask).concurrency(5).times(50);
+
+// start/stop controller
+const ctl = nsc.loop.duration('1s').call(task).concurrency(2).start();
+ctl.stop();
+await ctl.done;
+```
+
+API summary
+
+- nsc.create(namespace, opts) -> namespaced instance
+- nsc.info/warn/error/debug(...args)
+- nsc.level = 'error'|'warn'|'info'|'debug'
+- nsc.timestamp = { enabled: boolean, format: 'iso'|'local'|fn }
+- nsc.registerTheme(name, opts) / nsc.useTheme(name) / nsc.applyTheme(name)
+- nsc.style`...` and nsc.tagLog`...` (tagged templates)
+- nsc.red/.green/.blue etc. fluent proxies with .bold/.underline chaining
+- Utilities: nsc.debounce, nsc.throttle, nsc.retry, nsc.pLimit
+- nsc.logToFile(path, { maxBytes }) -> sink with write/close
+
+TypeScript
+
+Types are included at types/nsc.d.ts. Import with:
+
+```ts
+import nsc = require('nodescript');
+```
+
+License
+
+MIT — see LICENSE

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@endgame45/nodescript",
-  "version": "1.1.0",
+  "version": "1.4.0",
   "main": "src/nodescript.js",
+  "types": "types/nsc.d.ts",
   "files": [
     "src"
   ],
@@ -29,5 +30,5 @@
     "url": "https://github.com/horizon-std/nodescript"
   },
   "bugs": "https://github.com/horizon-std/nodescript/issues",
-  "readme": ""
+  "readme": "README.md"
 }

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'
@@ -97,6 +98,53 @@ function buildStyler(config) {
     return styler;
 }
 
+// Fluent style proxy helper: returns a callable that produces styled strings
+function makeStyleProxy(baseConfig = {}) {
+    const factory = function (...args) {
+        // when called, format like util.format and return styled string
+        const txt = util.format(...args);
+        const styler = buildStyler(baseConfig);
+        return styler(txt);
+    };
+
+    const handler = {
+        get(_, prop) {
+            const p = String(prop);
+            // allow access to .log/.info/.warn/.error which will print using the styled text
+            if (p === 'log') return (...a) => { console.log(factory(...a)); };
+            if (p === 'info') return (...a) => { console.log(factory(...a)); };
+            if (p === 'warn') return (...a) => { console.warn(factory(...a)); };
+            if (p === 'error') return (...a) => { console.error(factory(...a)); };
+            if (SUPPORTED_FONTS.has(p)) {
+                // return new proxy with font added
+                const next = Object.assign({}, baseConfig);
+                next.font = next.font ? (next.font + ' ' + p) : p;
+                return makeStyleProxy(next);
+            }
+            // treat other props as colors (e.g., .red)
+            const next = Object.assign({}, baseConfig);
+            next.textColor = p;
+            return makeStyleProxy(next);
+        }
+    };
+
+    return new Proxy(factory, handler);
+}
+
+// Create a style object from config that supports .log/.info chaining
+function styleConfig(config = {}) {
+    const inst = Object.create(nsc);
+    if (config.textColor) inst.textColor = config.textColor;
+    if (config.bgColor) inst.bgColor = config.bgColor;
+    if (config.font) inst.font = config.font;
+    // bind convenience
+    inst.log = inst.log.bind(inst);
+    inst.info = inst.info.bind(inst);
+    inst.warn = inst.warn.bind(inst);
+    inst.error = inst.error.bind(inst);
+    return inst;
+}
+
 /**
  * Parse duration input into milliseconds.
  * Supported inputs:
@@ -161,6 +209,7 @@ class LoopBuilder {
         this.fn = null;
         this.fnArgs = [];
         this._stopped = false;
+        this.concurrency = 1;
     }
 
     // set duration (accepts same inputs as parseDuration)
@@ -170,6 +219,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 +251,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 +333,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 +344,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 };
     }
 }
 
@@ -362,7 +445,12 @@ const nsc = {
             });
         }
         const out = styler(text);
-        console.log(out);
+        // if an outStream is configured on this instance, write to it; otherwise use console
+        if (this.outStream && typeof this.outStream.write === 'function') {
+            this.outStream.write(String(out) + (this.outStream._autoNewline === false ? '' : '\n'));
+        } else {
+            console.log(out);
+        }
     },
 
     // low-level logging method used by level helpers
@@ -481,6 +569,62 @@ const nsc = {
         console.log(s);
     },
 
+    // file sink: simple rotating file writer
+    logToFile(filename, opts = {}) {
+        const fs = require('fs');
+        const maxBytes = Number(opts.maxBytes || 0);
+        // create write stream
+        let stream = fs.createWriteStream(filename, { flags: 'a', encoding: 'utf8' });
+
+        const rotate = () => {
+            try {
+                stream.end();
+            } catch (e) {
+                // ignore errors when closing stream
+            }
+            const backup = filename + '.' + Date.now();
+            try {
+                fs.renameSync(filename, backup);
+            } catch (e) {
+                // ignore rotation errors
+            }
+            stream = fs.createWriteStream(filename, { flags: 'a', encoding: 'utf8' });
+        };
+
+        const writer = (text) => {
+            if (maxBytes > 0) {
+                try {
+                    const st = fs.existsSync(filename) ? fs.statSync(filename) : null;
+                    if (st && st.size >= maxBytes) rotate();
+                } catch (e) {
+                    // ignore stat errors
+                }
+            }
+            stream.write(String(text) + '\n');
+        };
+
+        // return a simple sink object and attach to this instance if desired
+        return { write: writer, close: () => stream.end() };
+    },
+
+    // utilities: debounce/throttle/retry/pLimit
+    debounce: utils.debounce,
+    throttle: utils.throttle,
+    retry: utils.retry,
+    pLimit: utils.pLimit,
+    // Fluent style factory and color shortcuts
+    styleConfig,
+    // common color shortcuts (red, green, blue, yellow, cyan, magenta, white, gray, black)
+    red: makeStyleProxy({ textColor: 'red' }),
+    green: makeStyleProxy({ textColor: 'green' }),
+    blue: makeStyleProxy({ textColor: 'blue' }),
+    yellow: makeStyleProxy({ textColor: 'yellow' }),
+    cyan: makeStyleProxy({ textColor: 'cyan' }),
+    magenta: makeStyleProxy({ textColor: 'magenta' }),
+    white: makeStyleProxy({ textColor: 'white' }),
+    gray: makeStyleProxy({ textColor: 'gray' }),
+    black: makeStyleProxy({ textColor: 'black' }),
+
     /**
      * 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
+};