From a4653e98ce935083af02572a6efdf2675ee1c7a6 Mon Sep 17 00:00:00 2001 From: Paul Copplestone Date: Thu, 25 Mar 2021 15:50:17 +0800 Subject: [PATCH 1/6] Adds some more documentation --- src/lib/storage/StorageApi.ts | 78 ++++++++++++++++++++--------------- 1 file changed, 45 insertions(+), 33 deletions(-) diff --git a/src/lib/storage/StorageApi.ts b/src/lib/storage/StorageApi.ts index 749b5f139..7ae04d578 100644 --- a/src/lib/storage/StorageApi.ts +++ b/src/lib/storage/StorageApi.ts @@ -21,7 +21,7 @@ export class StorageApi { } /** - * Gets all buckets details + * Retrieves the details of all Storage buckets within an existing product. */ async getAllBuckets(): Promise<{ data: Bucket[] | null; error: Error | null }> { try { @@ -33,8 +33,9 @@ export class StorageApi { } /** - * Get details of a bucket - * @param id the bucket id to retrieve + * Retrieves the details of an existing Storage bucket. + * + * @param id The unique identifier of the bucket you would like to retrieve. */ async getBucket(id: string): Promise<{ data: Bucket | null; error: Error | null }> { try { @@ -46,8 +47,9 @@ export class StorageApi { } /** - * Create a bucket - * @param name the new bucket name + * Retrieves the details of an existing Storage bucket. + * + * @param name A name of the bucket you are creating. */ async createBucket(name: string): Promise<{ data: Bucket | null; error: Error | null }> { try { @@ -59,8 +61,9 @@ export class StorageApi { } /** - * Empty a bucket - * @param id the bucket id to empty + * Removes all objects inside a single bucket. + * + * @param id The unique identifier of the bucket you would like to empty. */ async emptyBucket( id: string @@ -74,8 +77,10 @@ export class StorageApi { } /** - * Delete a bucket - * @param id the bucket id to be deleted + * Deletes an existing bucket. A bucket can't be deleted with existing objects inside it. + * You must first `empty()` the bucket. + * + * @param id The unique identifier of the bucket you would like to delete. */ async deleteBucket( id: string @@ -89,9 +94,10 @@ export class StorageApi { } /** - * Upload a file - * @param path the relative file path - * @param file the File content + * Uploads a file to an existing bucket. + * + * @param path The relative file path including the bucket ID. Should be of the format `bucket/folder/subfolder`. The bucket already exist before attempting to upload. + * @param file The File object to be stored in the bucket. */ async uploadFile( path: string, @@ -123,9 +129,10 @@ export class StorageApi { } /** - * Update a file - * @param path the relative file path - * @param file the File content + * Replaces an existing file at the specified path with a new one. + * + * @param path The relative file path including the bucket ID. Should be of the format `bucket/folder/subfolder`. The bucket already exist before attempting to upload. + * @param file The file object to be stored in the bucket. */ async updateFile( path: string, @@ -157,10 +164,11 @@ export class StorageApi { } /** - * Rename a file - * @param bucketName - * @param fromPath original relative file path - * @param toPath the new relative file path + * Renames an existing file. + * + * @param bucketName The bucket which contains the file. + * @param fromPath The original file path, including the current file name. For example `folder/image.png`. + * @param toPath The new file path, including the new file name. For example `folder/image-copy.png`. */ async renameFile( bucketName: string, @@ -180,9 +188,10 @@ export class StorageApi { } /** - * Create signed url to download file - * @param path the relative file path to be downloaded - * @param expiresIn seconds until the signed URL expires + * Create signed url to download file. + * + * @param path The file path to be downloaded, including the current file name. For example `folder/image.png`. + * @param expiresIn The number of seconds until the signed URL expires. For example, `60` for a URL which is valid for one minute. */ async createSignedUrl( path: string, @@ -201,8 +210,9 @@ export class StorageApi { } /** - * Download a file - * @param path the relative file path to be downloaded + * Downloads a file. + * + * @param path The file path to be downloaded, including the path and file name. For example `folder/image.png`. */ async downloadFile(path: string): Promise<{ data: Blob | null; error: Error | null }> { try { @@ -218,8 +228,9 @@ export class StorageApi { } /** - * Delete a file - * @param path the relative file path to be deleted + * Deletes a file. + * + * @param path The file path to be deleted, including the path and file name. For example `folder/image.png`. */ async deleteFile( path: string @@ -233,9 +244,10 @@ export class StorageApi { } /** - * Delete multiple files on the same bucket - * @param bucketName - * @param paths the relative file paths to be deleted excluded the bucket name + * Deletes multiple files within the same bucket + * + * @param bucketName The bucket which contains the files. + * @param paths An array of files to be deletes, including the path and file name. For example [`folder/image.png`]. */ async deleteFiles( bucketName: string, @@ -284,10 +296,10 @@ export class StorageApi { // } /** - * Use to fetch folder contents - * @param bucketName - * @param path the relative folder path excluded the bucket name - * @param options + * Lists all the files within a bucket. + * @param bucketName The bucket which contains the files. + * @param path The folder path. + * @param options Search options. */ async search( bucketName: string, From 061fc1a728f3c548940a17e87f1071470b535956 Mon Sep 17 00:00:00 2001 From: Paul Copplestone Date: Thu, 25 Mar 2021 15:50:58 +0800 Subject: [PATCH 2/6] getAllBuckets is now listBuckets. search is now listFiles --- src/lib/storage/StorageApi.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib/storage/StorageApi.ts b/src/lib/storage/StorageApi.ts index 7ae04d578..13a32d4f5 100644 --- a/src/lib/storage/StorageApi.ts +++ b/src/lib/storage/StorageApi.ts @@ -23,7 +23,7 @@ export class StorageApi { /** * Retrieves the details of all Storage buckets within an existing product. */ - async getAllBuckets(): Promise<{ data: Bucket[] | null; error: Error | null }> { + async listBuckets(): Promise<{ data: Bucket[] | null; error: Error | null }> { try { const data = await get(`${this.url}/bucket`, { headers: this.headers }) return { data, error: null } @@ -301,7 +301,7 @@ export class StorageApi { * @param path The folder path. * @param options Search options. */ - async search( + async listFiles( bucketName: string, path?: string, options?: SearchOptions From bbe11c0221d1f59d688c0b41f657f2a5d78e000b Mon Sep 17 00:00:00 2001 From: Paul Copplestone Date: Thu, 25 Mar 2021 15:54:11 +0800 Subject: [PATCH 3/6] changes bucketName to bucketId --- src/lib/storage/StorageApi.ts | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/lib/storage/StorageApi.ts b/src/lib/storage/StorageApi.ts index 13a32d4f5..b9bee6925 100644 --- a/src/lib/storage/StorageApi.ts +++ b/src/lib/storage/StorageApi.ts @@ -166,19 +166,19 @@ export class StorageApi { /** * Renames an existing file. * - * @param bucketName The bucket which contains the file. + * @param bucketId The bucket which contains the file. * @param fromPath The original file path, including the current file name. For example `folder/image.png`. * @param toPath The new file path, including the new file name. For example `folder/image-copy.png`. */ async renameFile( - bucketName: string, + bucketId: string, fromPath: string, toPath: string ): Promise<{ data: { message: string } | null; error: Error | null }> { try { const data = await post( `${this.url}/object/rename`, - { bucketName, sourceKey: fromPath, destinationKey: toPath }, + { bucketId, sourceKey: fromPath, destinationKey: toPath }, { headers: this.headers } ) return { data, error: null } @@ -246,16 +246,16 @@ export class StorageApi { /** * Deletes multiple files within the same bucket * - * @param bucketName The bucket which contains the files. + * @param bucketId The bucket which contains the files. * @param paths An array of files to be deletes, including the path and file name. For example [`folder/image.png`]. */ async deleteFiles( - bucketName: string, + bucketId: string, paths: string[] ): Promise<{ data: FileObject[] | null; error: Error | null }> { try { const data = await remove( - `${this.url}/object/${bucketName}`, + `${this.url}/object/${bucketId}`, { prefixes: paths }, { headers: this.headers } ) @@ -297,18 +297,18 @@ export class StorageApi { /** * Lists all the files within a bucket. - * @param bucketName The bucket which contains the files. + * @param bucketId The bucket which contains the files. * @param path The folder path. * @param options Search options. */ async listFiles( - bucketName: string, + bucketId: string, path?: string, options?: SearchOptions ): Promise<{ data: FileObject[] | null; error: Error | null }> { try { const body = { ...DEFAULT_SEARCH_OPTIONS, ...options, prefix: path || '' } - const data = await post(`${this.url}/search/${bucketName}`, body, { headers: this.headers }) + const data = await post(`${this.url}/search/${bucketId}`, body, { headers: this.headers }) return { data, error: null } } catch (error) { return { data: null, error } From 50d1c87f33382c3389031215300e1d5386dc812e Mon Sep 17 00:00:00 2001 From: Paul Copplestone Date: Thu, 25 Mar 2021 16:04:03 +0800 Subject: [PATCH 4/6] more documents --- src/lib/storage/StorageApi.ts | 2 +- src/lib/storage/types.ts | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/src/lib/storage/StorageApi.ts b/src/lib/storage/StorageApi.ts index b9bee6925..d9406b390 100644 --- a/src/lib/storage/StorageApi.ts +++ b/src/lib/storage/StorageApi.ts @@ -299,7 +299,7 @@ export class StorageApi { * Lists all the files within a bucket. * @param bucketId The bucket which contains the files. * @param path The folder path. - * @param options Search options. + * @param options Search options, including `limit`, `offset`, and `sortBy`. */ async listFiles( bucketId: string, diff --git a/src/lib/storage/types.ts b/src/lib/storage/types.ts index a75adc9ba..533d17020 100644 --- a/src/lib/storage/types.ts +++ b/src/lib/storage/types.ts @@ -22,10 +22,14 @@ export interface SortBy { column?: string order?: string } - export interface SearchOptions { + /** The number of files you want to be returned. */ limit?: number + + /** The starting position. */ offset?: number + + /** The column to sort by. Can be any column inside a FileObject. */ sortBy?: SortBy } From e9acad8bdd92214877b40fc5b351302cdad97a03 Mon Sep 17 00:00:00 2001 From: Paul Copplestone Date: Thu, 25 Mar 2021 16:06:01 +0800 Subject: [PATCH 5/6] Updated function to `move` as it's clearer - it operates the same as mv on linux. --- src/lib/storage/StorageApi.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib/storage/StorageApi.ts b/src/lib/storage/StorageApi.ts index d9406b390..2b63e9a61 100644 --- a/src/lib/storage/StorageApi.ts +++ b/src/lib/storage/StorageApi.ts @@ -164,13 +164,13 @@ export class StorageApi { } /** - * Renames an existing file. + * Moves an existing file, optionally renaming it at the same time. * * @param bucketId The bucket which contains the file. * @param fromPath The original file path, including the current file name. For example `folder/image.png`. * @param toPath The new file path, including the new file name. For example `folder/image-copy.png`. */ - async renameFile( + async moveFile( bucketId: string, fromPath: string, toPath: string From 5cdcb8e987f88af2d41873e8e6d831eb1e478909 Mon Sep 17 00:00:00 2001 From: Inian Parameshwaran Date: Fri, 26 Mar 2021 03:27:12 +0530 Subject: [PATCH 6/6] update storage-api endpoints to the latest version --- src/lib/storage/StorageApi.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib/storage/StorageApi.ts b/src/lib/storage/StorageApi.ts index 2b63e9a61..a21fc81ef 100644 --- a/src/lib/storage/StorageApi.ts +++ b/src/lib/storage/StorageApi.ts @@ -177,7 +177,7 @@ export class StorageApi { ): Promise<{ data: { message: string } | null; error: Error | null }> { try { const data = await post( - `${this.url}/object/rename`, + `${this.url}/object/move`, { bucketId, sourceKey: fromPath, destinationKey: toPath }, { headers: this.headers } ) @@ -308,7 +308,7 @@ export class StorageApi { ): Promise<{ data: FileObject[] | null; error: Error | null }> { try { const body = { ...DEFAULT_SEARCH_OPTIONS, ...options, prefix: path || '' } - const data = await post(`${this.url}/search/${bucketId}`, body, { headers: this.headers }) + const data = await post(`${this.url}/object/list/${bucketId}`, body, { headers: this.headers }) return { data, error: null } } catch (error) { return { data: null, error }