@design-edito/tools 0.4.23 → 0.5.1

package/node/files/get-size/index.d.ts

@@ -0,0 +1,56 @@
+import { type PathLike } from 'node:fs';
+import { Duration } from '../../../agnostic/time/duration/index.js';
+/**
+ * How to react to a per-entry read error (a failing `lstat`/`readdir`):
+ * - `'throw'`: reject the whole computation (default).
+ * - `'skip'`: count the offending entry as 0 bytes and keep going.
+ * - a function: called with the error and the offending path, then the entry
+ *   counts as 0 bytes.
+ */
+export type OnError = 'throw' | 'skip' | ((error: unknown, path: string) => void);
+export type GetSizeOptions = {
+    /** Maximum number of concurrent filesystem reads. Bounds file-descriptor usage on large trees. @default 32 */
+    concurrency?: number;
+    /** How to handle a per-entry read error. @default 'throw' */
+    onError?: OnError;
+    /** Abort the traversal; aborting rejects with the signal's reason. */
+    signal?: AbortSignal;
+    /** Abort the traversal after this delay. A `number` is milliseconds; a `Duration` is converted via `toMs()`. Combined with `signal` when both are given. */
+    timeoutMs?: number | Duration;
+    /** Maximum directory depth to descend; entries deeper than this are not counted. @default Infinity */
+    maxDepth?: number;
+    /** Follow symbolic links instead of counting the link itself. Cycle-safe via inode tracking. @default false */
+    followSymlinks?: boolean;
+    /** Count a file reached through several hard links only once. @default false */
+    dedupeHardlinks?: boolean;
+    /** `'content'` = apparent size (`stat.size`); `'allocated'` = on-disk blocks (`stat.blocks × 512`). @default 'content' */
+    sizeOf?: 'content' | 'allocated';
+};
+export declare const defaultGetSizeOptions: {
+    concurrency: number;
+    onError: "throw";
+    maxDepth: number;
+    followSymlinks: false;
+    dedupeHardlinks: false;
+    sizeOf: "content";
+};
+/**
+ * Computes the total size, in bytes, of a file or directory.
+ *
+ * For a regular file, returns its own size. For a directory, returns the summed
+ * size of everything it contains, recursively.
+ *
+ * @param target - Path to a file or directory (`string`, `Buffer`, or a `file:` URL).
+ * @param [options] - Optional configuration. See `GetSizeOptions`.
+ * @returns The total size in bytes.
+ *
+ * @remarks
+ * By default symbolic links are not followed (each link counts as its own small
+ * size) and hard links are counted once per link. Enable `followSymlinks` to
+ * resolve links — cycles and repeated targets are made safe by tracking visited
+ * inodes — and `dedupeHardlinks` to count a shared inode only once.
+ *
+ * @throws If a path cannot be read and `onError` is `'throw'` (the default), or if
+ * `options.signal` is aborted.
+ */
+export declare function getSize(target: PathLike, options?: GetSizeOptions): Promise<number>;

package/node/files/get-size/index.js

@@ -0,0 +1,167 @@
+import { promises as fs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { Duration } from '../../../agnostic/time/duration/index.js';
+export const defaultGetSizeOptions = {
+    concurrency: 32,
+    onError: 'throw',
+    maxDepth: Infinity,
+    followSymlinks: false,
+    dedupeHardlinks: false,
+    sizeOf: 'content'
+};
+/**
+ * Computes the total size, in bytes, of a file or directory.
+ *
+ * For a regular file, returns its own size. For a directory, returns the summed
+ * size of everything it contains, recursively.
+ *
+ * @param target - Path to a file or directory (`string`, `Buffer`, or a `file:` URL).
+ * @param [options] - Optional configuration. See `GetSizeOptions`.
+ * @returns The total size in bytes.
+ *
+ * @remarks
+ * By default symbolic links are not followed (each link counts as its own small
+ * size) and hard links are counted once per link. Enable `followSymlinks` to
+ * resolve links — cycles and repeated targets are made safe by tracking visited
+ * inodes — and `dedupeHardlinks` to count a shared inode only once.
+ *
+ * @throws If a path cannot be read and `onError` is `'throw'` (the default), or if
+ * `options.signal` is aborted.
+ */
+export async function getSize(target, options = {}) {
+    const concurrency = Math.max(1, Math.floor(options.concurrency ?? defaultGetSizeOptions.concurrency));
+    const timeoutMs = options.timeoutMs instanceof Duration ? options.timeoutMs.toMs() : options.timeoutMs;
+    const timeout = timeoutMs === undefined ? null : createTimeoutSignal(timeoutMs, options.signal);
+    const resolved = {
+        onError: options.onError ?? defaultGetSizeOptions.onError,
+        signal: timeout?.signal ?? options.signal,
+        limit: createLimiter(concurrency),
+        maxDepth: options.maxDepth ?? defaultGetSizeOptions.maxDepth,
+        followSymlinks: options.followSymlinks ?? defaultGetSizeOptions.followSymlinks,
+        dedupeHardlinks: options.dedupeHardlinks ?? defaultGetSizeOptions.dedupeHardlinks,
+        sizeOf: options.sizeOf ?? defaultGetSizeOptions.sizeOf,
+        visited: new Set()
+    };
+    try {
+        return await computeSize(toPathString(target), resolved, 0);
+    }
+    finally {
+        timeout?.dispose();
+    }
+}
+// Builds an abort signal that fires after `timeoutMs`, merged with a caller
+// signal when provided. Aborting either aborts the returned one. `dispose`
+// clears the timer and detaches the listener.
+function createTimeoutSignal(timeoutMs, userSignal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(new Error(`getSize timed out after ${timeoutMs} ms`)); }, Math.max(0, timeoutMs));
+    timer.unref();
+    if (userSignal === undefined) {
+        return { signal: controller.signal, dispose: () => { clearTimeout(timer); } };
+    }
+    if (userSignal.aborted)
+        controller.abort(userSignal.reason);
+    const onUserAbort = () => { controller.abort(userSignal.reason); };
+    userSignal.addEventListener('abort', onUserAbort, { once: true });
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            clearTimeout(timer);
+            userSignal.removeEventListener('abort', onUserAbort);
+        }
+    };
+}
+function toPathString(target) {
+    if (typeof target === 'string')
+        return target;
+    if (Buffer.isBuffer(target))
+        return target.toString('utf-8');
+    return fileURLToPath(target);
+}
+function measure(stats, options) {
+    return options.sizeOf === 'allocated' ? stats.blocks * 512 : stats.size;
+}
+async function computeSize(target, options, depth) {
+    options.signal?.throwIfAborted();
+    let stats;
+    try {
+        stats = await options.limit(async () => await fs.lstat(target));
+    }
+    catch (error) {
+        return handleError(error, target, options);
+    }
+    // Resolve symlinks when asked; otherwise a link counts as its own size.
+    let realTarget = target;
+    if (stats.isSymbolicLink()) {
+        if (!options.followSymlinks)
+            return measure(stats, options);
+        try {
+            stats = await options.limit(async () => await fs.stat(target));
+            if (stats.isDirectory())
+                realTarget = await options.limit(async () => await fs.realpath(target));
+        }
+        catch (error) {
+            return handleError(error, target, options);
+        }
+    }
+    // Count each physical inode once when following links (cycle safety) or
+    // deduping hard links.
+    if (options.followSymlinks || options.dedupeHardlinks) {
+        const key = `${stats.dev}:${stats.ino}`;
+        if (options.visited.has(key))
+            return 0;
+        options.visited.add(key);
+    }
+    if (!stats.isDirectory())
+        return measure(stats, options);
+    if (depth >= options.maxDepth)
+        return 0;
+    let children;
+    try {
+        children = await options.limit(async () => await fs.readdir(realTarget));
+    }
+    catch (error) {
+        return handleError(error, realTarget, options);
+    }
+    const childSizes = await Promise.all(children.map(async (child) => await computeSize(path.join(realTarget, child), options, depth + 1)));
+    return childSizes.reduce((total, size) => total + size, 0);
+}
+function handleError(error, target, options) {
+    if (options.onError === 'throw')
+        throw error;
+    if (typeof options.onError === 'function')
+        options.onError(error, target);
+    return 0;
+}
+// Global concurrency limiter: at most `max` wrapped calls run at once. Wrapped
+// calls must be leaf operations (single fs syscalls) that never await another
+// wrapped call, so the recursive traversal cannot deadlock on slots.
+function createLimiter(max) {
+    let active = 0;
+    const waiters = [];
+    const acquire = async () => {
+        if (active < max) {
+            active += 1;
+            return;
+        }
+        // Resumed by `release`, which hands over the slot without decrementing.
+        await new Promise(resolve => { waiters.push(resolve); });
+    };
+    const release = () => {
+        const resume = waiters.shift();
+        if (resume !== undefined)
+            resume();
+        else
+            active -= 1;
+    };
+    return async function limit(fn) {
+        await acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    };
+}

package/node/files/get-size/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node/files/get-size/index.test.js

@@ -0,0 +1,143 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { promises as fs } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import os from 'node:os';
+import path from 'node:path';
+import { getSize } from './index.js';
+import { seconds } from '../../../agnostic/time/duration/index.js';
+// Fixtures (all under the OS temp dir):
+//   root/         a.txt (10) + sub/b.txt (5) + sub/empty/
+//   wideRoot/     60 x 1-byte files (exercises concurrency)
+//   linkRoot/     target.txt (7) + link -> target.txt (symlink to file)
+//   cycleRoot/    self -> cycleRoot (symlink cycle to its own dir)
+//   hlRoot/       original.txt (9) + hard.txt (hard link to original.txt)
+let root;
+let wideRoot;
+let linkRoot;
+let cycleRoot;
+let hlRoot;
+const aBytes = 10;
+const bBytes = 5;
+const wideFileCount = 60;
+const targetBytes = 7;
+const hardBytes = 9;
+beforeAll(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'lm-get-size-'));
+    await fs.writeFile(path.join(root, 'a.txt'), 'x'.repeat(aBytes));
+    await fs.mkdir(path.join(root, 'sub'));
+    await fs.writeFile(path.join(root, 'sub', 'b.txt'), 'y'.repeat(bBytes));
+    await fs.mkdir(path.join(root, 'sub', 'empty'));
+    wideRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'lm-get-size-wide-'));
+    await Promise.all([...Array(wideFileCount)].map(async (_, i) => await fs.writeFile(path.join(wideRoot, `f${i}.txt`), 'z')));
+    linkRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'lm-get-size-link-'));
+    await fs.writeFile(path.join(linkRoot, 'target.txt'), 't'.repeat(targetBytes));
+    await fs.symlink(path.join(linkRoot, 'target.txt'), path.join(linkRoot, 'link'));
+    cycleRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'lm-get-size-cycle-'));
+    await fs.symlink(cycleRoot, path.join(cycleRoot, 'self'));
+    hlRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'lm-get-size-hl-'));
+    await fs.writeFile(path.join(hlRoot, 'original.txt'), 'h'.repeat(hardBytes));
+    await fs.link(path.join(hlRoot, 'original.txt'), path.join(hlRoot, 'hard.txt'));
+});
+afterAll(async () => {
+    await Promise.all([root, wideRoot, linkRoot, cycleRoot, hlRoot].map(async (dir) => await fs.rm(dir, { recursive: true, force: true })));
+});
+describe('getSize', () => {
+    it('returns the size of a single file', async () => {
+        expect(await getSize(path.join(root, 'a.txt'))).toBe(aBytes);
+    });
+    it('sums the sizes of a directory recursively', async () => {
+        expect(await getSize(root)).toBe(aBytes + bBytes);
+    });
+    it('returns the size of a nested directory', async () => {
+        expect(await getSize(path.join(root, 'sub'))).toBe(bBytes);
+    });
+    it('returns 0 for an empty directory', async () => {
+        expect(await getSize(path.join(root, 'sub', 'empty'))).toBe(0);
+    });
+    describe('PathLike variants', () => {
+        it('accepts a Buffer path', async () => {
+            expect(await getSize(Buffer.from(path.join(root, 'a.txt')))).toBe(aBytes);
+        });
+        it('accepts a file: URL', async () => {
+            expect(await getSize(pathToFileURL(root))).toBe(aBytes + bBytes);
+        });
+    });
+    it('rejects when the path does not exist', async () => {
+        await expect(getSize(path.join(root, 'does-not-exist'))).rejects.toThrow();
+    });
+    describe('concurrency', () => {
+        it('computes the same total with concurrency: 1', async () => {
+            expect(await getSize(root, { concurrency: 1 })).toBe(aBytes + bBytes);
+        });
+        it('handles a wide directory under a low concurrency', async () => {
+            expect(await getSize(wideRoot, { concurrency: 4 })).toBe(wideFileCount);
+        });
+    });
+    describe('onError', () => {
+        it("counts a missing path as 0 when onError is 'skip'", async () => {
+            expect(await getSize(path.join(root, 'nope'), { onError: 'skip' })).toBe(0);
+        });
+        it('invokes the onError callback and skips the entry', async () => {
+            const seen = [];
+            const size = await getSize(path.join(root, 'nope'), {
+                onError: (_error, failedPath) => { seen.push(failedPath); }
+            });
+            expect(size).toBe(0);
+            expect(seen).toHaveLength(1);
+            expect(seen[0]).toBe(path.join(root, 'nope'));
+        });
+    });
+    describe('signal', () => {
+        it('rejects when the signal is already aborted', async () => {
+            await expect(getSize(root, { signal: AbortSignal.abort() })).rejects.toThrow();
+        });
+    });
+    describe('maxDepth', () => {
+        it('counts only the first level with maxDepth: 1', async () => {
+            // a.txt (depth 1) counted; sub/ is a dir at depth 1, not descended.
+            expect(await getSize(root, { maxDepth: 1 })).toBe(aBytes);
+        });
+        it('descends one more level with maxDepth: 2', async () => {
+            expect(await getSize(root, { maxDepth: 2 })).toBe(aBytes + bBytes);
+        });
+    });
+    describe('followSymlinks', () => {
+        it('does not follow links by default (link counts as its own size)', async () => {
+            // target.txt (7) + the link's own (non-zero) size.
+            expect(await getSize(linkRoot)).toBeGreaterThan(targetBytes);
+        });
+        it('follows links and dedupes the shared target', async () => {
+            // The link resolves to target.txt, so the shared inode is counted once.
+            expect(await getSize(linkRoot, { followSymlinks: true })).toBe(targetBytes);
+        });
+        it('is cycle-safe when a link points back into the tree', async () => {
+            expect(await getSize(cycleRoot, { followSymlinks: true })).toBe(0);
+        });
+    });
+    describe('dedupeHardlinks', () => {
+        it('counts each hard link separately by default', async () => {
+            expect(await getSize(hlRoot)).toBe(hardBytes * 2);
+        });
+        it('counts a shared inode once when dedupeHardlinks is set', async () => {
+            expect(await getSize(hlRoot, { dedupeHardlinks: true })).toBe(hardBytes);
+        });
+    });
+    describe('sizeOf', () => {
+        it("'allocated' is at least the apparent content size", async () => {
+            const content = await getSize(root);
+            const allocated = await getSize(root, { sizeOf: 'allocated' });
+            expect(allocated).toBeGreaterThanOrEqual(content);
+        });
+    });
+    describe('timeoutMs', () => {
+        it('completes normally within a generous timeout (number)', async () => {
+            expect(await getSize(root, { timeoutMs: 10_000 })).toBe(aBytes + bBytes);
+        });
+        it('accepts a Duration', async () => {
+            expect(await getSize(root, { timeoutMs: seconds(10) })).toBe(aBytes + bBytes);
+        });
+        it('still honours an already-aborted signal when combined with a timeout', async () => {
+            await expect(getSize(root, { timeoutMs: 10_000, signal: AbortSignal.abort() })).rejects.toThrow();
+        });
+    });
+});

package/node/files/index.d.ts

@@ -1,3 +1,4 @@
+export * as getSize from './get-size/index.js'
 export * as isInDirectory from './is-in-directory/index.js'
 export * as readWrite from './read-write/index.js'
 export * as subpaths from './subpaths/index.js'

package/node/files/index.js

@@ -1,3 +1,4 @@
+export * as getSize from './get-size/index.js'
 export * as isInDirectory from './is-in-directory/index.js'
 export * as readWrite from './read-write/index.js'
 export * as subpaths from './subpaths/index.js'

package/node/files/read-write/index.d.ts

@@ -23,14 +23,14 @@ export type Replacements = Record<string, string>;
  * - **Replacements mode**: Pass an object with string replacements.
  * - **Function mode**: Pass a function that transforms the file content.
  *
- * @param {Path} path                    - The path to the file to read and edit.
- * @param {Replacements} editor          - Object mapping strings to replace with their replacements.
- * @param {Options} [opts]               - Optional configuration.
- * @param {Parameters<typeof fs.readFile>[1]} [opts.readOptions]  - Extra `readFile` params.
- * @param {Parameters<typeof fs.writeFile>[2]} [opts.writeOptions] - Extra `writeFile` params.
- * @param {Path} [opts.output]           - Output path (defaults to `path`).
- * @param {boolean} [opts.dryRun=false]  - If `true`, skip writing to disk.
- * @returns {Promise<string>} The edited file content as a string.
+ * @param path                    - The path to the file to read and edit.
+ * @param editor          - Object mapping strings to replace with their replacements.
+ * @param [opts]               - Optional configuration.
+ * @param [opts.readOptions]  - Extra `readFile` params.
+ * @param [opts.writeOptions] - Extra `writeFile` params.
+ * @param [opts.output]           - Output path (defaults to `path`).
+ * @param [opts.dryRun=false]  - If `true`, skip writing to disk.
+ * @returns The edited file content as a string.
  */
 export declare function readWrite(path: Path, editor: Replacements, opts?: Options): Promise<string>;
 /**
@@ -40,14 +40,14 @@ export declare function readWrite(path: Path, editor: Replacements, opts?: Optio
  * - **Replacements mode**: Pass an object with string replacements.
  * - **Function mode**: Pass a function that transforms the file content.
  *
- * @param {Path} path                    - The path to the file to read and edit.
- * @param {EditorFunc<T>} editor         - Function that transforms the file content.
- * @param {Options} [opts]               - Optional configuration.
- * @param {Parameters<typeof fs.readFile>[1]} [opts.readOptions]  - Extra `readFile` params.
- * @param {Parameters<typeof fs.writeFile>[2]} [opts.writeOptions] - Extra `writeFile` params.
- * @param {Path} [opts.output]           - Output path (defaults to `path`).
- * @param {boolean} [opts.dryRun=false]  - If `true`, skip writing to disk.
- * @returns {Promise<T>} The edited file content of type `T`.
+ * @param path                    - The path to the file to read and edit.
+ * @param editor         - Function that transforms the file content.
+ * @param [opts]               - Optional configuration.
+ * @param [opts.readOptions]  - Extra `readFile` params.
+ * @param [opts.writeOptions] - Extra `writeFile` params.
+ * @param [opts.output]           - Output path (defaults to `path`).
+ * @param [opts.dryRun=false]  - If `true`, skip writing to disk.
+ * @returns The edited file content of type `T`.
  */
 export declare function readWrite<T extends WriteFileData>(path: Path, editor: EditorFunc<T>, opts?: Options): Promise<T>;
 export {};

package/node/files/subpaths/index.d.ts

@@ -15,8 +15,8 @@ export declare const defaultListContext: Required<ListContext>;
 /**
  * Fills missing properties in a list context with default values.
  *
- * @param {ListContext} input - The partial list context to fill.
- * @returns {Required<ListContext>} A complete list context with all properties set.
+ * @param input - The partial list context to fill.
+ * @returns A complete list context with all properties set.
  */
 export declare const fillListContext: (input: ListContext) => Required<ListContext>;
 export type ListOptions = {
@@ -36,8 +36,8 @@ export declare const defaultListOptions: Required<ListOptions>;
 /**
  * Fills missing properties in list options with default values.
  *
- * @param {ListOptions} input - The partial list options to fill.
- * @returns {Required<ListOptions>} A complete list options object with all properties set.
+ * @param input - The partial list options to fill.
+ * @returns A complete list options object with all properties set.
  */
 export declare const fillOptions: (input: ListOptions) => Required<ListOptions>;
 /**
@@ -54,10 +54,10 @@ export declare function list(...args: Parameters<typeof listAbsoluteSubpaths>):
 /**
  * Internal function that lists absolute subpaths recursively.
  *
- * @param {string} inputPath              - The directory path to list.
- * @param {ListOptions} [_options]        - Optional configuration.
- * @param {ListContext} [__private_context] - Internal recursion context.
- * @returns {Promise<string[]>} Array of absolute subpaths.
+ * @param inputPath              - The directory path to list.
+ * @param [_options]        - Optional configuration.
+ * @param [__private_context] - Internal recursion context.
+ * @returns Array of absolute subpaths.
  */
 declare function listAbsoluteSubpaths(inputPath: string, _options?: ListOptions, __private_context?: ListContext): Promise<string[]>;
 export {};

package/node/files/subpaths/index.js

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-throw-literal */
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { matchesSome as stringMatchesSome } from '../../../agnostic/strings/matches/index.js';
@@ -10,8 +9,8 @@ export const defaultListContext = {
 /**
  * Fills missing properties in a list context with default values.
  *
- * @param {ListContext} input - The partial list context to fill.
- * @returns {Required<ListContext>} A complete list context with all properties set.
+ * @param input - The partial list context to fill.
+ * @returns A complete list context with all properties set.
  */
 export const fillListContext = (input) => {
     return {
@@ -35,8 +34,8 @@ export const defaultListOptions = {
 /**
  * Fills missing properties in list options with default values.
  *
- * @param {ListOptions} input - The partial list options to fill.
- * @returns {Required<ListOptions>} A complete list options object with all properties set.
+ * @param input - The partial list options to fill.
+ * @returns A complete list options object with all properties set.
  */
 export const fillOptions = (input) => {
     return {
@@ -65,10 +64,10 @@ export async function list(...args) {
 /**
  * Internal function that lists absolute subpaths recursively.
  *
- * @param {string} inputPath              - The directory path to list.
- * @param {ListOptions} [_options]        - Optional configuration.
- * @param {ListContext} [__private_context] - Internal recursion context.
- * @returns {Promise<string[]>} Array of absolute subpaths.
+ * @param inputPath              - The directory path to list.
+ * @param [_options]        - Optional configuration.
+ * @param [__private_context] - Internal recursion context.
+ * @returns Array of absolute subpaths.
  */
 async function listAbsoluteSubpaths(inputPath, _options = {}, 
 // eslint-disable-next-line @typescript-eslint/naming-convention
@@ -76,9 +75,7 @@ __private_context = {}) {
     const options = fillOptions(_options);
     // eslint-disable-next-line @typescript-eslint/naming-convention
     const _private_context = fillListContext(__private_context);
-    if (_private_context.rootPath === null) {
-        _private_context.rootPath = inputPath;
-    }
+    _private_context.rootPath ??= inputPath;
     const subpaths = [];
     if (_private_context.depth > options.maxDepth)
         return subpaths;
@@ -132,6 +129,7 @@ __private_context = {}) {
                 }
             }
             else {
+                // eslint-disable-next-line no-lonely-if
                 if (isDirectory) {
                     const childSubpaths = await listAbsoluteSubpaths(childAbsPath, options, {
                         ..._private_context,
@@ -147,7 +145,7 @@ __private_context = {}) {
         }
         catch (err) {
             if (typeof err !== 'boolean')
-                throw new Error('This try/catch block should only throw booleans');
+                throw new Error('This try/catch block should only throw booleans', { cause: err });
             const shouldDiveDeeper = err;
             if (!shouldDiveDeeper)
                 return [];

package/node/ftps/directory/copy-dir/index.d.ts

@@ -1,4 +1,4 @@
-import { type Client } from 'basic-ftp';
+import type { Client } from 'basic-ftp';
 import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
 export type CopyDirOptions = {
     /**
@@ -17,11 +17,11 @@ export type CopyDirOptions = {
  * 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>>}
+ * @param  ftpClient  - The FTP client instance.
+ * @param  sourceDir  - The source directory path to copy from.
+ * @param  targetDir  - The target directory path to copy to.
+ * @param [options] - Optional parameters for the operation.
+ * @returns
  * - Success: `Outcome.makeSuccess(true)` if the copy succeeds.
  * - Failure: `Outcome.makeFailure(errStr)` if an error occurs.
  */

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

@@ -5,11 +5,11 @@ import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/i
  * 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>>}
+ * @param  ftpClient  - The FTP client instance.
+ * @param  sourceDir  - The source directory path to copy from.
+ * @param  targetDir  - The target directory path to copy to.
+ * @param [options] - Optional parameters for the operation.
+ * @returns
  * - Success: `Outcome.makeSuccess(true)` if the copy succeeds.
  * - Failure: `Outcome.makeFailure(errStr)` if an error occurs.
  */
@@ -18,7 +18,7 @@ export async function copyDir(ftpClient, sourceDir, targetDir, 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 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) {

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

@@ -1,4 +1,4 @@
-export * as copyDir from './copy-dir/index.js'
 export * as list from './list/index.js'
 export * as moveDir from './move-dir/index.js'
 export * as removeDir from './remove-dir/index.js'
+export * as copyDir from './copy-dir/index.js'

package/node/ftps/directory/index.js

@@ -1,4 +1,4 @@
-export * as copyDir from './copy-dir/index.js'
 export * as list from './list/index.js'
 export * as moveDir from './move-dir/index.js'
 export * as removeDir from './remove-dir/index.js'
+export * as copyDir from './copy-dir/index.js'

package/node/ftps/directory/list/index.d.ts

@@ -1,12 +1,12 @@
-import { type Client } from 'basic-ftp';
+import type { Client } from 'basic-ftp';
 import * as Outcome from '../../../../agnostic/misc/outcome/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.
+ * @param ftpClient - The basic-ftp client instance used to interact with the FTP server.
+ * @param directoryPath - The directory path to list files under.
+ * @returns Returns either a success with an array of file paths, or a failure with an error message.
  */
 export declare function list(ftpClient: Client, directoryPath: string): Promise<Outcome.Either<string[], string>>;

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

@@ -5,9 +5,9 @@ import { unknownToString } from '../../../../agnostic/errors/unknown-to-string/i
  *
  * 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.
+ * @param ftpClient - The basic-ftp client instance used to interact with the FTP server.
+ * @param directoryPath - The directory path to list files under.
+ * @returns Returns either a success with an array of file paths, or a failure with an error message.
  */
 export async function list(ftpClient, directoryPath) {
     try {

package/node/ftps/directory/move-dir/index.d.ts

@@ -1,4 +1,4 @@
-import { type Client } from 'basic-ftp';
+import type { Client } from 'basic-ftp';
 import * as Outcome from '../../../../agnostic/misc/outcome/index.js';
 export type MoveDirOptions = {
     /** If false and `targetDir` exists, the operation is aborted. Defaults to false. */
@@ -15,11 +15,11 @@ export type MoveDirOptions = {
  * 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`:
+ * @param ftpClient - The FTP client instance.
+ * @param sourceDir - The source directory path to move from.
+ * @param targetDir - The target directory path to move to.
+ * @param [options] - Optional parameters for the operation.
+ * @returns 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.
  */