@design-edito/tools 0.4.5 → 0.4.6

package/node/ftps/file/move/index.js

@@ -1,47 +1,49 @@
-// 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/ftps/file/move/index.ts
-async function move(ftpClient, sourcePath, targetPath, options) {
-  const {
-    ensureDir = true,
-    overwrite = false
-  } = options ?? {};
-  try {
-    if (ensureDir) {
-      const dirPath = targetPath.substring(0, targetPath.lastIndexOf("/"));
-      await ftpClient.ensureDir(dirPath);
-    }
-    if (!overwrite) {
-      try {
-        await ftpClient.size(targetPath);
-        return makeFailure(`File already exists at ${targetPath}.`);
-      } catch (err) {
-        if (err.code !== 550) {
-          return makeFailure(unknownToString(err));
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+/**
+ * Moves (renames) a file on an FTP server.
+ *
+ * The function performs a simple `rename` operation, which moves the file from
+ * `sourcePath` to `targetPath`.  It supports two safety features:
+ *
+ * 1. **ensureDir** – If enabled, the parent directory of `targetPath`
+ *    is created with `ftpClient.ensureDir` before the rename.
+ * 2. **overwrite** – If disabled (default) the function first checks whether
+ *    an object already exists at `targetPath`; if so, it aborts.
+ *
+ * @param {Client} ftpClient  - The basic‑ftp client instance.
+ * @param {string} sourcePath - The full path of the source file.
+ * @param {string} targetPath - The full destination path.
+ * @param {MoveOptions} [options] - Optional move configuration.
+ * @param {boolean} [options.ensureDir=true]  - Whether to create missing parent directories.
+ * @param {boolean} [options.overwrite=false] - Whether to overwrite an existing destination.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success: `Outcome.makeSuccess(true)`.
+ * - On failure: `Outcome.makeFailure(errStr)`.
+ */
+export async function move(ftpClient, sourcePath, targetPath, options) {
+    const { ensureDir = true, overwrite = false } = options ?? {};
+    try {
+        if (ensureDir) {
+            const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+            await ftpClient.ensureDir(dirPath);
+        }
+        if (!overwrite) {
+            try {
+                await ftpClient.size(targetPath); // will succeed if file exists
+                return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+            }
+            catch (err) {
+                if (err.code !== 550) { // 550 = "not found"; any other error -> propagate
+                    return Outcome.makeFailure(unknownToString(err));
+                }
+                // 550 means destination does not exist – proceed
+            }
         }
-      }
+        await ftpClient.rename(sourcePath, targetPath);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    await ftpClient.rename(sourcePath, targetPath);
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  move
-};

package/node/ftps/file/remove/index.js

@@ -1,43 +1,40 @@
-// 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/ftps/file/remove/index.ts
-async function remove(ftpClient, targetPath, options) {
-  const { ignoreMissing = true } = options ?? {};
-  try {
-    let fileExists = true;
+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 FTP server.
+ *
+ * This function removes the file located at the given path on the FTP server.
+ * The deletion process can be customized using optional delete options.
+ * If the `ignoreMissing` option is true, it does not treat a missing file as an error.
+ *
+ * @param {Client} ftpClient - The basic-ftp client instance used to interact with the FTP server.
+ * @param {string} targetPath - The path of the file to delete on the FTP server.
+ * @param {RemoveOptions} [options] - Optional settings for configuring the deletion process.
+ * @returns {Promise<Outcome.Either<true, string>>} A promise that resolves to an Outcome.Either.
+ * - On success: Outcome.makeSuccess(true) indicating the deletion was successful.
+ * - On failure: Outcome.makeFailure(errStr) with an error message if the deletion fails.
+ */
+export async function remove(ftpClient, targetPath, options) {
+    const { ignoreMissing = true } = options ?? {};
     try {
-      await ftpClient.size(targetPath);
-    } catch {
-      fileExists = false;
+        let fileExists = true;
+        try {
+            await ftpClient.size(targetPath);
+        }
+        catch {
+            fileExists = false;
+        }
+        if (!fileExists) {
+            if (ignoreMissing) {
+                return Outcome.makeSuccess(true);
+            }
+            return Outcome.makeFailure(`File not found at ${targetPath}.`);
+        }
+        await ftpClient.remove(targetPath);
+        return Outcome.makeSuccess(true);
     }
-    if (!fileExists) {
-      if (ignoreMissing) {
-        return makeSuccess(true);
-      }
-      return makeFailure(`File not found at ${targetPath}.`);
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
     }
-    await ftpClient.remove(targetPath);
-    return makeSuccess(true);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
 }
-export {
-  remove
-};

package/node/ftps/file/stat/index.js

@@ -1,39 +1,31 @@
-// 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 file on an FTP server by listing its parent
+ * directory and matching the entry.
+ *
+ * @param {FtpClient} ftp – basic‑ftp client.
+ * @param {string} path  – Remote file path.
+ * @returns {Promise<Outcome.Either<Stat, string>>}
+ */
+export async function stat(ftp, path) {
+    try {
+        const slash = path.lastIndexOf('/');
+        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+        const dir = slash === -1 ? '.' : path.slice(0, slash) || '/';
+        const name = slash === -1 ? path : path.slice(slash + 1);
+        const list = await ftp.list(dir);
+        const entry = list.find(e => e.name === name && e.isFile);
+        if (entry === undefined)
+            return Outcome.makeFailure(`File not found: ${path}`);
+        return Outcome.makeSuccess({
+            size: entry.size,
+            modifiedAt: entry.modifiedAt ?? undefined,
+            permissions: entry.rawModifiedAt.toString(),
+            raw: entry
+        });
+    }
+    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/ftps/file/stat/index.ts
-async function stat(ftp, path) {
-  try {
-    const slash = path.lastIndexOf("/");
-    const dir = slash === -1 ? "." : path.slice(0, slash) || "/";
-    const name = slash === -1 ? path : path.slice(slash + 1);
-    const list = await ftp.list(dir);
-    const entry = list.find((e) => e.name === name && e.isFile);
-    if (entry === void 0) return makeFailure(`File not found: ${path}`);
-    return makeSuccess({
-      size: entry.size,
-      modifiedAt: entry.modifiedAt ?? void 0,
-      permissions: entry.rawModifiedAt.toString(),
-      raw: entry
-    });
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
-}
-export {
-  stat
-};

package/node/ftps/file/upload/index.js

@@ -1,48 +1,44 @@
-// 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/ftps/file/upload/index.ts
-async function upload(ftpClient, targetPath, fileStream, options) {
-  const {
-    ensureDir = true,
-    overwrite = false
-  } = options ?? {};
-  try {
-    if (ensureDir) {
-      const dirPath = targetPath.substring(0, targetPath.lastIndexOf("/"));
-      await ftpClient.ensureDir(dirPath);
-    }
-    let fileExists = false;
+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 FTP server.
+ *
+ * This function uploads the provided file stream to the given FTP server at the specified target path.
+ * The upload process can be customized using optional upload options.
+ * If the `ensureDir` option is true, it ensures that the target directory exists before uploading.
+ * If the `overwrite` option is false, it prevents overwriting an existing file.
+ *
+ * @param {Client} ftpClient - The basic-ftp client instance used to interact with the FTP server.
+ * @param {string} targetPath - The target path where the file will be stored on the FTP server.
+ * @param {Readable} fileStream - The file content to be uploaded.
+ * @param {UploadOptions} [options] - Optional settings for configuring 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(ftpClient, targetPath, fileStream, options) {
+    const { ensureDir = true, overwrite = false } = options ?? {};
     try {
-      await ftpClient.size(targetPath);
-      fileExists = true;
-    } catch {
-      fileExists = false;
+        if (ensureDir) {
+            const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+            await ftpClient.ensureDir(dirPath);
+        }
+        let fileExists = false;
+        try {
+            await ftpClient.size(targetPath);
+            fileExists = true;
+        }
+        catch {
+            fileExists = false;
+        }
+        if (fileExists && !overwrite) {
+            return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+        }
+        await ftpClient.uploadFrom(fileStream, targetPath, options);
+        return Outcome.makeSuccess(true);
     }
-    if (fileExists && !overwrite) {
-      return makeFailure(`File already exists at ${targetPath}.`);
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
     }
-    await ftpClient.uploadFrom(fileStream, targetPath, options);
-    return makeSuccess(true);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
 }
-export {
-  upload
-};