{"_id":"@blastomisty/wakerild","_rev":"1-cd501cd5e4039e3d9f42de61882f5967","name":"@blastomisty/wakerild","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.2":{"name":"@blastomisty/wakerild","version":"1.0.2","description":"A logging utility for nodejs projects!","main":"index.js","scripts":{"test":"jest","test_detail":"jest --verbose --coverage=true --coverageDirectory=.\\tests\\cov"},"repository":{"type":"git","url":"git+https://bitbucket.org/blastomisty/node_logger.git"},"author":{"name":"blastomisty"},"license":"ISC","bugs":{"url":"https://bitbucket.org/blastomisty/node_logger/issues"},"homepage":"https://bitbucket.org/blastomisty/node_logger#readme","devDependencies":{"jest":"^29.7.0"},"directories":{"test":"tests"},"dependencies":{"ansi-escapes":"^4.3.2","ansi-regex":"^5.0.1","ansi-styles":"^4.3.0","anymatch":"^3.1.3","argparse":"^1.0.10","babel-jest":"^29.7.0","babel-plugin-istanbul":"^6.1.1","babel-plugin-jest-hoist":"^29.6.3","babel-preset-current-node-syntax":"^1.0.1","babel-preset-jest":"^29.6.3","balanced-match":"^1.0.2","brace-expansion":"^1.1.11","braces":"^3.0.2","browserslist":"^4.22.3","bser":"^2.1.1","buffer-from":"^1.1.2","callsites":"^3.1.0","camelcase":"^5.3.1","caniuse-lite":"^1.0.30001580","chalk":"^4.1.2","char-regex":"^1.0.2","ci-info":"^3.9.0","cjs-module-lexer":"^1.2.3","cliui":"^8.0.1","co":"^4.6.0","collect-v8-coverage":"^1.0.2","color-convert":"^2.0.1","color-name":"^1.1.4","concat-map":"^0.0.1","convert-source-map":"^2.0.0","create-jest":"^29.7.0","cross-spawn":"^7.0.3","debug":"^4.3.4","dedent":"^1.5.1","deepmerge":"^4.3.1","detect-newline":"^3.1.0","diff-sequences":"^29.6.3","electron-to-chromium":"^1.4.648","emittery":"^0.13.1","emoji-regex":"^8.0.0","error-ex":"^1.3.2","escalade":"^3.1.1","escape-string-regexp":"^2.0.0","esprima":"^4.0.1","execa":"^5.1.1","exit":"^0.1.2","expect":"^29.7.0","fast-json-stable-stringify":"^2.1.0","fb-watchman":"^2.0.2","fill-range":"^7.0.1","find-up":"^4.1.0","fs.realpath":"^1.0.0","function-bind":"^1.1.2","gensync":"^1.0.0-beta.2","get-caller-file":"^2.0.5","get-package-type":"^0.1.0","get-stream":"^6.0.1","glob":"^7.2.3","globals":"^11.12.0","graceful-fs":"^4.2.11","has-flag":"^4.0.0","hasown":"^2.0.0","html-escaper":"^2.0.2","human-signals":"^2.1.0","import-local":"^3.1.0","imurmurhash":"^0.1.4","inflight":"^1.0.6","inherits":"^2.0.4","is-arrayish":"^0.2.1","is-core-module":"^2.13.1","is-fullwidth-code-point":"^3.0.0","is-generator-fn":"^2.1.0","is-number":"^7.0.0","is-stream":"^2.0.1","isexe":"^2.0.0","istanbul-lib-coverage":"^3.2.2","istanbul-lib-instrument":"^6.0.1","istanbul-lib-report":"^3.0.1","istanbul-lib-source-maps":"^4.0.1","istanbul-reports":"^3.1.6","jest-changed-files":"^29.7.0","jest-circus":"^29.7.0","jest-cli":"^29.7.0","jest-config":"^29.7.0","jest-diff":"^29.7.0","jest-docblock":"^29.7.0","jest-each":"^29.7.0","jest-environment-node":"^29.7.0","jest-get-type":"^29.6.3","jest-haste-map":"^29.7.0","jest-leak-detector":"^29.7.0","jest-matcher-utils":"^29.7.0","jest-message-util":"^29.7.0","jest-mock":"^29.7.0","jest-pnp-resolver":"^1.2.3","jest-regex-util":"^29.6.3","jest-resolve":"^29.7.0","jest-resolve-dependencies":"^29.7.0","jest-runner":"^29.7.0","jest-runtime":"^29.7.0","jest-snapshot":"^29.7.0","jest-util":"^29.7.0","jest-validate":"^29.7.0","jest-watcher":"^29.7.0","jest-worker":"^29.7.0","js-tokens":"^4.0.0","js-yaml":"^3.14.1","jsesc":"^2.5.2","json-parse-even-better-errors":"^2.3.1","json5":"^2.2.3","kleur":"^3.0.3","leven":"^3.1.0","lines-and-columns":"^1.2.4","locate-path":"^5.0.0","lru-cache":"^5.1.1","make-dir":"^4.0.0","makeerror":"^1.0.12","merge-stream":"^2.0.0","micromatch":"^4.0.5","mimic-fn":"^2.1.0","minimatch":"^3.1.2","ms":"^2.1.2","natural-compare":"^1.4.0","node-int64":"^0.4.0","node-releases":"^2.0.14","normalize-path":"^3.0.0","npm-run-path":"^4.0.1","once":"^1.4.0","onetime":"^5.1.2","p-limit":"^3.1.0","p-locate":"^4.1.0","p-try":"^2.2.0","parse-json":"^5.2.0","path-exists":"^4.0.0","path-is-absolute":"^1.0.1","path-key":"^3.1.1","path-parse":"^1.0.7","picocolors":"^1.0.0","picomatch":"^2.3.1","pirates":"^4.0.6","pkg-dir":"^4.2.0","pretty-format":"^29.7.0","prompts":"^2.4.2","pure-rand":"^6.0.4","react-is":"^18.2.0","require-directory":"^2.1.1","resolve":"^1.22.8","resolve-cwd":"^3.0.0","resolve-from":"^5.0.0","resolve.exports":"^2.0.2","semver":"^6.3.1","shebang-command":"^2.0.0","shebang-regex":"^3.0.0","signal-exit":"^3.0.7","sisteransi":"^1.0.5","slash":"^3.0.0","source-map":"^0.6.1","source-map-support":"^0.5.13","sprintf-js":"^1.0.3","stack-utils":"^2.0.6","string-length":"^4.0.2","string-width":"^4.2.3","strip-ansi":"^6.0.1","strip-bom":"^4.0.0","strip-final-newline":"^2.0.0","strip-json-comments":"^3.1.1","supports-color":"^7.2.0","supports-preserve-symlinks-flag":"^1.0.0","test-exclude":"^6.0.0","tmpl":"^1.0.5","to-fast-properties":"^2.0.0","to-regex-range":"^5.0.1","type-detect":"^4.0.8","type-fest":"^0.21.3","undici-types":"^5.26.5","update-browserslist-db":"^1.0.13","v8-to-istanbul":"^9.2.0","walker":"^1.0.8","which":"^2.0.2","wrap-ansi":"^7.0.0","wrappy":"^1.0.2","write-file-atomic":"^4.0.2","y18n":"^5.0.8","yallist":"^3.1.1","yargs":"^17.7.2","yargs-parser":"^21.1.1","yocto-queue":"^0.1.0"},"keywords":["logging"],"_id":"@blastomisty/wakerild@1.0.2","gitHead":"81ddfd5d8bc03c748eb61ac2c35d2b462262765d","_nodeVersion":"20.10.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-FTl4ucUXf4sP0aWanRNDXZSkSQlJotfErqW1Bb50hvKURkjBp8mYQRV7QfEo7LP+cnRDwKXFL0cwjxv2jA73Yw==","shasum":"0b11b6795e101d6b0ac10f2adc8b5f331659f8ff","tarball":"https://registry.npmjs.org/@blastomisty/wakerild/-/wakerild-1.0.2.tgz","fileCount":6,"unpackedSize":46914,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQD6ReNePnIBU1nXgyKLElU6Q+CSlqgdBYL6ltoe4NhQwQIgAjmJjV7rPg0pBy5xJXbNWro09ocLm5cCoJyym+sTKFA="}]},"_npmUser":{"name":"blastomisty","email":"blastomisty@gmail.com"},"maintainers":[{"name":"blastomisty","email":"blastomisty@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/wakerild_1.0.2_1710193631779_0.837171758000955"},"_hasShrinkwrap":false},"1.0.3":{"name":"@blastomisty/wakerild","version":"1.0.3","description":"A 0 dep logging utility for nodejs projects!","main":"index.js","scripts":{"test":"jest","test_detail":"jest --verbose --coverage=true --coverageDirectory=.\\tests\\cov","demo":"node logging_demo"},"repository":{"type":"git","url":"git+https://bitbucket.org/blastomisty/node_logger.git"},"author":{"name":"blastomisty"},"license":"ISC","bugs":{"url":"https://bitbucket.org/blastomisty/node_logger/issues"},"homepage":"https://bitbucket.org/blastomisty/node_logger#readme","directories":{"test":"tests"},"dependencies":{},"keywords":["logging"],"_id":"@blastomisty/wakerild@1.0.3","gitHead":"e454f079908edbedd54ce8e71d037647a79e9141","_nodeVersion":"20.10.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-2cPFoQ1znRJD6A76T8vuP+PdCDpwEVF45PSQex+VkpdlxSEfKFUCw7+4uB07yEFJ1tcnXSDeyR/RyQ7FLfVVYg==","shasum":"75adfe865bb298eaa45ab4527cb9792383440b50","tarball":"https://registry.npmjs.org/@blastomisty/wakerild/-/wakerild-1.0.3.tgz","fileCount":6,"unpackedSize":41619,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCICc6M56VMEaiB0Iq2QTC9vXwepscsxSFXKkmEutXbsgiAiEAkv45zGg7bZNpKOuofC0sNIj++wo9TJp7TqzWsHT71sg="}]},"_npmUser":{"name":"blastomisty","email":"blastomisty@gmail.com"},"maintainers":[{"name":"blastomisty","email":"blastomisty@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/wakerild_1.0.3_1710194317872_0.7368645299049816"},"_hasShrinkwrap":false}},"time":{"created":"2024-03-11T21:47:11.684Z","1.0.2":"2024-03-11T21:47:11.944Z","modified":"2024-03-11T21:58:38.659Z","1.0.3":"2024-03-11T21:58:38.022Z"},"maintainers":[{"name":"blastomisty","email":"blastomisty@gmail.com"}],"description":"A 0 dep logging utility for nodejs projects!","homepage":"https://bitbucket.org/blastomisty/node_logger#readme","keywords":["logging"],"repository":{"type":"git","url":"git+https://bitbucket.org/blastomisty/node_logger.git"},"author":{"name":"blastomisty"},"bugs":{"url":"https://bitbucket.org/blastomisty/node_logger/issues"},"license":"ISC","readme":"# wakerild\r\n> Middle English form of the Old English name *Wacerhild, derived from wacor meaning \"watchful, vigilant\" (cognate with Old High German wakkar) and hild meaning \"battle\". - [Behind the Name](https://www.behindthename.com/name/wakerild/submitted)\r\n\r\nThis is a utility for handling some useful logging stuff that keeps things really simple. Examples of this are having multiple loggers configured at different levels, file export, and custom log processing hooked into the logger.\r\n\r\n## running tests\r\nTests use Jest, if you have that on your system you can use `npm run test` to run unit tests and `npm run test_detail` to get verbose test & coverage report\r\n\r\n## demo file\r\nYou can run `npm run demo` to run the included `logging_demo.js` file to see what outputs look like out of the box.\r\n\r\n## usage\r\n```js\r\nconst logger = require('@blastomisty/wakerild') // ?\r\n\r\nlet ex_logger = new logger('example_logger')\r\n\r\nex_logger.setLogLevel(0) // debug/verbose\r\n    .setExportLogLevel(1) // log/info\r\n    .setExportLogFormat('json')\r\n\r\nex_logger.log('Hello World!')\r\n```\r\n## General Notes: Log Levels\r\n\r\nWakerild uses 4 logging levels that map evenly to JS console levels;\r\n* 0 - debug/verbose\r\n* 1 - log/info\r\n* 2 - warn\r\n* 3 - error\r\n\r\nAt the terminal logging level, these wrap JS console functions, and for file export/custom log processing, these are used to set filters. When you set a log level for Export or for a custom processor, you are setting the *lowest* level that it should be handling. For example, using the usage example above...\r\n```js\r\nconst logger = require('@blastomisty/wakerild')\r\n\r\nlet ex_logger = new logger('example_logger')\r\n\r\nex_logger.setLogLevel(0) // debug/verbose\r\n    .setExportLogLevel(1) // log/info\r\n    .setExportLogFormat('json')\r\n\r\nex_logger.log('Hello World!') // This would be both logged to the terminal and exported as a file\r\nex_logger.debug('Goodbye World!') // This would only be logged to the terminal\r\n```\r\n\r\n## General Notes: Log Files\r\nA decision was made to produce the following behavior;\r\n* A logger only saves log files in 1 directory using 1 format, when export is enabled on the logger\r\n* By default, a logger will save log files named after the date the log happened. You can set a property that allows you to use a \"Channel\" argument to prefix this file name (i.e. `ex_logger.log('Testing!', 'test))` would save to `test-YYYY-MM-DD.log`).\r\n\r\nIf you need a different behavior, you can implement a custom logging processor that handles it, that functionality was included for extraneous purposes like that.\r\n\r\n## General Notes: Actually Logging\r\nAll aliased logging functions have 3 arguments; `msg`, `channel`, and `withTrace`\r\n\r\n#### msg - string\r\nYour message! As long as it can become a string this should work for you.\r\n\r\n#### channel - string\r\nThis is an optional argument that allows you to logically separate logs within one logger; for instance you may want to log to an `initialization` channel while a database is starting up and otherwise just log transactions.\r\n\r\n#### withTrace - boolean\r\nIf true, it will send a stack trace with the message (for console logs) and will make a stack trace available to custom log processors. Decision was made not to dump stack traces into log files for sake of not upwards of tripling log file sizes.\r\n\r\n## Logger class methods\r\nAll of the following functions follow the Builder pattern, so you can string them together to build out your logger. These are also reserved in terms of logger alias names, so, sorry if you're torn up about not being able to use `logger.setConsoleLogLevel` as a logging function.\r\n\r\n### addLoggingFunction(name, level, alwaysTrace=false, fgColor=null, bgColor=null)\r\nCreate a new logging function. These will behave like the given logging functions, just allow for relatively unique aliases.\r\n\r\n```js\r\nex_logger.addLoggingFunction('scream', 1)\r\n\r\nex_logger.scream(\"hello world!\") \r\n```\r\n\r\n#### name - String, required\r\nThe name of this function, will be added to this logger directly. These must be unique from any Logger class method and any logger method that already exists. The utility comes with the following logging functions:\r\n```js\r\naddLoggingFunction('debug', 0, false, 'green') // logger.debug\r\naddLoggingFunction('log', 1, false, 'blue') // logger.log\r\naddLoggingFunction('info', 1, false, 'white') // logger.info\r\naddLoggingFunction('trace', 3, true, 'white') // logger.trace\r\naddLoggingFunction('warn', 2, false, 'black', 'yellow') // logger.warn\r\naddLoggingFunction('error', 3, true, 'white', 'red') // logger.error\r\n```\r\n\r\n#### level - number (0|1|2|3), required\r\nThe level that your function will use. See above for console wrapping behavior.\r\n\r\n#### alwaysTrace - boolean\r\nWhether or not this logging function should always send a stack trace\r\n\r\n#### fgColor - string ('red'|'green'|'blue'|'cyan'|'magenta'|'yellow'|'white'|'gray'|'black')\r\nThese map to terminal character sequences that color the logs in the terminal, these are not used in any other place. This sets the text color.\r\n\r\n#### bgColor - string ('red'|'green'|'blue'|'cyan'|'magenta'|'yellow'|'white'|'gray'|'black')\r\nThese map to terminal character sequences that color the logs in the terminal, these are not used in any other place. This sets the background/highlight color.\r\n\r\n### setConsoleLogLevel(newLevel)\r\nSet the lowest level of logs to display to the console.\r\n\r\n```js\r\nex_logger.setConsoleLogLevel(2)\r\n\r\nex_logger.debug(\"Hello?\") // Nothing will show up\r\nex_logger.log(\"Hello?\") // Nothing will show up\r\nex_logger.warn(\"Hello!\") // This will appear!\r\n```\r\n\r\n#### newLevel - number (0|1|2|3)\r\nSets the new level. If you set a level out of range, nothing will change.\r\n\r\n### exportToFile(state=true)\r\nBy default, the logger will not output log files. Using this function will make it start doing that (or stop, if you decide to)\r\n\r\n```js\r\nex_logger.exportToFile() // Logger will start exporting to a file\r\nex_logger.log('In a file')\r\nex_logger.exportToFile(false) // no more!\r\nex_logger.log('Not in a file')\r\n```\r\n\r\n#### state - boolean\r\nWhether or not to allow log files to be written.\r\n\r\n### exportLogUsesChannelAsFileName(state=true)\r\nUsing this function will change your Logger's behavior; Without using this, the default file name is `YYYY-MM-DD.<extension>`. When you use this, it will append a channel name to the front (i.e. `channelName-YYYY...`) if one is provided in the log function, otherwise it will use the default.\r\n\r\n```js\r\nex_logger.exportLogUsesChannelAsFileName()\r\nex_logger.log('In a prefixed file', 'somewhere-else')\r\nex_logger.log('In the default file')\r\n```\r\n\r\n#### state - boolean\r\nWhether or not to use the channel name as a file prefix\r\n\r\n### setExportLogLevel(newLevel)\r\nSet the lowest level of logs that are saved to a log file.\r\n\r\n```js\r\nex_logger.setExportLogLevel(2)\r\n\r\nex_logger.debug(\"Hello?\") // Nothing will save\r\nex_logger.log(\"Hello?\") // Nothing will save\r\nex_logger.warn(\"Hello!\") // This will save!\r\n```\r\n\r\n#### newLevel - number (0|1|2|3)\r\nSets the new level. If you set a level out of range, nothing will change.\r\n\r\n### setExportLogFileDirectory(path)\r\nSet the directory that this logger saves its log files to.\r\n\r\n```js\r\nex_logger.setExportLogFileDirectory( path.join(__dirname, 'logs') )\r\n```\r\n\r\n#### path - pathLike\r\nThe directory to save your files in. Note: If the directory does not exist, an error gets thrown.\r\n\r\n### setExportLogFormat(newFormat)\r\nSet the format to write your logs in from a pre-selected list. The log file will have a `.log` extension by default, this will determine the contents. You can change the extension with `setExportLogExtenstion()`\r\n\r\n```js\r\nex_logger.setExportLogFormat('csv') // Will now export logs in a csv format!\r\n```\r\n\r\n#### newFormat - string ('json'|'csv'|'tsv'|'psv'|'txt')\r\nThe new format, given one of the options. If you enter something that isn't one of the options, an error gets thrown.\r\n\r\n```\r\n# csv\r\ntimestamp,level,channel,message\r\n\"Mon, 11 Mar 2024 21:01:45 GMT\",WARN,csv_logger,\"There's a lot of potential with stuff like this!\"\r\n```\r\n\r\n```\r\n# psv\r\ntimestamp|level|channel|message\r\n\"Mon, 11 Mar 2024 21:01:45 GMT\"|WARN|psv_logger|\"There's a lot of potential with stuff like this!\"\r\n```\r\n\r\n```\r\n# tsv\r\ntimestamp\tlevel\tchannel\tmessage\r\n\"Mon, 11 Mar 2024 21:01:45 GMT\"\tWARN\ttsv_logger\t\"There's a lot of potential with stuff like this!\"\r\n```\r\n\r\n```\r\n# json\r\n{\"timestamp\":\"Mon, 11 Mar 2024 21:01:45 GMT\",\"level\":\"WARN\",\"channel\":\"json_logger\",\"message\":\"There's a lot of potential with stuff like this!\"}\r\n```\r\n\r\n```\r\n# txt\r\nWARN | Mon, 11 Mar 2024 21:01:45 GMT | From Logger Channel txt_logger | There's a lot of potential with stuff like this!\r\n```\r\n\r\n### setExportLogExtenstion(newExtension)\r\nThis function allows you to set a custom extension for your log files. This is limited to alphanumeric values.\r\n\r\n```js\r\nex_logger.setExportLogExtension('csv') // Will now write to <channel name->YYYY-MM-DD.csv\r\n```\r\n\r\n#### newExtension - string\r\nThe new extension! If you set it to an invalid one, nothing will change.\r\n\r\n### addCustomLogProcessor(name, fn, level=0)\r\nAdd a new custom log processor to your logger.\r\n\r\n```js\r\nex_logger.addCustomLogProcessor('sqlizer', (message, level, channel, time, trace) => {\r\n        db.run(`\r\n            INSERT INTO Logs (time, fromFunction, fromChannel, message, trace)\r\n            VALUES (\r\n                '${time.toUTCString()}',\r\n                '${level}',\r\n                '${channel}',\r\n                '${message}',\r\n                '${trace ? trace.join('|') : null}'\r\n            )\r\n        `)\r\n    })\r\n```\r\n\r\n#### name - string, required\r\nThe name of this log processor. If you neglect to add a name, an error will be thrown.\r\n\r\n#### fn - function(message, logFnName, channel, time, trace), required\r\nThis is the function that is doing the processing! The function must both be present and accept 5 arguments. If either of these is not the case, an error will be thrown.\r\n\r\n* **message** - This is the message that was logged.\r\n* **logFnName** - This is the alias of the function that was called to log the message (i.e. following `logger.log()`, logFnName would be 'log')\r\n* **channel** - The channel provided when the message was logged, if provided, else null\r\n* **time** - A datetime object that reflects the moment the message was logged.\r\n* **trace** - If the message was logged with `withTrace=true`, then this will be an array with the stack in it. Otherwise null\r\n\r\n#### level - number (0|1|2|3)\r\nThis is the level filter for this processor; By defualt, if this argument is either not provided or given an out of range value, it will be 0 (debug), and will process every log message. Setting it higher filters out lower order logs.\r\n\r\n### setCustomLogProcessorLevel(name, newLevel)\r\nSet a new level for a custom log processor, by name. If you provide either a name that doesn't exist as a log processor or you provide an out of range log level value, nothing will change.\r\n\r\n```js\r\nex_logger.setCustomLogProcessorLevelW('sqlizer', 2) // Now only warning level logs will be processed\r\n```\r\n\r\n#### name - string\r\nThe name of the custom log processor you want to modify\r\n\r\n#### newLevel - number (0|1|2|3)\r\nThe new log level","readmeFilename":"README.md"}