@wgtechlabs/log-engine 1.0.0 â 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +96 -149
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,28 +1,65 @@
|
|
|
1
|
-
# Log Engine
|
|
1
|
+
# Log Engine đ  
|
|
2
2
|
|
|
3
|
-
](https://github.com/wgtechlabs) [](https://github.com/sponsors/wgtechlabs) [](https://github.com/wgtechlabs/log-engine/releases) [](https://github.com/wgtechlabs/log-engine/stargazers) [](https://github.com/wgtechlabs/log-engine/blob/main/license)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://github.com/wgtechlabs/log-engine)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
WG's Log Engine is the **ultimate logging solution for Node.js developers** - a lightweight, battle-tested utility specifically engineered for Discord bots, Telegram bots, web servers, APIs, and server-side applications. Born from real-world development challenges and proven in production environments like the [Unthread Discord Bot](https://github.com/wgtechlabs/unthread-discord-bot/), Log Engine delivers enterprise-grade logging with zero complexity.
|
|
8
8
|
|
|
9
|
-
- Log
|
|
10
|
-
- Support for multiple log levels: DEBUG, INFO, WARN, ERROR, SILENT
|
|
11
|
-
- Configurable log level filtering
|
|
12
|
-
- Environment-based auto-configuration
|
|
13
|
-
- Easy integration into your Node.js applications
|
|
9
|
+
**Stop wrestling with logging configurations and start building amazing applications.** Whether you're creating the next viral Discord community bot, building high-performance APIs, developing microservices, or deploying production servers, Log Engine provides intelligent terminal-based logging that scales with your application's growth - from your first "Hello World" to handling millions of requests across distributed systems.
|
|
14
10
|
|
|
15
|
-
##
|
|
11
|
+
## âŖī¸ Motivation
|
|
16
12
|
|
|
17
|
-
|
|
13
|
+
Picture this: It's 2 AM, your server is crashing in production, and you're staring at a terminal filled with thousands of debug messages mixed with critical errors. Sound familiar? I've been there too many times. I created Log Engine because every developer deserves to sleep peacefully, knowing their logs are working intelligently in the background.
|
|
18
14
|
|
|
19
|
-
|
|
15
|
+
Log Engine transforms your development experience from chaotic debugging sessions into confident, data-driven problem solving. No more guessing what went wrong, no more drowning in irrelevant logs, no more manual configuration headaches. Just clear, contextual information exactly when and where you need it. Because great applications deserve great logging, and great developers deserve tools that just work.
|
|
16
|
+
|
|
17
|
+
## ⨠Key Features
|
|
18
|
+
|
|
19
|
+
- **Lightweight & Fast**: Minimal overhead with maximum performance - designed to enhance your application, not slow it down.
|
|
20
|
+
- **No Learning Curve**: Dead simple API that you can master in seconds. No extensive documentation, complex configurations, or setup required - Log Engine works instantly.
|
|
21
|
+
- **Multiple Log Levels**: Support for DEBUG, INFO, WARN, ERROR, and SILENT levels with smart filtering - just set your level and let it handle the rest.
|
|
22
|
+
- **Auto-Configuration**: Intelligent environment-based setup using NODE_ENV variables. No config files, initialization scripts, or manual setup - Log Engine works perfectly out of the box.
|
|
23
|
+
- **Timestamp Support**: Formatted timestamps with both ISO and human-readable formats - all the formatting you need built right in.
|
|
24
|
+
- **TypeScript Ready**: Full TypeScript support with comprehensive type definitions for a seamless development experience.
|
|
25
|
+
- **Zero Dependencies**: No external dependencies for maximum compatibility and security - keeps your bundle clean and your project simple.
|
|
26
|
+
- **Easy Integration**: Simple API that works seamlessly with existing Node.js applications. Just `import` and start logging - no middleware, plugins, or configuration required.
|
|
27
|
+
|
|
28
|
+
## đ¤ How It Works
|
|
29
|
+
|
|
30
|
+
1. Log Engine automatically detects your environment using `NODE_ENV` and sets appropriate log levels for optimal performance
|
|
31
|
+
2. When you call logging methods, messages are filtered based on the configured severity level (only messages at or above the set level are displayed)
|
|
32
|
+
3. Each log message is instantly formatted with precise timestamps in both ISO and human-readable formats
|
|
33
|
+
4. Messages are output to the console with clear level indicators, making debugging and monitoring effortless
|
|
34
|
+
|
|
35
|
+
Ready to streamline your application logging? Get started in seconds with our [simple installation](#đĻ-installation)!
|
|
36
|
+
|
|
37
|
+
## đ¤ Special Thanks
|
|
38
|
+
|
|
39
|
+
<!-- markdownlint-disable MD033 -->
|
|
40
|
+
| <div align="center">đ Platinum Sponsor</div> |
|
|
41
|
+
|:-------------------------------------------:|
|
|
42
|
+
| <a href="https://unthread.com"><img src="https://raw.githubusercontent.com/wgtechlabs/unthread-discord-bot/main/.github/assets/sponsors/platinum_unthread.png" width="250" alt="Unthread"></a> |
|
|
43
|
+
| <div align="center"><a href="https://unthread.com" target="_blank"><b>Unthread</b></a><br/>Streamlined support ticketing for modern teams.</div> |
|
|
44
|
+
<!-- markdownlint-enable MD033 -->
|
|
45
|
+
|
|
46
|
+
## đĻ Installation
|
|
47
|
+
|
|
48
|
+
Install the package using npm:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
20
51
|
npm install @wgtechlabs/log-engine
|
|
21
52
|
```
|
|
22
53
|
|
|
23
|
-
|
|
54
|
+
Or using yarn:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
yarn add @wgtechlabs/log-engine
|
|
58
|
+
```
|
|
24
59
|
|
|
25
|
-
|
|
60
|
+
## đšī¸ Usage
|
|
61
|
+
|
|
62
|
+
### Quick Start
|
|
26
63
|
|
|
27
64
|
```typescript
|
|
28
65
|
import { LogEngine, LogLevel } from '@wgtechlabs/log-engine';
|
|
@@ -34,9 +71,7 @@ LogEngine.warn('This is a warning message');
|
|
|
34
71
|
LogEngine.error('This is an error message');
|
|
35
72
|
```
|
|
36
73
|
|
|
37
|
-
### Configuration
|
|
38
|
-
|
|
39
|
-
You can configure the logger based on your environment variables or specific requirements:
|
|
74
|
+
### Custom Configuration
|
|
40
75
|
|
|
41
76
|
```typescript
|
|
42
77
|
import { LogEngine, LogLevel } from '@wgtechlabs/log-engine';
|
|
@@ -52,16 +87,16 @@ if (env === 'production') {
|
|
|
52
87
|
LogEngine.configure({ level: LogLevel.DEBUG });
|
|
53
88
|
}
|
|
54
89
|
|
|
55
|
-
// Now use
|
|
90
|
+
// Now use Log Engine - only messages at or above the configured level will be shown
|
|
56
91
|
LogEngine.debug('This will only show in development');
|
|
57
92
|
LogEngine.info('General information');
|
|
58
93
|
LogEngine.warn('Warning message');
|
|
59
94
|
LogEngine.error('Error message');
|
|
60
95
|
```
|
|
61
96
|
|
|
62
|
-
###
|
|
97
|
+
### Log Levels
|
|
63
98
|
|
|
64
|
-
|
|
99
|
+
Log Engine supports the following levels (in order of severity):
|
|
65
100
|
|
|
66
101
|
- `LogLevel.DEBUG` (0) - Detailed information for debugging
|
|
67
102
|
- `LogLevel.INFO` (1) - General information
|
|
@@ -71,173 +106,85 @@ The logger supports the following levels (in order of severity):
|
|
|
71
106
|
|
|
72
107
|
### Auto-Configuration
|
|
73
108
|
|
|
74
|
-
|
|
109
|
+
Log Engine automatically configures itself based on the `NODE_ENV` environment variable:
|
|
75
110
|
|
|
76
111
|
- `production` â `LogLevel.WARN`
|
|
77
112
|
- `development` â `LogLevel.DEBUG`
|
|
78
113
|
- `test` â `LogLevel.ERROR`
|
|
79
114
|
- `default` â `LogLevel.INFO`
|
|
80
115
|
|
|
81
|
-
|
|
116
|
+
### Log Format
|
|
82
117
|
|
|
83
|
-
|
|
118
|
+
Log messages are formatted with timestamps and levels:
|
|
84
119
|
|
|
85
120
|
```
|
|
86
121
|
[2025-05-20T16:57:45.678Z] [4:57 PM] [INFO] Message here.
|
|
87
122
|
```
|
|
88
123
|
|
|
89
|
-
##
|
|
90
|
-
|
|
91
|
-
The log-engine project includes a comprehensive test suite to ensure reliability and functionality. The tests are organized into focused, maintainable files covering different aspects of the logging system.
|
|
92
|
-
|
|
93
|
-
### Test Structure
|
|
94
|
-
|
|
95
|
-
The test suite is organized as follows:
|
|
96
|
-
|
|
97
|
-
```
|
|
98
|
-
src/__tests__/
|
|
99
|
-
âââ test-utils.ts # Shared test utilities and mocking helpers
|
|
100
|
-
âââ log-engine.test.ts # LogEngine core functionality tests
|
|
101
|
-
âââ logger.test.ts # Logger class unit tests
|
|
102
|
-
âââ formatter.test.ts # LogFormatter functionality tests
|
|
103
|
-
âââ environment.test.ts # Environment-based configuration tests
|
|
104
|
-
âââ log-level.test.ts # LogLevel enum validation tests
|
|
105
|
-
âââ integration.test.ts # End-to-end integration tests
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
### Running Tests
|
|
124
|
+
## đŦ Community Discussions
|
|
109
125
|
|
|
110
|
-
|
|
111
|
-
```bash
|
|
112
|
-
npm test
|
|
113
|
-
```
|
|
126
|
+
Join our community discussions to get help, share ideas, and connect with other users:
|
|
114
127
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
128
|
+
- đŖ **[Announcements](https://github.com/wgtechlabs/log-engine/discussions/categories/announcements)**: Official updates from the maintainer
|
|
129
|
+
- đ¸ **[Showcase](https://github.com/wgtechlabs/log-engine/discussions/categories/showcase)**: Show and tell your implementation
|
|
130
|
+
- đ **[Wall of Love](https://github.com/wgtechlabs/log-engine/discussions/categories/wall-of-love)**: Share your experience with the library
|
|
131
|
+
- đ **[Help & Support](https://github.com/wgtechlabs/log-engine/discussions/categories/help-support)**: Get assistance from the community
|
|
132
|
+
- đ§ **[Ideas](https://github.com/wgtechlabs/log-engine/discussions/categories/ideas)**: Suggest new features and improvements
|
|
119
133
|
|
|
120
|
-
|
|
121
|
-
```bash
|
|
122
|
-
npm run test:watch
|
|
123
|
-
```
|
|
134
|
+
## đ Help & Support
|
|
124
135
|
|
|
125
|
-
|
|
126
|
-
```bash
|
|
127
|
-
# Run only LogEngine tests
|
|
128
|
-
npm test log-engine
|
|
136
|
+
### Getting Help
|
|
129
137
|
|
|
130
|
-
|
|
131
|
-
npm test logger
|
|
138
|
+
Need assistance with the library? Here's how to get help:
|
|
132
139
|
|
|
133
|
-
|
|
134
|
-
|
|
140
|
+
- **Community Support**: Check the [Help & Support](https://github.com/wgtechlabs/log-engine/discussions/categories/help-support) category in our GitHub Discussions for answers to common questions.
|
|
141
|
+
- **Ask a Question**: Create a [new discussion](https://github.com/wgtechlabs/log-engine/discussions/new?category=help-support) if you can't find answers to your specific issue.
|
|
142
|
+
- **Documentation**: Review the [usage instructions](#đšī¸-usage) in this README for common examples and configurations.
|
|
143
|
+
- **Known Issues**: Browse [existing issues](https://github.com/wgtechlabs/log-engine/issues) to see if your problem has already been reported.
|
|
135
144
|
|
|
136
|
-
|
|
137
|
-
npm test formatter
|
|
138
|
-
```
|
|
145
|
+
### Reporting Issues
|
|
139
146
|
|
|
140
|
-
|
|
147
|
+
Please report any issues, bugs, or improvement suggestions by [creating a new issue](https://github.com/wgtechlabs/log-engine/issues/new/choose). Before submitting, please check if a similar issue already exists to avoid duplicates.
|
|
141
148
|
|
|
142
|
-
|
|
149
|
+
### Security Vulnerabilities
|
|
143
150
|
|
|
144
|
-
|
|
145
|
-
- **Branches**: ~87%
|
|
146
|
-
- **Functions**: ~90%
|
|
147
|
-
- **Lines**: ~94%
|
|
151
|
+
For security vulnerabilities, please do not report them publicly. Follow the guidelines in our [security policy](./security.md) to responsibly disclose security issues.
|
|
148
152
|
|
|
149
|
-
|
|
153
|
+
Your contributions to improving this project are greatly appreciated! đâ¨
|
|
150
154
|
|
|
151
|
-
|
|
155
|
+
## đ¯ Contributing
|
|
152
156
|
|
|
153
|
-
|
|
154
|
-
- **LogEngine** (`log-engine.test.ts`): Core logging functionality, configuration, and level filtering
|
|
155
|
-
- **Logger** (`logger.test.ts`): Logger class behavior and configuration
|
|
156
|
-
- **LogFormatter** (`formatter.test.ts`): Message formatting with timestamps and levels
|
|
157
|
-
- **LogLevel** (`log-level.test.ts`): Enum values and ordering validation
|
|
157
|
+
Contributions are welcome, create a pull request to this repo and I will review your code. Please consider to submit your pull request to the `dev` branch. Thank you!
|
|
158
158
|
|
|
159
|
-
|
|
160
|
-
- **Environment** (`environment.test.ts`): Auto-configuration based on `NODE_ENV`
|
|
159
|
+
Read the project's [contributing guide](./CONTRIBUTING.md) for more info, including testing guidelines and requirements.
|
|
161
160
|
|
|
162
|
-
|
|
163
|
-
- **Integration** (`integration.test.ts`): End-to-end scenarios and workflows
|
|
161
|
+
## đ Sponsor
|
|
164
162
|
|
|
165
|
-
|
|
163
|
+
Like this project? **Leave a star**! âââââ
|
|
166
164
|
|
|
167
|
-
|
|
165
|
+
There are several ways you can support this project:
|
|
168
166
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
import { LogEngine, LogLevel } from '../index';
|
|
172
|
-
import { setupConsoleMocks, restoreConsoleMocks, ConsoleMocks } from './test-utils';
|
|
173
|
-
|
|
174
|
-
describe('Feature Name', () => {
|
|
175
|
-
let mocks: ConsoleMocks;
|
|
176
|
-
|
|
177
|
-
beforeEach(() => {
|
|
178
|
-
mocks = setupConsoleMocks();
|
|
179
|
-
// Setup test state
|
|
180
|
-
});
|
|
181
|
-
|
|
182
|
-
afterEach(() => {
|
|
183
|
-
restoreConsoleMocks(mocks);
|
|
184
|
-
// Cleanup
|
|
185
|
-
});
|
|
186
|
-
|
|
187
|
-
it('should describe the expected behavior', () => {
|
|
188
|
-
// Arrange
|
|
189
|
-
LogEngine.configure({ level: LogLevel.INFO });
|
|
190
|
-
|
|
191
|
-
// Act
|
|
192
|
-
LogEngine.info('Test message');
|
|
193
|
-
|
|
194
|
-
// Assert
|
|
195
|
-
expect(mocks.mockConsoleLog).toHaveBeenCalledWith(
|
|
196
|
-
expect.stringContaining('[INFO] Test message')
|
|
197
|
-
);
|
|
198
|
-
});
|
|
199
|
-
});
|
|
200
|
-
```
|
|
167
|
+
- [Become a sponsor](https://github.com/sponsors/wgtechlabs) and get some perks! đ
|
|
168
|
+
- [Buy me a coffee](https://buymeacoffee.com/wgtechlabs) if you just love what I do! â
|
|
201
169
|
|
|
202
|
-
|
|
203
|
-
- Use descriptive test names that explain the expected behavior
|
|
204
|
-
- Follow the Arrange-Act-Assert pattern
|
|
205
|
-
- Use the shared `test-utils` for console mocking
|
|
206
|
-
- Clean up after each test to avoid side effects
|
|
207
|
-
- Test both positive and negative scenarios
|
|
208
|
-
- Include edge cases and error conditions
|
|
170
|
+
## â GitHub Star Nomination
|
|
209
171
|
|
|
210
|
-
|
|
211
|
-
The project uses shared console mocking utilities:
|
|
172
|
+
Found this project helpful? Consider nominating me **(@warengonzaga)** for the [GitHub Star program](https://stars.github.com/nominate/)! This recognition supports ongoing development of this project and [my other open-source projects](https://github.com/warengonzaga?tab=repositories). GitHub Stars are recognized for their significant contributions to the developer community - your nomination makes a difference and encourages continued innovation!
|
|
212
173
|
|
|
213
|
-
|
|
214
|
-
import { setupConsoleMocks, restoreConsoleMocks, ConsoleMocks } from './test-utils';
|
|
215
|
-
|
|
216
|
-
// In your test setup
|
|
217
|
-
const mocks = setupConsoleMocks();
|
|
174
|
+
## đ Code of Conduct
|
|
218
175
|
|
|
219
|
-
|
|
220
|
-
restoreConsoleMocks(mocks);
|
|
221
|
-
|
|
222
|
-
// In your assertions
|
|
223
|
-
expect(mocks.mockConsoleLog).toHaveBeenCalledWith(expected);
|
|
224
|
-
expect(mocks.mockConsoleWarn).toHaveBeenCalledTimes(1);
|
|
225
|
-
expect(mocks.mockConsoleError).not.toHaveBeenCalled();
|
|
226
|
-
```
|
|
176
|
+
I'm committed to providing a welcoming and inclusive environment for all contributors and users. Please review the project's [Code of Conduct](./code_of_conduct.md) to understand the community standards and expectations for participation.
|
|
227
177
|
|
|
228
|
-
|
|
178
|
+
## đ License
|
|
229
179
|
|
|
230
|
-
|
|
231
|
-
- Pull requests
|
|
232
|
-
- Pushes to main branch
|
|
233
|
-
- Release workflows
|
|
180
|
+
This project is licensed under the [GNU Affero General Public License v3.0](https://opensource.org/licenses/AGPL-3.0). This license requires that all modifications to the code must be shared under the same license, especially when the software is used over a network. See the [LICENSE](LICENSE) file for the full license text.
|
|
234
181
|
|
|
235
|
-
|
|
182
|
+
## đ Author
|
|
236
183
|
|
|
237
|
-
|
|
184
|
+
This project is created by **[Waren Gonzaga](https://github.com/warengonzaga)** under [WG Technology Labs](https://github.com/wgtechlabs), with the help of awesome [contributors](https://github.com/wgtechlabs/log-engine/graphs/contributors).
|
|
238
185
|
|
|
239
|
-
|
|
186
|
+
[](https://github.com/wgtechlabs/log-engine/graphs/contributors)
|
|
240
187
|
|
|
241
|
-
|
|
188
|
+
---
|
|
242
189
|
|
|
243
|
-
|
|
190
|
+
đģ with â¤ī¸ by [Waren Gonzaga](https://warengonzaga.com) under [WG Technology Labs](https://wgtechlabs.com), and [Him](https://www.youtube.com/watch?v=HHrxS4diLew&t=44s) đ
|