@design-edito/tools 0.4.5 → 0.4.6

package/node/@aws-s3/storage/file/stat/index.js

@@ -1,48 +1,34 @@
-// src/node/@aws-s3/storage/file/stat/index.ts
-import {
-  HeadObjectCommand
-} from "@aws-sdk/client-s3";
-
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
+import { HeadObjectCommand } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Retrieves metadata for a single S3 object.
+ *
+ * @param {S3Client} client – v3 S3 client.
+ * @param {string}   bucket – Bucket name.
+ * @param {string}   key    – Object key.
+ * @param {StatOptions} [options] – Extra HeadObject params.
+ * @returns {Promise<Outcome.Either<Stat, string>>}
+ */
+export async function stat(client, bucket, key, options) {
+    const { headObjectOptions } = options ?? {};
+    try {
+        const res = await client.send(new HeadObjectCommand({ Bucket: bucket, Key: key, ...headObjectOptions }));
+        const stat = {
+            size: res.ContentLength,
+            modifiedAt: res.LastModified,
+            checksum: res.ETag?.replace(/"/g, ''),
+            contentType: res.ContentType,
+            metadata: res.Metadata,
+            storageClass: res.StorageClass,
+            raw: res
+        };
+        return Outcome.makeSuccess(stat);
+    }
+    catch (err) {
+        const notFound = err.$metadata?.httpStatusCode === 404 || err.name === 'NotFound';
+        if (notFound)
+            return Outcome.makeFailure(`Object not found: ${key}`);
+        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/@aws-s3/storage/file/stat/index.ts
-async function stat(client, bucket, key, options) {
-  const { headObjectOptions } = options ?? {};
-  try {
-    const res = await client.send(
-      new HeadObjectCommand({ Bucket: bucket, Key: key, ...headObjectOptions })
-    );
-    const stat2 = {
-      size: res.ContentLength,
-      modifiedAt: res.LastModified,
-      checksum: res.ETag?.replace(/"/g, ""),
-      contentType: res.ContentType,
-      metadata: res.Metadata,
-      storageClass: res.StorageClass,
-      raw: res
-    };
-    return makeSuccess(stat2);
-  } catch (err) {
-    const notFound = err.$metadata?.httpStatusCode === 404 || err.name === "NotFound";
-    if (notFound) return makeFailure(`Object not found: ${key}`);
-    return makeFailure(unknownToString(err));
-  }
-}
-export {
-  stat
-};

package/node/@aws-s3/storage/file/upload/index.js

@@ -1,66 +1,55 @@
-// src/node/@aws-s3/storage/file/upload/index.ts
-import {
-  HeadObjectCommand
-} from "@aws-sdk/client-s3";
-import { Upload } from "@aws-sdk/lib-storage";
-
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
-}
-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/@aws-s3/storage/file/upload/index.ts
-async function upload(s3, bucketName, targetPath, fileStream, options) {
-  const {
-    uploadSettings,
-    fileMetadata,
-    overwrite = false
-  } = options ?? {};
-  if (!overwrite) {
-    try {
-      const headCommand = new HeadObjectCommand({
+import { HeadObjectCommand } from '@aws-sdk/client-s3';
+import { Upload } from '@aws-sdk/lib-storage';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Uploads a file stream to a specified Amazon S3 bucket using AWS SDK v3.
+ *
+ * If `overwrite` is false and the target file exists, upload is aborted.
+ *
+ * @param {S3Client} s3 - The AWS S3 v3 client instance.
+ * @param {string} bucketName - The S3 bucket name.
+ * @param {string} targetPath - The key to upload the file to.
+ * @param {Readable} fileStream - The file content as a stream.
+ * @param {UploadOptions} [options] - Optional configuration.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ */
+export async function upload(s3, bucketName, targetPath, fileStream, options) {
+    const { uploadSettings, fileMetadata, overwrite = false } = options ?? {};
+    if (!overwrite) {
+        try {
+            const headCommand = new HeadObjectCommand({
+                Bucket: bucketName,
+                Key: targetPath
+            });
+            await s3.send(headCommand);
+            // If no error, object exists
+            return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+        }
+        catch (err) {
+            const code = err?.name ?? err?.$metadata?.httpStatusCode;
+            if (code !== 'NotFound' && code !== 404) {
+                return Outcome.makeFailure(unknownToString(err));
+            }
+            // Object not found, proceed with upload
+        }
+    }
+    const params = {
+        ...fileMetadata,
         Bucket: bucketName,
-        Key: targetPath
-      });
-      await s3.send(headCommand);
-      return makeFailure(`File already exists at ${targetPath}.`);
-    } catch (err) {
-      const code = err?.name ?? err?.$metadata?.httpStatusCode;
-      if (code !== "NotFound" && code !== 404) {
-        return makeFailure(unknownToString(err));
-      }
+        Key: targetPath,
+        Body: fileStream
+    };
+    try {
+        const upload = new Upload({
+            client: s3,
+            params,
+            ...uploadSettings
+        });
+        await upload.done();
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-  }
-  const params = {
-    ...fileMetadata,
-    Bucket: bucketName,
-    Key: targetPath,
-    Body: fileStream
-  };
-  try {
-    const upload2 = new Upload({
-      client: s3,
-      params,
-      ...uploadSettings
-    });
-    await upload2.done();
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  upload
-};

package/node/@design-edito/index.js

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

package/node/@express/@multer/index.js

@@ -1,57 +1,63 @@
-// src/node/@express/@multer/index.ts
-import multer from "multer";
-
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
-}
-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/@express/@multer/index.ts
-async function useMulterMiddleware(req, res, options) {
-  const { storage, limits, fileFilter } = options;
-  const uploader = multer({
-    storage: storage ?? multer.memoryStorage(),
-    limits,
-    fileFilter
-  });
-  let middleware;
-  if (options.mode === "none") {
-    middleware = uploader.none();
-  } else if (options.mode === "single") {
-    middleware = uploader.single(options.fieldName);
-  } else if (options.mode === "array") {
-    middleware = uploader.array(options.fieldName, options.maxCount);
-  } else if (options.mode === "fields") {
-    middleware = uploader.fields(options.fields);
-  } else {
-    middleware = uploader.any();
-  }
-  return await new Promise((resolve) => middleware(req, res, (err) => {
-    if (err instanceof multer.MulterError) return resolve(makeFailure({
-      code: err.code,
-      message: err.message,
-      field: err.field
+import multer from 'multer';
+import * as Outcome from '../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Applies multer middleware to an Express request/response pair.
+ *
+ * The function creates a multer instance based on the provided options and
+ * applies the appropriate middleware based on the upload mode. Errors are
+ * captured and returned as a structured `WithMulterError` object.
+ *
+ * @param {Request} req                    - The Express request object.
+ * @param {Response} res                   - The Express response object.
+ * @param {WithMulterOptions} options      - Multer configuration and upload mode.
+ * @param {multer.StorageEngine} [options.storage] - Storage engine (defaults to memory).
+ * @param {multer.Options['limits']} [options.limits] - File size and count limits.
+ * @param {multer.Options['fileFilter']} [options.fileFilter] - File filter function.
+ * @param {'none'|'any'|'single'|'array'|'fields'} options.mode - Upload mode.
+ * @param {string} [options.fieldName]     - Field name (required for 'single' and 'array' modes).
+ * @param {number} [options.maxCount]      - Max file count (for 'array' mode).
+ * @param {multer.Field[]} [options.fields] - Field configurations (for 'fields' mode).
+ * @returns {Promise<Outcome.Either<true, WithMulterError>>}
+ * - On success:  `Outcome.makeSuccess(true)`.
+ * - On failure:  `Outcome.makeFailure(error)` with structured error details.
+ */
+export async function useMulterMiddleware(req, res, options) {
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    const { storage, limits, fileFilter } = options;
+    const uploader = multer({
+        storage: storage ?? multer.memoryStorage(),
+        limits,
+        fileFilter
+    });
+    let middleware;
+    if (options.mode === 'none') {
+        middleware = uploader.none();
+    }
+    else if (options.mode === 'single') {
+        middleware = uploader.single(options.fieldName);
+    }
+    else if (options.mode === 'array') {
+        middleware = uploader.array(options.fieldName, options.maxCount);
+    }
+    else if (options.mode === 'fields') {
+        middleware = uploader.fields(options.fields);
+    }
+    else {
+        middleware = uploader.any();
+    }
+    return await new Promise(resolve => middleware(req, res, (err) => {
+        if (err instanceof multer.MulterError)
+            return resolve(Outcome.makeFailure({
+                code: err.code,
+                message: err.message,
+                field: err.field
+            }));
+        return resolve(err !== undefined
+            ? Outcome.makeFailure({
+                code: 'UNKNOWN',
+                message: unknownToString(err)
+            })
+            : Outcome.makeSuccess(true));
     }));
-    return resolve(
-      err !== void 0 ? makeFailure({
-        code: "UNKNOWN",
-        message: unknownToString(err)
-      }) : makeSuccess(true)
-    );
-  }));
 }
-export {
-  useMulterMiddleware
-};

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

@@ -1,30 +1,26 @@
-// 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';
+/**
+ * Retrieves metadata for a Google Cloud Storage bucket.
+ *
+ * This function calls the Google Cloud Storage API to get information about the bucket,
+ * such as its location, storage class, and other configuration details.
+ *
+ * @param {Bucket} bucket - The Google Cloud Storage bucket object.
+ * @param {GetBucketMetadataOptions} [options] - Optional configuration options to pass to the `getMetadata` method.
+ * @returns {Promise<Outcome.Either<BucketMetadata, string>>} A promise that resolves to an `Outcome.Either`.
+ * - On success: `Outcome.makeSuccess(metadata)` with the bucket metadata.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message.
+ *
+ * @throws {Error} Throws an error if the metadata retrieval fails (e.g., network issues, incorrect permissions).
+ */
+export async function getMetadata(bucket, options) {
+    try {
+        const [metadata] = await bucket.getMetadata(options);
+        return Outcome.makeSuccess(metadata);
+    }
+    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/bucket/get-metadata/index.ts
-async function getMetadata(bucket, options) {
-  try {
-    const [metadata] = await bucket.getMetadata(options);
-    return makeSuccess(metadata);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
-}
-export {
-  getMetadata
-};

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

@@ -1,44 +1,38 @@
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
-}
-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/directory/copy-dir/index.ts
-async function copyDir(bucket, sourceDir, targetDir, options) {
-  const { getFileOptions, copyOptions, overwrite = false } = options ?? {};
-  const from = sourceDir.endsWith("/") ? sourceDir : `${sourceDir}/`;
-  const to = targetDir.endsWith("/") ? targetDir : `${targetDir}/`;
-  try {
-    const [files] = await bucket.getFiles({ ...getFileOptions, prefix: from });
-    for (const f of files) {
-      const rel = f.name.substring(from.length);
-      const dest = `${to}${rel}`;
-      if (!overwrite) {
-        const destFile = bucket.file(dest);
-        const [exists] = await destFile.exists();
-        if (exists) {
-          continue;
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/** Recursively copies every object under `sourceDir` to the same relative path
+ *  beneath `targetDir` within a single GCS bucket.
+ * @param {Bucket} bucket - The GCS bucket instance.
+ * @param {string} sourceDir - The source directory path (prefix) to copy from.
+ * @param {string} targetDir - The target directory path (prefix) to copy to.
+ * @param {CopyDirOptions} [options] - Optional parameters for the operation.
+ * @param {boolean} [options.overwrite=false] - Whether to overwrite existing files at target.
+ * @returns {Promise<Outcome.Either<true, string>>} A promise that resolves to an `Outcome.Either`:
+ * - On success: `Outcome.makeSuccess(true)` indicating the copy was successful.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message if the copy fails.
+ * */
+export async function copyDir(bucket, sourceDir, targetDir, options) {
+    const { getFileOptions, copyOptions, overwrite = false } = options ?? {};
+    const from = sourceDir.endsWith('/') ? sourceDir : `${sourceDir}/`;
+    const to = targetDir.endsWith('/') ? targetDir : `${targetDir}/`;
+    try {
+        const [files] = await bucket.getFiles({ ...getFileOptions, prefix: from });
+        for (const f of files) {
+            const rel = f.name.substring(from.length);
+            const dest = `${to}${rel}`;
+            if (!overwrite) {
+                const destFile = bucket.file(dest);
+                const [exists] = await destFile.exists();
+                if (exists) {
+                    // Skip copy if target exists and overwrite is false
+                    continue;
+                }
+            }
+            await f.copy(dest, copyOptions);
         }
-      }
-      await f.copy(dest, copyOptions);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  copyDir
-};

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

@@ -1,4 +1,4 @@
+export * as copyDir from './copy-dir/index.js'
 export * as list from './list/index.js'
 export * as moveDir from './move-dir/index.js'
-export * as copyDir from './copy-dir/index.js'
 export * as removeDir from './remove-dir/index.js'

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

@@ -1,4 +1,4 @@
+export * as copyDir from './copy-dir/index.js'
 export * as list from './list/index.js'
 export * as moveDir from './move-dir/index.js'
-export * as copyDir from './copy-dir/index.js'
 export * as removeDir from './remove-dir/index.js'

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

@@ -1,36 +1,29 @@
-// 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';
+/**
+ * Lists all direct children file paths under a given directory prefix in a GCS bucket.
+ *
+ * This function returns only the immediate files (not recursive) under the specified directory prefix.
+ *
+ * @param {Bucket} bucket - The GCS bucket to list files from.
+ * @param {string} directoryPath - The directory prefix to list files under.
+ * @param {ListOptions} [options] - Optional configuration for the listing.
+ * @param {FileOptions} [options.fileOptions] - Additional options for file retrieval.
+ * @returns {Promise<Outcome.Either<string[], string>>} Returns either a success with an array of file paths, or a failure with an error message.
+ */
+export async function list(bucket, directoryPath, options) {
+    const { fileOptions } = options ?? {};
+    try {
+        const prefix = directoryPath.endsWith('/') ? directoryPath : `${directoryPath}/`;
+        const [files] = await bucket.getFiles({
+            prefix,
+            delimiter: '/',
+            ...fileOptions
+        });
+        const paths = files.map(file => file.name);
+        return Outcome.makeSuccess(paths);
+    }
+    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/directory/list/index.ts
-async function list(bucket, directoryPath, options) {
-  const { fileOptions } = options ?? {};
-  try {
-    const prefix = directoryPath.endsWith("/") ? directoryPath : `${directoryPath}/`;
-    const [files] = await bucket.getFiles({
-      prefix,
-      delimiter: "/",
-      ...fileOptions
-    });
-    const paths = files.map((file) => file.name);
-    return makeSuccess(paths);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
-}
-export {
-  list
-};

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

@@ -1,44 +1,45 @@
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
-}
-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/directory/move-dir/index.ts
-async function moveDir(bucket, sourceDir, targetDir, options) {
-  const { fileOptions, copyOptions, deleteOptions, overwrite = false } = options ?? {};
-  const from = sourceDir.endsWith("/") ? sourceDir : `${sourceDir}/`;
-  const to = targetDir.endsWith("/") ? targetDir : `${targetDir}/`;
-  try {
-    const [files] = await bucket.getFiles({ prefix: from });
-    for (const f of files) {
-      const rel = f.name.substring(from.length);
-      const dest = `${to}${rel}`;
-      const srcFile = bucket.file(f.name, fileOptions);
-      const destFile = bucket.file(dest, fileOptions);
-      if (!overwrite) {
-        const [exists] = await destFile.exists();
-        if (exists) throw new Error(`File already exists at ${dest}.`);
-      }
-      await srcFile.copy(dest, copyOptions);
-      await srcFile.delete(deleteOptions);
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Recursively moves every object under `sourceDir` to the corresponding path
+ * under `targetDir` within the same bucket.
+ *
+ * Example: moving `a/b/` to `x/y/` copies
+ * `a/b/file.txt` → `x/y/file.txt` and then deletes the original.
+ *
+ * If `overwrite` is false (default), the operation aborts if any destination file
+ * already exists.
+ *
+ * @param {Bucket} bucket - The GCS bucket instance.
+ * @param {string} sourceDir - The source directory prefix to move from.
+ * @param {string} targetDir - The target directory prefix to move to.
+ * @param {MoveDirOptions} [options] - Optional parameters for the operation.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success: `Outcome.makeSuccess(true)`.
+ * - On failure: `Outcome.makeFailure(errStr)`.
+ */
+export async function moveDir(bucket, sourceDir, targetDir, options) {
+    const { fileOptions, copyOptions, deleteOptions, overwrite = false } = options ?? {};
+    const from = sourceDir.endsWith('/') ? sourceDir : `${sourceDir}/`;
+    const to = targetDir.endsWith('/') ? targetDir : `${targetDir}/`;
+    try {
+        const [files] = await bucket.getFiles({ prefix: from });
+        for (const f of files) {
+            const rel = f.name.substring(from.length);
+            const dest = `${to}${rel}`;
+            const srcFile = bucket.file(f.name, fileOptions);
+            const destFile = bucket.file(dest, fileOptions);
+            if (!overwrite) {
+                const [exists] = await destFile.exists();
+                if (exists)
+                    throw new Error(`File already exists at ${dest}.`);
+            }
+            await srcFile.copy(dest, copyOptions);
+            await srcFile.delete(deleteOptions);
+        }
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  moveDir
-};