@design-edito/tools 0.4.5 → 0.4.11

package/node/sftp/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/sftp/directory/remove-dir/index.ts
-async function removeDir(sftp, directoryPath, options) {
-  const { ignoreMissing = true } = options ?? {};
-  async function recurse(dir) {
-    const list = await sftp.list(dir);
-    for (const entry of list) {
-      const full = dir.endsWith("/") ? dir + entry.name : `${dir}/${entry.name}`;
-      if (entry.type === "d") {
-        await recurse(full);
-      } else if (entry.type === "-") {
-        await sftp.delete(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 SFTP server.
+ *
+ * @param {Client}  sftp           - The SFTP 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 the
+ *   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(sftp, directoryPath, options) {
+    const { ignoreMissing = true } = options ?? {};
+    async function recurse(dir) {
+        const list = await sftp.list(dir);
+        for (const entry of list) {
+            const full = dir.endsWith('/') ? dir + entry.name : `${dir}/${entry.name}`;
+            if (entry.type === 'd') {
+                await recurse(full);
+            }
+            else if (entry.type === '-') {
+                await sftp.delete(full);
+            }
+        }
+        await sftp.rmdir(dir);
+    }
+    try {
+        await recurse(directoryPath);
+        return Outcome.makeSuccess(true);
     }
-    await sftp.rmdir(dir);
-  }
-  try {
-    await recurse(directoryPath);
-    return makeSuccess(true);
-  } catch (err) {
-    if (ignoreMissing && (err.code === 2 || err.code === "ENOENT")) {
-      return makeSuccess(true);
+    catch (err) {
+        // ssh2-sftp-client uses code 2 / ENOENT for “No such file or directory”
+        if (ignoreMissing && (err.code === 2 || err.code === 'ENOENT')) {
+            return Outcome.makeSuccess(true);
+        }
+        return Outcome.makeFailure(unknownToString(err));
     }
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  removeDir
-};

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

@@ -1,48 +1,40 @@
-// src/node/sftp/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/sftp/file/copy/index.ts
-async function copy(sftp, sourcePath, targetPath, options) {
-  const {
-    overwrite = false,
-    ensureDir = true,
-    ...transferOptions
-  } = options ?? {};
-  try {
-    if (!overwrite) {
-      const exists = await sftp.exists(targetPath);
-      if (exists !== false) return makeFailure(`File already exists at ${targetPath}.`);
+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 SFTP server using streams
+ * (avoids loading the entire file into memory).
+ *
+ * @param {Client}  sftp       - The ssh2‑sftp‑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(sftp, sourcePath, targetPath, options) {
+    const { overwrite = false, ensureDir = true, ...transferOptions } = options ?? {};
+    try {
+        // Abort if destination exists and overwrite is disabled
+        if (!overwrite) {
+            const exists = await sftp.exists(targetPath);
+            if (exists !== false)
+                return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+        }
+        // Create missing target directories if requested
+        if (ensureDir) {
+            const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+            await sftp.mkdir(dirPath, true);
+        }
+        // Stream copy: download → PassThrough → upload
+        const pass = new PassThrough();
+        const uploadPromise = sftp.put(pass, targetPath, transferOptions);
+        await sftp.get(sourcePath, pass, transferOptions);
+        await uploadPromise;
+        return Outcome.makeSuccess(true);
     }
-    if (ensureDir) {
-      const dirPath = targetPath.substring(0, targetPath.lastIndexOf("/"));
-      await sftp.mkdir(dirPath, true);
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    const pass = new PassThrough();
-    const uploadPromise = sftp.put(pass, targetPath, transferOptions);
-    await sftp.get(sourcePath, pass, transferOptions);
-    await uploadPromise;
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  copy
-};

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

@@ -1,33 +1,27 @@
-// 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';
+/**
+ * Downloads a file from a specified SFTP server.
+ *
+ * This function downloads a file from the given SFTP 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} sftp - The ssh2-sftp-client instance used to interact with the SFTP server.
+ * @param {string} sourcePath - The path of the file to be downloaded from the SFTP server.
+ * @param {DownloadOptions} [options] - Optional settings for configuring the download process.
+ * @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(sftp, sourcePath, options) {
+    try {
+        const stream = sftp.createReadStream(sourcePath, options);
+        stream.on('error', (err) => { throw err; });
+        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/sftp/file/download/index.ts
-async function download(sftp, sourcePath, options) {
-  try {
-    const stream = sftp.createReadStream(sourcePath, options);
-    stream.on("error", (err) => {
-      throw err;
-    });
-    return makeSuccess(stream);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
-}
-export {
-  download
-};

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

@@ -1,30 +1,30 @@
-// 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';
+/**
+ * Checks if a *file* (not a directory) exists on a specified SFTP server.
+ *
+ * `sftp.exists(path)` resolves to:
+ *   • `'d'` – the path exists and is a **directory**
+ *   • `'-'` – the path exists and is a **regular file**
+ *   • `'l'` – the path exists and is a **symlink**
+ *   • `false` – the path does **not** exist
+ *
+ * For the purpose of this util we treat a regular file (`'-'`) **or** a
+ * symlink (`'l'`) as a “file”. A directory (`'d'`) returns `false`.
+ *
+ * @param {Client} sftp        - The ssh2‑sftp‑client instance.
+ * @param {string} sourcePath  - The path to check.
+ * @returns {Promise<Outcome.Either<boolean, string>>}
+ * - Success: `Outcome.makeSuccess(true | false)` indicating file existence.
+ * - Failure: `Outcome.makeFailure(errStr)` if an error occurs.
+ */
+export async function exists(sftp, sourcePath) {
+    try {
+        const res = await sftp.exists(sourcePath); // 'd' | '-' | 'l' | false
+        const isFile = res === '-' || res === 'l';
+        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/sftp/file/exists/index.ts
-async function exists(sftp, sourcePath) {
-  try {
-    const res = await sftp.exists(sourcePath);
-    const isFile = res === "-" || res === "l";
-    return makeSuccess(isFile);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
-}
-export {
-  exists
-};

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

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

package/node/sftp/file/index.js

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

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

@@ -1,41 +1,42 @@
-// 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/sftp/file/move/index.ts
-async function move(sftp, sourcePath, targetPath, options) {
-  const {
-    ensureDir = true,
-    overwrite = false
-  } = options ?? {};
-  try {
-    if (ensureDir) {
-      const dirPath = targetPath.substring(0, targetPath.lastIndexOf("/"));
-      await sftp.mkdir(dirPath, true);
+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 SFTP server.
+ *
+ * The function uses `rename`, which atomically moves the file from
+ * `sourcePath` to `targetPath`.  It supports two safety features:
+ *
+ * 1. **ensureDir** – If enabled, the parent directory of `targetPath`
+ *    is created with `mkdir -p` semantics before the rename.
+ * 2. **overwrite** – If disabled (default) the function first checks whether
+ *    something already exists at `targetPath`; if so, it aborts.
+ *
+ * @param {Client} sftp          - The ssh2‑sftp‑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(sftp, sourcePath, targetPath, options) {
+    const { ensureDir = true, overwrite = false } = options ?? {};
+    try {
+        if (ensureDir) {
+            const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+            await sftp.mkdir(dirPath, true); // mkdir -p
+        }
+        if (!overwrite) {
+            const exists = await sftp.exists(targetPath) !== false;
+            if (exists)
+                return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+        }
+        await sftp.rename(sourcePath, targetPath);
+        return Outcome.makeSuccess(true);
     }
-    if (!overwrite) {
-      const exists = await sftp.exists(targetPath) !== false;
-      if (exists) return makeFailure(`File already exists at ${targetPath}.`);
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
     }
-    await sftp.rename(sourcePath, targetPath);
-    return makeSuccess(true);
-  } catch (err) {
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  move
-};

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

@@ -1,36 +1,33 @@
-// 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/sftp/file/remove/index.ts
-async function remove(sftp, targetPath, options) {
-  const { ignoreMissing = true } = options ?? {};
-  try {
-    const exists = await sftp.exists(targetPath) !== false;
-    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';
+/**
+ * Deletes a file from a specified SFTP server.
+ *
+ * This function removes the file located at the given path on the SFTP 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 {SftpClient} sftp - The ssh2-sftp-client instance used to interact with the SFTP server.
+ * @param {string} targetPath - The path of the file to delete on the SFTP 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(sftp, targetPath, options) {
+    const { ignoreMissing = true } = options ?? {};
+    try {
+        const exists = await sftp.exists(targetPath) !== false;
+        if (!exists) {
+            if (ignoreMissing)
+                return Outcome.makeSuccess(true);
+            return Outcome.makeFailure(`File not found at ${targetPath}.`);
+        }
+        await sftp.delete(targetPath);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
     }
-    await sftp.delete(targetPath);
-    return makeSuccess(true);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
 }
-export {
-  remove
-};

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

@@ -1,39 +1,28 @@
-// 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/sftp/file/stat/index.ts
-async function stat(sftp, path) {
-  try {
-    const info = await sftp.stat(path);
-    return makeSuccess({
-      size: info.size,
-      modifiedAt: new Date(info.modifyTime * 1e3),
-      mode: info.mode,
-      uid: info.uid,
-      gid: info.gid,
-      raw: info
-    });
-  } catch (err) {
-    if (err.code === 2 || err.code === "ENOENT") {
-      return makeFailure(`File not found: ${path}`);
+import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Retrieves metadata for a file on an SFTP server.
+ *
+ * @param {SftpClient} sftp – ssh2-sftp-client.
+ * @param {string} path     – Remote file path.
+ * @returns {Promise<Outcome.Either<Stat, string>>}
+ */
+export async function stat(sftp, path) {
+    try {
+        const info = await sftp.stat(path); // throws if not found
+        return Outcome.makeSuccess({
+            size: info.size,
+            modifiedAt: new Date(info.modifyTime * 1000),
+            mode: info.mode,
+            uid: info.uid,
+            gid: info.gid,
+            raw: info
+        });
+    }
+    catch (err) {
+        if (err.code === 2 || err.code === 'ENOENT') {
+            return Outcome.makeFailure(`File not found: ${path}`);
+        }
+        return Outcome.makeFailure(unknownToString(err));
     }
-    return makeFailure(unknownToString(err));
-  }
 }
-export {
-  stat
-};

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

@@ -1,40 +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/sftp/file/upload/index.ts
-async function upload(sftp, targetPath, fileStream, options) {
-  const {
-    ensureDir = true,
-    overwrite = false
-  } = options ?? {};
-  try {
-    const exists = await sftp.exists(targetPath) !== false;
-    if (exists && !overwrite) return makeFailure(`File already exists at ${targetPath}.`);
-    if (ensureDir) {
-      const dirPath = targetPath.substring(0, targetPath.lastIndexOf("/"));
-      await sftp.mkdir(dirPath, true);
+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 SFTP server.
+ *
+ * This function uploads the provided file stream to the given SFTP 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 and a file already exists at the target path, the upload is aborted.
+ *
+ * @param {Client} sftp - The ssh2-sftp-client instance used to interact with the SFTP server.
+ * @param {string} targetPath - The target path where the file will be stored on the SFTP 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(sftp, targetPath, fileStream, options) {
+    const { ensureDir = true, overwrite = false } = options ?? {};
+    try {
+        const exists = await sftp.exists(targetPath) !== false;
+        if (exists && !overwrite)
+            return Outcome.makeFailure(`File already exists at ${targetPath}.`);
+        if (ensureDir) {
+            const dirPath = targetPath.substring(0, targetPath.lastIndexOf('/'));
+            await sftp.mkdir(dirPath, true);
+        }
+        await sftp.put(fileStream, targetPath, options);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
     }
-    await sftp.put(fileStream, targetPath, options);
-    return makeSuccess(true);
-  } catch (err) {
-    const errStr = unknownToString(err);
-    return makeFailure(errStr);
-  }
 }
-export {
-  upload
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-edito/tools",
-  "version": "0.4.5",
+  "version": "0.4.11",
   "description": "",
   "author": "Maxime Fabas",
   "license": "ISC",