Skip to content

Commit 764cd62

Browse files
committed
docs: update readme for prerelease
1 parent df7b271 commit 764cd62

File tree

1 file changed

+72
-30
lines changed

1 file changed

+72
-30
lines changed

README.md

Lines changed: 72 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,80 @@
55
[![All Contributors](https://img.shields.io/badge/all_contributors-10-orange.svg?style=flat-square)](#contributors-)
66
<!-- ALL-CONTRIBUTORS-BADGE:END -->
77

8+
## CAUTION!
9+
10+
This branch and release (`@next`) is under heavy development. This exists for testing and anyone who is willing to help out with testing. **DO NOT USE IN PRODUCTION!**
11+
12+
If you do decide to try out this brand new version of LambdaLog, please report any issues you face as I can only catch so much. Any help would be greatly appreciated, especially if you are more versed in TypeScript than I am!
13+
14+
15+
16+
### What's new?
17+
18+
This is the next major release of LambdaLog (v4.0.0) which contains many major breaking changes, new features, and TypeScript support.
19+
20+
#### Breaking Changes
21+
22+
- Complete rewrite of most of the core functionality into TypeScript.
23+
- Custom Log Levels has been removed.
24+
- Log levels are now hardcoded and cannot be changed. This greatly simplifies the code and allows us to support TypeScript.
25+
- Use of `Symbol` has been removed along with any static properties on the classes to retrieve the symbols.
26+
- The `debug` option has been removed.
27+
- The default key name for `levelKey` has changed from `_logLevel` to `__level`.
28+
- The default key name for `tagsKey` has changed from `_tags` to `__tags`.
29+
- The shortcut log methods are now hardcoded instead of dynamically generated.
30+
- Removed `addLevel()` method from LambdaLog class.
31+
- Removed `isError()` and `stubError()` static methods from the LogMessage class and moved them into utility functions.
32+
- Environment variables that configure different options now take precedence over locally configured options.
33+
- Internally used properties on the LogMessage class have been renamed.
34+
35+
#### New Features
36+
37+
- You can now configure the verbosity of your log messages through the new `level` option or `LAMBDALOG_LEVEL` env variable.
38+
- Added `fatal` and `trace` log levels.
39+
- Added `onParse` option that allows for custom parsing of log messages.
40+
- Added `onCompile` option that allows for custom structuring of the object that is logged to the console.
41+
- Added `onFormat` option that allows for custom formatting of the logged message. This gives the ability to render log messages in any format, not just JSON. (#75)
42+
- Added `clean` formatter that logs a message in a readable format.
43+
- Added `minimal` formatter that logs a message in a readable format without tags and metadata.
44+
- Ability to provide your own custom formatter as a function.
45+
- Added ability to configure the `level`, `dev`, and `silent` options via environment variables.
46+
- Full written in TypeScript with complete type definitions. (#63, #64)
47+
- The package now provides an ESM and CommonJS version to support your project.
48+
49+
#### Fixes
50+
51+
- Fixed issue where directly setting `log.options.logHandler` did not work (#45).
52+
53+
#### Misc. Changes
54+
55+
- Rewrote most tests into TypeScript and still maintaining 100% coverage.
56+
57+
58+
59+
### What's left?
60+
61+
It has been a pretty large undertaking for me, but one that this package desperately needed. This was my first real dive into TypeScript, so I'm sure there are things than can be written better. **If there is anyone with more advanced TypeScript knowledge, I'm in great need of someone who can review the code and suggest any changes or help refactor the code to get this production-ready.** _(I'll even add you as a maintainer!)_
62+
63+
- Testing package implementation in Node for both vanilla JavaScript and TypeScript.
64+
- Testing ESM support with Node and ensuring CommonJS works correctly as well.
65+
- Ensuring the end-user has access to all the proper files and functionality.
66+
- Documentation.
67+
68+
69+
70+
### Release Date
71+
72+
As much as I am trying to rush this out the door to get these features in the hands of all you awesome developers/engineers, I'm also limited on time (eg. I'm currently writing this documentation at midnight knowing that I have to wake up at 5:30am). Not only that, but I want to ensure I ship this next version of LambdaLog with performance, features, and stability in mind. I hope this will be the last major version for awhile.
73+
74+
Enough with all of that cheesy sob-story, let's talk about when this will be released, well, what I'm aiming for at this point. I hope to finish up most of my to-do list in the next couple of weeks and try to solicit some outside help for testing/analysis. Once that is complete, I hope to get this released as the latest stable version towards the end of 2021 or at the beginning of 2022. That's not guarantee at this point, but it will definitely be feasible if anyone in the community can help out!
75+
76+
---
77+
878
LambdaLog is a [Node.js package](https://www.npmjs.com/package/lambda-log) facilitates and enforces logging standards in Node.js processes or applications **anywhere** by formatting your log messages as JSON for simple parsing and filtering within log management tools, such as CloudWatch Logs. _Works with all of the supported versions of Node.js on Lambda._
979

1080
Originally created for AWS Lambda Functions, LambdaLog is a lightweight and feature-rich library that has **no** dependency on AWS or Lambda, meaning you can use it in any type of Node.js project you wish. **It's really a universal JSON logger.**
1181

12-
1382
**Why another lambda logger?**
1483
There are plenty of other logging libraries in the NPM ecosystem but most are convoluted, included more functionality than needed, not maintained, or are not configurable enough. I created LambdaLog to include the important functionality from other loggers, but still maintaining simplicity with minimal dependencies.
1584

@@ -26,41 +95,14 @@ Anyone can log JSON to the `console`, but with Lambda Log you also get:
2695
- Over 1.5 million downloads and more than 35k weekly downloads.
2796
- Small footprint.
2897

29-
#### New in Version 3.0.0
30-
31-
Version 3.0.0 of Lambda Log brings a bunch of changes, new features, and a [new website](https://lambdalog.dev).
32-
33-
**Broad Changes:**
34-
35-
* Refactor all code to meet new ESLint specifications and to stay up-to-date with newer ecmascript specifications.
36-
* New website with better documentation.
37-
* Tests are now using Jest instead of Mocha.
38-
* Switched from TravisCI to Github Actions.
39-
40-
**New Features:**
41-
42-
- Added `levelKey` configuration option to be able to change the key name for log levels.
43-
- Added `messageKey` configuration option to be able to change the key name for log messages.
44-
- Added `tagsKey` configuration option to be able to change the key name for tags.
45-
- Added ability to remove log level and tags from the outputted log JSON.
46-
- Added `addLevel()` method to quickly add a custom log level to an instance of LambdaLog.
47-
- Tags can now be functions that return a dynamic tag for log messages.
48-
- Tags now have variable support.
49-
- Tags that are `null`, `undefined` or `""` are now removed from the tags array.
50-
- Metadata that contains `Error` objects are now automatically converted to a plain object.
51-
52-
**Breaking Changes:**
53-
54-
- All of the private properties of both the LambdaLog and LogMessage classes are stored using Symbols. This may break some advanced uses of Lambda Log from version 2.
55-
- Tags no longer contain any default, built-in tags and are empty by default.
56-
- Some of the properties of LogMessage have been moved from the constructor to their own getter functions.
57-
5898

5999

60100
## Documentation
61101

62102
Documentation for Lambda Log has moved to our [new website](https://lambdalog.dev).
63103

104+
*Note: The documentation has NOT been updated for this new release yet. I'm working on it!*
105+
64106

65107

66108
## Tests

0 commit comments

Comments
 (0)