BREAKING CHANGE(core): Make API strict-by-default: remove *Strict variants, throw on not-found/exists conflicts, add explicit exists() methods, update docs/tests and bump deps

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartbucket',
-  version: '3.3.10',
+  version: '4.0.0',
   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.'
 }

ts/classes.bucket.ts

@@ -14,7 +14,7 @@ import { Trash } from './classes.trash.js';
  * operate in S3 basic fashion on blobs of data.
  */
 export class Bucket {
-  public static async getBucketByName(smartbucketRef: SmartBucket, bucketNameArg: string) {
+  public static async getBucketByName(smartbucketRef: SmartBucket, bucketNameArg: string): Promise<Bucket> {
     const command = new plugins.s3.ListBucketsCommand({});
     const buckets = await smartbucketRef.s3Client.send(command);
     const foundBucket = buckets.Buckets!.find((bucket) => bucket.Name === bucketNameArg);
@@ -24,8 +24,7 @@ export class Bucket {
       console.log(`Taking this as base for new Bucket instance`);
       return new this(smartbucketRef, bucketNameArg);
     } else {
-      console.log(`did not find bucket by name: ${bucketNameArg}`);
-      return null;
+      throw new Error(`Bucket '${bucketNameArg}' not found.`);
     }
   }
 
@@ -71,7 +70,7 @@ export class Bucket {
     }
     const checkPath = await helpers.reducePathDescriptorToPath(pathDescriptorArg);
     const baseDirectory = await this.getBaseDirectory();
-    return await baseDirectory.getSubDirectoryByNameStrict(checkPath, {
+    return await baseDirectory.getSubDirectoryByName(checkPath, {
       getEmptyDirectory: true,
     });
   }
@@ -88,15 +87,16 @@ export class Bucket {
       contents: string | Buffer;
       overwrite?: boolean;
     }
-  ): Promise<File | null> {
+  ): Promise<File> {
     try {
       const reducedPath = await helpers.reducePathDescriptorToPath(optionsArg);
       const exists = await this.fastExists({ path: reducedPath });
 
       if (exists && !optionsArg.overwrite) {
-        const errorText = `Object already exists at path '${reducedPath}' in bucket '${this.name}'.`;
-        console.error(errorText);
-        return null;
+        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}'.`
@@ -129,13 +129,6 @@ export class Bucket {
     }
   }
 
-  public async fastPutStrict(...args: Parameters<Bucket['fastPut']>) {
-    const file = await this.fastPut(...args);
-    if (!file) {
-      throw new Error(`File not stored at path '${args[0].path}'`);
-    }
-    return file;
-  }
 
   /**
    * get file
@@ -259,10 +252,10 @@ export class Bucket {
       const exists = await this.fastExists({ path: optionsArg.path });
 
       if (exists && !optionsArg.overwrite) {
-        console.error(
-          `Object already exists at path '${optionsArg.path}' in bucket '${this.name}'.`
+        throw new Error(
+          `Object already exists at path '${optionsArg.path}' in bucket '${this.name}'. ` +
+          `Set overwrite:true to replace it.`
         );
-        return;
       } else if (exists && optionsArg.overwrite) {
         console.log(
           `Overwriting existing object at path '${optionsArg.path}' in bucket '${this.name}'.`
@@ -460,7 +453,7 @@ export class Bucket {
         Range: `bytes=0-${optionsArg.length - 1}`,
       });
       const response = await this.smartbucketRef.s3Client.send(command);
-      const chunks = [];
+      const chunks: Buffer[] = [];
       const stream = response.Body as any; // SdkStreamMixin includes readable stream
 
       for await (const chunk of stream) {

ts/classes.directory.ts

@@ -69,7 +69,7 @@ export class Directory {
     path: string;
     createWithContents?: string | Buffer;
     getFromTrash?: boolean;
-  }): Promise<File | null> {
+  }): Promise<File> {
     const pathDescriptor = {
       directory: this,
       path: optionsArg.path,
@@ -83,7 +83,7 @@ export class Directory {
       return trashedFile;
     }
     if (!exists && !optionsArg.createWithContents) {
-      return null;
+      throw new Error(`File not found at path '${optionsArg.path}'`);
     }
     if (!exists && optionsArg.createWithContents) {
       await File.create({
@@ -98,17 +98,26 @@ export class Directory {
     });
   }
 
+
   /**
-   * gets a file strictly
-   * @param args 
-   * @returns 
+   * Check if a file exists in this directory
    */
-  public async getFileStrict(...args: Parameters<Directory['getFile']>) {
-    const file = await this.getFile(...args);
-    if (!file) {
-      throw new Error(`File not found at path '${args[0].path}'`);
-    }
-    return file;
+  public async fileExists(optionsArg: { path: string }): Promise<boolean> {
+    const pathDescriptor = {
+      directory: this,
+      path: optionsArg.path,
+    };
+    return this.bucketRef.fastExists({
+      path: await helpers.reducePathDescriptorToPath(pathDescriptor),
+    });
+  }
+
+  /**
+   * Check if a subdirectory exists
+   */
+  public async directoryExists(dirNameArg: string): Promise<boolean> {
+    const directories = await this.listDirectories();
+    return directories.some(dir => dir.name === dirNameArg);
   }
 
   /**
@@ -206,7 +215,7 @@ export class Directory {
      * if the path is a file path, it will be treated as a file and the parent directory will be returned
      */
     couldBeFilePath?: boolean;
-  } = {}): Promise<Directory | null> {
+  } = {}): Promise<Directory> {
 
     const dirNameArray = dirNameArg.split('/').filter(str => str.trim() !== "");
 
@@ -253,16 +262,12 @@ export class Directory {
       wantedDirectory = await getDirectory(directoryToSearchIn, dirNameToSearch, counter === dirNameArray.length);
     }
 
-    return wantedDirectory || null;
+    if (!wantedDirectory) {
+      throw new Error(`Directory not found at path '${dirNameArg}'`);
+    }
+    return wantedDirectory;
   }
 
-  public async getSubDirectoryByNameStrict(...args: Parameters<Directory['getSubDirectoryByName']>) {
-    const directory = await this.getSubDirectoryByName(...args);
-    if (!directory) {
-      throw new Error(`Directory not found at path '${args[0]}'`);
-    }
-    return directory;
-  }
 
   /**
    * moves the directory
@@ -360,7 +365,7 @@ export class Directory {
      */
     mode?: 'permanent' | 'trash';
   }) {
-    const file = await this.getFileStrict({
+    const file = await this.getFile({
       path: optionsArg.path,
     });
     await file.delete({

ts/classes.file.ts

@@ -245,7 +245,7 @@ export class File {
 
     // lets update references of this
     const baseDirectory = await this.parentDirectoryRef.bucketRef.getBaseDirectory();
-    this.parentDirectoryRef = await baseDirectory.getSubDirectoryByNameStrict(
+    this.parentDirectoryRef = await baseDirectory.getSubDirectoryByName(
       await helpers.reducePathDescriptorToPath(pathDescriptorArg),
       {
         couldBeFilePath: true,

ts/classes.metadata.ts

@@ -17,7 +17,7 @@ export class MetaData {
     metaData.fileRef = optionsArg.file;
 
     // lets find the existing metadata file
-    metaData.metadataFile = await metaData.fileRef.parentDirectoryRef.getFileStrict({
+    metaData.metadataFile = await metaData.fileRef.parentDirectoryRef.getFile({
       path: metaData.fileRef.name + '.metadata',
       createWithContents: '{}',
     });

ts/classes.smartbucket.ts

@@ -42,11 +42,12 @@ export class SmartBucket {
     return Bucket.getBucketByName(this, bucketNameArg);
   }
 
-  public async getBucketByNameStrict(...args: Parameters<SmartBucket['getBucketByName']>) {
-    const bucket = await this.getBucketByName(...args);
-    if (!bucket) {
-      throw new Error(`Bucket ${args[0]} does not exist.`);
-    }
-    return bucket;
+  /**
+   * Check if a bucket exists
+   */
+  public async bucketExists(bucketNameArg: string): Promise<boolean> {
+    const command = new plugins.s3.ListBucketsCommand({});
+    const buckets = await this.s3Client.send(command);
+    return buckets.Buckets?.some(bucket => bucket.Name === bucketNameArg) ?? false;
   }
 }

ts/classes.trash.ts

@@ -21,7 +21,7 @@ export class Trash {
     const trashDir = await this.getTrashDir();
     const originalPath = await helpers.reducePathDescriptorToPath(pathDescriptor);
     const trashKey = await this.getTrashKeyByOriginalBasePath(originalPath);
-    return trashDir.getFileStrict({ path: trashKey });
+    return trashDir.getFile({ path: trashKey });
   }
 
   public async getTrashKeyByOriginalBasePath (originalPath: string): Promise<string> {