@lossless.org/client 0.1.0

package/dist_ts/objectstorage/classes.bucket.d.ts

@@ -0,0 +1,227 @@
+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';
+export interface IListObjectKeysPageOptions {
+    prefix?: string;
+    limit: number;
+    startAfter?: string;
+}
+export interface IListObjectKeysPageResult {
+    keys: string[];
+    nextStartAfter?: string;
+}
+/**
+ * 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;
+    /**
+     * Performs a live, side-effectful provider probe for the conditional S3
+     * semantics required by fastPutStreamExact().
+     *
+     * Probe objects and multipart uploads use unique private keys and are removed
+     * before a capability is returned. A capability becomes stale when the
+     * Bucket object, bucket name, parent SmartBucket, S3 client, or SmartBucket
+     * lifecycle generation changes.
+     */
+    probeExactUploadCapability(optionsArg?: interfaces.IExactUploadCapabilityProbeOptions): Promise<interfaces.TExactUploadCapabilityProbeResult>;
+    /**
+     * Performs a live provider probe for exact conditional deletion,
+     * version-specific deletion, delete-marker removal, and verified cleanup.
+     */
+    probeExactPathPurgeCapability(optionsArg?: interfaces.IExactPathPurgeCapabilityProbeOptions): Promise<interfaces.TExactPathPurgeCapabilityProbeResult>;
+    /**
+     * 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: interfaces.IFastGetStreamOptions, typeArg: 'webstream'): Promise<ReadableStream>;
+    fastGetStream(optionsArg: interfaces.IFastGetStreamOptions, typeArg?: 'nodestream'): Promise<plugins.stream.Readable>;
+    /**
+     * store file as stream
+     */
+    fastPutStream(optionsArg: interfaces.IFastPutStreamOptions): Promise<void>;
+    /**
+     * Creates an object from a stream while enforcing the declared byte length
+     * and create-only destination semantics.
+     *
+     * Non-empty inputs always use multipart upload and never fall back to a
+     * single streaming PutObject request. Memory is bounded by the returned
+     * multipart plan. Every source chunk must be no larger than the effective
+     * multipart part size (5 MiB by default, or requestedPartSize after protocol
+     * normalization).
+     */
+    fastPutStreamExact(optionsArg: interfaces.IFastPutStreamExactOptions): Promise<interfaces.IExactUploadResult>;
+    /**
+     * Permanently removes the exact key, including every object version and
+     * delete marker, without deleting keys that merely share its prefix.
+     */
+    purgeExactPath(optionsArg: interfaces.IExactPathPurgeOptions): Promise<interfaces.IExactPathPurgeResult>;
+    fastCopy(optionsArg: interfaces.IFastCopyOptions): 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: interfaces.IFastRemoveOptions): Promise<void>;
+    /**
+     * check whether file exists
+     * @param optionsArg
+     * @returns
+     */
+    fastExists(optionsArg: interfaces.IFastExistsOptions): Promise<boolean>;
+    /**
+     * deletes this bucket
+     */
+    delete(): Promise<void>;
+    fastStat(pathDescriptor: interfaces.IFastStatOptions): 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;
+    /**
+     * List one deletion-stable keyset page using S3 ListObjectsV2 StartAfter.
+     * This requires a general-purpose S3 provider with UTF-8 byte-ordered keys.
+     */
+    listObjectKeysPage(optionsArg: IListObjectKeysPageOptions): Promise<IListObjectKeysPageResult>;
+    /**
+     * 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>;
+}