feat(storage): add useBytes (#31)

* feat(storage): add `useBytes`
* fix(storage): use `require` in `useBytes`

CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.5.0-next.2](https://github.com/andipaetzold/react-firehooks/compare/v1.5.0-next.1...v1.5.0-next.2) (2021-11-19)
+
+
+### Bug Fixes
+
+* **storage:** use `require` in `useBytes` ([9822fa0](https://github.com/andipaetzold/react-firehooks/commit/9822fa03a4c2f1cf0c7809c049073157a2a20bbc))
+
+# [1.5.0-next.1](https://github.com/andipaetzold/react-firehooks/compare/v1.4.2...v1.5.0-next.1) (2021-11-19)
+
+
+### Features
+
+* **storage:** add `useBytes` ([205869c](https://github.com/andipaetzold/react-firehooks/commit/205869c5b372e69112280400e3a652e4502a7a41))
+
 ## [1.4.2](https://github.com/andipaetzold/react-firehooks/compare/v1.4.1...v1.4.2) (2021-10-22)
 
 

README.md

@@ -57,6 +57,7 @@ This library consists of 4 modules with many hooks:
 -   [`messaging`](#Messaging)
     -   [`useMessagingToken`](#useMessagingToken)
 -   [`storage`](#Storage)
+    -   [`useBytes`](#useBytes)
     -   [`useDownloadURL`](#useDownloadURL)
 
 All hooks can be imported from `react-firehooks` directly or via `react-firehooks/<module>` to improve tree-shaking and bundle size.
@@ -356,6 +357,25 @@ Returns:
 import { ... } from 'react-firehooks/storage';
 ```
 
+#### useBytes
+
+Returns the data of a Google Cloud Storage object
+
+```javascript
+const [data, loading, error] = useBytes(storageReference);
+```
+
+Params:
+
+-   `reference`: Reference to a Google Cloud Storage object
+-   `maxDownloadSizeBytes`: If set, the maximum allowed size in bytes to retrieve.
+
+Returns:
+
+-   `value`: Object data; `undefined` if data of the object is currently being downloaded, or an error occurred
+-   `loading`: `true` while downloading the data of the object; `false` if the data was downloaded successfully or an error occurred
+-   `error`: `undefined` if no error occurred
+
 #### useDownloadURL
 
 Returns the download URL of a Google Cloud Storage object

package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-firehooks",
-    "version": "1.4.2",
+    "version": "1.5.0-next.2",
     "description": "Lightweight dependency-free collection of React hooks for Firebase",
     "main": "./lib/cjs/index.js",
     "module": "./lib/esm/index.js",

src/storage/index.ts

@@ -1 +1,2 @@
+export * from "./useBytes";
 export * from "./useDownloadURL";

src/storage/useBytes.ts

@@ -0,0 +1,36 @@
+import type { StorageError, StorageReference } from "firebase/storage";
+import { useCallback } from "react";
+import { ValueHookResult } from "../common";
+import { useOnce } from "../internal/useOnce";
+import { isStorageRefEqual } from "./internal";
+
+export type UseBytesResult = ValueHookResult<ArrayBuffer, StorageError>;
+
+/**
+ * Returns the data of a Google Cloud Storage object
+ *
+ * Requires firebase v9.5.0 or greater
+ *
+ * @param {StorageReference | undefined | null} reference Reference to a Google Cloud Storage object
+ * @param {?number} maxDownloadSizeBytes If set, the maximum allowed size in bytes to retrieve
+ * @returns {UseBytesResult} Data, loading state, and error
+ * * value: Object data; `undefined` if data of the object is currently being downloaded, or an error occurred
+ * * loading: `true` while downloading the data of the object; `false` if the data was downloaded successfully or an error occurred
+ * * error: `undefined` if no error occurred
+ */
+export function useBytes(reference: StorageReference | undefined | null, maxDownloadSizeBytes?: number): UseBytesResult {
+    const fetchBytes = useCallback(
+        async (ref: StorageReference) => {
+            // TODO: change to regular import in react-firehooks v2
+            const firebaseStorage = await require("firebase/storage");
+            if ("getBytes" in firebaseStorage) {
+                return await firebaseStorage.getBytes(ref, maxDownloadSizeBytes);
+            } else {
+                throw new Error("`useBytes` requires firebase v9.5.0 or greater");
+            }
+        },
+        [maxDownloadSizeBytes]
+    );
+
+    return useOnce(reference ?? undefined, fetchBytes, isStorageRefEqual);
+}