@santana-org/logger 0.1.0 → 0.1.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 +71 -42
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,77 +1,106 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/santana-org/.github/main/profile/santana-logo.png" alt="Santana" width="980" />
|
|
3
|
+
<br/>
|
|
4
|
+
<br/>
|
|
2
5
|
|
|
3
|
-
|
|
6
|
+
<strong>@santana-org/logger</strong>
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
<p>A lightweight, zero-dependency logger for Node.js — built to stay out of your way.</p>
|
|
9
|
+
|
|
10
|
+
[](https://www.npmjs.com/package/@santana-org/logger)
|
|
11
|
+
[](./LICENSE)
|
|
12
|
+
[](https://nodejs.org/api/esm.html)
|
|
6
13
|
|
|
7
|
-
|
|
8
|
-
- Configurable minimum level
|
|
9
|
-
- Optional timestamps
|
|
10
|
-
- Optional label / namespace
|
|
11
|
-
- Colorized output (auto-detected TTY)
|
|
12
|
-
- Custom formatter support
|
|
13
|
-
- ESM-first, CJS-compatible
|
|
14
|
-
- Zero dependencies
|
|
14
|
+
</div>
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## 📦 Install
|
|
17
17
|
|
|
18
18
|
```sh
|
|
19
|
-
npm install @
|
|
20
|
-
|
|
21
|
-
pnpm add @santa-org/logger
|
|
19
|
+
npm install @santana-org/logger
|
|
20
|
+
pnpm add @santana-org/logger
|
|
22
21
|
```
|
|
23
22
|
|
|
24
|
-
##
|
|
23
|
+
## 🚀 Quickstart
|
|
25
24
|
|
|
26
25
|
```ts
|
|
27
|
-
import { createLogger } from "@
|
|
26
|
+
import { createLogger } from "@santana-org/logger"
|
|
28
27
|
|
|
29
|
-
const
|
|
28
|
+
const log = createLogger({
|
|
30
29
|
level: "info",
|
|
31
30
|
label: "app",
|
|
32
31
|
timestamps: true,
|
|
33
32
|
})
|
|
34
33
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
34
|
+
log.info("Server started")
|
|
35
|
+
log.warn("Low memory")
|
|
36
|
+
log.error("Unhandled exception", { code: 500 })
|
|
38
37
|
```
|
|
39
38
|
|
|
40
|
-
|
|
39
|
+
## 📖 API
|
|
40
|
+
|
|
41
|
+
### `createLogger(options?)`
|
|
42
|
+
|
|
43
|
+
| Option | Type | Default | Description |
|
|
44
|
+
|---|---|---|---|
|
|
45
|
+
| `level` | `LogLevel` | `"debug"` | Minimum level to output |
|
|
46
|
+
| `label` | `string` | — | Namespace prepended to every message |
|
|
47
|
+
| `timestamps` | `boolean` | `false` | Prefix messages with ISO timestamp |
|
|
48
|
+
| `colors` | `boolean` | auto | Force or disable colorized output |
|
|
49
|
+
| `formatter` | `Formatter` | built-in | Override the output format entirely |
|
|
50
|
+
| `writer` | `Writer` | stdout/stderr | Override where output goes |
|
|
51
|
+
|
|
52
|
+
### 🔢 Log levels
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
debug → info → success → warn → error
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Anything below the configured `level` is silently ignored.
|
|
59
|
+
|
|
60
|
+
## 🧩 Recipes
|
|
61
|
+
|
|
62
|
+
**Scoped child logger**
|
|
41
63
|
|
|
42
64
|
```ts
|
|
43
|
-
const
|
|
44
|
-
|
|
65
|
+
const dbLog = log.child("db")
|
|
66
|
+
dbLog.debug("Query executed") // → [app:db] Query executed
|
|
45
67
|
```
|
|
46
68
|
|
|
47
|
-
|
|
69
|
+
**Custom formatter**
|
|
48
70
|
|
|
49
71
|
```ts
|
|
50
|
-
import { createLogger, type LogEntry } from "@
|
|
72
|
+
import { createLogger, type LogEntry } from "@santana-org/logger"
|
|
51
73
|
|
|
52
|
-
const
|
|
53
|
-
formatter: (entry: LogEntry,
|
|
74
|
+
const log = createLogger({
|
|
75
|
+
formatter: (entry: LogEntry, colors: boolean) =>
|
|
54
76
|
`[${entry.level.toUpperCase()}] ${entry.message}`,
|
|
55
77
|
})
|
|
56
78
|
```
|
|
57
79
|
|
|
58
|
-
|
|
80
|
+
**Silent in tests**
|
|
59
81
|
|
|
60
|
-
|
|
82
|
+
```ts
|
|
83
|
+
const log = createLogger({ level: "error" })
|
|
84
|
+
// Only errors get through — no noise in test output
|
|
85
|
+
```
|
|
61
86
|
|
|
62
|
-
|
|
63
|
-
|-------------|-------------|---------------|--------------------------------------------|
|
|
64
|
-
| `level` | `LogLevel` | `"debug"` | Minimum log level |
|
|
65
|
-
| `label` | `string` | — | Label/namespace prepended to each message |
|
|
66
|
-
| `timestamps`| `boolean` | `false` | Include ISO timestamps |
|
|
67
|
-
| `colors` | `boolean` | auto (TTY) | Colorize output |
|
|
68
|
-
| `formatter` | `Formatter` | built-in | Custom formatter function |
|
|
69
|
-
| `writer` | `Writer` | stdout/stderr | Custom output writer |
|
|
87
|
+
**Capture output**
|
|
70
88
|
|
|
71
|
-
|
|
89
|
+
```ts
|
|
90
|
+
const lines: string[] = []
|
|
91
|
+
|
|
92
|
+
const log = createLogger({
|
|
93
|
+
writer: (line) => lines.push(line),
|
|
94
|
+
})
|
|
95
|
+
```
|
|
72
96
|
|
|
73
|
-
|
|
97
|
+
## 🏗️ Design decisions
|
|
74
98
|
|
|
75
|
-
|
|
99
|
+
- **Zero dependencies.** No transitive risk, no bloat.
|
|
100
|
+
- **ESM-first.** CJS interop included, but the package is written for modern runtimes.
|
|
101
|
+
- **TTY-aware colors.** Colors auto-disable when piped — no `NO_COLOR` hacks needed.
|
|
102
|
+
- **Composable, not configurable-forever.** One factory, one logger, one job.
|
|
76
103
|
|
|
77
|
-
|
|
104
|
+
## 📄 License
|
|
105
|
+
|
|
106
|
+
MIT © [santana-org](https://github.com/santana-org) — contributions are welcome, see [CONTRIBUTING](https://github.com/santana-org/.github/blob/main/CONTRIBUTING.md).
|