@design-edito/tools 0.4.5 → 0.4.6

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

@@ -1,37 +1,36 @@
-// src/agnostic/errors/unknown-to-string/index.ts
-function unknownToString(unk, encoding) {
-  if (unk instanceof Error) return unk.message;
-  if (unk instanceof Buffer) return unk.toString(encoding ?? "utf-8");
-  if (typeof unk === "string") return unk;
-  if (typeof unk === "object" && unk !== null) return JSON.stringify(unk);
-  return `${unk}`;
-}
-
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
-}
-function makeFailure(error) {
-  return { success: false, error };
-}
-
-// src/node/@google-cloud/storage/file/remove/index.ts
-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 makeSuccess(true);
-      return makeFailure(`File not found at ${targetPath}.`);
+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);
     }
-    await file.delete(deleteOptions);
-    return makeSuccess(true);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
 }
-export {
-  remove
-};

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

@@ -1,96 +1,33 @@
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
+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);
 }
-function makeFailure(error) {
-  return { success: false, error };
-}
-
-// src/agnostic/errors/unknown-to-string/index.ts
-function unknownToString(unk, encoding) {
-  if (unk instanceof Error) return unk.message;
-  if (unk instanceof Buffer) return unk.toString(encoding ?? "utf-8");
-  if (typeof unk === "string") return unk;
-  if (typeof unk === "object" && unk !== null) return JSON.stringify(unk);
-  return `${unk}`;
-}
-
-// src/node/@google-cloud/storage/file/download/index.ts
-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 makeSuccess(stream);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
-}
-
-// src/node/@google-cloud/storage/file/remove/index.ts
-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 makeSuccess(true);
-      return makeFailure(`File not found at ${targetPath}.`);
-    }
-    await file.delete(deleteOptions);
-    return makeSuccess(true);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
-}
-
-// src/node/@google-cloud/storage/file/upload/index.ts
-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 makeFailure(`File already exists at ${targetPath}.`);
-      }
-    } catch (err) {
-      const errStr = unknownToString(err);
-      return 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 makeSuccess(true);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
-}
-
-// 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);
-}
-export {
-  revokeSignedUrls
-};

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

@@ -1,39 +1,35 @@
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
+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));
+    }
 }
-function makeFailure(error) {
-  return { success: false, error };
-}
-
-// src/agnostic/errors/unknown-to-string/index.ts
-function unknownToString(unk, encoding) {
-  if (unk instanceof Error) return unk.message;
-  if (unk instanceof Buffer) return unk.toString(encoding ?? "utf-8");
-  if (typeof unk === "string") return unk;
-  if (typeof unk === "object" && unk !== null) return JSON.stringify(unk);
-  return `${unk}`;
-}
-
-// src/node/@google-cloud/storage/file/stat/index.ts
-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 !== void 0 ? Number(meta.size) : void 0,
-      modifiedAt: meta.updated !== void 0 ? new Date(meta.updated) : void 0,
-      checksum: meta.md5Hash ?? meta.crc32c,
-      contentType: meta.contentType,
-      metadata: meta.metadata,
-      storageClass: meta.storageClass,
-      raw: meta
-    };
-    return makeSuccess(res);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
-}
-export {
-  stat
-};

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

@@ -1,32 +1,31 @@
-// src/agnostic/errors/unknown-to-string/index.ts
-function unknownToString(unk, encoding) {
-  if (unk instanceof Error) return unk.message;
-  if (unk instanceof Buffer) return unk.toString(encoding ?? "utf-8");
-  if (typeof unk === "string") return unk;
-  if (typeof unk === "object" && unk !== null) return JSON.stringify(unk);
-  return `${unk}`;
+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);
+    }
 }
-
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
-}
-function makeFailure(error) {
-  return { success: false, error };
-}
-
-// 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);
-  }
-}
-export {
-  updateFileMetadata
-};

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

@@ -1,49 +1,47 @@
-// src/agnostic/errors/unknown-to-string/index.ts
-function unknownToString(unk, encoding) {
-  if (unk instanceof Error) return unk.message;
-  if (unk instanceof Buffer) return unk.toString(encoding ?? "utf-8");
-  if (typeof unk === "string") return unk;
-  if (typeof unk === "object" && unk !== null) return JSON.stringify(unk);
-  return `${unk}`;
-}
-
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
-}
-function makeFailure(error) {
-  return { success: false, error };
-}
-
-// src/node/@google-cloud/storage/file/upload/index.ts
-async function upload(bucket, targetPath, fileStream, options) {
-  const { fileOptions, saveOptions, overwrite = false } = options ?? {};
-  const file = bucket.file(targetPath, fileOptions);
-  if (!overwrite) {
+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 {
-      const [exists] = await file.exists();
-      if (exists) {
-        return makeFailure(`File already exists at ${targetPath}.`);
-      }
-    } catch (err) {
-      const errStr = unknownToString(err);
-      return makeFailure(errStr);
+        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);
     }
-  }
-  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 makeSuccess(true);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
 }
-export {
-  upload
-};

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

@@ -1,3 +1,3 @@
-export * as directory from './directory/index.js'
 export * as bucket from './bucket/index.js'
+export * as directory from './directory/index.js'
 export * as file from './file/index.js'

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

@@ -1,3 +1,3 @@
-export * as directory from './directory/index.js'
 export * as bucket from './bucket/index.js'
+export * as directory from './directory/index.js'
 export * as file from './file/index.js'

package/node/cloud-storage/clients/index.js

@@ -1,15 +1,35 @@
-// src/node/cloud-storage/clients/index.ts
-import { Bucket as GCSBucket } from "@google-cloud/storage";
-import { S3Client } from "@aws-sdk/client-s3";
-import { Client as FtpClient } from "basic-ftp";
-import SftpClient from "ssh2-sftp-client";
-var isGcsBucket = (client) => client instanceof GCSBucket;
-var isS3ClientWithBucket = (client) => "bucketName" in client && typeof client.bucketName === "string" && "client" in client && client.client instanceof S3Client;
-var isFtpClient = (client) => client instanceof FtpClient;
-var isSftpClient = (client) => client instanceof SftpClient;
-export {
-  isFtpClient,
-  isGcsBucket,
-  isS3ClientWithBucket,
-  isSftpClient
-};
+import { Bucket as GCSBucket } from '@google-cloud/storage';
+import { S3Client } from '@aws-sdk/client-s3';
+import { Client as FtpClient } from 'basic-ftp';
+import SftpClient from 'ssh2-sftp-client';
+/**
+ * Type guard to check if a client is a Google Cloud Storage bucket.
+ *
+ * @param {AnyClient} client - The client to check.
+ * @returns {boolean} `true` if the client is a `GCSBucket`, `false` otherwise.
+ */
+export const isGcsBucket = (client) => client instanceof GCSBucket;
+/**
+ * Type guard to check if a client is an S3 client with bucket configuration.
+ *
+ * @param {AnyClient} client - The client to check.
+ * @returns {boolean} `true` if the client is an `S3ClientWithBucket`, `false` otherwise.
+ */
+export const isS3ClientWithBucket = (client) => ('bucketName' in client)
+    && typeof client.bucketName === 'string'
+    && ('client' in client)
+    && client.client instanceof S3Client;
+/**
+ * Type guard to check if a client is an FTP client.
+ *
+ * @param {AnyClient} client - The client to check.
+ * @returns {boolean} `true` if the client is an `FtpClient`, `false` otherwise.
+ */
+export const isFtpClient = (client) => client instanceof FtpClient;
+/**
+ * Type guard to check if a client is an SFTP client.
+ *
+ * @param {AnyClient} client - The client to check.
+ * @returns {boolean} `true` if the client is an `SftpClient`, `false` otherwise.
+ */
+export const isSftpClient = (client) => client instanceof SftpClient;