@design-edito/tools 0.4.4 → 0.4.6

package/components/Video/utils.js

@@ -0,0 +1,137 @@
+/* Video element triggers */
+export const muteAttributeWorkaround = (video, shouldMute, setIsSoundOn) => {
+    if (video === null)
+        return;
+    if (!shouldMute)
+        return;
+    const currentMuted = video.getAttribute('muted');
+    if (currentMuted !== null)
+        return;
+    video.setAttribute('muted', '');
+    video.load();
+    setIsSoundOn(false);
+};
+export const forceMute = (video, setIsSoundOn) => {
+    if (video === null)
+        return;
+    video.muted = true;
+    setIsSoundOn(false);
+};
+export const forceLoud = (video, setIsSoundOn) => {
+    if (video === null)
+        return;
+    video.muted = false;
+    setIsSoundOn(true);
+};
+export const forceVolume = (video, volumePercent, setVolume) => {
+    if (video === null)
+        return;
+    const volume = volumePercent / 100;
+    video.volume = volume;
+    setVolume(volume);
+};
+export const forceCurrentTime = (video, time, setCurrentTime) => {
+    if (video === null)
+        return;
+    video.currentTime = time;
+    setCurrentTime(time);
+};
+export const forcePlay = async (video, shouldDisclaimerBeOn, setIsPlaying) => {
+    if (shouldDisclaimerBeOn) {
+        setIsPlaying(false);
+        return;
+    }
+    if (video === null)
+        return;
+    try {
+        await video.play();
+        setIsPlaying(true);
+    }
+    catch (e) {
+        console.error(e);
+    }
+};
+export const forcePause = (video, setIsPlaying) => {
+    if (video === null) {
+        setIsPlaying(false);
+        return;
+    }
+    try {
+        video.pause();
+        setIsPlaying(false);
+    }
+    catch (e) {
+        console.error(e);
+    }
+};
+export const forcePlaybackRate = (video, rate, setPlaybackRate) => {
+    if (video === null)
+        return;
+    video.playbackRate = rate;
+    setPlaybackRate(rate);
+};
+export const forceFullScreen = async (video, shouldDisclaimerBeOn, setIsFullscreen) => {
+    if (shouldDisclaimerBeOn)
+        return;
+    if (video === null) {
+        setIsFullscreen(false);
+        return;
+    }
+    try {
+        await video.requestFullscreen();
+        setIsFullscreen(true);
+    }
+    catch (e) {
+        setIsFullscreen(false);
+        console.error(e);
+    }
+};
+export const forceExitFullScreen = async (video, setIsFullscreen) => {
+    if (video === null || document.fullscreenElement !== video) {
+        setIsFullscreen(false);
+        return;
+    }
+    try {
+        await document.exitFullscreen();
+        setIsFullscreen(false);
+    }
+    catch (e) {
+        console.error(e);
+    }
+};
+/* Time & formats */
+export function secondsToMs(seconds) {
+    return seconds * 1000;
+}
+export function formatTime(ms, format, fps = 25) {
+    const totalSeconds = Math.floor(ms / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = Math.floor(totalSeconds % 60);
+    const frames = Math.floor(((ms % 1000) / 1000) * fps);
+    const msRest = Math.floor(ms % 1000);
+    const tokens = {
+        hh: String(hours).padStart(2, '0'),
+        mm: String(minutes).padStart(2, '0'),
+        ss: String(seconds).padStart(2, '0'),
+        frame: String(frames).padStart(2, '0'),
+        ms: String(msRest).padStart(3, '0'),
+        h: hours,
+        m: minutes,
+        s: seconds,
+        f: frames
+    };
+    const result = Object
+        .keys(tokens)
+        .sort((a, b) => b.length - a.length)
+        .reduce((acc, t) => acc.replace(new RegExp(t, 'g'), String(tokens[t])), format);
+    return result;
+}
+export const getTimelineClickProgress = (event, timeline, video) => {
+    if (video === null || timeline === null)
+        return 0;
+    const timelineRect = event.currentTarget.getBoundingClientRect();
+    const position = event.clientX - timelineRect.left;
+    const progress = Math.min(1, Math.max(0, position / timelineRect.width));
+    return progress;
+};

package/components/_WIP_AudioQuote/index.js

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

package/components/_WIP_Icon/index.js

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

package/components/index.d.ts

@@ -1,15 +1,15 @@
 export * as beforeAfter from './BeforeAfter/index.js'
-export * as disclaimer from './Disclaimer/index.js'
 export * as drawer from './Drawer/index.js'
 export * as eventListener from './EventListener/index.js'
+export * as disclaimer from './Disclaimer/index.js'
 export * as gallery from './Gallery/index.js'
 export * as image from './Image/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
 export * as overlayer from './Overlayer/index.js'
 export * as paginator from './Paginator/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 scrllgngn from './Scrllgngn/index.js'
 export * as sequencer from './Sequencer/index.js'
 export * as shadowRoot from './ShadowRoot/index.js'
 export * as subtitles from './Subtitles/index.js'

package/components/index.js

@@ -1,15 +1,15 @@
 export * as beforeAfter from './BeforeAfter/index.js'
-export * as disclaimer from './Disclaimer/index.js'
 export * as drawer from './Drawer/index.js'
 export * as eventListener from './EventListener/index.js'
+export * as disclaimer from './Disclaimer/index.js'
 export * as gallery from './Gallery/index.js'
 export * as image from './Image/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
 export * as overlayer from './Overlayer/index.js'
 export * as paginator from './Paginator/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 scrllgngn from './Scrllgngn/index.js'
 export * as sequencer from './Sequencer/index.js'
 export * as shadowRoot from './ShadowRoot/index.js'
 export * as subtitles from './Subtitles/index.js'

package/components/public-classnames.js

@@ -0,0 +1,18 @@
+export const beforeAfter = 'dsed-before-after';
+export const disclaimer = 'dsed-disclaimer';
+export const drawer = 'dsed-drawer';
+export const eventListener = 'dsed-event-listener';
+export const gallery = 'dsed-gallery';
+export const image = 'dsed-image';
+export const intersectionObserver = 'dsed-intersection-observer';
+export const overlayer = 'dsed-overlayer';
+export const paginator = 'dsed-paginator';
+export const resizeObserver = 'dsed-resize-observer';
+export const scrllgngn = 'dsed-scrllgngn';
+export const scrollListener = 'dsed-scroll-listener';
+export const sequencer = 'dsed-sequencer';
+export const shadowRoot = 'dsed-shadow-root';
+export const subtitles = 'dsed-subtitles';
+export const theatre = 'dsed-theatre';
+export const uiModule = 'dsed-ui-module';
+export const video = 'dsed-video';

package/components/utils/index.js

@@ -1,7 +1,12 @@
-import {
-  mergeClassNames
-} from "../../chunks/chunk-OFCSIK6J.js";
-import "../../chunks/chunk-WSFCRVEQ.js";
-export {
-  mergeClassNames
-};
+export function mergeClassNames(...names) {
+    return names.map(name => {
+        if (typeof name !== 'string' && !Array.isArray(name))
+            return false;
+        if (Array.isArray(name))
+            return mergeClassNames(...name);
+        if (name.trim() === '')
+            return false;
+        return name.trim();
+    }).filter((name) => typeof name === 'string')
+        .join(' ');
+}

package/components/utils/types.js

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

package/index.d.ts

@@ -1,4 +1,3 @@
-export * as agnostic from './agnostic/index.js'
-export * as chunks from './chunks/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,4 +1,3 @@
-export * as agnostic from './agnostic/index.js'
-export * as chunks from './chunks/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/index.test.js

@@ -0,0 +1,6 @@
+import { describe, it, expect } from 'vitest';
+describe('FAKE-TEST', () => {
+    it('fake test', () => {
+        expect(1).toBe(1);
+    });
+});

package/node/@aws-s3/storage/directory/copy-dir/index.js

@@ -1,9 +1,68 @@
-import {
-  copyDir
-} from "../../../../../chunks/chunk-P4J6S2WQ.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  copyDir
-};
+import { ListObjectsV2Command, CopyObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Recursively copies every object under `sourceDir` to the same relative path
+ * beneath `targetDir` in a single S3 bucket (AWS SDK v3).
+ *
+ * @param {S3Client} client - The v3 S3 client instance.
+ * @param {string} bucketName - The name of the S3 bucket.
+ * @param {string} sourceDir - The source directory prefix to copy from.
+ * @param {string} targetDir - The target directory prefix to copy to.
+ * @param {CopyDirOptions} [options] - Optional copy‑behaviour configuration.
+ * @param {Omit<ListObjectsV2CommandInput,'Bucket'|'Prefix'>} [options.listObjectsOptions] - Extra list parameters.
+ * @param {Omit<CopyObjectCommandInput,'Bucket'|'Key'|'CopySource'>} [options.copyOptions] - Extra copy parameters.
+ * @param {boolean} [options.overwrite=false] - Whether to overwrite existing files at target.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - Success: `Outcome.makeSuccess(true)` if every object is copied.
+ * - Failure: `Outcome.makeFailure(errStr)` on error.
+ */
+export async function copyDir(client, bucketName, sourceDir, targetDir, options) {
+    const { listObjectsOptions, copyOptions, overwrite = false } = options ?? {};
+    const from = sourceDir.endsWith('/') ? sourceDir : `${sourceDir}/`;
+    const to = targetDir.endsWith('/') ? targetDir : `${targetDir}/`;
+    try {
+        let token;
+        do {
+            const listResp = await client.send(new ListObjectsV2Command({
+                Bucket: bucketName,
+                Prefix: from,
+                ContinuationToken: token,
+                ...listObjectsOptions
+            }));
+            for (const obj of listResp.Contents ?? []) {
+                if (obj.Key === undefined)
+                    continue;
+                const rel = obj.Key.substring(from.length);
+                const dest = `${to}${rel}`;
+                if (!overwrite) {
+                    try {
+                        await client.send(new HeadObjectCommand({ Bucket: bucketName, Key: dest }));
+                        // If headObject succeeds, file exists - skip copy
+                        continue;
+                    }
+                    catch (err) {
+                        const code = err?.name ?? err?.$metadata?.httpStatusCode;
+                        if (code !== 'NotFound' && code !== 404) {
+                            return Outcome.makeFailure(unknownToString(err));
+                        }
+                        // Not found, proceed with copy
+                    }
+                }
+                await client.send(new CopyObjectCommand({
+                    Bucket: bucketName,
+                    Key: dest,
+                    CopySource: `${bucketName}/${obj.Key}`,
+                    ...copyOptions
+                }));
+            }
+            token = listResp.IsTruncated === true
+                ? listResp.NextContinuationToken
+                : undefined;
+        } while (token !== undefined);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

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

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

package/node/@aws-s3/storage/directory/list/index.js

@@ -1,9 +1,33 @@
-import {
-  list
-} from "../../../../../chunks/chunk-3RZMW72G.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  list
-};
+import { ListObjectsV2Command } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Lists all direct‑child object keys under a given directory prefix in an S3
+ * bucket (AWS SDK v3). The listing is **non‑recursive**.
+ *
+ * @param {S3Client} client         - The v3 S3 client used to list objects.
+ * @param {string}   bucketName     - The name of the S3 bucket.
+ * @param {string}   directoryPath  - The directory prefix to list.
+ * @param {ListOptions} [options]   - Additional parameters for `ListObjectsV2`.
+ * @returns {Promise<Outcome.Either<string[], string>>}
+ * - Success: `Outcome.makeSuccess(keys)` where `keys` is an array of object keys.
+ * - Failure: `Outcome.makeFailure(errStr)` if the list operation fails.
+ */
+export async function list(client, bucketName, directoryPath, options) {
+    const prefix = directoryPath.endsWith('/') ? directoryPath : `${directoryPath}/`;
+    try {
+        const response = await client.send(new ListObjectsV2Command({
+            Bucket: bucketName,
+            Prefix: prefix,
+            Delimiter: '/',
+            ...options
+        }));
+        const keys = (response.Contents ?? [])
+            .map(obj => obj.Key)
+            .filter((e) => e !== undefined);
+        return Outcome.makeSuccess(keys);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/@aws-s3/storage/directory/move-dir/index.js

@@ -1,9 +1,69 @@
-import {
-  moveDir
-} from "../../../../../chunks/chunk-B5V7D2ZL.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  moveDir
-};
+import { ListObjectsV2Command, CopyObjectCommand, DeleteObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Recursively moves every object under `sourceDir` to the corresponding path
+ * under `targetDir` within the same S3 bucket (AWS SDK v3).
+ *
+ * Behaviour when `overwrite` is **false** (default): abort if *any* destination
+ * key already exists.
+ *
+ * @param {S3Client} client      - The v3 S3 client instance.
+ * @param {string}   bucketName  - The name of the S3 bucket.
+ * @param {string}   sourceDir   - The source directory prefix to move from.
+ * @param {string}   targetDir   - The target directory prefix to move to.
+ * @param {MoveDirOptions} [options] - Optional configuration.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success: `Outcome.makeSuccess(true)`.
+ * - On failure: `Outcome.makeFailure(errStr)`.
+ */
+export async function moveDir(client, bucketName, sourceDir, targetDir, options) {
+    const { listObjectsOptions, copyOptions, deleteOptions, overwrite = false } = options ?? {};
+    const from = sourceDir.endsWith('/') ? sourceDir : `${sourceDir}/`;
+    const to = targetDir.endsWith('/') ? targetDir : `${targetDir}/`;
+    try {
+        let token;
+        do {
+            const listResp = await client.send(new ListObjectsV2Command({
+                Bucket: bucketName,
+                Prefix: from,
+                ContinuationToken: token,
+                ...listObjectsOptions
+            }));
+            for (const obj of listResp.Contents ?? []) {
+                if (obj.Key === undefined)
+                    continue;
+                const rel = obj.Key.substring(from.length);
+                const dest = `${to}${rel}`;
+                if (!overwrite) {
+                    try {
+                        await client.send(new HeadObjectCommand({ Bucket: bucketName, Key: dest }));
+                        throw new Error(`Object already exists at ${dest}.`);
+                    }
+                    catch (err) {
+                        if (err.$metadata?.httpStatusCode !== 404 && err.name !== 'NotFound')
+                            throw err;
+                    }
+                }
+                await client.send(new CopyObjectCommand({
+                    Bucket: bucketName,
+                    Key: dest,
+                    CopySource: `${bucketName}/${obj.Key}`,
+                    ...copyOptions
+                }));
+                await client.send(new DeleteObjectCommand({
+                    Bucket: bucketName,
+                    Key: obj.Key,
+                    ...deleteOptions
+                }));
+            }
+            token = listResp.IsTruncated === true
+                ? listResp.NextContinuationToken
+                : undefined;
+        } while (token !== undefined);
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

package/node/@aws-s3/storage/directory/remove-dir/index.js

@@ -1,9 +1,59 @@
-import {
-  removeDir
-} from "../../../../../chunks/chunk-UTQNGKGQ.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  removeDir
-};
+import { ListObjectsV2Command, DeleteObjectsCommand } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Recursively deletes all objects under a directory prefix in an S3 bucket
+ * using the AWS SDK v3 client. Handles pagination and the 1 000‑key limit of
+ * `DeleteObjects`.
+ *
+ * @param {S3Client}  client           - The v3 S3 client instance.
+ * @param {string}    bucketName       - The name of the S3 bucket.
+ * @param {string}    directoryPath    - The “directory” prefix to delete.
+ * @param {RemoveDirOptions} [options] - Optional listing/deletion configuration.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success: `Outcome.makeSuccess(true)` – deletion succeeded, or prefix
+ *   absent and `ignoreMissing` is true.
+ * - On failure: `Outcome.makeFailure(errStr)` if deletion fails, or prefix
+ *   absent and `ignoreMissing` is false.
+ */
+export async function removeDir(client, bucketName, directoryPath, options) {
+    const { listObjectsOptions, deleteObjectsOptions, ignoreMissing = true } = options ?? {};
+    const prefix = directoryPath.endsWith('/') ? directoryPath : `${directoryPath}/`;
+    let continuationToken;
+    let anyFound = false;
+    try {
+        do {
+            const listResp = await client.send(new ListObjectsV2Command({
+                Bucket: bucketName,
+                Prefix: prefix,
+                ContinuationToken: continuationToken,
+                ...listObjectsOptions
+            }));
+            const keys = (listResp.Contents ?? [])
+                .map(o => o.Key)
+                .filter(e => e !== undefined);
+            if (keys.length > 0) {
+                anyFound = true;
+                // Delete in batches of ≤ 1 000 keys
+                for (let i = 0; i < keys.length; i += 1000) {
+                    const chunk = keys.slice(i, i + 1000);
+                    await client.send(new DeleteObjectsCommand({
+                        Bucket: bucketName,
+                        Delete: { Objects: chunk.map(Key => ({ Key })) },
+                        ...deleteObjectsOptions
+                    }));
+                }
+            }
+            continuationToken = listResp.IsTruncated === true
+                ? listResp.NextContinuationToken
+                : undefined;
+        } while (continuationToken !== undefined);
+        if (!anyFound && !ignoreMissing) {
+            return Outcome.makeFailure(`No objects found for prefix "${prefix}".`);
+        }
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

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

@@ -1,9 +1,43 @@
-import {
-  copy
-} from "../../../../../chunks/chunk-U664BT44.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  copy
-};
+import { CopyObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Copies an object from one key to another within the same S3 bucket.
+ *
+ * @param {S3Client} client            - The v3 S3 client instance.
+ * @param {string}   bucketName        - The name of the S3 bucket.
+ * @param {string}   sourcePath        - The key of the source object.
+ * @param {string}   targetPath        - The key where the object will be copied.
+ * @param {CopyOptions} [options]      - Optional copy configuration.
+ * @param {Omit<CopyObjectCommandInput,'Bucket'|'Key'|'CopySource'>} [options.copyOptions] - Extra copy params.
+ * @param {boolean} [options.overwrite=false] - Whether to overwrite an existing object.
+ * @returns {Promise<Outcome.Either<true, string>>}
+ * - On success:  `Outcome.makeSuccess(true)`.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function copy(client, bucketName, sourcePath, targetPath, options) {
+    const { copyOptions, overwrite = false } = options ?? {};
+    try {
+        if (!overwrite) {
+            try {
+                await client.send(new HeadObjectCommand({ Bucket: bucketName, Key: targetPath }));
+                return Outcome.makeFailure(`Object already exists at ${targetPath}.`);
+            }
+            catch (err) {
+                const notFound = err.$metadata?.httpStatusCode === 404 || err.name === 'NotFound';
+                if (!notFound)
+                    throw err; // propagate unexpected errors
+            }
+        }
+        await client.send(new CopyObjectCommand({
+            Bucket: bucketName,
+            Key: targetPath,
+            CopySource: `${bucketName}/${sourcePath}`,
+            ...copyOptions
+        }));
+        return Outcome.makeSuccess(true);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}

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

@@ -1,9 +1,30 @@
-import {
-  download
-} from "../../../../../chunks/chunk-2GJSPEO4.js";
-import "../../../../../chunks/chunk-LUAYN7VJ.js";
-import "../../../../../chunks/chunk-PUQUSA6S.js";
-import "../../../../../chunks/chunk-WSFCRVEQ.js";
-export {
-  download
-};
+import { GetObjectCommand } from '@aws-sdk/client-s3';
+import * as Outcome from '../../../../../agnostic/misc/outcome/index.js';
+import { unknownToString } from '../../../../../agnostic/errors/unknown-to-string/index.js';
+/**
+ * Downloads a file from a specified Amazon S3 bucket.
+ *
+ * The function streams the object’s content back as a Node `Readable`.
+ *
+ * @param {S3Client} client       - The v3 S3 client instance.
+ * @param {string}   bucketName   - The name of the S3 bucket.
+ * @param {string}   sourcePath   - The key of the object to download.
+ * @param {DownloadOptions} [options] - Extra parameters for the download.
+ * @returns {Promise<Outcome.Either<Readable, string>>}
+ * - On success:  `Outcome.makeSuccess(stream)` containing the file content.
+ * - On failure:  `Outcome.makeFailure(errStr)`.
+ */
+export async function download(client, bucketName, sourcePath, options) {
+    try {
+        const response = await client.send(new GetObjectCommand({
+            Bucket: bucketName,
+            Key: sourcePath,
+            ...options
+        }));
+        const stream = response.Body;
+        return Outcome.makeSuccess(stream);
+    }
+    catch (err) {
+        return Outcome.makeFailure(unknownToString(err));
+    }
+}