@compforge/harness-toolbox 0.5.1 → 0.5.2

package/README.md

@@ -426,3 +426,7 @@ MySQL, OpenSearch and Redis use the same acquisition lifecycle. `connectTimeoutM
 and handshake/probe; optional `acquireTimeoutMs` bounds all routes together (default: per-route budget × route count).
 Cancellation preserves the caller reason and prevents late mappings from starting a handshake. Query and command
 timeouts remain separate, and failed operations are never replayed on another transport.
+
+DataLoader accepts an optional `logger.debug(message)` and a non-sensitive `label`.
+Diagnostics distinguish miss, wait, hit, bypass, not-retained and close using scope/read
+identifiers, never keys, values or errors. Logging does not change retention or retry policy.

package/dist/data-loader.d.ts

@@ -3,6 +3,11 @@ export interface DataLoaderOptions {
     /** Serialized result bytes retained, excluding keys/errors and active operation memory. */
     maxBytes: number;
     signal: AbortSignal;
+    /** Non-sensitive label supplied by the adapter; keys and values never enter diagnostics. */
+    label?: string;
+    logger?: {
+        debug(message: string): void;
+    };
 }
 /** A scoped async loading cache, similar to Guava's LoadingCache.
  * Shares results, failures and in-flight reads until close; consumers must not mutate results.

package/dist/data-loader.js

@@ -1,8 +1,12 @@
 // src/data-loader.ts
 import { serialize } from "node:v8";
+var nextScopeId = 0;
 
 class DataLoader {
   options;
+  #scopeId = ++nextScopeId;
+  #readIds = new WeakMap;
+  #nextReadId = 0;
   #entries = new Map;
   #pending = new Set;
   #controller = new AbortController;
@@ -20,30 +24,46 @@ class DataLoader {
   #abort = () => {
     this.close(this.options.signal.reason);
   };
+  #debug(event, readId, reason) {
+    if (!this.options.logger)
+      return;
+    try {
+      this.options.logger.debug(`[data-loader] scope=${this.#scopeId}` + (this.options.label ? ` label=${this.options.label}` : "") + (readId === undefined ? "" : ` read=${readId}`) + ` event=${event}` + (reason ? ` reason=${reason}` : ""));
+    } catch {}
+  }
   async read(key, operation, signal) {
     this.#controller.signal.throwIfAborted();
     signal?.throwIfAborted();
     let pending = key === undefined ? undefined : this.#entries.get(key);
-    if (!pending) {
+    if (pending) {
+      this.#debug(this.#pending.has(pending) ? "wait" : "hit", this.#readIds.get(pending));
+    } else {
+      const readId = ++this.#nextReadId;
       const retain = key !== undefined && this.#entries.size < this.options.maxEntries;
+      this.#debug(retain ? "miss" : "bypass", readId, retain ? undefined : key === undefined ? "no-key" : "entry-limit");
       pending = Promise.resolve().then(async () => {
         this.#controller.signal.throwIfAborted();
         const value = await operation(this.#controller.signal);
         this.#controller.signal.throwIfAborted();
         if (retain) {
           let bytes;
+          let reason = "byte-limit";
           try {
             bytes = serialize(value).byteLength;
           } catch {
             bytes = Infinity;
+            reason = "not-serializable";
           }
           if (this.#bytes + bytes <= this.options.maxBytes)
             this.#bytes += bytes;
-          else
+          else {
             this.#entries.delete(key);
+            this.#debug("not-retained", readId, reason);
+          }
         }
         return value;
       });
+      this.#readIds.set(pending, readId);
       if (retain)
         this.#entries.set(key, pending);
       this.#pending.add(pending);
@@ -74,6 +94,7 @@ class DataLoader {
   }
   close(reason = new Error("DataLoader scope is closed")) {
     if (!this.#closing) {
+      this.#debug("close");
       this.#closing = Promise.resolve().then(async () => {
         await Promise.allSettled([...this.#pending]);
         this.#entries.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -104,7 +104,7 @@
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "3.1133.0",
-    "@compforge/harness-common": "0.5.10",
+    "@compforge/harness-common": "0.5.11",
     "@kubernetes/client-node": "1.4.0",
     "@opensearch-project/opensearch": "3.6.0",
     "@redis/client": "6.1.0",