@warlock.js/core 4.0.174 → 4.1.3

package/esm/benchmark/channels/console.channel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.channel.mjs","names":[],"sources":["../../../../../../../@warlock.js/core/src/benchmark/channels/console.channel.ts"],"sourcesContent":["import type { BenchmarkChannel, BenchmarkStats } from \"../types\";\n\nexport class ConsoleChannel implements BenchmarkChannel {\n  /**\n   * Pretty-prints a stats table per operation on onFlush().\n   *\n   * @param stats - Aggregated stats for all tracked operations.\n   *\n   * @example\n   * const channel = new ConsoleChannel();\n   * channel.onFlush({ \"db-query\": { p50: 10, count: 100, ... } });\n   */\n  public onFlush(stats: Record<string, BenchmarkStats>): void {\n    const tableData: Record<string, any> = {};\n\n    for (const [name, operationStats] of Object.entries(stats)) {\n      tableData[name] = {\n        \"p50 (ms)\": operationStats.p50,\n        \"p90 (ms)\": operationStats.p90,\n        \"p95 (ms)\": operationStats.p95,\n        \"p99 (ms)\": operationStats.p99,\n        \"Avg (ms)\": operationStats.avg,\n        \"Min (ms)\": operationStats.min,\n        \"Max (ms)\": operationStats.max,\n        \"Error Rate\": `${(operationStats.errorRate * 100).toFixed(2)}%`,\n        Errors: operationStats.errors,\n        Count: operationStats.count,\n      };\n    }\n\n    console.table(tableData);\n  }\n}\n"],"mappings":";AAEA,IAAa,iBAAb,MAAwD;;;;;;;;;;CAUtD,AAAO,QAAQ,OAA6C;EAC1D,MAAM,YAAiC,CAAC;EAExC,KAAK,MAAM,CAAC,MAAM,mBAAmB,OAAO,QAAQ,KAAK,GACvD,UAAU,QAAQ;GAChB,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,YAAY,eAAe;GAC3B,cAAc,IAAI,eAAe,YAAY,KAAK,QAAQ,CAAC,EAAE;GAC7D,QAAQ,eAAe;GACvB,OAAO,eAAe;EACxB;EAGF,QAAQ,MAAM,SAAS;CACzB;AACF"}

package/esm/benchmark/channels/noop.channel.d.mts

@@ -0,0 +1,9 @@
+import { BenchmarkChannel } from "../types.mjs";
+
+//#region ../../@warlock.js/core/src/benchmark/channels/noop.channel.d.ts
+declare class NoopChannel implements BenchmarkChannel {
+  onFlush(): void;
+}
+//#endregion
+export { NoopChannel };
+//# sourceMappingURL=noop.channel.d.mts.map

package/esm/benchmark/channels/noop.channel.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.channel.d.mts","names":[],"sources":["../../../../../../../@warlock.js/core/src/benchmark/channels/noop.channel.ts"],"mappings":";;;cAEa,WAAA,YAAuB,gBAAgB;EAC3C,OAAO,CAAA;AAAA"}

package/esm/benchmark/channels/noop.channel.mjs

@@ -0,0 +1,8 @@
+//#region ../../@warlock.js/core/src/benchmark/channels/noop.channel.ts
+var NoopChannel = class {
+	onFlush() {}
+};
+
+//#endregion
+export { NoopChannel };
+//# sourceMappingURL=noop.channel.mjs.map

package/esm/benchmark/channels/noop.channel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.channel.mjs","names":[],"sources":["../../../../../../../@warlock.js/core/src/benchmark/channels/noop.channel.ts"],"sourcesContent":["import type { BenchmarkChannel } from \"../types\";\n\nexport class NoopChannel implements BenchmarkChannel {\n  public onFlush(): void {}\n}\n"],"mappings":";AAEA,IAAa,cAAb,MAAqD;CACnD,AAAO,UAAgB,CAAC;AAC1B"}

package/esm/benchmark/index.mjs

@@ -0,0 +1,7 @@
+import { measure } from "./benchmark.mjs";
+import { BenchmarkSnapshots } from "./benchmark-snapshots.mjs";
+import { ConsoleChannel } from "./channels/console.channel.mjs";
+import { NoopChannel } from "./channels/noop.channel.mjs";
+import { BenchmarkProfiler } from "./profiler.mjs";
+
+export {  };

package/esm/benchmark/profiler.d.mts

@@ -0,0 +1,67 @@
+import { BenchmarkErrorResult, BenchmarkProfilerOptions, BenchmarkStats, BenchmarkSuccessResult } from "./types.mjs";
+
+//#region ../../@warlock.js/core/src/benchmark/profiler.d.ts
+declare class BenchmarkProfiler {
+  private readonly maxSamples;
+  private readonly channels;
+  private readonly entries;
+  private interval?;
+  constructor(options?: BenchmarkProfilerOptions);
+  /**
+   * Record one measurement result. Called automatically by measure() when a profiler is set.
+   *
+   * @param result - The success or error result from measure()
+   *
+   * @example
+   * profiler.record(result);
+   */
+  record(result: BenchmarkSuccessResult<unknown> | BenchmarkErrorResult): void;
+  /**
+   * Get aggregated stats for one operation name.
+   * Computes p50/p95/p99 by sorting the ring buffer on demand.
+   *
+   * @param name - The operation name to get stats for.
+   * @returns Stats object or undefined if no data yet.
+   *
+   * @example
+   * const stats = profiler.stats("db-query");
+   */
+  stats(name: string): BenchmarkStats | undefined;
+  /**
+   * Get stats for all tracked operations.
+   *
+   * @returns A record mapping operation names to their stats.
+   *
+   * @example
+   * const all = profiler.allStats();
+   */
+  allStats(): Record<string, BenchmarkStats>;
+  /**
+   * Send allStats() to all registered channels.
+   *
+   * @example
+   * await profiler.flush();
+   */
+  flush(): Promise<void>;
+  /**
+   * Clear ring buffer for one or all operations.
+   * Does NOT reset unbounded total/error counters.
+   *
+   * @param name - Optional operation name. If omitted, clears all ring buffers.
+   *
+   * @example
+   * profiler.reset("db-query");
+   * profiler.reset();
+   */
+  reset(name?: string): void;
+  /**
+   * Dispose the profiler, clearing its auto-flush interval.
+   *
+   * @example
+   * profiler.dispose();
+   */
+  dispose(): void;
+}
+//#endregion
+export { BenchmarkProfiler };
+//# sourceMappingURL=profiler.d.mts.map

package/esm/benchmark/profiler.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiler.d.mts","names":[],"sources":["../../../../../../@warlock.js/core/src/benchmark/profiler.ts"],"mappings":";;;cAkBa,iBAAA;EAAA,iBACM,UAAA;EAAA,iBACA,QAAA;EAAA,iBACA,OAAA;EAAA,QACT,QAAA;cAEW,OAAA,GAAU,wBAAA;EAoBP;;;;;;;;EAAf,MAAA,CAAO,MAAA,EAAQ,sBAAA,YAAkC,oBAAA;EAxBvC;;;;;;;;;;EAqEV,KAAA,CAAM,IAAA,WAAe,cAAA;EAAf;;;;;;;;EAoCN,QAAA,CAAA,GAAY,MAAA,SAAe,cAAA;EAyD3B;;AAAO;;;;EAxCD,KAAA,CAAA,GAAS,OAAA;;;;;;;;;;;EAmBf,KAAA,CAAM,IAAA;;;;;;;EAqBN,OAAA,CAAA;AAAA"}

package/esm/benchmark/profiler.mjs

@@ -0,0 +1,142 @@
+import { NoopChannel } from "./channels/noop.channel.mjs";
+
+//#region ../../@warlock.js/core/src/benchmark/profiler.ts
+var BenchmarkProfiler = class {
+	constructor(options) {
+		this.entries = /* @__PURE__ */ new Map();
+		this.maxSamples = options?.maxSamples ?? 1e3;
+		this.channels = options?.channels ?? [new NoopChannel()];
+		if (options?.flushEvery) this.interval = setInterval(() => {
+			this.flush();
+		}, options.flushEvery);
+	}
+	/**
+	* Record one measurement result. Called automatically by measure() when a profiler is set.
+	*
+	* @param result - The success or error result from measure()
+	*
+	* @example
+	* profiler.record(result);
+	*/
+	record(result) {
+		let entry = this.entries.get(result.name);
+		if (!entry) {
+			entry = {
+				latencies: [],
+				sum: 0,
+				total: 0,
+				errors: 0,
+				firstSeenAt: result.startedAt,
+				lastSeenAt: result.endedAt
+			};
+			this.entries.set(result.name, entry);
+		}
+		entry.latencies.push(result.latency);
+		entry.sum += result.latency;
+		if (entry.latencies.length > this.maxSamples) {
+			const removed = entry.latencies.shift();
+			if (removed !== void 0) entry.sum -= removed;
+		}
+		entry.total += 1;
+		if (!result.success) entry.errors += 1;
+		entry.lastSeenAt = result.endedAt;
+	}
+	/**
+	* Get aggregated stats for one operation name.
+	* Computes p50/p95/p99 by sorting the ring buffer on demand.
+	*
+	* @param name - The operation name to get stats for.
+	* @returns Stats object or undefined if no data yet.
+	*
+	* @example
+	* const stats = profiler.stats("db-query");
+	*/
+	stats(name) {
+		const entry = this.entries.get(name);
+		if (!entry || entry.latencies.length === 0) return void 0;
+		const latencies = [...entry.latencies].sort((a, b) => a - b);
+		const count = latencies.length;
+		const getP = (percentile) => {
+			return latencies[Math.min(count - 1, Math.floor(count * percentile))];
+		};
+		return {
+			p50: getP(.5),
+			p90: getP(.9),
+			p95: getP(.95),
+			p99: getP(.99),
+			avg: Math.round(entry.sum / count * 100) / 100,
+			min: latencies[0],
+			max: latencies[count - 1],
+			count: entry.total,
+			errors: entry.errors,
+			errorRate: Math.round(entry.errors / entry.total * 100) / 100,
+			firstSeenAt: entry.firstSeenAt,
+			lastSeenAt: entry.lastSeenAt
+		};
+	}
+	/**
+	* Get stats for all tracked operations.
+	*
+	* @returns A record mapping operation names to their stats.
+	*
+	* @example
+	* const all = profiler.allStats();
+	*/
+	allStats() {
+		const all = {};
+		for (const name of this.entries.keys()) {
+			const operationStats = this.stats(name);
+			if (operationStats) all[name] = operationStats;
+		}
+		return all;
+	}
+	/**
+	* Send allStats() to all registered channels.
+	*
+	* @example
+	* await profiler.flush();
+	*/
+	async flush() {
+		const stats = this.allStats();
+		if (Object.keys(stats).length === 0) return;
+		for (const channel of this.channels) await channel.onFlush(stats);
+	}
+	/**
+	* Clear ring buffer for one or all operations.
+	* Does NOT reset unbounded total/error counters.
+	*
+	* @param name - Optional operation name. If omitted, clears all ring buffers.
+	*
+	* @example
+	* profiler.reset("db-query");
+	* profiler.reset();
+	*/
+	reset(name) {
+		if (name) {
+			const entry = this.entries.get(name);
+			if (entry) {
+				entry.latencies = [];
+				entry.sum = 0;
+			}
+		} else for (const entry of this.entries.values()) {
+			entry.latencies = [];
+			entry.sum = 0;
+		}
+	}
+	/**
+	* Dispose the profiler, clearing its auto-flush interval.
+	*
+	* @example
+	* profiler.dispose();
+	*/
+	dispose() {
+		if (this.interval) {
+			clearInterval(this.interval);
+			this.interval = void 0;
+		}
+	}
+};
+
+//#endregion
+export { BenchmarkProfiler };
+//# sourceMappingURL=profiler.mjs.map

package/esm/benchmark/profiler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiler.mjs","names":[],"sources":["../../../../../../@warlock.js/core/src/benchmark/profiler.ts"],"sourcesContent":["import { NoopChannel } from \"./channels/noop.channel\";\nimport type {\n  BenchmarkChannel,\n  BenchmarkErrorResult,\n  BenchmarkProfilerOptions,\n  BenchmarkStats,\n  BenchmarkSuccessResult,\n} from \"./types\";\n\ntype BenchmarkEntry = {\n  latencies: number[];\n  sum: number;\n  total: number;\n  errors: number;\n  firstSeenAt: Date;\n  lastSeenAt: Date;\n};\n\nexport class BenchmarkProfiler {\n  private readonly maxSamples: number;\n  private readonly channels: BenchmarkChannel[];\n  private readonly entries = new Map<string, BenchmarkEntry>();\n  private interval?: ReturnType<typeof setInterval>;\n\n  public constructor(options?: BenchmarkProfilerOptions) {\n    this.maxSamples = options?.maxSamples ?? 1000;\n    this.channels = options?.channels ?? [new NoopChannel()];\n\n    if (options?.flushEvery) {\n      this.interval = setInterval(() => {\n        // We use void to explicitly ignore the promise, as this is a background interval\n        void this.flush();\n      }, options.flushEvery);\n    }\n  }\n\n  /**\n   * Record one measurement result. Called automatically by measure() when a profiler is set.\n   *\n   * @param result - The success or error result from measure()\n   *\n   * @example\n   * profiler.record(result);\n   */\n  public record(result: BenchmarkSuccessResult<unknown> | BenchmarkErrorResult): void {\n    let entry = this.entries.get(result.name);\n\n    if (!entry) {\n      entry = {\n        latencies: [],\n        sum: 0,\n        total: 0,\n        errors: 0,\n        firstSeenAt: result.startedAt,\n        lastSeenAt: result.endedAt,\n      };\n\n      this.entries.set(result.name, entry);\n    }\n\n    entry.latencies.push(result.latency);\n    entry.sum += result.latency;\n\n    if (entry.latencies.length > this.maxSamples) {\n      const removed = entry.latencies.shift();\n      if (removed !== undefined) {\n        entry.sum -= removed;\n      }\n    }\n\n    entry.total += 1;\n\n    if (!result.success) {\n      entry.errors += 1;\n    }\n\n    entry.lastSeenAt = result.endedAt;\n  }\n\n  /**\n   * Get aggregated stats for one operation name.\n   * Computes p50/p95/p99 by sorting the ring buffer on demand.\n   *\n   * @param name - The operation name to get stats for.\n   * @returns Stats object or undefined if no data yet.\n   *\n   * @example\n   * const stats = profiler.stats(\"db-query\");\n   */\n  public stats(name: string): BenchmarkStats | undefined {\n    const entry = this.entries.get(name);\n    if (!entry || entry.latencies.length === 0) return undefined;\n\n    const latencies = [...entry.latencies].sort((a, b) => a - b);\n    const count = latencies.length;\n\n    const getP = (percentile: number) => {\n      const index = Math.min(count - 1, Math.floor(count * percentile));\n      return latencies[index];\n    };\n\n    return {\n      p50: getP(0.5),\n      p90: getP(0.9),\n      p95: getP(0.95),\n      p99: getP(0.99),\n      avg: Math.round((entry.sum / count) * 100) / 100,\n      min: latencies[0],\n      max: latencies[count - 1],\n      count: entry.total,\n      errors: entry.errors,\n      errorRate: Math.round((entry.errors / entry.total) * 100) / 100,\n      firstSeenAt: entry.firstSeenAt,\n      lastSeenAt: entry.lastSeenAt,\n    };\n  }\n\n  /**\n   * Get stats for all tracked operations.\n   *\n   * @returns A record mapping operation names to their stats.\n   *\n   * @example\n   * const all = profiler.allStats();\n   */\n  public allStats(): Record<string, BenchmarkStats> {\n    const all: Record<string, BenchmarkStats> = {};\n    for (const name of this.entries.keys()) {\n      const operationStats = this.stats(name);\n      if (operationStats) {\n        all[name] = operationStats;\n      }\n    }\n    return all;\n  }\n\n  /**\n   * Send allStats() to all registered channels.\n   *\n   * @example\n   * await profiler.flush();\n   */\n  public async flush(): Promise<void> {\n    const stats = this.allStats();\n    if (Object.keys(stats).length === 0) return;\n\n    for (const channel of this.channels) {\n      await channel.onFlush(stats);\n    }\n  }\n\n  /**\n   * Clear ring buffer for one or all operations.\n   * Does NOT reset unbounded total/error counters.\n   *\n   * @param name - Optional operation name. If omitted, clears all ring buffers.\n   *\n   * @example\n   * profiler.reset(\"db-query\");\n   * profiler.reset();\n   */\n  public reset(name?: string): void {\n    if (name) {\n      const entry = this.entries.get(name);\n      if (entry) {\n        entry.latencies = [];\n        entry.sum = 0;\n      }\n    } else {\n      for (const entry of this.entries.values()) {\n        entry.latencies = [];\n        entry.sum = 0;\n      }\n    }\n  }\n\n  /**\n   * Dispose the profiler, clearing its auto-flush interval.\n   *\n   * @example\n   * profiler.dispose();\n   */\n  public dispose(): void {\n    if (this.interval) {\n      clearInterval(this.interval);\n      this.interval = undefined;\n    }\n  }\n}\n"],"mappings":";;;AAkBA,IAAa,oBAAb,MAA+B;CAM7B,AAAO,YAAY,SAAoC;iCAH5B,IAAI,IAA4B;EAIzD,KAAK,aAAa,SAAS,cAAc;EACzC,KAAK,WAAW,SAAS,YAAY,CAAC,IAAI,YAAY,CAAC;EAEvD,IAAI,SAAS,YACX,KAAK,WAAW,kBAAkB;GAEhC,AAAK,KAAK,MAAM;EAClB,GAAG,QAAQ,UAAU;CAEzB;;;;;;;;;CAUA,AAAO,OAAO,QAAsE;EAClF,IAAI,QAAQ,KAAK,QAAQ,IAAI,OAAO,IAAI;EAExC,IAAI,CAAC,OAAO;GACV,QAAQ;IACN,WAAW,CAAC;IACZ,KAAK;IACL,OAAO;IACP,QAAQ;IACR,aAAa,OAAO;IACpB,YAAY,OAAO;GACrB;GAEA,KAAK,QAAQ,IAAI,OAAO,MAAM,KAAK;EACrC;EAEA,MAAM,UAAU,KAAK,OAAO,OAAO;EACnC,MAAM,OAAO,OAAO;EAEpB,IAAI,MAAM,UAAU,SAAS,KAAK,YAAY;GAC5C,MAAM,UAAU,MAAM,UAAU,MAAM;GACtC,IAAI,YAAY,QACd,MAAM,OAAO;EAEjB;EAEA,MAAM,SAAS;EAEf,IAAI,CAAC,OAAO,SACV,MAAM,UAAU;EAGlB,MAAM,aAAa,OAAO;CAC5B;;;;;;;;;;;CAYA,AAAO,MAAM,MAA0C;EACrD,MAAM,QAAQ,KAAK,QAAQ,IAAI,IAAI;EACnC,IAAI,CAAC,SAAS,MAAM,UAAU,WAAW,GAAG,OAAO;EAEnD,MAAM,YAAY,CAAC,GAAG,MAAM,SAAS,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;EAC3D,MAAM,QAAQ,UAAU;EAExB,MAAM,QAAQ,eAAuB;GAEnC,OAAO,UADO,KAAK,IAAI,QAAQ,GAAG,KAAK,MAAM,QAAQ,UAAU,CAC1C;EACvB;EAEA,OAAO;GACL,KAAK,KAAK,EAAG;GACb,KAAK,KAAK,EAAG;GACb,KAAK,KAAK,GAAI;GACd,KAAK,KAAK,GAAI;GACd,KAAK,KAAK,MAAO,MAAM,MAAM,QAAS,GAAG,IAAI;GAC7C,KAAK,UAAU;GACf,KAAK,UAAU,QAAQ;GACvB,OAAO,MAAM;GACb,QAAQ,MAAM;GACd,WAAW,KAAK,MAAO,MAAM,SAAS,MAAM,QAAS,GAAG,IAAI;GAC5D,aAAa,MAAM;GACnB,YAAY,MAAM;EACpB;CACF;;;;;;;;;CAUA,AAAO,WAA2C;EAChD,MAAM,MAAsC,CAAC;EAC7C,KAAK,MAAM,QAAQ,KAAK,QAAQ,KAAK,GAAG;GACtC,MAAM,iBAAiB,KAAK,MAAM,IAAI;GACtC,IAAI,gBACF,IAAI,QAAQ;EAEhB;EACA,OAAO;CACT;;;;;;;CAQA,MAAa,QAAuB;EAClC,MAAM,QAAQ,KAAK,SAAS;EAC5B,IAAI,OAAO,KAAK,KAAK,EAAE,WAAW,GAAG;EAErC,KAAK,MAAM,WAAW,KAAK,UACzB,MAAM,QAAQ,QAAQ,KAAK;CAE/B;;;;;;;;;;;CAYA,AAAO,MAAM,MAAqB;EAChC,IAAI,MAAM;GACR,MAAM,QAAQ,KAAK,QAAQ,IAAI,IAAI;GACnC,IAAI,OAAO;IACT,MAAM,YAAY,CAAC;IACnB,MAAM,MAAM;GACd;EACF,OACE,KAAK,MAAM,SAAS,KAAK,QAAQ,OAAO,GAAG;GACzC,MAAM,YAAY,CAAC;GACnB,MAAM,MAAM;EACd;CAEJ;;;;;;;CAQA,AAAO,UAAgB;EACrB,IAAI,KAAK,UAAU;GACjB,cAAc,KAAK,QAAQ;GAC3B,KAAK,WAAW;EAClB;CACF;AACF"}

package/esm/benchmark/types.d.mts

@@ -0,0 +1,164 @@
+import { BenchmarkSnapshots } from "./benchmark-snapshots.mjs";
+import { BenchmarkProfiler } from "./profiler.mjs";
+
+//#region ../../@warlock.js/core/src/benchmark/types.d.ts
+/**
+ * Global benchmark configuration (set via config.get("benchmark"))
+ */
+type BenchmarkConfigurations = {
+  enabled?: boolean;
+  latencyRange?: {
+    excellent: number;
+    poor: number;
+  };
+  profiler?: BenchmarkProfiler;
+  snapshotContainer?: BenchmarkSnapshots;
+};
+type BenchmarkOptions<T = unknown> = {
+  /**
+   * Quick enable/disable without removing the call.
+   * When false, fn() is still called but no timing occurs and no hooks fire.
+   */
+  enabled?: boolean;
+  /**
+   * Latency thresholds (in ms) for performance classification.
+   * - latency <= excellent → "excellent"
+   * - latency >= poor      → "poor"
+   * - between              → "good"
+   *
+   * @example
+   * { excellent: 100, poor: 500 } // ≤100ms excellent, ≥500ms poor
+   */
+  latencyRange?: {
+    /**
+     * Upper bound (ms) for "excellent" classification
+     */
+    excellent: number;
+    /**
+     * Lower bound (ms) for "poor" classification
+     */
+    poor: number;
+  };
+  /**
+   * Hook called after a successful measurement
+   */
+  onComplete?: (result: BenchmarkSuccessResult<T>) => void;
+  /**
+   * Hook called after a benchmarked error
+   */
+  onError?: (result: BenchmarkErrorResult) => void;
+  /**
+   * Hook called after every measurement, success or error.
+   * Fires after onComplete / onError.
+   */
+  onFinish?: (result: BenchmarkSuccessResult<T> | BenchmarkErrorResult) => void;
+  /**
+   * Metadata tags for grouping/filtering benchmarks
+   *
+   * @example { service: "auth", endpoint: "/login" }
+   */
+  tags?: Record<string, string>;
+  /**
+   * Control whether a thrown error should be benchmarked.
+   * Return false for business logic errors (400, 404, validation) — they are re-thrown immediately.
+   * Return true for technical errors (timeouts, DB crashes) — they are captured and benchmarked.
+   *
+   * Default: benchmark all errors
+   */
+  shouldBenchmarkError?: (error: unknown) => boolean;
+  /**
+   * Profiler to record this measurement into.
+   * - BenchmarkProfiler instance → use it
+   * - false                      → skip profiling for this call
+   * - undefined (default)        → fall back to config.get("benchmark").profiler
+   */
+  profiler?: BenchmarkProfiler | false;
+  /**
+   * Snapshot container to record this result into.
+   * - BenchmarkSnapshots instance → use it
+   * - false                       → skip snapshot for this call
+   * - undefined (default)         → fall back to config.get("benchmark").snapshotContainer
+   */
+  snapshotContainer?: BenchmarkSnapshots | false;
+};
+type BenchmarkResult = {
+  /**
+   * Name of the benchmark
+   */
+  name: string;
+  /**
+   * Latency in milliseconds
+   */
+  latency: number;
+  /**
+   * Performance classification based on latency thresholds
+   */
+  state: "excellent" | "good" | "poor";
+  /**
+   * Optional metadata tags
+   */
+  tags?: Record<string, string>;
+  /**
+   * Start time of the measurement
+   */
+  startedAt: Date;
+  /**
+   * End time of the measurement
+   */
+  endedAt: Date;
+};
+/**
+ * Result of a successful benchmark measurement.
+ */
+type BenchmarkSuccessResult<T> = BenchmarkResult & {
+  success: true;
+  value: T;
+};
+/**
+ * Result of a benchmarked error.
+ */
+type BenchmarkErrorResult = BenchmarkResult & {
+  success: false;
+  error: unknown;
+};
+interface BenchmarkChannel {
+  /**
+   * Called on profiler.flush() with aggregated stats for all tracked operations.
+   */
+  onFlush(stats: Record<string, BenchmarkStats>): void | Promise<void>;
+}
+type BenchmarkStats = {
+  p50: number;
+  p90: number;
+  p95: number;
+  p99: number;
+  avg: number;
+  min: number;
+  max: number; /** Total call count — unbounded, not capped by ring buffer */
+  count: number; /** Total error count — unbounded */
+  errors: number; /** 0.0–1.0 — based on unbounded total/error counters */
+  errorRate: number;
+  firstSeenAt: Date;
+  lastSeenAt: Date;
+};
+type BenchmarkProfilerOptions = {
+  /** Max latency samples to keep per operation name. Default: 1000 */maxSamples?: number; /** Channels to broadcast stats to on flush(). Default: [new NoopChannel()] */
+  channels?: BenchmarkChannel[]; /** Auto-flush interval in ms. If not set, flush() must be called manually. */
+  flushEvery?: number;
+};
+type BenchmarkSnapshotsOptions = {
+  /** Max snapshots to keep per operation name. Default: 100 */maxSnapshots?: number;
+  /**
+   * What to capture:
+   * - "error" → only BenchmarkErrorResult (default, memory safe)
+   * - "value" → only BenchmarkSuccessResult<T> with value
+   * - "all"   → both
+   *
+   * WARNING: "value" and "all" store the full T value in memory.
+   * Do not use in production without understanding the memory implications.
+   */
+  capture?: "error" | "value" | "all";
+};
+//#endregion
+export { BenchmarkChannel, BenchmarkConfigurations, BenchmarkErrorResult, BenchmarkOptions, BenchmarkProfilerOptions, BenchmarkResult, BenchmarkSnapshotsOptions, BenchmarkStats, BenchmarkSuccessResult };
+//# sourceMappingURL=types.d.mts.map

package/esm/benchmark/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../@warlock.js/core/src/benchmark/types.ts"],"mappings":";;;;;;AAMA;KAAY,uBAAA;EACV,OAAA;EACA,YAAA;IAAiB,SAAA;IAAmB,IAAA;EAAA;EACpC,QAAA,GAAW,iBAAA;EACX,iBAAA,GAAoB,kBAAkB;AAAA;AAAA,KAG5B,gBAAA;EAHU;;AAAkB;AAGxC;EAKE,OAAA;EAL0B;;;;;;;;;EAe1B,YAAA;IAkDsC;;;IA9CpC,SAAA;IAJF;;;IAQE,IAAA;EAAA;EAK2C;;;EAA7C,UAAA,IAAc,MAAA,EAAQ,sBAAA,CAAuB,CAAA;EAIlC;;;EAAX,OAAA,IAAW,MAAA,EAAQ,oBAAA;EAK6B;;;;EAAhD,QAAA,IAAY,MAAA,EAAQ,sBAAA,CAAuB,CAAA,IAAK,oBAAA;EAcxB;;;;;EARxB,IAAA,GAAO,MAAA;EAsB+B;AAGxC;;;;;;EAjBE,oBAAA,IAAwB,KAAA;EAyCX;;;;;;EAlCb,QAAA,GAAW,iBAAA;EA8BA;;;;AAIE;AAMf;EAjCE,iBAAA,GAAoB,kBAAA;AAAA;AAAA,KAGV,eAAA;EA8BuB;;;EA1BjC,IAAA;EA4BO;;AAAC;EAxBR,OAAA;EA8B8B;;;EA1B9B,KAAA;EA2BA;;;EAvBA,IAAA,GAAO,MAAA;EA2BQ;;;EAvBf,SAAA,EAAW,IAAA;EA2BI;;;EAvBf,OAAA,EAAS,IAAA;AAAA;;;;KAMC,sBAAA,MAA4B,eAAA;EACtC,OAAA;EACA,KAAA,EAAO,CAAC;AAAA;;;;KAME,oBAAA,GAAuB,eAAe;EAChD,OAAA;EACA,KAAA;AAAA;AAAA,UAGe,gBAAA;EAaf;;;EATA,OAAA,CAAQ,KAAA,EAAO,MAAA,SAAe,cAAA,WAAyB,OAAA;AAAA;AAAA,KAG7C,cAAA;EACV,GAAA;EACA,GAAA;EACA,GAAA;EACA,GAAA;EACA,GAAA;EACA,GAAA;EACA,GAAA;EAEA,KAAA,UAWA;EATA,MAAA,UAWW;EATX,SAAA;EACA,WAAA,EAAa,IAAA;EACb,UAAA,EAAY,IAAI;AAAA;AAAA,KAGN,wBAAA;sEAEV,UAAA,WAmBO;EAjBP,QAAA,GAAW,gBAAgB;EAE3B,UAAA;AAAA;AAAA,KAGU,yBAAA;+DAEV,YAAA;;;;;;;;;;EAUA,OAAO;AAAA"}

package/esm/bootstrap/setup.d.mts

@@ -0,0 +1,5 @@
+//#region ../../@warlock.js/core/src/bootstrap/setup.d.ts
+declare function displayEnvironmentMode(): void;
+//#endregion
+export { displayEnvironmentMode };
+//# sourceMappingURL=setup.d.mts.map

package/esm/bootstrap/setup.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.mts","names":[],"sources":["../../../../../../@warlock.js/core/src/bootstrap/setup.ts"],"mappings":";iBAGgB,sBAAA,CAAA"}

package/esm/bootstrap/setup.mjs

@@ -0,0 +1,20 @@
+import { environment } from "../utils/environment.mjs";
+import "../utils/index.mjs";
+import { colors } from "@mongez/copper";
+
+//#region ../../@warlock.js/core/src/bootstrap/setup.ts
+function displayEnvironmentMode() {
+	const env = environment();
+	const envColor = (env) => {
+		switch (env) {
+			case "development": return colors.yellow(env);
+			case "production": return colors.green(env);
+			case "test": return colors.magentaBright(env);
+		}
+	};
+	console.log(colors.blueBright("ℹ"), colors.yellow(`(${(/* @__PURE__ */ new Date()).toISOString()})`), colors.orange("[warlock]"), colors.magenta(`bootstrap`), colors.blueBright(`Starting application in ${envColor(env)} mode`));
+}
+
+//#endregion
+export { displayEnvironmentMode };
+//# sourceMappingURL=setup.mjs.map

package/esm/bootstrap/setup.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.mjs","names":[],"sources":["../../../../../../@warlock.js/core/src/bootstrap/setup.ts"],"sourcesContent":["import { colors } from \"@mongez/copper\";\nimport { environment } from \"../utils\";\n\nexport function displayEnvironmentMode() {\n  const env = environment();\n\n  const envColor = (env: string) => {\n    switch (env) {\n      case \"development\":\n        return colors.yellow(env);\n      case \"production\":\n        return colors.green(env);\n      case \"test\":\n        return colors.magentaBright(env);\n    }\n  };\n\n  console.log(\n    colors.blueBright(\"ℹ\"),\n    colors.yellow(`(${new Date().toISOString()})`),\n    colors.orange(\"[warlock]\"),\n    colors.magenta(`bootstrap`),\n    colors.blueBright(`Starting application in ${envColor(env)} mode`),\n  );\n}\n"],"mappings":";;;;;AAGA,SAAgB,yBAAyB;CACvC,MAAM,MAAM,YAAY;CAExB,MAAM,YAAY,QAAgB;EAChC,QAAQ,KAAR;GACE,KAAK,eACH,OAAO,OAAO,OAAO,GAAG;GAC1B,KAAK,cACH,OAAO,OAAO,MAAM,GAAG;GACzB,KAAK,QACH,OAAO,OAAO,cAAc,GAAG;EACnC;CACF;CAEA,QAAQ,IACN,OAAO,WAAW,GAAG,GACrB,OAAO,OAAO,qBAAI,IAAI,KAAK,GAAE,YAAY,EAAE,EAAE,GAC7C,OAAO,OAAO,WAAW,GACzB,OAAO,QAAQ,WAAW,GAC1B,OAAO,WAAW,2BAA2B,SAAS,GAAG,EAAE,MAAM,CACnE;AACF"}

package/esm/bootstrap.d.mts

@@ -0,0 +1,5 @@
+//#region ../../@warlock.js/core/src/bootstrap.d.ts
+declare function bootstrap(): Promise<void>;
+//#endregion
+export { bootstrap };
+//# sourceMappingURL=bootstrap.d.mts.map

package/esm/bootstrap.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.mts","names":[],"sources":["../../../../../@warlock.js/core/src/bootstrap.ts"],"mappings":";iBAIsB,SAAA,CAAA,GAAS,OAAA"}

package/esm/bootstrap.mjs

@@ -0,0 +1,14 @@
+import { loadEnv } from "@mongez/dotenv";
+import { captureAnyUnhandledRejection } from "@warlock.js/logger";
+import { initializeDayjs } from "@mongez/time-wizard";
+
+//#region ../../@warlock.js/core/src/bootstrap.ts
+async function bootstrap() {
+	await loadEnv();
+	initializeDayjs();
+	captureAnyUnhandledRejection();
+}
+
+//#endregion
+export { bootstrap };
+//# sourceMappingURL=bootstrap.mjs.map

package/esm/bootstrap.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.mjs","names":[],"sources":["../../../../../@warlock.js/core/src/bootstrap.ts"],"sourcesContent":["import { loadEnv } from \"@mongez/dotenv\";\nimport { initializeDayjs } from \"@mongez/time-wizard\";\nimport { captureAnyUnhandledRejection } from \"@warlock.js/logger\";\n\nexport async function bootstrap() {\n  await loadEnv();\n\n  initializeDayjs();\n  captureAnyUnhandledRejection();\n}\n"],"mappings":";;;;;AAIA,eAAsB,YAAY;CAChC,MAAM,QAAQ;CAEd,gBAAgB;CAChB,6BAA6B;AAC/B"}

package/esm/cache/database-cache-driver.d.mts

@@ -0,0 +1,60 @@
+import { Model } from "@warlock.js/cascade";
+import { BaseCacheDriver, CacheDriver, CacheKey } from "@warlock.js/cache";
+
+//#region ../../@warlock.js/core/src/cache/database-cache-driver.d.ts
+type DatabaseCacheOptions = {
+  /**
+   * Database model class
+   */
+  model?: typeof CacheModel;
+  /**
+   * Global prefix for the cache key
+   */
+  globalPrefix?: string | (() => string);
+  /**
+   * The default TTL for the cache in seconds
+   *
+   * @default Infinity
+   */
+  ttl?: number;
+};
+declare class CacheModel extends Model {
+  static table: string;
+}
+declare class DatabaseCacheDriver extends BaseCacheDriver<DatabaseCacheDriver, DatabaseCacheOptions> implements CacheDriver<DatabaseCacheDriver, DatabaseCacheOptions> {
+  /**
+   * {@inheritdoc}
+   */
+  name: string;
+  /**
+   * Database model class
+   */
+  model: typeof CacheModel;
+  /**
+   * {@inheritdoc}
+   */
+  setOptions(options: DatabaseCacheOptions): this;
+  /**
+   * {@inheritdoc}
+   */
+  removeNamespace(namespace: string): Promise<this>;
+  /**
+   * {@inheritdoc}
+   */
+  set(key: CacheKey, value: any, ttl?: number): Promise<this>;
+  /**
+   * {@inheritdoc}
+   */
+  get(key: CacheKey): Promise<any>;
+  /**
+   * {@inheritdoc}
+   */
+  remove(key: CacheKey): Promise<void>;
+  /**
+   * {@inheritdoc}
+   */
+  flush(): Promise<void>;
+}
+//#endregion
+export { DatabaseCacheDriver, DatabaseCacheOptions };
+//# sourceMappingURL=database-cache-driver.d.mts.map

package/esm/cache/database-cache-driver.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-cache-driver.d.mts","names":[],"sources":["../../../../../../@warlock.js/core/src/cache/database-cache-driver.ts"],"mappings":";;;;KAQY,oBAAA;;AAAZ;;EAIE,KAAA,UAAe,UAAU;EAAA;;;EAIzB,YAAA;EAMA;;AAAG;AAGL;;EAHE,GAAA;AAAA;AAAA,cAGW,UAAA,SAAmB,KAAK;EAAA,OACrB,KAAK;AAAA;AAAA,cAGR,mBAAA,SACH,eAAA,CAAgB,mBAAA,EAAqB,oBAAA,aAClC,WAAA,CAAY,mBAAA,EAAqB,oBAAA;EADpB;;;EAMjB,IAAA;EAKe;;;EAAf,KAAA,SAAe,UAAA;EAiCkC;;;EA5BjD,UAAA,CAAW,OAAA,EAAS,oBAAA;EAgGM;;;EArFpB,eAAA,CAAgB,SAAA,WAAiB,OAAA;EA1BxB;;;EA2CT,GAAA,CAAI,GAAA,EAAK,QAAA,EAAU,KAAA,OAAY,GAAA,YAAY,OAAA;EA5CX;;;EAsFhC,GAAA,CAAI,GAAA,EAAK,QAAA,GAAQ,OAAA;EAhFvB;;;EA0GM,MAAA,CAAO,GAAA,EAAK,QAAA,GAAQ,OAAA;EAhGN;;;EA+Gd,KAAA,CAAA,GAAK,OAAA;AAAA"}

package/esm/cache/database-cache-driver.mjs

@@ -0,0 +1,98 @@
+import { Model } from "@warlock.js/cascade";
+import { BaseCacheDriver } from "@warlock.js/cache";
+
+//#region ../../@warlock.js/core/src/cache/database-cache-driver.ts
+var CacheModel = class extends Model {
+	static {
+		this.table = "cache";
+	}
+};
+var DatabaseCacheDriver = class extends BaseCacheDriver {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "database";
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setOptions(options) {
+		super.setOptions(options);
+		this.model = options.model ?? CacheModel;
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async removeNamespace(namespace) {
+		this.log("clearing", namespace);
+		namespace = this.parseKey(namespace);
+		await this.model.delete({ namespace });
+		this.log("cleared", namespace);
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async set(key, value, ttl) {
+		const parsedKey = this.parseKey(key);
+		this.log("caching", parsedKey);
+		if (ttl === void 0) ttl = this.ttl;
+		const namespace = parsedKey.split(".").slice(0, -1).join(".") || parsedKey;
+		let cacheEntry = await this.model.first({ key: parsedKey });
+		if (cacheEntry) {
+			cacheEntry.set("namespace", namespace);
+			cacheEntry.set("data", value);
+			cacheEntry.set("ttl", ttl);
+			cacheEntry.set("expiresAt", this.getExpiresAt(ttl) || null);
+			await cacheEntry.save();
+		} else await this.model.create({
+			key: parsedKey,
+			namespace,
+			data: value,
+			ttl,
+			expiresAt: this.getExpiresAt(ttl) || null
+		});
+		this.log("cached", parsedKey);
+		return this;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async get(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("fetching", parsedKey);
+		const model = await this.model.first({ key: parsedKey });
+		if (!model) {
+			this.log("notFound", parsedKey);
+			return null;
+		}
+		const data = {
+			data: model.get("data"),
+			expiresAt: model.get("expiresAt"),
+			ttl: model.get("ttl")
+		};
+		return this.parseCachedData(parsedKey, data);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async remove(key) {
+		const parsedKey = this.parseKey(key);
+		this.log("removing", parsedKey);
+		await this.model.delete({ key: parsedKey });
+		this.log("removed", parsedKey);
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async flush() {
+		this.log("flushing");
+		if (this.options.globalPrefix) this.removeNamespace("");
+		else await this.model.delete();
+		this.log("flushed");
+	}
+};
+
+//#endregion
+export { DatabaseCacheDriver };
+//# sourceMappingURL=database-cache-driver.mjs.map