@eserstack/logging 0.0.0-stage → 5.0.0

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.
@@ -0,0 +1,38 @@
1
+ /** A level the Go logger accepts. */
2
+ export type GoLogLevel = "debug" | "info" | "warn" | "error";
3
+ /** Options for `createGoLogger()`, passed to the Go library as they are. */
4
+ export type GoLoggerOptions = {
5
+ /** The scope name written with each entry */
6
+ readonly scopeName?: string;
7
+ /** The lowest level the logger writes */
8
+ readonly level?: GoLogLevel;
9
+ /** The output format of each entry */
10
+ readonly format?: "json" | "text";
11
+ /** Whether each entry carries the source location */
12
+ readonly addSource?: boolean;
13
+ };
14
+ /** A handle to a logger in the Go library. */
15
+ export type GoLogger = {
16
+ /** Write a log entry. */
17
+ write(level: GoLogLevel, message: string, attrs?: Record<string, unknown>): void;
18
+ /** Release the Go handle. */
19
+ close(): void;
20
+ };
21
+ /**
22
+ * Creates a Go-backed structured logger writing to stderr.
23
+ *
24
+ * If the native library is unavailable, returns a no-op logger.
25
+ *
26
+ * @param options - Logger configuration
27
+ * @returns A GoLogger handle
28
+ *
29
+ * @example
30
+ * ```typescript
31
+ * import * as goLogger from "@eserstack/logging/go-logger";
32
+ *
33
+ * const log = await goLogger.createGoLogger({ scopeName: "myapp", level: "info" });
34
+ * log.write("info", "Server started", { port: 8080 });
35
+ * log.close();
36
+ * ```
37
+ */
38
+ export declare const createGoLogger: (options?: GoLoggerOptions) => Promise<GoLogger>;
@@ -0,0 +1,55 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ import * as ffiClient from "./ffi-client.js";
3
+ import * as serialize from "./serialize.js";
4
+ /**
5
+ * Creates a Go-backed structured logger writing to stderr.
6
+ *
7
+ * If the native library is unavailable, returns a no-op logger.
8
+ *
9
+ * @param options - Logger configuration
10
+ * @returns A GoLogger handle
11
+ *
12
+ * @example
13
+ * ```typescript
14
+ * import * as goLogger from "@eserstack/logging/go-logger";
15
+ *
16
+ * const log = await goLogger.createGoLogger({ scopeName: "myapp", level: "info" });
17
+ * log.write("info", "Server started", { port: 8080 });
18
+ * log.close();
19
+ * ```
20
+ */
21
+ export const createGoLogger = async (options = {}) => {
22
+ await ffiClient.ensureLib();
23
+ const lib = ffiClient.getLib();
24
+ if (lib === null) {
25
+ // No-op fallback
26
+ return {
27
+ write: () => { },
28
+ close: () => { },
29
+ };
30
+ }
31
+ const result = lib.call("logCreate", { ...options });
32
+ if ((result.error !== undefined && result.error !== "") ||
33
+ result.handle === undefined) {
34
+ return { write: () => { }, close: () => { } };
35
+ }
36
+ const handle = result.handle;
37
+ return {
38
+ write(level, message, attrs) {
39
+ const lib2 = ffiClient.getLib();
40
+ if (lib2 === null)
41
+ return;
42
+ // Encoded here for the attribute replacer; the library sends a string
43
+ // request as it is.
44
+ const request = JSON.stringify({ handle, level, message, attrs }, serialize.jsonReplacer);
45
+ lib2.call("logWrite", request);
46
+ },
47
+ close() {
48
+ const lib2 = ffiClient.getLib();
49
+ if (lib2 === null)
50
+ return;
51
+ // logClose takes the bare handle.
52
+ lib2.call("logClose", handle);
53
+ },
54
+ };
55
+ };
@@ -0,0 +1,253 @@
1
+ import * as logging from "@eserstack/standards/logging";
2
+ import type { Category } from "./types.ts";
3
+ /** The lowest severity a logger writes when no configuration sets one. */
4
+ export declare const DEFAULT_LEVEL: logging.Severity;
5
+ /**
6
+ * Logger class with hierarchical category support.
7
+ */
8
+ export declare class Logger implements logging.Logger {
9
+ #private;
10
+ /** Hierarchical category of this logger */
11
+ readonly category: Category;
12
+ /** Parent logger (null for root loggers) */
13
+ readonly parent: Logger | null;
14
+ /**
15
+ * Creates a logger. Most code calls `getLogger()` instead, which returns the
16
+ * cached logger for a category.
17
+ *
18
+ * @param loggerCategory - Category as an array or a dot-separated string
19
+ * @param parent - The logger this one was derived from, if any
20
+ * @param properties - Properties added to every record this logger writes
21
+ */
22
+ constructor(loggerCategory: Category | string, parent?: Logger | null, properties?: Record<string, unknown>);
23
+ /**
24
+ * Creates a child logger with an extended category.
25
+ *
26
+ * @example
27
+ * ```typescript
28
+ * import * as logging from "@eserstack/logging";
29
+ *
30
+ * const logger = logging.logger.getLogger(["myapp"]);
31
+ * const http = logger.getChild("http"); // ["myapp", "http"]
32
+ *
33
+ * // ["myapp", "http", "request", "handler"]
34
+ * const handler = http.getChild(["request", "handler"]);
35
+ * ```
36
+ */
37
+ getChild(subcategory: string | Category): Logger;
38
+ /**
39
+ * Returns a new logger with preset properties.
40
+ * Properties are merged with existing ones.
41
+ *
42
+ * @example
43
+ * ```typescript
44
+ * import * as logging from "@eserstack/logging";
45
+ *
46
+ * const logger = logging.logger.getLogger(["myapp"]);
47
+ * const requestLogger = logger.with({ requestId: "abc-123" });
48
+ * await requestLogger.info("Processing"); // includes requestId
49
+ * ```
50
+ */
51
+ with(properties: Record<string, unknown>): Logger;
52
+ /**
53
+ * Gets the logger name as a dot-separated string.
54
+ * For backward compatibility with old code.
55
+ */
56
+ get loggerName(): string;
57
+ /**
58
+ * Converts a value to a string for logging.
59
+ */
60
+ asString(data: unknown, isProperty?: boolean): string;
61
+ /**
62
+ * Logs a message at the given severity level. When sinks are configured for
63
+ * this logger's category, the record goes to them only, after the
64
+ * configured filters. Otherwise it goes to Go, degrading to a local console
65
+ * sink when the backend is unavailable or rejects the record. Never throws:
66
+ * a logging fault, a failing sink or filter included, must not crash the
67
+ * caller.
68
+ *
69
+ * The record is written synchronously, before `log()` returns, and a sink
70
+ * that returns a promise is not awaited; `log()` stays async so a message
71
+ * function that throws still rejects the promise.
72
+ */
73
+ log<T>(severity: logging.Severity, message: (T extends (...args: ReadonlyArray<any>) => any ? never : T) | (() => T), ...args: ReadonlyArray<any>): Promise<T | undefined>;
74
+ /**
75
+ * Logs a debug message built by a function. The function runs only when the
76
+ * Debug level is enabled for this logger.
77
+ *
78
+ * @param message - Builds the message; its result is logged
79
+ * @param args - Extra values written with the record
80
+ * @returns The function's result, or `undefined` when the level is off
81
+ */
82
+ debug<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
83
+ /**
84
+ * Logs a debug message.
85
+ *
86
+ * @param message - The message; a string, or a value converted to one
87
+ * @param args - Extra values written with the record
88
+ * @returns The message it was given
89
+ */
90
+ debug<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
91
+ /**
92
+ * Logs an info message built by a function. The function runs only when the
93
+ * Info level is enabled for this logger.
94
+ *
95
+ * @param message - Builds the message; its result is logged
96
+ * @param args - Extra values written with the record
97
+ * @returns The function's result, or `undefined` when the level is off
98
+ */
99
+ info<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
100
+ /**
101
+ * Logs an info message.
102
+ *
103
+ * @param message - The message; a string, or a value converted to one
104
+ * @param args - Extra values written with the record
105
+ * @returns The message it was given
106
+ */
107
+ info<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
108
+ /**
109
+ * Logs a warning message built by a function. The function runs only when the
110
+ * Warning level is enabled for this logger.
111
+ *
112
+ * @param message - Builds the message; its result is logged
113
+ * @param args - Extra values written with the record
114
+ * @returns The function's result, or `undefined` when the level is off
115
+ */
116
+ warn<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
117
+ /**
118
+ * Logs a warning message.
119
+ *
120
+ * @param message - The message; a string, or a value converted to one
121
+ * @param args - Extra values written with the record
122
+ * @returns The message it was given
123
+ */
124
+ warn<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
125
+ /**
126
+ * Logs an error message built by a function. The function runs only when the
127
+ * Error level is enabled for this logger.
128
+ *
129
+ * @param message - Builds the message; its result is logged
130
+ * @param args - Extra values written with the record
131
+ * @returns The function's result, or `undefined` when the level is off
132
+ */
133
+ error<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
134
+ /**
135
+ * Logs an error message.
136
+ *
137
+ * @param message - The message; a string, or a value converted to one
138
+ * @param args - Extra values written with the record
139
+ * @returns The message it was given
140
+ */
141
+ error<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
142
+ /**
143
+ * Logs a critical message built by a function. The function runs only when the
144
+ * Critical level is enabled for this logger.
145
+ *
146
+ * @param message - Builds the message; its result is logged
147
+ * @param args - Extra values written with the record
148
+ * @returns The function's result, or `undefined` when the level is off
149
+ */
150
+ critical<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
151
+ /**
152
+ * Logs a critical message.
153
+ *
154
+ * @param message - The message; a string, or a value converted to one
155
+ * @param args - Extra values written with the record
156
+ * @returns The message it was given
157
+ */
158
+ critical<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
159
+ /**
160
+ * Logs an emergency message built by a function. The function runs only when the
161
+ * Emergency level is enabled for this logger.
162
+ *
163
+ * @param message - Builds the message; its result is logged
164
+ * @param args - Extra values written with the record
165
+ * @returns The function's result, or `undefined` when the level is off
166
+ */
167
+ emergency<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
168
+ /**
169
+ * Logs an emergency message.
170
+ *
171
+ * @param message - The message; a string, or a value converted to one
172
+ * @param args - Extra values written with the record
173
+ * @returns The message it was given
174
+ */
175
+ emergency<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
176
+ /**
177
+ * Logs an alert message built by a function. The function runs only when the
178
+ * Alert level is enabled for this logger.
179
+ *
180
+ * @param message - Builds the message; its result is logged
181
+ * @param args - Extra values written with the record
182
+ * @returns The function's result, or `undefined` when the level is off
183
+ */
184
+ alert<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
185
+ /**
186
+ * Logs an alert message.
187
+ *
188
+ * @param message - The message; a string, or a value converted to one
189
+ * @param args - Extra values written with the record
190
+ * @returns The message it was given
191
+ */
192
+ alert<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
193
+ /**
194
+ * Logs a notice message built by a function. The function runs only when the
195
+ * Notice level is enabled for this logger.
196
+ *
197
+ * @param message - Builds the message; its result is logged
198
+ * @param args - Extra values written with the record
199
+ * @returns The function's result, or `undefined` when the level is off
200
+ */
201
+ notice<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
202
+ /**
203
+ * Logs a notice message.
204
+ *
205
+ * @param message - The message; a string, or a value converted to one
206
+ * @param args - Extra values written with the record
207
+ * @returns The message it was given
208
+ */
209
+ notice<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
210
+ /**
211
+ * Logs a trace message (most verbose level) built by a function. The function runs only when the
212
+ * Trace level is enabled for this logger.
213
+ *
214
+ * @param message - Builds the message; its result is logged
215
+ * @param args - Extra values written with the record
216
+ * @returns The function's result, or `undefined` when the level is off
217
+ */
218
+ trace<T>(message: () => T, ...args: ReadonlyArray<any>): Promise<T | undefined>;
219
+ /**
220
+ * Logs a trace message (most verbose level).
221
+ *
222
+ * @param message - The message; a string, or a value converted to one
223
+ * @param args - Extra values written with the record
224
+ * @returns The message it was given
225
+ */
226
+ trace<T>(message: T extends (...args: ReadonlyArray<any>) => any ? never : T, ...args: ReadonlyArray<any>): Promise<T>;
227
+ }
228
+ /**
229
+ * Gets or creates a logger for the given category.
230
+ *
231
+ * @example
232
+ * ```typescript
233
+ * import * as logging from "@eserstack/logging";
234
+ *
235
+ * const logger = logging.logger.getLogger(["myapp", "http"]);
236
+ * await logger.info("Request received");
237
+ *
238
+ * // The same logger, from a dot-separated string
239
+ * const sameLogger = logging.logger.getLogger("myapp.http");
240
+ * ```
241
+ */
242
+ export declare const getLogger: (loggerCategory: Category | string) => Logger;
243
+ /**
244
+ * Clears the logger instance cache.
245
+ * Useful for testing.
246
+ */
247
+ export declare const clearLoggerCache: () => void;
248
+ /**
249
+ * Default logger instance (for backward compatibility).
250
+ * Uses the "default" category and console output.
251
+ */
252
+ export declare const current: Logger;
253
+ export type { Category, LogRecord } from "./types.ts";