@design-edito/tools 0.4.4 → 0.4.6

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

@@ -3,5 +3,5 @@ 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

@@ -3,5 +3,5 @@ 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/move/index.js

@@ -1,9 +1,49 @@
-import {
-  move
-} from "../../../../chunks/chunk-WL4WNJ2Y.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  move
-};
+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));
+    }
+}

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

@@ -1,9 +1,40 @@
-import {
-  remove
-} from "../../../../chunks/chunk-5WVGUZL5.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  remove
-};
+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 {
+        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);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}

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

@@ -1,9 +1,31 @@
-import {
-  stat
-} from "../../../../chunks/chunk-IPRWXI27.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  stat
-};
+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));
+    }
+}

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

@@ -1,9 +1,44 @@
-import {
-  upload
-} from "../../../../chunks/chunk-5TM235Z3.js";
-import "../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  upload
-};
+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 {
+        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);
+    }
+    catch (err) {
+        const errStr = unknownToString(err);
+        return Outcome.makeFailure(errStr);
+    }
+}

package/node/images/create/index.js

@@ -1,19 +1,11 @@
-import {
-  toCreateOptions
-} from "../../../chunks/chunk-HMMPT3UM.js";
-import "../../../chunks/chunk-CVMYA5XK.js";
-import "../../../chunks/chunk-OBSTP7YR.js";
-import "../../../chunks/chunk-HQLRJ7XW.js";
-import "../../../chunks/chunk-DNIOWD7K.js";
-import "../../../chunks/chunk-PUQUSA6S.js";
-import "../../../chunks/chunk-OSAXBA7G.js";
-import "../../../chunks/chunk-WSFCRVEQ.js";
-
-// src/node/images/create/index.ts
-import sharp from "sharp";
-async function create(options) {
-  return sharp({ create: toCreateOptions(options) });
+import sharp from 'sharp';
+import { toCreateOptions } from '../utils/index.js';
+/**
+ * Creates a new image using Sharp with the specified options.
+ *
+ * @param options - Image creation options. See `CreateOptions` for details.
+ * @returns A Sharp instance ready for further image operations.
+ */
+export async function create(options) {
+    return sharp({ create: toCreateOptions(options) });
 }
-export {
-  create
-};