@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.
Files changed (115) hide show
  1. package/README.md +97 -0
  2. package/dist/API.md +850 -0
  3. package/dist/app-config-Cb5dO2s9.d.ts +480 -0
  4. package/dist/app-config.d.ts +2 -0
  5. package/dist/app-config.js +8 -0
  6. package/dist/app-config.js.map +1 -0
  7. package/dist/auth.d.ts +237 -0
  8. package/dist/auth.js +1335 -0
  9. package/dist/auth.js.map +1 -0
  10. package/dist/baerly.js +761 -0
  11. package/dist/baerly.js.map +1 -0
  12. package/dist/bucket-uri-BrDEYvzy.js +4922 -0
  13. package/dist/bucket-uri-BrDEYvzy.js.map +1 -0
  14. package/dist/chunk-EAsCxrDo.js +14 -0
  15. package/dist/client-BLf3Ae5s.d.ts +233 -0
  16. package/dist/client-react.d.ts +131 -0
  17. package/dist/client-react.js +559 -0
  18. package/dist/client-react.js.map +1 -0
  19. package/dist/client.d.ts +4 -0
  20. package/dist/client.js +160 -0
  21. package/dist/client.js.map +1 -0
  22. package/dist/cloudflare-CINJPKCW.js +911 -0
  23. package/dist/cloudflare-CINJPKCW.js.map +1 -0
  24. package/dist/cloudflare.d.ts +211 -0
  25. package/dist/cloudflare.js +445 -0
  26. package/dist/cloudflare.js.map +1 -0
  27. package/dist/config-Bsg8wgwo.js +198 -0
  28. package/dist/config-Bsg8wgwo.js.map +1 -0
  29. package/dist/context-Oj7ffwD-.js +187 -0
  30. package/dist/context-Oj7ffwD-.js.map +1 -0
  31. package/dist/cost-B1WiZxlf.js +203 -0
  32. package/dist/cost-B1WiZxlf.js.map +1 -0
  33. package/dist/current-json-BkatBzF7.js +252 -0
  34. package/dist/current-json-BkatBzF7.js.map +1 -0
  35. package/dist/db-D62JguBc.d.ts +336 -0
  36. package/dist/deploy-BB-wqbhf.js +83 -0
  37. package/dist/deploy-BB-wqbhf.js.map +1 -0
  38. package/dist/dev-banner-CWHIk8tH.d.ts +26 -0
  39. package/dist/dev-vite.d.ts +146 -0
  40. package/dist/dev-vite.js +223 -0
  41. package/dist/dev-vite.js.map +1 -0
  42. package/dist/dev.d.ts +3 -0
  43. package/dist/dev.js +2 -0
  44. package/dist/doctor-B8h9GCN9.js +331 -0
  45. package/dist/doctor-B8h9GCN9.js.map +1 -0
  46. package/dist/dump-BHo_sIMZ.js +116 -0
  47. package/dist/dump-BHo_sIMZ.js.map +1 -0
  48. package/dist/errors-DOdL95kK.js +58 -0
  49. package/dist/errors-DOdL95kK.js.map +1 -0
  50. package/dist/export-Dz2PZKSR.js +423 -0
  51. package/dist/export-Dz2PZKSR.js.map +1 -0
  52. package/dist/fsck-DEz9lyCy.js +293 -0
  53. package/dist/fsck-DEz9lyCy.js.map +1 -0
  54. package/dist/http-CjUO1Bec.js +1756 -0
  55. package/dist/http-CjUO1Bec.js.map +1 -0
  56. package/dist/http.d.ts +1619 -0
  57. package/dist/http.js +2 -0
  58. package/dist/index-BGC-ENnj.d.ts +1065 -0
  59. package/dist/index-BYv0hb8M.d.ts +1457 -0
  60. package/dist/index-BquQkhJi.d.ts +112 -0
  61. package/dist/index-COsQ-Mlz.d.ts +146 -0
  62. package/dist/index.d.ts +6 -0
  63. package/dist/index.js +6 -0
  64. package/dist/indexes-BXn7a06a.js +297 -0
  65. package/dist/indexes-BXn7a06a.js.map +1 -0
  66. package/dist/indexes-DwOXkn1Y.d.ts +22 -0
  67. package/dist/inspect-x02aFWnh.js +149 -0
  68. package/dist/inspect-x02aFWnh.js.map +1 -0
  69. package/dist/log-walk-DIru96UT.js +260 -0
  70. package/dist/log-walk-DIru96UT.js.map +1 -0
  71. package/dist/maintenance-Bn6ul9aV.js +758 -0
  72. package/dist/maintenance-Bn6ul9aV.js.map +1 -0
  73. package/dist/maintenance.d.ts +323 -0
  74. package/dist/maintenance.js +2 -0
  75. package/dist/node.d.ts +422 -0
  76. package/dist/node.js +2 -0
  77. package/dist/normalize-XWY25_sG.js +133 -0
  78. package/dist/normalize-XWY25_sG.js.map +1 -0
  79. package/dist/observability-2IDYRuZK.js +2333 -0
  80. package/dist/observability-2IDYRuZK.js.map +1 -0
  81. package/dist/observability.d.ts +3 -0
  82. package/dist/observability.js +3 -0
  83. package/dist/plan-Cs17VqjU.js +224 -0
  84. package/dist/plan-Cs17VqjU.js.map +1 -0
  85. package/dist/query-DcSbFLJt.js +1880 -0
  86. package/dist/query-DcSbFLJt.js.map +1 -0
  87. package/dist/rebuild-index-C5gTXryd.js +119 -0
  88. package/dist/rebuild-index-C5gTXryd.js.map +1 -0
  89. package/dist/rebuild-index-DwXM0WfA.js +104 -0
  90. package/dist/rebuild-index-DwXM0WfA.js.map +1 -0
  91. package/dist/request-BEF_OvMh.js +72 -0
  92. package/dist/request-BEF_OvMh.js.map +1 -0
  93. package/dist/restore-CbKVMMpm.js +847 -0
  94. package/dist/restore-CbKVMMpm.js.map +1 -0
  95. package/dist/shared-secret-BJdSwpgw.js +71 -0
  96. package/dist/shared-secret-BJdSwpgw.js.map +1 -0
  97. package/dist/snapshot-D7C4_FSl.js +71 -0
  98. package/dist/snapshot-D7C4_FSl.js.map +1 -0
  99. package/dist/snapshot-z_N9hpTe.js +917 -0
  100. package/dist/snapshot-z_N9hpTe.js.map +1 -0
  101. package/dist/src-Chafbw8r.js +522 -0
  102. package/dist/src-Chafbw8r.js.map +1 -0
  103. package/dist/src-DyET_VPP.js +6199 -0
  104. package/dist/src-DyET_VPP.js.map +1 -0
  105. package/dist/src-n0Te1r98.js +352 -0
  106. package/dist/src-n0Te1r98.js.map +1 -0
  107. package/dist/subcommand-BWs6K7zb.js +110 -0
  108. package/dist/subcommand-BWs6K7zb.js.map +1 -0
  109. package/dist/usage-RVUQMLop.js +339 -0
  110. package/dist/usage-RVUQMLop.js.map +1 -0
  111. package/dist/validate-DhH1lO8I.js +377 -0
  112. package/dist/validate-DhH1lO8I.js.map +1 -0
  113. package/dist/wire-izfGZDvr.js +7 -0
  114. package/dist/wire-izfGZDvr.js.map +1 -0
  115. 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