@push.rocks/smartbucket
Version:
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.
206 lines (205 loc) • 7.33 kB
TypeScript
import * as plugins from './plugins.js';
import * as interfaces from './interfaces.js';
import { SmartBucket } from './classes.smartbucket.js';
import { Directory } from './classes.directory.js';
import { File } from './classes.file.js';
import { Trash } from './classes.trash.js';
import { ListCursor, type IListCursorOptions } from './classes.listcursor.js';
import { BucketWatcher } from './classes.watcher.js';
/**
* The bucket class exposes the basic functionality of a bucket.
* The functions of the bucket alone are enough to
* operate on blobs of data in an S3-compatible object store.
*/
export declare class Bucket {
static getBucketByName(smartbucketRef: SmartBucket, bucketNameArg: string): Promise<Bucket>;
static createBucketByName(smartbucketRef: SmartBucket, bucketName: string): Promise<Bucket>;
static removeBucketByName(smartbucketRef: SmartBucket, bucketName: string): Promise<void>;
smartbucketRef: SmartBucket;
name: string;
constructor(smartbucketRef: SmartBucket, bucketName: string);
/**
* Returns the underlying AWS SDK v3 S3Client for this bucket.
*
* Use this when you need to perform operations smartbucket doesn't
* wrap directly (e.g. lifecycle policies, bucket tagging, multipart
* upload control, object-lock, inventory config, etc.).
*
* The returned client is shared with the parent SmartBucket — do not
* call `.destroy()` on it.
*/
getStorageClient(): plugins.s3.S3Client;
/**
* gets the base directory of the bucket
*/
getBaseDirectory(): Promise<Directory>;
/**
* gets the trash directory
*/
getTrash(): Promise<Trash>;
getDirectoryFromPath(pathDescriptorArg: interfaces.IPathDecriptor): Promise<Directory>;
/**
* store file
*/
fastPut(optionsArg: interfaces.IPathDecriptor & {
contents: string | Buffer;
overwrite?: boolean;
}): Promise<File>;
/**
* get file
*/
fastGet(optionsArg: {
path: string;
}): Promise<Buffer>;
/**
* good when time to first byte is important
* and multiple subscribers are expected
* @param optionsArg
* @returns
*/
fastGetReplaySubject(optionsArg: {
path: string;
}): Promise<plugins.smartrx.rxjs.ReplaySubject<Buffer>>;
fastGetStream(optionsArg: {
path: string;
}, typeArg: 'webstream'): Promise<ReadableStream>;
fastGetStream(optionsArg: {
path: string;
}, typeArg: 'nodestream'): Promise<plugins.stream.Readable>;
/**
* store file as stream
*/
fastPutStream(optionsArg: {
path: string;
readableStream: plugins.stream.Readable | ReadableStream;
nativeMetadata?: {
[key: string]: string;
};
overwrite?: boolean;
}): Promise<void>;
fastCopy(optionsArg: {
sourcePath: string;
destinationPath?: string;
targetBucket?: Bucket;
nativeMetadata?: {
[key: string]: string;
};
deleteExistingNativeMetadata?: boolean;
}): Promise<void>;
/**
* Move object from one path to another within the same bucket or to another bucket
*/
fastMove(optionsArg: {
sourcePath: string;
destinationPath: string;
targetBucket?: Bucket;
overwrite?: boolean;
}): Promise<void>;
/**
* removeObject
*/
fastRemove(optionsArg: {
path: string;
}): Promise<void>;
/**
* check whether file exists
* @param optionsArg
* @returns
*/
fastExists(optionsArg: {
path: string;
}): Promise<boolean>;
/**
* deletes this bucket
*/
delete(): Promise<void>;
fastStat(pathDescriptor: interfaces.IPathDecriptor): Promise<plugins.s3.HeadObjectCommandOutput>;
isDirectory(pathDescriptor: interfaces.IPathDecriptor): Promise<boolean>;
isFile(pathDescriptor: interfaces.IPathDecriptor): Promise<boolean>;
getMagicBytes(optionsArg: {
path: string;
length: number;
}): Promise<Buffer>;
/**
* List all objects with a given prefix using async generator (memory-efficient streaming)
* @param prefix - Optional prefix to filter objects (default: '' for all objects)
* @yields Object keys one at a time
* @example
* ```ts
* for await (const key of bucket.listAllObjects('npm/')) {
* console.log(key);
* if (shouldStop) break; // Early exit supported
* }
* ```
*/
listAllObjects(prefix?: string): AsyncIterableIterator<string>;
/**
* List all objects as an RxJS Observable (for complex reactive pipelines)
* @param prefix - Optional prefix to filter objects (default: '' for all objects)
* @returns Observable that emits object keys
* @example
* ```ts
* bucket.listAllObjectsObservable('npm/')
* .pipe(
* filter(key => key.endsWith('.json')),
* take(100)
* )
* .subscribe(key => console.log(key));
* ```
*/
listAllObjectsObservable(prefix?: string): plugins.smartrx.rxjs.Observable<string>;
/**
* Create a cursor for manual pagination control
* @param prefix - Optional prefix to filter objects (default: '' for all objects)
* @param options - Cursor options (pageSize, etc.)
* @returns ListCursor instance
* @example
* ```ts
* const cursor = bucket.createCursor('npm/', { pageSize: 500 });
* while (cursor.hasMore()) {
* const { keys, done } = await cursor.next();
* console.log(`Processing ${keys.length} keys...`);
* }
* ```
*/
createCursor(prefix?: string, options?: IListCursorOptions): ListCursor;
/**
* Create a watcher for monitoring bucket changes (add/modify/delete)
* @param options - Watcher options (prefix, pollIntervalMs, etc.)
* @returns BucketWatcher instance
* @example
* ```ts
* const watcher = bucket.createWatcher({ prefix: 'uploads/', pollIntervalMs: 3000 });
* watcher.changeSubject.subscribe((change) => console.log('Change:', change));
* await watcher.start();
* // ... later
* await watcher.stop();
* ```
*/
createWatcher(options?: interfaces.IBucketWatcherOptions): BucketWatcher;
/**
* Find objects matching a glob pattern (memory-efficient)
* @param pattern - Glob pattern (e.g., "**\/*.json", "npm/packages/*\/index.json")
* @yields Matching object keys
* @example
* ```ts
* for await (const key of bucket.findByGlob('npm/packages/*\/index.json')) {
* console.log('Found package index:', key);
* }
* ```
*/
findByGlob(pattern: string): AsyncIterableIterator<string>;
/**
* List all objects and collect into an array (convenience method)
* WARNING: Loads entire result set into memory. Use listAllObjects() generator for large buckets.
* @param prefix - Optional prefix to filter objects (default: '' for all objects)
* @returns Array of all object keys
* @example
* ```ts
* const allKeys = await bucket.listAllObjectsArray('npm/');
* console.log(`Found ${allKeys.length} objects`);
* ```
*/
listAllObjectsArray(prefix?: string): Promise<string[]>;
cleanAllContents(): Promise<void>;
}