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.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Google Cloud Storage Client Library

Name: tessl/npm-google-cloud--storage
Author: tessl

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
});

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 2 months ago
Describes: pkg:npm/@google-cloud/storage@7.17.x
Publish Source: CLI
Badge