Google Cloud Developer Utilities

A comprehensive TypeScript library providing utilities and abstractions for Google Cloud Platform services including Cloud Storage, Firestore, Secret Manager, and metadata access.

Installation

npm install @farport/gcutils

Requirements:

• Node.js >=20
• Google Cloud authentication (see Authentication)

Authentication

Before using any modules, ensure you have Google Cloud authentication set up:

1. Application Default Credentials (Recommended):

   gcloud auth application-default login

2. Service Account Keys:

   Set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your service account key file.

3. Environment Variables:

   For local development, you can use environment variable fallbacks (see individual module documentation).

Components Overview

Cloud Storage

Powerful wrapper around Google Cloud Storage with support for gs:// style paths.

• BStore - Promise-based interface for Cloud Storage operations
• BStoreRx - RxJS Observable-based interface for reactive programming
• Features: Automatic path parsing, streaming support, metadata handling

📖 Detailed Documentation

Firestore

Class-driven interface for Google Cloud Firestore with built-in validation and type safety.

• FirestoreService - Promise-based Firestore operations
• AbstractBaseFirebaseModel - Base class for type-safe document models
• Features: Automatic validation, namespace support, query capabilities, multi-tenant applications

📖 Detailed Documentation

Secret Manager

Service-oriented interface for Google Cloud Secret Manager with caching and version management.

• SecretsService - Promise-based secret management with async factory pattern
• Features: In-memory caching, version management, bulk secret loading, error handling with defaults

📖 Detailed Documentation

Pub/Sub

Service-oriented interface for Google Cloud Pub/Sub with built-in error handling and JSON message support.

• PubSubService - Main service class for managing topics and subscriptions
• Publisher - Dedicated class for publishing messages with JSON support
• Subscriber - Dedicated class for consuming messages with automatic error handling
• Features: Automatic topic/subscription creation, JSON message support, retry logic, clean resource management

📖 Detailed Documentation

Metadata

Easy access to Google Cloud Metadata server for instance and project information.

• GCloudMetadata - Cached access to Google Cloud metadata
• Features: Automatic caching, environment variable fallbacks, type-safe property access

📖 Detailed Documentation

Quick Start

// Cloud Storage
import { BStore, BStoreRx } from '@farport/gcutils/cloud-storage';
const store = new BStore();

// Firestore
import { FirestoreService } from '@farport/gcutils/firestore';
const firestore = new FirestoreService({ projectId: 'your-project' });

// Pub/Sub
import { PubSubService } from '@farport/gcutils/pubsub';
const pubsub = new PubSubService({ projectId: 'your-project' });

// Secret Manager
import { SecretsService } from '@farport/gcutils/secret-manager';
const secrets = await SecretsService.create({ projectId: 'your-project' });

// Metadata
import { GCloudMetadata } from '@farport/gcutils/metadata';
const metadata = new GCloudMetadata();

Running Tests

Prerequisites:

• Make sure that a google cloud project is activated using gcloud
• You must create a .env.local with required test env variables
• Ensure that files in the test/data is in a bucket gs://<GCUTILS_TEST_BUCKET>/public/ directory
• Start emulators by running yarn emulators:up

Content of .env.local:

GCUTILS_GOOGLE_CLOUD_PROJECT="<Google Project Name>"
GCUTILS_GOOGLE_CLOUD_PROJECT_NUMBER="<Google Project Number>"
GCUTILS_TEST_BUCKET="<Google Cloud Storage Bucket Name>"
GCUTILS_METADATA_PROXY_URL="<Secure Cloud Run URL that proxy to the metadata.google.internal host>"

You can easily skip the test/metadata/mdata-proxy.spec.ts test if you do not have a GCUTILS_METADATA_PROXY_URL

Run Tests:

# Run all tests with coverage
yarn test

# Run tests that exits upon first failure
yarn utest

# Run library tests
yarn test:lib

Stop Emulators:

yarn emulators:down

Development

Build the library:

yarn build

Lint and format:

yarn lint

Generate documentation:

yarn gendoc

Clean build artifacts:

yarn clean