@treeimmersion/storage

@treeimmersion/storage is an NPM library developed by Tree Immersion Technologies that provides a unified interface for managing file storage operations in Amazon S3 and Google Cloud Storage (GCS).

This library simplifies file uploads, downloads, and deletions while ensuring consistency and ease of use across both cloud storage services.

🔥 Key Features

• ✅ Multi-cloud support: Works seamlessly with both Amazon S3 and Google Cloud Storage.
• ✅ Unified API: One interface to manage storage operations across different cloud providers.
• ✅ Error handling: Custom error classes provide better debugging and error management.
• ✅ Flexible access control: Support for both public and private file storage.
• ✅ TypeScript support: Fully typed with TypeScript for better developer experience.

🚀 Installation

Install the package using npm:

npm install @treeimmersion/storage

Or using yarn:

yarn add @treeimmersion/storage

⚙️ Configuration

Before using the library, ensure that your environment variables are properly set.

Amazon S3 Configuration

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=your_region
AWS_BUCKET_NAME=your_bucket

Google Cloud Storage (GCS) Configuration

GOOGLE_APPLICATION_CREDENTIALS=path/to/your-credentials.json
GCS_BUCKET_NAME=your_bucket

📌 Usage

Initializing the Storage Client

For Amazon S3

import storage from '@treeimmersion/storage';

const s3Client: S3Client = storage.createS3Client(
  {
    region: process.env.AWS_REGION!,
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    },
  },
  process.env.AWS_BUCKET_NAME!,
);

For Google Cloud Storage (GCS)

import storage from '@treeimmersion/storage';

const gcsClient: GCSClient = storage.createGCSClient(
  {
    keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS!,
  },
  process.env.GCS_BUCKET_NAME!,
);

Uploading a File

For Amazon S3

const body = Buffer | string;
const metadata = {
  owner: 'user123',
  description: 'Confidential document',
  uploadedBy: 'admin',
};
const response = await s3Client.createFile({
  path: 'docs',
  fileName: 'README.md',
  body,
  isPublic: true,
  metadata, // Optional
  expiresInSeconds: 60, // Optional
});

console.log('File uploaded to:', response?.url);

For Google Cloud Storage (GCS)

const data = Buffer | string;
const metadata = {
  owner: 'user123',
  description: 'Confidential document',
  uploadedBy: 'admin',
};
const response = await gcsClient.createFile({
  path: 'docs',
  fileName: 'README.md',
  data,
  isPublic: true,
  metadata, // Optional
  expiresInSeconds: 60, // Optional
});

console.log('File uploaded successfully:', response?.url);

Other Methods

For Amazon S3

• getFile({ key: string }): Buffer
• getFileMetadata({ key: string }): any
• updateFile({ key: string; body: Buffer | string; isPublic?: boolean, metadata?: any, expiresInSeconds?: number }): { id: string; key: string; url: string }
• deleteFile({ key: string }): void
• fileExists({ key: string }): boolean
• generateSignedUrl({ key: string; expiresInSeconds: number }): string

For Google Cloud Storage (GCS)

• getFile({ filePath: string }): Buffer
• getFileMetadata({ filePath: string }): any
• updateFile({ filePath: string; data: Buffer | string; isPublic?: boolean, metadata?: any, expiresInSeconds?: number }): { filePath: string; url: string }
• deleteFile({ filePath: string }): void
• fileExists({ filePath: string }): boolean
• generateSignedUrl({ filePath: string; expiresInSeconds: number }): string

📜 License

This project is licensed under the MIT License.

© 2025 Tree Immersion Technologies. All rights reserved.