feat: add comments to explain the exposed API. (#1)

node-real · Jan 9, 2024 · 014a676 · 014a676
1 parent c0fa58a
commit 014a676
Show file tree

Hide file tree

Showing 13 changed files with 78 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -85,7 +85,7 @@ export default function App({ Component, pageProps }: AppProps) {
 
 ## Contributing
 
-Please follow our [UploadKit Contribution Guide](./CONTRIBUTING.md).
+Please follow our [Greenfield UploadKit Contribution Guide](./CONTRIBUTING.md).
 
 ## License
 

diff --git a/packages/uploadkit/dev/App.tsx b/packages/uploadkit/dev/App.tsx
@@ -18,6 +18,7 @@ import { client } from './client';
 import ProgressBarExample from './components/ProgressExample';
 import { Icons } from './components/Icons';
 import { Link } from '@/base/components/Link';
+import { ReedSolomon } from '@bnb-chain/reed-solomon';
 
 const config = createConfig(
   getDefaultConfig({
@@ -40,6 +41,12 @@ const options: WalletKitOptions = {
 const uploadOptions: UploadKitOptions = {
   client: client,
   bucketName: 'test-upload-kit',
+  seedString:
+    '0xa25fa0de5d5e82b84826a0bce8c84a1bf1b0c8786c586ec696dc52300a9ffe007bb7e10d9901a32b67ed06fdef1d296f6d6fa00fdd33deaeadbd2363fe87708d1c',
+  checksumFn: async (data: Uint8Array) => {
+    const rs = new ReedSolomon();
+    return rs.encode(data);
+  },
   sp: {
     operatorAddress: '0x89A1CC91B642DECbC4789474694C606E0E0c420b',
     endpoint: 'https://gnfd-testnet-sp1.bnbchain.org',

diff --git a/packages/uploadkit/src/components/GlobalTasks/index.tsx b/packages/uploadkit/src/components/GlobalTasks/index.tsx
@@ -16,7 +16,7 @@ export const GlobalTasks = () => {
   const { state, dispatch } = useUpload();
   const { address } = useAccount();
   const {
-    options: { client },
+    options: { client, checksumFn },
   } = useUploadKitContext();
   const { uploadQueue, tmpAccount, selectedSp, seedString } = state;
   const rs = useSingleton(ReedSolomon);
@@ -57,7 +57,8 @@ export const GlobalTasks = () => {
       },
     });
     const fileBytes = await hashTask.waitObject.file.arrayBuffer();
-    const checkSumRes = rs.encode(new Uint8Array(fileBytes));
+    const calChecksumFn = typeof checksumFn === 'function' ? checksumFn : rs.encode;
+    const checkSumRes = await calChecksumFn(new Uint8Array(fileBytes));
     if (!checkSumRes) {
       return dispatch({
         type: 'SET_UPLOAD_TASK_ERROR_MSG',

diff --git a/packages/uploadkit/src/components/UploadKitButton/index.tsx b/packages/uploadkit/src/components/UploadKitButton/index.tsx
@@ -1,14 +1,18 @@
 import { ButtonProps, Button } from '@/base/components/Button';
 import { useIsMounted } from '@/base/hooks/useIsMounted';
-import { useModal, cx } from '@/index';
+import { cx } from '@/index';
 import React, { useCallback } from 'react';
 import { clsUploadKitButton } from './styles.css';
 import { useRouter } from '../RouteProvider/context';
 import { routes } from '../RouteProvider';
 import { UploadQueueStatus, useUploadQueueStatus } from '@/hooks/useUploadQueueStatus';
+import { useModal } from '../ModalProvider/context';
 
 export type UploadKitButtonProps = ButtonProps;
 
+/**
+ * UploadKitButton is the button that trigger the UploadKit modal.
+ */
 export const UploadKitButton = React.forwardRef((props: UploadKitButtonProps, ref: any) => {
   const { className, onClick, children, ...restProps } = props;
   const { onOpen } = useModal();

diff --git a/packages/uploadkit/src/components/UploadKitProvider/context.ts b/packages/uploadkit/src/components/UploadKitProvider/context.ts
@@ -3,10 +3,30 @@ import { Client } from '@bnb-chain/greenfield-js-sdk';
 import { Sp } from '@/components/UploadProvider/types';
 import { VisibilityType } from '@bnb-chain/greenfield-cosmos-types/greenfield/storage/common';
 
+/**
+ * UploadKitOptions is the options of the Greenfield UploadKit.
+ *
+ * @property {Client} client - THe Greenfield js sdk client, Reference: https://docs.bnbchain.org/greenfield-js-sdk/client/greenfield-client
+ *
+ * @property {string} seedString -seedString is used to authenticate yourself to the provider. If not specified, the provider will generate one.
+ * @property {(data: Uint8Array) => Promise<string[]>} [checksumFn] - The function to calculate the checksum of the object. If not specified, the provider will use the default checksum function.
+ *
+ * @property {string} [bucketName] - The name of the bucket. If not specified, the default bucket will be used.
+ * @property {Sp} [sp] - The storage service provider. If not specified, a random one will be selected.
+ * @property {keyof typeof VisibilityType} [visibility='VISIBILITY_TYPE_PUBLIC_READ'] - The visibility of the object. If not specified, 'VISIBILITY_TYPE_PUBLIC_READ' will be used.
+ *
+ * @property {number} [maxObjectSize=56 * 1024 * 1024] - If not specified, the default is set to 56MB, resulting in an encoding time of under 6 seconds. Larger files may experience extended encoding times, and it is recommended to utilize a web worker for encoding large files. Reference: https://github.com/bnb-chain/greenfield-js-sdk/blob/main/packages/reed-solomon/examples/web-worker.html
+ * @property {number} [maxObjectCount=100] - The maximum count of objects. If not specified, 100 will be used.
+ *
+ * @property {boolean} [taskManagementButton=true] - Specifies whether to show the task management button.
+ *
+ * @property {(errorMsg: string) => void} [onError] - The callback function when an error occurs.
+ */
 export interface UploadKitOptions {
   client: Client;
+
   seedString?: string;
-  checksumFn?: (file: File) => Promise<string[]>;
+  checksumFn?: (data: Uint8Array) => Promise<string[]>;
 
   bucketName?: string;
   sp?: Sp;
@@ -17,7 +37,6 @@ export interface UploadKitOptions {
 
   taskManagementButton?: boolean;
 
-  closeModalAfterConnected?: boolean;
   closeModalOnEsc?: boolean;
   closeModalOnOverlayClick?: boolean;
 

diff --git a/packages/uploadkit/src/components/UploadKitProvider/index.tsx b/packages/uploadkit/src/components/UploadKitProvider/index.tsx
@@ -21,6 +21,9 @@ export interface UploadKitProviderProps {
   customTheme?: CustomTheme;
 }
 
+/**
+ * UploadKitProvider is the root component of the UploadKit library.
+ */
 export const UploadKitProvider = (props: UploadKitProviderProps) => {
   const { children, theme = 'base', mode = 'light', options, customTheme } = props;
 

diff --git a/packages/uploadkit/src/defaultConfig/getDefaultProviderOptions.ts b/packages/uploadkit/src/defaultConfig/getDefaultProviderOptions.ts
@@ -15,7 +15,6 @@ export function getDefaultProviderOptions(options: UploadKitOptions) {
 
     taskManagementButton: true,
 
-    closeModalAfterConnected: true,
     closeModalOnEsc: true,
     closeModalOnOverlayClick: true,
 

diff --git a/packages/uploadkit/src/hooks/useTaskManagementButton.ts b/packages/uploadkit/src/hooks/useTaskManagementButton.ts
@@ -1,5 +1,8 @@
 import { useUpload } from '@/components/UploadProvider';
 
+/**
+ * useTaskManagementButton for display/hide the task management button.
+ */
 export const useTaskManagementButton = () => {
   const {
     state: { taskManagement },

diff --git a/packages/uploadkit/src/hooks/useTotalFee.ts b/packages/uploadkit/src/hooks/useTotalFee.ts
@@ -14,6 +14,9 @@ import BigNumber from 'bignumber.js';
 import { WaitObject } from '@/components/UploadProvider/types';
 import { getStoreNetflowRate } from '@/utils/fee';
 
+/**
+ * useTotalFee returns the total fee of the upload queue.
+ */
 export function useTotalFee() {
   const {
     state: { waitQueue },

diff --git a/packages/uploadkit/src/hooks/useUploadModal.ts b/packages/uploadkit/src/hooks/useUploadModal.ts
@@ -2,6 +2,9 @@ import { useModal } from '@/components/ModalProvider/context';
 import { routes } from '@/components/RouteProvider';
 import { useRouter } from '@/components/RouteProvider/context';
 
+/**
+ * useUploadModal for open/close upload modal.
+ */
 export const useUploadModal = () => {
   const router = useRouter();
   const { onOpen, onClose } = useModal();

diff --git a/packages/uploadkit/src/hooks/useUploadQueue.ts b/packages/uploadkit/src/hooks/useUploadQueue.ts
@@ -1,5 +1,8 @@
 import { useUpload } from '@/components/UploadProvider';
 
+/**
+ * useUploadQueue for get the upload queue data.
+ */
 export const useUploadQueue = () => {
   const {
     state: { uploadQueue },

diff --git a/packages/uploadkit/src/index.ts b/packages/uploadkit/src/index.ts
@@ -2,8 +2,6 @@
 export * from './components/UploadKitButton';
 export * from './components/UploadKitProvider/context';
 export * from './components/UploadKitProvider';
-export { useUpload } from './components/UploadProvider/index';
-export { useModal } from './components/ModalProvider/context';
 
 export * from './hooks/useUploadQueue';
 export * from './hooks/useUploadModal';

diff --git a/website/src/pages/index.mdx b/website/src/pages/index.mdx
@@ -338,19 +338,43 @@ export interface UploadKitProviderProps {
 ### 2. UploadKitOptions
 
 ```tsx live=false
+/**
+ * UploadKitOptions is the options of the Greenfield UploadKit.
+ *
+ * @property {Client} client - THe Greenfield js sdk client, Reference: https://docs.bnbchain.org/greenfield-js-sdk/client/greenfield-client
+ *
+ * @property {string} seedString -seedString is used to authenticate yourself to the provider. If not specified, the provider will generate one.
+ * @property {(data: Uint8Array) => Promise<string[]>} [checksumFn] - The function to calculate the checksum of the object. If not specified, the provider will use the default checksum function.
+ *
+ * @property {string} [bucketName] - The name of the bucket. If not specified, the default bucket will be used.
+ * @property {Sp} [sp] - The storage service provider. If not specified, a random one will be selected.
+ * @property {keyof typeof VisibilityType} [visibility='VISIBILITY_TYPE_PUBLIC_READ'] - The visibility of the object. If not specified, 'VISIBILITY_TYPE_PUBLIC_READ' will be used.
+ *
+ * @property {number} [maxObjectSize=56 * 1024 * 1024] - If not specified, the default is set to 56MB, resulting in an encoding time of under 6 seconds. Larger files may experience extended encoding times, and it is recommended to utilize a web worker for encoding large files. Reference: https://github.com/bnb-chain/greenfield-js-sdk/blob/main/packages/reed-solomon/examples/web-worker.html
+ * @property {number} [maxObjectCount=100] - The maximum count of objects. If not specified, 100 will be used.
+ *
+ * @property {boolean} [taskManagementButton=true] - Specifies whether to show the task management button.
+ *
+ * @property {(errorMsg: string) => void} [onError] - The callback function when an error occurs.
+ */
 export interface UploadKitOptions {
   client: Client;
+
   seedString?: string;
-  checksumFn?: (file: File) => Promise<string[]>;
+  checksumFn?: (data: Uint8Array) => Promise<string[]>;
+
   bucketName?: string;
   sp?: Sp;
   visibility?: keyof typeof VisibilityType;
+
   maxObjectSize?: number;
   maxObjectCount?: number;
+
   taskManagementButton?: boolean;
-  closeModalAfterConnected?: boolean;
+
   closeModalOnEsc?: boolean;
   closeModalOnOverlayClick?: boolean;
+
   onError?: (errorMsg: string) => void;
 }
 ```