@compforge/harness-toolbox 0.3.3 → 0.3.4

package/README.md

@@ -157,6 +157,49 @@ fall back to Pod Python. Completion, truncation, timeout, and cancellation destr
 session without replay or changes to ordinary borrowed sessions. Disconnect does not prove immediate
 server cancellation. The byte budget limits retained JSON rows, not individual wire packets or fields.
 
+## Reusable bounded queries and read caches
+
+For trusted, caller-owned SELECT statements, `queryLimited(database, target, statement, maxRows)`
+appends an integer `LIMIT maxRows + 1` and returns `{ rows, truncated }`. SQL must not already have
+LIMIT or a trailing terminator; the helper does not parse or rewrite arbitrary SQL. Business values
+stay bound parameters. `limitedStatement` and `limitedRows` expose the same preparation/projection
+for `Database.queryBatch`. `maxRows` must be a positive integer below 2147483647. These helpers
+bound row count only: use `queryReadonly` when a disposable readonly session and byte/time budgets
+are required.
+
+`DataLoader` shares results, failures and in-flight work within one explicit read scope, similar to
+Guava's LoadingCache but scoped to a single collection round. Consumers must not mutate shared results.
+Use `withReadScope` to bind caller-approved database reads; do not use it for writes or polling.
+
+```ts
+import { DataLoader } from '@compforge/harness-toolbox/data-loader';
+import { withReadScope, queryLimited } from '@compforge/harness-toolbox/mysql';
+
+const scope = new DataLoader({
+  maxEntries: 256, maxBytes: 4 * 1024 * 1024, signal: client.signal,
+});
+const reads = withReadScope(client.database, scope);
+try {
+  const page = await queryLimited(reads, client.target, {
+    sql: 'SELECT id FROM items WHERE owner = ? ORDER BY id', values: [owner],
+  }, 100);
+} finally {
+  await scope.close(); // Root still owns client.dispose().
+}
+```
+
+Keys include full database identity, SQL and typed parameters as an opaque digest. Nonserializable
+parameters bypass caching. Batch reads reuse cached entries and send misses as one ordered native
+batch, or sequential queries when batching is unavailable. Failures are shared without replay;
+use a new scope for fresh observations. This is not a consistent database snapshot.
+
+Entry capacity includes failures and pending reads; new keys bypass caching when full. Serialized
+result bytes bound retained results, excluding keys/errors and active operation memory. Oversized
+or nonserializable results are returned but not retained. Scope close signals cancellation and joins
+operations, including uncached reads. Operations must honor the signal for prompt cancellation;
+MySQL reads retain their underlying client's timeout/cancellation policy. Adapter close owns neither
+the scope nor the database. A waiter's optional signal to `scope.read` cancels only that waiter.
+
 ## Shared Pod relay transport
 
 `PodRelayTransport` opens TCP routes through an existing Running/Ready Pod. It discovers an

package/dist/chunk-1gyshqd9.js

@@ -0,0 +1,20 @@
+// src/mysql/limited.ts
+function validateLimit(maxRows) {
+  if (!Number.isSafeInteger(maxRows) || maxRows < 1 || maxRows >= 2147483647) {
+    throw new Error("maxRows must be a positive integer < 2147483647");
+  }
+}
+function limitedStatement(statement, maxRows) {
+  validateLimit(maxRows);
+  return { sql: `${statement.sql} LIMIT ${maxRows + 1}`, values: statement.values };
+}
+function limitedRows(rows, maxRows) {
+  validateLimit(maxRows);
+  return { rows: rows.slice(0, maxRows), truncated: rows.length > maxRows };
+}
+async function queryLimited(database, target, statement, maxRows) {
+  const bounded = limitedStatement(statement, maxRows);
+  return limitedRows(await database.query(target, bounded.sql, bounded.values), maxRows);
+}
+
+export { limitedStatement, limitedRows, queryLimited };

package/dist/chunk-4sqvppz7.js

@@ -0,0 +1,51 @@
+// src/mysql/scoped.ts
+import { createHash } from "node:crypto";
+import { serialize } from "node:v8";
+function queryKey(kind, target, statement) {
+  try {
+    return createHash("sha256").update(serialize([
+      kind,
+      target.host,
+      target.port,
+      target.database,
+      target.user,
+      target.password,
+      statement.sql,
+      statement.values
+    ])).digest("hex");
+  } catch {
+    return;
+  }
+}
+function withReadScope(database, scope) {
+  const query = (target, sql, values) => scope.read(queryKey("query", target, { sql, values }), () => database.query(target, sql, values));
+  return {
+    query,
+    queryOne: (target, sql, values) => scope.read(queryKey("one", target, { sql, values }), () => database.queryOne(target, sql, values)),
+    queryBatch: async (target, statements) => {
+      const misses = [];
+      let batch;
+      if (!statements.length)
+        return scope.read(undefined, async () => []);
+      return Promise.all(statements.map((statement) => scope.read(queryKey("query", target, statement), (signal) => {
+        const position = misses.length;
+        misses.push(statement);
+        batch ??= Promise.resolve().then(async () => {
+          signal.throwIfAborted();
+          if (database.queryBatch)
+            return database.queryBatch(target, misses);
+          const rows = [];
+          for (const item of misses) {
+            signal.throwIfAborted();
+            rows.push(await database.query(target, item.sql, item.values));
+          }
+          return rows;
+        });
+        return batch.then((rows) => rows[position]);
+      })));
+    },
+    close: async () => {}
+  };
+}
+
+export { withReadScope };

package/dist/data-loader.d.ts

@@ -0,0 +1,21 @@
+export interface DataLoaderOptions {
+    maxEntries: number;
+    /** Serialized result bytes retained, excluding keys/errors and active operation memory. */
+    maxBytes: number;
+    signal: AbortSignal;
+}
+/** A scoped async loading cache, similar to Guava's LoadingCache.
+ * Shares results, failures and in-flight reads until close; consumers must not mutate results.
+ * Unlike a long-lived LoadingCache, this scope has no refresh/expiry or automatic batching.
+ * Keys and loading operations belong to adapters; the same key must have the same result type.
+ * Operations must honor their signal for prompt cancellation. No underlying client is owned.
+ */
+export declare class DataLoader {
+    #private;
+    private readonly options;
+    constructor(options: DataLoaderOptions);
+    /** Undefined keys bypass caching. A waiter's signal cancels only that wait, not shared work. */
+    read<T>(key: unknown, operation: (signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /** Abort cooperative operations and join all reads, including capacity-bypass reads. */
+    close(reason?: unknown): Promise<void>;
+}

package/dist/data-loader.js

@@ -0,0 +1,91 @@
+// src/data-loader.ts
+import { serialize } from "node:v8";
+
+class DataLoader {
+  options;
+  #entries = new Map;
+  #pending = new Set;
+  #controller = new AbortController;
+  #bytes = 0;
+  #closing;
+  constructor(options) {
+    this.options = options;
+    for (const name of ["maxEntries", "maxBytes"]) {
+      if (!Number.isSafeInteger(options[name]) || options[name] < 1)
+        throw new Error(`${name} must be a positive safe integer`);
+    }
+    options.signal.throwIfAborted();
+    options.signal.addEventListener("abort", this.#abort, { once: true });
+  }
+  #abort = () => {
+    this.close(this.options.signal.reason);
+  };
+  async read(key, operation, signal) {
+    this.#controller.signal.throwIfAborted();
+    signal?.throwIfAborted();
+    let pending = key === undefined ? undefined : this.#entries.get(key);
+    if (!pending) {
+      const retain = key !== undefined && this.#entries.size < this.options.maxEntries;
+      pending = Promise.resolve().then(async () => {
+        this.#controller.signal.throwIfAborted();
+        const value = await operation(this.#controller.signal);
+        this.#controller.signal.throwIfAborted();
+        if (retain) {
+          let bytes;
+          try {
+            bytes = serialize(value).byteLength;
+          } catch {
+            bytes = Infinity;
+          }
+          if (this.#bytes + bytes <= this.options.maxBytes)
+            this.#bytes += bytes;
+          else
+            this.#entries.delete(key);
+        }
+        return value;
+      });
+      if (retain)
+        this.#entries.set(key, pending);
+      this.#pending.add(pending);
+      const done = () => {
+        this.#pending.delete(pending);
+      };
+      pending.then(done, done);
+    }
+    if (!signal)
+      return await pending;
+    return new Promise((resolve, reject) => {
+      const abort = () => {
+        cleanup();
+        reject(signal.reason);
+      };
+      const cleanup = () => {
+        signal.removeEventListener("abort", abort);
+      };
+      signal.addEventListener("abort", abort, { once: true });
+      pending.then((value) => {
+        cleanup();
+        resolve(value);
+      }, (error) => {
+        cleanup();
+        reject(error);
+      });
+    });
+  }
+  close(reason = new Error("DataLoader scope is closed")) {
+    if (!this.#closing) {
+      this.#closing = Promise.resolve().then(async () => {
+        await Promise.allSettled([...this.#pending]);
+        this.#entries.clear();
+        this.#bytes = 0;
+      });
+      this.options.signal.removeEventListener("abort", this.#abort);
+      this.#controller.abort(reason);
+      this.#entries.clear();
+    }
+    return this.#closing;
+  }
+}
+export {
+  DataLoader
+};

package/dist/kubernetes/pod-log-client.js

@@ -1,9 +1,9 @@
 import {
   PodLogClient
-} from "../chunk-010339ga.js";
+} from "../chunk-mnad4zkp.js";
 import"../chunk-8nm9f0hh.js";
-import"../chunk-1vfwvgkj.js";
 import"../chunk-mp88s7r7.js";
+import"../chunk-1vfwvgkj.js";
 import"../chunk-a9htb6cr.js";
 import"../chunk-v3hxvnrc.js";
 export {

package/dist/kubernetes/pod-log-datasource.js

@@ -1,9 +1,9 @@
 import {
   PodLogClient
-} from "../chunk-010339ga.js";
+} from "../chunk-mnad4zkp.js";
 import"../chunk-8nm9f0hh.js";
-import"../chunk-1vfwvgkj.js";
 import"../chunk-mp88s7r7.js";
+import"../chunk-1vfwvgkj.js";
 import"../chunk-a9htb6cr.js";
 import {
   clientKey

package/dist/mysql/client.js

@@ -2,9 +2,9 @@ import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-jx740hjh.js";
-import"../chunk-kbewz29a.js";
+} from "../chunk-56t4qyp7.js";
 import"../chunk-m91t44jh.js";
+import"../chunk-kbewz29a.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-5fgbhx2r.js";

package/dist/mysql/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./types";
 export * from "./target";
 export * from "./client";
+export * from "./limited";
+export * from "./scoped";

package/dist/mysql/index.js

@@ -1,14 +1,22 @@
+import"../chunk-pfar9cm3.js";
+import {
+  withReadScope
+} from "../chunk-4sqvppz7.js";
 import {
   MysqlClient,
   MysqlDatabase,
   openMysql
-} from "../chunk-jx740hjh.js";
+} from "../chunk-56t4qyp7.js";
+import"../chunk-m91t44jh.js";
 import"../chunk-kbewz29a.js";
 import {
   parseMysqlEnvTarget
 } from "../chunk-qq77x9ek.js";
-import"../chunk-pfar9cm3.js";
-import"../chunk-m91t44jh.js";
+import {
+  limitedRows,
+  limitedStatement,
+  queryLimited
+} from "../chunk-1gyshqd9.js";
 import"../chunk-v3hxvnrc.js";
 import"../chunk-h8fwx0k7.js";
 import"../chunk-5fgbhx2r.js";
@@ -17,8 +25,12 @@ import"../chunk-hmah9t8e.js";
 import"../chunk-mn6dwsvh.js";
 import"../chunk-ssj93brx.js";
 export {
+  withReadScope,
+  queryLimited,
   parseMysqlEnvTarget,
   openMysql,
+  limitedStatement,
+  limitedRows,
   MysqlDatabase,
   MysqlClient
 };

package/dist/mysql/limited.d.ts

@@ -0,0 +1,13 @@
+import type { Database, DatabaseRow, DatabaseTarget, SqlStatement } from "./types";
+export interface LimitedRows {
+    rows: DatabaseRow[];
+    truncated: boolean;
+}
+/** Append to caller-owned SQL without an existing LIMIT or trailing terminator; never rewrite SQL.
+ * An integer literal avoids driver/server differences in numeric LIMIT parameter binding.
+ */
+export declare function limitedStatement(statement: SqlStatement, maxRows: number): SqlStatement;
+/** The extra row proves truncation; batch callers can use the same projection. */
+export declare function limitedRows(rows: DatabaseRow[], maxRows: number): LimitedRows;
+/** Row-count bound for trusted reads on the existing session, not a readonly transaction or byte cap. */
+export declare function queryLimited(database: Pick<Database, "query">, target: DatabaseTarget, statement: SqlStatement, maxRows: number): Promise<LimitedRows>;

package/dist/mysql/limited.js

@@ -0,0 +1,10 @@
+import {
+  limitedRows,
+  limitedStatement,
+  queryLimited
+} from "../chunk-1gyshqd9.js";
+export {
+  queryLimited,
+  limitedStatement,
+  limitedRows
+};

package/dist/mysql/scoped.d.ts

@@ -0,0 +1,7 @@
+import type { DataLoader } from "../data-loader";
+import type { Database } from "./types";
+/** Bind caller-approved reads to a borrowed scope. Results are shared and must not be mutated.
+ * Close is a no-op: the root owns both scope and database lifetimes. Database operations retain
+ * their client's cancellation/timeout policy; they cannot be individually aborted by this adapter.
+ */
+export declare function withReadScope(database: Database, scope: DataLoader): Database & Required<Pick<Database, "queryBatch">>;

package/dist/mysql/scoped.js

@@ -0,0 +1,6 @@
+import {
+  withReadScope
+} from "../chunk-4sqvppz7.js";
+export {
+  withReadScope
+};

package/dist/mysql/types.d.ts

@@ -29,5 +29,7 @@ export interface DatabaseQueryResult {
 export interface Database {
     query(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow[]>;
     queryOne(target: DatabaseTarget, sql: string, values: readonly unknown[]): Promise<DatabaseRow | undefined>;
+    /** Independent statements in submission order; fail-fast, without atomicity or replay. */
+    queryBatch?(target: DatabaseTarget, statements: readonly SqlStatement[]): Promise<DatabaseRow[][]>;
     close(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compforge/harness-toolbox",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Shared infrastructure clients, transports and bounded data capture",
   "type": "module",
   "scripts": {
@@ -80,6 +80,10 @@
     "./concurrency": {
       "types": "./dist/concurrency.d.ts",
       "import": "./dist/concurrency.js"
+    },
+    "./data-loader": {
+      "types": "./dist/data-loader.d.ts",
+      "import": "./dist/data-loader.js"
     }
   },
   "files": [
@@ -102,9 +106,6 @@
     "@types/node-fetch": "2.6.13",
     "@types/node": "^22"
   },
-  "overrides": {
-    "@compforge/harness-common": "file:../common"
-  },
   "publishConfig": {
     "access": "public"
   },

package/dist/{chunk-jx740hjh.js → chunk-56t4qyp7.js}

@@ -1,11 +1,11 @@
-import {
-  queryReadonlySession,
-  validateQueryLimits
-} from "./chunk-kbewz29a.js";
 import {
   queryMysqlViaPod,
   queryMysqlViaPodBatch
 } from "./chunk-m91t44jh.js";
+import {
+  queryReadonlySession,
+  validateQueryLimits
+} from "./chunk-kbewz29a.js";
 import {
   ConcurrencyPool
 } from "./chunk-v3hxvnrc.js";

package/dist/{chunk-010339ga.js → chunk-mnad4zkp.js}

@@ -2,12 +2,12 @@ import {
   PodLogByteBudget,
   runPodLogCapturePlan
 } from "./chunk-8nm9f0hh.js";
-import {
-  LogCaptureFile
-} from "./chunk-1vfwvgkj.js";
 import {
   logTimestampNanos
 } from "./chunk-mp88s7r7.js";
+import {
+  LogCaptureFile
+} from "./chunk-1vfwvgkj.js";
 import {
   clientKey
 } from "./chunk-a9htb6cr.js";