@design-edito/tools 0.4.4 → 0.4.6

package/node/@google-cloud/storage/file/copy/index.js

@@ -1,9 +1,37 @@
-import {
-  copy
-} from "../../../../../chunks/chunk-3QI2MSDK.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  copy
-};
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+/**
+ * Copies a file from one location to another within a Google Cloud Storage bucket.
+ *
+ * If `overwrite` is **false** (default) and the destination object already
+ * exists, the operation aborts.
+ *
+ * @param {Bucket} bucket - The Google Cloud Storage bucket containing the file.
+ * @param {string} sourcePath - The path of the source object to copy.
+ * @param {string} targetPath - The destination path for the copied object.
+ * @param {CopyOptions} [options] - Optional copy configuration.
+ * @param {FileOptions} [options.fileOptions] - Extra options for `bucket.file`.
+ * @param {GCSFileCopyOptions} [options.copyOptions] - Extra options for `file.copy`.
+ * @param {boolean} [options.overwrite=false] - Whether to overwrite an existing destination object.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success:  `Outcome.makeSuccess(true)`.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function copy(bucket, sourcePath, targetPath, options) {
+    const { fileOptions, copyOptions, overwrite = false } = options ?? {};
+    try {
+        const srcFile = bucket.file(sourcePath, fileOptions);
+        const destFile = bucket.file(targetPath, fileOptions);
+        if (!overwrite) {
+            const [destExists] = await destFile.exists();
+            if (destExists) {
+                return Outcome.makeFailure(`Object already exists at ${targetPath}.`);
+            }
+        }
+        await srcFile.copy(destFile, copyOptions);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/@google-cloud/storage/file/download/index.js

@@ -1,9 +1,28 @@
-import {
-  download
-} from "../../../../../chunks/chunk-4Q4T7QQO.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  download
-};
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+/**
+ * Downloads a file from a specified Google Cloud Storage bucket.
+ *
+ * This function downloads a file from the given bucket and path, returning the file content as a `Readable`.
+ * The download process can be customized using optional `fileOptions` and `downloadOptions`.
+ *
+ * @param {Bucket} bucket - The Google Cloud Storage bucket object from which to download the file.
+ * @param {string} sourcePath - The path of the file to be downloaded in the bucket.
+ * @param {DownloadOptions} [options] - Optional configuration options for the download.
+ * @returns {Promise<Outcome.Either<Readable, string>>} A promise that resolves to an `Outcome.Either`.
+ * - On success: `Outcome.makeSuccess(stream)` containing the downloaded file's content as a `Readable`.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message if the download fails.
+ */
+export async function download(bucket, sourcePath, options) {
+    const { fileOptions, downloadOptions } = options ?? {};
+    try {
+        const file = bucket.file(sourcePath, fileOptions);
+        const stream = file.createReadStream(downloadOptions);
+        stream.on('error', (err) => { throw err; });
+        return Outcome.makeSuccess(stream);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}

package/node/@google-cloud/storage/file/exists/index.js

@@ -1,9 +1,26 @@
-import {
-  exists
-} from "../../../../../chunks/chunk-YHMR7IBA.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  exists
-};
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Checks if a file exists in the specified bucket.
+ *
+ * This function verifies whether a file at the given `sourcePath` exists in the bucket. It can be configured with options to customize the behavior of the check.
+ *
+ * @param {Bucket} bucket - The GCS bucket to check for the file existence.
+ * @param {string} sourcePath - The path of the file to check within the bucket.
+ * @param {ExistsOptions} [options] - Optional configuration for the file existence check.
+ * @param {FileOptions} [options.fileOptions] - Additional options for the file, such as custom metadata or ACL settings.
+ * @param {ExistsOptions} [options.existsOptions] - Options for controlling the `exists` method (if any).
+ * @returns {Promise<Outcome.Either<boolean, string>>} - Returns either a success with `true` or `false` indicating whether the file exists, or a failure with an error message.
+ */
+export async function exists(bucket, sourcePath, options) {
+    const { fileOptions, existsOptions } = options ?? {};
+    try {
+        const file = bucket.file(sourcePath, fileOptions);
+        const [exists] = await file.exists(existsOptions);
+        return Outcome.makeSuccess(exists);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}

package/node/@google-cloud/storage/file/generate-signed-url/index.js

@@ -1,28 +1,34 @@
-import {
-  makeFailure,
-  makeSuccess
-} from "../../../../../chunks/chunk-LUAYN7VJ.js";
-import {
-  unknownToString
-} from "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/@google-cloud/storage/file/generate-signed-url/index.ts
-async function generateSignedUrl(bucket, sourcePath, action, expiresOn, options) {
-  const { fileOptions, getSignedUrlOptions } = options ?? {};
-  try {
-    const file = bucket.file(sourcePath, fileOptions);
-    const [url] = await file.getSignedUrl({
-      action,
-      expires: expiresOn,
-      ...getSignedUrlOptions
-    });
-    return makeSuccess(url);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+/**
+ * Generates a signed URL that provides temporary access to a file in Google Cloud Storage.
+ *
+ * This function generates a signed URL for the file located at `sourcePath` in the given bucket. The signed URL
+ * allows users to perform an action on the file (e.g., `read`, `write`) for a limited time as defined by the `expiresOn` parameter.
+ * The behavior can be customized using optional `fileOptions` and `getSignedUrlOptions`.
+ *
+ * @param {Bucket} bucket - The Google Cloud Storage bucket object containing the file.
+ * @param {string} sourcePath - The path of the file for which the signed URL is being generated.
+ * @param {GetSignedUrlConfig['action']} action - The action allowed by the signed URL (e.g., 'read', 'write', 'delete').
+ * @param {GetSignedUrlConfig['expires']} expiresOn - The expiration time of the signed URL, after which it is no longer valid.
+ * @param {GenerateSignedUrlOptions} [options] - Optional configuration options for generating the signed URL.
+ * @returns {Promise<Outcome.Either<string, string>>} A promise that resolves to an `Outcome.Either`.
+ * - On success: `Outcome.makeSuccess(url)` containing the generated signed URL.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message if the signed URL generation fails.
+ */
+export async function generateSignedUrl(bucket, sourcePath, action, expiresOn, options) {
+    const { fileOptions, getSignedUrlOptions } = options ?? {};
+    try {
+        const file = bucket.file(sourcePath, fileOptions);
+        const [url] = await file.getSignedUrl({
+            action,
+            expires: expiresOn,
+            ...getSignedUrlOptions
+        });
+        return Outcome.makeSuccess(url);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
 }
-export {
-  generateSignedUrl
-};

package/node/@google-cloud/storage/file/get-metadata/index.js

@@ -1,24 +1,29 @@
-import {
-  makeFailure,
-  makeSuccess
-} from "../../../../../chunks/chunk-LUAYN7VJ.js";
-import {
-  unknownToString
-} from "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/@google-cloud/storage/file/get-metadata/index.ts
-async function getMetadata(bucket, sourcePath, options) {
-  const { fileOptions, getFileMetadataOptions } = options ?? {};
-  try {
-    const file = bucket.file(sourcePath, fileOptions);
-    const [metadata] = await file.getMetadata(getFileMetadataOptions);
-    return makeSuccess(metadata);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+/**
+ * Retrieves the metadata of a file from a specified Google Cloud Storage bucket.
+ *
+ * This function fetches the metadata for a file located at `sourcePath` in the given bucket.
+ * It can be customized using optional `fileOptions` and `getFileMetadataOptions` to control the retrieval behavior.
+ *
+ * @param {Bucket} bucket - The Google Cloud Storage bucket object containing the file whose metadata is being retrieved.
+ * @param {string} sourcePath - The path of the file whose metadata is to be fetched.
+ * @param {GetMetadataOptions} [options] - Optional configuration options for the file metadata retrieval.
+ * @returns {Promise<Outcome.Either<FileMetadata, string>>} A promise that resolves to an `Outcome.Either`.
+ * - On success: `Outcome.makeSuccess(metadata)` containing the file's metadata.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message if the metadata retrieval fails.
+ *
+ * @throws {Error} Throws an error if the metadata retrieval operation fails (e.g., file not found, insufficient permissions, etc.).
+ */
+export async function getMetadata(bucket, sourcePath, options) {
+    const { fileOptions, getFileMetadataOptions } = options ?? {};
+    try {
+        const file = bucket.file(sourcePath, fileOptions);
+        const [metadata] = await file.getMetadata(getFileMetadataOptions);
+        return Outcome.makeSuccess(metadata);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
 }
-export {
-  getMetadata
-};

package/node/@google-cloud/storage/file/get-permissions/index.js

@@ -1,24 +1,26 @@
-import {
-  makeFailure,
-  makeSuccess
-} from "../../../../../chunks/chunk-LUAYN7VJ.js";
-import {
-  unknownToString
-} from "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/@google-cloud/storage/file/get-permissions/index.ts
-async function getPermissions(bucket, sourcePath, options) {
-  const { fileOptions, getAclOptions } = options ?? {};
-  try {
-    const file = bucket.file(sourcePath, fileOptions);
-    const [acl] = await file.acl.get(getAclOptions);
-    return makeSuccess(acl);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+/**
+ * Retrieves the access control list (ACL) for a file in Google Cloud Storage.
+ *
+ * This function fetches the ACL settings of a given file to determine the permissions assigned to different users or roles.
+ *
+ * @param {Bucket} bucket - The Google Cloud Storage bucket containing the file.
+ * @param {string} sourcePath - The path of the file whose permissions need to be retrieved.
+ * @param {GetPermissionsOptions} [options] - Optional configuration options for the file and ACL retrieval.
+ * @returns {Promise<Outcome.Either<any, string>>} A promise that resolves to an `Outcome.Either`.
+ * - On success: `Outcome.makeSuccess(acl)` containing the file's ACL settings.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message if the ACL retrieval fails.
+ */
+export async function getPermissions(bucket, sourcePath, options) {
+    const { fileOptions, getAclOptions } = options ?? {};
+    try {
+        const file = bucket.file(sourcePath, fileOptions);
+        const [acl] = await file.acl.get(getAclOptions);
+        return Outcome.makeSuccess(acl);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
 }
-export {
-  getPermissions
-};

package/node/@google-cloud/storage/file/index.d.ts

@@ -1,8 +1,8 @@
 export * as copy from './copy/index.js'
 export * as download from './download/index.js'
 export * as exists from './exists/index.js'
-export * as getMetadata from './get-metadata/index.js'
 export * as generateSignedUrl from './generate-signed-url/index.js'
+export * as getMetadata from './get-metadata/index.js'
 export * as getPermissions from './get-permissions/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'

package/node/@google-cloud/storage/file/index.js

@@ -1,8 +1,8 @@
 export * as copy from './copy/index.js'
 export * as download from './download/index.js'
 export * as exists from './exists/index.js'
-export * as getMetadata from './get-metadata/index.js'
 export * as generateSignedUrl from './generate-signed-url/index.js'
+export * as getMetadata from './get-metadata/index.js'
 export * as getPermissions from './get-permissions/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'

package/node/@google-cloud/storage/file/move/index.js

@@ -1,9 +1,40 @@
-import {
-  move
-} from "../../../../../chunks/chunk-4KLCJX2T.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  move
-};
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+/**
+ * Moves a file from one location to another within a Google Cloud Storage bucket.
+ *
+ * The function copies the object at `sourcePath` to `targetPath` and, on
+ * successful copy, deletes the original. If `overwrite` is **false** and the
+ * destination already exists, the operation aborts.
+ *
+ * @param {Bucket}   bucket      - The Google Cloud Storage bucket.
+ * @param {string}   sourcePath  - The path of the source object.
+ * @param {string}   targetPath  - The destination path.
+ * @param {MoveOptions} [options] - Optional configuration.
+ * @param {FileOptions}   [options.fileOptions]   - Options for file handles.
+ * @param {CopyOptions}   [options.copyOptions]   - Extra options for `copy`.
+ * @param {GCSDeleteFileOptions} [options.deleteOptions] - Extra options for `delete`.
+ * @param {boolean}      [options.overwrite=false] - Whether to overwrite an existing destination.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - Success: `Outcome.makeSuccess(true)` if the move succeeds.
+ * - Failure: `Outcome.makeFailure(errStr)` if the move fails.
+ */
+export async function move(bucket, sourcePath, targetPath, options) {
+    const { fileOptions, copyOptions, deleteOptions, overwrite = false } = options ?? {};
+    try {
+        const srcFile = bucket.file(sourcePath, fileOptions);
+        const destFile = bucket.file(targetPath, fileOptions);
+        if (!overwrite) {
+            const [exists] = await destFile.exists();
+            if (exists) {
+                return Outcome.makeFailure(`Object already exists at ${targetPath}.`);
+            }
+        }
+        await srcFile.copy(destFile, copyOptions);
+        await srcFile.delete(deleteOptions);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/@google-cloud/storage/file/remove/index.js

@@ -1,9 +1,36 @@
-import {
-  remove
-} from "../../../../../chunks/chunk-MO4TRYNI.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  remove
-};
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+/**
+ * Removes a file from a specified Google Cloud Storage bucket.
+ *
+ * This function deletes the object located at `targetPath` in the given bucket.
+ * The operation can be customized using optional `fileOptions` (to reference the object)
+ * and `deleteOptions` (to influence GCS deletion behaviour).
+ * If the `ignoreMissing` option is **true**, the function treats a missing object as a
+ * successful outcome instead of returning an error.
+ *
+ * @param {Bucket} bucket - The Google Cloud Storage bucket instance.
+ * @param {string} targetPath - The path of the file to remove in the bucket.
+ * @param {RemoveOptions} [options] - Optional settings for configuring the removal process.
+ * @returns {Promise<Outcome.Either<true, string>>} A promise that resolves to an Outcome.Either.
+ * - On success: `Outcome.makeSuccess(true)` indicating the removal was successful.
+ * - On failure:  `Outcome.makeFailure(errStr)` with an error message if the removal fails.
+ */
+export async function remove(bucket, targetPath, options) {
+    const { fileOptions, deleteOptions, ignoreMissing = true } = options ?? {};
+    try {
+        const file = bucket.file(targetPath, fileOptions);
+        const [exists] = await file.exists();
+        if (!exists) {
+            if (ignoreMissing)
+                return Outcome.makeSuccess(true);
+            return Outcome.makeFailure(`File not found at ${targetPath}.`);
+        }
+        await file.delete(deleteOptions);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}

package/node/@google-cloud/storage/file/revoke-signed-urls/index.js

@@ -1,30 +1,33 @@
-import {
-  upload
-} from "../../../../../chunks/chunk-EX2QKFY5.js";
-import {
-  remove
-} from "../../../../../chunks/chunk-MO4TRYNI.js";
-import {
-  download
-} from "../../../../../chunks/chunk-4Q4T7QQO.js";
-import {
-  makeSuccess
-} from "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/@google-cloud/storage/file/revoke-signed-urls/index.ts
-async function revokeSignedUrls(bucket, targetPath, options) {
-  const { downloadOptions, removeOptions, uploadOptions } = options ?? {};
-  const downloadAttempt = await download(bucket, targetPath, downloadOptions);
-  if (!downloadAttempt.success) return downloadAttempt;
-  const deletionAttempt = await remove(bucket, targetPath, removeOptions);
-  if (!deletionAttempt.success) return deletionAttempt;
-  const downloaded = downloadAttempt.payload;
-  const reuploadAttempt = await upload(bucket, targetPath, downloaded, uploadOptions);
-  if (!reuploadAttempt.success) return reuploadAttempt;
-  return makeSuccess(true);
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { download } from '../download/index.js';
+import { remove } from '../remove/index.js';
+import { upload } from '../upload/index.js';
+/**
+ * Revokes the signed URLs for a file in Google Cloud Storage by downloading the file,
+ * deleting it, and re-uploading it to effectively invalidate any previously generated signed URLs.
+ *
+ * This function first attempts to download the file from the bucket, then removes the file,
+ * and finally re-uploads the file to the same path. The re-upload effectively revokes any signed URLs that
+ * were generated for the file, as they are tied to the file's existence and content.
+ *
+ * @param {Bucket} bucket - The Google Cloud Storage bucket containing the file.
+ * @param {string} targetPath - The path of the file for which the signed URLs are to be revoked.
+ * @param {RevokeSignedUrlsOptions} [options] - Optional configuration options for the file operations.
+ * @returns {Promise<Outcome.Either<true, string>>} A promise that resolves to an `Outcome.Either`.
+ * - On success: `Outcome.makeSuccess(true)` if the file has been successfully re-uploaded after deletion.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message if any of the steps (download, remove, or upload) fail.
+ */
+export async function revokeSignedUrls(bucket, targetPath, options) {
+    const { downloadOptions, removeOptions, uploadOptions } = options ?? {};
+    const downloadAttempt = await download(bucket, targetPath, downloadOptions);
+    if (!downloadAttempt.success)
+        return downloadAttempt;
+    const deletionAttempt = await remove(bucket, targetPath, removeOptions);
+    if (!deletionAttempt.success)
+        return deletionAttempt;
+    const downloaded = downloadAttempt.payload;
+    const reuploadAttempt = await upload(bucket, targetPath, downloaded, uploadOptions);
+    if (!reuploadAttempt.success)
+        return reuploadAttempt;
+    return Outcome.makeSuccess(true);
 }
-export {
-  revokeSignedUrls
-};

package/node/@google-cloud/storage/file/stat/index.js

@@ -1,9 +1,35 @@
-import {
-  stat
-} from "../../../../../chunks/chunk-77SWZUHV.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  stat
-};
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Retrieves metadata for a single GCS object.
+ *
+ * @param {Bucket} bucket – GCS bucket.
+ * @param {string} path  – Object path.
+ * @param {StatOptions} [options] – Extra getMetadata options.
+ * @returns {Promise<Outcome.Either<Stat, string>>}
+ */
+export async function stat(bucket, path, options) {
+    const { fileOptions, getMetadataOptions } = options ?? {};
+    try {
+        const [meta] = await bucket
+            .file(path, fileOptions)
+            .getMetadata(getMetadataOptions);
+        const res = {
+            size: meta.size !== undefined
+                ? Number(meta.size)
+                : undefined,
+            modifiedAt: meta.updated !== undefined
+                ? new Date(meta.updated)
+                : undefined,
+            checksum: meta.md5Hash ?? meta.crc32c,
+            contentType: meta.contentType,
+            metadata: meta.metadata,
+            storageClass: meta.storageClass,
+            raw: meta
+        };
+        return Outcome.makeSuccess(res);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/@google-cloud/storage/file/update-metadata/index.js

@@ -1,24 +1,31 @@
-import {
-  makeFailure,
-  makeSuccess
-} from "../../../../../chunks/chunk-LUAYN7VJ.js";
-import {
-  unknownToString
-} from "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/@google-cloud/storage/file/update-metadata/index.ts
-async function updateFileMetadata(bucket, targetPath, metadata, options) {
-  const { fileOptions, metadataOptions } = options ?? {};
-  try {
-    const file = bucket.file(targetPath, fileOptions);
-    await file.setMetadata(metadata, metadataOptions);
-    return makeSuccess(true);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+/**
+ * Updates the metadata of a file in a Google Cloud Storage bucket.
+ *
+ * This function allows updating the metadata of a file located at `targetPath` in the given bucket.
+ * The metadata is updated according to the provided `metadata` object, which contains the new metadata key-value pairs.
+ * It can be customized using optional `fileOptions` and `metadataOptions` to control the update behavior.
+ *
+ * @param {Bucket} bucket - The Google Cloud Storage bucket object containing the file whose metadata is being updated.
+ * @param {string} targetPath - The path of the file whose metadata is to be updated.
+ * @param {Record<string, any>} metadata - The metadata object containing key-value pairs to be set on the file.
+ * @param {UpdateFileMetadataOptions} [options] - Optional configuration options for the metadata update operation.
+ * @returns {Promise<Outcome.Either<true, string>>} A promise that resolves to an `Outcome.Either`.
+ * - On success: `Outcome.makeSuccess(true)` indicating the metadata was successfully updated.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message if the metadata update operation fails.
+ *
+ * @throws {Error} Throws an error if the metadata update operation fails (e.g., file not found, insufficient permissions, etc.).
+ */
+export async function updateFileMetadata(bucket, targetPath, metadata, options) {
+    const { fileOptions, metadataOptions } = options ?? {};
+    try {
+        const file = bucket.file(targetPath, fileOptions);
+        await file.setMetadata(metadata, metadataOptions);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
 }
-export {
-  updateFileMetadata
-};

package/node/@google-cloud/storage/file/upload/index.js

@@ -1,9 +1,47 @@
-import {
-  upload
-} from "../../../../../chunks/chunk-EX2QKFY5.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  upload
-};
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+/**
+ * Uploads a file stream to a specified Google Cloud Storage bucket.
+ *
+ * This function uploads the provided file stream to the specified bucket at the given target path.
+ * The upload can be customized using optional `fileOptions` and `saveOptions`.
+ * If the `overwrite` option is false and a file already exists at the target path, the upload is aborted.
+ *
+ * @param {Bucket} bucket - The Google Cloud Storage bucket object.
+ * @param {string} targetPath - The target path where the file will be saved in the bucket.
+ * @param {Readable} fileStream - The file content to be uploaded.
+ * @param {UploadOptions} [options] - Optional options to configure the upload process.
+ * @returns {Promise<Outcome.Either<true, string>>} A promise that resolves to an Outcome.Either.
+ * - On success: Outcome.makeSuccess(true) indicating the upload was successful.
+ * - On failure: Outcome.makeFailure(errStr) with an error message if the upload fails.
+ */
+export async function upload(bucket, targetPath, fileStream, options) {
+    const { fileOptions, saveOptions, overwrite = false } = options ?? {};
+    const file = bucket.file(targetPath, fileOptions);
+    if (!overwrite) {
+        try {
+            const [exists] = await file.exists();
+            if (exists) {
+                return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+            }
+        }
+        catch (err) {
+            const errStr = unknownToString(err);
+            return Outcome.makeFailure(errStr);
+        }
+    }
+    try {
+        await new Promise((resolve, reject) => {
+            const writeStream = file.createWriteStream(saveOptions);
+            fileStream.pipe(writeStream);
+            fileStream.on('error', reject);
+            writeStream.on('finish', resolve);
+            writeStream.on('error', reject);
+        });
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}