@design-edito/tools 0.4.5 → 0.4.11

package/node/@aws-s3/storage/directory/remove-dir/index.js

@@ -1,70 +1,59 @@
-// src/node/@aws-s3/storage/directory/remove-dir/index.ts
-import {
-  ListObjectsV2Command,
-  DeleteObjectsCommand
-} from "@aws-sdk/client-s3";
-
-// 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/directory/remove-dir/index.ts
-async function removeDir(client, bucketName, directoryPath, options) {
-  const {
-    listObjectsOptions,
-    deleteObjectsOptions,
-    ignoreMissing = true
-  } = options ?? {};
-  const prefix = directoryPath.endsWith("/") ? directoryPath : `${directoryPath}/`;
-  let continuationToken;
-  let anyFound = false;
-  try {
-    do {
-      const listResp = await client.send(
-        new ListObjectsV2Command({
-          Bucket: bucketName,
-          Prefix: prefix,
-          ContinuationToken: continuationToken,
-          ...listObjectsOptions
-        })
-      );
-      const keys = (listResp.Contents ?? []).map((o) => o.Key).filter((e) => e !== void 0);
-      if (keys.length > 0) {
-        anyFound = true;
-        for (let i = 0; i < keys.length; i += 1e3) {
-          const chunk = keys.slice(i, i + 1e3);
-          await client.send(
-            new DeleteObjectsCommand({
-              Bucket: bucketName,
-              Delete: { Objects: chunk.map((Key) => ({ Key })) },
-              ...deleteObjectsOptions
-            })
-          );
+import { ListObjectsV2Command, DeleteObjectsCommand } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Recursively deletes all objects under a directory prefix in an S3 bucket
+ * using the AWS SDK v3 client. Handles pagination and the 1 000‑key limit of
+ * `DeleteObjects`.
+ *
+ * @param {S3Client}  client           - The v3 S3 client instance.
+ * @param {string}    bucketName       - The name of the S3 bucket.
+ * @param {string}    directoryPath    - The “directory” prefix to delete.
+ * @param {RemoveDirOptions} [options] - Optional listing/deletion configuration.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success: `Outcome.makeSuccess(true)` – deletion succeeded, or prefix
+ *   absent and `ignoreMissing` is true.
+ * - On failure: `Outcome.makeFailure(errStr)` if deletion fails, or prefix
+ *   absent and `ignoreMissing` is false.
+ */
+export async function removeDir(client, bucketName, directoryPath, options) {
+    const { listObjectsOptions, deleteObjectsOptions, ignoreMissing = true } = options ?? {};
+    const prefix = directoryPath.endsWith('/') ? directoryPath : `${directoryPath}/`;
+    let continuationToken;
+    let anyFound = false;
+    try {
+        do {
+            const listResp = await client.send(new ListObjectsV2Command({
+                Bucket: bucketName,
+                Prefix: prefix,
+                ContinuationToken: continuationToken,
+                ...listObjectsOptions
+            }));
+            const keys = (listResp.Contents ?? [])
+                .map(o => o.Key)
+                .filter(e => e !== undefined);
+            if (keys.length > 0) {
+                anyFound = true;
+                // Delete in batches of ≤ 1 000 keys
+                for (let i = 0; i < keys.length; i += 1000) {
+                    const chunk = keys.slice(i, i + 1000);
+                    await client.send(new DeleteObjectsCommand({
+                        Bucket: bucketName,
+                        Delete: { Objects: chunk.map(Key => ({ Key })) },
+                        ...deleteObjectsOptions
+                    }));
+                }
+            }
+            continuationToken = listResp.IsTruncated === true
+                ? listResp.NextContinuationToken
+                : undefined;
+        } while (continuationToken !== undefined);
+        if (!anyFound && !ignoreMissing) {
+            return Outcome.makeFailure(`No objects found for prefix "${prefix}".`);
         }
-      }
-      continuationToken = listResp.IsTruncated === true ? listResp.NextContinuationToken : void 0;
-    } while (continuationToken !== void 0);
-    if (!anyFound && !ignoreMissing) {
-      return makeFailure(`No objects found for prefix "${prefix}".`);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  removeDir
-};

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

@@ -1,55 +1,43 @@
-// src/node/@aws-s3/storage/file/copy/index.ts
-import {
-  CopyObjectCommand,
-  HeadObjectCommand
-} from "@aws-sdk/client-s3";
-
-// 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/copy/index.ts
-async function copy(client, bucketName, sourcePath, targetPath, options) {
-  const {
-    copyOptions,
-    overwrite = false
-  } = options ?? {};
-  try {
-    if (!overwrite) {
-      try {
-        await client.send(new HeadObjectCommand({ Bucket: bucketName, Key: targetPath }));
-        return makeFailure(`Object already exists at ${targetPath}.`);
-      } catch (err) {
-        const notFound = err.$metadata?.httpStatusCode === 404 || err.name === "NotFound";
-        if (!notFound) throw err;
-      }
+import { CopyObjectCommand, 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';
+/**
+ * Copies an object from one key to another within the same S3 bucket.
+ *
+ * @param {S3Client} client            - The v3 S3 client instance.
+ * @param {string}   bucketName        - The name of the S3 bucket.
+ * @param {string}   sourcePath        - The key of the source object.
+ * @param {string}   targetPath        - The key where the object will be copied.
+ * @param {CopyOptions} [options]      - Optional copy configuration.
+ * @param {Omit<CopyObjectCommandInput,'Bucket'|'Key'|'CopySource'>} [options.copyOptions] - Extra copy params.
+ * @param {boolean} [options.overwrite=false] - Whether to overwrite an existing object.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success:  `Outcome.makeSuccess(true)`.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function copy(client, bucketName, sourcePath, targetPath, options) {
+    const { copyOptions, overwrite = false } = options ?? {};
+    try {
+        if (!overwrite) {
+            try {
+                await client.send(new HeadObjectCommand({ Bucket: bucketName, Key: targetPath }));
+                return Outcome.makeFailure(`Object already exists at ${targetPath}.`);
+            }
+            catch (err) {
+                const notFound = err.$metadata?.httpStatusCode === 404 || err.name === 'NotFound';
+                if (!notFound)
+                    throw err; // propagate unexpected errors
+            }
+        }
+        await client.send(new CopyObjectCommand({
+            Bucket: bucketName,
+            Key: targetPath,
+            CopySource: `${bucketName}/${sourcePath}`,
+            ...copyOptions
+        }));
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    await client.send(
-      new CopyObjectCommand({
-        Bucket: bucketName,
-        Key: targetPath,
-        CopySource: `${bucketName}/${sourcePath}`,
-        ...copyOptions
-      })
-    );
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  copy
-};

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

@@ -1,41 +1,30 @@
-// src/node/@aws-s3/storage/file/download/index.ts
-import {
-  GetObjectCommand
-} from "@aws-sdk/client-s3";
-
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
+import { GetObjectCommand } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Downloads a file from a specified Amazon S3 bucket.
+ *
+ * The function streams the object’s content back as a Node `Readable`.
+ *
+ * @param {S3Client} client       - The v3 S3 client instance.
+ * @param {string}   bucketName   - The name of the S3 bucket.
+ * @param {string}   sourcePath   - The key of the object to download.
+ * @param {DownloadOptions} [options] - Extra parameters for the download.
+ * @returns {Promise<Outcome.Either<Readable, string>>}
+ * - On success:  `Outcome.makeSuccess(stream)` containing the file content.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function download(client, bucketName, sourcePath, options) {
+    try {
+        const response = await client.send(new GetObjectCommand({
+            Bucket: bucketName,
+            Key: sourcePath,
+            ...options
+        }));
+        const stream = response.Body;
+        return Outcome.makeSuccess(stream);
+    }
+    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/@aws-s3/storage/file/download/index.ts
-async function download(client, bucketName, sourcePath, options) {
-  try {
-    const response = await client.send(
-      new GetObjectCommand({
-        Bucket: bucketName,
-        Key: sourcePath,
-        ...options
-      })
-    );
-    const stream = response.Body;
-    return makeSuccess(stream);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
-}
-export {
-  download
-};

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

@@ -1,45 +1,37 @@
-// src/node/@aws-s3/storage/file/exists/index.ts
-import {
-  HeadObjectCommand
-} from "@aws-sdk/client-s3";
-
-// 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/exists/index.ts
-async function exists(client, bucketName, sourcePath, options) {
-  const { headObjectOptions } = options ?? {};
-  try {
-    await client.send(
-      new HeadObjectCommand({
-        Bucket: bucketName,
-        Key: sourcePath,
-        ...headObjectOptions
-      })
-    );
-    return makeSuccess(true);
-  } catch (err) {
-    const notFound = err.$metadata?.httpStatusCode === 404 || err.name === "NotFound" || err.Code === "NotFound" || err.Code === "NoSuchKey";
-    if (notFound) {
-      return makeSuccess(false);
+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';
+/**
+ * Checks whether an object exists in a specified S3 bucket (AWS SDK v3).
+ *
+ * @param {S3Client} client          - The v3 S3 client instance.
+ * @param {string}   bucketName      - The name of the S3 bucket.
+ * @param {string}   sourcePath      - The key of the object to test.
+ * @param {ExistsOptions} [options]  - Optional configuration.
+ * @param {Omit<HeadObjectCommandInput,'Bucket'|'Key'>} [options.headObjectOptions] - Extra `HeadObject` params.
+ * @returns {Promise<Outcome.Either<boolean, string>>}
+ * - Success: `Outcome.makeSuccess(true)` if the object exists,
+ *            `Outcome.makeSuccess(false)` if it does not.
+ * - Failure: `Outcome.makeFailure(errStr)` for unexpected errors.
+ */
+export async function exists(client, bucketName, sourcePath, options) {
+    const { headObjectOptions } = options ?? {};
+    try {
+        await client.send(new HeadObjectCommand({
+            Bucket: bucketName,
+            Key: sourcePath,
+            ...headObjectOptions
+        }));
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        const notFound = err.$metadata?.httpStatusCode === 404
+            || err.name === 'NotFound'
+            || err.Code === 'NotFound' // some SDKs emit Code
+            || err.Code === 'NoSuchKey';
+        if (notFound) {
+            return Outcome.makeSuccess(false);
+        }
+        return Outcome.makeFailure(unknownToString(err));
     }
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  exists
-};

package/node/@aws-s3/storage/file/index.d.ts

@@ -1,5 +1,5 @@
-export * as download from './download/index.js'
 export * as copy from './copy/index.js'
+export * as download from './download/index.js'
 export * as exists from './exists/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'

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

@@ -1,5 +1,5 @@
-export * as download from './download/index.js'
 export * as copy from './copy/index.js'
+export * as download from './download/index.js'
 export * as exists from './exists/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'

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

@@ -1,66 +1,60 @@
-// src/node/@aws-s3/storage/file/move/index.ts
-import {
-  HeadObjectCommand,
-  CopyObjectCommand,
-  DeleteObjectCommand
-} from "@aws-sdk/client-s3";
-
-// 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/move/index.ts
-async function move(client, bucketName, sourcePath, targetPath, options) {
-  const {
-    copyOptions,
-    deleteOptions,
-    overwrite = false
-  } = options ?? {};
-  try {
-    if (!overwrite) {
-      try {
-        await client.send(new HeadObjectCommand({ Bucket: bucketName, Key: targetPath }));
-        return makeFailure(`Object already exists at ${targetPath}.`);
-      } catch (err) {
-        const notFound = err.$metadata?.httpStatusCode === 404 || err.name === "NotFound" || err.Code === "NotFound" || err.Code === "NoSuchKey";
-        if (!notFound) {
-          return makeFailure(unknownToString(err));
+import { HeadObjectCommand, CopyObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Moves an object from one key to another within the same S3 bucket (AWS SDK v3).
+ *
+ * The function copies the object from `sourcePath` to `targetPath` and, upon
+ * successful copy, deletes the original object.
+ *
+ * @param {S3Client} client - The S3 client instance.
+ * @param {string}   bucketName - The name of the bucket.
+ * @param {string}   sourcePath - The source object's key.
+ * @param {string}   targetPath - The destination object's key.
+ * @param {MoveOptions} [options] - Optional copy/delete behaviour.
+ * @param {Omit<CopyObjectCommandInput,'Bucket'|'Key'|'CopySource'>} [options.copyOptions]   - Extra copy params.
+ * @param {Omit<DeleteObjectCommandInput,'Bucket'|'Key'>}            [options.deleteOptions] - Extra delete params.
+ * @param {boolean} [options.overwrite=false] - Whether to overwrite an existing `targetPath`.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - Success: `Outcome.makeSuccess(true)`
+ * - Failure: `Outcome.makeFailure(errStr)`
+ */
+export async function move(client, bucketName, sourcePath, targetPath, options) {
+    const { copyOptions, deleteOptions, overwrite = false } = options ?? {};
+    try {
+        // Abort early if destination exists and overwrite is disabled
+        if (!overwrite) {
+            try {
+                await client.send(new HeadObjectCommand({ Bucket: bucketName, Key: targetPath }));
+                return Outcome.makeFailure(`Object already exists at ${targetPath}.`);
+            }
+            catch (err) {
+                const notFound = err.$metadata?.httpStatusCode === 404
+                    || err.name === 'NotFound'
+                    || err.Code === 'NotFound'
+                    || err.Code === 'NoSuchKey';
+                if (!notFound) {
+                    return Outcome.makeFailure(unknownToString(err));
+                }
+                // If not found, proceed with copy
+            }
         }
-      }
+        // Copy to the new key
+        await client.send(new CopyObjectCommand({
+            Bucket: bucketName,
+            Key: targetPath,
+            CopySource: `${bucketName}/${sourcePath}`,
+            ...copyOptions
+        }));
+        // Delete the original key
+        await client.send(new DeleteObjectCommand({
+            Bucket: bucketName,
+            Key: sourcePath,
+            ...deleteOptions
+        }));
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    await client.send(
-      new CopyObjectCommand({
-        Bucket: bucketName,
-        Key: targetPath,
-        CopySource: `${bucketName}/${sourcePath}`,
-        ...copyOptions
-      })
-    );
-    await client.send(
-      new DeleteObjectCommand({
-        Bucket: bucketName,
-        Key: sourcePath,
-        ...deleteOptions
-      })
-    );
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  move
-};

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

@@ -1,46 +1,38 @@
-// src/node/@aws-s3/storage/file/remove/index.ts
-import {
-  HeadObjectCommand,
-  DeleteObjectCommand
-} from "@aws-sdk/client-s3";
-
-// 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/remove/index.ts
-async function remove(s3, bucketName, targetPath, options) {
-  const { ignoreMissing = true } = options ?? {};
-  try {
+import { HeadObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Removes a file from a specified Amazon S3 bucket (AWS SDK v3).
+ *
+ * If `ignoreMissing` is true (default), a missing object is considered success.
+ *
+ * @param {S3Client} s3 - The AWS S3 client instance.
+ * @param {string} bucketName - The name of the bucket.
+ * @param {string} targetPath - The key of the object to delete.
+ * @param {RemoveOptions} [options] - Optional settings.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ */
+export async function remove(s3, bucketName, targetPath, options) {
+    const { ignoreMissing = true } = options ?? {};
     try {
-      await s3.send(new HeadObjectCommand({ Bucket: bucketName, Key: targetPath }));
-    } catch (err) {
-      const code = err?.name ?? err?.Code ?? err?.code;
-      if (code === "NotFound" || code === "NoSuchKey" || code === "NotFoundException") {
-        if (ignoreMissing) return makeSuccess(true);
-        return makeFailure(`File not found at ${targetPath}.`);
-      }
-      return makeFailure(unknownToString(err));
+        // Check if object exists, respecting ignoreMissing
+        try {
+            await s3.send(new HeadObjectCommand({ Bucket: bucketName, Key: targetPath }));
+        }
+        catch (err) {
+            const code = err?.name ?? err?.Code ?? err?.code;
+            if (code === 'NotFound' || code === 'NoSuchKey' || code === 'NotFoundException') {
+                if (ignoreMissing)
+                    return Outcome.makeSuccess(true);
+                return Outcome.makeFailure(`File not found at ${targetPath}.`);
+            }
+            return Outcome.makeFailure(unknownToString(err));
+        }
+        // Delete the object
+        await s3.send(new DeleteObjectCommand({ Bucket: bucketName, Key: targetPath }));
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    await s3.send(new DeleteObjectCommand({ Bucket: bucketName, Key: targetPath }));
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  remove
-};