logixia 1.12.5 → 1.12.6
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 +65 -14
- package/dist/.tsbuildinfo +1 -1
- package/dist/async-context-CSHWoHMB.js +88 -0
- package/dist/async-context-CSHWoHMB.js.map +1 -0
- package/dist/async-context-CwBNMm2E.mjs +68 -0
- package/dist/async-context-CwBNMm2E.mjs.map +1 -0
- package/dist/azure-monitor.transport-CG7ClkYj.d.ts +62 -0
- package/dist/azure-monitor.transport-CG7ClkYj.d.ts.map +1 -0
- package/dist/azure-monitor.transport-CHnjVRF-.mjs +152 -0
- package/dist/azure-monitor.transport-CHnjVRF-.mjs.map +1 -0
- package/dist/azure-monitor.transport-Cm74kXZS.d.mts +62 -0
- package/dist/azure-monitor.transport-Cm74kXZS.d.mts.map +1 -0
- package/dist/azure-monitor.transport-CrvfHd9C.js +157 -0
- package/dist/azure-monitor.transport-CrvfHd9C.js.map +1 -0
- package/dist/azure.d.mts +3 -0
- package/dist/azure.d.ts +3 -0
- package/dist/azure.js +6 -0
- package/dist/azure.mjs +6 -0
- package/dist/batch-buffer-BY-mRWIK.js +170 -0
- package/dist/batch-buffer-BY-mRWIK.js.map +1 -0
- package/dist/batch-buffer-PGvSgbmd.mjs +132 -0
- package/dist/batch-buffer-PGvSgbmd.mjs.map +1 -0
- package/dist/browser.d.mts +427 -0
- package/dist/browser.d.mts.map +1 -0
- package/dist/browser.d.ts +427 -0
- package/dist/browser.d.ts.map +1 -0
- package/dist/browser.js +590 -0
- package/dist/browser.js.map +1 -0
- package/dist/browser.mjs +586 -0
- package/dist/browser.mjs.map +1 -0
- package/dist/chunk-DLSkYcPk.mjs +7 -0
- package/dist/chunk-nOFOJqeH.js +30 -0
- package/dist/cloudwatch.d.mts +3 -0
- package/dist/cloudwatch.d.ts +3 -0
- package/dist/cloudwatch.js +6 -0
- package/dist/cloudwatch.mjs +6 -0
- package/dist/cloudwatch.transport-CGHY4buE.d.mts +81 -0
- package/dist/cloudwatch.transport-CGHY4buE.d.mts.map +1 -0
- package/dist/cloudwatch.transport-DK_8cKd3.d.ts +81 -0
- package/dist/cloudwatch.transport-DK_8cKd3.d.ts.map +1 -0
- package/dist/cloudwatch.transport-pNBNWJLt.js +370 -0
- package/dist/cloudwatch.transport-pNBNWJLt.js.map +1 -0
- package/dist/cloudwatch.transport-yBwm4OeO.mjs +360 -0
- package/dist/cloudwatch.transport-yBwm4OeO.mjs.map +1 -0
- package/dist/coerce.utils-BN980Y9V.js +44 -0
- package/dist/coerce.utils-BN980Y9V.js.map +1 -0
- package/dist/coerce.utils-Dxv4_ikC.mjs +38 -0
- package/dist/coerce.utils-Dxv4_ikC.mjs.map +1 -0
- package/dist/correlation.d.mts +238 -0
- package/dist/correlation.d.mts.map +1 -0
- package/dist/correlation.d.ts +238 -0
- package/dist/correlation.d.ts.map +1 -0
- package/dist/correlation.js +272 -0
- package/dist/correlation.js.map +1 -0
- package/dist/correlation.mjs +261 -0
- package/dist/correlation.mjs.map +1 -0
- package/dist/gcp.d.mts +3 -0
- package/dist/gcp.d.ts +3 -0
- package/dist/gcp.js +6 -0
- package/dist/gcp.mjs +6 -0
- package/dist/gcp.transport-BJuNRFe_.mjs +192 -0
- package/dist/gcp.transport-BJuNRFe_.mjs.map +1 -0
- package/dist/gcp.transport-BOhkVKlI.d.ts +71 -0
- package/dist/gcp.transport-BOhkVKlI.d.ts.map +1 -0
- package/dist/gcp.transport-Bi6CUqZR.d.mts +71 -0
- package/dist/gcp.transport-Bi6CUqZR.d.mts.map +1 -0
- package/dist/gcp.transport-SHdtc1n0.js +198 -0
- package/dist/gcp.transport-SHdtc1n0.js.map +1 -0
- package/dist/{index-CwFww7VC.d.ts → index-BPKwwERo.d.mts} +18 -174
- package/dist/index-BPKwwERo.d.mts.map +1 -0
- package/dist/{index-DnyeaoZU.d.mts → index-C1X-TE5I.d.ts} +18 -174
- package/dist/index-C1X-TE5I.d.ts.map +1 -0
- package/dist/index.d.mts +41 -11
- package/dist/index.d.mts.map +1 -1
- package/dist/index.d.ts +40 -10
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +87 -147
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +62 -132
- package/dist/index.mjs.map +1 -1
- package/dist/internal-log-BUJYMZbE.js +70 -0
- package/dist/internal-log-BUJYMZbE.js.map +1 -0
- package/dist/internal-log-Cm8SOWSV.mjs +52 -0
- package/dist/internal-log-Cm8SOWSV.mjs.map +1 -0
- package/dist/{logitron-logger.module-BIGTm2V6.mjs → logitron-logger.module-Bs3XYZgF.mjs} +266 -166
- package/dist/logitron-logger.module-Bs3XYZgF.mjs.map +1 -0
- package/dist/{logitron-logger.module-BTxDpK6u.js → logitron-logger.module-BsDZR5BH.js} +297 -203
- package/dist/logitron-logger.module-BsDZR5BH.js.map +1 -0
- package/dist/{logitron-logger.module-DvqtI43C.d.ts → logitron-logger.module-CxT1F6Cm.d.ts} +25 -12
- package/dist/logitron-logger.module-CxT1F6Cm.d.ts.map +1 -0
- package/dist/{logitron-logger.module-CpffEHec.d.mts → logitron-logger.module-zDKVd_o0.d.mts} +25 -12
- package/dist/logitron-logger.module-zDKVd_o0.d.mts.map +1 -0
- package/dist/middleware.d.mts +5 -2
- package/dist/middleware.d.mts.map +1 -1
- package/dist/middleware.d.ts +5 -2
- package/dist/middleware.d.ts.map +1 -1
- package/dist/middleware.js +13 -4
- package/dist/middleware.js.map +1 -1
- package/dist/middleware.mjs +14 -4
- package/dist/middleware.mjs.map +1 -1
- package/dist/nest.d.mts +3 -2
- package/dist/nest.d.mts.map +1 -1
- package/dist/nest.d.ts +3 -2
- package/dist/nest.d.ts.map +1 -1
- package/dist/nest.js +6 -2
- package/dist/nest.mjs +6 -2
- package/dist/safe-stringify-DJ66tW5I.mjs +118 -0
- package/dist/safe-stringify-DJ66tW5I.mjs.map +1 -0
- package/dist/safe-stringify-DWo3aZp_.js +142 -0
- package/dist/safe-stringify-DWo3aZp_.js.map +1 -0
- package/dist/search-CFQRISUv.mjs +1596 -0
- package/dist/search-CFQRISUv.mjs.map +1 -0
- package/dist/search-CQOo-Iq6.d.mts +816 -0
- package/dist/search-CQOo-Iq6.d.mts.map +1 -0
- package/dist/search-DujhR94O.d.ts +816 -0
- package/dist/search-DujhR94O.d.ts.map +1 -0
- package/dist/search-njTI2hdo.js +1631 -0
- package/dist/search-njTI2hdo.js.map +1 -0
- package/dist/search.d.mts +4 -1
- package/dist/search.d.ts +4 -1
- package/dist/search.js +9 -1
- package/dist/search.mjs +3 -2
- package/dist/testing.d.mts +2 -1
- package/dist/testing.d.mts.map +1 -1
- package/dist/testing.d.ts +2 -1
- package/dist/testing.d.ts.map +1 -1
- package/dist/{transport.manager-ciG4r5uz.js → transport.manager-BivyUTtU.js} +497 -437
- package/dist/transport.manager-BivyUTtU.js.map +1 -0
- package/dist/{transport.manager-DETpXuaY.mjs → transport.manager-D6KL3t9V.mjs} +473 -364
- package/dist/transport.manager-D6KL3t9V.mjs.map +1 -0
- package/dist/transport.types-B5vcyv2k.d.mts +187 -0
- package/dist/transport.types-B5vcyv2k.d.mts.map +1 -0
- package/dist/transport.types-BuY84TwO.d.ts +187 -0
- package/dist/transport.types-BuY84TwO.d.ts.map +1 -0
- package/dist/transports.d.mts +90 -29
- package/dist/transports.d.mts.map +1 -1
- package/dist/transports.d.ts +90 -29
- package/dist/transports.d.ts.map +1 -1
- package/dist/transports.js +14 -2
- package/dist/transports.mjs +10 -2
- package/dist/worker-entry.js +1241 -0
- package/dist/worker.d.mts +3 -0
- package/dist/worker.d.ts +3 -0
- package/dist/worker.js +4 -0
- package/dist/worker.mjs +4 -0
- package/dist/worker.transport-BP8Q28Z2.d.mts +76 -0
- package/dist/worker.transport-BP8Q28Z2.d.mts.map +1 -0
- package/dist/worker.transport-BhMyvqQ2.mjs +167 -0
- package/dist/worker.transport-BhMyvqQ2.mjs.map +1 -0
- package/dist/worker.transport-CfH6z37Z.js +168 -0
- package/dist/worker.transport-CfH6z37Z.js.map +1 -0
- package/dist/worker.transport-mKXgNK0L.d.ts +76 -0
- package/dist/worker.transport-mKXgNK0L.d.ts.map +1 -0
- package/package.json +23 -18
- package/dist/index-CwFww7VC.d.ts.map +0 -1
- package/dist/index-DnyeaoZU.d.mts.map +0 -1
- package/dist/logitron-logger.module-BIGTm2V6.mjs.map +0 -1
- package/dist/logitron-logger.module-BTxDpK6u.js.map +0 -1
- package/dist/logitron-logger.module-CpffEHec.d.mts.map +0 -1
- package/dist/logitron-logger.module-DvqtI43C.d.ts.map +0 -1
- package/dist/search-Cg_OasF-.d.ts +0 -1
- package/dist/search-DN676Dnz.d.mts +0 -1
- package/dist/search-DOvSI-mb.mjs +0 -1
- package/dist/search-DoZF3RZj.js +0 -0
- package/dist/transport.manager-DETpXuaY.mjs.map +0 -1
- package/dist/transport.manager-ciG4r5uz.js.map +0 -1
|
@@ -0,0 +1,427 @@
|
|
|
1
|
+
//#region src/utils/otel.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* logixia — OpenTelemetry auto trace-log correlation
|
|
4
|
+
*
|
|
5
|
+
* Zero-config: if `@opentelemetry/api` is installed, logixia automatically
|
|
6
|
+
* reads the active span context and injects `traceId`, `spanId`, and
|
|
7
|
+
* `traceFlags` into every log entry. No manual wiring needed.
|
|
8
|
+
*
|
|
9
|
+
* The integration is completely optional — if `@opentelemetry/api` is absent
|
|
10
|
+
* (or the OTel SDK is not initialised), all helpers return `undefined` silently.
|
|
11
|
+
*
|
|
12
|
+
* Additionally exposes a `createOtelLogExporter()` factory that routes every
|
|
13
|
+
* logixia log entry through the active OTel LoggerProvider (OTLP export).
|
|
14
|
+
*
|
|
15
|
+
* @example Auto bridge (zero config)
|
|
16
|
+
* ```ts
|
|
17
|
+
* import { createLogger } from 'logixia';
|
|
18
|
+
* import { initOtelBridge } from 'logixia';
|
|
19
|
+
*
|
|
20
|
+
* // Call once at app startup, after your OTel SDK is initialised
|
|
21
|
+
* initOtelBridge();
|
|
22
|
+
*
|
|
23
|
+
* const logger = createLogger({ appName: 'api' });
|
|
24
|
+
* // Every logger.info / warn / error call now auto-injects traceId + spanId
|
|
25
|
+
* // from the currently active OTel span — no per-call code needed.
|
|
26
|
+
* ```
|
|
27
|
+
*
|
|
28
|
+
* @example Manual span context injection
|
|
29
|
+
* ```ts
|
|
30
|
+
* import { getActiveOtelContext } from 'logixia';
|
|
31
|
+
*
|
|
32
|
+
* const ctx = getActiveOtelContext();
|
|
33
|
+
* await logger.info('Payment processed', { ...ctx, orderId: 'ord_123' });
|
|
34
|
+
* // → { traceId: 'abc...', spanId: 'def...', traceFlags: 1, orderId: 'ord_123' }
|
|
35
|
+
* ```
|
|
36
|
+
*/
|
|
37
|
+
interface OtelSpanContext {
|
|
38
|
+
/** W3C 32-hex-char trace ID */
|
|
39
|
+
traceId: string;
|
|
40
|
+
/** W3C 16-hex-char span ID */
|
|
41
|
+
spanId: string;
|
|
42
|
+
/** W3C trace-flags integer (1 = sampled) */
|
|
43
|
+
traceFlags: number;
|
|
44
|
+
/** Whether this context is from a valid, sampled span */
|
|
45
|
+
isSampled: boolean;
|
|
46
|
+
}
|
|
47
|
+
interface OtelBridgeOptions {
|
|
48
|
+
/**
|
|
49
|
+
* Field name written to log entries for the trace ID.
|
|
50
|
+
* @default 'traceId'
|
|
51
|
+
*/
|
|
52
|
+
traceIdField?: string;
|
|
53
|
+
/**
|
|
54
|
+
* Field name written to log entries for the span ID.
|
|
55
|
+
* @default 'spanId'
|
|
56
|
+
*/
|
|
57
|
+
spanIdField?: string;
|
|
58
|
+
/**
|
|
59
|
+
* Field name written to log entries for trace flags.
|
|
60
|
+
* @default 'traceFlags'
|
|
61
|
+
*/
|
|
62
|
+
traceFlagsField?: string;
|
|
63
|
+
/**
|
|
64
|
+
* Only inject context when the span is sampled (traceFlags bit 1 set).
|
|
65
|
+
* @default false
|
|
66
|
+
*/
|
|
67
|
+
sampledOnly?: boolean;
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Read the currently active OTel span context (if any) and return its fields
|
|
71
|
+
* in a plain object suitable for spreading into a log entry.
|
|
72
|
+
*
|
|
73
|
+
* Returns `undefined` when:
|
|
74
|
+
* - `@opentelemetry/api` is not installed
|
|
75
|
+
* - No active span exists (root context)
|
|
76
|
+
* - The span context is invalid (all-zeros)
|
|
77
|
+
*/
|
|
78
|
+
declare function getActiveOtelContext(opts?: OtelBridgeOptions): OtelSpanContext | undefined;
|
|
79
|
+
/**
|
|
80
|
+
* Returns a metadata object with OTel context fields ready to merge into a log call,
|
|
81
|
+
* using the configured field names.
|
|
82
|
+
*
|
|
83
|
+
* Returns `{}` when no active span exists (safe to spread unconditionally).
|
|
84
|
+
*
|
|
85
|
+
* @example
|
|
86
|
+
* ```ts
|
|
87
|
+
* await logger.info('Payment processed', {
|
|
88
|
+
* ...getOtelMetaFields(),
|
|
89
|
+
* orderId: 'ord_123',
|
|
90
|
+
* });
|
|
91
|
+
* ```
|
|
92
|
+
*/
|
|
93
|
+
declare function getOtelMetaFields(opts?: OtelBridgeOptions): Record<string, unknown>;
|
|
94
|
+
/**
|
|
95
|
+
* Initialise the global OTel bridge.
|
|
96
|
+
*
|
|
97
|
+
* Once called, logixia's internal log pipeline checks for an active OTel span
|
|
98
|
+
* on **every** log call and automatically merges the span context into the
|
|
99
|
+
* entry's metadata — no per-call wiring needed.
|
|
100
|
+
*
|
|
101
|
+
* Call once at app startup, **after** the OTel SDK has been initialised:
|
|
102
|
+
* ```ts
|
|
103
|
+
* import { initOtelBridge } from 'logixia';
|
|
104
|
+
* initOtelBridge();
|
|
105
|
+
* ```
|
|
106
|
+
*/
|
|
107
|
+
declare function initOtelBridge(opts?: OtelBridgeOptions): void;
|
|
108
|
+
/**
|
|
109
|
+
* Disable the OTel bridge (useful for tests).
|
|
110
|
+
*/
|
|
111
|
+
declare function disableOtelBridge(): void;
|
|
112
|
+
//#endregion
|
|
113
|
+
//#region src/utils/typed-logger.d.ts
|
|
114
|
+
/**
|
|
115
|
+
* logixia — TypeScript typed log fields
|
|
116
|
+
*
|
|
117
|
+
* Solves the type-safety gap: standard `Record<string, unknown>` metadata gives
|
|
118
|
+
* zero IDE autocomplete and lets typos slip silently into production logs.
|
|
119
|
+
*
|
|
120
|
+
* Two complementary utilities:
|
|
121
|
+
*
|
|
122
|
+
* 1. `createTypedLogger<TFields>()` — wraps any IBaseLogger so that the second
|
|
123
|
+
* argument of every log method is constrained to `TFields` (a typed object).
|
|
124
|
+
* Compile-time safety, zero runtime overhead.
|
|
125
|
+
*
|
|
126
|
+
* 2. `defineLogSchema<TFields>(schema)` — declares expected fields with optional
|
|
127
|
+
* validators. In development (NODE_ENV !== 'production') every log call is
|
|
128
|
+
* validated against the schema and a warning is emitted for missing required
|
|
129
|
+
* fields or type mismatches.
|
|
130
|
+
*
|
|
131
|
+
* @example
|
|
132
|
+
* ```ts
|
|
133
|
+
* import { createTypedLogger, defineLogSchema } from 'logixia';
|
|
134
|
+
*
|
|
135
|
+
* interface OrderFields {
|
|
136
|
+
* orderId: string;
|
|
137
|
+
* userId: string;
|
|
138
|
+
* amount?: number;
|
|
139
|
+
* currency?: string;
|
|
140
|
+
* }
|
|
141
|
+
*
|
|
142
|
+
* const schema = defineLogSchema<OrderFields>({
|
|
143
|
+
* orderId: { type: 'string', required: true },
|
|
144
|
+
* userId: { type: 'string', required: true },
|
|
145
|
+
* amount: { type: 'number' },
|
|
146
|
+
* currency: { type: 'string' },
|
|
147
|
+
* });
|
|
148
|
+
*
|
|
149
|
+
* const orderLogger = createTypedLogger<OrderFields>(baseLogger, schema);
|
|
150
|
+
* await orderLogger.info('Order created', { orderId: 'ord_123', userId: 'usr_456', amount: 99.99 });
|
|
151
|
+
* // ^^^^ fully typed autocomplete ^^^^
|
|
152
|
+
* ```
|
|
153
|
+
*/
|
|
154
|
+
type LogFieldType = 'string' | 'number' | 'boolean' | 'object' | 'array';
|
|
155
|
+
interface LogFieldDef {
|
|
156
|
+
type: LogFieldType;
|
|
157
|
+
/** Emit a warning when this field is missing from the log call. Default: false */
|
|
158
|
+
required?: boolean;
|
|
159
|
+
/** Custom validator — return a string to emit it as a warning message. */
|
|
160
|
+
validate?: (value: unknown) => string | undefined;
|
|
161
|
+
}
|
|
162
|
+
type LogSchema<TFields extends Record<string, unknown>> = { [K in keyof TFields]: LogFieldDef };
|
|
163
|
+
interface CompiledSchema<TFields extends Record<string, unknown>> {
|
|
164
|
+
readonly fields: LogSchema<TFields>;
|
|
165
|
+
/**
|
|
166
|
+
* Validate a payload against the schema.
|
|
167
|
+
* Returns an array of warning strings (empty = pass).
|
|
168
|
+
* Only runs in non-production environments.
|
|
169
|
+
*/
|
|
170
|
+
validate(payload: Partial<TFields>): string[];
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* Define a typed schema for a category of log entries.
|
|
174
|
+
*
|
|
175
|
+
* Call this once at module initialisation and pass it to `createTypedLogger`.
|
|
176
|
+
* In development, every log call is validated against the schema.
|
|
177
|
+
*/
|
|
178
|
+
declare function defineLogSchema<TFields extends Record<string, unknown>>(fields: LogSchema<TFields>): CompiledSchema<TFields>;
|
|
179
|
+
/** IBaseLogger-compatible subset used by TypedLogger */
|
|
180
|
+
interface LoggerLike {
|
|
181
|
+
error(message: string | Error, data?: Record<string, unknown>): Promise<void>;
|
|
182
|
+
warn(message: string, data?: Record<string, unknown>): Promise<void>;
|
|
183
|
+
info(message: string, data?: Record<string, unknown>): Promise<void>;
|
|
184
|
+
debug(message: string, data?: Record<string, unknown>): Promise<void>;
|
|
185
|
+
verbose?(message: string, data?: Record<string, unknown>): Promise<void>;
|
|
186
|
+
trace?(message: string, data?: Record<string, unknown>): Promise<void>;
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* A logger whose metadata is typed to `TFields`.
|
|
190
|
+
*
|
|
191
|
+
* The `error` overload still accepts a plain `Error` object as the first arg
|
|
192
|
+
* (with optional `TFields` data) so the typed logger remains a drop-in replacement.
|
|
193
|
+
*/
|
|
194
|
+
interface TypedLogger<TFields extends Record<string, unknown>> {
|
|
195
|
+
error(error: Error, data?: Partial<TFields>): Promise<void>;
|
|
196
|
+
error(message: string, data?: Partial<TFields>): Promise<void>;
|
|
197
|
+
warn(message: string, data?: Partial<TFields>): Promise<void>;
|
|
198
|
+
info(message: string, data?: Partial<TFields>): Promise<void>;
|
|
199
|
+
debug(message: string, data?: Partial<TFields>): Promise<void>;
|
|
200
|
+
verbose(message: string, data?: Partial<TFields>): Promise<void>;
|
|
201
|
+
trace(message: string, data?: Partial<TFields>): Promise<void>;
|
|
202
|
+
/** Access the underlying untyped logger if needed. */
|
|
203
|
+
readonly raw: LoggerLike;
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* Wrap any logixia logger with a type-safe field interface.
|
|
207
|
+
*
|
|
208
|
+
* @param logger Any object that implements `IBaseLogger` (e.g. the result of `createLogger()`)
|
|
209
|
+
* @param schema Optional schema for dev-time validation. Created with `defineLogSchema()`.
|
|
210
|
+
*/
|
|
211
|
+
declare function createTypedLogger<TFields extends Record<string, unknown>>(logger: LoggerLike, schema?: CompiledSchema<TFields>): TypedLogger<TFields>;
|
|
212
|
+
//#endregion
|
|
213
|
+
//#region src/browser.d.ts
|
|
214
|
+
/**
|
|
215
|
+
* logixia — Browser / Edge Runtime entry point
|
|
216
|
+
*
|
|
217
|
+
* This module is the browser-safe subset of logixia. It contains **no**
|
|
218
|
+
* references to Node.js built-ins (`node:fs`, `node:http`, `node:worker_threads`,
|
|
219
|
+
* `node:crypto`, `node:async_hooks`) so it can be bundled for:
|
|
220
|
+
*
|
|
221
|
+
* - Browser (Webpack / Vite / esbuild)
|
|
222
|
+
* - Cloudflare Workers / Vercel Edge Functions
|
|
223
|
+
* - Deno (via ESM import)
|
|
224
|
+
* - Bun (core subset, no file/DB transports)
|
|
225
|
+
*
|
|
226
|
+
* Excluded from this entry: FileTransport, DatabaseTransport, WorkerTransport,
|
|
227
|
+
* CloudWatchTransport, GCPTransport, AzureMonitorTransport, and anything that
|
|
228
|
+
* requires `AsyncLocalStorage`.
|
|
229
|
+
*
|
|
230
|
+
* @example Basic browser usage
|
|
231
|
+
* ```ts
|
|
232
|
+
* import { createBrowserLogger, BrowserConsoleTransport } from 'logixia/browser';
|
|
233
|
+
*
|
|
234
|
+
* const logger = createBrowserLogger({ appName: 'my-app' });
|
|
235
|
+
* logger.info('Page loaded', { url: location.href });
|
|
236
|
+
* ```
|
|
237
|
+
*
|
|
238
|
+
* @example Custom transport in browser
|
|
239
|
+
* ```ts
|
|
240
|
+
* import { createBrowserLogger, BrowserConsoleTransport } from 'logixia/browser';
|
|
241
|
+
*
|
|
242
|
+
* const logger = createBrowserLogger({
|
|
243
|
+
* appName: 'my-app',
|
|
244
|
+
* json: false, // pretty-print in devtools
|
|
245
|
+
* level: 'debug',
|
|
246
|
+
* });
|
|
247
|
+
* ```
|
|
248
|
+
*/
|
|
249
|
+
type BrowserLogLevel = 'verbose' | 'debug' | 'info' | 'warn' | 'error' | 'critical';
|
|
250
|
+
interface BrowserLogEntry {
|
|
251
|
+
timestamp: string;
|
|
252
|
+
level: BrowserLogLevel;
|
|
253
|
+
appName: string;
|
|
254
|
+
message: string;
|
|
255
|
+
payload?: Record<string, unknown>;
|
|
256
|
+
traceId?: string;
|
|
257
|
+
context?: string;
|
|
258
|
+
}
|
|
259
|
+
interface BrowserLoggerConfig {
|
|
260
|
+
/** Application name shown in every log entry. @default 'App' */
|
|
261
|
+
appName?: string;
|
|
262
|
+
/** Minimum log level to emit. @default 'info' */
|
|
263
|
+
level?: BrowserLogLevel;
|
|
264
|
+
/**
|
|
265
|
+
* When `true` serializes entries as compact JSON strings — useful for
|
|
266
|
+
* structured logging pipelines (Sentry breadcrumbs, LogRocket, etc.).
|
|
267
|
+
* When `false` (default) uses console group/table for devtools-friendly output.
|
|
268
|
+
*/
|
|
269
|
+
json?: boolean;
|
|
270
|
+
/**
|
|
271
|
+
* Additional transports to write to (e.g. a remote analytics endpoint).
|
|
272
|
+
* The built-in `BrowserConsoleTransport` is always added unless `silent: true`.
|
|
273
|
+
*/
|
|
274
|
+
transports?: IBrowserTransport[];
|
|
275
|
+
/** Suppress all output (useful for tests). @default false */
|
|
276
|
+
silent?: boolean;
|
|
277
|
+
/** Static context fields merged into every log entry. */
|
|
278
|
+
context?: Record<string, unknown>;
|
|
279
|
+
}
|
|
280
|
+
interface IBrowserTransport {
|
|
281
|
+
name: string;
|
|
282
|
+
level?: BrowserLogLevel;
|
|
283
|
+
write(entry: BrowserLogEntry): void;
|
|
284
|
+
}
|
|
285
|
+
/**
|
|
286
|
+
* Default browser transport — writes to the browser console using native
|
|
287
|
+
* level methods so devtools can filter by severity.
|
|
288
|
+
*
|
|
289
|
+
* In pretty mode (default):
|
|
290
|
+
* - Groups each entry under a collapsible header with timestamp + app name
|
|
291
|
+
* - Payload displayed as an expandable object via `console.table` / `console.dir`
|
|
292
|
+
*
|
|
293
|
+
* In JSON mode:
|
|
294
|
+
* - Emits compact JSON strings via `console.log` / `console.error`
|
|
295
|
+
*/
|
|
296
|
+
declare class BrowserConsoleTransport implements IBrowserTransport {
|
|
297
|
+
readonly name = "browser-console";
|
|
298
|
+
readonly level?: BrowserLogLevel;
|
|
299
|
+
private readonly json;
|
|
300
|
+
constructor(options?: {
|
|
301
|
+
json?: boolean;
|
|
302
|
+
level?: BrowserLogLevel;
|
|
303
|
+
});
|
|
304
|
+
write(entry: BrowserLogEntry): void;
|
|
305
|
+
private writeJson;
|
|
306
|
+
private writePretty;
|
|
307
|
+
private levelStyle;
|
|
308
|
+
}
|
|
309
|
+
/**
|
|
310
|
+
* Browser transport that batches log entries and sends them to a remote
|
|
311
|
+
* HTTP endpoint via `fetch` (available in all modern browsers and Edge runtimes).
|
|
312
|
+
*
|
|
313
|
+
* @example
|
|
314
|
+
* ```ts
|
|
315
|
+
* const logger = createBrowserLogger({
|
|
316
|
+
* transports: [
|
|
317
|
+
* new BrowserRemoteTransport({
|
|
318
|
+
* url: '/api/logs',
|
|
319
|
+
* batchSize: 50,
|
|
320
|
+
* flushIntervalMs: 10_000,
|
|
321
|
+
* }),
|
|
322
|
+
* ],
|
|
323
|
+
* });
|
|
324
|
+
* ```
|
|
325
|
+
*/
|
|
326
|
+
declare class BrowserRemoteTransport implements IBrowserTransport {
|
|
327
|
+
readonly name = "browser-remote";
|
|
328
|
+
readonly level?: BrowserLogLevel;
|
|
329
|
+
private readonly url;
|
|
330
|
+
private readonly batchSize;
|
|
331
|
+
private readonly flushIntervalMs;
|
|
332
|
+
private readonly maxBufferSize;
|
|
333
|
+
private readonly headers;
|
|
334
|
+
private batch;
|
|
335
|
+
private timer;
|
|
336
|
+
private droppedEntries;
|
|
337
|
+
constructor(options: {
|
|
338
|
+
/** Endpoint URL to POST batched log entries to. */
|
|
339
|
+
url: string;
|
|
340
|
+
/** Headers added to each request (e.g. `Authorization`). @default {} */
|
|
341
|
+
headers?: Record<string, string>;
|
|
342
|
+
/** Max entries per batch. @default 100 */
|
|
343
|
+
batchSize?: number;
|
|
344
|
+
/**
|
|
345
|
+
* Auto-flush interval in milliseconds. @default 5000
|
|
346
|
+
* Set to `0` to disable the timer — flushing is then manual (`flush()`)
|
|
347
|
+
* or size-triggered (when the batch reaches `batchSize`).
|
|
348
|
+
*/
|
|
349
|
+
flushIntervalMs?: number;
|
|
350
|
+
/**
|
|
351
|
+
* Upper bound on buffered entries. When the buffer exceeds this, the
|
|
352
|
+
* oldest entries are dropped and counted in `dropped`. @default 1000
|
|
353
|
+
*/
|
|
354
|
+
maxBufferSize?: number;
|
|
355
|
+
level?: BrowserLogLevel;
|
|
356
|
+
});
|
|
357
|
+
/**
|
|
358
|
+
* Number of entries dropped without delivery — either because the buffer
|
|
359
|
+
* exceeded `maxBufferSize` (oldest first) or because a POST failed with a
|
|
360
|
+
* non-retryable HTTP status (a 4xx other than 429).
|
|
361
|
+
*/
|
|
362
|
+
get dropped(): number;
|
|
363
|
+
write(entry: BrowserLogEntry): void;
|
|
364
|
+
flush(): Promise<void>;
|
|
365
|
+
private scheduleFlush;
|
|
366
|
+
/**
|
|
367
|
+
* Stop the flush timer and flush remaining entries. Without the final flush,
|
|
368
|
+
* any buffered logs were lost on page unload / teardown — the browser
|
|
369
|
+
* equivalent of the "last N seconds of logs lost on deploy" problem.
|
|
370
|
+
*/
|
|
371
|
+
destroy(): void;
|
|
372
|
+
}
|
|
373
|
+
/**
|
|
374
|
+
* Lightweight browser-safe logger.
|
|
375
|
+
*
|
|
376
|
+
* Unlike the Node.js `LogixiaLogger`, this implementation has **zero**
|
|
377
|
+
* Node.js dependencies. It can be bundled for any runtime.
|
|
378
|
+
*/
|
|
379
|
+
declare class BrowserLogger {
|
|
380
|
+
private readonly config;
|
|
381
|
+
private readonly transports;
|
|
382
|
+
constructor(config?: BrowserLoggerConfig);
|
|
383
|
+
verbose(message: string, payload?: Record<string, unknown>): void;
|
|
384
|
+
debug(message: string, payload?: Record<string, unknown>): void;
|
|
385
|
+
info(message: string, payload?: Record<string, unknown>): void;
|
|
386
|
+
log(message: string, payload?: Record<string, unknown>): void;
|
|
387
|
+
warn(message: string, payload?: Record<string, unknown>): void;
|
|
388
|
+
error(message: string, payload?: Record<string, unknown>): void;
|
|
389
|
+
critical(message: string, payload?: Record<string, unknown>): void;
|
|
390
|
+
/**
|
|
391
|
+
* Create a child logger that inherits config and merges extra context fields
|
|
392
|
+
* into every emitted entry.
|
|
393
|
+
*
|
|
394
|
+
* @example
|
|
395
|
+
* ```ts
|
|
396
|
+
* const childLogger = logger.child({ context: 'AuthService', userId: '42' });
|
|
397
|
+
* childLogger.info('Login succeeded'); // → { context: 'AuthService', userId: '42', ... }
|
|
398
|
+
* ```
|
|
399
|
+
*/
|
|
400
|
+
child(extraContext: Record<string, unknown>): BrowserLogger;
|
|
401
|
+
private emit;
|
|
402
|
+
}
|
|
403
|
+
/**
|
|
404
|
+
* Create a browser-safe logixia logger instance.
|
|
405
|
+
*
|
|
406
|
+
* @example
|
|
407
|
+
* ```ts
|
|
408
|
+
* import { createBrowserLogger } from 'logixia/browser';
|
|
409
|
+
*
|
|
410
|
+
* const logger = createBrowserLogger({ appName: 'checkout', level: 'debug' });
|
|
411
|
+
* logger.info('Cart updated', { itemCount: 3, total: 49.99 });
|
|
412
|
+
* ```
|
|
413
|
+
*/
|
|
414
|
+
declare function createBrowserLogger(config?: BrowserLoggerConfig): BrowserLogger;
|
|
415
|
+
/**
|
|
416
|
+
* Default browser logger instance (singleton, console transport, info level).
|
|
417
|
+
*
|
|
418
|
+
* @example
|
|
419
|
+
* ```ts
|
|
420
|
+
* import { browserLogger } from 'logixia/browser';
|
|
421
|
+
* browserLogger.info('Hello from browser');
|
|
422
|
+
* ```
|
|
423
|
+
*/
|
|
424
|
+
declare const browserLogger: BrowserLogger;
|
|
425
|
+
//#endregion
|
|
426
|
+
export { BrowserConsoleTransport, BrowserLogEntry, BrowserLogLevel, BrowserLogger, BrowserLoggerConfig, BrowserRemoteTransport, type CompiledSchema, IBrowserTransport, type LogFieldDef, type LogFieldType, type LogSchema, type LoggerLike, type OtelBridgeOptions, type OtelSpanContext, type TypedLogger, browserLogger, createBrowserLogger, createTypedLogger, defineLogSchema, disableOtelBridge, getActiveOtelContext, getOtelMetaFields, initOtelBridge };
|
|
427
|
+
//# sourceMappingURL=browser.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser.d.mts","names":[],"sources":["../src/utils/otel.ts","../src/utils/typed-logger.ts","../src/browser.ts"],"sourcesContent":[],"mappings":"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"}
|