@spinajs/log-common 2.0.480 → 2.0.482

package/README.md

@@ -1,11 +1,132 @@
 # `@spinajs/log-common`
 
-> TODO: description
+Shared, dependency-light contracts for the SpinaJS logging stack. This package
+holds no logging implementation of its own; it defines the abstract types that
+`@spinajs/log`, `@spinajs/internal-logger` and the various log-source packages
+implement. Depend on it when you write a **custom log target** or a **custom
+`Log` implementation**, and want to avoid a circular dependency on `@spinajs/log`.
 
-## Usage
+## What lives here
 
+| Export | Purpose |
+| --- | --- |
+| `Log` (abstract) | The logger contract: `trace/debug/info/warn/error/fatal/security/success`, `child`, `write`, `addVariable`, `timeStart/timeEnd`. |
+| `LogTarget<T>` (abstract) | A sink that receives `ILogEntry` objects and writes them somewhere ( console, file, HTTP, ... ). |
+| `createLogMessageObject` | Builds a normalized `ILogEntry` from the many call shapes the `Log` methods accept. |
+| `LogLevel` / `StrToLogLevel` / `LogLevelStrings` | Level enum and string<->enum maps. |
+| `ILogEntry`, `ILogRule`, `ICommonTargetOptions`, `IFileTargetOptions`, `ILogOptions` | Config and payload shapes. |
+
+## The `LogTarget` contract
+
+```ts
+abstract class LogTarget<T extends ICommonTargetOptions> extends SyncService {
+  public HasError: boolean;              // true after a failed write, cleared on the next success
+  public Error: Error | null | unknown;  // the last write error, or null
+  public Options: T;                     // merged options ( includes the default layout )
+  public abstract write(data: ILogEntry): void;
+}
 ```
-const logCommon = require('@spinajs/log-common');
 
-// TODO: DEMONSTRATE API
+A target receives fully-formed `ILogEntry` objects. It is responsible for:
+
+- honouring `Options.enabled` ( skip when `false` ),
+- rendering `data.Variables` through its `Options.layout`,
+- setting `HasError = true` / `Error = err` when a write fails and clearing them
+  ( `HasError = false`, `Error = null` ) on the next successful write. Consumers
+  can poll these fields to detect a degraded sink.
+
+## `createLogMessageObject`
+
+```ts
+createLogMessageObject(
+  err: Error | string,
+  message: string | any[],
+  level: LogLevel,
+  logger: string,
+  variables: any,
+  ...args: any[]
+): ILogEntry
 ```
+
+It normalizes the two calling conventions the `Log` methods accept:
+
+- **Message overload** — `err` is the format string ( or `undefined` ) and
+  `message` carries the format arguments, e.g. `log.info("hello %s", "world")`.
+- **Error overload** — `err` is an `Error` and `message` is the human message,
+  e.g. `log.error(err, "could not connect")`.
+
+Rules it applies:
+
+- `sMsg = (err instanceof Error || !err) ? message : err` — an `err` string is
+  itself the message body, so a bare `log.info("hi")` works.
+- `tMsg = args.length ? format(sMsg, ...args) : sMsg` — runs `util.format`-style
+  substitution ( see `format.ts`; `%s %d %i %f %j %o %O %%` ) only when there are
+  args.
+- `Variables.error` is set only for the `Error` overload.
+- `Variables.logger = logger ?? message` and `Variables.level` is the upper-cased
+  level string.
+
+The returned entry is:
+
+```ts
+{
+  Level: LogLevel,
+  Variables: {
+    error,     // Error | undefined
+    level,     // "INFO" | "ERROR" | ...
+    logger,    // logger name
+    message,   // formatted message
+    ...variables
+  }
+}
+```
+
+## Layout variables
+
+A target's `layout` is a template string resolved by `@spinajs/configuration`'s
+`format(variables, layout)`. Every key on `ILogEntry.Variables` is available as
+`${key}`. The always-present variables are:
+
+| Variable | Value |
+| --- | --- |
+| `${datetime}` | timestamp of the entry |
+| `${level}` | upper-cased level, e.g. `INFO` |
+| `${message}` | the formatted message |
+| `${error}` | the `Error` ( use `${error:message}` for its message ) |
+| `${logger}` | the logger name |
+
+Conditional blocks are supported, e.g. `${?error} ... ${/error}` only renders
+when `error` is set. Any custom variable you attach via `log.addVariable(name, value)`
+or the config `variables` array is also available as `${name}`.
+
+The default layout ( applied to every target unless overridden ) is:
+
+```
+${datetime} ${level} ${message}${?error} Exception: ${error:message}${/error} (${logger})
+```
+
+## Writing a custom target
+
+```ts
+import { Injectable } from "@spinajs/di";
+import { format } from "@spinajs/configuration";
+import { LogTarget, ILogEntry, ICommonTargetOptions } from "@spinajs/log-common";
+
+@Injectable("MyTarget") // referenced by `type: "MyTarget"` in config
+export class MyTarget extends LogTarget<ICommonTargetOptions> {
+  public write(data: ILogEntry): void {
+    if (!this.Options.enabled) return;
+    try {
+      // render with the configured layout and send it somewhere
+      send(format(data.Variables, this.Options.layout));
+      this.HasError = false;
+      this.Error = null;
+    } catch (err) {
+      this.HasError = true;
+      this.Error = err;
+    }
+  }
+}
+```
+
+See `@spinajs/log` for the concrete targets and the rules/targets configuration.

package/lib/cjs/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/cjs/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"}

package/lib/cjs/BatchQueue.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchQueue = void 0;
+class BatchQueue {
+    constructor(options) {
+        this.options = options;
+        this.buffer = [];
+        this.stopped = false;
+        /**
+         * 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.
+         */
+        this.inFlight = null;
+        this.timer = setInterval(() => void this.flush(), this.options.flushIntervalMs);
+        // Do not keep the event loop / process alive just for the flush tick.
+        this.timer.unref?.();
+    }
+    /** Current number of buffered items. */
+    get size() {
+        return this.buffer.length;
+    }
+    /**
+     * 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) {
+        if (this.stopped) {
+            return Promise.resolve();
+        }
+        this.buffer.push(item);
+        this.enforceCap();
+        if (this.size >= this.options.maxBatch) {
+            return this.flush();
+        }
+        return Promise.resolve();
+    }
+    /**
+     * 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) {
+        this.buffer = [...items, ...this.buffer];
+        this.enforceCap();
+    }
+    /**
+     * Enforce the hard `maxQueue` cap by dropping the OLDEST items. Fires
+     * `onOverflow(droppedItems)` with the spliced-out items when anything is dropped.
+     */
+    enforceCap() {
+        if (this.buffer.length > this.options.maxQueue) {
+            const dropCount = this.buffer.length - this.options.maxQueue;
+            const droppedItems = this.buffer.splice(0, dropCount);
+            this.options.onOverflow?.(droppedItems);
+        }
+    }
+    /**
+     * 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() {
+        if (this.inFlight) {
+            return this.inFlight;
+        }
+        if (this.buffer.length === 0) {
+            return Promise.resolve();
+        }
+        const batch = this.buffer;
+        this.buffer = [];
+        const run = this.options.exportTimeoutMs !== undefined ? this.withTimeout(this.options.onFlush(batch), this.options.exportTimeoutMs) : this.options.onFlush(batch);
+        // Store as the guard and clear it once settled ( success OR failure ) so the
+        // next flush can proceed. The promise is still returned to the caller so the
+        // rejection propagates for owner-side handling.
+        this.inFlight = run.finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    /**
+     * 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.
+     */
+    withTimeout(promise, ms) {
+        let timeout;
+        const timer = new Promise((_resolve, reject) => {
+            timeout = setTimeout(() => reject(new Error(`BatchQueue flush timed out after ${ms}ms`)), ms);
+            timeout.unref?.();
+        });
+        return Promise.race([promise, timer]).finally(() => {
+            clearTimeout(timeout);
+        });
+    }
+    /**
+     * 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.
+     */
+    async forceFlush() {
+        if (this.inFlight) {
+            await this.inFlight;
+        }
+        await this.flush();
+    }
+    /**
+     * Stop the periodic timer and perform a best-effort final flush of buffered
+     * items. After shutdown, `enqueue` is a no-op that resolves.
+     */
+    async shutdown() {
+        this.stopped = true;
+        clearInterval(this.timer);
+        await this.forceFlush();
+    }
+}
+exports.BatchQueue = BatchQueue;
+//# sourceMappingURL=BatchQueue.js.map

package/lib/cjs/BatchQueue.js.map

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

package/lib/cjs/filters/filter.d.ts

@@ -0,0 +1,27 @@
+import type { ILogEntry } from "../index.js";
+/**
+ * Common shape of a configured filter entry. `type` is the DI string name the
+ * filter is registered under ( eg. "LevelFilter" ); all other keys are the
+ * filter's own free-form options and are read by the concrete filter.
+ */
+export interface ILogFilterOptions {
+    type: string;
+    [k: string]: unknown;
+}
+/**
+ * Base class for a composable log filter. Filters are DI-registered by string
+ * name ( just like log targets ) via `@Injectable("<Name>")` and resolved per
+ * logger from `logger.filters` config. They run IN ORDER inside the logger's
+ * `write()`: each filter may pass the entry through ( optionally mutating it ),
+ * or return `null` to DROP it entirely.
+ *
+ * Kept a plain, dependency-light abstract class ( no SyncService etc. ) so the
+ * contract stays browser-safe and cheap to instantiate.
+ */
+export declare abstract class LogFilter {
+    protected options?: ILogFilterOptions | undefined;
+    constructor(options?: ILogFilterOptions | undefined);
+    /** Return the ( possibly modified ) entry to keep, or null to DROP it. */
+    abstract apply(entry: ILogEntry): ILogEntry | null;
+}
+//# sourceMappingURL=filter.d.ts.map

package/lib/cjs/filters/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/filters/filter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,8BAAsB,SAAS;IACjB,SAAS,CAAC,OAAO,CAAC,EAAE,iBAAiB;gBAA3B,OAAO,CAAC,EAAE,iBAAiB,YAAA;IAEjD,0EAA0E;aAC1D,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;CAC1D"}

package/lib/cjs/filters/filter.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogFilter = void 0;
+/**
+ * Base class for a composable log filter. Filters are DI-registered by string
+ * name ( just like log targets ) via `@Injectable("<Name>")` and resolved per
+ * logger from `logger.filters` config. They run IN ORDER inside the logger's
+ * `write()`: each filter may pass the entry through ( optionally mutating it ),
+ * or return `null` to DROP it entirely.
+ *
+ * Kept a plain, dependency-light abstract class ( no SyncService etc. ) so the
+ * contract stays browser-safe and cheap to instantiate.
+ */
+class LogFilter {
+    constructor(options) {
+        this.options = options;
+    }
+}
+exports.LogFilter = LogFilter;
+//# sourceMappingURL=filter.js.map

package/lib/cjs/filters/filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../../../src/filters/filter.ts"],"names":[],"mappings":";;;AAeA;;;;;;;;;GASG;AACH,MAAsB,SAAS;IAC7B,YAAsB,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;IAAG,CAAC;CAItD;AALD,8BAKC"}

package/lib/cjs/filters/whenRepeated.d.ts

@@ -0,0 +1,52 @@
+import type { ILogEntry } from "../index.js";
+import { LogFilter, ILogFilterOptions } from "./filter.js";
+export interface IWhenRepeatedOptions extends Partial<ILogFilterOptions> {
+    /**
+     * Suppression window in SECONDS. Identical entries logged within this window
+     * ( from the first occurrence ) are collapsed into one. Default is 10.
+     */
+    timeout?: number;
+    /**
+     * Hard cap on the number of tracked keys. The internal map is self-pruning:
+     * expired records are dropped first, then the oldest, so memory stays bounded
+     * even under many distinct messages. Default is 1024.
+     */
+    maxKeys?: number;
+}
+interface IRepeatRecord {
+    count: number;
+    windowStart: number;
+    level: number;
+}
+/**
+ * Port of NLog's WhenRepeatedFilter. Collapses identical, repeated log entries
+ * within a timeout window into a single emitted entry, appending a ` (xN)`
+ * suppressed-count when logging of that key resumes. This stops a hot loop or a
+ * flapping error from flooding console / file / Loki and burying real signal.
+ *
+ * Known tradeoff: there is no background timer. A residual suppressed count is
+ * flushed on the NEXT matching entry ( window expired or higher severity ), NOT
+ * when the window simply elapses with no further activity. This keeps the filter
+ * dependency-free; the full filter pipeline in a later phase can layer a timed
+ * flush on top.
+ */
+export declare class WhenRepeatedFilter extends LogFilter {
+    protected now: () => number;
+    protected timeoutMs: number;
+    protected maxKeys: number;
+    protected records: Map<string, IRepeatRecord>;
+    constructor(options?: IWhenRepeatedOptions, now?: () => number);
+    protected keyOf(entry: ILogEntry): string;
+    /**
+     * Returns the entry to EMIT ( possibly with an injected suppressed-count ) or
+     * `null` to SUPPRESS.
+     */
+    apply(entry: ILogEntry): ILogEntry | null;
+    /**
+     * Keeps the tracked-key map bounded. Drops expired records first, then the
+     * oldest by `windowStart` until at/under the cap.
+     */
+    protected prune(now: number): void;
+}
+export {};
+//# sourceMappingURL=whenRepeated.d.ts.map

package/lib/cjs/filters/whenRepeated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whenRepeated.d.ts","sourceRoot":"","sources":["../../../src/filters/whenRepeated.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE3D,MAAM,WAAW,oBAAqB,SAAQ,OAAO,CAAC,iBAAiB,CAAC;IACtE;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,aAAa;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,qBAEa,kBAAmB,SAAQ,SAAS;IAKH,SAAS,CAAC,GAAG,EAAE,MAAM,MAAM;IAJvE,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAa;gBAE9C,OAAO,CAAC,EAAE,oBAAoB,EAAY,GAAG,GAAE,MAAM,MAAyB;IAM1F,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM;IAIzC;;;OAGG;IACI,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;IA8BhD;;;OAGG;IACH,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAuBnC"}

package/lib/cjs/filters/whenRepeated.js

@@ -0,0 +1,98 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WhenRepeatedFilter = void 0;
+const di_1 = require("@spinajs/di");
+const filter_js_1 = require("./filter.js");
+/**
+ * Port of NLog's WhenRepeatedFilter. Collapses identical, repeated log entries
+ * within a timeout window into a single emitted entry, appending a ` (xN)`
+ * suppressed-count when logging of that key resumes. This stops a hot loop or a
+ * flapping error from flooding console / file / Loki and burying real signal.
+ *
+ * Known tradeoff: there is no background timer. A residual suppressed count is
+ * flushed on the NEXT matching entry ( window expired or higher severity ), NOT
+ * when the window simply elapses with no further activity. This keeps the filter
+ * dependency-free; the full filter pipeline in a later phase can layer a timed
+ * flush on top.
+ */
+let WhenRepeatedFilter = class WhenRepeatedFilter extends filter_js_1.LogFilter {
+    constructor(options, now = () => Date.now()) {
+        super(options);
+        this.now = now;
+        this.records = new Map();
+        this.timeoutMs = (options?.timeout ?? 10) * 1000;
+        this.maxKeys = options?.maxKeys ?? 1024;
+    }
+    keyOf(entry) {
+        return `${entry.Level}|${entry.Variables.logger}|${entry.Variables.message}`;
+    }
+    /**
+     * Returns the entry to EMIT ( possibly with an injected suppressed-count ) or
+     * `null` to SUPPRESS.
+     */
+    apply(entry) {
+        const key = this.keyOf(entry);
+        const now = this.now();
+        const record = this.records.get(key);
+        if (!record) {
+            // first occurrence of this key - emit and start tracking
+            this.records.set(key, { count: 0, windowStart: now, level: entry.Level });
+            this.prune(now);
+            return entry;
+        }
+        if (now - record.windowStart < this.timeoutMs && entry.Level <= record.level) {
+            // still inside the window and not a higher severity - suppress
+            record.count++;
+            return null;
+        }
+        // window expired OR a higher-severity entry arrived - emit and reset. If we
+        // suppressed anything, inject the count into the ( freshly built per call,
+        // so safe to mutate ) message string.
+        if (record.count > 0) {
+            entry.Variables.message = `${entry.Variables.message} (x${record.count})`;
+        }
+        this.records.set(key, { count: 0, windowStart: now, level: entry.Level });
+        this.prune(now);
+        return entry;
+    }
+    /**
+     * Keeps the tracked-key map bounded. Drops expired records first, then the
+     * oldest by `windowStart` until at/under the cap.
+     */
+    prune(now) {
+        if (this.records.size <= this.maxKeys) {
+            return;
+        }
+        for (const [k, r] of this.records) {
+            if (now - r.windowStart >= this.timeoutMs) {
+                this.records.delete(k);
+            }
+        }
+        if (this.records.size <= this.maxKeys) {
+            return;
+        }
+        const byAge = [...this.records.entries()].sort((a, b) => a[1].windowStart - b[1].windowStart);
+        for (const [k] of byAge) {
+            if (this.records.size <= this.maxKeys) {
+                break;
+            }
+            this.records.delete(k);
+        }
+    }
+};
+exports.WhenRepeatedFilter = WhenRepeatedFilter;
+exports.WhenRepeatedFilter = WhenRepeatedFilter = __decorate([
+    (0, di_1.Injectable)("WhenRepeatedFilter"),
+    (0, di_1.NewInstance)(),
+    __metadata("design:paramtypes", [Object, Function])
+], WhenRepeatedFilter);
+//# sourceMappingURL=whenRepeated.js.map

package/lib/cjs/filters/whenRepeated.js.map

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

package/lib/cjs/format.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal, platform-free clone of Node's `util.format`.
+ *
+ * Supports the format specifiers the framework actually uses:
+ *   %s  - String
+ *   %d  - Number ( integer )
+ *   %i  - parseInt
+ *   %f  - parseFloat
+ *   %j  - JSON
+ *   %o  - Object ( JSON.stringify )
+ *   %O  - Object ( JSON.stringify )
+ *   %%  - literal percent sign ( consumes no argument )
+ *
+ * Any arguments left over after the specifiers are consumed are appended,
+ * space-separated. Objects are rendered via JSON.stringify ( circular refs
+ * fall back to String() ). This avoids pulling in Node's `util` module so the
+ * logger is usable in the browser.
+ */
+export declare function format(f?: any, ...args: any[]): string;
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/format.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CA0CtD"}