@endgame45/nodescript 1.2.0 → 1.4.0

package/README.md

@@ -1,85 +1,95 @@
 # nodescript
 
-Node.js logging and scheduling utility with easy chalk styling.
+Lightweight Node.js logging, styling and scheduling helpers.
 
 Features
-- Simple styled logging: nsc.log, nsc.info, nsc.warn, nsc.error, nsc.debug
-- Namespaced loggers: nsc.create(namespace, opts)
+- 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/custom)
+- Timestamping (ISO, local, or custom formatter)
 - 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
+- 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 examples
-
-Basic logging
+Quick start
 
 ```javascript
 const nsc = require('nodescript');
+
+// basic
 nsc.info('Hello %s', 'world');
-nsc.warn('This is a warning');
-nsc.error('Oops: %s', 'failure');
+nsc.warn('Low disk space: %d%%', 12);
 
 // change global level
 nsc.level = 'debug';
-```
 
-Namespaced logger
-
-```javascript
+// namespaced logger
 const db = nsc.create('db', { textColor: 'cyan', level: 'debug', timestamp: { enabled: true } });
 db.debug('Connected to %s', 'postgres://...');
-```
 
-Themes
-
-```javascript
+// themes
 nsc.registerTheme('errorTheme', { textColor: '#ff4444', font: 'bold', level: 'error' });
 const err = nsc.useTheme('errorTheme');
 err.error('Fatal: %s', 'something broke');
-```
 
-Tagged template styling
-
-```javascript
+// tagged-template
 const name = 'Alice';
 console.log(nsc.style`Hello, ${name}!`);
+// or log via tag
 nsc.tagLog`Processed ${42} items for ${() => name}`;
-```
 
-Looping and concurrency
+// fluent style shortcuts
+console.log(nsc.red.bold('Important: %s', 'value'));
+nsc.red.bold.log('Important message');
 
-```javascript
-// run task 50 times with up to 5 concurrent executions
+// 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 infinite loop with 2 workers
+// start/stop controller
 const ctl = nsc.loop.duration('1s').call(task).concurrency(2).start();
-// stop
 ctl.stop();
 await ctl.done;
 ```
 
-Utilities
+API summary
 
-```javascript
-const deb = nsc.debounce(() => console.log('debounced'), 200);
-deb();
+- 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
 
-const safe = await nsc.retry(async () => fetchSomething(), { retries: 5 });
-await safe();
+Types are included at types/nsc.d.ts. Import with:
 
-const limit = nsc.pLimit(3);
-const limited = limit(async (id) => fetch(id));
-await Promise.all(ids.map(id => limited(id)));
+```ts
+import nsc = require('nodescript');
 ```
 
 License
 
-MIT — see LICENSE file.
+MIT — see LICENSE

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@endgame45/nodescript",
-  "version": "1.2.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

@@ -98,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:
@@ -398,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
@@ -517,11 +569,61 @@ 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.