@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,151 @@
1
+ import type { Category, LoggerConfig } from "./types.ts";
2
+ /**
3
+ * Normalizes a category to a readonly string array.
4
+ * Accepts either a string (dot-separated) or an array.
5
+ *
6
+ * @example
7
+ * ```typescript
8
+ * import * as logging from "@eserstack/logging";
9
+ *
10
+ * logging.category.normalizeCategory("myapp.http.request");
11
+ * // ["myapp", "http", "request"]
12
+ * logging.category.normalizeCategory(["myapp", "http"]); // ["myapp", "http"]
13
+ * ```
14
+ */
15
+ export declare const normalizeCategory: (category: Category | string) => Category;
16
+ /**
17
+ * Converts a category array to a dot-separated string.
18
+ *
19
+ * @example
20
+ * ```typescript
21
+ * import * as logging from "@eserstack/logging";
22
+ *
23
+ * logging.category.categoryToString(["myapp", "http", "request"]);
24
+ * // "myapp.http.request"
25
+ * ```
26
+ */
27
+ export declare const categoryToString: (category: Category, separator?: string) => string;
28
+ /**
29
+ * Creates a category key for use in maps (ensures consistent string representation).
30
+ */
31
+ export declare const categoryKey: (category: Category) => string;
32
+ /**
33
+ * Checks if a child category is a descendant of a parent category.
34
+ * A descendant has the parent as a prefix and is longer.
35
+ *
36
+ * @example
37
+ * ```typescript
38
+ * import * as logging from "@eserstack/logging";
39
+ *
40
+ * logging.category.isDescendant(["app", "http", "req"], ["app"]); // true
41
+ * // false: the same category is not a descendant
42
+ * logging.category.isDescendant(["app", "http"], ["app", "http"]);
43
+ * logging.category.isDescendant(["app"], ["app", "http"]); // false: shorter
44
+ * ```
45
+ */
46
+ export declare const isDescendant: (child: Category, parent: Category) => boolean;
47
+ /**
48
+ * Checks if a child category is the same as or a descendant of a parent category.
49
+ *
50
+ * @example
51
+ * ```typescript
52
+ * import * as logging from "@eserstack/logging";
53
+ *
54
+ * logging.category.isDescendantOrSelf(["app", "http"], ["app"]); // true
55
+ * logging.category.isDescendantOrSelf(["app"], ["app"]); // true
56
+ * logging.category.isDescendantOrSelf(["other"], ["app"]); // false
57
+ * ```
58
+ */
59
+ export declare const isDescendantOrSelf: (child: Category, parent: Category) => boolean;
60
+ /**
61
+ * Checks if a parent category is an ancestor of a child category.
62
+ *
63
+ * @example
64
+ * ```typescript
65
+ * import * as logging from "@eserstack/logging";
66
+ *
67
+ * logging.category.isAncestor(["app"], ["app", "http", "req"]); // true
68
+ * // false: the same category is not an ancestor
69
+ * logging.category.isAncestor(["app", "http"], ["app", "http"]);
70
+ * ```
71
+ */
72
+ export declare const isAncestor: (parent: Category, child: Category) => boolean;
73
+ /**
74
+ * Checks if two categories are equal.
75
+ */
76
+ export declare const categoriesEqual: (a: Category, b: Category) => boolean;
77
+ /**
78
+ * Finds all logger configs that match a given category.
79
+ * Returns configs sorted by specificity (most specific first).
80
+ *
81
+ * A config matches if its category is the same as or an ancestor of the target category.
82
+ *
83
+ * @example
84
+ * ```typescript
85
+ * import * as logging from "@eserstack/logging";
86
+ *
87
+ * const configs = new Map<string, logging.LoggerConfig>([
88
+ * ["app", { category: ["app"] }],
89
+ * ["app.http", { category: ["app", "http"] }],
90
+ * ]);
91
+ *
92
+ * // [{ category: ["app", "http"] }, { category: ["app"] }]
93
+ * logging.category.findMatchingConfigs(["app", "http", "req"], configs);
94
+ * ```
95
+ */
96
+ export declare const findMatchingConfigs: (category: Category, configs: Map<string, LoggerConfig>) => LoggerConfig[];
97
+ /**
98
+ * Gets the parent category (removes the last element).
99
+ * Returns null for root categories (empty or single element).
100
+ *
101
+ * @example
102
+ * ```typescript
103
+ * import * as logging from "@eserstack/logging";
104
+ *
105
+ * logging.category.getParentCategory(["app", "http", "req"]); // ["app", "http"]
106
+ * logging.category.getParentCategory(["app"]); // null
107
+ * logging.category.getParentCategory([]); // null
108
+ * ```
109
+ */
110
+ export declare const getParentCategory: (category: Category) => Category | null;
111
+ /**
112
+ * Extends a category with additional parts.
113
+ *
114
+ * @example
115
+ * ```typescript
116
+ * import * as logging from "@eserstack/logging";
117
+ *
118
+ * logging.category.extendCategory(["app"], "http"); // ["app", "http"]
119
+ * logging.category.extendCategory(["app"], ["http", "req"]);
120
+ * // ["app", "http", "req"]
121
+ * ```
122
+ */
123
+ export declare const extendCategory: (parent: Category, child: string | Category) => Category;
124
+ /**
125
+ * Gets the common ancestor of two categories.
126
+ * Returns an empty array if there's no common prefix.
127
+ *
128
+ * @example
129
+ * ```typescript
130
+ * import * as logging from "@eserstack/logging";
131
+ *
132
+ * logging.category.getCommonAncestor(["app", "http"], ["app", "db"]); // ["app"]
133
+ * logging.category.getCommonAncestor(["app", "http"], ["other"]); // []
134
+ * ```
135
+ */
136
+ export declare const getCommonAncestor: (a: Category, b: Category) => Category;
137
+ /**
138
+ * Checks if a category matches a pattern with wildcards.
139
+ * Supports "*" to match any single segment and "**" to match any number of segments.
140
+ *
141
+ * @example
142
+ * ```typescript
143
+ * import * as logging from "@eserstack/logging";
144
+ *
145
+ * logging.category.matchesPattern(["app", "http", "req"], ["app", "*", "req"]);
146
+ * // true
147
+ * logging.category.matchesPattern(["app", "http", "req"], ["app", "**"]); // true
148
+ * logging.category.matchesPattern(["app", "http"], ["app", "db"]); // false
149
+ * ```
150
+ */
151
+ export declare const matchesPattern: (category: Category, pattern: Category) => boolean;
@@ -0,0 +1,244 @@
1
+ // Copyright 2023-present Eser Ozvataf and other contributors. All rights reserved. Apache-2.0 license.
2
+ /**
3
+ * Normalizes a category to a readonly string array.
4
+ * Accepts either a string (dot-separated) or an array.
5
+ *
6
+ * @example
7
+ * ```typescript
8
+ * import * as logging from "@eserstack/logging";
9
+ *
10
+ * logging.category.normalizeCategory("myapp.http.request");
11
+ * // ["myapp", "http", "request"]
12
+ * logging.category.normalizeCategory(["myapp", "http"]); // ["myapp", "http"]
13
+ * ```
14
+ */
15
+ export const normalizeCategory = (category) => {
16
+ if (typeof category === "string") {
17
+ return category.split(".").filter(Boolean);
18
+ }
19
+ return category;
20
+ };
21
+ /**
22
+ * Converts a category array to a dot-separated string.
23
+ *
24
+ * @example
25
+ * ```typescript
26
+ * import * as logging from "@eserstack/logging";
27
+ *
28
+ * logging.category.categoryToString(["myapp", "http", "request"]);
29
+ * // "myapp.http.request"
30
+ * ```
31
+ */
32
+ export const categoryToString = (category, separator = ".") => {
33
+ return category.join(separator);
34
+ };
35
+ /**
36
+ * Creates a category key for use in maps (ensures consistent string representation).
37
+ */
38
+ export const categoryKey = (category) => {
39
+ return category.join("\0");
40
+ };
41
+ /**
42
+ * Checks if a child category is a descendant of a parent category.
43
+ * A descendant has the parent as a prefix and is longer.
44
+ *
45
+ * @example
46
+ * ```typescript
47
+ * import * as logging from "@eserstack/logging";
48
+ *
49
+ * logging.category.isDescendant(["app", "http", "req"], ["app"]); // true
50
+ * // false: the same category is not a descendant
51
+ * logging.category.isDescendant(["app", "http"], ["app", "http"]);
52
+ * logging.category.isDescendant(["app"], ["app", "http"]); // false: shorter
53
+ * ```
54
+ */
55
+ export const isDescendant = (child, parent) => {
56
+ if (child.length <= parent.length) {
57
+ return false;
58
+ }
59
+ return parent.every((part, index) => child[index] === part);
60
+ };
61
+ /**
62
+ * Checks if a child category is the same as or a descendant of a parent category.
63
+ *
64
+ * @example
65
+ * ```typescript
66
+ * import * as logging from "@eserstack/logging";
67
+ *
68
+ * logging.category.isDescendantOrSelf(["app", "http"], ["app"]); // true
69
+ * logging.category.isDescendantOrSelf(["app"], ["app"]); // true
70
+ * logging.category.isDescendantOrSelf(["other"], ["app"]); // false
71
+ * ```
72
+ */
73
+ export const isDescendantOrSelf = (child, parent) => {
74
+ if (child.length < parent.length) {
75
+ return false;
76
+ }
77
+ return parent.every((part, index) => child[index] === part);
78
+ };
79
+ /**
80
+ * Checks if a parent category is an ancestor of a child category.
81
+ *
82
+ * @example
83
+ * ```typescript
84
+ * import * as logging from "@eserstack/logging";
85
+ *
86
+ * logging.category.isAncestor(["app"], ["app", "http", "req"]); // true
87
+ * // false: the same category is not an ancestor
88
+ * logging.category.isAncestor(["app", "http"], ["app", "http"]);
89
+ * ```
90
+ */
91
+ export const isAncestor = (parent, child) => {
92
+ return isDescendant(child, parent);
93
+ };
94
+ /**
95
+ * Checks if two categories are equal.
96
+ */
97
+ export const categoriesEqual = (a, b) => {
98
+ if (a.length !== b.length) {
99
+ return false;
100
+ }
101
+ return a.every((part, index) => part === b[index]);
102
+ };
103
+ /**
104
+ * Finds all logger configs that match a given category.
105
+ * Returns configs sorted by specificity (most specific first).
106
+ *
107
+ * A config matches if its category is the same as or an ancestor of the target category.
108
+ *
109
+ * @example
110
+ * ```typescript
111
+ * import * as logging from "@eserstack/logging";
112
+ *
113
+ * const configs = new Map<string, logging.LoggerConfig>([
114
+ * ["app", { category: ["app"] }],
115
+ * ["app.http", { category: ["app", "http"] }],
116
+ * ]);
117
+ *
118
+ * // [{ category: ["app", "http"] }, { category: ["app"] }]
119
+ * logging.category.findMatchingConfigs(["app", "http", "req"], configs);
120
+ * ```
121
+ */
122
+ export const findMatchingConfigs = (category, configs) => {
123
+ const matches = [];
124
+ for (const config of configs.values()) {
125
+ const configCategory = normalizeCategory(config.category);
126
+ if (isDescendantOrSelf(category, configCategory)) {
127
+ matches.push(config);
128
+ }
129
+ }
130
+ // Sort by specificity (longer category = more specific = first)
131
+ matches.sort((a, b) => {
132
+ const aLen = normalizeCategory(a.category).length;
133
+ const bLen = normalizeCategory(b.category).length;
134
+ return bLen - aLen;
135
+ });
136
+ return matches;
137
+ };
138
+ /**
139
+ * Gets the parent category (removes the last element).
140
+ * Returns null for root categories (empty or single element).
141
+ *
142
+ * @example
143
+ * ```typescript
144
+ * import * as logging from "@eserstack/logging";
145
+ *
146
+ * logging.category.getParentCategory(["app", "http", "req"]); // ["app", "http"]
147
+ * logging.category.getParentCategory(["app"]); // null
148
+ * logging.category.getParentCategory([]); // null
149
+ * ```
150
+ */
151
+ export const getParentCategory = (category) => {
152
+ if (category.length <= 1) {
153
+ return null;
154
+ }
155
+ return category.slice(0, -1);
156
+ };
157
+ /**
158
+ * Extends a category with additional parts.
159
+ *
160
+ * @example
161
+ * ```typescript
162
+ * import * as logging from "@eserstack/logging";
163
+ *
164
+ * logging.category.extendCategory(["app"], "http"); // ["app", "http"]
165
+ * logging.category.extendCategory(["app"], ["http", "req"]);
166
+ * // ["app", "http", "req"]
167
+ * ```
168
+ */
169
+ export const extendCategory = (parent, child) => {
170
+ const childParts = typeof child === "string" ? [child] : child;
171
+ return [...parent, ...childParts];
172
+ };
173
+ /**
174
+ * Gets the common ancestor of two categories.
175
+ * Returns an empty array if there's no common prefix.
176
+ *
177
+ * @example
178
+ * ```typescript
179
+ * import * as logging from "@eserstack/logging";
180
+ *
181
+ * logging.category.getCommonAncestor(["app", "http"], ["app", "db"]); // ["app"]
182
+ * logging.category.getCommonAncestor(["app", "http"], ["other"]); // []
183
+ * ```
184
+ */
185
+ export const getCommonAncestor = (a, b) => {
186
+ const result = [];
187
+ const minLen = Math.min(a.length, b.length);
188
+ for (let i = 0; i < minLen; i++) {
189
+ if (a[i] === b[i]) {
190
+ result.push(a[i]);
191
+ }
192
+ else {
193
+ break;
194
+ }
195
+ }
196
+ return result;
197
+ };
198
+ /**
199
+ * Checks if a category matches a pattern with wildcards.
200
+ * Supports "*" to match any single segment and "**" to match any number of segments.
201
+ *
202
+ * @example
203
+ * ```typescript
204
+ * import * as logging from "@eserstack/logging";
205
+ *
206
+ * logging.category.matchesPattern(["app", "http", "req"], ["app", "*", "req"]);
207
+ * // true
208
+ * logging.category.matchesPattern(["app", "http", "req"], ["app", "**"]); // true
209
+ * logging.category.matchesPattern(["app", "http"], ["app", "db"]); // false
210
+ * ```
211
+ */
212
+ export const matchesPattern = (category, pattern) => {
213
+ let catIndex = 0;
214
+ let patIndex = 0;
215
+ while (patIndex < pattern.length && catIndex < category.length) {
216
+ const pat = pattern[patIndex];
217
+ if (pat === "**") {
218
+ // "**" matches zero or more segments
219
+ if (patIndex === pattern.length - 1) {
220
+ // "**" at end matches everything remaining
221
+ return true;
222
+ }
223
+ // Try matching remaining pattern at each position
224
+ for (let i = catIndex; i <= category.length; i++) {
225
+ if (matchesPattern(category.slice(i), pattern.slice(patIndex + 1))) {
226
+ return true;
227
+ }
228
+ }
229
+ return false;
230
+ }
231
+ if (pat === "*" || pat === category[catIndex]) {
232
+ catIndex++;
233
+ patIndex++;
234
+ }
235
+ else {
236
+ return false;
237
+ }
238
+ }
239
+ // Handle trailing "**"
240
+ while (patIndex < pattern.length && pattern[patIndex] === "**") {
241
+ patIndex++;
242
+ }
243
+ return catIndex === category.length && patIndex === pattern.length;
244
+ };
@@ -0,0 +1,95 @@
1
+ import * as logging from "@eserstack/standards/logging";
2
+ import type { Category, ConfigureOptions, Filter, LoggerConfig, LoggerRegistryState, Sink } from "./types.ts";
3
+ /**
4
+ * Registers a callback to clear the logger cache (called from logger.ts).
5
+ */
6
+ export declare const registerLoggerCacheClear: (callback: () => void) => void;
7
+ /**
8
+ * Registers a callback invoked after every configure() call.
9
+ */
10
+ export declare const registerConfigureHook: (callback: (loggers: readonly LoggerConfig[]) => Promise<void> | void) => void;
11
+ /**
12
+ * Gets the current registry state.
13
+ * Returns null if not configured.
14
+ */
15
+ export declare const getRegistryState: () => LoggerRegistryState | null;
16
+ /**
17
+ * Checks if the logging system is configured.
18
+ */
19
+ export declare const isConfigured: () => boolean;
20
+ /**
21
+ * Configures the logging system with sinks, filters, and loggers.
22
+ *
23
+ * @example
24
+ * ```typescript
25
+ * import * as logging from "@eserstack/logging";
26
+ * import * as streams from "@eserstack/streams";
27
+ *
28
+ * const out = streams.output({
29
+ * renderer: streams.renderers.ansi(),
30
+ * sink: streams.sinks.stdout(),
31
+ * });
32
+ *
33
+ * await logging.config.configure({
34
+ * sinks: { console: logging.sinks.getOutputSink(out) },
35
+ * filters: {
36
+ * production: logging.filters.getLevelFilter(logging.Severities.Warning),
37
+ * },
38
+ * loggers: [
39
+ * {
40
+ * category: ["myapp"],
41
+ * lowestLevel: logging.Severities.Debug,
42
+ * sinks: ["console"],
43
+ * },
44
+ * { category: ["myapp", "db"], filters: ["production"] },
45
+ * ],
46
+ * });
47
+ * ```
48
+ */
49
+ export declare const configure: (options: ConfigureOptions) => Promise<void>;
50
+ /**
51
+ * Resets the logging configuration and disposes of sinks.
52
+ */
53
+ export declare const reset: () => Promise<void>;
54
+ /**
55
+ * Gets the effective configuration for a category (sinks, filters, level).
56
+ * This resolves inheritance from parent categories.
57
+ */
58
+ export declare const getEffectiveConfig: (loggerCategory: Category) => {
59
+ sinks: Sink[];
60
+ filters: Filter[];
61
+ lowestLevel: logging.Severity;
62
+ };
63
+ /**
64
+ * Registers a sink by name (for dynamic sink registration).
65
+ */
66
+ export declare const registerSink: (name: string, sink: Sink) => void;
67
+ /**
68
+ * Unregisters a sink by name.
69
+ */
70
+ export declare const unregisterSink: (name: string) => void;
71
+ /**
72
+ * Registers a filter by name.
73
+ */
74
+ export declare const registerFilter: (name: string, filter: Filter) => void;
75
+ /**
76
+ * Unregisters a filter by name.
77
+ */
78
+ export declare const unregisterFilter: (name: string) => void;
79
+ /**
80
+ * Registers a logger configuration.
81
+ */
82
+ export declare const registerLogger: (config: LoggerConfig) => void;
83
+ /**
84
+ * Gets all registered sink names.
85
+ */
86
+ export declare const getSinkNames: () => string[];
87
+ /**
88
+ * Gets all registered filter names.
89
+ */
90
+ export declare const getFilterNames: () => string[];
91
+ /**
92
+ * Gets all registered logger categories.
93
+ */
94
+ export declare const getLoggerCategories: () => Category[];
95
+ export type { ConfigureOptions, LoggerConfig, LoggerRegistryState, } from "./types.ts";