or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

access-control.mdauthentication.mdbucket-operations.mdfile-operations.mdindex.mdnotifications.mdstorage-client.mdtransfer-manager.mdutilities.md
tile.json

tessl/npm-google-cloud--storage

Cloud Storage Client Library for Node.js that provides comprehensive API for managing buckets, files, and metadata with authentication, streaming, and access control.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@google-cloud/storage@7.17.x

To install, run

npx @tessl/cli install tessl/npm-google-cloud--storage@7.17.0

index.mddocs/

Google Cloud Storage Client Library

Official Node.js client library for Google Cloud Storage that provides comprehensive API for managing buckets, files, and metadata with authentication, streaming, and access control.

Package Information

// Installation
npm install @google-cloud/storage

// Import
import { Storage } from '@google-cloud/storage';
// or
const { Storage } = require('@google-cloud/storage');

Core Imports

// Main Storage class and core types
import { 
  Storage,
  StorageOptions,
  IdempotencyStrategy,
  PreconditionOptions,
  RetryOptions
} from '@google-cloud/storage';

// Bucket class and related types
import { 
  Bucket,
  BucketOptions,
  CreateBucketRequest,
  CreateBucketResponse,
  GetBucketsRequest,
  GetBucketsResponse,
  UploadOptions,
  UploadResponse
} from '@google-cloud/storage';

// File class and related types
import { 
  File,
  FileOptions,
  FileMetadata,
  DownloadOptions,
  DownloadResponse,
  PredefinedAcl
} from '@google-cloud/storage';

// Access control classes and types
import { 
  AclMetadata,
  AccessControlObject,
  Policy,
  PolicyBinding,
  Iam
} from '@google-cloud/storage';

// HMAC Key management
import {
  HmacKey,
  HmacKeyMetadata,
  CreateHmacKeyOptions,
  CreateHmacKeyResponse
} from '@google-cloud/storage';

// Notifications
import {
  Notification,
  NotificationMetadata,
  Channel
} from '@google-cloud/storage';

// Transfer Manager
import {
  TransferManager,
  UploadManyFilesOptions,
  DownloadManyFilesOptions
} from '@google-cloud/storage';

// Utilities and validation
import {
  CRC32C,
  HashStreamValidator,
  GetSignedUrlResponse
} from '@google-cloud/storage';

// Error handling
import { ApiError } from '@google-cloud/storage';

Basic Usage

// Create client with Application Default Credentials
const storage = new Storage();

// Create client with explicit credentials
const storage = new Storage({
  projectId: 'your-project-id',
  keyFilename: '/path/to/keyfile.json'
});

// Get bucket reference
const bucket = storage.bucket('my-bucket');

// Get file reference
const file = bucket.file('path/to/file.txt');

Architecture

The library is organized around these core concepts:

  • Storage: Main client class providing bucket and service account management
  • Bucket: Container for files with metadata, lifecycle rules, and access control
  • File: Individual objects with upload/download, encryption, and access control
  • Access Control: ACL and IAM-based permissions for buckets and files
  • Authentication: HMAC keys and service account management
  • Utilities: Transfer manager, checksums, and signed URL generation

Essential Types

// Configuration options
interface StorageOptions {
  projectId?: string;
  keyFilename?: string;
  apiEndpoint?: string;
  retryOptions?: RetryOptions;
  crc32cGenerator?: CRC32CValidatorGenerator;
}

interface BucketOptions {
  userProject?: string;
  kmsKeyName?: string;
  generation?: number;
  preconditionOpts?: PreconditionOptions;
}

interface FileOptions {
  generation?: number | string;
  encryptionKey?: string | Buffer;
  kmsKeyName?: string;
  userProject?: string;
}

// Precondition options for conditional operations
interface PreconditionOptions {
  ifGenerationMatch?: number | string;
  ifGenerationNotMatch?: number | string;
  ifMetagenerationMatch?: number | string;
  ifMetagenerationNotMatch?: number | string;
}

// Retry configuration
interface RetryOptions {
  retryDelayMultiplier?: number;
  totalTimeout?: number;
  maxRetryDelay?: number;
  autoRetry?: boolean;
  maxRetries?: number;
  retryableErrorFn?: (err: ApiError) => boolean;
  idempotencyStrategy?: IdempotencyStrategy;
}

// Idempotency strategy enum
enum IdempotencyStrategy {
  RetryAlways,
  RetryConditional, 
  RetryNever
}

// Common response patterns
type ResourceResponse<T> = [T, unknown]; // [resource, apiResponse]
type ListResponse<T> = [T[], {}, unknown]; // [items, nextQuery, apiResponse]
type OperationResponse = [unknown]; // [apiResponse]

Client Operations

Storage Client

Core Storage class functionality including bucket management, service account operations, and HMAC key administration.

Key APIs:

  • Bucket management: bucket(), createBucket(), getBuckets()
  • Service account: getServiceAccount()
  • HMAC keys: createHmacKey(), getHmacKeys(), hmacKey()
  • Channels: channel()

Bucket Operations

Bucket class providing file management, metadata operations, lifecycle rules, and bucket-level access control.

Key APIs:

  • File operations: file(), getFiles(), upload(), deleteFiles()
  • Metadata: getMetadata(), setMetadata(), exists()
  • Access control: makePublic(), makePrivate()
  • Lifecycle: addLifecycleRule(), setStorageClass()
  • Notifications: createNotification(), getNotifications()

File Operations

File class for individual object operations including upload/download, encryption, and metadata management.

Key APIs:

  • Upload/Download: save(), download(), createReadStream(), createWriteStream()
  • Management: copy(), move(), delete(), getMetadata(), setMetadata()
  • Security: makePublic(), makePrivate(), getSignedUrl()
  • Encryption: rotateEncryptionKey()

Access Control

ACL and IAM functionality for managing permissions on buckets and files.

Key APIs:

  • ACL operations: add(), get(), update(), remove()
  • Role management: owners, readers, writers
  • IAM policies: getPolicy(), setPolicy(), testIamPermissions()

Authentication

HMAC key management and authentication options for programmatic access.

Key APIs:

  • HMAC management: createHmacKey(), getHmacKeys(), hmacKey()
  • Key operations: getMetadata(), setMetadata(), delete()

Notifications

Pub/Sub integration for bucket change notifications and channel management.

Key APIs:

  • Notifications: createNotification(), getNotifications(), delete()
  • Channels: createChannel(), stop()

Transfer Manager

Bulk upload/download operations with parallel processing and progress tracking.

Key APIs:

  • Bulk uploads: uploadManyFiles(), uploadFileInChunks()
  • Bulk downloads: downloadManyFiles(), downloadFileInChunks()

Utilities

Supporting utilities including checksums, signed URLs, and stream validation.

Key APIs:

  • Checksums: CRC32C, HashStreamValidator
  • Signed URLs: getSignedUrl(), generateSignedPostPolicy()
  • Channels: Channel, stop()

Error Handling

import { ApiError } from '@google-cloud/storage';

try {
  const [files] = await bucket.getFiles();
} catch (error) {
  if (error instanceof ApiError) {
    console.log(`Error ${error.code}: ${error.message}`);
    console.log('Details:', error.errors);
  }
}

// Configure retry behavior
const storage = new Storage({
  retryOptions: {
    autoRetry: true,
    maxRetries: 3,
    retryDelayMultiplier: 2,
    totalTimeout: 600000, // 10 minutes
    idempotencyStrategy: IdempotencyStrategy.RetryConditional
  }
});

Common Patterns

// List all buckets
const [buckets] = await storage.getBuckets();
buckets.forEach(bucket => console.log(bucket.name));

// Upload a file
await bucket.upload('/local/path/file.txt', {
  destination: 'remote/path/file.txt',
  metadata: {
    contentType: 'text/plain'
  }
});

// Download a file
await bucket.file('remote/path/file.txt').download({
  destination: '/local/path/downloaded.txt'
});

// Stream operations
const readStream = bucket.file('large-file.zip').createReadStream();
const writeStream = bucket.file('upload.zip').createWriteStream();

readStream.pipe(writeStream);

// Signed URL for temporary access
const [url] = await bucket.file('document.pdf').getSignedUrl({
  version: 'v4',
  action: 'read',
  expires: Date.now() + 15 * 60 * 1000 // 15 minutes
});