@gusto/baerly-storage 0.1.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.
- package/README.md +97 -0
- package/dist/API.md +850 -0
- package/dist/app-config-Cb5dO2s9.d.ts +480 -0
- package/dist/app-config.d.ts +2 -0
- package/dist/app-config.js +8 -0
- package/dist/app-config.js.map +1 -0
- package/dist/auth.d.ts +237 -0
- package/dist/auth.js +1335 -0
- package/dist/auth.js.map +1 -0
- package/dist/baerly.js +761 -0
- package/dist/baerly.js.map +1 -0
- package/dist/bucket-uri-BrDEYvzy.js +4922 -0
- package/dist/bucket-uri-BrDEYvzy.js.map +1 -0
- package/dist/chunk-EAsCxrDo.js +14 -0
- package/dist/client-BLf3Ae5s.d.ts +233 -0
- package/dist/client-react.d.ts +131 -0
- package/dist/client-react.js +559 -0
- package/dist/client-react.js.map +1 -0
- package/dist/client.d.ts +4 -0
- package/dist/client.js +160 -0
- package/dist/client.js.map +1 -0
- package/dist/cloudflare-CINJPKCW.js +911 -0
- package/dist/cloudflare-CINJPKCW.js.map +1 -0
- package/dist/cloudflare.d.ts +211 -0
- package/dist/cloudflare.js +445 -0
- package/dist/cloudflare.js.map +1 -0
- package/dist/config-Bsg8wgwo.js +198 -0
- package/dist/config-Bsg8wgwo.js.map +1 -0
- package/dist/context-Oj7ffwD-.js +187 -0
- package/dist/context-Oj7ffwD-.js.map +1 -0
- package/dist/cost-B1WiZxlf.js +203 -0
- package/dist/cost-B1WiZxlf.js.map +1 -0
- package/dist/current-json-BkatBzF7.js +252 -0
- package/dist/current-json-BkatBzF7.js.map +1 -0
- package/dist/db-D62JguBc.d.ts +336 -0
- package/dist/deploy-BB-wqbhf.js +83 -0
- package/dist/deploy-BB-wqbhf.js.map +1 -0
- package/dist/dev-banner-CWHIk8tH.d.ts +26 -0
- package/dist/dev-vite.d.ts +146 -0
- package/dist/dev-vite.js +223 -0
- package/dist/dev-vite.js.map +1 -0
- package/dist/dev.d.ts +3 -0
- package/dist/dev.js +2 -0
- package/dist/doctor-B8h9GCN9.js +331 -0
- package/dist/doctor-B8h9GCN9.js.map +1 -0
- package/dist/dump-BHo_sIMZ.js +116 -0
- package/dist/dump-BHo_sIMZ.js.map +1 -0
- package/dist/errors-DOdL95kK.js +58 -0
- package/dist/errors-DOdL95kK.js.map +1 -0
- package/dist/export-Dz2PZKSR.js +423 -0
- package/dist/export-Dz2PZKSR.js.map +1 -0
- package/dist/fsck-DEz9lyCy.js +293 -0
- package/dist/fsck-DEz9lyCy.js.map +1 -0
- package/dist/http-CjUO1Bec.js +1756 -0
- package/dist/http-CjUO1Bec.js.map +1 -0
- package/dist/http.d.ts +1619 -0
- package/dist/http.js +2 -0
- package/dist/index-BGC-ENnj.d.ts +1065 -0
- package/dist/index-BYv0hb8M.d.ts +1457 -0
- package/dist/index-BquQkhJi.d.ts +112 -0
- package/dist/index-COsQ-Mlz.d.ts +146 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +6 -0
- package/dist/indexes-BXn7a06a.js +297 -0
- package/dist/indexes-BXn7a06a.js.map +1 -0
- package/dist/indexes-DwOXkn1Y.d.ts +22 -0
- package/dist/inspect-x02aFWnh.js +149 -0
- package/dist/inspect-x02aFWnh.js.map +1 -0
- package/dist/log-walk-DIru96UT.js +260 -0
- package/dist/log-walk-DIru96UT.js.map +1 -0
- package/dist/maintenance-Bn6ul9aV.js +758 -0
- package/dist/maintenance-Bn6ul9aV.js.map +1 -0
- package/dist/maintenance.d.ts +323 -0
- package/dist/maintenance.js +2 -0
- package/dist/node.d.ts +422 -0
- package/dist/node.js +2 -0
- package/dist/normalize-XWY25_sG.js +133 -0
- package/dist/normalize-XWY25_sG.js.map +1 -0
- package/dist/observability-2IDYRuZK.js +2333 -0
- package/dist/observability-2IDYRuZK.js.map +1 -0
- package/dist/observability.d.ts +3 -0
- package/dist/observability.js +3 -0
- package/dist/plan-Cs17VqjU.js +224 -0
- package/dist/plan-Cs17VqjU.js.map +1 -0
- package/dist/query-DcSbFLJt.js +1880 -0
- package/dist/query-DcSbFLJt.js.map +1 -0
- package/dist/rebuild-index-C5gTXryd.js +119 -0
- package/dist/rebuild-index-C5gTXryd.js.map +1 -0
- package/dist/rebuild-index-DwXM0WfA.js +104 -0
- package/dist/rebuild-index-DwXM0WfA.js.map +1 -0
- package/dist/request-BEF_OvMh.js +72 -0
- package/dist/request-BEF_OvMh.js.map +1 -0
- package/dist/restore-CbKVMMpm.js +847 -0
- package/dist/restore-CbKVMMpm.js.map +1 -0
- package/dist/shared-secret-BJdSwpgw.js +71 -0
- package/dist/shared-secret-BJdSwpgw.js.map +1 -0
- package/dist/snapshot-D7C4_FSl.js +71 -0
- package/dist/snapshot-D7C4_FSl.js.map +1 -0
- package/dist/snapshot-z_N9hpTe.js +917 -0
- package/dist/snapshot-z_N9hpTe.js.map +1 -0
- package/dist/src-Chafbw8r.js +522 -0
- package/dist/src-Chafbw8r.js.map +1 -0
- package/dist/src-DyET_VPP.js +6199 -0
- package/dist/src-DyET_VPP.js.map +1 -0
- package/dist/src-n0Te1r98.js +352 -0
- package/dist/src-n0Te1r98.js.map +1 -0
- package/dist/subcommand-BWs6K7zb.js +110 -0
- package/dist/subcommand-BWs6K7zb.js.map +1 -0
- package/dist/usage-RVUQMLop.js +339 -0
- package/dist/usage-RVUQMLop.js.map +1 -0
- package/dist/validate-DhH1lO8I.js +377 -0
- package/dist/validate-DhH1lO8I.js.map +1 -0
- package/dist/wire-izfGZDvr.js +7 -0
- package/dist/wire-izfGZDvr.js.map +1 -0
- package/package.json +189 -0
|
@@ -0,0 +1,1457 @@
|
|
|
1
|
+
import { m as Storage, t as MetricsRecorder } from "./index-BGC-ENnj.js";
|
|
2
|
+
|
|
3
|
+
//#region packages/server/src/observability/recorder.d.ts
|
|
4
|
+
/** One observation row, kept in insertion order. */
|
|
5
|
+
interface ObservationRow {
|
|
6
|
+
readonly name: string;
|
|
7
|
+
readonly value: number;
|
|
8
|
+
readonly labels: Readonly<Record<string, string>>;
|
|
9
|
+
}
|
|
10
|
+
/** Result of {@link RequestScopedMetricsRecorder.snapshot}. */
|
|
11
|
+
interface MetricsSnapshot {
|
|
12
|
+
readonly counters: readonly ObservationRow[];
|
|
13
|
+
readonly gauges: readonly ObservationRow[];
|
|
14
|
+
readonly histograms: readonly ObservationRow[];
|
|
15
|
+
}
|
|
16
|
+
/** Flat per-metric aggregation as consumed by the canonical line. */
|
|
17
|
+
type MetricsSummary = Record<string, number>;
|
|
18
|
+
/**
|
|
19
|
+
* Implementation. Allocations:
|
|
20
|
+
*
|
|
21
|
+
* - Three arrays at construction time, grown on each emission.
|
|
22
|
+
* - On `summarize()` we materialize one extra `Map` per metric-
|
|
23
|
+
* family (counter / gauge / histogram) plus a copy of each
|
|
24
|
+
* histogram's values for sorting.
|
|
25
|
+
*
|
|
26
|
+
* CPU-ms budget on Workers is tight; we deliberately defer all of
|
|
27
|
+
* that to flush time.
|
|
28
|
+
*/
|
|
29
|
+
declare class RequestScopedMetricsRecorder implements MetricsRecorder {
|
|
30
|
+
#private;
|
|
31
|
+
counter(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
|
|
32
|
+
gauge(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
|
|
33
|
+
histogram(name: string, value: number, labels?: Readonly<Record<string, string>>): void;
|
|
34
|
+
/**
|
|
35
|
+
* Read-only view of every observation seen so far. Intended for
|
|
36
|
+
* tests + structured debugging; the canonical-line flusher uses
|
|
37
|
+
* {@link summarize} instead.
|
|
38
|
+
*
|
|
39
|
+
* @internal Not part of the published observability surface; tests
|
|
40
|
+
* import via relative path. Production reads via {@link summarize}.
|
|
41
|
+
*/
|
|
42
|
+
snapshot(): MetricsSnapshot;
|
|
43
|
+
/**
|
|
44
|
+
* Flat aggregation, keyed by metric name with suffixes baked in:
|
|
45
|
+
*
|
|
46
|
+
* - Counter `db.foo.bar` → `db.foo.bar_total` (sum of all observations)
|
|
47
|
+
* - Gauge `db.foo.bar` → `db.foo.bar` (last value seen)
|
|
48
|
+
* - Histogram `db.foo.bar` → `db.foo.bar_count` (number of observations)
|
|
49
|
+
* + `db.foo.bar_sum` (sum of values)
|
|
50
|
+
*
|
|
51
|
+
* Histogram aggregation is a single pass in insertion order — no
|
|
52
|
+
* sort. Returns numbers only — labels are NOT collapsed into keys;
|
|
53
|
+
* if a metric is emitted with different label sets, its
|
|
54
|
+
* observations are aggregated together by `name` alone. The
|
|
55
|
+
* canonical line is per-request anyway; per-label fan-out belongs
|
|
56
|
+
* to the operator's long-term recorder.
|
|
57
|
+
*/
|
|
58
|
+
summarize(): MetricsSummary;
|
|
59
|
+
}
|
|
60
|
+
//#endregion
|
|
61
|
+
//#region packages/server/src/observability/context.d.ts
|
|
62
|
+
/** Read-mostly per-request observability state. */
|
|
63
|
+
interface ObservabilityContext {
|
|
64
|
+
/** Externally-correlatable request identifier (UUID-ish). */
|
|
65
|
+
readonly request_id: string;
|
|
66
|
+
/** Monotonic `performance.now()` reading captured at construction. */
|
|
67
|
+
readonly started_at: number;
|
|
68
|
+
/**
|
|
69
|
+
* Mutable bag for canonical-line attributes. Callers `obs.fields.set("k", v)`;
|
|
70
|
+
* the canonical-line flusher spreads this onto the emitted properties at
|
|
71
|
+
* end-of-request.
|
|
72
|
+
*/
|
|
73
|
+
readonly fields: Map<string, unknown>;
|
|
74
|
+
/**
|
|
75
|
+
* Per-request metrics bag. Lives on the context so adapters can
|
|
76
|
+
* reach it from inside the `Db`'s `MetricsRecorder` callback via
|
|
77
|
+
* `getCurrentContext()?.recorder` — no parallel `AsyncLocalStorage`
|
|
78
|
+
* lookup. The canonical-line flusher reads its `summarize()` at
|
|
79
|
+
* end-of-request and spreads the result onto the emitted line.
|
|
80
|
+
*/
|
|
81
|
+
readonly recorder: RequestScopedMetricsRecorder;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Optional construction inputs. All fields are optional so callers in
|
|
85
|
+
* unit-of-work entry middleware (HTTP router, maintenance scheduler)
|
|
86
|
+
* can pass only what they have. Defaults:
|
|
87
|
+
*
|
|
88
|
+
* - `request_id`: a fresh `crypto.randomUUID()`. Pass an externally-
|
|
89
|
+
* supplied id (`X-Request-Id` header, scheduler-supplied tag) to
|
|
90
|
+
* propagate correlation downstream.
|
|
91
|
+
* - `recorder`: a fresh {@link RequestScopedMetricsRecorder}. Tests can
|
|
92
|
+
* pass an externally-constructed recorder to assert on its
|
|
93
|
+
* `snapshot()` after the unit-of-work completes; production callers
|
|
94
|
+
* should accept the default.
|
|
95
|
+
*/
|
|
96
|
+
interface ObservabilityContextInit {
|
|
97
|
+
readonly request_id?: string;
|
|
98
|
+
readonly recorder?: RequestScopedMetricsRecorder;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Factory for {@link ObservabilityContext}. We use a factory rather
|
|
102
|
+
* than a class so consumers can structural-type the result and so
|
|
103
|
+
* the `AsyncLocalStorage` slot type stays a plain interface — no
|
|
104
|
+
* surprises around `instanceof` across realms (Workers vs Node).
|
|
105
|
+
*/
|
|
106
|
+
declare const createObservabilityContext: (init?: ObservabilityContextInit) => ObservabilityContext;
|
|
107
|
+
/**
|
|
108
|
+
* Run `fn` with `ctx` active as the current observability context.
|
|
109
|
+
* Inside `fn` (and any `await`-chained continuation rooted in `fn`),
|
|
110
|
+
* {@link getCurrentContext} returns `ctx`. Outside, it returns the
|
|
111
|
+
* previously-active context (or `undefined`).
|
|
112
|
+
*
|
|
113
|
+
* `runWithContext` is async-safe via `AsyncLocalStorage`; it propagates
|
|
114
|
+
* through `await`, `Promise.all`, `setTimeout`, and `queueMicrotask`.
|
|
115
|
+
*
|
|
116
|
+
* Returns `fn`'s return value verbatim — including its promise
|
|
117
|
+
* identity, so callers can `await` or chain off it without extra
|
|
118
|
+
* indirection.
|
|
119
|
+
*/
|
|
120
|
+
declare const runWithContext: <T>(ctx: ObservabilityContext, fn: () => T | Promise<T>) => T | Promise<T>;
|
|
121
|
+
/** Returns the currently-active context, or `undefined` outside one. */
|
|
122
|
+
declare const getCurrentContext: () => ObservabilityContext | undefined;
|
|
123
|
+
//#endregion
|
|
124
|
+
//#region node_modules/.pnpm/@logtape+logtape@2.1.1/node_modules/@logtape/logtape/dist/level.d.ts
|
|
125
|
+
//#region src/level.d.ts
|
|
126
|
+
declare const logLevels: readonly ["trace", "debug", "info", "warning", "error", "fatal"];
|
|
127
|
+
/**
|
|
128
|
+
* The severity level of a {@link LogRecord}.
|
|
129
|
+
*/
|
|
130
|
+
type LogLevel = typeof logLevels[number];
|
|
131
|
+
/**
|
|
132
|
+
* Lists all available log levels with the order of their severity.
|
|
133
|
+
* The `"trace"` level goes first, and the `"fatal"` level goes last.
|
|
134
|
+
* @returns A new copy of the array of log levels.
|
|
135
|
+
* @since 1.0.0
|
|
136
|
+
*/
|
|
137
|
+
//#endregion
|
|
138
|
+
//#region node_modules/.pnpm/@logtape+logtape@2.1.1/node_modules/@logtape/logtape/dist/record.d.ts
|
|
139
|
+
//#region src/record.d.ts
|
|
140
|
+
/**
|
|
141
|
+
* A log record.
|
|
142
|
+
*/
|
|
143
|
+
interface LogRecord {
|
|
144
|
+
/**
|
|
145
|
+
* The category of the logger that produced the log record.
|
|
146
|
+
*/
|
|
147
|
+
readonly category: readonly string[];
|
|
148
|
+
/**
|
|
149
|
+
* The log level.
|
|
150
|
+
*/
|
|
151
|
+
readonly level: LogLevel;
|
|
152
|
+
/**
|
|
153
|
+
* The log message. This is the result of substituting the message template
|
|
154
|
+
* with the values. The number of elements in this array is always odd,
|
|
155
|
+
* with the message template values interleaved between the substitution
|
|
156
|
+
* values.
|
|
157
|
+
*/
|
|
158
|
+
readonly message: readonly unknown[];
|
|
159
|
+
/**
|
|
160
|
+
* The raw log message. This is the original message template without any
|
|
161
|
+
* further processing. It can be either:
|
|
162
|
+
*
|
|
163
|
+
* - A string without any substitutions if the log record was created with
|
|
164
|
+
* a method call syntax, e.g., "Hello, {name}!" for
|
|
165
|
+
* `logger.info("Hello, {name}!", { name })`.
|
|
166
|
+
* - A template string array if the log record was created with a tagged
|
|
167
|
+
* template literal syntax, e.g., `["Hello, ", "!"]` for
|
|
168
|
+
* ``logger.info`Hello, ${name}!```.
|
|
169
|
+
*
|
|
170
|
+
* @since 0.6.0
|
|
171
|
+
*/
|
|
172
|
+
readonly rawMessage: string | TemplateStringsArray;
|
|
173
|
+
/**
|
|
174
|
+
* The timestamp of the log record in milliseconds since the Unix epoch.
|
|
175
|
+
*/
|
|
176
|
+
readonly timestamp: number;
|
|
177
|
+
/**
|
|
178
|
+
* The extra properties of the log record.
|
|
179
|
+
*/
|
|
180
|
+
readonly properties: Record<string, unknown>;
|
|
181
|
+
} //# sourceMappingURL=record.d.ts.map
|
|
182
|
+
//#endregion
|
|
183
|
+
//#endregion
|
|
184
|
+
//#region node_modules/.pnpm/@logtape+logtape@2.1.1/node_modules/@logtape/logtape/dist/sink.d.ts
|
|
185
|
+
//#region src/sink.d.ts
|
|
186
|
+
/**
|
|
187
|
+
* A sink is a function that accepts a log record and prints it somewhere.
|
|
188
|
+
* Thrown exceptions will be suppressed and then logged to the meta logger,
|
|
189
|
+
* a {@link Logger} with the category `["logtape", "meta"]`. (In that case,
|
|
190
|
+
* the meta log record will not be passed to the sink to avoid infinite
|
|
191
|
+
* recursion.)
|
|
192
|
+
*
|
|
193
|
+
* @param record The log record to sink.
|
|
194
|
+
*/
|
|
195
|
+
type Sink = (record: LogRecord) => void;
|
|
196
|
+
/**
|
|
197
|
+
* An async sink is a function that accepts a log record and asynchronously
|
|
198
|
+
* processes it. This type is used with {@link fromAsyncSink} to create
|
|
199
|
+
* a regular sink that properly handles asynchronous operations.
|
|
200
|
+
*
|
|
201
|
+
* @param record The log record to process asynchronously.
|
|
202
|
+
* @returns A promise that resolves when the record has been processed.
|
|
203
|
+
* @since 1.0.0
|
|
204
|
+
*/
|
|
205
|
+
//#endregion
|
|
206
|
+
//#region node_modules/.pnpm/@logtape+logtape@2.1.1/node_modules/@logtape/logtape/dist/logger.d.ts
|
|
207
|
+
/**
|
|
208
|
+
* A logger interface. It provides methods to log messages at different
|
|
209
|
+
* severity levels.
|
|
210
|
+
*
|
|
211
|
+
* ```typescript
|
|
212
|
+
* const logger = getLogger("category");
|
|
213
|
+
* logger.trace `A trace message with ${value}`
|
|
214
|
+
* logger.debug `A debug message with ${value}.`;
|
|
215
|
+
* logger.info `An info message with ${value}.`;
|
|
216
|
+
* logger.warn `A warning message with ${value}.`;
|
|
217
|
+
* logger.error `An error message with ${value}.`;
|
|
218
|
+
* logger.fatal `A fatal error message with ${value}.`;
|
|
219
|
+
* ```
|
|
220
|
+
*
|
|
221
|
+
* Callback-based string-message overloads should be treated as
|
|
222
|
+
* fire-and-forget. Async callbacks return `Promise<void>`, and when a
|
|
223
|
+
* callback is filtered out because the level is disabled an implementation may
|
|
224
|
+
* still return an already-resolved promise so the async path remains awaitable
|
|
225
|
+
* without invoking the callback. Call sites should not branch on these
|
|
226
|
+
* return values.
|
|
227
|
+
*/
|
|
228
|
+
interface Logger {
|
|
229
|
+
/**
|
|
230
|
+
* The category of the logger. It is an array of strings.
|
|
231
|
+
*/
|
|
232
|
+
readonly category: readonly string[];
|
|
233
|
+
/**
|
|
234
|
+
* The logger with the supercategory of the current logger. If the current
|
|
235
|
+
* logger is the root logger, this is `null`.
|
|
236
|
+
*/
|
|
237
|
+
readonly parent: Logger | null;
|
|
238
|
+
/**
|
|
239
|
+
* Get a child logger with the given subcategory.
|
|
240
|
+
*
|
|
241
|
+
* ```typescript
|
|
242
|
+
* const logger = getLogger("category");
|
|
243
|
+
* const subLogger = logger.getChild("sub-category");
|
|
244
|
+
* ```
|
|
245
|
+
*
|
|
246
|
+
* The above code is equivalent to:
|
|
247
|
+
*
|
|
248
|
+
* ```typescript
|
|
249
|
+
* const logger = getLogger("category");
|
|
250
|
+
* const subLogger = getLogger(["category", "sub-category"]);
|
|
251
|
+
* ```
|
|
252
|
+
*
|
|
253
|
+
* @param subcategory The subcategory.
|
|
254
|
+
* @returns The child logger.
|
|
255
|
+
*/
|
|
256
|
+
getChild(subcategory: string | readonly [string] | readonly [string, ...string[]]): Logger;
|
|
257
|
+
/**
|
|
258
|
+
* Get a logger with contextual properties. This is useful for
|
|
259
|
+
* log multiple messages with the shared set of properties.
|
|
260
|
+
*
|
|
261
|
+
* ```typescript
|
|
262
|
+
* const logger = getLogger("category");
|
|
263
|
+
* const ctx = logger.with({ foo: 123, bar: "abc" });
|
|
264
|
+
* ctx.info("A message with {foo} and {bar}.");
|
|
265
|
+
* ctx.warn("Another message with {foo}, {bar}, and {baz}.", { baz: true });
|
|
266
|
+
* ```
|
|
267
|
+
*
|
|
268
|
+
* The above code is equivalent to:
|
|
269
|
+
*
|
|
270
|
+
* ```typescript
|
|
271
|
+
* const logger = getLogger("category");
|
|
272
|
+
* logger.info("A message with {foo} and {bar}.", { foo: 123, bar: "abc" });
|
|
273
|
+
* logger.warn(
|
|
274
|
+
* "Another message with {foo}, {bar}, and {baz}.",
|
|
275
|
+
* { foo: 123, bar: "abc", baz: true },
|
|
276
|
+
* );
|
|
277
|
+
* ```
|
|
278
|
+
*
|
|
279
|
+
* @param properties
|
|
280
|
+
* @returns
|
|
281
|
+
* @since 0.5.0
|
|
282
|
+
*/
|
|
283
|
+
with(properties: Record<string, unknown>): Logger;
|
|
284
|
+
/**
|
|
285
|
+
* Log a trace message. Use this as a template string prefix.
|
|
286
|
+
*
|
|
287
|
+
* ```typescript
|
|
288
|
+
* logger.trace `A trace message with ${value}.`;
|
|
289
|
+
* ```
|
|
290
|
+
*
|
|
291
|
+
* @param message The message template strings array.
|
|
292
|
+
* @param values The message template values.
|
|
293
|
+
* @since 0.12.0
|
|
294
|
+
*/
|
|
295
|
+
trace(message: TemplateStringsArray, ...values: readonly unknown[]): void;
|
|
296
|
+
/**
|
|
297
|
+
* Log a trace message with properties.
|
|
298
|
+
*
|
|
299
|
+
* ```typescript
|
|
300
|
+
* logger.trace('A trace message with {value}.', { value });
|
|
301
|
+
* ```
|
|
302
|
+
*
|
|
303
|
+
* If the properties are expensive to compute, you can pass a callback that
|
|
304
|
+
* returns the properties:
|
|
305
|
+
*
|
|
306
|
+
* ```typescript
|
|
307
|
+
* logger.trace(
|
|
308
|
+
* 'A trace message with {value}.',
|
|
309
|
+
* () => ({ value: expensiveComputation() })
|
|
310
|
+
* );
|
|
311
|
+
* ```
|
|
312
|
+
*
|
|
313
|
+
* @param message The message template. Placeholders to be replaced with
|
|
314
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
315
|
+
* `{value}`).
|
|
316
|
+
* @param properties The values to replace placeholders with. For lazy
|
|
317
|
+
* evaluation, this can be a callback that returns the
|
|
318
|
+
* properties.
|
|
319
|
+
* @since 0.12.0
|
|
320
|
+
*/
|
|
321
|
+
trace(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
322
|
+
/**
|
|
323
|
+
* Log a trace message with properties computed asynchronously.
|
|
324
|
+
*
|
|
325
|
+
* Use this when the properties require async operations to compute:
|
|
326
|
+
*
|
|
327
|
+
* ```typescript
|
|
328
|
+
* await logger.trace(
|
|
329
|
+
* 'A trace message with {value}.',
|
|
330
|
+
* async () => ({ value: await fetchValue() })
|
|
331
|
+
* );
|
|
332
|
+
* ```
|
|
333
|
+
*
|
|
334
|
+
* @param message The message template. Placeholders to be replaced with
|
|
335
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
336
|
+
* `{value}`).
|
|
337
|
+
* @param properties An async callback that returns the properties.
|
|
338
|
+
* @returns A promise that resolves when the log is written.
|
|
339
|
+
* @since 2.0.0
|
|
340
|
+
*/
|
|
341
|
+
trace(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
342
|
+
/**
|
|
343
|
+
* Log a trace values with no message. This is useful when you
|
|
344
|
+
* want to log properties without a message, e.g., when you want to log
|
|
345
|
+
* the context of a request or an operation.
|
|
346
|
+
*
|
|
347
|
+
* ```typescript
|
|
348
|
+
* logger.trace({ method: 'GET', url: '/api/v1/resource' });
|
|
349
|
+
* ```
|
|
350
|
+
*
|
|
351
|
+
* Note that this is a shorthand for:
|
|
352
|
+
*
|
|
353
|
+
* ```typescript
|
|
354
|
+
* logger.trace('{*}', { method: 'GET', url: '/api/v1/resource' });
|
|
355
|
+
* ```
|
|
356
|
+
*
|
|
357
|
+
* If the properties are expensive to compute, you cannot use this shorthand
|
|
358
|
+
* and should use the following syntax instead:
|
|
359
|
+
*
|
|
360
|
+
* ```typescript
|
|
361
|
+
* logger.trace('{*}', () => ({
|
|
362
|
+
* method: expensiveMethod(),
|
|
363
|
+
* url: expensiveUrl(),
|
|
364
|
+
* }));
|
|
365
|
+
* ```
|
|
366
|
+
*
|
|
367
|
+
* @param properties The values to log. Note that this does not take
|
|
368
|
+
* a callback.
|
|
369
|
+
* @since 0.12.0
|
|
370
|
+
*/
|
|
371
|
+
trace(properties: Record<string, unknown>): void;
|
|
372
|
+
/**
|
|
373
|
+
* Lazily log a trace message. Use this when the message values are expensive
|
|
374
|
+
* to compute and should only be computed if the message is actually logged.
|
|
375
|
+
*
|
|
376
|
+
* ```typescript
|
|
377
|
+
* logger.trace(l => l`A trace message with ${expensiveValue()}.`);
|
|
378
|
+
* ```
|
|
379
|
+
*
|
|
380
|
+
* @param callback A callback that returns the message template prefix.
|
|
381
|
+
* @throws {TypeError} If no log record was made inside the callback.
|
|
382
|
+
* @since 0.12.0
|
|
383
|
+
*/
|
|
384
|
+
trace(callback: LogCallback): void;
|
|
385
|
+
/**
|
|
386
|
+
* Log a debug message. Use this as a template string prefix.
|
|
387
|
+
*
|
|
388
|
+
* ```typescript
|
|
389
|
+
* logger.debug `A debug message with ${value}.`;
|
|
390
|
+
* ```
|
|
391
|
+
*
|
|
392
|
+
* @param message The message template strings array.
|
|
393
|
+
* @param values The message template values.
|
|
394
|
+
*/
|
|
395
|
+
debug(message: TemplateStringsArray, ...values: readonly unknown[]): void;
|
|
396
|
+
/**
|
|
397
|
+
* Log a debug message with properties.
|
|
398
|
+
*
|
|
399
|
+
* ```typescript
|
|
400
|
+
* logger.debug('A debug message with {value}.', { value });
|
|
401
|
+
* ```
|
|
402
|
+
*
|
|
403
|
+
* If the properties are expensive to compute, you can pass a callback that
|
|
404
|
+
* returns the properties:
|
|
405
|
+
*
|
|
406
|
+
* ```typescript
|
|
407
|
+
* logger.debug(
|
|
408
|
+
* 'A debug message with {value}.',
|
|
409
|
+
* () => ({ value: expensiveComputation() })
|
|
410
|
+
* );
|
|
411
|
+
* ```
|
|
412
|
+
*
|
|
413
|
+
* @param message The message template. Placeholders to be replaced with
|
|
414
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
415
|
+
* `{value}`).
|
|
416
|
+
* @param properties The values to replace placeholders with. For lazy
|
|
417
|
+
* evaluation, this can be a callback that returns the
|
|
418
|
+
* properties.
|
|
419
|
+
*/
|
|
420
|
+
debug(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
421
|
+
/**
|
|
422
|
+
* Log a debug message with properties computed asynchronously.
|
|
423
|
+
*
|
|
424
|
+
* Use this when the properties require async operations to compute:
|
|
425
|
+
*
|
|
426
|
+
* ```typescript
|
|
427
|
+
* await logger.debug(
|
|
428
|
+
* 'A debug message with {value}.',
|
|
429
|
+
* async () => ({ value: await fetchValue() })
|
|
430
|
+
* );
|
|
431
|
+
* ```
|
|
432
|
+
*
|
|
433
|
+
* @param message The message template. Placeholders to be replaced with
|
|
434
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
435
|
+
* `{value}`).
|
|
436
|
+
* @param properties An async callback that returns the properties.
|
|
437
|
+
* @returns A promise that resolves when the log is written.
|
|
438
|
+
* @since 2.0.0
|
|
439
|
+
*/
|
|
440
|
+
debug(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
441
|
+
/**
|
|
442
|
+
* Log a debug values with no message. This is useful when you
|
|
443
|
+
* want to log properties without a message, e.g., when you want to log
|
|
444
|
+
* the context of a request or an operation.
|
|
445
|
+
*
|
|
446
|
+
* ```typescript
|
|
447
|
+
* logger.debug({ method: 'GET', url: '/api/v1/resource' });
|
|
448
|
+
* ```
|
|
449
|
+
*
|
|
450
|
+
* Note that this is a shorthand for:
|
|
451
|
+
*
|
|
452
|
+
* ```typescript
|
|
453
|
+
* logger.debug('{*}', { method: 'GET', url: '/api/v1/resource' });
|
|
454
|
+
* ```
|
|
455
|
+
*
|
|
456
|
+
* If the properties are expensive to compute, you cannot use this shorthand
|
|
457
|
+
* and should use the following syntax instead:
|
|
458
|
+
*
|
|
459
|
+
* ```typescript
|
|
460
|
+
* logger.debug('{*}', () => ({
|
|
461
|
+
* method: expensiveMethod(),
|
|
462
|
+
* url: expensiveUrl(),
|
|
463
|
+
* }));
|
|
464
|
+
* ```
|
|
465
|
+
*
|
|
466
|
+
* @param properties The values to log. Note that this does not take
|
|
467
|
+
* a callback.
|
|
468
|
+
* @since 0.11.0
|
|
469
|
+
*/
|
|
470
|
+
debug(properties: Record<string, unknown>): void;
|
|
471
|
+
/**
|
|
472
|
+
* Lazily log a debug message. Use this when the message values are expensive
|
|
473
|
+
* to compute and should only be computed if the message is actually logged.
|
|
474
|
+
*
|
|
475
|
+
* ```typescript
|
|
476
|
+
* logger.debug(l => l`A debug message with ${expensiveValue()}.`);
|
|
477
|
+
* ```
|
|
478
|
+
*
|
|
479
|
+
* @param callback A callback that returns the message template prefix.
|
|
480
|
+
* @throws {TypeError} If no log record was made inside the callback.
|
|
481
|
+
*/
|
|
482
|
+
debug(callback: LogCallback): void;
|
|
483
|
+
/**
|
|
484
|
+
* Log an informational message. Use this as a template string prefix.
|
|
485
|
+
*
|
|
486
|
+
* ```typescript
|
|
487
|
+
* logger.info `An info message with ${value}.`;
|
|
488
|
+
* ```
|
|
489
|
+
*
|
|
490
|
+
* @param message The message template strings array.
|
|
491
|
+
* @param values The message template values.
|
|
492
|
+
*/
|
|
493
|
+
info(message: TemplateStringsArray, ...values: readonly unknown[]): void;
|
|
494
|
+
/**
|
|
495
|
+
* Log an informational message with properties.
|
|
496
|
+
*
|
|
497
|
+
* ```typescript
|
|
498
|
+
* logger.info('An info message with {value}.', { value });
|
|
499
|
+
* ```
|
|
500
|
+
*
|
|
501
|
+
* If the properties are expensive to compute, you can pass a callback that
|
|
502
|
+
* returns the properties:
|
|
503
|
+
*
|
|
504
|
+
* ```typescript
|
|
505
|
+
* logger.info(
|
|
506
|
+
* 'An info message with {value}.',
|
|
507
|
+
* () => ({ value: expensiveComputation() })
|
|
508
|
+
* );
|
|
509
|
+
* ```
|
|
510
|
+
*
|
|
511
|
+
* @param message The message template. Placeholders to be replaced with
|
|
512
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
513
|
+
* `{value}`).
|
|
514
|
+
* @param properties The values to replace placeholders with. For lazy
|
|
515
|
+
* evaluation, this can be a callback that returns the
|
|
516
|
+
* properties.
|
|
517
|
+
*/
|
|
518
|
+
info(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
519
|
+
/**
|
|
520
|
+
* Log an informational message with properties computed asynchronously.
|
|
521
|
+
*
|
|
522
|
+
* Use this when the properties require async operations to compute:
|
|
523
|
+
*
|
|
524
|
+
* ```typescript
|
|
525
|
+
* await logger.info(
|
|
526
|
+
* 'An info message with {value}.',
|
|
527
|
+
* async () => ({ value: await fetchValue() })
|
|
528
|
+
* );
|
|
529
|
+
* ```
|
|
530
|
+
*
|
|
531
|
+
* @param message The message template. Placeholders to be replaced with
|
|
532
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
533
|
+
* `{value}`).
|
|
534
|
+
* @param properties An async callback that returns the properties.
|
|
535
|
+
* @returns A promise that resolves when the log is written.
|
|
536
|
+
* @since 2.0.0
|
|
537
|
+
*/
|
|
538
|
+
info(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
539
|
+
/**
|
|
540
|
+
* Log an informational values with no message. This is useful when you
|
|
541
|
+
* want to log properties without a message, e.g., when you want to log
|
|
542
|
+
* the context of a request or an operation.
|
|
543
|
+
*
|
|
544
|
+
* ```typescript
|
|
545
|
+
* logger.info({ method: 'GET', url: '/api/v1/resource' });
|
|
546
|
+
* ```
|
|
547
|
+
*
|
|
548
|
+
* Note that this is a shorthand for:
|
|
549
|
+
*
|
|
550
|
+
* ```typescript
|
|
551
|
+
* logger.info('{*}', { method: 'GET', url: '/api/v1/resource' });
|
|
552
|
+
* ```
|
|
553
|
+
*
|
|
554
|
+
* If the properties are expensive to compute, you cannot use this shorthand
|
|
555
|
+
* and should use the following syntax instead:
|
|
556
|
+
*
|
|
557
|
+
* ```typescript
|
|
558
|
+
* logger.info('{*}', () => ({
|
|
559
|
+
* method: expensiveMethod(),
|
|
560
|
+
* url: expensiveUrl(),
|
|
561
|
+
* }));
|
|
562
|
+
* ```
|
|
563
|
+
*
|
|
564
|
+
* @param properties The values to log. Note that this does not take
|
|
565
|
+
* a callback.
|
|
566
|
+
* @since 0.11.0
|
|
567
|
+
*/
|
|
568
|
+
info(properties: Record<string, unknown>): void;
|
|
569
|
+
/**
|
|
570
|
+
* Lazily log an informational message. Use this when the message values are
|
|
571
|
+
* expensive to compute and should only be computed if the message is actually
|
|
572
|
+
* logged.
|
|
573
|
+
*
|
|
574
|
+
* ```typescript
|
|
575
|
+
* logger.info(l => l`An info message with ${expensiveValue()}.`);
|
|
576
|
+
* ```
|
|
577
|
+
*
|
|
578
|
+
* @param callback A callback that returns the message template prefix.
|
|
579
|
+
* @throws {TypeError} If no log record was made inside the callback.
|
|
580
|
+
*/
|
|
581
|
+
info(callback: LogCallback): void;
|
|
582
|
+
/**
|
|
583
|
+
* Log a warning.
|
|
584
|
+
*
|
|
585
|
+
* This overload is a shorthand for logging an {@link Error} instance as a
|
|
586
|
+
* structured property.
|
|
587
|
+
*
|
|
588
|
+
* ```typescript
|
|
589
|
+
* logger.warn(new Error("Oops"));
|
|
590
|
+
* ```
|
|
591
|
+
*
|
|
592
|
+
* Note that this uses `{error.message}` as the default message template.
|
|
593
|
+
* If you want to include the stack trace in text output, include `{error}`
|
|
594
|
+
* in the message template instead.
|
|
595
|
+
*
|
|
596
|
+
* @param error The error to log.
|
|
597
|
+
* @since 2.0.0
|
|
598
|
+
*/
|
|
599
|
+
warn(error: Error): void;
|
|
600
|
+
/**
|
|
601
|
+
* Log a warning with additional properties.
|
|
602
|
+
*
|
|
603
|
+
* This overload is a shorthand for logging an {@link Error} instance as a
|
|
604
|
+
* structured property while also adding extra properties.
|
|
605
|
+
*
|
|
606
|
+
* ```typescript
|
|
607
|
+
* logger.warn(new Error("Oops"), { requestId });
|
|
608
|
+
* ```
|
|
609
|
+
*
|
|
610
|
+
* @param error The error to log.
|
|
611
|
+
* @param properties Additional properties to log alongside the error.
|
|
612
|
+
* @since 2.1.0
|
|
613
|
+
*/
|
|
614
|
+
warn(error: Error, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
615
|
+
/**
|
|
616
|
+
* Log a warning with additional properties computed asynchronously.
|
|
617
|
+
*
|
|
618
|
+
* @param error The error to log.
|
|
619
|
+
* @param properties An async callback that returns the properties.
|
|
620
|
+
* @returns A promise that resolves when the log is written.
|
|
621
|
+
* @since 2.1.0
|
|
622
|
+
*/
|
|
623
|
+
warn(error: Error, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
624
|
+
/**
|
|
625
|
+
* Log a warning message with an {@link Error}.
|
|
626
|
+
*
|
|
627
|
+
* ```typescript
|
|
628
|
+
* logger.warn("Failed to do something", new Error("Oops"));
|
|
629
|
+
* ```
|
|
630
|
+
*
|
|
631
|
+
* @param message The message.
|
|
632
|
+
* @param error The error to log.
|
|
633
|
+
* @since 2.0.0
|
|
634
|
+
*/
|
|
635
|
+
warn(message: string, error: Error): void;
|
|
636
|
+
/**
|
|
637
|
+
* Log a warning message. Use this as a template string prefix.
|
|
638
|
+
*
|
|
639
|
+
* ```typescript
|
|
640
|
+
* logger.warn `A warning message with ${value}.`;
|
|
641
|
+
* ```
|
|
642
|
+
*
|
|
643
|
+
* @param message The message template strings array.
|
|
644
|
+
* @param values The message template values.
|
|
645
|
+
*/
|
|
646
|
+
warn(message: TemplateStringsArray, ...values: readonly unknown[]): void;
|
|
647
|
+
/**
|
|
648
|
+
* Log a warning message with properties.
|
|
649
|
+
*
|
|
650
|
+
* ```typescript
|
|
651
|
+
* logger.warn('A warning message with {value}.', { value });
|
|
652
|
+
* ```
|
|
653
|
+
*
|
|
654
|
+
* If the properties are expensive to compute, you can pass a callback that
|
|
655
|
+
* returns the properties:
|
|
656
|
+
*
|
|
657
|
+
* ```typescript
|
|
658
|
+
* logger.warn(
|
|
659
|
+
* 'A warning message with {value}.',
|
|
660
|
+
* () => ({ value: expensiveComputation() })
|
|
661
|
+
* );
|
|
662
|
+
* ```
|
|
663
|
+
*
|
|
664
|
+
* @param message The message template. Placeholders to be replaced with
|
|
665
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
666
|
+
* `{value}`).
|
|
667
|
+
* @param properties The values to replace placeholders with. For lazy
|
|
668
|
+
* evaluation, this can be a callback that returns the
|
|
669
|
+
* properties.
|
|
670
|
+
*/
|
|
671
|
+
warn(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
672
|
+
/**
|
|
673
|
+
* Log a warning message with properties computed asynchronously.
|
|
674
|
+
*
|
|
675
|
+
* Use this when the properties require async operations to compute:
|
|
676
|
+
*
|
|
677
|
+
* ```typescript
|
|
678
|
+
* await logger.warn(
|
|
679
|
+
* 'A warning message with {value}.',
|
|
680
|
+
* async () => ({ value: await fetchValue() })
|
|
681
|
+
* );
|
|
682
|
+
* ```
|
|
683
|
+
*
|
|
684
|
+
* @param message The message template. Placeholders to be replaced with
|
|
685
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
686
|
+
* `{value}`).
|
|
687
|
+
* @param properties An async callback that returns the properties.
|
|
688
|
+
* @returns A promise that resolves when the log is written.
|
|
689
|
+
* @since 2.0.0
|
|
690
|
+
*/
|
|
691
|
+
warn(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
692
|
+
/**
|
|
693
|
+
* Log a warning values with no message. This is useful when you
|
|
694
|
+
* want to log properties without a message, e.g., when you want to log
|
|
695
|
+
* the context of a request or an operation.
|
|
696
|
+
*
|
|
697
|
+
* ```typescript
|
|
698
|
+
* logger.warn({ method: 'GET', url: '/api/v1/resource' });
|
|
699
|
+
* ```
|
|
700
|
+
*
|
|
701
|
+
* Note that this is a shorthand for:
|
|
702
|
+
*
|
|
703
|
+
* ```typescript
|
|
704
|
+
* logger.warn('{*}', { method: 'GET', url: '/api/v1/resource' });
|
|
705
|
+
* ```
|
|
706
|
+
*
|
|
707
|
+
* If the properties are expensive to compute, you cannot use this shorthand
|
|
708
|
+
* and should use the following syntax instead:
|
|
709
|
+
*
|
|
710
|
+
* ```typescript
|
|
711
|
+
* logger.warn('{*}', () => ({
|
|
712
|
+
* method: expensiveMethod(),
|
|
713
|
+
* url: expensiveUrl(),
|
|
714
|
+
* }));
|
|
715
|
+
* ```
|
|
716
|
+
*
|
|
717
|
+
* @param properties The values to log. Note that this does not take
|
|
718
|
+
* a callback.
|
|
719
|
+
* @since 0.11.0
|
|
720
|
+
*/
|
|
721
|
+
warn(properties: Record<string, unknown>): void;
|
|
722
|
+
/**
|
|
723
|
+
* Lazily log a warning message. Use this when the message values are
|
|
724
|
+
* expensive to compute and should only be computed if the message is actually
|
|
725
|
+
* logged.
|
|
726
|
+
*
|
|
727
|
+
* ```typescript
|
|
728
|
+
* logger.warn(l => l`A warning message with ${expensiveValue()}.`);
|
|
729
|
+
* ```
|
|
730
|
+
*
|
|
731
|
+
* @param callback A callback that returns the message template prefix.
|
|
732
|
+
* @throws {TypeError} If no log record was made inside the callback.
|
|
733
|
+
*/
|
|
734
|
+
warn(callback: LogCallback): void;
|
|
735
|
+
/**
|
|
736
|
+
* Log a warning.
|
|
737
|
+
*
|
|
738
|
+
* This overload is a shorthand for logging an {@link Error} instance as a
|
|
739
|
+
* structured property.
|
|
740
|
+
*
|
|
741
|
+
* ```typescript
|
|
742
|
+
* logger.warning(new Error("Oops"));
|
|
743
|
+
* ```
|
|
744
|
+
*
|
|
745
|
+
* Note that this uses `{error.message}` as the default message template.
|
|
746
|
+
* If you want to include the stack trace in text output, include `{error}`
|
|
747
|
+
* in the message template instead.
|
|
748
|
+
*
|
|
749
|
+
* @param error The error to log.
|
|
750
|
+
* @since 2.0.0
|
|
751
|
+
*/
|
|
752
|
+
warning(error: Error): void;
|
|
753
|
+
/**
|
|
754
|
+
* Log a warning with additional properties.
|
|
755
|
+
*
|
|
756
|
+
* This overload is a shorthand for logging an {@link Error} instance as a
|
|
757
|
+
* structured property while also adding extra properties.
|
|
758
|
+
*
|
|
759
|
+
* ```typescript
|
|
760
|
+
* logger.warning(new Error("Oops"), { requestId });
|
|
761
|
+
* ```
|
|
762
|
+
*
|
|
763
|
+
* @param error The error to log.
|
|
764
|
+
* @param properties Additional properties to log alongside the error.
|
|
765
|
+
* @since 2.1.0
|
|
766
|
+
*/
|
|
767
|
+
warning(error: Error, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
768
|
+
/**
|
|
769
|
+
* Log a warning with additional properties computed asynchronously.
|
|
770
|
+
*
|
|
771
|
+
* @param error The error to log.
|
|
772
|
+
* @param properties An async callback that returns the properties.
|
|
773
|
+
* @returns A promise that resolves when the log is written.
|
|
774
|
+
* @since 2.1.0
|
|
775
|
+
*/
|
|
776
|
+
warning(error: Error, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
777
|
+
/**
|
|
778
|
+
* Log a warning message with an {@link Error}.
|
|
779
|
+
*
|
|
780
|
+
* ```typescript
|
|
781
|
+
* logger.warning("Failed to do something", new Error("Oops"));
|
|
782
|
+
* ```
|
|
783
|
+
*
|
|
784
|
+
* @param message The message.
|
|
785
|
+
* @param error The error to log.
|
|
786
|
+
* @since 2.0.0
|
|
787
|
+
*/
|
|
788
|
+
warning(message: string, error: Error): void;
|
|
789
|
+
/**
|
|
790
|
+
* Log a warning message. Use this as a template string prefix.
|
|
791
|
+
*
|
|
792
|
+
* ```typescript
|
|
793
|
+
* logger.warning `A warning message with ${value}.`;
|
|
794
|
+
* ```
|
|
795
|
+
*
|
|
796
|
+
* @param message The message template strings array.
|
|
797
|
+
* @param values The message template values.
|
|
798
|
+
* @since 0.12.0
|
|
799
|
+
*/
|
|
800
|
+
warning(message: TemplateStringsArray, ...values: readonly unknown[]): void;
|
|
801
|
+
/**
|
|
802
|
+
* Log a warning message with properties.
|
|
803
|
+
*
|
|
804
|
+
* ```typescript
|
|
805
|
+
* logger.warning('A warning message with {value}.', { value });
|
|
806
|
+
* ```
|
|
807
|
+
*
|
|
808
|
+
* If the properties are expensive to compute, you can pass a callback that
|
|
809
|
+
* returns the properties:
|
|
810
|
+
*
|
|
811
|
+
* ```typescript
|
|
812
|
+
* logger.warning(
|
|
813
|
+
* 'A warning message with {value}.',
|
|
814
|
+
* () => ({ value: expensiveComputation() })
|
|
815
|
+
* );
|
|
816
|
+
* ```
|
|
817
|
+
*
|
|
818
|
+
* @param message The message template. Placeholders to be replaced with
|
|
819
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
820
|
+
* `{value}`).
|
|
821
|
+
* @param properties The values to replace placeholders with. For lazy
|
|
822
|
+
* evaluation, this can be a callback that returns the
|
|
823
|
+
* properties.
|
|
824
|
+
* @since 0.12.0
|
|
825
|
+
*/
|
|
826
|
+
warning(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
827
|
+
/**
|
|
828
|
+
* Log a warning message with properties computed asynchronously.
|
|
829
|
+
*
|
|
830
|
+
* Use this when the properties require async operations to compute:
|
|
831
|
+
*
|
|
832
|
+
* ```typescript
|
|
833
|
+
* await logger.warning(
|
|
834
|
+
* 'A warning message with {value}.',
|
|
835
|
+
* async () => ({ value: await fetchValue() })
|
|
836
|
+
* );
|
|
837
|
+
* ```
|
|
838
|
+
*
|
|
839
|
+
* @param message The message template. Placeholders to be replaced with
|
|
840
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
841
|
+
* `{value}`).
|
|
842
|
+
* @param properties An async callback that returns the properties.
|
|
843
|
+
* @returns A promise that resolves when the log is written.
|
|
844
|
+
* @since 2.0.0
|
|
845
|
+
*/
|
|
846
|
+
warning(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
847
|
+
/**
|
|
848
|
+
* Log a warning values with no message. This is useful when you
|
|
849
|
+
* want to log properties without a message, e.g., when you want to log
|
|
850
|
+
* the context of a request or an operation.
|
|
851
|
+
*
|
|
852
|
+
* ```typescript
|
|
853
|
+
* logger.warning({ method: 'GET', url: '/api/v1/resource' });
|
|
854
|
+
* ```
|
|
855
|
+
*
|
|
856
|
+
* Note that this is a shorthand for:
|
|
857
|
+
*
|
|
858
|
+
* ```typescript
|
|
859
|
+
* logger.warning('{*}', { method: 'GET', url: '/api/v1/resource' });
|
|
860
|
+
* ```
|
|
861
|
+
*
|
|
862
|
+
* If the properties are expensive to compute, you cannot use this shorthand
|
|
863
|
+
* and should use the following syntax instead:
|
|
864
|
+
*
|
|
865
|
+
* ```typescript
|
|
866
|
+
* logger.warning('{*}', () => ({
|
|
867
|
+
* method: expensiveMethod(),
|
|
868
|
+
* url: expensiveUrl(),
|
|
869
|
+
* }));
|
|
870
|
+
* ```
|
|
871
|
+
*
|
|
872
|
+
* @param properties The values to log. Note that this does not take
|
|
873
|
+
* a callback.
|
|
874
|
+
* @since 0.12.0
|
|
875
|
+
*/
|
|
876
|
+
warning(properties: Record<string, unknown>): void;
|
|
877
|
+
/**
|
|
878
|
+
* Lazily log a warning message. Use this when the message values are
|
|
879
|
+
* expensive to compute and should only be computed if the message is actually
|
|
880
|
+
* logged.
|
|
881
|
+
*
|
|
882
|
+
* ```typescript
|
|
883
|
+
* logger.warning(l => l`A warning message with ${expensiveValue()}.`);
|
|
884
|
+
* ```
|
|
885
|
+
*
|
|
886
|
+
* @param callback A callback that returns the message template prefix.
|
|
887
|
+
* @throws {TypeError} If no log record was made inside the callback.
|
|
888
|
+
* @since 0.12.0
|
|
889
|
+
*/
|
|
890
|
+
warning(callback: LogCallback): void;
|
|
891
|
+
/**
|
|
892
|
+
* Log an error.
|
|
893
|
+
*
|
|
894
|
+
* This overload is a shorthand for logging an {@link Error} instance as a
|
|
895
|
+
* structured property.
|
|
896
|
+
*
|
|
897
|
+
* ```typescript
|
|
898
|
+
* logger.error(new Error("Oops"));
|
|
899
|
+
* ```
|
|
900
|
+
*
|
|
901
|
+
* Note that this uses `{error.message}` as the default message template.
|
|
902
|
+
* If you want to include the stack trace in text output, include `{error}`
|
|
903
|
+
* in the message template instead.
|
|
904
|
+
*
|
|
905
|
+
* @param error The error to log.
|
|
906
|
+
* @since 2.0.0
|
|
907
|
+
*/
|
|
908
|
+
error(error: Error): void;
|
|
909
|
+
/**
|
|
910
|
+
* Log an error with additional properties.
|
|
911
|
+
*
|
|
912
|
+
* This overload is a shorthand for logging an {@link Error} instance as a
|
|
913
|
+
* structured property while also adding extra properties.
|
|
914
|
+
*
|
|
915
|
+
* ```typescript
|
|
916
|
+
* logger.error(new Error("Oops"), { requestId });
|
|
917
|
+
* ```
|
|
918
|
+
*
|
|
919
|
+
* If the properties are expensive to compute, you can pass a callback that
|
|
920
|
+
* returns the properties:
|
|
921
|
+
*
|
|
922
|
+
* ```typescript
|
|
923
|
+
* logger.error(
|
|
924
|
+
* new Error("Oops"),
|
|
925
|
+
* () => ({ requestId: expensiveLookup() })
|
|
926
|
+
* );
|
|
927
|
+
* ```
|
|
928
|
+
*
|
|
929
|
+
* @param error The error to log.
|
|
930
|
+
* @param properties Additional properties to log alongside the error.
|
|
931
|
+
* @since 2.1.0
|
|
932
|
+
*/
|
|
933
|
+
error(error: Error, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
934
|
+
/**
|
|
935
|
+
* Log an error with additional properties computed asynchronously.
|
|
936
|
+
*
|
|
937
|
+
* Use this when the properties require async operations to compute:
|
|
938
|
+
*
|
|
939
|
+
* ```typescript
|
|
940
|
+
* await logger.error(
|
|
941
|
+
* new Error("Oops"),
|
|
942
|
+
* async () => ({ requestId: await fetchRequestId() })
|
|
943
|
+
* );
|
|
944
|
+
* ```
|
|
945
|
+
*
|
|
946
|
+
* @param error The error to log.
|
|
947
|
+
* @param properties An async callback that returns the properties.
|
|
948
|
+
* @returns A promise that resolves when the log is written.
|
|
949
|
+
* @since 2.1.0
|
|
950
|
+
*/
|
|
951
|
+
error(error: Error, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
952
|
+
/**
|
|
953
|
+
* Log an error message with an {@link Error}.
|
|
954
|
+
*
|
|
955
|
+
* ```typescript
|
|
956
|
+
* logger.error("Failed to do something", new Error("Oops"));
|
|
957
|
+
* ```
|
|
958
|
+
*
|
|
959
|
+
* @param message The message.
|
|
960
|
+
* @param error The error to log.
|
|
961
|
+
* @since 2.0.0
|
|
962
|
+
*/
|
|
963
|
+
error(message: string, error: Error): void;
|
|
964
|
+
/**
|
|
965
|
+
* Log an error message. Use this as a template string prefix.
|
|
966
|
+
*
|
|
967
|
+
* ```typescript
|
|
968
|
+
* logger.error `An error message with ${value}.`;
|
|
969
|
+
* ```
|
|
970
|
+
*
|
|
971
|
+
* @param message The message template strings array.
|
|
972
|
+
* @param values The message template values.
|
|
973
|
+
*/
|
|
974
|
+
error(message: TemplateStringsArray, ...values: readonly unknown[]): void;
|
|
975
|
+
/**
|
|
976
|
+
* Log an error message with properties.
|
|
977
|
+
*
|
|
978
|
+
* ```typescript
|
|
979
|
+
* logger.warn('An error message with {value}.', { value });
|
|
980
|
+
* ```
|
|
981
|
+
*
|
|
982
|
+
* If the properties are expensive to compute, you can pass a callback that
|
|
983
|
+
* returns the properties:
|
|
984
|
+
*
|
|
985
|
+
* ```typescript
|
|
986
|
+
* logger.error(
|
|
987
|
+
* 'An error message with {value}.',
|
|
988
|
+
* () => ({ value: expensiveComputation() })
|
|
989
|
+
* );
|
|
990
|
+
* ```
|
|
991
|
+
*
|
|
992
|
+
* @param message The message template. Placeholders to be replaced with
|
|
993
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
994
|
+
* `{value}`).
|
|
995
|
+
* @param properties The values to replace placeholders with. For lazy
|
|
996
|
+
* evaluation, this can be a callback that returns the
|
|
997
|
+
* properties.
|
|
998
|
+
*/
|
|
999
|
+
error(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
1000
|
+
/**
|
|
1001
|
+
* Log an error message with properties computed asynchronously.
|
|
1002
|
+
*
|
|
1003
|
+
* Use this when the properties require async operations to compute:
|
|
1004
|
+
*
|
|
1005
|
+
* ```typescript
|
|
1006
|
+
* await logger.error(
|
|
1007
|
+
* 'An error message with {value}.',
|
|
1008
|
+
* async () => ({ value: await fetchValue() })
|
|
1009
|
+
* );
|
|
1010
|
+
* ```
|
|
1011
|
+
*
|
|
1012
|
+
* @param message The message template. Placeholders to be replaced with
|
|
1013
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
1014
|
+
* `{value}`).
|
|
1015
|
+
* @param properties An async callback that returns the properties.
|
|
1016
|
+
* @returns A promise that resolves when the log is written.
|
|
1017
|
+
* @since 2.0.0
|
|
1018
|
+
*/
|
|
1019
|
+
error(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
1020
|
+
/**
|
|
1021
|
+
* Log an error values with no message. This is useful when you
|
|
1022
|
+
* want to log properties without a message, e.g., when you want to log
|
|
1023
|
+
* the context of a request or an operation.
|
|
1024
|
+
*
|
|
1025
|
+
* ```typescript
|
|
1026
|
+
* logger.error({ method: 'GET', url: '/api/v1/resource' });
|
|
1027
|
+
* ```
|
|
1028
|
+
*
|
|
1029
|
+
* Note that this is a shorthand for:
|
|
1030
|
+
*
|
|
1031
|
+
* ```typescript
|
|
1032
|
+
* logger.error('{*}', { method: 'GET', url: '/api/v1/resource' });
|
|
1033
|
+
* ```
|
|
1034
|
+
*
|
|
1035
|
+
* If the properties are expensive to compute, you cannot use this shorthand
|
|
1036
|
+
* and should use the following syntax instead:
|
|
1037
|
+
*
|
|
1038
|
+
* ```typescript
|
|
1039
|
+
* logger.error('{*}', () => ({
|
|
1040
|
+
* method: expensiveMethod(),
|
|
1041
|
+
* url: expensiveUrl(),
|
|
1042
|
+
* }));
|
|
1043
|
+
* ```
|
|
1044
|
+
*
|
|
1045
|
+
* @param properties The values to log. Note that this does not take
|
|
1046
|
+
* a callback.
|
|
1047
|
+
* @since 0.11.0
|
|
1048
|
+
*/
|
|
1049
|
+
error(properties: Record<string, unknown>): void;
|
|
1050
|
+
/**
|
|
1051
|
+
* Lazily log an error message. Use this when the message values are
|
|
1052
|
+
* expensive to compute and should only be computed if the message is actually
|
|
1053
|
+
* logged.
|
|
1054
|
+
*
|
|
1055
|
+
* ```typescript
|
|
1056
|
+
* logger.error(l => l`An error message with ${expensiveValue()}.`);
|
|
1057
|
+
* ```
|
|
1058
|
+
*
|
|
1059
|
+
* @param callback A callback that returns the message template prefix.
|
|
1060
|
+
* @throws {TypeError} If no log record was made inside the callback.
|
|
1061
|
+
*/
|
|
1062
|
+
error(callback: LogCallback): void;
|
|
1063
|
+
/**
|
|
1064
|
+
* Log a fatal error.
|
|
1065
|
+
*
|
|
1066
|
+
* This overload is a shorthand for logging an {@link Error} instance as a
|
|
1067
|
+
* structured property.
|
|
1068
|
+
*
|
|
1069
|
+
* ```typescript
|
|
1070
|
+
* logger.fatal(new Error("Oops"));
|
|
1071
|
+
* ```
|
|
1072
|
+
*
|
|
1073
|
+
* Note that this uses `{error.message}` as the default message template.
|
|
1074
|
+
* If you want to include the stack trace in text output, include `{error}`
|
|
1075
|
+
* in the message template instead.
|
|
1076
|
+
*
|
|
1077
|
+
* @param error The error to log.
|
|
1078
|
+
* @since 2.0.0
|
|
1079
|
+
*/
|
|
1080
|
+
fatal(error: Error): void;
|
|
1081
|
+
/**
|
|
1082
|
+
* Log a fatal error with additional properties.
|
|
1083
|
+
*
|
|
1084
|
+
* This overload is a shorthand for logging an {@link Error} instance as a
|
|
1085
|
+
* structured property while also adding extra properties.
|
|
1086
|
+
*
|
|
1087
|
+
* ```typescript
|
|
1088
|
+
* logger.fatal(new Error("Oops"), { requestId });
|
|
1089
|
+
* ```
|
|
1090
|
+
*
|
|
1091
|
+
* @param error The error to log.
|
|
1092
|
+
* @param properties Additional properties to log alongside the error.
|
|
1093
|
+
* @since 2.1.0
|
|
1094
|
+
*/
|
|
1095
|
+
fatal(error: Error, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
1096
|
+
/**
|
|
1097
|
+
* Log a fatal error with additional properties computed asynchronously.
|
|
1098
|
+
*
|
|
1099
|
+
* @param error The error to log.
|
|
1100
|
+
* @param properties An async callback that returns the properties.
|
|
1101
|
+
* @returns A promise that resolves when the log is written.
|
|
1102
|
+
* @since 2.1.0
|
|
1103
|
+
*/
|
|
1104
|
+
fatal(error: Error, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
1105
|
+
/**
|
|
1106
|
+
* Log a fatal error message with an {@link Error}.
|
|
1107
|
+
*
|
|
1108
|
+
* ```typescript
|
|
1109
|
+
* logger.fatal("Failed to do something", new Error("Oops"));
|
|
1110
|
+
* ```
|
|
1111
|
+
*
|
|
1112
|
+
* @param message The message.
|
|
1113
|
+
* @param error The error to log.
|
|
1114
|
+
* @since 2.0.0
|
|
1115
|
+
*/
|
|
1116
|
+
fatal(message: string, error: Error): void;
|
|
1117
|
+
/**
|
|
1118
|
+
* Log a fatal error message. Use this as a template string prefix.
|
|
1119
|
+
*
|
|
1120
|
+
* ```typescript
|
|
1121
|
+
* logger.fatal `A fatal error message with ${value}.`;
|
|
1122
|
+
* ```
|
|
1123
|
+
*
|
|
1124
|
+
* @param message The message template strings array.
|
|
1125
|
+
* @param values The message template values.
|
|
1126
|
+
*/
|
|
1127
|
+
fatal(message: TemplateStringsArray, ...values: readonly unknown[]): void;
|
|
1128
|
+
/**
|
|
1129
|
+
* Log a fatal error message with properties.
|
|
1130
|
+
*
|
|
1131
|
+
* ```typescript
|
|
1132
|
+
* logger.warn('A fatal error message with {value}.', { value });
|
|
1133
|
+
* ```
|
|
1134
|
+
*
|
|
1135
|
+
* If the properties are expensive to compute, you can pass a callback that
|
|
1136
|
+
* returns the properties:
|
|
1137
|
+
*
|
|
1138
|
+
* ```typescript
|
|
1139
|
+
* logger.fatal(
|
|
1140
|
+
* 'A fatal error message with {value}.',
|
|
1141
|
+
* () => ({ value: expensiveComputation() })
|
|
1142
|
+
* );
|
|
1143
|
+
* ```
|
|
1144
|
+
*
|
|
1145
|
+
* @param message The message template. Placeholders to be replaced with
|
|
1146
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
1147
|
+
* `{value}`).
|
|
1148
|
+
* @param properties The values to replace placeholders with. For lazy
|
|
1149
|
+
* evaluation, this can be a callback that returns the
|
|
1150
|
+
* properties.
|
|
1151
|
+
*/
|
|
1152
|
+
fatal(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
|
|
1153
|
+
/**
|
|
1154
|
+
* Log a fatal error message with properties computed asynchronously.
|
|
1155
|
+
*
|
|
1156
|
+
* Use this when the properties require async operations to compute:
|
|
1157
|
+
*
|
|
1158
|
+
* ```typescript
|
|
1159
|
+
* await logger.fatal(
|
|
1160
|
+
* 'A fatal error message with {value}.',
|
|
1161
|
+
* async () => ({ value: await fetchValue() })
|
|
1162
|
+
* );
|
|
1163
|
+
* ```
|
|
1164
|
+
*
|
|
1165
|
+
* @param message The message template. Placeholders to be replaced with
|
|
1166
|
+
* `values` are indicated by keys in curly braces (e.g.,
|
|
1167
|
+
* `{value}`).
|
|
1168
|
+
* @param properties An async callback that returns the properties.
|
|
1169
|
+
* @returns A promise that resolves when the log is written.
|
|
1170
|
+
* @since 2.0.0
|
|
1171
|
+
*/
|
|
1172
|
+
fatal(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
|
|
1173
|
+
/**
|
|
1174
|
+
* Log a fatal error values with no message. This is useful when you
|
|
1175
|
+
* want to log properties without a message, e.g., when you want to log
|
|
1176
|
+
* the context of a request or an operation.
|
|
1177
|
+
*
|
|
1178
|
+
* ```typescript
|
|
1179
|
+
* logger.fatal({ method: 'GET', url: '/api/v1/resource' });
|
|
1180
|
+
* ```
|
|
1181
|
+
*
|
|
1182
|
+
* Note that this is a shorthand for:
|
|
1183
|
+
*
|
|
1184
|
+
* ```typescript
|
|
1185
|
+
* logger.fatal('{*}', { method: 'GET', url: '/api/v1/resource' });
|
|
1186
|
+
* ```
|
|
1187
|
+
*
|
|
1188
|
+
* If the properties are expensive to compute, you cannot use this shorthand
|
|
1189
|
+
* and should use the following syntax instead:
|
|
1190
|
+
*
|
|
1191
|
+
* ```typescript
|
|
1192
|
+
* logger.fatal('{*}', () => ({
|
|
1193
|
+
* method: expensiveMethod(),
|
|
1194
|
+
* url: expensiveUrl(),
|
|
1195
|
+
* }));
|
|
1196
|
+
* ```
|
|
1197
|
+
*
|
|
1198
|
+
* @param properties The values to log. Note that this does not take
|
|
1199
|
+
* a callback.
|
|
1200
|
+
* @since 0.11.0
|
|
1201
|
+
*/
|
|
1202
|
+
fatal(properties: Record<string, unknown>): void;
|
|
1203
|
+
/**
|
|
1204
|
+
* Lazily log a fatal error message. Use this when the message values are
|
|
1205
|
+
* expensive to compute and should only be computed if the message is actually
|
|
1206
|
+
* logged.
|
|
1207
|
+
*
|
|
1208
|
+
* ```typescript
|
|
1209
|
+
* logger.fatal(l => l`A fatal error message with ${expensiveValue()}.`);
|
|
1210
|
+
* ```
|
|
1211
|
+
*
|
|
1212
|
+
* @param callback A callback that returns the message template prefix.
|
|
1213
|
+
* @throws {TypeError} If no log record was made inside the callback.
|
|
1214
|
+
*/
|
|
1215
|
+
fatal(callback: LogCallback): void;
|
|
1216
|
+
/**
|
|
1217
|
+
* Emits a log record with custom fields while using this logger's
|
|
1218
|
+
* category.
|
|
1219
|
+
*
|
|
1220
|
+
* This is a low-level API for integration scenarios where you need full
|
|
1221
|
+
* control over the log record, particularly for preserving timestamps
|
|
1222
|
+
* from external systems.
|
|
1223
|
+
*
|
|
1224
|
+
* ```typescript
|
|
1225
|
+
* const logger = getLogger(["my-app", "integration"]);
|
|
1226
|
+
*
|
|
1227
|
+
* // Emit a log with a custom timestamp
|
|
1228
|
+
* logger.emit({
|
|
1229
|
+
* timestamp: kafkaLog.originalTimestamp,
|
|
1230
|
+
* level: "info",
|
|
1231
|
+
* message: [kafkaLog.message],
|
|
1232
|
+
* rawMessage: kafkaLog.message,
|
|
1233
|
+
* properties: {
|
|
1234
|
+
* source: "kafka",
|
|
1235
|
+
* partition: kafkaLog.partition,
|
|
1236
|
+
* offset: kafkaLog.offset,
|
|
1237
|
+
* },
|
|
1238
|
+
* });
|
|
1239
|
+
* ```
|
|
1240
|
+
*
|
|
1241
|
+
* @param record Log record without category field (category comes from
|
|
1242
|
+
* the logger instance)
|
|
1243
|
+
* @since 1.1.0
|
|
1244
|
+
*/
|
|
1245
|
+
emit(record: Omit<LogRecord, "category">): void;
|
|
1246
|
+
/**
|
|
1247
|
+
* Check if a message of the given severity level would be processed by
|
|
1248
|
+
* this logger.
|
|
1249
|
+
*
|
|
1250
|
+
* This is useful for conditionally executing expensive computations
|
|
1251
|
+
* before logging, particularly for async operations where lazy
|
|
1252
|
+
* evaluation callbacks cannot be used:
|
|
1253
|
+
*
|
|
1254
|
+
* ```typescript
|
|
1255
|
+
* if (logger.isEnabledFor("debug")) {
|
|
1256
|
+
* const result = await expensiveAsync();
|
|
1257
|
+
* logger.debug("Result: {result}", { result });
|
|
1258
|
+
* }
|
|
1259
|
+
* ```
|
|
1260
|
+
*
|
|
1261
|
+
* @param level The log level to check.
|
|
1262
|
+
* @returns `true` if a message of the given level would be logged,
|
|
1263
|
+
* `false` otherwise.
|
|
1264
|
+
* @since 2.0.0
|
|
1265
|
+
*/
|
|
1266
|
+
isEnabledFor(level: LogLevel): boolean;
|
|
1267
|
+
}
|
|
1268
|
+
/**
|
|
1269
|
+
* A logging callback function. It is used to defer the computation of a
|
|
1270
|
+
* message template until it is actually logged.
|
|
1271
|
+
* @param prefix The message template prefix.
|
|
1272
|
+
* @returns The rendered message array.
|
|
1273
|
+
*/
|
|
1274
|
+
type LogCallback = (prefix: LogTemplatePrefix) => unknown[];
|
|
1275
|
+
/**
|
|
1276
|
+
* A logging template prefix function. It is used to log a message in
|
|
1277
|
+
* a {@link LogCallback} function.
|
|
1278
|
+
* @param message The message template strings array.
|
|
1279
|
+
* @param values The message template values.
|
|
1280
|
+
* @returns The rendered message array.
|
|
1281
|
+
*/
|
|
1282
|
+
type LogTemplatePrefix = (message: TemplateStringsArray, ...values: unknown[]) => unknown[];
|
|
1283
|
+
/**
|
|
1284
|
+
* A function type for logging methods in the {@link Logger} interface.
|
|
1285
|
+
* @since 1.0.0
|
|
1286
|
+
*/
|
|
1287
|
+
//#endregion
|
|
1288
|
+
//#region packages/server/src/observability/logger.d.ts
|
|
1289
|
+
/**
|
|
1290
|
+
* Canonical category names. Use these instead of bare strings.
|
|
1291
|
+
*
|
|
1292
|
+
* Each entry is a two-segment array (`["baerly", "<unit>"]`) so
|
|
1293
|
+
* LogTape's hierarchical routing — categories descend by element,
|
|
1294
|
+
* not by string-split — picks up the parent `"baerly"` config we
|
|
1295
|
+
* register in {@link configureObservability}. Passing the dotted
|
|
1296
|
+
* string `"baerly.http"` would create a single-element sibling
|
|
1297
|
+
* category and miss the parent's sink wiring.
|
|
1298
|
+
*/
|
|
1299
|
+
declare const CATEGORY: {
|
|
1300
|
+
readonly http: readonly ["baerly", "http"];
|
|
1301
|
+
readonly storage: readonly ["baerly", "storage"];
|
|
1302
|
+
};
|
|
1303
|
+
/** Logical type of a `CATEGORY.*` value. */
|
|
1304
|
+
type CategoryName = (typeof CATEGORY)[keyof typeof CATEGORY];
|
|
1305
|
+
/** Friendly level names accepted by {@link configureObservability}. */
|
|
1306
|
+
type FriendlyLogLevel = "debug" | "info" | "warn" | "error";
|
|
1307
|
+
/**
|
|
1308
|
+
* `configureObservability` configuration.
|
|
1309
|
+
*
|
|
1310
|
+
* Anything `undefined` falls back through the env-var pipeline.
|
|
1311
|
+
*/
|
|
1312
|
+
interface ObservabilityConfig {
|
|
1313
|
+
/**
|
|
1314
|
+
* Lowest level that reaches the sink. Records below this level
|
|
1315
|
+
* are dropped. Fallback chain:
|
|
1316
|
+
* `config.level → LOG_LEVEL env → "info"`.
|
|
1317
|
+
*/
|
|
1318
|
+
readonly level?: FriendlyLogLevel;
|
|
1319
|
+
/**
|
|
1320
|
+
* Sink shorthand or a custom LogTape {@link Sink}.
|
|
1321
|
+
*
|
|
1322
|
+
* - `"console-json"` — one JSON object per line via `console.log`.
|
|
1323
|
+
* - A {@link Sink} function — passed through verbatim. Adapters
|
|
1324
|
+
* targeting TTY environments (e.g. `@baerly/adapter-node`'s
|
|
1325
|
+
* `baerlyDev()` Vite-mount path) construct a pretty sink locally
|
|
1326
|
+
* and pass it as a function; the kernel deliberately does not
|
|
1327
|
+
* ship a pretty-printer to keep `picocolors` off the runtime
|
|
1328
|
+
* closure.
|
|
1329
|
+
*
|
|
1330
|
+
* Default: `"console-json"`.
|
|
1331
|
+
*/
|
|
1332
|
+
readonly sink?: "console-json" | Sink;
|
|
1333
|
+
}
|
|
1334
|
+
/**
|
|
1335
|
+
* Wire LogTape's global config.
|
|
1336
|
+
*
|
|
1337
|
+
* Idempotent — call as many times as you like. The adapter boot
|
|
1338
|
+
* path calls it once at init; tests call it once per
|
|
1339
|
+
* `beforeEach`.
|
|
1340
|
+
*/
|
|
1341
|
+
declare const configureObservability: (config?: ObservabilityConfig) => Promise<void>;
|
|
1342
|
+
/**
|
|
1343
|
+
* Thin re-export. Identical shape to `@logtape/logtape`'s `getLogger`.
|
|
1344
|
+
* Constants in {@link CATEGORY} are the canonical inputs; bare
|
|
1345
|
+
* strings still work for ad-hoc instrumentation.
|
|
1346
|
+
*/
|
|
1347
|
+
declare const getLogger: (category: string | readonly string[]) => Logger;
|
|
1348
|
+
//#endregion
|
|
1349
|
+
//#region packages/server/src/observability/canonical.d.ts
|
|
1350
|
+
/** Options accepted by {@link flushCanonicalLine}. */
|
|
1351
|
+
interface FlushCanonicalLineOptions {
|
|
1352
|
+
readonly unit: "http";
|
|
1353
|
+
/** HTTP status code. Influences the level decision. */
|
|
1354
|
+
readonly status?: number;
|
|
1355
|
+
/**
|
|
1356
|
+
* Short outcome tag. In production all callsites route through
|
|
1357
|
+
* {@link deriveOutcome} which yields one of `"read"` /
|
|
1358
|
+
* `"committed"` / `"conflict"` / `"error"`; the field is typed
|
|
1359
|
+
* `string` so test fixtures and future units can pass a
|
|
1360
|
+
* unit-specific tag without type gymnastics.
|
|
1361
|
+
*/
|
|
1362
|
+
readonly outcome: string;
|
|
1363
|
+
/** Thrown value on the failure path. */
|
|
1364
|
+
readonly error?: unknown;
|
|
1365
|
+
/** Caller-supplied extra fields, spread onto the line last (override fields/summary). */
|
|
1366
|
+
readonly extra?: Readonly<Record<string, unknown>>;
|
|
1367
|
+
}
|
|
1368
|
+
/**
|
|
1369
|
+
* Emit (or suppress) the canonical line for this unit-of-work.
|
|
1370
|
+
*
|
|
1371
|
+
* Idempotent in the sense that the caller is expected to call it
|
|
1372
|
+
* exactly once per unit-of-work. Calling it twice will produce two
|
|
1373
|
+
* lines — there is no internal latch.
|
|
1374
|
+
*/
|
|
1375
|
+
declare const flushCanonicalLine: (ctx: ObservabilityContext, recorder: RequestScopedMetricsRecorder, opts: FlushCanonicalLineOptions) => void;
|
|
1376
|
+
/**
|
|
1377
|
+
* HTTP unit-of-work scope. Opens an {@link ObservabilityContext} from the
|
|
1378
|
+
* inbound `Request` (request id from `x-request-id` header or generated),
|
|
1379
|
+
* runs `fetch(req)` under {@link runWithContext}, and flushes the canonical
|
|
1380
|
+
* line in finally with `unit: "http"`.
|
|
1381
|
+
*
|
|
1382
|
+
* Production adapters open their own context BEFORE calling
|
|
1383
|
+
* `createRouter().fetch`; this helper is for standalone callers (tests,
|
|
1384
|
+
* one-off harnesses) that want one canonical line per request without
|
|
1385
|
+
* managing the bracket themselves.
|
|
1386
|
+
*
|
|
1387
|
+
* Behaviour mirrors what the legacy `app.use("*", ...)` middleware
|
|
1388
|
+
* did in Mode B (no ambient context): canonical line on every
|
|
1389
|
+
* request in `finally`. Because this wrapper sits OUTSIDE
|
|
1390
|
+
* `app.fetch`, errors absorbed by `app.onError` reach the caller as
|
|
1391
|
+
* a non-2xx `Response` whose body is the {@link HttpErrorEnvelope};
|
|
1392
|
+
* the helper reconstructs a `BaerlyError` from that envelope so the
|
|
1393
|
+
* canonical line carries the same `{ code, message }` shape it would
|
|
1394
|
+
* have under the in-Hono middleware.
|
|
1395
|
+
*/
|
|
1396
|
+
declare const withHttpObservability: (req: Request, fetch: (req: Request) => Promise<Response> | Response) => Promise<Response>;
|
|
1397
|
+
/**
|
|
1398
|
+
* Verifier rejected the request — log the warn, flush the canonical
|
|
1399
|
+
* line, and return the 401 envelope Response. Adapters call this
|
|
1400
|
+
* inside `runWithContext(obsCtx, ...)` so the canonical line lands on
|
|
1401
|
+
* the same context the rest of the request would have used.
|
|
1402
|
+
*
|
|
1403
|
+
* Both adapters share this so the 401 wire shape AND the
|
|
1404
|
+
* observability record are byte-identical across runtimes.
|
|
1405
|
+
*/
|
|
1406
|
+
declare const flushUnauthorizedAndRespond: (obsCtx: ObservabilityContext, req: Request) => Response;
|
|
1407
|
+
//#endregion
|
|
1408
|
+
//#region packages/server/src/observability/storage.d.ts
|
|
1409
|
+
/**
|
|
1410
|
+
* Wrap `inner` with metric emission. The returned object is itself
|
|
1411
|
+
* a `Storage` impl and passes the `Storage` conformance suite
|
|
1412
|
+
* (round-trip semantics, ETag preservation, `list` ordering — none
|
|
1413
|
+
* of which the decorator touches).
|
|
1414
|
+
*
|
|
1415
|
+
* Per-op counters and per-op duration histograms flow into the
|
|
1416
|
+
* active {@link ObservabilityContext}'s recorder (`ctxMetrics()`);
|
|
1417
|
+
* outside any context they fall through to {@link noopMetricsRecorder}.
|
|
1418
|
+
*/
|
|
1419
|
+
declare const observableStorage: (inner: Storage) => Storage;
|
|
1420
|
+
//#endregion
|
|
1421
|
+
//#region packages/server/src/observability/derive-outcome.d.ts
|
|
1422
|
+
/**
|
|
1423
|
+
* Canonical-line outcome derivation for HTTP requests. Shared
|
|
1424
|
+
* helper used by `packages/server/src/http/router.ts` (Mode B
|
|
1425
|
+
* standalone branch) and both host adapters
|
|
1426
|
+
* (`@baerly/adapter-node`'s server.ts and
|
|
1427
|
+
* `@baerly/adapter-cloudflare`'s worker.ts).
|
|
1428
|
+
*
|
|
1429
|
+
* Classification rules (evaluated in order):
|
|
1430
|
+
*
|
|
1431
|
+
* 1. `error !== undefined && status >= 500` → `"error"`. The
|
|
1432
|
+
* handler threw and the wire status surfaced as 5xx; the
|
|
1433
|
+
* canonical line carries the diagnostic at error level.
|
|
1434
|
+
* 2. `status < 400` and `method === "GET"` → `"read"`.
|
|
1435
|
+
* 3. `status < 400` and any other method → `"committed"`.
|
|
1436
|
+
* 4. `status === 409` → `"conflict"`
|
|
1437
|
+
* (writer CAS loss).
|
|
1438
|
+
* 5. Anything else (other 4xx/5xx) → `"error"`.
|
|
1439
|
+
*
|
|
1440
|
+
* Pure function — no allocations beyond the returned string
|
|
1441
|
+
* literal, no logging, no side effects. Safe to call from any
|
|
1442
|
+
* scope.
|
|
1443
|
+
*
|
|
1444
|
+
* @param method - The HTTP method that produced this response.
|
|
1445
|
+
* Case-sensitive; pass `req.method` verbatim.
|
|
1446
|
+
* @param status - The wire status the caller will see. For thrown
|
|
1447
|
+
* errors that haven't yet mapped to a response,
|
|
1448
|
+
* pass the result of `mapError(err).status`.
|
|
1449
|
+
* @param error - The error object attached to the request (if
|
|
1450
|
+
* any). Optional — pass `undefined` on the
|
|
1451
|
+
* happy path.
|
|
1452
|
+
*/
|
|
1453
|
+
type Outcome = "read" | "committed" | "conflict" | "error";
|
|
1454
|
+
declare const deriveOutcome: (method: string, status: number, error?: unknown) => Outcome;
|
|
1455
|
+
//#endregion
|
|
1456
|
+
export { getCurrentContext as _, flushCanonicalLine as a, CATEGORY as c, ObservabilityConfig as d, configureObservability as f, createObservabilityContext as g, ObservabilityContextInit as h, FlushCanonicalLineOptions as i, CategoryName as l, ObservabilityContext as m, deriveOutcome as n, flushUnauthorizedAndRespond as o, getLogger as p, observableStorage as r, withHttpObservability as s, Outcome as t, FriendlyLogLevel as u, runWithContext as v };
|
|
1457
|
+
//# sourceMappingURL=index-BYv0hb8M.d.ts.map
|