@design-edito/tools 0.5.0 → 0.5.2

package/components/ListLoader/index.js

@@ -0,0 +1,146 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { toError } from '../../agnostic/misc/cast/index.js';
+import { clamp } from '../../agnostic/numbers/clamp/index.js';
+import { ListLoaderControlled } from './index.controlled.js';
+import { rangeBetween } from './utils.js';
+/**
+ * Paginated list abstraction. Fetches the pages it is asked for, keeps them
+ * fresh, and drives a {@link ListLoaderControlled} with the result.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @see {@link ListLoaderControlled} for the rendered markup and CSS elements.
+ * @returns A {@link ListLoaderControlled} fed with the loaded pages.
+ *
+ * @remarks
+ * - In controlled mode (`pages` defined), the page set is entirely driven by the
+ *   parent. `fillGaps` and `dropPagesFurtherThan` are inert, and load buttons only
+ *   report through `onLoadPageClick`.
+ * - In uncontrolled mode, internal state is initialized from `defaultPage` and load
+ *   buttons extend the set themselves. `onLoadPageClick` still fires, after the
+ *   internal state has been updated.
+ * - A page removed from the effective set is dropped from memory, and a request
+ *   still in flight for it is discarded on arrival rather than re-inserted.
+ * - No page outside `firstPagePos`–`lastPagePos` is ever fetched, whichever mode
+ *   is in use.
+ */
+export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClick, staleAfterMs, onFetchSuccess, onFetchError, fetchRetriesNb = Infinity, fetchRetriesDelayMs = 1000 }) => {
+    const [itemsPages, setItemsPages] = useState(new Map());
+    const [loadingPages, setLoadingPages] = useState(new Set());
+    const [internalPages, setInternalPages] = useState([
+        clamp(defaultPage ?? firstPagePos, firstPagePos, lastPagePos)
+    ]);
+    const requestedPages = useRef(new Set());
+    // Single source of truth for what should be loaded. Memoized so the effects
+    // below keep a stable dependency when the page set has not actually changed.
+    const currentPages = useMemo(() => (pages ?? internalPages).filter(page => page >= firstPagePos && page <= lastPagePos), [pages, internalPages, firstPagePos, lastPagePos]);
+    const handleLoadClick = (pagePos) => {
+        if (pages === undefined) {
+            setInternalPages(curr => {
+                const next = curr.includes(pagePos) ? curr : [...curr, pagePos];
+                if (dropPagesFurtherThan === undefined)
+                    return next;
+                const kept = next.filter(page => Math.abs(page - pagePos) <= dropPagesFurtherThan);
+                return kept.length === next.length ? next : kept;
+            });
+        }
+        onLoadPageClick?.(pagePos);
+    };
+    const storePage = (page, items) => setItemsPages(curr => {
+        const next = new Map(curr);
+        next.set(page, { loadedAt: new Date(), items });
+        return next;
+    });
+    const setPageLoading = (page, isLoading) => setLoadingPages(curr => {
+        const next = new Set(curr);
+        if (isLoading)
+            next.add(page);
+        else
+            next.delete(page);
+        return next;
+    });
+    const reportFetchError = (page, err) => {
+        const error = toError(err);
+        if (onFetchError !== undefined)
+            return onFetchError(page, error);
+        // eslint-disable-next-line no-console
+        console.warn(`ListLoader failed to fetch page ${page}`, error);
+    };
+    // Guards the whole load path at once: a page dropped meanwhile stops its
+    // pending retries and its stale reloads without any further bookkeeping.
+    const loadPage = (page, retriesLeft = fetchRetriesNb) => {
+        if (!requestedPages.current.has(page))
+            return;
+        setPageLoading(page, true);
+        void fetch(page)
+            .then(items => {
+            if (!requestedPages.current.has(page))
+                return;
+            storePage(page, items);
+            onFetchSuccess?.(page, items);
+            setPageLoading(page, false);
+        })
+            .catch((err) => {
+            reportFetchError(page, err);
+            if (retriesLeft <= 0)
+                return setPageLoading(page, false);
+            window.setTimeout(() => loadPage(page, retriesLeft - 1), fetchRetriesDelayMs);
+        });
+    };
+    // Fx. dep. `currentPages` - Drops everything held for pages no longer wanted.
+    // The updaters return `curr` untouched when nothing was removed, so an unstable
+    // `pages` prop cannot spin the render loop.
+    useEffect(() => {
+        Array.from(requestedPages.current)
+            .filter(page => !currentPages.includes(page))
+            .forEach(page => { requestedPages.current.delete(page); });
+        setItemsPages(curr => {
+            const next = new Map(Array.from(curr).filter(([page]) => currentPages.includes(page)));
+            return next.size === curr.size ? curr : next;
+        });
+        setLoadingPages(curr => {
+            const next = new Set(Array.from(curr).filter(page => currentPages.includes(page)));
+            return next.size === curr.size ? curr : next;
+        });
+    }, [currentPages]);
+    useEffect(() => {
+        if (pages !== undefined)
+            return;
+        if (!fillGaps)
+            return;
+        setInternalPages(curr => {
+            if (curr.length === 0)
+                return curr;
+            const missing = rangeBetween(Math.min(...curr), Math.max(...curr))
+                .filter(page => !curr.includes(page));
+            if (missing.length === 0)
+                return curr;
+            return [...curr, ...missing];
+        });
+    }, [currentPages, fillGaps, pages]);
+    useEffect(() => {
+        currentPages.forEach(page => {
+            if (requestedPages.current.has(page))
+                return;
+            requestedPages.current.add(page);
+            loadPage(page);
+        });
+    }, [currentPages, fetch]);
+    // Fx. dep. `itemsPages` - Reschedules one timeout per page on every store, each
+    // due from its own `loadedAt`. A refetch updates `loadedAt`, which re-runs this
+    // effect and keeps the cycle going.
+    useEffect(() => {
+        if (staleAfterMs === undefined)
+            return;
+        const timeouts = Array.from(itemsPages).map(([page, { loadedAt }]) => {
+            const dueInMs = Math.max(0, staleAfterMs - (Date.now() - loadedAt.getTime()));
+            return window.setTimeout(() => loadPage(page), dueInMs);
+        });
+        return () => timeouts.forEach(timeout => window.clearTimeout(timeout));
+    }, [itemsPages, staleAfterMs, fetch]);
+    const controlledItemsPages = new Map(Array
+        .from(itemsPages)
+        .map(([page, { items }]) => [page, items]));
+    return _jsx(ListLoaderControlled, { className: className, pages: currentPages, firstPagePos: firstPagePos, lastPagePos: lastPagePos, itemsPages: controlledItemsPages, filter: filter, display: display, getIdentifier: getIdentifier, loadingPages: Array.from(loadingPages), onLoadPageClick: handleLoadClick, autoLoadPrevWhenVisible: autoLoadPrevWhenVisible, autoLoadNextWhenVisible: autoLoadNextWhenVisible });
+};

package/components/ListLoader/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Lists every integer from `from` to `to`, both included.
+ *
+ * @param from - Lower bound.
+ * @param to - Upper bound. When lower than `from`, the range is empty.
+ * @returns The integers in ascending order.
+ */
+export declare function rangeBetween(from: number, to: number): number[];

package/components/ListLoader/utils.js

@@ -0,0 +1,10 @@
+/**
+ * Lists every integer from `from` to `to`, both included.
+ *
+ * @param from - Lower bound.
+ * @param to - Upper bound. When lower than `from`, the range is empty.
+ * @returns The integers in ascending order.
+ */
+export function rangeBetween(from, to) {
+    return Array.from({ length: Math.max(0, to - from + 1) }, (_, pos) => from + pos);
+}

package/components/index.d.ts

@@ -1,7 +1,7 @@
 export * as beforeAfter from './BeforeAfter/index.js'
 export * as button from './Button/index.js'
-export * as clippable from './Clippable/index.js'
 export * as disclaimer from './Disclaimer/index.js'
+export * as clippable from './Clippable/index.js'
 export * as drawer from './Drawer/index.js'
 export * as eventListener from './EventListener/index.js'
 export * as gallery from './Gallery/index.js'
@@ -10,10 +10,11 @@ export * as image from './Image/index.js'
 export * as input from './Input/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
 export * as jsonEditor from './JsonEditor/index.js'
+export * as listLoader from './ListLoader/index.js'
 export * as overlayer from './Overlayer/index.js'
 export * as paginator from './Paginator/index.js'
-export * as scrllgngn from './Scrllgngn/index.js'
 export * as resizeObserver from './ResizeObserver/index.js'
+export * as scrllgngn from './Scrllgngn/index.js'
 export * as scrollListener from './ScrollListener/index.js'
 export * as select from './Select/index.js'
 export * as sequencer from './Sequencer/index.js'

package/components/index.js

@@ -1,7 +1,7 @@
 export * as beforeAfter from './BeforeAfter/index.js'
 export * as button from './Button/index.js'
-export * as clippable from './Clippable/index.js'
 export * as disclaimer from './Disclaimer/index.js'
+export * as clippable from './Clippable/index.js'
 export * as drawer from './Drawer/index.js'
 export * as eventListener from './EventListener/index.js'
 export * as gallery from './Gallery/index.js'
@@ -10,10 +10,11 @@ export * as image from './Image/index.js'
 export * as input from './Input/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
 export * as jsonEditor from './JsonEditor/index.js'
+export * as listLoader from './ListLoader/index.js'
 export * as overlayer from './Overlayer/index.js'
 export * as paginator from './Paginator/index.js'
-export * as scrllgngn from './Scrllgngn/index.js'
 export * as resizeObserver from './ResizeObserver/index.js'
+export * as scrllgngn from './Scrllgngn/index.js'
 export * as scrollListener from './ScrollListener/index.js'
 export * as select from './Select/index.js'
 export * as sequencer from './Sequencer/index.js'

package/components/public-classnames.d.ts

@@ -10,6 +10,7 @@ export declare const image = "lm-image";
 export declare const input = "lm-input";
 export declare const intersectionObserver = "lm-intersection-observer";
 export declare const jsonEditor = "lm-json-editor";
+export declare const listLoader = "lm-list-loader";
 export declare const overlayer = "lm-overlayer";
 export declare const paginator = "lm-paginator";
 export declare const resizeObserver = "lm-resize-observer";

package/components/public-classnames.js

@@ -10,6 +10,7 @@ export const image = 'lm-image';
 export const input = 'lm-input';
 export const intersectionObserver = 'lm-intersection-observer';
 export const jsonEditor = 'lm-json-editor';
+export const listLoader = 'lm-list-loader';
 export const overlayer = 'lm-overlayer';
 export const paginator = 'lm-paginator';
 export const resizeObserver = 'lm-resize-observer';

package/index.d.ts

@@ -1,3 +1,3 @@
-export * as agnostic from './agnostic/index.js'
 export * as components from './components/index.js'
 export * as node from './node/index.js'
+export * as agnostic from './agnostic/index.js'

package/index.js

@@ -1,3 +1,3 @@
-export * as agnostic from './agnostic/index.js'
 export * as components from './components/index.js'
 export * as node from './node/index.js'
+export * as agnostic from './agnostic/index.js'

package/node/@aws-s3/storage/file/index.d.ts

@@ -1,6 +1,6 @@
 export * as copy from './copy/index.js'
-export * as download from './download/index.js'
 export * as exists from './exists/index.js'
+export * as download from './download/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'
 export * as stat from './stat/index.js'

package/node/@aws-s3/storage/file/index.js

@@ -1,6 +1,6 @@
 export * as copy from './copy/index.js'
-export * as download from './download/index.js'
 export * as exists from './exists/index.js'
+export * as download from './download/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'
 export * as stat from './stat/index.js'

package/node/@google-cloud/storage/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 removeDir from './remove-dir/index.js'
 export * as moveDir from './move-dir/index.js'
+export * as removeDir from './remove-dir/index.js'

package/node/@google-cloud/storage/directory/index.js

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

package/node/@google-cloud/storage/index.d.ts

@@ -1,3 +1,3 @@
-export * as bucket from './bucket/index.js'
 export * as directory from './directory/index.js'
+export * as bucket from './bucket/index.js'
 export * as file from './file/index.js'

package/node/@google-cloud/storage/index.js

@@ -1,3 +1,3 @@
-export * as bucket from './bucket/index.js'
 export * as directory from './directory/index.js'
+export * as bucket from './bucket/index.js'
 export * as file from './file/index.js'

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();
+        });
+    });
+});