"description":"A TypeScript library providing a cloud-agnostic interface for managing object storage with functionalities like bucket management, file and directory operations, and advanced features such as metadata handling and file locking.",
"description":"A TypeScript library offering simple and cloud-agnostic object storage with advanced features like bucket creation, file and directory management, and data streaming.",
"description":"A TypeScript library providing a cloud-agnostic interface for managing object storage with functionalities like bucket management, file and directory operations, and advanced features such as metadata handling and file locking.",
"version":"3.3.0",
"description":"A TypeScript library offering simple and cloud-agnostic object storage with advanced features like bucket creation, file and directory management, and data streaming.",
A comprehensive TypeScript library for cloud-agnostic object storage offering bucket management, file operations, and advanced data streaming.
A TypeScript library for cloud-independent object storage, providing features like bucket creation, file and directory management, and data streaming.
## Install
To install `@push.rocks/smartbucket`, ensure you have Node.js and npm installed. Then, run the following command in your project directory:
To install `@push.rocks/smartbucket`, you need to have Node.js and npm (Node Package Manager) installed. If they are installed, you can add `@push.rocks/smartbucket` to your project by running the following command in your project's root directory:
```bash
npm install @push.rocks/smartbucket --save
```
This command will add `@push.rocks/smartbucket` to your project's dependencies and install it along with its requirements in the `node_modules` directory.
This command will download and install `@push.rocks/smartbucket` along with its required dependencies into your project's `node_modules` directory and save it as a dependency in your project's `package.json` file.
## Usage
### Introduction
`@push.rocks/smartbucket` is a TypeScript module designed to provide simple cloud-independent object storage functionality. It wraps various cloud storage providers such as AWS S3, Google Cloud Storage, and others, offering a unified API to manage storage buckets and objects within those buckets.
`@push.rocks/smartbucket` provides a robust set of features to manage cloud storage operations in a cloud-agnostic manner. By leveraging this library, you can seamlessly interact with object storage services like AWS S3, without being tied to any vendor-specific implementations. This library not only abstracts basic file operations but also integrates advanced capabilities such as metadata management, data streaming, file locking, and bucket policies, all through a simplified API.
In this guide, we will delve into the usage of SmartBucket, covering its full range of features from setting up the library to advanced usage scenarios.
### Table of Contents
1. [Setting Up](#setting-up)
2. [Working with Buckets](#working-with-buckets)
- [Creating a New Bucket](#creating-a-new-bucket)
- [Listing Buckets](#listing-buckets)
- [Deleting Buckets](#deleting-buckets)
3. [File Operations in Buckets](#file-operations-in-buckets)
2. [Creating a New Bucket](#creating-a-new-bucket)
3. [Listing Buckets](#listing-buckets)
4. [Working with Files](#working-with-files)
- [Uploading Files](#uploading-files)
- [Downloading Files](#downloading-files)
- [Streaming Files](#streaming-files)
- [Deleting Files](#deleting-files)
4. [Directory Operations](#directory-operations)
- [Listing Directories and Files](#listing-directories-and-files)
- [Managing Files in Directories](#managing-files-in-directories)
5. [Advanced Features](#advanced-features)
- [Streaming Files](#streaming-files)
5. [Working with Directories](#working-with-directories)
6. [Advanced Features](#advanced-features)
- [Bucket Policies](#bucket-policies)
- [Metadata Management](#metadata-management)
- [File Locking](#file-locking)
- [Trash Management](#trash-management)
6. [Cloud Agnosticism](#cloud-agnosticism)
- [Object Metadata](#object-metadata)
- [Cloud Agnostic](#cloud-agnostic)
### Setting Up
Begin by importing the necessary classes from the `@push.rocks/smartbucket` package into your TypeScript file. Create an instance of `SmartBucket` with your storage configuration:
First, ensure you are using ECMAScript modules (ESM) and TypeScript in your project for best compatibility. Here's how to import and initialize SmartBucket in a TypeScript file:
```typescript
import {
@ -57,223 +49,264 @@ const mySmartBucket = new SmartBucket({
accessKey: "yourAccessKey",
accessSecret: "yourSecretKey",
endpoint: "yourEndpointURL",
port: 443,
useSsl: true
port: 443, // Default is 443, can be customized for specific endpoint
useSsl: true // Defaults to true
});
```
Replace `"yourAccessKey"`, `"yourSecretKey"`, and `"yourEndpointURL"` with actual data specific to your cloud provider.
Make sure to replace `"yourAccessKey"`, `"yourSecretKey"`, and `"yourEndpointURL"` with your actual credentials and endpoint URL. The `port` and `useSsl` options are optional and can be omitted if the defaults are acceptable.
### Working with Buckets
### Creating a New Bucket
#### Creating a New Bucket
Creating a bucket involves invoking the `createBucket` method. Note that bucket names are unique and follow the rules of the cloud provider:
console.log(`Bucket ${bucketName} created successfully.`);
} catch (error) {
console.error("Error creating bucket:", error);
}
}
createBucket("myNewBucket");
// Use the function
createBucket("exampleBucket");
```
#### Listing Buckets
Bucket names must be unique across the storage service.
While the library uses cloud-provider capabilities like AWS SDK to list existing buckets, `smartbucket` is aimed at simplifying content management within them.
### Listing Buckets
#### Deleting Buckets
Currently, SmartBucket does not include a direct method to list all buckets, but you can access the underlying client provided by the cloud storage SDK to perform such operations, depending on the SDK's capabilities.
To delete a bucket, simply call the `removeBucket` function:
`@push.rocks/smartbucket` offers abstractions for directories within buckets for easier object management. You can create, list, and delete directories using the `Directory` class.
To list the contents of a directory:
```typescript
async function listDirectoryContents(bucketName: string, directoryPath: string) {
SmartBucket enables a safe deletion mode where files can be moved to a recycling bin, allowing for restoration:
`@push.rocks/smartbucket` is designed to work with multiple cloud providers, allowing for easier migration or multi-cloud strategies. This means you can switch from one provider to another with minimal changes to your codebase.
```typescript
async function trashAndRestoreFile(bucketName: string, filePath: string) {
Remember, each cloud provider has specific features and limitations. `@push.rocks/smartbucket` aims to abstract common functionalities, but always refer to the specific cloud provider's documentation for advanced features or limitations.
console.log(`File ${filePath} restored from trash.`);
}
trashAndRestoreFile("myBucket", "example.txt");
```
### Cloud Agnosticism
`@push.rocks/smartbucket` supports a multitude of cloud providers, enhancing flexibility in adopting different cloud strategies without the need for extensive code rewrite. It offers a uniform interface allowing to perform operations seamlessly between different storage solutions such as AWS S3, Google Cloud Storage, and more. This aspect empowers organizations to align their storage decisions with business needs rather than technical constraints.
By following this guide, you should be well-equipped to handle cloud storage operations using the `@push.rocks/smartbucket` library. Diligently constructed code examples elucidate the extensive functionalities offered by the library, aligned with best practices in cloud storage. For a deeper dive into any specific feature, refer to the comprehensive documentation provided with the library and the official documentation of the cloud providers you are integrating with.
```
This guide covers the basic to advanced scenarios of using `@push.rocks/smartbucket`. For further details, refer to the API documentation and examples.
description:'A TypeScript library providing a cloud-agnostic interface for managing object storage with functionalities like bucket management, file and directory operations, and advanced features such as metadata handling and file locking.'
version:'3.3.0',
description:'A TypeScript library offering simple and cloud-agnostic object storage with advanced features like bucket creation, file and directory management, and data streaming.'
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.