@engineers/gcloud-storage 0.0.8-temp → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Dibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# @engineers/gcloud-storage
+
+google cloud storage
+
+## install
+
+install the package and it's peer dependencies:
+
+<!-- todo: peerDependencies.toString() -->
+
+```
+npm i @engineers/gcloud-storage
+```
+
+you can build this package and any of our packages yourself from [source](https://github.com/its-dibo/dibo/tree/main/packages)
+
+## contributing
+
+contributing with us are very welcome.
+
+read our [contributing guide](https://github.com/its-dibo/dibo/blob/main/CONTRIBUTING.md)
+
+## support us
+
+- [paypal](https://paypal.me/group99001)
+
+- [patreon](https://www.patreon.com/GoogleDev)
+
+## apps by `@engineers`
+
+- [ngx-cms](https://github.com/its-dibo/dibo/tree/main/projects/ngx-cms)
+
+- [social-control](https://github.com/its-dibo/dibo/tree/main/projects/social-control)
+
+- [vscode](https://github.com/its-dibo/dibo/tree/main/projects/vscode)
+
+## useful packages by `@engineers`
+
+- check out these useful packages that created by [@engineers organization](https://www.npmjs.com/org/engineers)
+
+- [cache](https://www.npmjs.com/package/@engineers/cache)
+
+- [databases](https://www.npmjs.com/package/@engineers/databases)
+
+- [dom](https://www.npmjs.com/package/@engineers/dom)
+
+- [express](https://www.npmjs.com/package/@engineers/express)
+
+- [firebase-admin](https://www.npmjs.com/package/@engineers/firebase-admin)
+
+- [gcloud-storage](https://www.npmjs.com/package/@engineers/gcloud-storage)
+
+- [geo](https://www.npmjs.com/package/@engineers/geo)
+
+- [graphics](https://www.npmjs.com/package/@engineers/graphics)
+
+- [hookable](https://www.npmjs.com/package/@engineers/hookable)
+
+- [javascript](https://www.npmjs.com/package/@engineers/javascript)
+
+- [lazy-load](https://www.npmjs.com/package/@engineers/lazy-load)
+
+- [mongoose](https://www.npmjs.com/package/@engineers/mongoose)
+
+- [ngx-chat-firebase-mat](https://www.npmjs.com/package/@engineers/ngx-chat-firebase-mat)
+
+- [ngx-content-core](https://www.npmjs.com/package/@engineers/ngx-content-core)
+
+- [ngx-content-view-mat](https://www.npmjs.com/package/@engineers/ngx-content-view-mat)
+
+- [ngx-formly](https://www.npmjs.com/package/@engineers/ngx-formly)
+
+- [ngx-universal-express](https://www.npmjs.com/package/@engineers/ngx-universal-express)
+
+- [ngx-utils](https://www.npmjs.com/package/@engineers/ngx-utils)
+
+- [nodejs](https://www.npmjs.com/package/@engineers/nodejs)
+
+- [rxjs](https://www.npmjs.com/package/@engineers/rxjs)
+
+- [tmpl](https://www.npmjs.com/package/@engineers/tmpl)
+
+- [updater](https://www.npmjs.com/package/@engineers/updater)
+
+- [webpack](https://www.npmjs.com/package/@engineers/webpack)

package/index.d.ts

@@ -1,48 +1,2 @@
-/// <reference types="node" />
-/// <reference types="node" />
-import { Bucket, CreateBucketRequest, File, SaveOptions, Storage, UploadResponse, StorageOptions as _StorageOptions } from '@google-cloud/storage';
-import { PathLike } from 'node:fs';
-export interface StorageOptions extends _StorageOptions {
-    bucket: string;
-    rootDir?: string;
-}
-export interface UploadOptions {
-    destination: string;
-}
-export interface DownloadOptions {
-    destination?: string;
-    encoding?: BufferEncoding | null;
-}
-export interface DeleteOptions {
-    ignoreNotFound?: boolean;
-}
-export interface ExistsOptions {
-}
-export interface CreateBucketMeta extends CreateBucketRequest {
-    labels?: {
-        [key: string]: string;
-    };
-}
-export default class {
-    storage: Storage;
-    bucket: Bucket;
-    private baseDir;
-    constructor(options: StorageOptions);
-    upload(path: PathLike, options?: UploadOptions | string): Promise<UploadResponse | void>;
-    download(file: PathLike | File, options?: DownloadOptions | string): Promise<Buffer | string | Array<any> | {
-        [key: string]: any;
-    } | void>;
-    downloadAll(destination: PathLike, directory?: PathLike, filter?: RegExp | ((file: string) => boolean), options?: {
-        start?: number;
-        end?: number;
-    }): Promise<{
-        [key: string]: boolean;
-    }>;
-    write(path: PathLike, content?: any, options?: SaveOptions): Promise<any>;
-    read(file: PathLike | File, options?: DownloadOptions | string): Promise<string | void | any[] | Buffer | {
-        [key: string]: any;
-    }>;
-    delete(path: PathLike, options?: DeleteOptions): Promise<any>;
-    exists(path: PathLike, options?: ExistsOptions): Promise<boolean>;
-    create(metaData?: CreateBucketMeta): Promise<import("@google-cloud/storage").CreateBucketResponse>;
-}
+export * from './src';
+export { default as Storage } from './src';

package/index.js

@@ -1,297 +1,5 @@
-// src/index.ts
-import {
-  Storage
-} from "@google-cloud/storage";
-import { mkdirSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import stripJsonComments from "strip-json-comments";
-import { URL } from "node:url";
-
-// ../javascript/src/objects.ts
-function objectType(object) {
-  return Object.prototype.toString.call(object).replace("[object ", "").replace("]", "").toLowerCase();
-}
-
-// ../javascript/src/string.ts
-function cleanString(value, options = {}) {
-  let opts = {
-    // remove '//' comments
-    // it is better to disable this option to avoid removing comment-like strings by mistake
-    // suc as `https://`
-    removeComments: false,
-    // remove break lines for multi-line string
-    removeBreakLines: true,
-    // trim each line of the multi-line string
-    trim: false,
-    ...options
-  };
-  if (opts.removeComments)
-    value = value.replace(/\s*\/\/.*$/gm, "");
-  if (opts.removeBreakLines)
-    value = value.split("\n").map((line) => opts.trim ? line.trim() : line).join("");
-  if (opts.trim)
-    value = value.trim();
-  return value;
-}
-
-// ../javascript/src/regex.ts
-function escape(value) {
-  return value.replace(/[$()*+./?[\\\]^{|}]/g, "\\$&");
-}
-function clean(value, options = {}) {
-  value = cleanString(value, options);
-  return options.escape ? escape(value) : value;
-}
-function toRegExp(value, optionsOrFlags = {}) {
-  let opts = {
-    delimiter: "",
-    ...typeof optionsOrFlags === "string" ? { flags: optionsOrFlags } : optionsOrFlags
-  };
-  if (typeof value === "string") {
-    value = clean(value, opts);
-  } else if (Array.isArray(value)) {
-    value = value.map(
-      (element) => (
-        // we don't need to escape a RegExp pattern, only escape strings
-        `(?:${element instanceof RegExp ? element.source : clean(element.toString(), opts)})`
-      )
-    ).join(opts.delimiter);
-  } else if (value instanceof RegExp) {
-  } else {
-    throw new TypeError(`value ${value} must be of type Pattern`);
-  }
-  return new RegExp(value, opts.flags);
-}
-
-// ../javascript/src/patterns.ts
-var ipv4 = /^(?:(?:25[0-5]|2[0-4]\d|1\d\d|\d)\.?){4}$/;
-var v6segment = "[a-fA-F\\d]{1,4}";
-var ipv6 = toRegExp(
-  `(?:(?:${v6segment}:){7}(?:${v6segment}|:)|(?:${v6segment}:){6}(?:${ipv4}|:${v6segment}|:)|(?:${v6segment}:){5}(?::${ipv4}|(?::${v6segment}){1,2}|:)| (?:${v6segment}:){4}(?:(?::${v6segment}){0,1}:${ipv4}|(?::${v6segment}){1,3}|:)| (?:${v6segment}:){3}(?:(?::${v6segment}){0,2}:${ipv4}|(?::${v6segment}){1,4}|:)|(?:${v6segment}:){2}(?:(?::${v6segment}){0,3}:${ipv4}|(?::${v6segment}){1,5}|:)|(?:${v6segment}:){1}(?:(?::${v6segment}){0,4}:${ipv4}|(?::${v6segment}){1,6}|:)|(?::(?:(?::${v6segment}){0,5}:${ipv4}|(?::${v6segment}){1,7}|:)))(?:%[0-9a-zA-Z]{1,})?`,
-  { removeComments: false }
-);
-var ip = toRegExp([ipv4, ipv6], { delimiter: "|" });
-var rootDomain = /^([\dA-Za-z][\dA-Za-z-]{2,62})\.(\w{2,3})(?:\.([A-Za-z]{2}))?$/;
-var domain = toRegExp(
-  [
-    // subdomain
-    // todo: RegExp captures the latest group match only, instead of capturing all of the repeating patterns
-    // https://stackoverflow.com/a/37004214/12577650
-    /^((?:([\dA-Za-z][\dA-Za-z-]{0,62})+\.)*)/,
-    // remove the first '^' from '^---' or '(?:^---)'
-    rootDomain.source.replace("^", "")
-  ],
-  { delimiter: "" }
-);
-var email = toRegExp([/^([a-z]+\w+)@/, domain.source.replace("^", "")], {
-  delimiter: ""
-});
-var unallowedUrlChars = ` "'\`
-<>[\\]`;
-var tdl = "com|net|org";
-var link = toRegExp(
-  `((?:ftp|https?://[^${unallowedUrlChars}]+)|(?:[^${unallowedUrlChars}\\/]+\\.(?:${tdl})(?:\\.[a-z]{2}){0,1}))(?::d+)?(?:/[^${unallowedUrlChars}]+)*`,
-  { flags: "gi" }
-);
-var plainLink = toRegExp(
-  [
-    link,
-    // doesn't followed by '*</a>', i.e: doesn't exist inside <a> tag (plain links only)
-    // https://stackoverflow.com/a/68188492/12577650
-    `(?![^<]*</a>)`
-  ],
-  { delimiter: "" }
-);
-
-// src/index.ts
-var src_default = class {
-  storage;
-  bucket;
-  baseDir;
-  /**
-   * creates a new bucket
-   *
-   * @function constructor
-   * @param options
-   * @param  bucket
-   */
-  // todo: if(bucket instanceof admin.Bucket)this.bucket=bucket
-  // constructor();
-  constructor(options) {
-    let opts = { ...options };
-    if (!opts.keyFile && !opts.keyFilename && !opts.credentials && process.env.gcloud_service_account_storage) {
-      opts.credentials = JSON.parse(process.env.gcloud_service_account_storage);
-    }
-    this.storage = new Storage(opts);
-    if (opts.bucket.includes("/")) {
-      let parts = opts.bucket.split("/");
-      opts.bucket = parts.shift();
-      this.baseDir = parts.join("/") + opts.rootDir ? "/" + opts.rootDir : "";
-    }
-    this.bucket = this.storage.bucket(opts.bucket);
-  }
-  /**
-   * uploads a file to the current bucket
-   *
-   * @function upload
-   * @param  file file path
-   * @param path
-   * @param  options UploadOptions object or destination path as string
-   * @returns Promise<UploadResponse>;  //UploadResponse=[File, API request]
-   */
-  // todo: upload / download a folder
-  upload(path, options) {
-    let opts = {
-      ...typeof options === "string" ? { destination: options } : options || {}
-    };
-    if (this.baseDir && opts?.destination) {
-      opts.destination = `${this.baseDir}/${opts.destination}`;
-    }
-    return this.bucket.upload(path.toString(), opts);
-  }
-  /**
-   * downloads a file
-   *
-   * @function download
-   * @param  file        file path
-   * @param  options DownloadOptions object or destination as string
-   * @returns Promise that resolves to:
-   *           - void: if options.destination used
-   *           - Buffer: if options.encoding is undefined
-   *           - Array or plain object: if the file is json
-   *           - string: otherwise
-   */
-  // todo: if(!options.destination)return th content as Promise<Buffer | ...>
-  // otherwise write the content into a local destination and return boolean
-  download(file, options) {
-    if (typeof file === "string" || file instanceof Buffer || file instanceof URL) {
-      file = this.bucket.file(
-        this.baseDir ? `${this.baseDir}/${file.toString()}` : file.toString()
-      );
-    }
-    let opts = Object.assign(
-      { encoding: null },
-      typeof options === "string" ? { destination: options } : options || {}
-    );
-    if (opts.destination) {
-      mkdirSync(dirname(opts.destination), { recursive: true });
-    }
-    return file.download({ ...opts }).then((result) => {
-      if (opts.destination) {
-        return;
-      }
-      let data = result[0];
-      if (opts.encoding === void 0) {
-        return data;
-      }
-      let dataString = data.toString();
-      try {
-        return file.name.slice(-5) === ".json" ? JSON.parse(stripJsonComments(dataString)) : dataString;
-      } catch {
-        return dataString;
-      }
-    });
-  }
-  /**
-   * download all files from a directory that match the provided filter
-   *
-   * @param destination the local path to download the files to
-   * @param directory the directory to be downloaded
-   * @param filter a pattern or function to filter the files to be downloaded
-   * @param options
-   * @param options.start download all files starting from the specified one (paginating behavior) (default is the first file)
-   * @param options.end download all files until the specified file (default is the last file)
-   * @returns a map of {file: result}
-   */
-  downloadAll(destination, directory, filter, options = {}) {
-    options = Object.assign({ start: 0, end: void 0 }, options || {});
-    let results = {};
-    if (!filter) {
-      filter = (file) => true;
-    } else if (filter instanceof RegExp) {
-      filter = (file) => filter.test(file);
-    }
-    if (this.baseDir) {
-      directory = `${this.baseDir}/${directory}`;
-    }
-    return this.bucket.getFiles({ prefix: directory?.toString() }).then((files) => files[0].filter((file) => filter(file.name))).then(
-      (files) => Promise.all(
-        files.slice(options.start, options.end).map(
-          (file) => this.download(file, {
-            destination: resolve(`${destination.toString()}/${file.name}`)
-          }).then((result) => {
-            results[file.name] = true;
-          }).catch((error) => {
-            results[file.name] = false;
-          })
-        )
-      ).then(() => results)
-    );
-  }
-  /**
-   * writes a content to a file in the bucket
-   *
-   * @param path bucket path
-   * @param content the content to be written. if no content provided, an empty file is created
-   * @param options
-   * @returns the original content
-   */
-  write(path, content = "", options) {
-    if (this.baseDir) {
-      path = `${this.baseDir}/${path}`;
-    }
-    return this.bucket.file(path.toString()).save(
-      ["array", "object"].includes(objectType(content)) ? JSON.stringify(content) : content,
-      options
-    ).then(() => content);
-  }
-  /** an alias to download() to be compatible with node:fs functions */
-  read(file, options) {
-    return this.download(file, options);
-  }
-  // eslint-disable-next-line no-secrets/no-secrets
-  // https://stackoverflow.com/a/64539948/12577650
-  delete(path, options) {
-    if (this.baseDir) {
-      path = `${this.baseDir}/${path}`;
-    }
-    return this.bucket.file(path.toString()).delete(options);
-  }
-  /**
-   * check if a file exists in the bucket
-   * this method works with files only, not folders
-   * folders doesn't actually exist
-   * https://cloud.google.com/storage/docs/folders
-   *
-   * @param path file path
-   * @param options
-   * @returns boolean
-   */
-  exists(path, options) {
-    if (this.baseDir) {
-      path = `/${this.baseDir}/${path}`;
-    }
-    return this.bucket.file(path.toString()).exists(options).then((result) => result[0]);
-  }
-  /**
-   * create a new bucket, and optionally add labels to it
-   * add the desired labels as key-value pairs to metaData.labels
-   * https://cloud.google.com/storage/docs/using-bucket-labels#storage-modify-bucket-label-nodejs
-   *
-   * @param metaData
-   * @returns
-   */
-  create(metaData) {
-    let bucketName = this.bucket.name;
-    let { labels, ...meta } = metaData || {};
-    return this.storage.createBucket(bucketName, meta).then((result) => {
-      this.bucket.name = bucketName;
-      return labels ? this.bucket.setLabels(labels).then(() => result) : result;
-    });
-  }
-  // todo: read(file:string):Buffer
-  // todo: delete folder
-};
+export * from "./src";
+import { default as default2 } from "./src";
 export {
-  src_default as default
+  default2 as Storage
 };

package/nx.json

@@ -0,0 +1,177 @@
+{
+  "$schema": "./node_modules/nx/schemas/nx-schema.json",
+  "targetDefaults": {
+    "build": {
+      "executor": "@engineers/nx-manager:universal-builder",
+      "dependsOn": ["typecheck", "prebuild", "^build"],
+      "cache": true,
+      "inputs": ["default", "^default"],
+      "outputs": ["{projectRoot}/dist"],
+      "options": {
+        "forceRnDefaultPostBuild": true
+      }
+    },
+    "serve": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build", "preserve"],
+      "continuous": true,
+      "options": {
+        "cwd": "{projectRoot}",
+        "command": "NODE_ENV=development pnpm tsx --env-file-if-exists=.env --env-file-if-exists=.env.local dist/main.js"
+      },
+      "configurations": {
+        "production": {
+          "command": "NODE_ENV=production pnpm tsx --env-file-if-exists=.env --env-file-if-exists=.env.local --env-file-if-exists=.env.production --env-file-if-exists=.env.production.local dist/main.js"
+        }
+      }
+    },
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "{projectRoot}/dist"
+      }
+    },
+    "semantic-release": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build", "prerelease"],
+      "options": {
+        "cwd": "{projectRoot}",
+        "command": "pnpm tsx node_modules/semantic-release/bin/semantic-release.js"
+      },
+      "configurations": {
+        "local": {
+          "command": "DOTENV_CONFIG_PATH=../../.env pnpm run release --no-ci"
+        },
+        "dry": {
+          "command": "DOTENV_CONFIG_PATH=../../.env pnpm run release --no-ci --dry-run"
+        }
+      }
+    },
+    "test": {
+      "inputs": ["test"],
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "dependsOn": ["^build", "pretest"],
+      "configurations": {
+        "unit": {
+          "args": [
+            "--testPathIgnorePatterns '.*\\.e2e\\.spec\\.ts$'",
+            "--testPathIgnorePatterns '/.*-e2e/'",
+            "--testPathIgnorePatterns '/.*-e2e/'"
+          ]
+        },
+        "e2e": {
+          "args": [
+            "--testMatch '**/*-e2e/**/*.{spec,test}.[mc]?[jt]s?(x)'",
+            "--testMatch '**/e2e/**/*.{spec,test}.[mc]?[jt]s?(x)'",
+            "--testMatch  '**/*.e2e.(spec|test).?([mc])[jt]s?(x)'"
+          ]
+        }
+      }
+    },
+    "@angular/build:application": {
+      "cache": true,
+      "dependsOn": ["prebuild", "^build"],
+      "inputs": ["default", "^default"]
+    },
+    "@nx/angular:package": {
+      "cache": true,
+      "dependsOn": ["^build"],
+      "inputs": ["default", "^default"],
+      "outputs": ["{projectRoot}/dist"],
+      "options": {
+        "project": "{projectRoot}/ng-package.json",
+        "tsConfig": "{projectRoot}/tsconfig.lib.json"
+      }
+    },
+    "@nx/js:tsc": {
+      "cache": true,
+      "dependsOn": ["^build"],
+      "inputs": ["default", "^default"]
+    }
+  },
+  "namedInputs": {
+    "default": [
+      "{projectRoot}/src/**/*",
+      "!{projectRoot}/**/*.(spec|test)(.e2e)?.[tj]sx?",
+      "!{projectRoot}/**/e2e/**/*",
+      "{projectRoot}/.env(.*)?",
+      "{workspaceRoot}/tasks/(post-)?build.ts",
+      "{projectRoot}/(project|package|tsconfig)(.+)?.json",
+      "{workspaceRoot}/tsconfig.base.json",
+      {
+        "runtime": "node --version"
+      },
+      {
+        "env": "NODE_ENV"
+      }
+    ],
+    "test": [
+      "default",
+      "{projectRoot}/tsconfig.spec.json",
+      "{projectRoot}/jest.config.[jt]s",
+      "{workspaceRoot}/jest.config.[jt]s",
+      "{projectRoot}/**/*.(spec|test)(.e2e)?.[jt]sx?",
+      "{projectRoot}/**/e2e/**/*.[jt]sx?",
+      {
+        "externalDependencies": ["jest"]
+      }
+    ]
+  },
+  "plugins": [
+    {
+      "plugin": "@nx/js/typescript",
+      "options": {
+        "typecheck": {
+          "targetName": "typecheck"
+        },
+        "build": false
+      }
+    },
+    {
+      "plugin": "@nx/jest/plugin",
+      "options": {
+        "targetName": "test",
+        "ciTargetName": "test-ci"
+      }
+    }
+  ],
+  "tasksRunnerOptions": {
+    "default": {
+      "options": {
+        "useDaemonProcess": false
+      }
+    }
+  },
+  "generators": {
+    "@nx/angular:library": {
+      "linter": "eslint",
+      "unitTestRunner": "jest"
+    },
+    "@nx/angular:component": {
+      "style": "scss"
+    }
+  },
+  "release": {
+    "projectsRelationship": "independent",
+    "version": {
+      "conventionalCommits": true,
+      "updateDependents": "always",
+      "preVersionCommand": "pnpm nx run-many -t build",
+      "manifestRootsToUpdate": [
+        "{projectRoot}",
+        {
+          "path": "{projectRoot}/dist",
+          "preserveLocalDependencyProtocols": false
+        }
+      ]
+    },
+    "releaseTag": {
+      "pattern": "{projectName}@{version}"
+    },
+    "changelog": {
+      "projectChangelogs": true
+    }
+  },
+  "sync": {
+    "applyChanges": false
+  }
+}

package/package.json

@@ -1,14 +1,66 @@
 {
   "name": "@engineers/gcloud-storage",
-  "version": "0.0.8-temp",
+  "version": "2.0.0",
   "type": "module",
-  "private": false,
   "description": "google cloud storage",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
-    "@google-cloud/storage": "^6.10.1",
-    "strip-json-comments": "^5.0.1"
+    "@google-cloud/storage": "^7.18.0"
+  },
+  "nx": {
+    "projectType": "library",
+    "targets": {
+      "build": {},
+      "semantic-release": {}
+    }
   },
   "imports": {
-    "#*": "./*"
-  }
-}
+    "#*": "./src/*.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.js",
+      "default": "./index.js"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    },
+    "./*": "./src/*"
+  },
+  "devDependencies": {
+    "@engineers/javascript": "2.0.2",
+    "@engineers/nodejs": "2.0.1",
+    "semantic-release": "^25.0.2",
+    "semantic-release-monorepo": "^8.0.2",
+    "tsx": "^4.21.0"
+  },
+  "engines": {
+    "node": "^18.19.1 || ^20.11.1 || >=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/its-dibo/dibo.git"
+  },
+  "author": "Sherif Eldeeb <sh.eldeeb.2010+github@gmail.com> (https://github.com/its-dibo)",
+  "homepage": "https://github.com/its-dibo/dibo#readme",
+  "bugs": {
+    "url": "https://github.com/its-dibo/dibo/issues",
+    "email": "sh.eldeeb.2010+github@gmail.com"
+  },
+  "license": "MIT",
+  "contributors": [],
+  "funding": [
+    {
+      "type": "paypal",
+      "url": "https://paypal.me/group99001"
+    },
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/GoogleDev"
+    }
+  ],
+  "scripts": {}
+}

package/src/index.d.ts

@@ -0,0 +1,46 @@
+import { Bucket, type CreateBucketRequest, File, type SaveOptions, Storage, type UploadResponse, type StorageOptions as _StorageOptions } from '@google-cloud/storage';
+import { type PathLike } from 'node:fs';
+export interface StorageOptions extends _StorageOptions {
+    bucket: string;
+    rootDir?: string;
+}
+export interface UploadOptions {
+    destination: string;
+}
+export interface DownloadOptions {
+    destination?: string;
+    encoding?: BufferEncoding | null;
+}
+export interface DeleteOptions {
+    ignoreNotFound?: boolean;
+}
+export interface ExistsOptions {
+}
+export interface CreateBucketMeta extends CreateBucketRequest {
+    labels?: {
+        [key: string]: string;
+    };
+}
+export default class {
+    storage: Storage;
+    bucket: Bucket;
+    private baseDir;
+    constructor(options: StorageOptions);
+    upload(path: PathLike, options?: UploadOptions | string): Promise<UploadResponse | void>;
+    download(file: PathLike | File, options?: DownloadOptions | string): Promise<Buffer | string | Array<any> | {
+        [key: string]: any;
+    } | void>;
+    downloadAll(destination: PathLike, directory?: PathLike, filter?: RegExp | ((file: string) => boolean), options?: {
+        start?: number;
+        end?: number;
+    }): Promise<{
+        [key: string]: boolean;
+    }>;
+    write(path: PathLike, content?: any, options?: SaveOptions): Promise<any>;
+    read(file: PathLike | File, options?: DownloadOptions | string): Promise<string | void | any[] | Buffer<ArrayBufferLike> | {
+        [key: string]: any;
+    }>;
+    delete(path: PathLike, options?: DeleteOptions): Promise<any>;
+    exists(path: PathLike, options?: ExistsOptions): Promise<boolean>;
+    create(metaData?: CreateBucketMeta): Promise<import("@google-cloud/storage").CreateBucketResponse>;
+}

package/src/index.js

@@ -0,0 +1,200 @@
+import {
+  Storage
+} from "@google-cloud/storage";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { cleanJson, objectType } from "@engineers/javascript";
+import { URL } from "node:url";
+class src_default {
+  storage;
+  bucket;
+  baseDir;
+  /**
+   * creates a new bucket
+   *
+   * @function constructor
+   * @param options
+   * @param  bucket
+   */
+  // todo: if(bucket instanceof admin.Bucket)this.bucket=bucket
+  // constructor();
+  constructor(options) {
+    let opts = { ...options };
+    if (!opts.keyFile && !opts.keyFilename && !opts.credentials && process.env.gcloud_service_account_storage) {
+      opts.credentials = JSON.parse(process.env.gcloud_service_account_storage);
+    }
+    this.storage = new Storage(opts);
+    if (opts.bucket.includes("/")) {
+      let parts = opts.bucket.split("/");
+      opts.bucket = parts.shift();
+      this.baseDir = parts.join("/") + opts.rootDir ? "/" + opts.rootDir : "";
+    }
+    this.bucket = this.storage.bucket(opts.bucket);
+  }
+  /**
+   * uploads a file to the current bucket
+   *
+   * @function upload
+   * @param  file file path
+   * @param path
+   * @param  options UploadOptions object or destination path as string
+   * @returns Promise<UploadResponse>;  //UploadResponse=[File, API request]
+   */
+  // todo: upload / download a folder
+  upload(path, options) {
+    let opts = {
+      ...typeof options === "string" ? { destination: options } : options || {}
+    };
+    if (this.baseDir && opts?.destination) {
+      opts.destination = `${this.baseDir}/${opts.destination}`;
+    }
+    return this.bucket.upload(path.toString(), opts);
+  }
+  /**
+   * downloads a file
+   *
+   * @function download
+   * @param  file        file path
+   * @param  options DownloadOptions object or destination as string
+   * @returns Promise that resolves to:
+   *           - void: if options.destination used
+   *           - Buffer: if options.encoding is undefined
+   *           - Array or plain object: if the file is json
+   *           - string: otherwise
+   */
+  // todo: if(!options.destination)return th content as Promise<Buffer | ...>
+  // otherwise write the content into a local destination and return boolean
+  download(file, options) {
+    if (typeof file === "string" || // note: TS doesn't narrow down the type `Buffer<ArrayBufferLike>`
+    // so, it'll still see the type of file as `File | Buffer<ArrayBufferLike>`
+    // you may need to explicitly use `<File>file`
+    file instanceof Buffer || file instanceof URL) {
+      file = this.bucket.file(
+        this.baseDir ? `${this.baseDir}/${file.toString()}` : file.toString()
+      );
+    }
+    let opts = Object.assign(
+      { encoding: null },
+      typeof options === "string" ? { destination: options } : options || {}
+    );
+    if (opts.destination) {
+      mkdirSync(dirname(opts.destination), { recursive: true });
+    }
+    return file.download({ ...opts }).then((result) => {
+      if (opts.destination) {
+        return;
+      }
+      let data = result[0];
+      if (opts.encoding === void 0) {
+        return data;
+      }
+      let dataString = data.toString();
+      try {
+        return file.name.slice(-5) === ".json" ? JSON.parse(cleanJson(dataString)) : dataString;
+      } catch {
+        return dataString;
+      }
+    });
+  }
+  /**
+   * download all files from a directory that match the provided filter
+   *
+   * @param destination the local path to download the files to
+   * @param directory the directory to be downloaded
+   * @param filter a pattern or function to filter the files to be downloaded
+   * @param options
+   * @param options.start download all files starting from the specified one (paginating behavior) (default is the first file)
+   * @param options.end download all files until the specified file (default is the last file)
+   * @returns a map of {file: result}
+   */
+  downloadAll(destination, directory, filter, options = {}) {
+    options = Object.assign({ start: 0, end: void 0 }, options || {});
+    let results = {};
+    if (!filter) {
+      filter = (_file) => true;
+    } else if (filter instanceof RegExp) {
+      filter = (file) => filter.test(file);
+    }
+    if (this.baseDir) {
+      directory = `${this.baseDir}/${directory}`;
+    }
+    return this.bucket.getFiles({ prefix: directory?.toString() }).then((files) => files[0].filter((file) => filter(file.name))).then(
+      (files) => Promise.all(
+        files.slice(options.start, options.end).map(
+          (file) => this.download(file, {
+            destination: resolve(`${destination.toString()}/${file.name}`)
+          }).then((_result) => {
+            results[file.name] = true;
+          }).catch((_error) => {
+            results[file.name] = false;
+          })
+        )
+      ).then(() => results)
+    );
+  }
+  /**
+   * writes a content to a file in the bucket
+   *
+   * @param path bucket path
+   * @param content the content to be written. if no content provided, an empty file is created
+   * @param options
+   * @returns the original content
+   */
+  write(path, content = "", options) {
+    if (this.baseDir) {
+      path = `${this.baseDir}/${path}`;
+    }
+    return this.bucket.file(path.toString()).save(
+      ["array", "object"].includes(objectType(content)) ? JSON.stringify(content) : content,
+      options
+    ).then(() => content);
+  }
+  /** an alias to download() to be compatible with node:fs functions */
+  read(file, options) {
+    return this.download(file, options);
+  }
+  // https://stackoverflow.com/a/64539948/12577650
+  delete(path, options) {
+    if (this.baseDir) {
+      path = `${this.baseDir}/${path}`;
+    }
+    return this.bucket.file(path.toString()).delete(options);
+  }
+  /**
+   * check if a file exists in the bucket
+   * this method works with files only, not folders
+   * folders doesn't actually exist
+   * https://cloud.google.com/storage/docs/folders
+   *
+   * @param path file path
+   * @param options
+   * @returns boolean
+   */
+  exists(path, options) {
+    if (this.baseDir) {
+      path = `/${this.baseDir}/${path}`;
+    }
+    return this.bucket.file(path.toString()).exists(options).then((result) => result[0]);
+  }
+  /**
+   * create a new bucket, and optionally add labels to it
+   * add the desired labels as key-value pairs to metaData.labels
+   * https://cloud.google.com/storage/docs/using-bucket-labels#storage-modify-bucket-label-nodejs
+   *
+   * @param metaData
+   * @returns
+   */
+  create(metaData) {
+    let bucketName = this.bucket.name;
+    let { labels, ...meta } = metaData || {};
+    return this.storage.createBucket(bucketName, meta).then((result) => {
+      this.bucket.name = bucketName;
+      return labels ? this.bucket.setLabels(labels).then(() => result) : result;
+    });
+  }
+  // todo: read(file:string):Buffer
+  // todo: delete folder
+}
+export {
+  src_default as default
+};

package/src/index.spec.js

@@ -0,0 +1,72 @@
+import { afterAll, expect, test } from "@jest/globals";
+import Storage from "./index";
+import { read, remove, resolve, writeSync } from "@engineers/nodejs";
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let serviceAccount = resolve(__dirname, "./gcloud-service-account!!.json");
+if (existsSync(serviceAccount)) {
+  let bucket = `dibo-testing/test!!/gcloud-storage`;
+  let storage = new Storage({ bucket, keyFilename: serviceAccount });
+  writeSync(__dirname + "/test~~/file.json", { ok: 1 });
+  afterAll(() => {
+    return Promise.all(
+      ["file.json"].map((file) => storage.delete(`${file}`))
+    ).then(() => remove(__dirname + "/test~~"));
+  });
+  test("upload", () => {
+    return storage.upload(__dirname + "/test~~/file.json", `file.json`).then((result) => {
+      let metadata = result[1];
+      expect(metadata.kind).toEqual("storage#object");
+      expect(metadata.name).toEqual(`test!!/gcloud-storage/file.json`);
+      expect(metadata.size).toEqual(8);
+    });
+  });
+  test("write", () => {
+    return expect(storage.write(`note.txt`, "ok")).resolves.not.toThrow();
+  });
+  test("download to a destination", () => {
+    let destination = __dirname + "/test~~/file.json";
+    return expect(
+      storage.download(`file.json`, destination)
+    ).resolves.not.toThrow();
+  });
+  test("download as Buffer", () => {
+    return storage.download(`file.json`).then((result) => {
+      expect(result).toMatchObject({ ok: 1 });
+    });
+  });
+  test("download non-existing file", () => {
+    return expect(storage.download(`non-existing.txt`)).rejects.toThrow(
+      "No such object"
+    );
+  });
+  test("download to a non-existing directory", () => {
+    let destination = __dirname + "/test~~/non-existing/file.json";
+    return storage.download(`file.json`, destination).then(() => read(destination)).then((result) => {
+      expect(result).toMatchObject({ ok: 1 });
+    });
+    return expect(
+      storage.download(`file.json`, destination)
+    ).resolves.not.toThrow();
+  });
+  test("delete", () => {
+    return storage.delete(`note.txt`).then((result) => {
+      expect(result).toBeTruthy();
+    });
+  });
+  test("delete non-existing file", () => {
+    return expect(storage.delete(`none-existing.txt`)).rejects.toThrow(
+      "No such object"
+    );
+  });
+} else {
+  console.warn(
+    `testing for gcloud-storage skipped because the service account file does'nt exist
+    to run the test create "gcloud-service-account!!.json" contains your own service account
+    note that files that end with "!!" or "~~" don't be committed to the remote repository for security`
+  );
+  test("skip", () => {
+  });
+}

package/index.spec.d.ts

@@ -1 +0,0 @@
-export {};