@flystorage/file-storage 1.1.0 → 1.2.0

package/README.md

@@ -20,35 +20,28 @@ to, simply because they cannot be abstracted over in a reasonable manner.
 
 ## Capabilities
 
-### Implemented
-- [x] Write files using string | buffer | readable/stream
-- [x] Read files as stream, string, or Uint8Array
-- [x] Set permissions using abstracted visibility
-- [x] List the contents of a directory/prefix, (shallow and deep).
-- [x] Delete files without failing when they don't exist.
-- [x] Delete directories (and any files it contains)
-- [x] Generate public URLs.
-- [x] Generate temporary (signed) URLs.
-- [x] Expose or calculate checksums for files.
-- [x] Mime-type resolving
-- [x] Last modified fetching
-- [x] File size
-- [x] Moving files
-- [x] Copying files
-
-## Implementations / Adapters
-
-### Implemented
-- [x] [Local Filesystem](https://www.npmjs.com/package/@flystorage/local-fs)
-- [x] [AWS S3 (using the V3 SDK)](https://www.npmjs.com/package/@flystorage/aws-s3)
-- [x] [Azure Blob Storage](https://www.npmjs.com/package/@flystorage/azure-storage-blob)
-- [x] [Test implementation (in-memory)](https://www.npmjs.com/package/@flystorage/in-memory)
-- [x] [Google Cloud Storage](https://www.npmjs.com/package/@flystorage/google-cloud-storage)
-- [x] [Chaos adapter decorator](https://www.npmjs.com/package/@flystorage/chaos)
-
-### Planned
-- [ ] FTP (using `basic-ftp`)
-- [ ] SFTP (?)
+- Write files using string | buffer | readable/stream
+- Read files as stream, string, or Uint8Array
+- List the contents of a directory/prefix, (shallow and deep).
+- Metadata, such as; mime-type, last modified timestamp, and file size.
+- Expose or calculate checksums for files.
+- Delete files without failing when they don't exist.
+- Set permissions using abstracted visibility
+- Delete directories (and any files it contains)
+- Generate public URLs.
+- Generate temporary (signed) URLs.
+- Secure direct uploads from the browser.
+- Moving files
+- Copying files
+
+
+## Adapters
+- [Local Filesystem](https://www.npmjs.com/package/@flystorage/local-fs)
+- [AWS S3 (using the V3 SDK)](https://www.npmjs.com/package/@flystorage/aws-s3)
+- [Azure Blob Storage](https://www.npmjs.com/package/@flystorage/azure-storage-blob)
+- [Test implementation (in-memory)](https://www.npmjs.com/package/@flystorage/in-memory)
+- [Google Cloud Storage](https://www.npmjs.com/package/@flystorage/google-cloud-storage)
+- [Chaos adapter decorator](https://www.npmjs.com/package/@flystorage/chaos)
 
 ## Usage
 Install the main package and any adapters you might need:

package/changelog.md

@@ -1,5 +1,12 @@
 # `@flystorage/file-storage`
 
+## 1.2.0
+
+## Added
+
+- Ability to ignore visibility using configuration
+- Support Bun runtime
+
 ## 1.1.0
 
 ## Added

package/dist/cjs/file-storage.js

@@ -197,6 +197,17 @@ class FileStorage {
     }
     async changeVisibility(path, visibility, options = {}) {
         options = instrumentAbortSignal({ ...this.options.timeout, ...options });
+        if (options.useVisibility === false) {
+            const fallback = options.visibilityFallback;
+            if (fallback.strategy === 'ignore') {
+                return;
+            }
+            else if (fallback.strategy === 'error') {
+                throw errors_js_1.UnableToSetVisibility.because(fallback.errorMessage ?? 'Configured not to use visibility', {
+                    context: { path, visibility },
+                });
+            }
+        }
         try {
             return await this.adapter.changeVisibility(this.pathNormalizer.normalizePath(path), visibility, options);
         }
@@ -205,7 +216,18 @@ class FileStorage {
         }
     }
     async visibility(path, options = {}) {
-        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.visibility, ...options });
+        if (options.useVisibility === false) {
+            const fallback = options.visibilityFallback;
+            if (fallback.strategy === 'ignore') {
+                return fallback.stagedVisibilityResponse ?? 'unknown';
+            }
+            else if (fallback.strategy === 'error') {
+                throw errors_js_1.UnableToGetVisibility.because(fallback.errorMessage ?? 'Configured not to use visibility', {
+                    context: { path },
+                });
+            }
+        }
         try {
             return await this.adapter.visibility(this.pathNormalizer.normalizePath(path), options);
         }
@@ -223,7 +245,7 @@ class FileStorage {
         }
     }
     list(path, options = {}) {
-        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.list, ...options });
         const adapterOptions = {
             ...options,
             deep: options.deep ?? false,

package/dist/esm/file-storage.js

@@ -184,6 +184,17 @@ export class FileStorage {
     }
     async changeVisibility(path, visibility, options = {}) {
         options = instrumentAbortSignal({ ...this.options.timeout, ...options });
+        if (options.useVisibility === false) {
+            const fallback = options.visibilityFallback;
+            if (fallback.strategy === 'ignore') {
+                return;
+            }
+            else if (fallback.strategy === 'error') {
+                throw UnableToSetVisibility.because(fallback.errorMessage ?? 'Configured not to use visibility', {
+                    context: { path, visibility },
+                });
+            }
+        }
         try {
             return await this.adapter.changeVisibility(this.pathNormalizer.normalizePath(path), visibility, options);
         }
@@ -192,7 +203,18 @@ export class FileStorage {
         }
     }
     async visibility(path, options = {}) {
-        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.visibility, ...options });
+        if (options.useVisibility === false) {
+            const fallback = options.visibilityFallback;
+            if (fallback.strategy === 'ignore') {
+                return fallback.stagedVisibilityResponse ?? 'unknown';
+            }
+            else if (fallback.strategy === 'error') {
+                throw UnableToGetVisibility.because(fallback.errorMessage ?? 'Configured not to use visibility', {
+                    context: { path },
+                });
+            }
+        }
         try {
             return await this.adapter.visibility(this.pathNormalizer.normalizePath(path), options);
         }
@@ -210,7 +232,7 @@ export class FileStorage {
         }
     }
     list(path, options = {}) {
-        options = instrumentAbortSignal({ ...this.options.timeout, ...options });
+        options = instrumentAbortSignal({ ...this.options.timeout, ...this.options.list, ...options });
         const adapterOptions = {
             ...options,
             deep: options.deep ?? false,

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

@@ -67,10 +67,23 @@ export type MimeTypeOptions = MiscellaneousOptions & {
     disallowFallback?: boolean;
     fallbackMethod?: 'contents' | 'path';
 };
-export type VisibilityOptions = {
+export type VisibilityFallback = {
+    strategy: 'ignore';
+    stagedVisibilityResponse?: string;
+} | {
+    strategy: 'error';
+    errorMessage?: string;
+};
+export type VisibilityOptions = MiscellaneousOptions & {
     visibility?: string;
     directoryVisibility?: string;
-};
+    retainVisibility?: boolean;
+} & ({
+    useVisibility: true;
+} | {
+    useVisibility: false;
+    visibilityFallback: VisibilityFallback;
+} | {});
 export type WriteOptions = VisibilityOptions & MiscellaneousOptions & {
     mimeType?: string;
     size?: number;
@@ -114,6 +127,7 @@ export type ConfigurationOptions = {
     mimeTypes?: MimeTypeOptions;
     preparedUploadStrategy?: PreparedUploadStrategy;
     timeout?: TimeoutOptions;
+    list?: ListOptions;
 };
 export declare function toReadable(contents: FileContents): Readable;
 export declare class FileStorage {
@@ -132,8 +146,8 @@ export declare class FileStorage {
     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>;
-    changeVisibility(path: string, visibility: string, options?: MiscellaneousOptions): Promise<void>;
-    visibility(path: string, options?: MiscellaneousOptions): Promise<string>;
+    changeVisibility(path: string, visibility: string, options?: VisibilityOptions): Promise<void>;
+    visibility(path: string, options?: VisibilityOptions): Promise<string>;
     fileExists(path: string, options?: MiscellaneousOptions): Promise<boolean>;
     list(path: string, options?: ListOptions): DirectoryListing;
     statFile(path: string, options?: MiscellaneousOptions): Promise<FileInfo>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flystorage/file-storage",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "File-storage abstraction: multiple filesystems, one API.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/types/index.d.ts",