@lossless.org/client 0.1.0

package/ts/objectstorage/classes.bucket.ts

@@ -0,0 +1,1114 @@
+// classes.bucket.ts
+
+import * as plugins from './plugins.js';
+import * as helpers from './helpers.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';
+import {
+  fastPutStreamExact as fastPutStreamExactOperation,
+  probeExactUploadCapability as probeExactUploadCapabilityOperation,
+} from './internal.exactupload.operations.js';
+import {
+  probeExactPathPurgeCapability as probeExactPathPurgeCapabilityOperation,
+  purgeExactPath as purgeExactPathOperation,
+} from './internal.exactpathpurge.operations.js';
+import { beginBasicBucketOperation } from './internal.exactupload.capability.js';
+
+export interface IListObjectKeysPageOptions {
+  prefix?: string;
+  limit: number;
+  startAfter?: string;
+}
+
+export interface IListObjectKeysPageResult {
+  keys: string[];
+  nextStartAfter?: string;
+}
+
+const compareUtf8ObjectKeys = (leftArg: string, rightArg: string): number =>
+  Buffer.compare(Buffer.from(leftArg, 'utf8'), Buffer.from(rightArg, 'utf8'));
+
+const destroyReadableAndWaitForSettlement = async (
+  readableArg: plugins.stream.Readable,
+): Promise<void> => {
+  let removeFinishedListeners = (): void => {};
+  const settlement = new Promise<boolean>((resolveArg) => {
+    removeFinishedListeners = plugins.stream.finished(
+      readableArg,
+      { readable: true, writable: false },
+      () => resolveArg(true),
+    );
+  });
+  readableArg.destroy();
+  let settlementDeadline: ReturnType<typeof setTimeout> | undefined;
+  let settled = false;
+  try {
+    settled = await Promise.race([
+      settlement,
+      new Promise<boolean>((resolveArg) => {
+        settlementDeadline = setTimeout(() => resolveArg(false), 5_000);
+      }),
+    ]);
+  } finally {
+    if (settlementDeadline) {
+      clearTimeout(settlementDeadline);
+    }
+    removeFinishedListeners();
+  }
+  if (!settled && !readableArg.closed) {
+    const onLateError = (): void => {
+      readableArg.removeListener('close', onLateClose);
+    };
+    const onLateClose = (): void => {
+      readableArg.removeListener('error', onLateError);
+    };
+    readableArg.once('error', onLateError);
+    readableArg.once('close', onLateClose);
+  }
+};
+
+/**
+ * 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 class Bucket {
+  public static async getBucketByName(smartbucketRef: SmartBucket, bucketNameArg: string): Promise<Bucket> {
+    const command = new plugins.s3.ListBucketsCommand({});
+    const buckets = await smartbucketRef.storageClient.send(command);
+    const foundBucket = buckets.Buckets!.find((bucket) => bucket.Name === bucketNameArg);
+
+    if (foundBucket) {
+      console.log(`bucket with name ${bucketNameArg} exists.`);
+      console.log(`Taking this as base for new Bucket instance`);
+      return new this(smartbucketRef, bucketNameArg);
+    } else {
+      throw new Error(`Bucket '${bucketNameArg}' not found.`);
+    }
+  }
+
+  public static async createBucketByName(smartbucketRef: SmartBucket, bucketName: string) {
+    const command = new plugins.s3.CreateBucketCommand({ Bucket: bucketName });
+    await smartbucketRef.storageClient.send(command);
+    return new Bucket(smartbucketRef, bucketName);
+  }
+
+  public static async removeBucketByName(smartbucketRef: SmartBucket, bucketName: string) {
+    const command = new plugins.s3.DeleteBucketCommand({ Bucket: bucketName });
+    await smartbucketRef.storageClient.send(command);
+  }
+
+  public smartbucketRef: SmartBucket;
+  public name: string;
+
+  constructor(smartbucketRef: SmartBucket, bucketName: string) {
+    this.smartbucketRef = smartbucketRef;
+    this.name = bucketName;
+  }
+
+  /**
+   * 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.
+   */
+  public getStorageClient(): plugins.s3.S3Client {
+    return this.smartbucketRef.storageClient;
+  }
+
+  /**
+   * 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.
+   */
+  public probeExactUploadCapability(
+    optionsArg: interfaces.IExactUploadCapabilityProbeOptions = {},
+  ): Promise<interfaces.TExactUploadCapabilityProbeResult> {
+    return probeExactUploadCapabilityOperation(this, optionsArg);
+  }
+
+  /**
+   * Performs a live provider probe for exact conditional deletion,
+   * version-specific deletion, delete-marker removal, and verified cleanup.
+   */
+  public probeExactPathPurgeCapability(
+    optionsArg: interfaces.IExactPathPurgeCapabilityProbeOptions = {},
+  ): Promise<interfaces.TExactPathPurgeCapabilityProbeResult> {
+    return probeExactPathPurgeCapabilityOperation(this, optionsArg);
+  }
+
+  /**
+   * gets the base directory of the bucket
+   */
+  public async getBaseDirectory(): Promise<Directory> {
+    return new Directory(this, null!, '');
+  }
+
+  /**
+   * gets the trash directory
+   */
+  public async getTrash(): Promise<Trash> {
+    const trash = new Trash(this);
+    return trash;
+  }
+
+  public async getDirectoryFromPath(
+    pathDescriptorArg: interfaces.IPathDecriptor
+  ): Promise<Directory> {
+    if (!pathDescriptorArg.path && !pathDescriptorArg.directory) {
+      return this.getBaseDirectory();
+    }
+    const checkPath = await helpers.reducePathDescriptorToPath(pathDescriptorArg);
+    const baseDirectory = await this.getBaseDirectory();
+    return await baseDirectory.getSubDirectoryByName(checkPath, {
+      getEmptyDirectory: true,
+    });
+  }
+
+  // ===============
+  // Fast Operations
+  // ===============
+
+  /**
+   * store file
+   */
+  public async fastPut(
+    optionsArg: interfaces.IPathDecriptor & {
+      contents: string | Buffer;
+      overwrite?: boolean;
+    }
+  ): Promise<File> {
+    try {
+      const reducedPath = await helpers.reducePathDescriptorToPath(optionsArg);
+      const exists = await this.fastExists({ path: reducedPath });
+
+      if (exists && !optionsArg.overwrite) {
+        throw new Error(
+          `Object already exists at path '${reducedPath}' in bucket '${this.name}'. ` +
+          `Set overwrite:true to replace it.`
+        );
+      } else if (exists && optionsArg.overwrite) {
+        console.log(
+          `Overwriting existing object at path '${reducedPath}' in bucket '${this.name}'.`
+        );
+      } else {
+        console.log(`Creating new object at path '${reducedPath}' in bucket '${this.name}'.`);
+      }
+
+      const command = new plugins.s3.PutObjectCommand({
+        Bucket: this.name,
+        Key: reducedPath,
+        Body: optionsArg.contents,
+      });
+      await this.smartbucketRef.storageClient.send(command);
+
+      console.log(`Object '${reducedPath}' has been successfully stored in bucket '${this.name}'.`);
+      const parsedPath = plugins.path.parse(reducedPath);
+      return new File({
+        directoryRefArg: await this.getDirectoryFromPath({
+          path: parsedPath.dir,
+        }),
+        fileName: parsedPath.base,
+      });
+    } catch (error) {
+      console.error(
+        `Error storing object at path '${optionsArg.path}' in bucket '${this.name}':`,
+        error
+      );
+      throw error;
+    }
+  }
+
+
+  /**
+   * get file
+   */
+  public async fastGet(optionsArg: { path: string }): Promise<Buffer> {
+    const source = await this.fastGetStream(optionsArg);
+    const chunks: Buffer[] = [];
+    try {
+      for await (const chunk of source) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      return Buffer.concat(chunks);
+    } finally { source.destroy(); }
+  }
+
+  /**
+   * good when time to first byte is important
+   * and multiple subscribers are expected
+   * @param optionsArg
+   * @returns
+   */
+  public async fastGetReplaySubject(optionsArg: {
+    path: string;
+  }): Promise<plugins.smartrx.rxjs.ReplaySubject<Buffer>> {
+    const command = new plugins.s3.GetObjectCommand({
+      Bucket: this.name,
+      Key: optionsArg.path,
+    });
+    const response = await this.smartbucketRef.storageClient.send(command);
+    const replaySubject = new plugins.smartrx.rxjs.ReplaySubject<Buffer>();
+
+    // Convert the stream to a format that supports piping
+    const stream = response.Body as any; // SdkStreamMixin includes readable stream
+    if (typeof stream.pipe === 'function') {
+      const duplexStream = new plugins.smartstream.SmartDuplex<Buffer, void>({
+        writeFunction: async (chunk) => {
+          replaySubject.next(chunk);
+          return;
+        },
+        finalFunction: async (cb) => {
+          replaySubject.complete();
+          return;
+        },
+      });
+
+      stream.pipe(duplexStream);
+    }
+
+    return replaySubject;
+  }
+
+  public fastGetStream(
+    optionsArg: interfaces.IFastGetStreamOptions,
+    typeArg: 'webstream'
+  ): Promise<ReadableStream>;
+  public async fastGetStream(
+    optionsArg: interfaces.IFastGetStreamOptions,
+    typeArg?: 'nodestream'
+  ): Promise<plugins.stream.Readable>;
+
+  public async fastGetStream(
+    optionsArg: interfaces.IFastGetStreamOptions,
+    typeArg: 'webstream' | 'nodestream' = 'nodestream'
+  ): Promise<ReadableStream | plugins.stream.Readable> {
+    const operation = beginBasicBucketOperation(this, optionsArg.signal);
+    const disposeBody = async (responseBodyArg: unknown): Promise<void> => {
+      try {
+        if (responseBodyArg instanceof plugins.stream.Readable) {
+          await destroyReadableAndWaitForSettlement(responseBodyArg);
+        } else if (
+          typeof ReadableStream !== 'undefined'
+          && responseBodyArg instanceof ReadableStream
+        ) {
+          await responseBodyArg.cancel();
+        } else if (
+          typeof responseBodyArg === 'object'
+          && responseBodyArg !== null
+          && typeof (responseBodyArg as { destroy?: unknown }).destroy === 'function'
+        ) {
+          (responseBodyArg as { destroy: () => void }).destroy();
+        } else if (
+          typeof responseBodyArg === 'object'
+          && responseBodyArg !== null
+          && typeof (responseBodyArg as { cancel?: unknown }).cancel === 'function'
+        ) {
+          await (responseBodyArg as { cancel: () => Promise<void> }).cancel();
+        }
+      } catch {
+        // Preserve the primary response-body or conversion failure.
+      }
+    };
+    let response: plugins.s3.GetObjectCommandOutput;
+    try {
+      response = await operation.runProvider(
+        () => operation.client.send(
+          new plugins.s3.GetObjectCommand({
+            Bucket: operation.bucketName,
+            Key: optionsArg.path,
+          }),
+          { abortSignal: operation.signal },
+        ),
+        {
+          disposeLateResult: async (lateResponseArg) => {
+            await disposeBody(lateResponseArg.Body);
+          },
+        },
+      );
+    } catch (error) {
+      operation.finish();
+      throw error;
+    }
+    const responseBody = response.Body as unknown;
+    const disposeResponseBody = async (): Promise<void> => {
+      await disposeBody(responseBody);
+    };
+    let sourceStream: plugins.stream.Readable | null = null;
+    try {
+      sourceStream = responseBody instanceof plugins.stream.Readable
+        ? responseBody
+        : (
+            typeof ReadableStream !== 'undefined'
+            && responseBody instanceof ReadableStream
+          )
+          ? plugins.stream.Readable.fromWeb(responseBody as never)
+          : null;
+    } catch (error) {
+      await disposeResponseBody();
+      operation.finish();
+      throw error;
+    }
+    if (!sourceStream) {
+      await disposeResponseBody();
+      operation.finish();
+      throw new Error('S3 GetObject returned no supported response stream.');
+    }
+
+    const outputStream = new plugins.stream.PassThrough();
+    const abortError = (): Error => {
+      if (operation.signal.reason instanceof Error) {
+        return operation.signal.reason;
+      }
+      const error = new Error('S3 object download was aborted.');
+      error.name = 'AbortError';
+      return error;
+    };
+    let sourceEnded = false;
+    let forwardingCleanedUp = false;
+    let sourceErrorGuardReleased = false;
+    const preventUnhandledSourceError = (): void => {};
+    const preventUnhandledOutputError = (): void => {};
+    const cleanupForwarding = (): void => {
+      if (forwardingCleanedUp) {
+        return;
+      }
+      forwardingCleanedUp = true;
+      operation.signal.removeEventListener('abort', onAbort);
+      sourceStream.removeListener('error', onSourceError);
+      sourceStream.removeListener('end', onSourceEnd);
+      sourceStream.removeListener('close', onSourceClose);
+      outputStream.removeListener('error', preventUnhandledOutputError);
+      outputStream.removeListener('close', onOutputClose);
+    };
+    const releaseSourceErrorGuard = (): void => {
+      if (sourceErrorGuardReleased) {
+        return;
+      }
+      sourceErrorGuardReleased = true;
+      sourceStream.removeListener('error', preventUnhandledSourceError);
+    };
+    let sourceSettlement: Promise<void> | undefined;
+    const settleSource = (): Promise<void> => {
+      sourceSettlement ??= destroyReadableAndWaitForSettlement(sourceStream);
+      return sourceSettlement;
+    };
+    const finishAfterSourceSettlement = async (): Promise<void> => {
+      await settleSource();
+      releaseSourceErrorGuard();
+      operation.finish();
+    };
+    const onAbort = (): void => {
+      const error = abortError();
+      outputStream.destroy(error);
+      void settleSource();
+    };
+    const onSourceError = (errorArg: Error): void => {
+      outputStream.destroy(errorArg);
+    };
+    const onSourceEnd = (): void => {
+      sourceEnded = true;
+    };
+    const onSourceClose = (): void => {
+      if (!sourceEnded && !outputStream.destroyed) {
+        outputStream.destroy(
+          new Error('S3 object download stream closed before completion.'),
+        );
+      }
+    };
+    const onOutputClose = (): void => {
+      cleanupForwarding();
+      if (sourceStream.closed) {
+        releaseSourceErrorGuard();
+        operation.finish();
+      } else {
+        void finishAfterSourceSettlement();
+      }
+    };
+
+    sourceStream.on('error', preventUnhandledSourceError);
+    sourceStream.once('error', onSourceError);
+    sourceStream.once('end', onSourceEnd);
+    sourceStream.once('close', onSourceClose);
+    outputStream.on('error', preventUnhandledOutputError);
+    outputStream.once('close', onOutputClose);
+    operation.signal.addEventListener('abort', onAbort, { once: true });
+
+    if (sourceStream.closed) {
+      sourceEnded = sourceStream.readableEnded;
+      onSourceClose();
+    }
+
+    if (operation.signal.aborted) {
+      const error = abortError();
+      cleanupForwarding();
+      outputStream.destroy();
+      await settleSource();
+      releaseSourceErrorGuard();
+      operation.finish();
+      throw error;
+    }
+
+    let result: ReadableStream | plugins.stream.Readable;
+    try {
+      if (typeArg === 'nodestream') {
+        result = outputStream;
+      } else if (typeArg === 'webstream') {
+        result = plugins.stream.Readable.toWeb(outputStream) as ReadableStream;
+      } else {
+        throw new Error('unknown typeArg');
+      }
+      sourceStream.pipe(outputStream);
+    } catch (error) {
+      cleanupForwarding();
+      outputStream.destroy();
+      await settleSource();
+      releaseSourceErrorGuard();
+      operation.finish();
+      throw error;
+    }
+    return result;
+  }
+
+  /**
+   * store file as stream
+   */
+  public async fastPutStream(
+    optionsArg: interfaces.IFastPutStreamOptions,
+  ): Promise<void> {
+    if (
+      optionsArg.contentLength !== undefined
+      && (
+        !Number.isSafeInteger(optionsArg.contentLength)
+        || optionsArg.contentLength < 0
+      )
+    ) {
+      throw new Error('contentLength must be a non-negative safe integer');
+    }
+    const operation = beginBasicBucketOperation(this, optionsArg.signal);
+    let uploadStream: plugins.stream.Readable | undefined;
+    let sourceOwnershipStarted = false;
+    const disposeSource = async (): Promise<void> => {
+      if (!uploadStream) {
+        if (optionsArg.readableStream instanceof plugins.stream.Readable) {
+          uploadStream = optionsArg.readableStream;
+        } else {
+          const cancellation = optionsArg.readableStream.cancel().catch(() => undefined);
+          let cancellationDeadline: ReturnType<typeof setTimeout> | undefined;
+          try {
+            await Promise.race([
+              cancellation,
+              new Promise<void>((resolveCancellationArg) => {
+                cancellationDeadline = setTimeout(resolveCancellationArg, 5_000);
+              }),
+            ]);
+          } finally {
+            if (cancellationDeadline) {
+              clearTimeout(cancellationDeadline);
+            }
+          }
+          return;
+        }
+      }
+      await destroyReadableAndWaitForSettlement(uploadStream);
+    };
+    let putDispatched = false;
+    try {
+      let exists: boolean;
+      try {
+        await operation.runProvider(() => operation.client.send(
+          new plugins.s3.HeadObjectCommand({
+            Bucket: operation.bucketName,
+            Key: optionsArg.path,
+          }),
+          { abortSignal: operation.signal },
+        ));
+        exists = true;
+      } catch (error: any) {
+        try {
+          operation.assertCurrent();
+        } catch (abortError) {
+          throw abortError;
+        }
+        if (error?.name === 'NotFound') {
+          exists = false;
+        } else {
+          throw error;
+        }
+      }
+
+      if (exists && !optionsArg.overwrite) {
+        throw new Error(
+          `Object already exists at path '${optionsArg.path}' in bucket '${this.name}'. ` +
+          `Set overwrite:true to replace it.`
+        );
+      } else if (exists && optionsArg.overwrite) {
+        console.log(
+          `Overwriting existing object at path '${optionsArg.path}' in bucket '${this.name}'.`
+        );
+      } else {
+        console.log(`Creating new object at path '${optionsArg.path}' in bucket '${this.name}'.`);
+      }
+
+      sourceOwnershipStarted = true;
+      uploadStream = optionsArg.readableStream instanceof plugins.stream.Readable
+        ? optionsArg.readableStream
+        : plugins.stream.Readable.fromWeb(optionsArg.readableStream as never);
+      const command = new plugins.s3.PutObjectCommand({
+        Bucket: operation.bucketName,
+        Key: optionsArg.path,
+        Body: uploadStream,
+        ContentLength: optionsArg.contentLength,
+        Metadata: optionsArg.nativeMetadata,
+      });
+      putDispatched = true;
+      await operation.runProvider(
+        () => operation.client.send(command, { abortSignal: operation.signal }),
+      );
+
+      console.log(
+        `Object '${optionsArg.path}' has been successfully stored in bucket '${this.name}'.`
+      );
+    } catch (error) {
+      if (sourceOwnershipStarted || putDispatched || operation.signal.aborted) {
+        await disposeSource();
+      }
+      console.error(
+        `Error storing object at path '${optionsArg.path}' in bucket '${this.name}':`,
+        error
+      );
+      throw error;
+    } finally {
+      operation.finish();
+    }
+  }
+
+  /**
+   * 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).
+   */
+  public fastPutStreamExact(
+    optionsArg: interfaces.IFastPutStreamExactOptions,
+  ): Promise<interfaces.IExactUploadResult> {
+    return fastPutStreamExactOperation(this, optionsArg);
+  }
+
+  /**
+   * Permanently removes the exact key, including every object version and
+   * delete marker, without deleting keys that merely share its prefix.
+   */
+  public purgeExactPath(
+    optionsArg: interfaces.IExactPathPurgeOptions,
+  ): Promise<interfaces.IExactPathPurgeResult> {
+    return purgeExactPathOperation(this, optionsArg);
+  }
+
+  public async fastCopy(optionsArg: interfaces.IFastCopyOptions): Promise<void> {
+    const operation = beginBasicBucketOperation(this, optionsArg.signal);
+    try {
+      const targetBucketName = optionsArg.targetBucket ? optionsArg.targetBucket.name : this.name;
+
+      // Retrieve current object information to use in copy conditions
+      const currentObjInfo = await operation.runProvider(
+        () => operation.client.send(new plugins.s3.HeadObjectCommand({
+          Bucket: operation.bucketName,
+          Key: optionsArg.sourcePath,
+        }), { abortSignal: operation.signal }),
+      );
+
+      // Prepare new metadata
+      const newNativeMetadata = {
+        ...(optionsArg.deleteExistingNativeMetadata ? {} : currentObjInfo.Metadata),
+        ...optionsArg.nativeMetadata,
+      };
+
+      // Define the copy operation
+      const copySource = `${operation.bucketName}/${optionsArg.sourcePath}`;
+      const command = new plugins.s3.CopyObjectCommand({
+        Bucket: targetBucketName,
+        CopySource: copySource,
+        Key: optionsArg.destinationPath || optionsArg.sourcePath,
+        Metadata: newNativeMetadata,
+        MetadataDirective: optionsArg.deleteExistingNativeMetadata ? 'REPLACE' : 'COPY',
+      });
+      await operation.runProvider(
+        () => operation.client.send(command, { abortSignal: operation.signal }),
+      );
+    } catch (err) {
+      console.error('Error updating metadata:', err);
+      throw err; // rethrow to allow caller to handle
+    } finally {
+      operation.finish();
+    }
+  }
+
+  /**
+   * Move object from one path to another within the same bucket or to another bucket
+   */
+  public async fastMove(optionsArg: {
+    sourcePath: string;
+    destinationPath: string;
+    targetBucket?: Bucket;
+    overwrite?: boolean;
+  }): Promise<void> {
+    try {
+      const destinationBucket = optionsArg.targetBucket || this;
+      const exists = await destinationBucket.fastExists({
+        path: optionsArg.destinationPath,
+      });
+
+      if (exists && !optionsArg.overwrite) {
+        console.error(
+          `Object already exists at destination path '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
+        );
+        return;
+      } else if (exists && optionsArg.overwrite) {
+        console.log(
+          `Overwriting existing object at destination path '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
+        );
+      } else {
+        console.log(
+          `Moving object to path '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
+        );
+      }
+
+      await this.fastCopy(optionsArg);
+      await this.fastRemove({ path: optionsArg.sourcePath });
+
+      console.log(
+        `Object '${optionsArg.sourcePath}' has been successfully moved to '${optionsArg.destinationPath}' in bucket '${destinationBucket.name}'.`
+      );
+    } catch (error) {
+      console.error(
+        `Error moving object from '${optionsArg.sourcePath}' to '${optionsArg.destinationPath}':`,
+        error
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * removeObject
+   */
+  public async fastRemove(optionsArg: interfaces.IFastRemoveOptions) {
+    const operation = beginBasicBucketOperation(this, optionsArg.signal);
+    const command = new plugins.s3.DeleteObjectCommand({
+      Bucket: operation.bucketName,
+      Key: optionsArg.path,
+    });
+    try {
+      await operation.runProvider(
+        () => operation.client.send(command, { abortSignal: operation.signal }),
+      );
+    } finally {
+      operation.finish();
+    }
+  }
+
+  /**
+   * check whether file exists
+   * @param optionsArg
+   * @returns
+   */
+  public async fastExists(optionsArg: interfaces.IFastExistsOptions): Promise<boolean> {
+    const operation = beginBasicBucketOperation(this, optionsArg.signal);
+    try {
+      const command = new plugins.s3.HeadObjectCommand({
+        Bucket: operation.bucketName,
+        Key: optionsArg.path,
+      });
+      await operation.runProvider(
+        () => operation.client.send(command, { abortSignal: operation.signal }),
+      );
+      console.log(`Object '${optionsArg.path}' exists in bucket '${this.name}'.`);
+      return true;
+    } catch (error: any) {
+      try {
+        operation.assertCurrent();
+      } catch (abortError) {
+        throw abortError;
+      }
+      if (error?.name === 'NotFound') {
+        console.log(`Object '${optionsArg.path}' does not exist in bucket '${this.name}'.`);
+        return false;
+      } else {
+        console.error('Error checking object existence:', error);
+        throw error; // Rethrow if it's not a NotFound error to handle unexpected issues
+      }
+    } finally {
+      operation.finish();
+    }
+  }
+
+  /**
+   * deletes this bucket
+   */
+  public async delete() {
+    await this.smartbucketRef.storageClient.send(
+      new plugins.s3.DeleteBucketCommand({ Bucket: this.name })
+    );
+  }
+
+  public async fastStat(
+    pathDescriptor: interfaces.IFastStatOptions,
+  ) {
+    const operation = beginBasicBucketOperation(this, pathDescriptor.signal);
+    try {
+      operation.assertCurrent();
+      const checkPath = await helpers.reducePathDescriptorToPath(pathDescriptor);
+      operation.assertCurrent();
+      const command = new plugins.s3.HeadObjectCommand({
+        Bucket: operation.bucketName,
+        Key: checkPath,
+      });
+      return await operation.runProvider(
+        () => operation.client.send(command, { abortSignal: operation.signal }),
+      );
+    } finally {
+      operation.finish();
+    }
+  }
+
+  public async isDirectory(pathDescriptor: interfaces.IPathDecriptor): Promise<boolean> {
+    const checkPath = await helpers.reducePathDescriptorToPath(pathDescriptor);
+    const command = new plugins.s3.ListObjectsV2Command({
+      Bucket: this.name,
+      Prefix: checkPath,
+      Delimiter: '/',
+    });
+    const { CommonPrefixes } = await this.smartbucketRef.storageClient.send(command);
+    return !!CommonPrefixes && CommonPrefixes.length > 0;
+  }
+
+  public async isFile(pathDescriptor: interfaces.IPathDecriptor): Promise<boolean> {
+    const checkPath = await helpers.reducePathDescriptorToPath(pathDescriptor);
+    const command = new plugins.s3.ListObjectsV2Command({
+      Bucket: this.name,
+      Prefix: checkPath,
+      Delimiter: '/',
+    });
+    const { Contents } = await this.smartbucketRef.storageClient.send(command);
+    return !!Contents && Contents.length > 0;
+  }
+
+  public async getMagicBytes(optionsArg: { path: string; length: number }): Promise<Buffer> {
+    try {
+      const command = new plugins.s3.GetObjectCommand({
+        Bucket: this.name,
+        Key: optionsArg.path,
+        Range: `bytes=0-${optionsArg.length - 1}`,
+      });
+      const response = await this.smartbucketRef.storageClient.send(command);
+      const chunks: Buffer[] = [];
+      const stream = response.Body as any; // SdkStreamMixin includes readable stream
+
+      for await (const chunk of stream) {
+        chunks.push(chunk);
+      }
+      return Buffer.concat(chunks);
+    } catch (error) {
+      console.error(
+        `Error retrieving magic bytes from object at path '${optionsArg.path}' in bucket '${this.name}':`,
+        error
+      );
+      throw error;
+    }
+  }
+
+  // ==========================================
+  // Memory-Efficient Listing Methods (Phase 1)
+  // ==========================================
+
+  /**
+   * 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
+   * }
+   * ```
+   */
+  public async *listAllObjects(prefix: string = ''): AsyncIterableIterator<string> {
+    let continuationToken: string | undefined;
+
+    do {
+      const command = new plugins.s3.ListObjectsV2Command({
+        Bucket: this.name,
+        Prefix: prefix,
+        ContinuationToken: continuationToken,
+      });
+
+      const response = await this.smartbucketRef.storageClient.send(command);
+
+      for (const obj of response.Contents || []) {
+        if (obj.Key) yield obj.Key;
+      }
+
+      continuationToken = response.NextContinuationToken;
+    } while (continuationToken);
+  }
+
+  /**
+   * 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));
+   * ```
+   */
+  public listAllObjectsObservable(prefix: string = ''): plugins.smartrx.rxjs.Observable<string> {
+    return new plugins.smartrx.rxjs.Observable<string>((subscriber) => {
+      const fetchPage = async (token?: string) => {
+        try {
+          const command = new plugins.s3.ListObjectsV2Command({
+            Bucket: this.name,
+            Prefix: prefix,
+            ContinuationToken: token,
+          });
+
+          const response = await this.smartbucketRef.storageClient.send(command);
+
+          for (const obj of response.Contents || []) {
+            if (obj.Key) subscriber.next(obj.Key);
+          }
+
+          if (response.NextContinuationToken) {
+            await fetchPage(response.NextContinuationToken);
+          } else {
+            subscriber.complete();
+          }
+        } catch (error) {
+          subscriber.error(error);
+        }
+      };
+
+      fetchPage();
+    });
+  }
+
+  /**
+   * 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...`);
+   * }
+   * ```
+   */
+  public createCursor(prefix: string = '', options?: IListCursorOptions): ListCursor {
+    return new ListCursor(this, prefix, options);
+  }
+
+  /**
+   * List one deletion-stable keyset page using S3 ListObjectsV2 StartAfter.
+   * This requires a general-purpose S3 provider with UTF-8 byte-ordered keys.
+   */
+  public async listObjectKeysPage(
+    optionsArg: IListObjectKeysPageOptions,
+  ): Promise<IListObjectKeysPageResult> {
+    if (!optionsArg || typeof optionsArg !== 'object' || Array.isArray(optionsArg)) {
+      throw new TypeError('Object key page options must be a plain object');
+    }
+    const prefix = optionsArg.prefix ?? '';
+    if (typeof prefix !== 'string') {
+      throw new TypeError('Object key page prefix must be a string');
+    }
+    if (!Number.isInteger(optionsArg.limit) || optionsArg.limit < 1 || optionsArg.limit > 1_000) {
+      throw new Error('Object key page limit must be an integer from 1 to 1000');
+    }
+    if (
+      optionsArg.startAfter !== undefined
+      && (
+        typeof optionsArg.startAfter !== 'string'
+        || optionsArg.startAfter.length === 0
+        || !optionsArg.startAfter.startsWith(prefix)
+      )
+    ) {
+      throw new Error('Object key page startAfter must be a non-empty key under the prefix');
+    }
+
+    const response = await this.smartbucketRef.storageClient.send(
+      new plugins.s3.ListObjectsV2Command({
+        Bucket: this.name,
+        Prefix: prefix,
+        MaxKeys: optionsArg.limit,
+        ...(optionsArg.startAfter ? { StartAfter: optionsArg.startAfter } : {}),
+      }),
+    );
+    if (typeof response.IsTruncated !== 'boolean') {
+      throw new Error('Object storage returned an invalid key page truncation flag');
+    }
+    if (response.Contents !== undefined && !Array.isArray(response.Contents)) {
+      throw new Error('Object storage returned invalid key page contents');
+    }
+
+    const keys = (response.Contents ?? []).map((entry) => {
+      if (!entry || typeof entry.Key !== 'string') {
+        throw new Error('Object storage returned a key page entry without a string key');
+      }
+      return entry.Key;
+    });
+    if (keys.length > optionsArg.limit) {
+      throw new Error('Object storage returned more keys than the requested page limit');
+    }
+    if (new Set(keys).size !== keys.length) {
+      throw new Error('Object storage returned duplicate keys in one page');
+    }
+
+    let previousKey = optionsArg.startAfter;
+    for (const key of keys) {
+      if (!key.startsWith(prefix)) {
+        throw new Error('Object storage returned a key outside the requested prefix');
+      }
+      if (previousKey !== undefined && compareUtf8ObjectKeys(key, previousKey) <= 0) {
+        throw new Error('Object storage returned keys outside strict UTF-8 byte order');
+      }
+      previousKey = key;
+    }
+    if (response.IsTruncated && keys.length === 0) {
+      throw new Error('Object storage returned an empty truncated key page');
+    }
+
+    return {
+      keys,
+      ...(response.IsTruncated ? { nextStartAfter: keys[keys.length - 1] } : {}),
+    };
+  }
+
+  /**
+   * 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();
+   * ```
+   */
+  public createWatcher(options?: interfaces.IBucketWatcherOptions): BucketWatcher {
+    return new BucketWatcher(this, options);
+  }
+
+  // ==========================================
+  // High-Level Listing Helpers (Phase 2)
+  // ==========================================
+
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  public async *findByGlob(pattern: string): AsyncIterableIterator<string> {
+    const matcher = new plugins.Minimatch(pattern);
+    for await (const key of this.listAllObjects('')) {
+      if (matcher.match(key)) yield key;
+    }
+  }
+
+  /**
+   * 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`);
+   * ```
+   */
+  public async listAllObjectsArray(prefix: string = ''): Promise<string[]> {
+    const keys: string[] = [];
+    for await (const key of this.listAllObjects(prefix)) {
+      keys.push(key);
+    }
+    return keys;
+  }
+
+  public async cleanAllContents(): Promise<void> {
+    try {
+      // Define the command type explicitly
+      const listCommandInput: plugins.s3.ListObjectsV2CommandInput = {
+        Bucket: this.name,
+      };
+  
+      let isTruncated = true;
+      let continuationToken: string | undefined = undefined;
+  
+      while (isTruncated) {
+        // Add the continuation token to the input if present
+        const listCommand = new plugins.s3.ListObjectsV2Command({
+          ...listCommandInput,
+          ContinuationToken: continuationToken,
+        });
+  
+        // Explicitly type the response
+        const response: plugins.s3.ListObjectsV2Output =
+          await this.smartbucketRef.storageClient.send(listCommand);
+        
+        console.log(`Cleaning contents of bucket '${this.name}': Now deleting ${response.Contents?.length} items...`);
+
+        if (response.Contents && response.Contents.length > 0) {
+          // Delete objects in batches, mapping each item to { Key: string }
+          const deleteCommand = new plugins.s3.DeleteObjectsCommand({
+            Bucket: this.name,
+            Delete: {
+              Objects: response.Contents.map((item) => ({ Key: item.Key! })),
+              Quiet: true,
+            },
+          });
+  
+          await this.smartbucketRef.storageClient.send(deleteCommand);
+        }
+  
+        // Update continuation token and truncation status
+        isTruncated = response.IsTruncated || false;
+        continuationToken = response.NextContinuationToken;
+      }
+  
+      console.log(`All contents in bucket '${this.name}' have been deleted.`);
+    } catch (error) {
+      console.error(`Error cleaning contents of bucket '${this.name}':`, error);
+      throw error;
+    }
+  }
+}