"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.",
"description":"A TypeScript library offering simple and cloud-agnostic object storage with advanced features like bucket creation, file and directory management, and data streaming.",
"version":"3.3.7",
"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.",
A TypeScript library for cloud-independent object storage, providing 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.
## Install
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:
To install `@push.rocks/smartbucket`, ensure you have Node.js and npm installed. Then, run the following command in your project directory:
```bash
npm install @push.rocks/smartbucket --save
```
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.
This command will add `@push.rocks/smartbucket` to your project's dependencies and install it along with its requirements in the `node_modules` directory.
## Usage
`@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.
### Introduction
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.
`@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.
### Table of Contents
1. [Setting Up](#setting-up)
2. [Creating a New Bucket](#creating-a-new-bucket)
3. [Listing Buckets](#listing-buckets)
4. [Working with Files](#working-with-files)
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)
- [Uploading Files](#uploading-files)
- [Downloading Files](#downloading-files)
- [Deleting Files](#deleting-files)
- [Streaming Files](#streaming-files)
5. [Working with Directories](#working-with-directories)
6. [Advanced Features](#advanced-features)
- [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)
- [Bucket Policies](#bucket-policies)
- [Object Metadata](#object-metadata)
- [Cloud Agnostic](#cloud-agnostic)
- [Metadata Management](#metadata-management)
- [File Locking](#file-locking)
- [Trash Management](#trash-management)
6. [Cloud Agnosticism](#cloud-agnosticism)
### Setting Up
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:
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:
```typescript
import {
@ -49,264 +57,223 @@ const mySmartBucket = new SmartBucket({
accessKey: "yourAccessKey",
accessSecret: "yourSecretKey",
endpoint: "yourEndpointURL",
port: 443, // Default is 443, can be customized for specific endpoint
useSsl: true // Defaults to true
port: 443,
useSsl: true
});
```
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.
Replace `"yourAccessKey"`, `"yourSecretKey"`, and `"yourEndpointURL"` with actual data specific to your cloud provider.
### Creating a New Bucket
### Working with Buckets
To create 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);
}
}
// Use the function
createBucket("exampleBucket");
createBucket("myNewBucket");
```
Bucket names must be unique across the storage service.
#### Listing Buckets
### Listing Buckets
While the library uses cloud-provider capabilities like AWS SDK to list existing buckets, `smartbucket` is aimed at simplifying content management within them.
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.
#### Deleting Buckets
### Working with Files
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.
Leverage directory functionalities to better organize and manage files within buckets.
To list the contents of a directory:
#### Listing Directories and Files
Listing contents showcases a directory’s structure and file contents:
```typescript
async function listDirectoryContents(bucketName: string, directoryPath: string) {
`@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.
SmartBucket enables a safe deletion mode where files can be moved to a recycling bin, allowing for restoration:
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.
```typescript
async function trashAndRestoreFile(bucketName: string, filePath: string) {
This guide covers the basic to advanced scenarios of using `@push.rocks/smartbucket`. For further details, refer to the API documentation and examples.
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.
description:'A TypeScript library offering simple and cloud-agnostic object storage with advanced features like bucket creation, file and directory management, and data streaming.'
version:'3.3.7',
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.'
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.
