feat(bucket): Enhanced SmartBucket with trash management and metadata handling

ts/classes.directory.ts

@@ -69,7 +69,7 @@ export class Directory {
     path: string;
     createWithContents?: string | Buffer;
     getFromTrash?: boolean;
-  }): Promise<File> {
+  }): Promise<File | null> {
     const pathDescriptor = {
       directory: this,
       path: optionsArg.path,
@@ -98,6 +98,19 @@ export class Directory {
     });
   }
 
+  /**
+   * gets a file strictly
+   * @param args 
+   * @returns 
+   */
+  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;
+  }
+
   /**
    * lists all files
    */
@@ -110,7 +123,7 @@ export class Directory {
     const response = await this.bucketRef.smartbucketRef.s3Client.send(command);
     const fileArray: File[] = [];
 
-    response.Contents.forEach((item) => {
+    response.Contents?.forEach((item) => {
       if (item.Key && !item.Key.endsWith('/')) {
         const subtractedPath = item.Key.replace(this.getBasePath(), '');
         if (!subtractedPath.includes('/')) {
@@ -178,23 +191,53 @@ export class Directory {
   /**
    * gets a sub directory by name
    */
-  public async getSubDirectoryByName(dirNameArg: string): Promise<Directory> {
-    const dirNameArray = dirNameArg.split('/');
+  public async getSubDirectoryByName(dirNameArg: string, optionsArg: {
+    getEmptyDirectory?: boolean;
+    createWithInitializerFile?: boolean;
+  } = {}): Promise<Directory | null> {
+    const dirNameArray = dirNameArg.split('/').filter(str => str.trim() !== "");
 
-    const getDirectory = async (directoryArg: Directory, dirNameToSearch: string) => {
-      const directories = await directoryArg.listDirectories();
-      return directories.find((directory) => {
-        return directory.name === dirNameToSearch;
-      });
-    };
-
-    let wantedDirectory: Directory;
-    for (const dirNameToSearch of dirNameArray) {
-      const directoryToSearchIn = wantedDirectory ? wantedDirectory : this;
-      wantedDirectory = await getDirectory(directoryToSearchIn, dirNameToSearch);
+    optionsArg = {
+      getEmptyDirectory: false,
+      createWithInitializerFile: false,
+      ...optionsArg,
     }
 
-    return wantedDirectory;
+
+    const getDirectory = async (directoryArg: Directory, dirNameToSearch: string, isFinalDirectory: boolean) => {
+      const directories = await directoryArg.listDirectories();
+      let returnDirectory = directories.find((directory) => {
+        return directory.name === dirNameToSearch;
+      });
+      if (returnDirectory) {
+        return returnDirectory;
+      }
+      if (optionsArg.getEmptyDirectory || optionsArg.createWithInitializerFile) {
+        returnDirectory = new Directory(this.bucketRef, this, dirNameToSearch);
+      }
+      if (isFinalDirectory && optionsArg.createWithInitializerFile) {
+        returnDirectory?.createEmptyFile('00init.txt');
+      }
+      return returnDirectory || null;
+    };
+
+    let wantedDirectory: Directory | null = null;
+    let counter = 0; 
+    for (const dirNameToSearch of dirNameArray) {
+      counter++;
+      const directoryToSearchIn = wantedDirectory ? wantedDirectory : this;
+      wantedDirectory = await getDirectory(directoryToSearchIn, dirNameToSearch, counter === dirNameArray.length);
+    }
+
+    return wantedDirectory || null;
+  }
+
+  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;
   }
 
   /**