gcf-common-lib 0.41.0 → 0.45.0

package/.github/workflows/npm-publish.yml

@@ -1,39 +1,37 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
-
-name: Node.js Package
-on: [ push ]
-
-# on:
-#  release:
-#    types: [created]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npm ci
-#      - run: npm run build
-      - run: npm test
-
-  publish-npm:
-    permissions:
-      contents: read # This is required for actions/checkout
-      id-token: write # This is required for publishing to npm
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-      - run: npm ci
-#      - run: npm run build
-      - run: npm publish --provenance
-#        env:
-#          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
+
+name: Node.js Package
+on: [ push ]
+
+# on:
+#  release:
+#    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+      - run: npm ci
+#      - run: npm run build
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # This is required for actions/checkout
+      id-token: write # This is required for publishing to npm
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+#      - run: npm run build
+      - run: npm publish

package/.junie/guidelines.md

@@ -1,108 +1,108 @@
-# gcf-common-lib: Development Guidelines
-
-This document captures project-specific details to speed up work on this repository.
-It assumes an advanced Node/TypeScript developer familiar with Node 20+, npm, ESLint flat config, and the Node test runner.
-
-## 1) Build and Configuration
-
-- Runtime/Tooling versions
-  - Node: >= 20 (see package.json "engines"). Tested with Node 20.x.
-  - TypeScript: ^5.3 (dev dependency). The project extends `@tsconfig/node20`.
-- TypeScript config
-  - tsconfig.json extends `@tsconfig/node20`. It currently sets only `"compilerOptions.newLine": "crlf"`.
-  - `@tsconfig/node20` typically configures strict mode and `noEmit: true`. As a result, `npm run build` performs type-checking only and does not emit JS artifacts by default.
-  - If you need JS output, add an `outDir` and override `noEmit: false` in tsconfig.json (or create a separate tsconfig.build.json) and adjust the build script accordingly.
-- Build
-  - Type-check: `npm run build` (runs `tsc`). No compiled JS will be emitted with the current config.
-- Entry point / module resolution
-  - package.json sets `"main": "src/index"`. The published package is intended to be consumed by TS-aware builds, bundlers, or via transpilation. Node alone cannot `require('src')` TypeScript without a loader/transpiler.
-- Linting/Formatting
-  - ESLint flat config with:
-    - `@eslint/js` (base JS rules), `typescript-eslint` (TS rules), `eslint-plugin-unicorn`, and `eslint-plugin-promise`.
-    - Notable overrides: several `@typescript-eslint/*` rules are off (no-explicit-any, no-unused-vars, no-empty-function, no-empty-interface). `unicorn/prevent-abbreviations` is off. Additional rules enforce `block-scoped-var`, `no-loop-func`.
-  - Prettier is present as a dev dependency; there is no explicit npm script, run via `npx prettier --write .` if needed.
-  - Line endings: CRLF (Windows) per tsconfig; ensure your editor respects this to avoid noisy diffs.
-
-## 2) Testing
-
-- Framework
-  - Uses Node’s built-in test runner (`node:test`) with `node:assert/strict`.
-  - Default npm script: `npm test` runs `node --test ./test/`.
-
-- Important notes for this repo
-  - Some code paths interact with external services (Google Pub/Sub via `@google-cloud/pubsub`, AMQP via `amqplib`). Avoid hitting those in unit tests unless you have proper credentials and brokers.
-  - The repository contains `test/test.ts` (TypeScript) and a historical compiled `test/test.js`. The JS test tries to `require('../src')`, but the project does not emit JS builds by default, so Node cannot load TS sources as JS. Running the whole suite may therefore fail locally unless you:
-    - Compile TS to JS and point Node to the emitted entry, or
-    - Use a loader (e.g., ts-node / swc / tsx) to run TS directly, or
-    - Write tests in JS that import only pure functions that do not require transpilation.
-
-- Recommended local workflows
-  1) Run a single, deterministic JS test file (no external deps):
-     - Place a JS test under `test/` with a `.test.js` name, then run:
-       - `node --test .\test\your.test.js`
-     - Example (verified locally):
-       ```js
-       // test/sample.test.js
-       const { describe, it } = require('node:test');
-       const assert = require('node:assert/strict');
-       describe('sample', () => {
-         it('adds numbers', () => {
-           assert.equal(1 + 1, 2);
-         });
-         it('async works', async () => {
-           const v = await Promise.resolve('ok');
-           assert.equal(v, 'ok');
-         });
-       });
-       ```
-       - Run: `node --test .\test\sample.test.js`
-
-  2) Testing library functions without network calls:
-     - Prefer testing pure utilities from `src/utils.ts` (e.g., `ms`, `sec`, `A1` conversions, `safeJsonParse`). Create JS shims if needed or compile.
-     - For `GcfCommon.process(...)`, avoid network I/O by passing payloads that do not contain `topic`, `exchange`, or `queue` in metadata/attributes. The `response(...)` method publishes only if those are present. Example payload for a no-network test:
-       ```ts
-       const payload = { event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: { ok: 1 }, attributes: {} }, context: undefined };
-       // No topic/exchange/queue -> response() becomes a no-op for network I/O
-       ```
-     - Alternatively, stub `GcfCommon.response` in tests:
-       ```js
-       const { GcfCommon } = require('../src');
-       const original = GcfCommon.response;
-       GcfCommon.response = async () => {}; // no-op
-       // ... run test logic ...
-       GcfCommon.response = original;
-       ```
-
-  3) Running TS tests
-     - Option A (compile): configure tsconfig to emit JS (e.g., to `dist/`), compile tests and source, and run Node against the emitted JS.
-     - Option B (loader): use a TS loader like `tsx` or `ts-node` to run TS under Node’s test runner. Example with tsx:
-       - Install dev dep: `npm i -D tsx`
-       - Run: `node --test --import tsx .\test\test.ts`
-       - Caveat: loader flags and support differ across Node versions; prefer pure JS tests if you want zero-config.
-
-- Integration tests (Pub/Sub, AMQP)
-  - Pub/Sub requires Google Application Default Credentials (e.g., set `GOOGLE_APPLICATION_CREDENTIALS=path\to\service-account.json`).
-  - AMQP requires a reachable broker URL; set `GcfCommon.amqpOptions.url` appropriately.
-  - These are not required for unit testing and should be skipped or stubbed in CI unless explicitly needed.
-
-## 3) Additional development information
-
-- Project layout
-  - `src/`: TypeScript sources (helpers for Pub/Sub, AMQP, Mongo, utilities, types, and `GcfCommon`).
-  - `test/`: Node test runner tests. Prefer `.test.js` files for frictionless execution without transpilation.
-- External services
-  - `GcfCommon.response(...)` conditionally publishes to Pub/Sub or AMQP if `topic`, `exchange`, or `queue` are present in payload metadata/attributes. Omit these in unit tests to avoid network calls.
-  - `GcfCommon.getOptions(...)` parses JSON options from metadata/attributes; it uses `safeJsonParse` with a fallback to avoid throwing.
-- Coding style
-  - Adhere to the ESLint setup, especially around promises and unicorn rules; long-lived abbreviations are allowed (prevent-abbreviations is off).
-  - Use CRLF line endings to match repo configuration.
-- CI/CD & publishing
-  - `publishConfig.access: public`; branch is `master` in metadata. If publishing, ensure you build/type-check and validate tests that do not require external services, or segregate integration tests under a separate command.
-
-## Quick Commands
-
-- Install deps: `npm ci`
-- Type-check build: `npm run build`
-- Run all JS tests in a file: `node --test .\test\some.test.js`
-- Lint (manual): `npx eslint .`
-- Format (manual): `npx prettier --write .`
+# gcf-common-lib: Development Guidelines
+
+This document captures project-specific details to speed up work on this repository.
+It assumes an advanced Node/TypeScript developer familiar with Node 20+, npm, ESLint flat config, and the Node test runner.
+
+## 1) Build and Configuration
+
+- Runtime/Tooling versions
+  - Node: >= 20 (see package.json "engines"). Tested with Node 20.x.
+  - TypeScript: ^5.3 (dev dependency). The project extends `@tsconfig/node20`.
+- TypeScript config
+  - tsconfig.json extends `@tsconfig/node20`. It currently sets only `"compilerOptions.newLine": "crlf"`.
+  - `@tsconfig/node20` typically configures strict mode and `noEmit: true`. As a result, `npm run build` performs type-checking only and does not emit JS artifacts by default.
+  - If you need JS output, add an `outDir` and override `noEmit: false` in tsconfig.json (or create a separate tsconfig.build.json) and adjust the build script accordingly.
+- Build
+  - Type-check: `npm run build` (runs `tsc`). No compiled JS will be emitted with the current config.
+- Entry point / module resolution
+  - package.json sets `"main": "src/index"`. The published package is intended to be consumed by TS-aware builds, bundlers, or via transpilation. Node alone cannot `require('src')` TypeScript without a loader/transpiler.
+- Linting/Formatting
+  - ESLint flat config with:
+    - `@eslint/js` (base JS rules), `typescript-eslint` (TS rules), `eslint-plugin-unicorn`, and `eslint-plugin-promise`.
+    - Notable overrides: several `@typescript-eslint/*` rules are off (no-explicit-any, no-unused-vars, no-empty-function, no-empty-interface). `unicorn/prevent-abbreviations` is off. Additional rules enforce `block-scoped-var`, `no-loop-func`.
+  - Prettier is present as a dev dependency; there is no explicit npm script, run via `npx prettier --write .` if needed.
+  - Line endings: CRLF (Windows) per tsconfig; ensure your editor respects this to avoid noisy diffs.
+
+## 2) Testing
+
+- Framework
+  - Uses Node’s built-in test runner (`node:test`) with `node:assert/strict`.
+  - Default npm script: `npm test` runs `node --test ./test/`.
+
+- Important notes for this repo
+  - Some code paths interact with external services (Google Pub/Sub via `@google-cloud/pubsub`, AMQP via `amqplib`). Avoid hitting those in unit tests unless you have proper credentials and brokers.
+  - The repository contains `test/test.ts` (TypeScript) and a historical compiled `test/test.js`. The JS test tries to `require('../src')`, but the project does not emit JS builds by default, so Node cannot load TS sources as JS. Running the whole suite may therefore fail locally unless you:
+    - Compile TS to JS and point Node to the emitted entry, or
+    - Use a loader (e.g., ts-node / swc / tsx) to run TS directly, or
+    - Write tests in JS that import only pure functions that do not require transpilation.
+
+- Recommended local workflows
+  1) Run a single, deterministic JS test file (no external deps):
+     - Place a JS test under `test/` with a `.test.js` name, then run:
+       - `node --test .\test\your.test.js`
+     - Example (verified locally):
+       ```js
+       // test/sample.test.js
+       const { describe, it } = require('node:test');
+       const assert = require('node:assert/strict');
+       describe('sample', () => {
+         it('adds numbers', () => {
+           assert.equal(1 + 1, 2);
+         });
+         it('async works', async () => {
+           const v = await Promise.resolve('ok');
+           assert.equal(v, 'ok');
+         });
+       });
+       ```
+       - Run: `node --test .\test\sample.test.js`
+
+  2) Testing library functions without network calls:
+     - Prefer testing pure utilities from `src/utils.ts` (e.g., `ms`, `sec`, `A1` conversions, `safeJsonParse`). Create JS shims if needed or compile.
+     - For `GcfCommon.process(...)`, avoid network I/O by passing payloads that do not contain `topic`, `exchange`, or `queue` in metadata/attributes. The `response(...)` method publishes only if those are present. Example payload for a no-network test:
+       ```ts
+       const payload = { event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: { ok: 1 }, attributes: {} }, context: undefined };
+       // No topic/exchange/queue -> response() becomes a no-op for network I/O
+       ```
+     - Alternatively, stub `GcfCommon.response` in tests:
+       ```js
+       const { GcfCommon } = require('../src');
+       const original = GcfCommon.response;
+       GcfCommon.response = async () => {}; // no-op
+       // ... run test logic ...
+       GcfCommon.response = original;
+       ```
+
+  3) Running TS tests
+     - Option A (compile): configure tsconfig to emit JS (e.g., to `dist/`), compile tests and source, and run Node against the emitted JS.
+     - Option B (loader): use a TS loader like `tsx` or `ts-node` to run TS under Node’s test runner. Example with tsx:
+       - Install dev dep: `npm i -D tsx`
+       - Run: `node --test --import tsx .\test\test.ts`
+       - Caveat: loader flags and support differ across Node versions; prefer pure JS tests if you want zero-config.
+
+- Integration tests (Pub/Sub, AMQP)
+  - Pub/Sub requires Google Application Default Credentials (e.g., set `GOOGLE_APPLICATION_CREDENTIALS=path\to\service-account.json`).
+  - AMQP requires a reachable broker URL; set `GcfCommon.amqpOptions.url` appropriately.
+  - These are not required for unit testing and should be skipped or stubbed in CI unless explicitly needed.
+
+## 3) Additional development information
+
+- Project layout
+  - `src/`: TypeScript sources (helpers for Pub/Sub, AMQP, Mongo, utilities, types, and `GcfCommon`).
+  - `test/`: Node test runner tests. Prefer `.test.js` files for frictionless execution without transpilation.
+- External services
+  - `GcfCommon.response(...)` conditionally publishes to Pub/Sub or AMQP if `topic`, `exchange`, or `queue` are present in payload metadata/attributes. Omit these in unit tests to avoid network calls.
+  - `GcfCommon.getOptions(...)` parses JSON options from metadata/attributes; it uses `safeJsonParse` with a fallback to avoid throwing.
+- Coding style
+  - Adhere to the ESLint setup, especially around promises and unicorn rules; long-lived abbreviations are allowed (prevent-abbreviations is off).
+  - Use CRLF line endings to match repo configuration.
+- CI/CD & publishing
+  - `publishConfig.access: public`; branch is `master` in metadata. If publishing, ensure you build/type-check and validate tests that do not require external services, or segregate integration tests under a separate command.
+
+## Quick Commands
+
+- Install deps: `npm ci`
+- Type-check build: `npm run build`
+- Run all JS tests in a file: `node --test .\test\some.test.js`
+- Lint (manual): `npx eslint .`
+- Format (manual): `npx prettier --write .`

package/.prettierrc

@@ -1,10 +1,10 @@
-{
-  "printWidth": 120,
-  "trailingComma": "all",
-  "tabWidth": 2,
-  "semi": true,
-  "singleQuote": true,
-  "arrowParens": "avoid",
-  "bracketSameLine": true,
-  "endOfLine": "crlf"
-}
+{
+  "printWidth": 120,
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": true,
+  "arrowParens": "avoid",
+  "bracketSameLine": true,
+  "endOfLine": "crlf"
+}

package/README.md

@@ -1,110 +1,110 @@
-# gcf-common-lib
-
-Common helpers for Google Cloud Functions (GCF) and Node services:
-- Orchestrate handlers and conditional response publishing via Pub/Sub or AMQP (RabbitMQ).
-- Utilities: time helpers (ms/sec), Excel A1 conversions, safeJsonParse, simple delay/timeout.
-- Helpers for AMQP and MongoDB lifecycles.
-
-This library targets Node >= 20 and TypeScript. It is designed to be consumed by TS-aware builds or transpiled output.
-
-## Installation
-
-```sh
-npm i gcf-common-lib
-```
-
-## Quick start
-
-### Process an event without network I/O
-Pass a payload without `topic`, `exchange`, or `queue` to avoid publishing in unit tests or offline flows.
-
-```ts
-import { GcfCommon } from 'gcf-common-lib';
-
-export async function handler(payload: any) {
-  return { ok: 1 };
-}
-
-// Example payload: Pub/Sub-like message without routing attributes
-const payload = {
-  event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: { hello: 'world' }, attributes: {} },
-  context: undefined,
-};
-
-await GcfCommon.process(payload, handler);
-```
-
-### Publish a response to Pub/Sub
-Set the `topic` attribute in metadata/attributes. Response attributes are coerced to strings; common fields `request_id`, `consumer_id`, `app_id`, `env` are propagated if present.
-
-```ts
-import { GcfCommon } from 'gcf-common-lib';
-
-const payload = {
-  event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: {}, attributes: { topic: 'projects/my-proj/topics/my-topic', request_id: 'r1' } },
-  context: undefined,
-};
-
-await GcfCommon.process(payload, async () => ({ result: 42 }));
-// GcfCommon.response() will publish to the provided topic
-```
-
-### Publish a response to AMQP (RabbitMQ)
-Provide either `exchange` (with optional `queue` as routing key) or a `queue`.
-
-```ts
-import { GcfCommon } from 'gcf-common-lib';
-
-GcfCommon.amqpOptions.url = 'amqp://guest:guest@localhost:5672';
-
-const payload = {
-  event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: {}, attributes: { exchange: 'events', queue: 'route.key', request_id: 'r1' } },
-  context: undefined,
-};
-
-await GcfCommon.process(payload, async () => ({ result: 42 }));
-```
-
-## API overview
-
-### GcfCommon
-- `process<TResponse, E = TEvent>(payload: TPayload<E>, handler: (p: TPayload<E>) => Promise<any> | any): Promise<any>`
-  - Runs handler, then calls `response(...)` with handler result; on error publishes a structured error via `buildResponse(error)` and rethrows.
-- `response<E = TEvent>(payload: TPayload<E>, json?: TResponse, attributes?: Dict<any>): Promise<void>`
-  - Publishes to Pub/Sub if `topic` is present; to AMQP if `exchange` or `queue` is present. Attributes are stringified.
-- `buildResponse(error: Error): TResponse`
-- `getOptions(payload: TPayload): Promise<Dict<any>>`
-  - Parses JSON from `options` attribute with `safeJsonParse` and `{}` fallback.
-- `getMetadataOrAttribute<E = TEvent>(payload: TPayload<E>): TMetadataOrAttributes`
-  - Extracts attributes from GCS finalize, Pub/Sub publish events, or HTTP request body shape.
-- `getRequestMessage(request: express.Request)`
-
-### Utils
-- `ms({ w?, d?, h?, m?, s? }): number`
-- `sec({ w?, d?, h?, m?, s? }): number`
-- `indexToA1(idx: number): string`
-- `A1ToIndex(value: string): number`
-- `colNumToA1(columnNumber: number): string`
-- `A1ToColNum(value: string): number`
-- `safeJsonParse<T>(value: string, fallback?: T): T | undefined`
-- `delay(seconds: number): Promise<void>`
-- `timeoutAfter(seconds?: number): Promise<void>`
-
-### AmqpHelper
-- `withAmqpConn(fn, url)` — acquire AMQP connection (Bluebird disposer) and run `fn`.
-- `withAmqpCh(fn, url, useConfirmChannel = false, prefetch = 1)` — channel lifecycle helper.
-- `publishAmqp(ch, exchange | undefined, routingKey, json, options?)`
-- `sendToQueueConfAmqp(ch: ConfirmChannel, queue, json, options?)`
-
-### MongoHelper
-- `collectionExists(client, name)`
-- `collectionSafeGet(client, name, options?, afterCreate?)`
-- `withMongoClient(fn, url, options?)` — maintains a shared client in-process.
-
-## Testing
-- Uses Node’s built-in test runner (`node:test`).
-- Prefer JS tests under `test/*.test.js` for zero-transpilation.
-- Avoid network I/O in unit tests by omitting `topic`, `exchange`, and `queue` attributes or by stubbing `GcfCommon.response`.
-
-## License
+# gcf-common-lib
+
+Common helpers for Google Cloud Functions (GCF) and Node services:
+- Orchestrate handlers and conditional response publishing via Pub/Sub or AMQP (RabbitMQ).
+- Utilities: time helpers (ms/sec), Excel A1 conversions, safeJsonParse, simple delay/timeout.
+- Helpers for AMQP and MongoDB lifecycles.
+
+This library targets Node >= 20 and TypeScript. It is designed to be consumed by TS-aware builds or transpiled output.
+
+## Installation
+
+```sh
+npm i gcf-common-lib
+```
+
+## Quick start
+
+### Process an event without network I/O
+Pass a payload without `topic`, `exchange`, or `queue` to avoid publishing in unit tests or offline flows.
+
+```ts
+import { GcfCommon } from 'gcf-common-lib';
+
+export async function handler(payload: any) {
+  return { ok: 1 };
+}
+
+// Example payload: Pub/Sub-like message without routing attributes
+const payload = {
+  event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: { hello: 'world' }, attributes: {} },
+  context: undefined,
+};
+
+await GcfCommon.process(payload, handler);
+```
+
+### Publish a response to Pub/Sub
+Set the `topic` attribute in metadata/attributes. Response attributes are coerced to strings; common fields `request_id`, `consumer_id`, `app_id`, `env` are propagated if present.
+
+```ts
+import { GcfCommon } from 'gcf-common-lib';
+
+const payload = {
+  event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: {}, attributes: { topic: 'projects/my-proj/topics/my-topic', request_id: 'r1' } },
+  context: undefined,
+};
+
+await GcfCommon.process(payload, async () => ({ result: 42 }));
+// GcfCommon.response() will publish to the provided topic
+```
+
+### Publish a response to AMQP (RabbitMQ)
+Provide either `exchange` (with optional `queue` as routing key) or a `queue`.
+
+```ts
+import { GcfCommon } from 'gcf-common-lib';
+
+GcfCommon.amqpOptions.url = 'amqp://guest:guest@localhost:5672';
+
+const payload = {
+  event: { '@type': 'type.googleapis.com/google.pubsub.v1.PubsubMessage', json: {}, attributes: { exchange: 'events', queue: 'route.key', request_id: 'r1' } },
+  context: undefined,
+};
+
+await GcfCommon.process(payload, async () => ({ result: 42 }));
+```
+
+## API overview
+
+### GcfCommon
+- `process<TResponse, E = TEvent>(payload: TPayload<E>, handler: (p: TPayload<E>) => Promise<any> | any): Promise<any>`
+  - Runs handler, then calls `response(...)` with handler result; on error publishes a structured error via `buildResponse(error)` and rethrows.
+- `response<E = TEvent>(payload: TPayload<E>, json?: TResponse, attributes?: Dict<any>): Promise<void>`
+  - Publishes to Pub/Sub if `topic` is present; to AMQP if `exchange` or `queue` is present. Attributes are stringified.
+- `buildResponse(error: Error): TResponse`
+- `getOptions(payload: TPayload): Promise<Dict<any>>`
+  - Parses JSON from `options` attribute with `safeJsonParse` and `{}` fallback.
+- `getMetadataOrAttribute<E = TEvent>(payload: TPayload<E>): TMetadataOrAttributes`
+  - Extracts attributes from GCS finalize, Pub/Sub publish events, or HTTP request body shape.
+- `getRequestMessage(request: express.Request)`
+
+### Utils
+- `ms({ w?, d?, h?, m?, s? }): number`
+- `sec({ w?, d?, h?, m?, s? }): number`
+- `indexToA1(idx: number): string`
+- `A1ToIndex(value: string): number`
+- `colNumToA1(columnNumber: number): string`
+- `A1ToColNum(value: string): number`
+- `safeJsonParse<T>(value: string, fallback?: T): T | undefined`
+- `delay(seconds: number): Promise<void>`
+- `timeoutAfter(seconds?: number): Promise<void>`
+
+### AmqpHelper
+- `withAmqpConn(fn, url)` — acquire AMQP connection (Bluebird disposer) and run `fn`.
+- `withAmqpCh(fn, url, useConfirmChannel = false, prefetch = 1)` — channel lifecycle helper.
+- `publishAmqp(ch, exchange | undefined, routingKey, json, options?)`
+- `sendToQueueConfAmqp(ch: ConfirmChannel, queue, json, options?)`
+
+### MongoHelper
+- `collectionExists(client, name)`
+- `collectionSafeGet(client, name, options?, afterCreate?)`
+- `withMongoClient(fn, url, options?)` — maintains a shared client in-process.
+
+## Testing
+- Uses Node’s built-in test runner (`node:test`).
+- Prefer JS tests under `test/*.test.js` for zero-transpilation.
+- Avoid network I/O in unit tests by omitting `topic`, `exchange`, and `queue` attributes or by stubbing `GcfCommon.response`.
+
+## License
 MIT. See LICENSE.