@flystorage/file-storage 1.0.1 → 1.1.0

package/changelog.md

@@ -1,5 +1,13 @@
 # `@flystorage/file-storage`
 
+## 1.1.0
+
+## Added
+
+- AbortSignal Support
+- Normalised over stream errors for reads
+- Introduce way to detect failed reads because of missing files.
+
 ## 1.0.1
 
 ### Fixes

package/dist/cjs/errors.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnableToListDirectory = exports.UnableToCheckDirectoryExistence = exports.UnableToCheckFileExistence = exports.UnableToDeleteFile = exports.UnableToDeleteDirectory = exports.UnableToCreateDirectory = exports.UnableToGetStat = exports.UnableToMoveFile = exports.UnableToCopyFile = exports.UnableToPrepareUploadRequest = exports.UnableToGetTemporaryUrl = exports.UnableToGetPublicUrl = exports.UnableToGetVisibility = exports.UnableToSetVisibility = exports.UnableToReadFile = exports.UnableToWriteFile = exports.UnableToGetFileSize = exports.UnableToGetLastModified = exports.UnableToGetMimeType = exports.UnableToGetChecksum = exports.ChecksumIsNotAvailable = exports.FlystorageError = void 0;
+exports.UnableToListDirectory = exports.UnableToCheckDirectoryExistence = exports.UnableToCheckFileExistence = exports.UnableToDeleteFile = exports.UnableToDeleteDirectory = exports.UnableToCreateDirectory = exports.UnableToGetStat = exports.UnableToMoveFile = exports.UnableToCopyFile = exports.UnableToPrepareUploadRequest = exports.UnableToGetTemporaryUrl = exports.UnableToGetPublicUrl = exports.UnableToGetVisibility = exports.UnableToSetVisibility = exports.FileWasNotFound = exports.UnableToReadFile = exports.UnableToWriteFile = exports.UnableToGetFileSize = exports.UnableToGetLastModified = exports.UnableToGetMimeType = exports.UnableToGetChecksum = exports.ChecksumIsNotAvailable = exports.FlystorageError = void 0;
 exports.errorToMessage = errorToMessage;
+exports.isFileWasNotFound = isFileWasNotFound;
 function errorToMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -59,10 +60,26 @@ class UnableToWriteFile extends FlystorageError {
 }
 exports.UnableToWriteFile = UnableToWriteFile;
 class UnableToReadFile extends FlystorageError {
+    wasFileNotFound;
+    context;
     code = 'flystorage.unable_to_read_file';
-    static because = (reason, { context = {}, cause = undefined }) => new UnableToReadFile(`Unable to read the file. Reason: ${reason}`, context, cause);
+    constructor(wasFileNotFound, message, context = {}, cause = undefined) {
+        super(message, context, cause);
+        this.wasFileNotFound = wasFileNotFound;
+        this.context = context;
+    }
+    static because = (reason, { context = {}, cause = undefined }) => new UnableToReadFile(false, `Unable to read the file. Reason: ${reason}`, context, cause);
+    static becauseFileWasNotFound = (error) => new UnableToReadFile(true, `Unable to read the file. Reason: ${error.message}`, error.context, error);
 }
 exports.UnableToReadFile = UnableToReadFile;
+class FileWasNotFound extends FlystorageError {
+    code = 'flystorage.file_was_not_found';
+    static atLocation = (location, { context = {}, cause = undefined }) => new FileWasNotFound(`File was not found at location: ${location}`, context, cause);
+}
+exports.FileWasNotFound = FileWasNotFound;
+function isFileWasNotFound(error) {
+    return (typeof error === 'object' && error.code === 'flystorage.file_was_not_found');
+}
 class UnableToSetVisibility extends FlystorageError {
     code = 'flystorage.unable_to_set_visibility';
     static because = (reason, { context = {}, cause = undefined }) => new UnableToSetVisibility(`Unable to set visibility. Reason: ${reason}`, context, cause);

package/dist/cjs/file-storage.js

@@ -8,12 +8,14 @@ exports.normalizeExpiryToDate = normalizeExpiryToDate;
 exports.normalizeExpiryToMilliseconds = normalizeExpiryToMilliseconds;
 exports.closeReadable = closeReadable;
 exports.readableToString = readableToString;
+exports.readableToBuffer = readableToBuffer;
 exports.readableToUint8Array = readableToUint8Array;
 const stream_1 = require("stream");
 const checksum_from_stream_js_1 = require("./checksum-from-stream.js");
 const path_normalizer_js_1 = require("./path-normalizer.js");
 const util_1 = require("util");
 const errors_js_1 = require("./errors.js");
+const node_stream_1 = require("node:stream");
 function isFile(stat) {
     return stat.isFile;
 }
@@ -67,8 +69,28 @@ function toReadable(contents) {
 }
 const naturalSorting = new Intl.Collator(undefined, {
     numeric: true,
-    sensitivity: 'base'
+    sensitivity: 'base',
 });
+function instrumentAbortSignal(options) {
+    let abortSignal = options.abortSignal;
+    if (options.timeout !== undefined) {
+        const timeoutAbort = AbortSignal.timeout(options.timeout);
+        if (options.abortSignal) {
+            const originalAbortSignal = options.abortSignal;
+            abortSignal = AbortSignal.any([
+                originalAbortSignal,
+                timeoutAbort,
+            ]);
+        }
+        else {
+            abortSignal = timeoutAbort;
+        }
+    }
+    if (abortSignal?.aborted) {
+        throw abortSignal.reason;
+    }
+    return { ...options, abortSignal };
+}
 class FileStorage {
     adapter;
     pathNormalizer;
@@ -79,145 +101,172 @@ class FileStorage {
         this.options = options;
     }
     async write(path, contents, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.visibility, ...this.options.writes, ...options });
         try {
             const body = toReadable(contents);
-            await this.adapter.write(this.pathNormalizer.normalizePath(path), body, { ...this.options.visibility, ...this.options.writes, ...options });
+            await this.adapter.write(this.pathNormalizer.normalizePath(path), body, options);
             await closeReadable(body);
         }
         catch (error) {
             throw errors_js_1.UnableToWriteFile.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path, options } });
         }
     }
-    async read(path) {
+    async read(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return stream_1.Readable.from(await this.adapter.read(this.pathNormalizer.normalizePath(path)));
+            const stream = stream_1.Readable.from(await this.adapter.read(this.pathNormalizer.normalizePath(path), options));
+            const streamOut = new node_stream_1.PassThrough();
+            stream.on('error', (error) => {
+                stream.unpipe(streamOut);
+                streamOut.destroy((0, errors_js_1.isFileWasNotFound)(error)
+                    ? errors_js_1.UnableToReadFile.becauseFileWasNotFound(error)
+                    : error);
+            });
+            stream.pipe(streamOut);
+            return streamOut;
         }
         catch (error) {
+            if ((0, errors_js_1.isFileWasNotFound)(error)) {
+                throw errors_js_1.UnableToReadFile.becauseFileWasNotFound(error);
+            }
             throw errors_js_1.UnableToReadFile.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path } });
         }
     }
-    async readToString(path) {
-        return await readableToString(await this.read(path));
+    async readToString(path, options = {}) {
+        return await readableToString(await this.read(path, options));
     }
-    async readToUint8Array(path) {
-        return await readableToUint8Array(await this.read(path));
+    async readToUint8Array(path, options = {}) {
+        return await readableToUint8Array(await this.read(path, options));
     }
-    async readToBuffer(path) {
-        return Buffer.from(await this.readToUint8Array(path));
+    async readToBuffer(path, options = {}) {
+        return Buffer.from(await this.readToUint8Array(path, options));
     }
-    async deleteFile(path) {
+    async deleteFile(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            await this.adapter.deleteFile(this.pathNormalizer.normalizePath(path));
+            await this.adapter.deleteFile(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToDeleteFile.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path } });
         }
     }
     async createDirectory(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.visibility, ...options });
         try {
-            return await this.adapter.createDirectory(this.pathNormalizer.normalizePath(path), { ...this.options.visibility, ...options });
+            return await this.adapter.createDirectory(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToCreateDirectory.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path, options } });
         }
     }
-    async deleteDirectory(path) {
+    async deleteDirectory(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.deleteDirectory(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.deleteDirectory(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToDeleteDirectory.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path } });
         }
     }
-    async stat(path) {
+    async stat(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.stat(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.stat(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToGetStat.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path } });
         }
     }
     async moveFile(from, to, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.visibility, ...this.options.moves, ...options });
         try {
-            await this.adapter.moveFile(this.pathNormalizer.normalizePath(from), this.pathNormalizer.normalizePath(to), { ...this.options.visibility, ...this.options.moves, ...options });
+            await this.adapter.moveFile(this.pathNormalizer.normalizePath(from), this.pathNormalizer.normalizePath(to), options);
         }
         catch (error) {
             throw errors_js_1.UnableToMoveFile.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { from, to } });
         }
     }
     async copyFile(from, to, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.visibility, ...this.options.copies, ...options });
         try {
-            await this.adapter.copyFile(this.pathNormalizer.normalizePath(from), this.pathNormalizer.normalizePath(to), { ...this.options.visibility, ...this.options.copies, ...options });
+            await this.adapter.copyFile(this.pathNormalizer.normalizePath(from), this.pathNormalizer.normalizePath(to), options);
         }
         catch (error) {
             throw errors_js_1.UnableToCopyFile.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { from, to } });
         }
     }
-    /**
-     * @deprecated use changeVisibility instead
-     */
-    async setVisibility(path, visibility) {
-        return this.changeVisibility(path, visibility);
-    }
-    async changeVisibility(path, visibility) {
+    async changeVisibility(path, visibility, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.changeVisibility(this.pathNormalizer.normalizePath(path), visibility);
+            return await this.adapter.changeVisibility(this.pathNormalizer.normalizePath(path), visibility, options);
         }
         catch (error) {
             throw errors_js_1.UnableToSetVisibility.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path, visibility } });
         }
     }
-    async visibility(path) {
+    async visibility(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.visibility(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.visibility(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToGetVisibility.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path } });
         }
     }
-    async fileExists(path) {
+    async fileExists(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.fileExists(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.fileExists(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToCheckFileExistence.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path } });
         }
     }
-    list(path, { deep = false } = {}) {
-        return new DirectoryListing(this.adapter.list(this.pathNormalizer.normalizePath(path), { deep }), path, deep);
+    list(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
+        const adapterOptions = {
+            ...options,
+            deep: options.deep ?? false,
+        };
+        return new DirectoryListing(this.adapter.list(this.pathNormalizer.normalizePath(path), adapterOptions), path, adapterOptions.deep);
     }
-    async statFile(path) {
-        const stat = await this.stat(path);
+    async statFile(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
+        const stat = await this.stat(path, options);
         if (isFile(stat)) {
             return stat;
         }
         throw errors_js_1.UnableToGetStat.noFileStatResolved({ context: { path } });
     }
-    async directoryExists(path) {
+    async directoryExists(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.directoryExists(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.directoryExists(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToCheckDirectoryExistence.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path } });
         }
     }
     async publicUrl(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.publicUrls, ...options });
         try {
-            return await this.adapter.publicUrl(this.pathNormalizer.normalizePath(path), { ...this.options.publicUrls, ...options });
+            return await this.adapter.publicUrl(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToGetPublicUrl.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path, options } });
         }
     }
     async temporaryUrl(path, options) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.temporaryUrls, ...options });
         try {
-            return await this.adapter.temporaryUrl(this.pathNormalizer.normalizePath(path), { ...this.options.temporaryUrls, ...options });
+            return await this.adapter.temporaryUrl(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToGetTemporaryUrl.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path, options } });
         }
     }
     async prepareUpload(path, options) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.uploadRequest, ...options });
         if (this.options.preparedUploadStrategy !== undefined) {
             try {
                 return this.options.preparedUploadStrategy.prepareUpload(path, options);
@@ -230,15 +279,16 @@ class FileStorage {
             throw new Error('The used adapter does not support prepared uploads.');
         }
         try {
-            return await this.adapter.prepareUpload(this.pathNormalizer.normalizePath(path), { ...this.options.uploadRequest, ...options });
+            return await this.adapter.prepareUpload(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToPrepareUploadRequest.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path, options } });
         }
     }
     async checksum(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.checksums, ...options });
         try {
-            return await this.adapter.checksum(this.pathNormalizer.normalizePath(path), { ...this.options.checksums, ...options });
+            return await this.adapter.checksum(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             if (errors_js_1.ChecksumIsNotAvailable.isErrorOfType(error)) {
@@ -248,24 +298,27 @@ class FileStorage {
         }
     }
     async mimeType(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.mimeTypes, ...options });
         try {
-            return await this.adapter.mimeType(this.pathNormalizer.normalizePath(path), { ...this.options.mimeTypes, ...options });
+            return await this.adapter.mimeType(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToGetMimeType.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path, options } });
         }
     }
-    async lastModified(path) {
+    async lastModified(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.lastModified(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.lastModified(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToGetLastModified.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path } });
         }
     }
-    async fileSize(path) {
+    async fileSize(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.fileSize(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.fileSize(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw errors_js_1.UnableToGetFileSize.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path } });
@@ -273,7 +326,7 @@ class FileStorage {
     }
     async calculateChecksum(path, options) {
         try {
-            return await (0, checksum_from_stream_js_1.checksumFromStream)(await this.read(path), options);
+            return await (0, checksum_from_stream_js_1.checksumFromStream)(await this.read(path, options), options);
         }
         catch (error) {
             throw errors_js_1.UnableToGetChecksum.because((0, errors_js_1.errorToMessage)(error), { cause: error, context: { path, options } });
@@ -292,6 +345,7 @@ async function closeReadable(body) {
         return;
     }
     await new Promise((resolve, reject) => {
+        body.on('error', reject);
         body.on('close', (err) => {
             err ? reject(err) : resolve();
         });
@@ -304,6 +358,15 @@ async function readableToString(stream) {
     await closeReadable(stream);
     return contents;
 }
+async function readableToBuffer(stream) {
+    return new Promise((resolve, reject) => {
+        const buffers = [];
+        stream.on('data', chunk => buffers.push(Buffer.from(chunk)));
+        stream.on('end', () => resolve(Buffer.concat(buffers)));
+        stream.on('finish', () => resolve(Buffer.concat(buffers)));
+        stream.on('error', err => reject(err));
+    });
+}
 const encoder = new util_1.TextEncoder();
 function readableToUint8Array(stream) {
     return new Promise((resolve, reject) => {

package/dist/esm/errors.js

@@ -48,8 +48,23 @@ export class UnableToWriteFile extends FlystorageError {
     static because = (reason, { context = {}, cause = undefined }) => new UnableToWriteFile(`Unable to write the file. Reason: ${reason}`, context, cause);
 }
 export class UnableToReadFile extends FlystorageError {
+    wasFileNotFound;
+    context;
     code = 'flystorage.unable_to_read_file';
-    static because = (reason, { context = {}, cause = undefined }) => new UnableToReadFile(`Unable to read the file. Reason: ${reason}`, context, cause);
+    constructor(wasFileNotFound, message, context = {}, cause = undefined) {
+        super(message, context, cause);
+        this.wasFileNotFound = wasFileNotFound;
+        this.context = context;
+    }
+    static because = (reason, { context = {}, cause = undefined }) => new UnableToReadFile(false, `Unable to read the file. Reason: ${reason}`, context, cause);
+    static becauseFileWasNotFound = (error) => new UnableToReadFile(true, `Unable to read the file. Reason: ${error.message}`, error.context, error);
+}
+export class FileWasNotFound extends FlystorageError {
+    code = 'flystorage.file_was_not_found';
+    static atLocation = (location, { context = {}, cause = undefined }) => new FileWasNotFound(`File was not found at location: ${location}`, context, cause);
+}
+export function isFileWasNotFound(error) {
+    return (typeof error === 'object' && error.code === 'flystorage.file_was_not_found');
 }
 export class UnableToSetVisibility extends FlystorageError {
     code = 'flystorage.unable_to_set_visibility';

package/dist/esm/file-storage.js

@@ -1,8 +1,9 @@
 import { Readable } from 'stream';
 import { checksumFromStream } from './checksum-from-stream.js';
 import { PathNormalizerV1 } from './path-normalizer.js';
-import { TextEncoder } from "util";
-import { ChecksumIsNotAvailable, errorToMessage, UnableToCheckDirectoryExistence, UnableToCheckFileExistence, UnableToCopyFile, UnableToCreateDirectory, UnableToDeleteDirectory, UnableToDeleteFile, UnableToGetChecksum, UnableToGetFileSize, UnableToGetLastModified, UnableToGetMimeType, UnableToGetPublicUrl, UnableToGetStat, UnableToGetTemporaryUrl, UnableToGetVisibility, UnableToListDirectory, UnableToMoveFile, UnableToPrepareUploadRequest, UnableToReadFile, UnableToSetVisibility, UnableToWriteFile, } from './errors.js';
+import { TextEncoder } from 'util';
+import { ChecksumIsNotAvailable, errorToMessage, isFileWasNotFound, UnableToCheckDirectoryExistence, UnableToCheckFileExistence, UnableToCopyFile, UnableToCreateDirectory, UnableToDeleteDirectory, UnableToDeleteFile, UnableToGetChecksum, UnableToGetFileSize, UnableToGetLastModified, UnableToGetMimeType, UnableToGetPublicUrl, UnableToGetStat, UnableToGetTemporaryUrl, UnableToGetVisibility, UnableToListDirectory, UnableToMoveFile, UnableToPrepareUploadRequest, UnableToReadFile, UnableToSetVisibility, UnableToWriteFile, } from './errors.js';
+import { PassThrough } from 'node:stream';
 export function isFile(stat) {
     return stat.isFile;
 }
@@ -55,8 +56,28 @@ export function toReadable(contents) {
 }
 const naturalSorting = new Intl.Collator(undefined, {
     numeric: true,
-    sensitivity: 'base'
+    sensitivity: 'base',
 });
+function instrumentAbortSignal(options) {
+    let abortSignal = options.abortSignal;
+    if (options.timeout !== undefined) {
+        const timeoutAbort = AbortSignal.timeout(options.timeout);
+        if (options.abortSignal) {
+            const originalAbortSignal = options.abortSignal;
+            abortSignal = AbortSignal.any([
+                originalAbortSignal,
+                timeoutAbort,
+            ]);
+        }
+        else {
+            abortSignal = timeoutAbort;
+        }
+    }
+    if (abortSignal?.aborted) {
+        throw abortSignal.reason;
+    }
+    return { ...options, abortSignal };
+}
 export class FileStorage {
     adapter;
     pathNormalizer;
@@ -67,145 +88,172 @@ export class FileStorage {
         this.options = options;
     }
     async write(path, contents, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.visibility, ...this.options.writes, ...options });
         try {
             const body = toReadable(contents);
-            await this.adapter.write(this.pathNormalizer.normalizePath(path), body, { ...this.options.visibility, ...this.options.writes, ...options });
+            await this.adapter.write(this.pathNormalizer.normalizePath(path), body, options);
             await closeReadable(body);
         }
         catch (error) {
             throw UnableToWriteFile.because(errorToMessage(error), { cause: error, context: { path, options } });
         }
     }
-    async read(path) {
+    async read(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return Readable.from(await this.adapter.read(this.pathNormalizer.normalizePath(path)));
+            const stream = Readable.from(await this.adapter.read(this.pathNormalizer.normalizePath(path), options));
+            const streamOut = new PassThrough();
+            stream.on('error', (error) => {
+                stream.unpipe(streamOut);
+                streamOut.destroy(isFileWasNotFound(error)
+                    ? UnableToReadFile.becauseFileWasNotFound(error)
+                    : error);
+            });
+            stream.pipe(streamOut);
+            return streamOut;
         }
         catch (error) {
+            if (isFileWasNotFound(error)) {
+                throw UnableToReadFile.becauseFileWasNotFound(error);
+            }
             throw UnableToReadFile.because(errorToMessage(error), { cause: error, context: { path } });
         }
     }
-    async readToString(path) {
-        return await readableToString(await this.read(path));
+    async readToString(path, options = {}) {
+        return await readableToString(await this.read(path, options));
     }
-    async readToUint8Array(path) {
-        return await readableToUint8Array(await this.read(path));
+    async readToUint8Array(path, options = {}) {
+        return await readableToUint8Array(await this.read(path, options));
     }
-    async readToBuffer(path) {
-        return Buffer.from(await this.readToUint8Array(path));
+    async readToBuffer(path, options = {}) {
+        return Buffer.from(await this.readToUint8Array(path, options));
     }
-    async deleteFile(path) {
+    async deleteFile(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            await this.adapter.deleteFile(this.pathNormalizer.normalizePath(path));
+            await this.adapter.deleteFile(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToDeleteFile.because(errorToMessage(error), { cause: error, context: { path } });
         }
     }
     async createDirectory(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.visibility, ...options });
         try {
-            return await this.adapter.createDirectory(this.pathNormalizer.normalizePath(path), { ...this.options.visibility, ...options });
+            return await this.adapter.createDirectory(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToCreateDirectory.because(errorToMessage(error), { cause: error, context: { path, options } });
         }
     }
-    async deleteDirectory(path) {
+    async deleteDirectory(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.deleteDirectory(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.deleteDirectory(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToDeleteDirectory.because(errorToMessage(error), { cause: error, context: { path } });
         }
     }
-    async stat(path) {
+    async stat(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.stat(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.stat(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToGetStat.because(errorToMessage(error), { cause: error, context: { path } });
         }
     }
     async moveFile(from, to, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.visibility, ...this.options.moves, ...options });
         try {
-            await this.adapter.moveFile(this.pathNormalizer.normalizePath(from), this.pathNormalizer.normalizePath(to), { ...this.options.visibility, ...this.options.moves, ...options });
+            await this.adapter.moveFile(this.pathNormalizer.normalizePath(from), this.pathNormalizer.normalizePath(to), options);
         }
         catch (error) {
             throw UnableToMoveFile.because(errorToMessage(error), { cause: error, context: { from, to } });
         }
     }
     async copyFile(from, to, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.visibility, ...this.options.copies, ...options });
         try {
-            await this.adapter.copyFile(this.pathNormalizer.normalizePath(from), this.pathNormalizer.normalizePath(to), { ...this.options.visibility, ...this.options.copies, ...options });
+            await this.adapter.copyFile(this.pathNormalizer.normalizePath(from), this.pathNormalizer.normalizePath(to), options);
         }
         catch (error) {
             throw UnableToCopyFile.because(errorToMessage(error), { cause: error, context: { from, to } });
         }
     }
-    /**
-     * @deprecated use changeVisibility instead
-     */
-    async setVisibility(path, visibility) {
-        return this.changeVisibility(path, visibility);
-    }
-    async changeVisibility(path, visibility) {
+    async changeVisibility(path, visibility, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.changeVisibility(this.pathNormalizer.normalizePath(path), visibility);
+            return await this.adapter.changeVisibility(this.pathNormalizer.normalizePath(path), visibility, options);
         }
         catch (error) {
             throw UnableToSetVisibility.because(errorToMessage(error), { cause: error, context: { path, visibility } });
         }
     }
-    async visibility(path) {
+    async visibility(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.visibility(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.visibility(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToGetVisibility.because(errorToMessage(error), { cause: error, context: { path } });
         }
     }
-    async fileExists(path) {
+    async fileExists(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.fileExists(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.fileExists(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToCheckFileExistence.because(errorToMessage(error), { cause: error, context: { path } });
         }
     }
-    list(path, { deep = false } = {}) {
-        return new DirectoryListing(this.adapter.list(this.pathNormalizer.normalizePath(path), { deep }), path, deep);
+    list(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
+        const adapterOptions = {
+            ...options,
+            deep: options.deep ?? false,
+        };
+        return new DirectoryListing(this.adapter.list(this.pathNormalizer.normalizePath(path), adapterOptions), path, adapterOptions.deep);
     }
-    async statFile(path) {
-        const stat = await this.stat(path);
+    async statFile(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
+        const stat = await this.stat(path, options);
         if (isFile(stat)) {
             return stat;
         }
         throw UnableToGetStat.noFileStatResolved({ context: { path } });
     }
-    async directoryExists(path) {
+    async directoryExists(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.directoryExists(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.directoryExists(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToCheckDirectoryExistence.because(errorToMessage(error), { cause: error, context: { path } });
         }
     }
     async publicUrl(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.publicUrls, ...options });
         try {
-            return await this.adapter.publicUrl(this.pathNormalizer.normalizePath(path), { ...this.options.publicUrls, ...options });
+            return await this.adapter.publicUrl(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToGetPublicUrl.because(errorToMessage(error), { cause: error, context: { path, options } });
         }
     }
     async temporaryUrl(path, options) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.temporaryUrls, ...options });
         try {
-            return await this.adapter.temporaryUrl(this.pathNormalizer.normalizePath(path), { ...this.options.temporaryUrls, ...options });
+            return await this.adapter.temporaryUrl(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToGetTemporaryUrl.because(errorToMessage(error), { cause: error, context: { path, options } });
         }
     }
     async prepareUpload(path, options) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.uploadRequest, ...options });
         if (this.options.preparedUploadStrategy !== undefined) {
             try {
                 return this.options.preparedUploadStrategy.prepareUpload(path, options);
@@ -218,15 +266,16 @@ export class FileStorage {
             throw new Error('The used adapter does not support prepared uploads.');
         }
         try {
-            return await this.adapter.prepareUpload(this.pathNormalizer.normalizePath(path), { ...this.options.uploadRequest, ...options });
+            return await this.adapter.prepareUpload(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToPrepareUploadRequest.because(errorToMessage(error), { cause: error, context: { path, options } });
         }
     }
     async checksum(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.checksums, ...options });
         try {
-            return await this.adapter.checksum(this.pathNormalizer.normalizePath(path), { ...this.options.checksums, ...options });
+            return await this.adapter.checksum(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             if (ChecksumIsNotAvailable.isErrorOfType(error)) {
@@ -236,24 +285,27 @@ export class FileStorage {
         }
     }
     async mimeType(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.mimeTypes, ...options });
         try {
-            return await this.adapter.mimeType(this.pathNormalizer.normalizePath(path), { ...this.options.mimeTypes, ...options });
+            return await this.adapter.mimeType(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToGetMimeType.because(errorToMessage(error), { cause: error, context: { path, options } });
         }
     }
-    async lastModified(path) {
+    async lastModified(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.lastModified(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.lastModified(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToGetLastModified.because(errorToMessage(error), { cause: error, context: { path } });
         }
     }
-    async fileSize(path) {
+    async fileSize(path, options = {}) {
+        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
         try {
-            return await this.adapter.fileSize(this.pathNormalizer.normalizePath(path));
+            return await this.adapter.fileSize(this.pathNormalizer.normalizePath(path), options);
         }
         catch (error) {
             throw UnableToGetFileSize.because(errorToMessage(error), { cause: error, context: { path } });
@@ -261,7 +313,7 @@ export class FileStorage {
     }
     async calculateChecksum(path, options) {
         try {
-            return await checksumFromStream(await this.read(path), options);
+            return await checksumFromStream(await this.read(path, options), options);
         }
         catch (error) {
             throw UnableToGetChecksum.because(errorToMessage(error), { cause: error, context: { path, options } });
@@ -279,6 +331,7 @@ export async function closeReadable(body) {
         return;
     }
     await new Promise((resolve, reject) => {
+        body.on('error', reject);
         body.on('close', (err) => {
             err ? reject(err) : resolve();
         });
@@ -291,6 +344,15 @@ export async function readableToString(stream) {
     await closeReadable(stream);
     return contents;
 }
+export async function readableToBuffer(stream) {
+    return new Promise((resolve, reject) => {
+        const buffers = [];
+        stream.on('data', chunk => buffers.push(Buffer.from(chunk)));
+        stream.on('end', () => resolve(Buffer.concat(buffers)));
+        stream.on('finish', () => resolve(Buffer.concat(buffers)));
+        stream.on('error', err => reject(err));
+    });
+}
 const encoder = new TextEncoder();
 export function readableToUint8Array(stream) {
     return new Promise((resolve, reject) => {

package/dist/types/errors.d.ts

@@ -61,12 +61,24 @@ export declare class UnableToWriteFile extends FlystorageError {
     }) => UnableToWriteFile;
 }
 export declare class UnableToReadFile extends FlystorageError {
+    readonly wasFileNotFound: boolean;
+    readonly context: ErrorContext;
     readonly code = "flystorage.unable_to_read_file";
+    constructor(wasFileNotFound: boolean, message: string, context?: ErrorContext, cause?: unknown);
     static because: (reason: string, { context, cause }: {
         context?: ErrorContext;
         cause?: unknown;
     }) => UnableToReadFile;
+    static becauseFileWasNotFound: (error: FileWasNotFound) => UnableToReadFile;
+}
+export declare class FileWasNotFound extends FlystorageError {
+    readonly code = "flystorage.file_was_not_found";
+    static atLocation: (location: string, { context, cause }: {
+        context?: ErrorContext;
+        cause?: unknown;
+    }) => FileWasNotFound;
 }
+export declare function isFileWasNotFound(error: unknown): error is FileWasNotFound;
 export declare class UnableToSetVisibility extends FlystorageError {
     readonly code = "flystorage.unable_to_set_visibility";
     static because: (reason: string, { context, cause }: {

package/dist/types/file-storage.d.ts

@@ -21,29 +21,30 @@ export type DirectoryInfo = Readonly<{
 export declare function isFile(stat: StatEntry): stat is FileInfo;
 export declare function isDirectory(stat: StatEntry): stat is DirectoryInfo;
 export type StatEntry = FileInfo | DirectoryInfo;
+export type AdapterListOptions = ListOptions & {
+    deep: boolean;
+};
 export interface StorageAdapter {
     write(path: string, contents: Readable, options: WriteOptions): Promise<void>;
-    read(path: string): Promise<FileContents>;
-    deleteFile(path: string): Promise<void>;
+    read(path: string, options: MiscellaneousOptions): Promise<FileContents>;
+    deleteFile(path: string, options: MiscellaneousOptions): Promise<void>;
     createDirectory(path: string, options: CreateDirectoryOptions): Promise<void>;
     copyFile(from: string, to: string, options: CopyFileOptions): Promise<void>;
     moveFile(from: string, to: string, options: MoveFileOptions): Promise<void>;
-    stat(path: string): Promise<StatEntry>;
-    list(path: string, options: {
-        deep: boolean;
-    }): AsyncGenerator<StatEntry>;
-    changeVisibility(path: string, visibility: string): Promise<void>;
-    visibility(path: string): Promise<string>;
-    deleteDirectory(path: string): Promise<void>;
-    fileExists(path: string): Promise<boolean>;
-    directoryExists(path: string): Promise<boolean>;
+    stat(path: string, options: MiscellaneousOptions): Promise<StatEntry>;
+    list(path: string, options: AdapterListOptions): AsyncGenerator<StatEntry>;
+    changeVisibility(path: string, visibility: string, options: MiscellaneousOptions): Promise<void>;
+    visibility(path: string, options: MiscellaneousOptions): Promise<string>;
+    deleteDirectory(path: string, options: MiscellaneousOptions): Promise<void>;
+    fileExists(path: string, options: MiscellaneousOptions): Promise<boolean>;
+    directoryExists(path: string, options: MiscellaneousOptions): Promise<boolean>;
     publicUrl(path: string, options: PublicUrlOptions): Promise<string>;
     temporaryUrl(path: string, options: TemporaryUrlOptions): Promise<string>;
     prepareUpload?(path: string, options: UploadRequestOptions): Promise<UploadRequest>;
     checksum(path: string, options: ChecksumOptions): Promise<string>;
     mimeType(path: string, options: MimeTypeOptions): Promise<string>;
-    lastModified(path: string): Promise<number>;
-    fileSize(path: string): Promise<number>;
+    lastModified(path: string, options: MiscellaneousOptions): Promise<number>;
+    fileSize(path: string, options: MiscellaneousOptions): Promise<number>;
 }
 export declare class DirectoryListing implements AsyncIterable<StatEntry> {
     private readonly listing;
@@ -55,8 +56,12 @@ export declare class DirectoryListing implements AsyncIterable<StatEntry> {
     [Symbol.asyncIterator](): AsyncGenerator<StatEntry, void, unknown>;
 }
 export type FileContents = Iterable<any> | AsyncIterable<any> | NodeJS.ReadableStream | Readable | string;
-export type MiscellaneousOptions = {
+export type TimeoutOptions = {
+    timout?: number;
+};
+export type MiscellaneousOptions = TimeoutOptions & {
     [option: string]: any;
+    abortSignal?: AbortSignal;
 };
 export type MimeTypeOptions = MiscellaneousOptions & {
     disallowFallback?: boolean;
@@ -84,7 +89,7 @@ export type CopyFileOptions = MiscellaneousOptions & VisibilityOptions & {
 export type MoveFileOptions = MiscellaneousOptions & VisibilityOptions & {
     retainVisibility?: boolean;
 };
-export type ListOptions = {
+export type ListOptions = MiscellaneousOptions & {
     deep?: boolean;
 };
 export type TemporaryUrlOptions = MiscellaneousOptions & {
@@ -108,6 +113,7 @@ export type ConfigurationOptions = {
     checksums?: ChecksumOptions;
     mimeTypes?: MimeTypeOptions;
     preparedUploadStrategy?: PreparedUploadStrategy;
+    timeout?: TimeoutOptions;
 };
 export declare function toReadable(contents: FileContents): Readable;
 export declare class FileStorage {
@@ -116,33 +122,29 @@ export declare class FileStorage {
     private readonly options;
     constructor(adapter: StorageAdapter, pathNormalizer?: PathNormalizer, options?: ConfigurationOptions);
     write(path: string, contents: FileContents, options?: WriteOptions): Promise<void>;
-    read(path: string): Promise<Readable>;
-    readToString(path: string): Promise<string>;
-    readToUint8Array(path: string): Promise<Uint8Array>;
-    readToBuffer(path: string): Promise<Buffer>;
-    deleteFile(path: string): Promise<void>;
+    read(path: string, options?: MiscellaneousOptions): Promise<Readable>;
+    readToString(path: string, options?: MiscellaneousOptions): Promise<string>;
+    readToUint8Array(path: string, options?: MiscellaneousOptions): Promise<Uint8Array>;
+    readToBuffer(path: string, options?: MiscellaneousOptions): Promise<Buffer>;
+    deleteFile(path: string, options?: MiscellaneousOptions): Promise<void>;
     createDirectory(path: string, options?: CreateDirectoryOptions): Promise<void>;
-    deleteDirectory(path: string): Promise<void>;
-    stat(path: string): Promise<StatEntry>;
+    deleteDirectory(path: string, options?: MiscellaneousOptions): Promise<void>;
+    stat(path: string, options?: MiscellaneousOptions): Promise<StatEntry>;
     moveFile(from: string, to: string, options?: MoveFileOptions): Promise<void>;
     copyFile(from: string, to: string, options?: CopyFileOptions): Promise<void>;
-    /**
-     * @deprecated use changeVisibility instead
-     */
-    setVisibility(path: string, visibility: string): Promise<void>;
-    changeVisibility(path: string, visibility: string): Promise<void>;
-    visibility(path: string): Promise<string>;
-    fileExists(path: string): Promise<boolean>;
-    list(path: string, { deep }?: ListOptions): DirectoryListing;
-    statFile(path: string): Promise<FileInfo>;
-    directoryExists(path: string): Promise<boolean>;
+    changeVisibility(path: string, visibility: string, options?: MiscellaneousOptions): Promise<void>;
+    visibility(path: string, options?: MiscellaneousOptions): Promise<string>;
+    fileExists(path: string, options?: MiscellaneousOptions): Promise<boolean>;
+    list(path: string, options?: ListOptions): DirectoryListing;
+    statFile(path: string, options?: MiscellaneousOptions): Promise<FileInfo>;
+    directoryExists(path: string, options?: MiscellaneousOptions): Promise<boolean>;
     publicUrl(path: string, options?: PublicUrlOptions): Promise<string>;
     temporaryUrl(path: string, options: TemporaryUrlOptions): Promise<string>;
     prepareUpload(path: string, options: UploadRequestOptions): Promise<UploadRequest>;
     checksum(path: string, options?: ChecksumOptions): Promise<string>;
     mimeType(path: string, options?: MimeTypeOptions): Promise<string>;
-    lastModified(path: string): Promise<number>;
-    fileSize(path: string): Promise<number>;
+    lastModified(path: string, options?: MiscellaneousOptions): Promise<number>;
+    fileSize(path: string, options?: MiscellaneousOptions): Promise<number>;
     private calculateChecksum;
 }
 export type TimestampMs = number;
@@ -151,6 +153,7 @@ export declare function normalizeExpiryToDate(expiresAt: ExpiresAt): Date;
 export declare function normalizeExpiryToMilliseconds(expiresAt: ExpiresAt): number;
 export declare function closeReadable(body: Readable): Promise<void>;
 export declare function readableToString(stream: Readable): Promise<string>;
+export declare function readableToBuffer(stream: Readable): Promise<Buffer>;
 export declare function readableToUint8Array(stream: Readable): Promise<Uint8Array>;
 export type UploadRequestHeaders = Record<string, string | ReadonlyArray<string>>;
 export type UploadRequest = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flystorage/file-storage",
   "type": "module",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "File-storage abstraction: multiple filesystems, one API.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/types/index.d.ts",
@@ -30,6 +30,7 @@
     "url": "git+https://github.com/duna-oss/flystorage.git",
     "directory": "packages/file-storage"
   },
+  "homepage": "https://flystorage.dev/",
   "keywords": [
     "fs",
     "file",