@design-edito/tools 0.4.5 → 0.4.6

package/node/ftps/directory/copy-dir/index.js

@@ -1,65 +1,58 @@
-// src/node/ftps/directory/copy-dir/index.ts
-import { PassThrough } from "node:stream";
-
-// 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/ftps/directory/copy-dir/index.ts
-async function copyDir(ftpClient, sourceDir, targetDir, options) {
-  const {
-    overwrite = false,
-    ensureDir = true
-  } = options ?? {};
-  async function recurse(dir) {
-    const list = await ftpClient.list(dir);
-    for (const entry of list) {
-      const src = dir.endsWith("/") ? dir + entry.name : dir + "/" + entry.name;
-      const rel = src.substring(sourceDir.length + (sourceDir.endsWith("/") ? 0 : 1));
-      const dst = targetDir.endsWith("/") ? targetDir + rel : `${targetDir}/${rel}`;
-      if (entry.isDirectory) {
-        if (ensureDir) await ftpClient.ensureDir(dst);
-        await recurse(src);
-      } else if (entry.isFile) {
-        if (!overwrite) {
-          try {
-            await ftpClient.size(dst);
-            throw new Error(`File already exists at ${dst}.`);
-          } catch {
-          }
+import { PassThrough } from 'node:stream';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Recursively copies every file under `sourceDir` to the same relative path
+ * beneath `targetDir` on an FTP server, streaming data to avoid buffering.
+ *
+ * @param {Client}  ftpClient  - The FTP client instance.
+ * @param {string}  sourceDir  - The source directory path to copy from.
+ * @param {string}  targetDir  - The target directory path to copy to.
+ * @param {CopyDirOptions} [options] - Optional parameters for the operation.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - Success: `Outcome.makeSuccess(true)` if the copy succeeds.
+ * - Failure: `Outcome.makeFailure(errStr)` if an error occurs.
+ */
+export async function copyDir(ftpClient, sourceDir, targetDir, options) {
+    const { overwrite = false, ensureDir = true } = options ?? {};
+    async function recurse(dir) {
+        const list = await ftpClient.list(dir);
+        for (const entry of list) {
+            const src = dir.endsWith('/') ? dir + entry.name : dir + '/' + entry.name;
+            const rel = src.substring(sourceDir.length + (sourceDir.endsWith('/') ? 0 : 1));
+            const dst = targetDir.endsWith('/') ? targetDir + rel : `${targetDir}/${rel}`;
+            if (entry.isDirectory) {
+                if (ensureDir)
+                    await ftpClient.ensureDir(dst);
+                await recurse(src);
+            }
+            else if (entry.isFile) {
+                if (!overwrite) {
+                    try {
+                        await ftpClient.size(dst);
+                        throw new Error(`File already exists at ${dst}.`);
+                    }
+                    catch { /* 550 “not found” – safe to proceed */ }
+                }
+                // Make sure parent directory exists if ensureDir is enabled
+                if (ensureDir) {
+                    const dirPath = dst.substring(0, dst.lastIndexOf('/'));
+                    await ftpClient.ensureDir(dirPath);
+                }
+                const pass = new PassThrough();
+                const upload = ftpClient.uploadFrom(pass, dst);
+                await ftpClient.downloadTo(pass, src);
+                await upload;
+            }
         }
-        if (ensureDir) {
-          const dirPath = dst.substring(0, dst.lastIndexOf("/"));
-          await ftpClient.ensureDir(dirPath);
-        }
-        const pass = new PassThrough();
-        const upload = ftpClient.uploadFrom(pass, dst);
-        await ftpClient.downloadTo(pass, src);
-        await upload;
-      }
     }
-  }
-  try {
-    if (ensureDir) await ftpClient.ensureDir(targetDir);
-    await recurse(sourceDir);
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
+    try {
+        if (ensureDir)
+            await ftpClient.ensureDir(targetDir);
+        await recurse(sourceDir);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
 }
-export {
-  copyDir
-};

package/node/ftps/directory/list/index.js

@@ -1,30 +1,25 @@
-// 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 files under a given directory on an FTP server.
+ *
+ * This function returns only the immediate files (not recursive) under the specified directory.
+ *
+ * @param {Client} ftpClient - The basic-ftp client instance used to interact with the FTP server.
+ * @param {string} directoryPath - The directory path to list files under.
+ * @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(ftpClient, directoryPath) {
+    try {
+        const list = await ftpClient.list(directoryPath);
+        const files = list
+            .filter(entry => entry.isFile)
+            .map(entry => (directoryPath.endsWith('/')
+            ? `${directoryPath}${entry.name}`
+            : `${directoryPath}/${entry.name}`));
+        return Outcome.makeSuccess(files);
+    }
+    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/directory/list/index.ts
-async function list(ftpClient, directoryPath) {
-  try {
-    const list2 = await ftpClient.list(directoryPath);
-    const files = list2.filter((entry) => entry.isFile).map((entry) => directoryPath.endsWith("/") ? `${directoryPath}${entry.name}` : `${directoryPath}/${entry.name}`);
-    return makeSuccess(files);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
-}
-export {
-  list
-};

package/node/ftps/directory/move-dir/index.js

@@ -1,41 +1,41 @@
-// 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/ftps/directory/move-dir/index.ts
-async function moveDir(ftpClient, sourceDir, targetDir, options) {
-  const { overwrite = false, ensureDir = true } = options ?? {};
-  try {
-    if (ensureDir) {
-      const parentDir = targetDir.substring(0, targetDir.lastIndexOf("/"));
-      await ftpClient.ensureDir(parentDir);
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Renames (moves) a directory on an FTP server.
+ * Most FTP servers allow `RNFR /path/old` + `RNTO /path/new` to move a tree
+ * atomically. Falling back to manual copy/delete would be expensive, so this
+ * util simply performs `rename`.
+ *
+ * If `ensureDir` is true (default), the parent directory of `targetDir` is
+ * created if it does not exist.
+ *
+ * @param {Client} ftpClient - The FTP client instance.
+ * @param {string} sourceDir - The source directory path to move from.
+ * @param {string} targetDir - The target directory path to move to.
+ * @param {MoveDirOptions} [options] - Optional parameters for the operation.
+ * @returns {Promise<Outcome.Either<true, string>>} A promise that resolves to an `Outcome.Either`:
+ * - On success: `Outcome.makeSuccess(true)` indicating the move was successful.
+ * - On failure: `Outcome.makeFailure(errStr)` with an error message if the move fails.
+ */
+export async function moveDir(ftpClient, sourceDir, targetDir, options) {
+    const { overwrite = false, ensureDir = true } = options ?? {};
+    try {
+        if (ensureDir) {
+            // ensure parent directory of targetDir exists
+            const parentDir = targetDir.substring(0, targetDir.lastIndexOf('/'));
+            await ftpClient.ensureDir(parentDir);
+        }
+        if (!overwrite) {
+            try {
+                await ftpClient.size(targetDir); // will throw 550 for dirs or missing
+                return Outcome.makeFailure(`Target ${targetDir} already exists.`);
+            }
+            catch { /* not found – ok */ }
+        }
+        await ftpClient.rename(sourceDir, targetDir);
+        return Outcome.makeSuccess(true);
     }
-    if (!overwrite) {
-      try {
-        await ftpClient.size(targetDir);
-        return makeFailure(`Target ${targetDir} already exists.`);
-      } catch {
-      }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    await ftpClient.rename(sourceDir, targetDir);
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  moveDir
-};

package/node/ftps/directory/remove-dir/index.js

@@ -1,45 +1,42 @@
-// 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/ftps/directory/remove-dir/index.ts
-async function removeDir(ftpClient, directoryPath, options) {
-  const { ignoreMissing = true } = options ?? {};
-  async function recurse(dir) {
-    const list = await ftpClient.list(dir);
-    for (const entry of list) {
-      const full = dir.endsWith("/") ? dir + entry.name : `${dir}/${entry.name}`;
-      if (entry.isDirectory) {
-        await recurse(full);
-      } else if (entry.isFile) {
-        await ftpClient.remove(full);
-      }
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Recursively deletes a directory (and all contents) on an FTP server.
+ *
+ * @param {Client} ftpClient            - The FTP client instance.
+ * @param {string} directoryPath        - The path of the directory to delete.
+ * @param {RemoveDirOptions} [options]  - Optional configuration.
+ * @param {boolean} [options.ignoreMissing=true] - Whether to ignore a missing directory.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success: `Outcome.makeSuccess(true)` – deletion succeeded, or directory
+ *   was absent and `ignoreMissing` is true.
+ * - On failure: `Outcome.makeFailure(errStr)` if deletion fails, or directory
+ *   absent and `ignoreMissing` is false.
+ */
+export async function removeDir(ftpClient, directoryPath, options) {
+    const { ignoreMissing = true } = options ?? {};
+    async function recurse(dir) {
+        const list = await ftpClient.list(dir);
+        for (const entry of list) {
+            const full = dir.endsWith('/') ? dir + entry.name : `${dir}/${entry.name}`;
+            if (entry.isDirectory) {
+                await recurse(full);
+            }
+            else if (entry.isFile) {
+                await ftpClient.remove(full);
+            }
+        }
+        await ftpClient.removeDir(dir);
+    }
+    try {
+        await recurse(directoryPath);
+        return Outcome.makeSuccess(true);
     }
-    await ftpClient.removeDir(dir);
-  }
-  try {
-    await recurse(directoryPath);
-    return makeSuccess(true);
-  } catch (err) {
-    if (ignoreMissing && err.code === 550) {
-      return makeSuccess(true);
+    catch (err) {
+        // 550 (“No such file or directory”) when the path is missing
+        if (ignoreMissing && err.code === 550) {
+            return Outcome.makeSuccess(true);
+        }
+        return Outcome.makeFailure(unknownToString(err));
     }
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  removeDir
-};

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

@@ -1,50 +1,45 @@
-// src/node/ftps/file/copy/index.ts
-import { PassThrough } from "node:stream";
-
-// 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/ftps/file/copy/index.ts
-async function copy(ftpClient, sourcePath, targetPath, options) {
-  const {
-    overwrite = false,
-    ensureDir = true
-  } = options ?? {};
-  try {
-    if (!overwrite) {
-      try {
-        await ftpClient.size(targetPath);
-        return makeFailure(`File already exists at ${targetPath}.`);
-      } catch {
-      }
+import { PassThrough } from 'node:stream';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Copies a file from one path to another on the same FTP server, streaming the
+ * data instead of buffering it in memory.
+ *
+ * @param {Client}  ftpClient  - The basic‑ftp client instance.
+ * @param {string}  sourcePath - The path of the source file.
+ * @param {string}  targetPath - The destination path.
+ * @param {CopyOptions} [options] - Optional copy configuration.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success:  `Outcome.makeSuccess(true)`.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function copy(ftpClient, sourcePath, targetPath, options) {
+    const { overwrite = false, ensureDir = true } = options ?? {};
+    try {
+        // Abort if destination exists and overwrite is disabled
+        if (!overwrite) {
+            try {
+                await ftpClient.size(targetPath);
+                return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+            }
+            catch { /* 550 = not found – safe to proceed */ }
+        }
+        // Create missing target directories if requested
+        if (ensureDir) {
+            const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+            await ftpClient.ensureDir(dirPath);
+        }
+        // Stream copy: download → PassThrough → upload
+        const pass = new PassThrough();
+        // Start the upload first so the server reads from `pass` as data arrives
+        const uploadPromise = ftpClient.uploadFrom(pass, targetPath);
+        // Pump data from source into `pass`
+        await ftpClient.downloadTo(pass, sourcePath);
+        // Wait until the upload completes
+        await uploadPromise;
+        return Outcome.makeSuccess(true);
     }
-    if (ensureDir) {
-      const dirPath = targetPath.substring(0, targetPath.lastIndexOf("/"));
-      await ftpClient.ensureDir(dirPath);
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    const pass = new PassThrough();
-    const uploadPromise = ftpClient.uploadFrom(pass, targetPath);
-    await ftpClient.downloadTo(pass, sourcePath);
-    await uploadPromise;
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  copy
-};

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

@@ -1,35 +1,30 @@
-// src/node/ftps/file/download/index.ts
-import { PassThrough } from "node:stream";
-
-// 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 { PassThrough } from 'node:stream';
+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 FTP server.
+ *
+ * This function downloads a file from the given FTP server at the specified source path,
+ * returning the file content as a Readable stream. The download process can be customized
+ * using optional download options.
+ *
+ * @param {Client} ftpClient - The basic-ftp client instance used to interact with the FTP server.
+ * @param {string} sourcePath - The path of the file to be downloaded from the FTP server.
+ * @param {DownloadOptions} [options] - Optional settings for configuring the download process.
+ * @param {number} [options.startAt] - The byte offset at which to start downloading the file.
+ * @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 stream.
+ * - On failure: Outcome.makeFailure(errStr) with an error message if the download fails.
+ */
+export async function download(ftpClient, sourcePath, options) {
+    const { startAt } = options ?? {};
+    const stream = new PassThrough();
+    try {
+        await ftpClient.downloadTo(stream, sourcePath, startAt);
+        return Outcome.makeSuccess(stream);
+    }
+    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/ftps/file/download/index.ts
-async function download(ftpClient, sourcePath, options) {
-  const { startAt } = options ?? {};
-  const stream = new PassThrough();
-  try {
-    await ftpClient.downloadTo(stream, sourcePath, startAt);
-    return makeSuccess(stream);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
-}
-export {
-  download
-};

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

@@ -1,37 +1,39 @@
-// src/node/ftps/file/exists/index.ts
-import { FileType } from "basic-ftp";
-
-// 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 { FileType } from 'basic-ftp';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+/**
+ * Checks if a *file* (not a directory) exists on a specified FTP server.
+ *
+ * `ftpClient.list(parentDir)` returns an array of `FileInfo` objects:
+ *   • `type === FileType.File`          → regular file
+ *   • `type === FileType.Directory`     → directory
+ *   • `type === FileType.SymbolicLink`  → symlink
+ *
+ * The function reports **true** only for `FileType.File` or
+ * `FileType.SymbolicLink`, mirroring the SFTP behaviour where `'-'` and `'l'`
+ * are considered files.
+ *
+ * @param {Client} ftpClient  - The basic‑ftp client instance.
+ * @param {string} sourcePath - The full path to check on the FTP server.
+ * @returns {Promise<Outcome.Either<boolean, string>>}
+ * - Success: `Outcome.makeSuccess(true | false)` – true only if a file exists.
+ * - Failure: `Outcome.makeFailure(errStr)` if an error occurs.
+ */
+export async function exists(ftpClient, sourcePath) {
+    try {
+        // Split path into parent dir and base name
+        const lastSlash = sourcePath.lastIndexOf('/');
+        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+        const parentDir = lastSlash === -1 ? '.' : sourcePath.slice(0, lastSlash) || '/';
+        const baseName = lastSlash === -1 ? sourcePath : sourcePath.slice(lastSlash + 1);
+        const list = await ftpClient.list(parentDir);
+        const entry = list.find(e => e.name === baseName);
+        const isFile = entry !== undefined
+            ? (entry.type === FileType.File || entry.type === FileType.SymbolicLink)
+            : false;
+        return Outcome.makeSuccess(isFile);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
 }
-
-// src/agnostic/misc/outcome/index.ts
-function makeSuccess(payload) {
-  return { success: true, payload };
-}
-function makeFailure(error) {
-  return { success: false, error };
-}
-
-// src/node/ftps/file/exists/index.ts
-async function exists(ftpClient, sourcePath) {
-  try {
-    const lastSlash = sourcePath.lastIndexOf("/");
-    const parentDir = lastSlash === -1 ? "." : sourcePath.slice(0, lastSlash) || "/";
-    const baseName = lastSlash === -1 ? sourcePath : sourcePath.slice(lastSlash + 1);
-    const list = await ftpClient.list(parentDir);
-    const entry = list.find((e) => e.name === baseName);
-    const isFile = entry !== void 0 ? entry.type === FileType.File || entry.type === FileType.SymbolicLink : false;
-    return makeSuccess(isFile);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
-}
-export {
-  exists
-};

package/node/ftps/file/index.d.ts

@@ -1,7 +1,7 @@
 export * as copy from './copy/index.js'
-export * as exists from './exists/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'
-export * as stat from './stat/index.js'
 export * as upload from './upload/index.js'
+export * as stat from './stat/index.js'

package/node/ftps/file/index.js

@@ -1,7 +1,7 @@
 export * as copy from './copy/index.js'
-export * as exists from './exists/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'
-export * as stat from './stat/index.js'
 export * as upload from './upload/index.js'
+export * as stat from './stat/index.js'