{"id":16179982,"url":"https://github.com/sullivanpj/log-right","last_synced_at":"2026-02-05T10:33:27.097Z","repository":{"id":42519390,"uuid":"456406255","full_name":"sullivanpj/log-right","owner":"sullivanpj","description":"📓 Log-Right is a light-weight (but expansive) javascript logging library with a focus on developer experience and simplifying the process of error handling, reporting, and troubleshooting. ","archived":false,"fork":false,"pushed_at":"2022-07-20T19:46:09.000Z","size":5248,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-09T10:14:00.485Z","etag":null,"topics":["error-handling","error-reporting","javascript","logging","logging-library","performance-analysis","reporting","typescript","validation"],"latest_commit_sha":null,"homepage":"https://sullivanpj.github.io/log-right/","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/sullivanpj.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":"SECURITY.md","support":null}},"created_at":"2022-02-07T07:47:55.000Z","updated_at":"2022-02-16T08:23:23.000Z","dependencies_parsed_at":"2022-09-12T11:15:05.030Z","dependency_job_id":null,"html_url":"https://github.com/sullivanpj/log-right","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sullivanpj/log-right","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sullivanpj%2Flog-right","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sullivanpj%2Flog-right/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sullivanpj%2Flog-right/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sullivanpj%2Flog-right/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sullivanpj","download_url":"https://codeload.github.com/sullivanpj/log-right/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sullivanpj%2Flog-right/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29119232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T09:40:36.738Z","status":"ssl_error","status_checked_at":"2026-02-05T09:36:49.977Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["error-handling","error-reporting","javascript","logging","logging-library","performance-analysis","reporting","typescript","validation"],"created_at":"2024-10-10T05:44:26.211Z","updated_at":"2026-02-05T10:33:27.080Z","avatar_url":"https://github.com/sullivanpj.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- @format --\u003e\n\n![log-right Logo](https://sullivanpj.com/images/log-more-banner.png)\n\n📓Log-Right is a light-weight (but expansive) javascript logging library with a focus on developer experience and simplifying the process of error handling, reporting, and troubleshooting.\n\n[![NPM Version](https://img.shields.io/npm/v/react-final-form.svg?style=for-the-badge\u0026logo=npm)](https://www.npmjs.com/package/log-right)\n[![License](https://img.shields.io/github/license/sullivanpj/log-right?style=for-the-badge\u0026logo=opensourceinitiative)](https://github.com/sullivanpj/log-right)\n[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg?style=for-the-badge\u0026logo=prettier)](https://github.com/sullivanpj/log-right)\n[![Build Status](https://img.shields.io/github/issues/sullivanpj/log-right?style=for-the-badge\u0026logo=openbugbounty)](https://github.com/sullivanpj/log-right)\n[![GitHub package.json version](https://img.shields.io/github/package-json/v/sullivanpj/log-right?style=for-the-badge\u0026logo=git)](https://github.com/sullivanpj/log-right)\n[![GitHub last commit](https://img.shields.io/github/last-commit/sullivanpj/log-right?style=for-the-badge\u0026logo=github)](https://github.com/sullivanpj/log-right)\n[![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg?style=for-the-badge)](https://liberamanifesto.com)\n\n# Features\n\n- Provides a logger utility to extend build-in logging functionality\n- Includes a Result class that can be used to manage errors (or any other type of result) that are returned from any kind of function or process\n- Simplifies global application logging by allowing users to specify how and when logs should be written/handled\n- Provides various utility methods to handle Results return from functions/process and log information and performance metrics\n- Allow user to specify custom event types which will then drive how event handler logic and logging is executed\n- Supports formatting of log event messages using custom string templates provided by the user\n\n## Some Benefits of Using 📓Log-Right\n\n- **Simple:** The APIs are extremely easy to use and include detailed [documentation](https://sullivanpj.github.io/log-right/) for all of the functionality\n- **Very Modular:** Package modules are separated by functionality/utility. Works with webpack, Browserify, or Rollup and also supports tree-shaking.\n- **TypeScript Support:** Log-Right was created using TypeScript, so all the types associated with the package are fully supported and up to date\n- [**And many more**](https://sullivanpj.github.io/log-right/)\n\n## Visit our [documentation](https://sullivanpj.github.io/log-right/) for more info, guides, API and more!\n\n# Installation\n\nInstalling and using Log-Right is very simple. Start by installing the `log-right` dependency:\n\n```bash\n$ npm i log-right --save\n# or\n$ yarn add log-right\n```\n\nOnce it is installed, you can import and use the `log-right` helper utilities and classes:\n\n```js\nimport { ConfigurationManager, validate, write, Result } from \"log-right\";\n```\n\n# Configuration\n\nOnce the package has been installed, you can use the [ConfigurationManager](https://sullivanpj.github.io/log-right/docs/log-right.configurationmanager) to specify how you want your application's logging to behave.\n\n```ts\nimport { ConfigurationManager, LogEvent } from \"log-right\";\n\nconst writeLog = (logEvent: LogEvent) =\u003e {\n  console.log(\"Event Type: \" + logEvent.eventType);\n  console.log(\"Event Message: \" + logEvent.message);\n};\n\nConfigurationManager.setConfig({\n  writeLogEvent: writeLog,\n  defaultEventSource: \"User's Custom Source\",\n  defaultResultName: \"User's Result Name\",\n  defaultErrorResultMessage:\n    \"This is a custom default error message specified by the user\",\n});\n```\n\nThe full list of configuration parameters can be found in our [documentation](https://sullivanpj.github.io/log-right/docs/log-right.logrightconfig).\n\n# 📓 Logging 📓\n\nLog-Right provides the user with \"write\" logging utility methods that will use the [configuration](https://sullivanpj.github.io/log-right/modules.html#Configuration) parameters previously provided by the user to write logs.\n\n```ts\nimport {\n  writeDebug,\n  writeInfo,\n  writeWarning,\n  writeError,\n  write,\n} from \"log-right\";\n\nwriteDebug(\"This is an debug message.\");\nwriteInfo(\"This is an info message.\");\nwriteWarning(\"This is an warn message.\");\nwriteError(\"This is an error message.\");\n\n// The below function call specifies a user-defined event type\nwrite(\"This is a custom event message.\", \"CUSTOM_EVENT_TYPE\");\n```\n\nThis event logged in the [write](https://sullivanpj.github.io/log-right/modules.html#write) method above will use custom event handler and logging logic specified by the user for that specific event type. Prior to the code snippet above, it is assumed the user [registered](https://sullivanpj.github.io/log-right/modules.html#CustomEventTypeDetails) the \"CUSTOM_EVENT_TYPE\" event type in the [ConfigurationManager](https://sullivanpj.github.io/log-right/classes/ConfigurationManager.html).\n\n**NOTE:** All five of the \"write\" methods above will call the [writeLogEvent](https://sullivanpj.github.io/log-right/modules.html#WriteLogEventFunction) functions defined in the [Configuration](https://sullivanpj.github.io/log-right/modules.html#Configuration) that were passed to the [ConfigurationManager](https://sullivanpj.github.io/log-right/classes/ConfigurationManager.html)\n\nMore information on the \"write\" logging utility methods shown above can be found in our [documentation](https://sullivanpj.github.io/log-right/modules.html#write).\n\n# Error (and Any Other Type of Result) Handling\n\nThe [Result](https://sullivanpj.github.io/log-right/classes/Result.html) class provided by Log-Right can be used in any function or process to indicate success, failure, or something in between.\n\nFor quick usage, the [Result](https://sullivanpj.github.io/log-right/classes/Result.html) class includes some static methods that can be used to generate a new Result object with the specified `validationType`.\n\n```ts\nimport { Result, validate, write } from \"log-right\";\n\nconst someSuccessfulFunction = () =\u003e {\n  const returnValues = {\n    value1: \"foo\",\n    value2: \"bar\",\n  };\n\n  return Result.success(returnValues);\n```\n\n```ts\nimport { Result, validate, write } from \"log-right\";\n\nconst someSuccessfulFunction = () =\u003e {\n  const returnValues = {\n    value1: \"foo\",\n    value2: \"bar\",\n  };\n\n  return Result.success(returnValues);\n};\n\nconst someFailureFunction = () =\u003e {\n  return Result.error({ message: \"The reason for the failure\" });\n};\n\nconst successResult: Result = someSuccessfulFunction();\nif (successResult.isFailure) {\n  // This code will not be hit\n}\n\n// The validate helper function uses the same underlying logic as the Result.isFailure property accessor\nif (!validate(successResult)) {\n  // This code will not be hit\n}\n\n// The values property will contain the values passed into Result.success function\nconsole.log(success.values); -\u003e { value1: \"foo\", value2: \"bar\" }\n\nconst failure = someFailureFunction();\nif (failure.isFailure) {\n  // This code will be hit\n}\n\n// The \"write\" helper functions mentioned in the previous section can also\n// accept a Result object as an input parameter to log\nwrite(failure);\n```\n\n**NOTE:** In Log-Right, event types and validation types are **NOT** the same. Event types are free-format strings that can be used to look up details on how the log event object should be handled/logged. There are a variable amount of possible event types, as the user is able to register as many or as few as they like. [Validation types](https://sullivanpj.github.io/log-right/modules.html#ResultValidationType) are defined through code (as a result, they have a fixed number of types) and are used to determine which path in code should be taken when an event occurs. The user-defined event types added in the [eventTypeRegistry](https://sullivanpj.github.io/log-right/modules.html#Configuration) will have a validation type associated with them. While there could be some overlap in the event and validation type values, they are not directly related to each other.\n\n## Custom User Defined Events\n\nLog-Right allows users to specify custom event types, handlers, and logging.\n\nWhen providing a configuration object to the [ConfigurationManager](https://sullivanpj.github.io/log-right/classes/ConfigurationManager.html), user's can specify the [eventTypeRegistry](https://sullivanpj.github.io/log-right/modules.html#Configuration) parameter. This parameter allows users to [register](https://sullivanpj.github.io/log-right/modules.html#CustomEventTypeDetails) custom event types with Log-Right that can be handled at a later time.\n\n```ts\nimport {\n  ConfigurationManager,\n  LogEvent,\n  ResultValidationTypes,\n} from \"log-right\";\n\nconst writeCustomEventLog = (logEvent: LogEvent) =\u003e {\n  console.log(logEvent.message);\n};\n\nConfigurationManager.setConfig({\n  eventTypeRegistry: {\n    CUSTOM_EVENT_TYPE: {\n      // Will be called to log this custom event type\n      writeLogEvent: writeCustomEventLog,\n\n      // Tell the validate function how to handle this event\n      validationType: ResultValidationTypes.ERROR,\n\n      // The specified object will be thrown if this event occurs (if nothing is specified\n      // in the throwOnEvent field, nothing will be thrown)\n      throwOnEvent: {\n        message: \"This object was thrown because we specified it\",\n      },\n\n      // The template used to format this event type's logs\n      formatTemplate: \"CUSTOM_EVENT_TYPE: \u003c!--MESSAGE--!\u003e\",\n    },\n  },\n});\n```\n\nAfter registering the custom event type with the [ConfigurationManager](https://sullivanpj.github.io/log-right/classes/ConfigurationManager.html), you can use it by returning [Result](https://sullivanpj.github.io/log-right/classes/Result.html) objects with the type specified in the `eventType` field.\n\n```ts\nimport { Result, validate } from \"log-right\";\n\nconst someCustomEventFunction = () =\u003e {\n  return new Result({ eventType: \"CUSTOM_EVENT_TYPE\" });\n};\n\nconst result = someCustomEventFunction();\nif (!validate(result)) {\n  // This code will be hit if the validationType on the eventTypeRegistry is set to \"ERROR\"\n}\n```\n\nPlease see the Result section in our [documentation](https://sullivanpj.github.io/log-right/classes/Result.html) for more details on this functionality.\n\n# Log Message Format / Formatting Templates\n\nLog-Right allows users to define their own custom templates to be used in [formatting](https://sullivanpj.github.io/log-right/modules.html#formatLogMessage) the data associated with an event into something that is either more human-readable or can be processed by a service. These templates can be applied to all types of logs on a global-level, or specific to a certain event type that is [registered](https://sullivanpj.github.io/log-right/modules.html#Configuration) with the [ConfigurationManager](https://sullivanpj.github.io/log-right/classes/ConfigurationManager.html).\n\nThe format templates are made up of template fields that are passed into the [formatTemplateToken](https://sullivanpj.github.io/log-right/modules.html#formatTemplateToken) function to generate template field tokens. Creating the template field tokens in the [formatTemplateToken](https://sullivanpj.github.io/log-right/modules.html#formatTemplateToken) function is a very straight forward process - essentially just pre-pending the templateTokenStart and appending the templateTokenStop strings from the [Configuration](https://sullivanpj.github.io/log-right/modules.html#Configuration) data around the field name. The below list of fields are available to include in a formatting template:\n\n|    **Field Name**     | **Template Field** |\n| :-------------------: | :----------------: |\n|      Event Type       |     EVENT_TYPE     |\n|    Validation Type    |  VALIDATION_TYPE   |\n|       Event ID        |         ID         |\n|      Event Name       |        NAME        |\n|     Event Source      |       SOURCE       |\n|        Context        |      CONTEXT       |\n|     Event Message     |      MESSAGE       |\n| Event Message Details |      DETAILS       |\n|      Stack Trace      |       STACK        |\n|        User ID        |      USER_ID       |\n| Timestamp (formatted) |     TIME_STAMP     |\n\n```ts\nimport { formatTemplateToken } from \"log-right\";\n\nconst templateToken = formatTemplateToken(\"EVENT_TYPE\", \"\u003c-\", \"-\u003e\");\n\nconsole.log(templateToken); -\u003e \"\u003c-EVENT_TYPE-\u003e\"\n```\n\nAfter the [formatTemplateToken](https://sullivanpj.github.io/log-right/modules.html#formatTemplateToken) is used to create the template tokens, a template string can be generated and saved to the [ConfigurationManager](https://sullivanpj.github.io/log-right/classes/ConfigurationManager.html).\n\n```ts\nimport { formatTemplateToken, ConfigurationManager, formatLogMessage } from \"log-right\";\n\nconst sourceTemplateToken = \"\u003c-SOURCE-\u003e\";\nconst userIdTemplateToken = \"\u003c-USER_ID-\u003e\";\nconst messageTemplateToken = \"\u003c-MESSAGE-\u003e\";\nconst detailsTemplateToken = \"\u003c-DETAILS-\u003e\";\nconst timestampTemplateToken = \"\u003c-TIME_STAMP-\u003e\";\n\nconst result = ConfigurationManager.setConfigItem(\"defaultFormatTemplate\", `*** Sample Log Template Header ***\nEvent Source: ${defaultFormatTemplate}\nUser ID: ${userIdTemplateToken}\nTimestamp (Est): ${timestampTemplateToken}\n\n${messageTemplateToken}\n------------------------\n${detailsTemplateToken}\n\n** A custom event log footer **\n`);\nif (result.isSuccessful) {\n  // Template was successfully saved to configuration\n}\n\n  .\n  .\n  .\n\nconst result = formatLogMessage(logEventObj);\nif (result.isSuccessful) {\n  console.log(result.values); -\u003e `*** Sample Log Template Header ***\nEvent Source: TRADE_INPUT_SYSTEM\nUser ID: JohnsonR (Richard Johnson)\nTimestamp (Est): 12/15/2022 11:23:57 AM\n\nAn error occurred while processing a transaction\n------------------------\nAn unexpected value was provided for the transaction date and amount values. This transaction will require multiple levels of approval.\n\n** A custom event log footer **\n`\n}\n```\n\nMore details on creating templates and formatting logs can be found in our [documentation](https://sullivanpj.github.io/log-right/modules.html#formatLogMessage).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsullivanpj%2Flog-right","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsullivanpj%2Flog-right","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsullivanpj%2Flog-right/lists"}