{"id":17540307,"url":"https://github.com/pabra/logger","last_synced_at":"2025-06-11T14:36:16.648Z","repository":{"id":41872451,"uuid":"274384947","full_name":"pabra/logger","owner":"pabra","description":"A small and simple but extendable logger for typescript/javascript in browser and Node.js.","archived":false,"fork":false,"pushed_at":"2024-05-08T15:13:48.000Z","size":783,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-23T22:33:40.590Z","etag":null,"topics":["browser","logger","logging","nodejs","syslog","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@pabra/logger","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pabra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-23T11:12:17.000Z","updated_at":"2024-12-06T22:00:26.000Z","dependencies_parsed_at":"2024-05-08T16:43:18.683Z","dependency_job_id":"8bd3051a-aefd-44b3-b776-c575c2c4c3a3","html_url":"https://github.com/pabra/logger","commit_stats":{"total_commits":103,"total_committers":5,"mean_commits":20.6,"dds":"0.30097087378640774","last_synced_commit":"bfc85564a2495697c7535b291a68ea1c53a9c322"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pabra%2Flogger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pabra%2Flogger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pabra%2Flogger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pabra%2Flogger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pabra","download_url":"https://codeload.github.com/pabra/logger/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pabra%2Flogger/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259280711,"owners_count":22833434,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","logger","logging","nodejs","syslog","typescript"],"created_at":"2024-10-20T22:09:04.350Z","updated_at":"2025-06-11T14:36:16.615Z","avatar_url":"https://github.com/pabra.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @pabra/logger\n\n[![npm version](https://img.shields.io/npm/v/%40pabra%2Flogger?label=version\u0026logo=npm)](https://www.npmjs.com/package/%40pabra%2Flogger)\n[![npm bundle size (scoped)](https://img.shields.io/bundlephobia/min/@pabra/logger?logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAACSUlEQVRYw%2B2XP2gTcRTH459BEKSiQkH8%2FcmlaUpJEESECpKh0IKiU2b%2FDNKxDkrp0rjZUXBSHERcBEEX7eRQhVKcBBfrIgriYDEoorVJzs%2FL%2FdpexbSXXq4g3MHjLne%2F3%2Ft%2B3vu9y%2B9dJhPjsNb2G5O9YUzBZLbrKJVKexG9qLV9aYz9zPW01mbRGPM0m82eqVarOxMRRuAEorc5f0X4CdGfrVQqu4Jn5T3cP8%2F9eew9UBO5XO5QbNF8Pn8QZ1eI8A3i78SxMYO9G83xPO8YMHcBqXF%2BwO%2BhjkQlhUwcwcHDwIm9R7SnOs%2FY0R6Ax5m%2FgL3mekyWb6OC0gy6TqQfsVcygTTui5tF3%2Fd3UBvDBPVIlg%2Fft7TuG1g3iBT7QSHZmwwuJlXALOlhCVKKVzRXimvKATSgewHA8aQAqIcjStnHaNVFU2DCAA7CNLEvwFzt1hIENSWFbBpKtTT8dgBhE5A6xDNbKcJisbhfKe8aPmqhwNZpbAawCqKUXnZZmYz4Gsob9NsJt%2FUdFSBsDef4OfPOlcvl3Wt%2FRN4FAN%2FyfOlf0XYLIGw%2FmVsLXivzg%2BtfnfqICxDbUoAUIAVIAVKAFoDriGrBBmKXkxalH5BmpEng3%2F5qy%2FQQe%2F%2Bs61bqUXe06Nba0ptBh913uu1%2BLr0%2BgyfJxqcuZKXhWj12Sn2%2F428F%2BsO86%2BGW1pxFj5Z0f6BBudyVhhKnl4BZ2CQrreVjfZ8JfCKdbaFQOKC1dweI70A1XXakqBYRnVr5XNuWA9FRQOaU6j%2BZ%2BV%2BPP5ZRWPOOMBtbAAAAAElFTkSuQmCC)](https://bundlephobia.com/package/%40pabra%2Flogger)\n[![Codecov](https://img.shields.io/codecov/c/github/pabra/logger/master?logo=codecov)](https://codecov.io/gh/pabra/logger)\n[![unit-tests](https://github.com/pabra/logger/actions/workflows/unit-tests.yml/badge.svg?branch=master)](https://github.com/pabra/logger/actions?query=branch%3Amaster+workflow%3Aunit-tests)\n[![npm-publish](https://github.com/pabra/logger/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/pabra/logger/actions?query=workflow%3Anpm-publish)\n\n## What\n\nA JavaScript/TypeScript logger that implements [Syslog severitiy levels](https://en.wikipedia.org/wiki/Syslog#Severity_level).\n\ngoals are:\n\n- be lightweight/small\n- can be used in browser and node.js\n- have as few as possible dependencies (currently just 1)\n- (almost) ready to use if you just want to use `console.log` and do not want to\n log debug messages in production\n- easily extendable\n- functional code and immutable data\n\nA [Logger](#logger) consists of 3 parts:\n\n- [Filter](#filter) (optional) - should a message be logged at all\n- [Formatter](#formatter) - how to format log entries\n- [Transporter](#transporter) - where to trasport log entries to\n\nThese are packed together into a [Handler](#handler).\n\n## Install\n\n```bash\nnpm install --save @pabra/logger\n# or\nyarn add @pabra/logger\n```\n\n## Getting Started\n\n### Just Log\n\nThis works in both, browser and node.js environments.\n\n```typescript\n// import\nimport getLogger from '@pabra/logger';\n\n// init and use root logger\nconst rootLogger = getLogger('myProject');\n\nrootLogger.info(\"I'm using a simple logger now!\");\n```\n\nResults in the following console output:\n\n```console\n2020-08-13T13:55:32.327Z [myProject] INFORMATIONAL - I'm using a simple logger now!\n```\n\n### Logging Data\n\nPass any additional data after the log message.\n\n```typescript\nrootLogger.warning(\n 'something unexpected happened',\n { some: ['data', true] },\n '23',\n 42,\n);\n```\n\nResults in the following console output:\n\n```console\n2020-09-06T07:29:05.356Z [myProject] WARNING - something unexpected happened { some: [ 'data', true ] } 23 42\n```\n\n### Child Logger\n\nCall `getLogger` on your rootLogger to get a child logger.\n\n```typescript\n// import\nimport getLogger from '@pabra/logger';\n\n// init root logger\nconst rootLogger = getLogger('myProject');\n\n// init and use child logger in your modules/components/etc.\nconst moduleLogger = rootLogger.getLogger('myModule');\nmoduleLogger.info('Logging from within a module!');\n```\n\nResults in the following console output:\n\n```console\n2020-09-06T07:39:08.677Z [myProject.myModule] INFORMATIONAL - Logging from within a module!\n```\n\n### Selectively Logging for Dev / Prod\n\nSet up a custom [Handler](#handler) to only show log messages starting at\n'warning' level in production:\n\n```typescript\nimport getLogger, { handlers } from '@pabra/logger';\n\nconst logLevel = process.env.NODE_ENV === 'development' ? undefined : 'warning';\nconst logHandler = handlers.getConsoleRawDataHandler(logLevel);\nconst rootLogger = getLogger('myProject', logHandler);\n// in some module\nconst moduleLogger = rootLogger.getLogger('myModule');\n```\n\nThen, any log messages that are lower than \"warning\" will be ignored.\n\n```typescript\nrootLogger.info(\"I'm using a simple logger now!\");\nmoduleLogger.notice(\"I'm using a simple module logger now!\");\nrootLogger.err('No such table in db.');\nmoduleLogger.warning('User entered invalid user name.');\n```\n\nWill only show messages eqal or higher than 'warning' level:\n\n```console\n2020-09-06T07:53:40.896Z [myProject] ERROR - No such table in db.\n2020-09-06T07:53:40.896Z [myProject.myModule] WARNING - User entered invalid user name.\n```\n\nYou should take care that `process.env.NODE_ENV` is properly set. This might\nalso differ if you use it in node.js or browser (there is no global `process` in\nthe browser - webpack\n[EnvironmentPlugin](https://webpack.js.org/plugins/environment-plugin/) might\nhelp with that).\n\n## Usage\n\n### Logger\n\n#### What is it\n\n```typescript\ntype Logger = {\n emerg: (message: string, ...data: any[]) =\u003e void;\n alert: (message: string, ...data: any[]) =\u003e void;\n crit: (message: string, ...data: any[]) =\u003e void;\n err: (message: string, ...data: any[]) =\u003e void;\n warning: (message: string, ...data: any[]) =\u003e void;\n notice: (message: string, ...data: any[]) =\u003e void;\n info: (message: string, ...data: any[]) =\u003e void;\n debug: (message: string, ...data: any[]) =\u003e void;\n getLogger: GetLogger;\n getHandlers: () =\u003e Handlers;\n};\n```\n\n#### How to get it\n\n```typescript\nimport getLogger from '@pabra/logger';\n\n// get a main/root logger\nconst mainLogger = getLogger(loggerName); // default handler will be used\n// or\nconst mainLogger = getLogger(loggerName, handler);\n// or\nconst mainLogger = getLogger(loggerName, handlers);\n\n// get a child/module logger\nconst moduleLogger = mainLogger.getLogger(loggerName); // parent's handlers will be used\n// or\nconst moduleLogger = mainLogger.getLogger(loggerName, handler);\n// or\nconst moduleLogger = mainLogger.getLogger(loggerName, handlers);\n```\n\n| object | type | required | description |\n| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | ------------------------------- |\n| `loggerName` | \u003cpre\u003estring\u003c/pre\u003e | yes | name of your logger |\n| `handler` | \u003cpre\u003etype\u0026nbsp;Handler\u0026nbsp;=\u0026nbsp;{\u003cbr\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;readonly\u0026nbsp;filter?:\u0026nbsp;Filter\u0026nbsp;\\|\u0026nbsp;undefined;\u003cbr\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;readonly\u0026nbsp;formatter:\u0026nbsp;Formatter;\u003cbr\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;readonly\u0026nbsp;transporter:\u0026nbsp;Transporter;\u003cbr\u003e}\u003c/pre\u003e | no | a single [`Handler`](#handler) |\n| `handlers` | \u003cpre\u003eHandler[]\u003c/pre\u003e | no | multiple [`Handler`](#handler)s |\n\n#### How to use it\n\n```typescript\nmoduleLogger.info(message, ...data);\n```\n\n| object | type | required | description |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | ------------------------------------- |\n| `moduleLogger` | \u003cpre\u003etype\u0026nbsp;Logger\u0026nbsp;=\u0026nbsp;{\u003cbr\u003e\u0026nbsp;\u0026nbsp;emerg:\u0026nbsp;(message:\u0026nbsp;string,\u0026nbsp;...data:\u0026nbsp;any[])\u0026nbsp;=\u003e\u0026nbsp;void;\u003cbr\u003e\u0026nbsp;\u0026nbsp;alert:\u0026nbsp;(message:\u0026nbsp;string,\u0026nbsp;...data:\u0026nbsp;any[])\u0026nbsp;=\u003e\u0026nbsp;void;\u003cbr\u003e\u0026nbsp;\u0026nbsp;crit:\u0026nbsp;(message:\u0026nbsp;string,\u0026nbsp;...data:\u0026nbsp;any[])\u0026nbsp;=\u003e\u0026nbsp;void;\u003cbr\u003e\u0026nbsp;\u0026nbsp;err:\u0026nbsp;(message:\u0026nbsp;string,\u0026nbsp;...data:\u0026nbsp;any[])\u0026nbsp;=\u003e\u0026nbsp;void;\u003cbr\u003e\u0026nbsp;\u0026nbsp;warning:\u0026nbsp;(message:\u0026nbsp;string,\u0026nbsp;...data:\u0026nbsp;any[])\u0026nbsp;=\u003e\u0026nbsp;void;\u003cbr\u003e\u0026nbsp;\u0026nbsp;notice:\u0026nbsp;(message:\u0026nbsp;string,\u0026nbsp;...data:\u0026nbsp;any[])\u0026nbsp;=\u003e\u0026nbsp;void;\u003cbr\u003e\u0026nbsp;\u0026nbsp;info:\u0026nbsp;(message:\u0026nbsp;string,\u0026nbsp;...data:\u0026nbsp;any[])\u0026nbsp;=\u003e\u0026nbsp;void;\u003cbr\u003e\u0026nbsp;\u0026nbsp;debug:\u0026nbsp;(message:\u0026nbsp;string,\u0026nbsp;...data:\u0026nbsp;any[])\u0026nbsp;=\u003e\u0026nbsp;void;\u003cbr\u003e\u0026nbsp;\u0026nbsp;getLogger:\u0026nbsp;GetLogger;\u003cbr\u003e\u0026nbsp;\u0026nbsp;getHandlers:\u0026nbsp;()\u0026nbsp;=\u003e\u0026nbsp;Handlers;\u003cbr\u003e};\u003c/pre\u003e | | the actual [`Logger`](#logger) Object |\n| `message` | \u003cpre\u003estring\u003c/pre\u003e | yes | a message to log |\n| `data` | \u003cpre\u003eany\u003c/pre\u003e | no | some kind of data to log |\n\nFor each call of a log function the [`Logger`](#logger) will pass the message\nand data to each of it's [`Handler`](#handler)s.\n\n### Handler\n\n#### What is it\n\n```typescript\ntype Handler = {\n readonly filter?: Filter;\n readonly formatter: Formatter;\n readonly transporter: Transporter;\n};\n```\n\nA [`Handler`](#handler) keeps all 3 parts together that are needed to handle a\nlog entry - hence the name. Whereas the filter is optional.\n\n#### How to get it\n\n```typescript\nimport { handlers, Handler } from '@pabra/logger';\n\nconst myHandler: Handler = handlers.getConsoleTextHandler(logLevelName);\nconst myHandler: Handler = handlers.getConsoleRawDataHandler(logLevelName);\nconst myHandler: Handler = handlers.getConsoleJsonHandler(logLevelName);\n```\n\n| object | type | required | description |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `handlers` | \u003cpre\u003e{\u003cbr\u003e\u0026nbsp;\u0026nbsp;getConsoleTextHandler,\u003cbr\u003e\u0026nbsp;\u0026nbsp;getConsoleRawDataHandler,\u003cbr\u003e\u0026nbsp;\u0026nbsp;getConsoleJsonHandler,\u003cbr\u003e}\u0026nbsp;as\u0026nbsp;const;\u003c/pre\u003e | | an object of common handlers |\n| `logLevelName` | \u003cpre\u003etype\u0026nbsp;LogLevelName\u0026nbsp;=\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'emerg'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'alert'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'crit'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'err'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'warning'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'notice'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'info'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'debug';\u003c/pre\u003e | no | The name of the maximal log level to handle (low log levels are more urgent than higher ones). If none is passed (or `undefined`) that Hanlder won't filter - means everything get's logged. |\n| `getConsoleRawDataHandler` | \u003cpre\u003e(\u003cbr\u003e\u0026nbsp;\u0026nbsp;level?:\u0026nbsp;LogLevelName\u0026nbsp;\\|\u0026nbsp;undefined,\u003cbr\u003e)\u0026nbsp;=\u003e\u0026nbsp;Handler\u003c/pre\u003e | | This is the default [`Handler`](#handler) if you don't pass one to `getLogger`. It mostly works like `console.log`. It doesn't has a [`Formatter`](#formatter) and just passes the raw data to console. |\n| `getConsoleTextHandler` | \u003cpre\u003e(\u003cbr\u003e\u0026nbsp;\u0026nbsp;level?:\u0026nbsp;LogLevelName\u0026nbsp;\\|\u0026nbsp;undefined,\u003cbr\u003e)\u0026nbsp;=\u003e\u0026nbsp;Handler\u003c/pre\u003e | | This [`Handler`](#handler) will be best for human readability. |\n| `getConsoleJsonHandler` | \u003cpre\u003e(\u003cbr\u003e\u0026nbsp;\u0026nbsp;level?:\u0026nbsp;LogLevelName\u0026nbsp;\\|\u0026nbsp;undefined,\u003cbr\u003e)\u0026nbsp;=\u003e\u0026nbsp;Handler\u003c/pre\u003e | | This [`Handler`](#handler) will be best for machine readability as it will be one big strigified JSON line. |\n\n#### How to make it\n\n```typescript\nimport { Handler } from '@pabra/logger';\n\nconst myHandler: Handler = {\n filter: myFilter,\n formatter: myFormatter,\n transporter: myTransporter,\n};\n```\n\n### Filter\n\n#### What is it\n\n```typescript\ntype Filter = (logger: InternalLogger, message: Message) =\u003e boolean;\ntype InternalLogger = {\n readonly name: string;\n readonly nameChain: string[];\n readonly handlers: Handler[];\n};\ninterface Message {\n readonly raw: string;\n readonly data: any[];\n readonly level:\n | 'emerg'\n | 'alert'\n | 'crit'\n | 'err'\n | 'warning'\n | 'notice'\n | 'info'\n | 'debug';\n}\n```\n\nThe [`Filter`](#filter) function decides if a log entry should be handled at\nall. If it returns `false` the log entry handling immediately ends for this\nhandler.\n\nIf there is no [`Filter`](#filter) provided in a [`Handler`](#handler), every\nlog entry gets handled. So no [`Filter`](#filter) behaves the same as a\n[`Filter`](#filter) that's always returning `true`.\n\n#### How to get it\n\n```typescript\nimport { filters, Filter } from '@pabra/logger';\n\nconst myFilter: Filter = filters.getMaxLevelFilter(logLevelName);\n```\n\n| object | type | required | description |\n| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `filters` | \u003cpre\u003e{\u0026nbsp;getMaxLevelFilter\u0026nbsp;}\u0026nbsp;as\u0026nbsp;const;\u003c/pre\u003e | | an object of common filters |\n| `logLevelName` | \u003cpre\u003etype\u0026nbsp;LogLevelName\u0026nbsp;=\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'emerg'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'alert'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'crit'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'err'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'warning'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'notice'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'info'\u003cbr\u003e\u0026nbsp;\u0026nbsp;\\|\u0026nbsp;'debug';\u003c/pre\u003e | yes | The name of the maximal log level to handle (low log levels are more urgent than higher ones). |\n| `getMaxLevelFilter` | \u003cpre\u003e(\u003cbr\u003e\u0026nbsp;\u0026nbsp;level:\u0026nbsp;LogLevelName,\u003cbr\u003e)\u0026nbsp;=\u003e\u0026nbsp;Filter\u003c/pre\u003e | | This Filter decides based on the severity of the log entry weather it should be logged/handled or not (low levels are more urgent - see [Syslog severitiy levels](https://en.wikipedia.org/wiki/Syslog#Severity_level)). |\n\n#### How to make it\n\nA [`Filter`](#filter) is a function that gets the `InternalLogger` object and\nthe `Message` object passed as arguments and needs to return a boolean.\n\nIf you want to have a [`Handler`](#handler) that should only handle `error` log\nentries, your [`Filter`](#filter) could look like this:\n\n```typescript\nimport { Filter } from '@pabra/logger';\n\nconst myFilter: Filter = (_logger, message) =\u003e message.level === 'err';\n\n// or if you only want to handle log entries from your \"auth\" module\nconst myFilter: Filter = (logger, _message) =\u003e logger.name === 'auth';\n```\n\n### Formatter\n\n#### What is it\n\n```typescript\ntype Formatter = (logger: InternalLogger, message: Message) =\u003e string;\ntype InternalLogger = {\n readonly name: string;\n readonly nameChain: string[];\n readonly handlers: Handler[];\n};\ninterface Message {\n readonly raw: string;\n readonly data: any[];\n readonly level:\n | 'emerg'\n | 'alert'\n | 'crit'\n | 'err'\n | 'warning'\n | 'notice'\n | 'info'\n | 'debug';\n}\n```\n\nThe [`Formatter`](#formatter) function produces the formatted message (`string`)\nthat finally appears in your log file/console/etc. It might add a time stamp and\nthan somehow join the severity level/name, logger name, raw log message and log\ndata into one string.\n\n#### How to get it\n\n```typescript\nimport { formatters, Formatter } from '@pabra/logger';\n\nconst myFormatter: Formatter = formatters.jsonFormatter;\nconst myFormatter: Formatter = formatters.textFormatter;\nconst myFormatter: Formatter = formatters.textWithoutDataFormatter;\nconst myFormatter: Formatter = formatters.getJsonLengthFormatter(maxLength);\nconst myFormatter: Formatter = formatters.getTextLengthFormatter(maxLength);\n```\n\n| object | type | required | description |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `formatters` | \u003cpre\u003e{\u003cbr\u003e\u0026nbsp;\u0026nbsp;textWithoutDataFormatter,\u003cbr\u003e\u0026nbsp;\u0026nbsp;textFormatter,\u003cbr\u003e\u0026nbsp;\u0026nbsp;jsonFormatter,\u003cbr\u003e\u0026nbsp;\u0026nbsp;getTextLengthFormatter,\u003cbr\u003e\u0026nbsp;\u0026nbsp;getJsonLengthFormatter,\u003cbr\u003e}\u0026nbsp;as\u0026nbsp;const;\u003c/pre\u003e | | an object of common formatters |\n| `maxLength` | \u003cpre\u003eundefined\u0026nbsp;\\|\u0026nbsp;number\u003c/pre\u003e | no | The maximum length of your formatted log message. If `undefined` or omitted the default is `1024^2` (1 MiB). It is there to prevent you from potentially sending huge data objects over the wire. \u003cbr\u003e**Notice:** if used with `jsonFormatter` the stringified data will end up truncated and not parseable anymore. |\n| `jsonFormatter` | \u003cpre\u003eFormatter\u003c/pre\u003e | | Will return untruncated, stringified JSON like this: \u003cpre\u003e{\u003cbr\u003e\u0026nbsp;\u0026nbsp;\"name\":\u0026nbsp;\"auth\",\u003cbr\u003e\u0026nbsp;\u0026nbsp;\"nameChain\":\u0026nbsp;[\"main\",\u0026nbsp;\"auth\"],\u003cbr\u003e\u0026nbsp;\u0026nbsp;\"time\":\u0026nbsp;\"2020-08-16T08:23:43.395Z\",\u003cbr\u003e\u0026nbsp;\u0026nbsp;\"level\":\u0026nbsp;\"debug\",\u003cbr\u003e\u0026nbsp;\u0026nbsp;\"levelValue\":\u0026nbsp;7,\u003cbr\u003e\u0026nbsp;\u0026nbsp;\"levelServerity\":\u0026nbsp;\"Debug\",\u003cbr\u003e\u0026nbsp;\u0026nbsp;\"message\":\u0026nbsp;\"failed\u0026nbsp;to\u0026nbsp;login\",\u003cbr\u003e\u0026nbsp;\u0026nbsp;\"data\":\u0026nbsp;[{\u0026nbsp;\"user\":\u0026nbsp;\"bob\"\u0026nbsp;}]\u003cbr\u003e}\u003c/pre\u003e \u003cbr\u003eCan handle instances of `Error` as data. |\n| `textFormatter` | \u003cpre\u003eFormatter\u003c/pre\u003e | | Will return untruncated, text like this: `2020-08-16T08:45:08.297Z [main.auth] DEBUG - failed to login {\"user\":\"bob\"}` \u003cbr\u003eCan handle instances of `Error` as data. |\n| `textWithoutDataFormatter` | \u003cpre\u003eFormatter\u003c/pre\u003e | | This [`Formatter`](#formatter) will just return the raw message without trying to serialize data. It's used for `getConsoleRawDataHandler` to be able to pass arbitrary objects like DOM Nodes or Events to the console which could not be serialized by JSON.stringify otherwise. |\n| `getJsonLengthFormatter` | \u003cpre\u003e(\u003cbr\u003e\u0026nbsp;\u0026nbsp;maxLength?:\u0026nbsp;number\u0026nbsp;\\|\u0026nbsp;undefined,\u003cbr\u003e)\u0026nbsp;=\u003e\u0026nbsp;Formatter\u003c/pre\u003e | | Will return length limited `jsonFormatter`. |\n| `getTextLengthFormatter` | \u003cpre\u003e(\u003cbr\u003e\u0026nbsp;\u0026nbsp;maxLength?:\u0026nbsp;number\u0026nbsp;\\|\u0026nbsp;undefined,\u003cbr\u003e)\u0026nbsp;=\u003e\u0026nbsp;Formatter\u003c/pre\u003e | | Will return length limited `textFormatter`. |\n\n#### How to make it\n\nA [`Formatter`](#formatter) is a function that gets the `InternalLogger` object\nand the `Message` object passed as arguments and needs to return a string.\n\nA very simple [`Formatter`](#formatter) (for the sake of simplicity ignores\ndata) could look like this:\n\n```typescript\nimport { Formatter } from '@pabra/logger';\n\nconst myFormatter: Formatter = (logger, message) =\u003e\n `${new Date().toISOString()} [${logger.name}] ${message.level}: ${\n message.raw\n }`;\n```\n\n### Transporter\n\n#### What is it\n\n```typescript\ntype Transporter = (logger: InternalLogger, message: MessageFormatted) =\u003e void;\ntype InternalLogger = {\n readonly name: string;\n readonly nameChain: string[];\n readonly handlers: Handler[];\n};\ninterface MessageFormatted {\n readonly raw: string;\n readonly data: DataArgs;\n readonly level: LogLevelName;\n readonly formatted: string;\n}\n```\n\nThe [`Transporter`](#transporter) \"transports\" the formatted message to its\ndestination. That might be the `console`, a file, some http endpoint, etc.\n\n#### How to get it\n\n```typescript\nimport { transporters, Transporter } from '@pabra/logger';\n\nconst myTransporter: Transporter = transporters.consoleTransporter;\nconst myTransporter: Transporter = transporters.consoleWithoutDataTransporter;\n```\n\n| object | type | required | description |\n| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `transporters` | \u003cpre\u003e{\u003cbr\u003e\u0026nbsp;\u0026nbsp;consoleTransporter,\u003cbr\u003e\u0026nbsp;\u0026nbsp;consoleWithoutDataTransporter,\u003cbr\u003e}\u0026nbsp;as\u0026nbsp;const\u003c/pre\u003e | | an object of common transporters |\n| `consoleTransporter` | \u003cpre\u003eTransporter\u003c/pre\u003e | | It passes the formated message **and** data to the console. It's used by the default [`Handler`](#handler) (`getConsoleRawDataHandler` - used if no [`Handler`](#handler) is passed to `getLogger`). It can be used if you want to pass arbitrary objects (like DOM Nodes, Events, etc.) to the console without having formatter dealt with them. |\n| `consoleWithoutDataTransporter` | \u003cpre\u003eTransporter\u003c/pre\u003e | | It passes only the formatted message to the console. A [`Formatter`](#formatter) should have taken care, that data became part of formatted message. It's used by `getConsoleTextHandler` and `getConsoleJsonHandler`. |\n\n#### How to make it\n\nA [`Transporter`](#transporter) is a function that gets the `InternalLogger`\nobject and the `MessageFormatted` object passed as arguments and needs to return\nnothing (`viod`).\n\nA very simple `Tranporter` to POST to your logging server might look like:\n\n```typescript\nimport { Transporter } from '@pabra/logger';\n\nconst myTransporter: Transporter = (_logger, message) =\u003e\n void fetch('https://example.com', {\n method: 'POST',\n body: message.formatted,\n });\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpabra%2Flogger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpabra%2Flogger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpabra%2Flogger/lists"}