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

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.

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.

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.

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.