@spinajs/log-common 2.0.480 → 2.0.482

package/lib/cjs/persistence.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.persistLevel = persistLevel;
+exports.readPersistedLevel = readPersistedLevel;
+exports.clearPersistedLevel = clearPersistedLevel;
+/**
+ * Browser-only runtime log-level persistence ( loglevel-style ). Lets a user's
+ * `setLevel(...)` choice survive page reloads via `localStorage`, with a
+ * `document.cookie` fallback for environments where storage throws ( eg. Safari
+ * private mode ). On Node ( no `window` ) every helper is a clean no-op.
+ *
+ * Kept dependency-free and free of any `node:*` imports so log-common stays
+ * browser-safe: the only globals touched are `window` / `document`, guarded by
+ * `typeof` checks.
+ */
+const KEY_PREFIX = "spinajs:log:level:";
+function storageKey(loggerName) {
+    return `${KEY_PREFIX}${loggerName}`;
+}
+/** True only in a browser-like environment with a usable localStorage. */
+function hasWindow() {
+    return typeof window !== "undefined";
+}
+function writeCookie(key, value) {
+    if (typeof document === "undefined") {
+        return;
+    }
+    try {
+        // 1 year, path=/ so the value is visible across the app.
+        const maxAge = 60 * 60 * 24 * 365;
+        document.cookie = `${encodeURIComponent(key)}=${encodeURIComponent(value)};path=/;max-age=${maxAge}`;
+    }
+    catch {
+        // nothing else we can do - persistence is best-effort.
+    }
+}
+function readCookie(key) {
+    if (typeof document === "undefined") {
+        return undefined;
+    }
+    try {
+        const enc = encodeURIComponent(key);
+        const parts = document.cookie ? document.cookie.split(";") : [];
+        for (const part of parts) {
+            const [k, ...rest] = part.trim().split("=");
+            if (k === enc) {
+                return decodeURIComponent(rest.join("="));
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return undefined;
+}
+function expireCookie(key) {
+    if (typeof document === "undefined") {
+        return;
+    }
+    try {
+        document.cookie = `${encodeURIComponent(key)}=;path=/;max-age=0`;
+    }
+    catch {
+        // ignore
+    }
+}
+/**
+ * Persist `level` for `loggerName`. Browser only - writes `String(level)` to
+ * localStorage under `spinajs:log:level:<loggerName>`, falling back to a cookie
+ * when storage throws. No-op on Node.
+ */
+function persistLevel(loggerName, level) {
+    if (!hasWindow()) {
+        return;
+    }
+    const key = storageKey(loggerName);
+    const value = String(level);
+    try {
+        // window.localStorage access itself can throw ( disabled cookies / private mode ).
+        if (window.localStorage) {
+            window.localStorage.setItem(key, value);
+            return;
+        }
+    }
+    catch {
+        // fall through to the cookie fallback below.
+    }
+    writeCookie(key, value);
+}
+/**
+ * Read back the persisted level for `loggerName` ( localStorage then cookie ).
+ * Returns a finite {@link LogLevel} number, or `undefined` when nothing valid is
+ * stored. Always `undefined` on Node.
+ */
+function readPersistedLevel(loggerName) {
+    if (!hasWindow()) {
+        return undefined;
+    }
+    const key = storageKey(loggerName);
+    let raw;
+    try {
+        if (window.localStorage) {
+            raw = window.localStorage.getItem(key);
+        }
+    }
+    catch {
+        raw = undefined;
+    }
+    if (raw === null || raw === undefined) {
+        raw = readCookie(key);
+    }
+    if (raw === null || raw === undefined || raw === "") {
+        return undefined;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * Remove any persisted level for `loggerName` ( localStorage + cookie ). No-op
+ * on Node.
+ */
+function clearPersistedLevel(loggerName) {
+    if (!hasWindow()) {
+        return;
+    }
+    const key = storageKey(loggerName);
+    try {
+        if (window.localStorage) {
+            window.localStorage.removeItem(key);
+        }
+    }
+    catch {
+        // ignore - fall through to also expire the cookie.
+    }
+    expireCookie(key);
+}
+//# sourceMappingURL=persistence.js.map

package/lib/cjs/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../../src/persistence.ts"],"names":[],"mappings":"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"}

package/lib/cjs/serializers.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Pure, dependency-free serialization helpers used by the log targets.
+ *
+ * These functions are intentionally browser-safe: they use no Node-only APIs
+ * ( no `util`, no `Buffer` ), only plain ECMAScript. They are also written to
+ * be defensive - neither of them may ever throw, because a logger that crashes
+ * while trying to log an error is worse than useless.
+ */
+/**
+ * Structured representation of an Error suitable for JSON serialization.
+ */
+export interface ISerializedError {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string | number;
+    signal?: string;
+}
+/**
+ * Turn an `Error` into a plain, JSON-friendly record.
+ *
+ * - Returns `undefined` for anything that is not an `Error` ( callers only
+ *   serialize actual errors ).
+ * - `stack` walks the `.cause` chain and any `AggregateError.errors`, appending
+ *   each nested error under a `Caused by:` line ( bunyan-style ).
+ * - `code` / `signal` are included only when present ( common on Node system
+ *   errors such as `ECONNREFUSED` / `SIGTERM` ).
+ * - Never throws.
+ */
+export declare function serializeError(err: unknown): ISerializedError | undefined;
+/**
+ * A serializer turns a raw log-variable value into a structured, log-friendly
+ * form. It receives the value stored under a given field name and returns its
+ * replacement. Returning `undefined` means "leave the original value alone"
+ * ( e.g. `serializeError` returns `undefined` for a non-Error ).
+ */
+export type LogSerializer = (value: unknown) => unknown;
+/**
+ * Registry of field-name -> serializer. Applied by {@link applySerializers} to
+ * every log entry's variables. Out of the box the SpinaJS `error` variable
+ * ( set by `createLogMessageObject` ) is serialized by {@link serializeError },
+ * so `error` becomes a plain `{ name, message, stack, code, signal }` record
+ * instead of an opaque `Error`.
+ */
+export declare const serializers: Map<string, LogSerializer>;
+/**
+ * Register ( or override ) the serializer used for a given log-variable field.
+ */
+export declare function registerSerializer(field: string, fn: LogSerializer): void;
+/**
+ * Apply the registered serializers to a log entry's variables, MUTATING `vars`
+ * in place.
+ *
+ * For each registered `[field, fn]`:
+ *   - skip when `field` is absent or its value is `undefined` / `null`;
+ *   - run `fn` inside a try/catch:
+ *       - on success, overwrite `vars[field]` ONLY when the serializer returned
+ *         a defined value, so a serializer that returns `undefined` for an
+ *         unhandled value ( like `serializeError` on a non-Error ) leaves the
+ *         original untouched;
+ *       - on throw, replace the value with `{ serializerError: <message> }` so a
+ *         broken serializer degrades gracefully and NEVER crashes the caller.
+ */
+export declare function applySerializers(vars: Record<string, unknown>): void;
+/**
+ * JSON-stringify any value without ever throwing.
+ *
+ * Three tiers:
+ *   1. plain `JSON.stringify` ( the common, fast path );
+ *   2. on throw ( typically circular references ) retry with a replacer that
+ *      swaps already-seen objects for the string `"[Circular]"`, producing
+ *      VALID JSON;
+ *   3. if that still throws ( e.g. a getter that throws while enumerating ),
+ *      fall back to `String(value)`.
+ */
+export declare function safeStringify(value: unknown, indent?: number): string;
+//# sourceMappingURL=serializers.d.ts.map

package/lib/cjs/serializers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializers.d.ts","sourceRoot":"","sources":["../../src/serializers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA8ED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAiCzE;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,4BAA+E,CAAC;AAExG;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,GAAG,IAAI,CAEzE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAoBpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CA4BrE"}

package/lib/cjs/serializers.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * Pure, dependency-free serialization helpers used by the log targets.
+ *
+ * These functions are intentionally browser-safe: they use no Node-only APIs
+ * ( no `util`, no `Buffer` ), only plain ECMAScript. They are also written to
+ * be defensive - neither of them may ever throw, because a logger that crashes
+ * while trying to log an error is worse than useless.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializers = void 0;
+exports.serializeError = serializeError;
+exports.registerSerializer = registerSerializer;
+exports.applySerializers = applySerializers;
+exports.safeStringify = safeStringify;
+/**
+ * Max depth we walk down the `.cause` chain. A self-referential cause
+ * ( `err.cause = err` ) would otherwise loop forever, so we cap the walk.
+ */
+const MAX_CAUSE_DEPTH = 10;
+/**
+ * Best-effort read of a property that might be defined via a throwing getter.
+ * Returns `undefined` instead of propagating the throw.
+ */
+function safeGet(obj, key) {
+    try {
+        return obj[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Returns the most useful string form of an error for embedding in a stack:
+ * its `.stack` when available, otherwise its `.message`, otherwise `String()`.
+ */
+function errorText(err) {
+    const stack = safeGet(err, "stack");
+    if (typeof stack === "string" && stack.length > 0) {
+        return stack;
+    }
+    const message = safeGet(err, "message");
+    if (typeof message === "string" && message.length > 0) {
+        return message;
+    }
+    try {
+        return String(err);
+    }
+    catch {
+        return "[unserializable error]";
+    }
+}
+/**
+ * Builds a combined stack string that walks the `.cause` chain and, for
+ * `AggregateError`, its inner `errors`. Mirrors bunyan's `getFullErrorStack`:
+ * each nested error is appended under a `Caused by:` line.
+ *
+ * `seen` guards against cycles ( shared cause objects ) and `depth` caps how
+ * far down the chain we recurse, so a self-referential cause cannot hang.
+ */
+function buildFullStack(err, seen, depth) {
+    let out = errorText(err);
+    if (depth >= MAX_CAUSE_DEPTH || seen.has(err)) {
+        return out;
+    }
+    seen.add(err);
+    // Follow the standard `.cause` chain ( ES2022 error cause ).
+    const cause = safeGet(err, "cause");
+    if (cause instanceof Error && !seen.has(cause)) {
+        out += "\nCaused by: " + buildFullStack(cause, seen, depth + 1);
+    }
+    // AggregateError ( or any error carrying an `errors` array ) - surface each
+    // inner error under the same `Caused by:` style.
+    const errors = safeGet(err, "errors");
+    if (Array.isArray(errors)) {
+        for (const inner of errors) {
+            if (inner instanceof Error && !seen.has(inner)) {
+                out += "\nCaused by: " + buildFullStack(inner, seen, depth + 1);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Turn an `Error` into a plain, JSON-friendly record.
+ *
+ * - Returns `undefined` for anything that is not an `Error` ( callers only
+ *   serialize actual errors ).
+ * - `stack` walks the `.cause` chain and any `AggregateError.errors`, appending
+ *   each nested error under a `Caused by:` line ( bunyan-style ).
+ * - `code` / `signal` are included only when present ( common on Node system
+ *   errors such as `ECONNREFUSED` / `SIGTERM` ).
+ * - Never throws.
+ */
+function serializeError(err) {
+    if (!(err instanceof Error)) {
+        return undefined;
+    }
+    try {
+        const name = typeof err.name === "string" ? err.name : "Error";
+        const message = typeof err.message === "string" ? err.message : "";
+        const result = { name, message };
+        const stack = buildFullStack(err, new Set(), 0);
+        if (stack.length > 0) {
+            result.stack = stack;
+        }
+        // Node system errors carry a `code` ( e.g. 'ECONNREFUSED' ) and sometimes a
+        // `signal` ( e.g. 'SIGTERM' ). Include them only when actually present.
+        const code = safeGet(err, "code");
+        if (typeof code === "string" || typeof code === "number") {
+            result.code = code;
+        }
+        const signal = safeGet(err, "signal");
+        if (typeof signal === "string") {
+            result.signal = signal;
+        }
+        return result;
+    }
+    catch {
+        // Absolute last-resort guard - serialization must never throw.
+        return { name: "Error", message: "[unserializable error]" };
+    }
+}
+/**
+ * Registry of field-name -> serializer. Applied by {@link applySerializers} to
+ * every log entry's variables. Out of the box the SpinaJS `error` variable
+ * ( set by `createLogMessageObject` ) is serialized by {@link serializeError },
+ * so `error` becomes a plain `{ name, message, stack, code, signal }` record
+ * instead of an opaque `Error`.
+ */
+exports.serializers = new Map([["error", serializeError]]);
+/**
+ * Register ( or override ) the serializer used for a given log-variable field.
+ */
+function registerSerializer(field, fn) {
+    exports.serializers.set(field, fn);
+}
+/**
+ * Apply the registered serializers to a log entry's variables, MUTATING `vars`
+ * in place.
+ *
+ * For each registered `[field, fn]`:
+ *   - skip when `field` is absent or its value is `undefined` / `null`;
+ *   - run `fn` inside a try/catch:
+ *       - on success, overwrite `vars[field]` ONLY when the serializer returned
+ *         a defined value, so a serializer that returns `undefined` for an
+ *         unhandled value ( like `serializeError` on a non-Error ) leaves the
+ *         original untouched;
+ *       - on throw, replace the value with `{ serializerError: <message> }` so a
+ *         broken serializer degrades gracefully and NEVER crashes the caller.
+ */
+function applySerializers(vars) {
+    for (const [field, fn] of exports.serializers) {
+        if (!(field in vars)) {
+            continue;
+        }
+        const value = vars[field];
+        if (value === undefined || value === null) {
+            continue;
+        }
+        try {
+            const s = fn(value);
+            if (s !== undefined) {
+                vars[field] = s;
+            }
+        }
+        catch (e) {
+            vars[field] = { serializerError: e?.message ?? String(e) };
+        }
+    }
+}
+/**
+ * JSON-stringify any value without ever throwing.
+ *
+ * Three tiers:
+ *   1. plain `JSON.stringify` ( the common, fast path );
+ *   2. on throw ( typically circular references ) retry with a replacer that
+ *      swaps already-seen objects for the string `"[Circular]"`, producing
+ *      VALID JSON;
+ *   3. if that still throws ( e.g. a getter that throws while enumerating ),
+ *      fall back to `String(value)`.
+ */
+function safeStringify(value, indent) {
+    try {
+        // Tier 1: the fast, common path.
+        return JSON.stringify(value, undefined, indent);
+    }
+    catch {
+        // Tier 2: handle circular references with a WeakSet of seen objects.
+        try {
+            const seen = new WeakSet();
+            const replacer = (_key, val) => {
+                if (val !== null && typeof val === "object") {
+                    if (seen.has(val)) {
+                        return "[Circular]";
+                    }
+                    seen.add(val);
+                }
+                return val;
+            };
+            return JSON.stringify(value, replacer, indent);
+        }
+        catch {
+            // Tier 3: something else threw ( e.g. a throwing getter ). Give up on
+            // structured output but still return *a* string.
+            try {
+                return String(value);
+            }
+            catch {
+                return "[unserializable value]";
+            }
+        }
+    }
+}
+//# sourceMappingURL=serializers.js.map

package/lib/cjs/serializers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializers.js","sourceRoot":"","sources":["../../src/serializers.ts"],"names":[],"mappings":"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"}

package/lib/mjs/BatchQueue.d.ts

@@ -0,0 +1,127 @@
+/**
+ * A small, dependency-free, browser-safe buffered-batch queue.
+ *
+ * `BatchQueue<T>` owns ACCUMULATION and FLUSH TRIGGERING only; it delegates the
+ * actual I/O to the owner via `onFlush`. Ported from the essence of
+ * OpenTelemetry's BatchLogRecordProcessor.
+ *
+ * Triggers a flush when either:
+ *  - the buffer reaches `maxBatch` items ( size trigger ), or
+ *  - the periodic timer fires every `flushIntervalMs` ( interval trigger ).
+ *
+ * ## Failure model
+ *
+ * There are two, deliberately distinct, ways items can leave the queue:
+ *
+ *  1. **Overflow ( the ONLY silent drop ).** The buffer is hard-capped at
+ *     `maxQueue`. When it grows past the cap the OLDEST items are dropped so
+ *     memory stays bounded, and `onOverflow(droppedItems)` fires. This is the
+ *     back-pressure release valve for a stuck/slow sink.
+ *
+ *  2. **Flush failure ( never a silent drop ).** `onFlush` may throw / reject.
+ *     `BatchQueue` does NOT retry, requeue, or swallow the batch on its own —
+ *     that is the owner's decision. The rejection PROPAGATES to any caller that
+ *     awaits `flush()` / `forceFlush()`, so the owner can `catch` it and call
+ *     `requeueFront(batch)` to put the batch back at the front ( never-drop
+ *     semantics ) or drop it deliberately. The periodic timer intentionally
+ *     ignores the rejection ( `void this.flush()` ) so a failing sink never
+ *     kills the flush loop; the in-flight guard is always cleared in `finally`
+ *     so the next flush can proceed regardless of outcome.
+ *
+ * ## Re-entrancy
+ *
+ * At most one `onFlush` runs at a time. If a flush is already in flight, calling
+ * `flush()` returns the SAME in-flight promise ( coalesced ) rather than
+ * starting a second `onFlush`. A flush snapshots and clears the buffer
+ * synchronously before awaiting the I/O, so items enqueued during a flush land
+ * in a fresh buffer and are picked up by the next flush.
+ *
+ * ## Runtime
+ *
+ * Uses only `setInterval` / `setTimeout` ( available in both Node and browsers ).
+ * The periodic timer ( and the optional per-flush timeout timer ) are `unref()`'d
+ * when that method exists, so they never keep a Node process alive; the `?.`
+ * guard makes the calls harmless in browsers.
+ */
+export interface IBatchQueueOptions<T> {
+    /** Flush automatically once the buffer reaches this many items. */
+    maxBatch: number;
+    /** Hard cap on buffered items. Beyond it the OLDEST are dropped ( onOverflow fires ). */
+    maxQueue: number;
+    /** Periodic flush tick in ms. The timer is unref()'d so it never blocks process exit. */
+    flushIntervalMs: number;
+    /** Optional per-flush timeout in ms. If onFlush does not settle in time, the flush rejects. */
+    exportTimeoutMs?: number;
+    /** Does the actual I/O for a batch. May throw/reject; the owner handles retry/requeue/drop. */
+    onFlush: (items: T[]) => Promise<void>;
+    /**
+     * Called when the queue cap is exceeded and the oldest items are dropped.
+     * Receives the DROPPED ITEMS themselves ( oldest first ) so an owner can route
+     * exactly what was dropped to a fallback ( see LogTarget.OnDropped ). Use
+     * `droppedItems.length` when only the count matters.
+     */
+    onOverflow?: (droppedItems: T[]) => void;
+}
+export declare class BatchQueue<T> {
+    private options;
+    private buffer;
+    private timer;
+    private stopped;
+    /**
+     * The currently running flush, or null when idle. Used both as the
+     * re-entrancy guard ( coalesce concurrent flush() calls ) and to let
+     * forceFlush()/shutdown() wait for an in-flight flush before draining.
+     */
+    private inFlight;
+    constructor(options: IBatchQueueOptions<T>);
+    /** Current number of buffered items. */
+    get size(): number;
+    /**
+     * Add an item to the buffer.
+     *
+     * If the queue has been shut down this is a no-op that resolves immediately.
+     * When the buffer reaches `maxBatch` a flush is triggered and its promise is
+     * returned, so a caller MAY await a size-triggered flush; otherwise resolves
+     * immediately.
+     */
+    enqueue(item: T): Promise<void>;
+    /**
+     * Put items back at the FRONT of the buffer ( then enforce the cap ). Owners
+     * use this to re-queue a batch whose `onFlush` failed, without dropping it.
+     */
+    requeueFront(items: T[]): void;
+    /**
+     * Enforce the hard `maxQueue` cap by dropping the OLDEST items. Fires
+     * `onOverflow(droppedItems)` with the spliced-out items when anything is dropped.
+     */
+    private enforceCap;
+    /**
+     * Flush the entire buffer in a single `onFlush` call.
+     *
+     * Re-entrancy: if a flush is already in flight, that same promise is returned
+     * ( no second `onFlush` ). If the buffer is empty, resolves immediately.
+     * Otherwise the buffer is snapshotted and cleared synchronously, `onFlush`
+     * runs ( optionally raced against `exportTimeoutMs` ), and the in-flight guard
+     * is cleared in `finally` regardless of success or failure. The returned
+     * promise settles with `onFlush`'s outcome so an awaiting owner can catch a
+     * rejection and requeue.
+     */
+    flush(): Promise<void>;
+    /**
+     * Race a flush promise against a timeout that rejects after `ms`. The timeout
+     * timer is cleared ( and unref()'d ) so it neither leaks nor keeps the loop alive.
+     */
+    private withTimeout;
+    /**
+     * Flush any buffered items and await completion. If a flush is already in
+     * flight, wait for it first, then flush any remainder that accumulated. Since
+     * a single `flush()` drains the ENTIRE buffer, one follow-up flush suffices.
+     */
+    forceFlush(): Promise<void>;
+    /**
+     * Stop the periodic timer and perform a best-effort final flush of buffered
+     * items. After shutdown, `enqueue` is a no-op that resolves.
+     */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=BatchQueue.d.ts.map

package/lib/mjs/BatchQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BatchQueue.d.ts","sourceRoot":"","sources":["../../src/BatchQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,eAAe,EAAE,MAAM,CAAC;IACxB,+FAA+F;IAC/F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;CAC1C;AAED,qBAAa,UAAU,CAAC,CAAC;IAcX,OAAO,CAAC,OAAO;IAb3B,OAAO,CAAC,MAAM,CAAW;IAEzB,OAAO,CAAC,KAAK,CAAiC;IAE9C,OAAO,CAAC,OAAO,CAAS;IAExB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAA8B;gBAE1B,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAMlD,wCAAwC;IACxC,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;;;;;OAOG;IACI,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAetC;;;OAGG;IACI,YAAY,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;IAKrC;;;OAGG;IACH,OAAO,CAAC,UAAU;IAQlB;;;;;;;;;;OAUG;IACI,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB7B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAanB;;;;OAIG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQxC;;;OAGG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAKvC"}