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