refactor listBuckets (minio#1179)

* refactor listBuckets

* remove unused

* address review comment

* address review comments and feedback

* format

* update doc example

* update note about top level await

* update note about top level await

docs/API.md

@@ -145,6 +145,8 @@ var s3Client = new Minio.Client({
 })
 ```
 
+### _Note_: The below examples rely on top level await .
+
 ## 2. Bucket operations
 
 <a name="makeBucket"></a>
@@ -183,17 +185,15 @@ minioClient.makeBucket('mybucket', 'us-east-1', { ObjectLocking: true }, functio
 
 <a name="listBuckets"></a>
 
-### listBuckets([callback])
+### listBuckets()
 
 Lists all buckets.
 
 **Parameters**
 
-| Param                          | Type       | Description                                                                                                                                                      |
-| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `callback(err, bucketStream) ` | _function_ | Callback function with error as the first argument. `bucketStream` is the stream emitting bucket information. If no callback is passed, a `Promise` is returned. |
+NIL
 
-bucketStream emits Object with the format:-
+Returns Array of Objects with the format:-
 
 | Param                 | Type     | Description                   |
 | --------------------- | -------- | ----------------------------- |
@@ -202,11 +202,15 @@ bucketStream emits Object with the format:-
 
 **Example**
 
+Please refer to: [list-buckets.mjs](..%2Fexamples%2Flist-buckets.mjs)
+
 ```js
-minioClient.listBuckets(function (err, buckets) {
-  if (err) return console.log(err)
-  console.log('buckets :', buckets)
-})
+try {
+  const buckets = await s3Client.listBuckets()
+  console.log('Success', buckets)
+} catch (err) {
+  console.log(err.message)
+}
 ```
 
 <a name="bucketExists"></a>

examples/list-buckets.js → examples/list-buckets.mjs

@@ -14,18 +14,23 @@
  * limitations under the License.
  */
 
+// Using the top-level await as we use .mjs extension
+// run it like: node list-buckets.mjs
+
 // Note: YOUR-ACCESSKEYID and YOUR-SECRETACCESSKEY are dummy values, please
 // replace them with original values.
 
-var Minio = require('minio')
+import * as Minio from 'minio'
 
 var s3Client = new Minio.Client({
   endPoint: 's3.amazonaws.com',
   accessKey: 'YOUR-ACCESSKEYID',
   secretKey: 'YOUR-SECRETACCESSKEY',
 })
 
-s3Client.listBuckets(function (e, buckets) {
-  if (e) return console.log(e)
-  console.log('buckets :', buckets)
-})
+try {
+  const buckets = await s3Client.listBuckets()
+  console.log('Success', buckets)
+} catch (err) {
+  console.log(err.message)
+}

src/internal/client.ts

@@ -34,7 +34,7 @@ import { request } from './request.ts'
 import { drainResponse, readAsString } from './response.ts'
 import type { Region } from './s3-endpoints.ts'
 import { getS3Endpoint } from './s3-endpoints.ts'
-import type { Binary, IRequest, RequestHeaders, Transport } from './type.ts'
+import type { Binary, BucketItemFromList, IRequest, RequestHeaders, Transport } from './type.ts'
 import type { UploadedPart } from './xml-parser.ts'
 import * as xmlParsers from './xml-parser.ts'
 
@@ -864,4 +864,11 @@ export class TypedClient {
     const res = await this.makeRequestAsync({ method, bucketName, objectName, query })
     return xmlParsers.parseListParts(await readAsString(res))
   }
+
+  async listBuckets(): Promise<BucketItemFromList[]> {
+    const method = 'GET'
+    const httpRes = await this.makeRequestAsync({ method }, '', [200], DEFAULT_REGION)
+    const xmlResult = await readAsString(httpRes)
+    return xmlParsers.parseListBucket(xmlResult)
+  }
 }

src/internal/xml-parser.ts

@@ -3,9 +3,9 @@ import type * as http from 'node:http'
 import { XMLParser } from 'fast-xml-parser'
 
 import * as errors from '../errors.ts'
-import type { BucketItemWithMetadata } from '../minio'
 import { parseXml, sanitizeETag, sanitizeObjectKey, toArray } from './helper.ts'
 import { readAsString } from './response.ts'
+import type { BucketItemFromList, BucketItemWithMetadata } from './type.ts'
 
 // parse XML response for bucket region
 export function parseBucketRegion(xml: string): string {
@@ -196,3 +196,23 @@ export function parseListParts(xml: string): {
   }
   return result
 }
+
+export function parseListBucket(xml: string) {
+  let result: BucketItemFromList[] = []
+  const parsedXmlRes = parseXml(xml)
+
+  if (!parsedXmlRes.ListAllMyBucketsResult) {
+    throw new errors.InvalidXMLError('Missing tag: "ListAllMyBucketsResult"')
+  }
+  const { ListAllMyBucketsResult: { Buckets = {} } = {} } = parsedXmlRes
+
+  if (Buckets.Bucket) {
+    result = toArray(Buckets.Bucket).map((bucket = {}) => {
+      const { Name: bucketName, CreationDate } = bucket
+      const creationDate = new Date(CreationDate)
+
+      return { name: bucketName, creationDate: creationDate }
+    })
+  }
+  return result
+}

src/minio.d.ts

@@ -231,9 +231,6 @@ export class Client extends TypedClient {
   makeBucket(bucketName: string, callback: NoResultCallback): void
   makeBucket(bucketName: string, region?: Region, makeOpts?: MakeBucketOpt): Promise<void>
 
-  listBuckets(callback: ResultCallback<BucketItemFromList[]>): void
-  listBuckets(): Promise<BucketItemFromList[]>
-
   bucketExists(bucketName: string, callback: ResultCallback<boolean>): void
   bucketExists(bucketName: string): Promise<boolean>
 

src/minio.js

@@ -209,32 +209,6 @@ export class Client extends TypedClient {
     this.makeRequest({ method, bucketName, headers }, payload, [200], region, false, processWithRetry)
   }
 
-  // List of buckets created.
-  //
-  // __Arguments__
-  // * `callback(err, buckets)` _function_ - callback function with error as the first argument. `buckets` is an array of bucket information
-  //
-  // `buckets` array element:
-  // * `bucket.name` _string_ : bucket name
-  // * `bucket.creationDate` _Date_: date when bucket was created
-  listBuckets(cb) {
-    if (!isFunction(cb)) {
-      throw new TypeError('callback should be of type "function"')
-    }
-    var method = 'GET'
-    this.makeRequest({ method }, '', [200], DEFAULT_REGION, true, (e, response) => {
-      if (e) {
-        return cb(e)
-      }
-      var transformer = transformers.getListBucketTransformer()
-      var buckets
-      pipesetup(response, transformer)
-        .on('data', (result) => (buckets = result))
-        .on('error', (e) => cb(e))
-        .on('end', () => cb(null, buckets))
-    })
-  }
-
   // Returns a stream that emits objects that are partially uploaded.
   //
   // __Arguments__
@@ -2860,7 +2834,6 @@ export class Client extends TypedClient {
 
 // Promisify various public-facing APIs on the Client module.
 Client.prototype.makeBucket = promisify(Client.prototype.makeBucket)
-Client.prototype.listBuckets = promisify(Client.prototype.listBuckets)
 Client.prototype.bucketExists = promisify(Client.prototype.bucketExists)
 Client.prototype.removeBucket = promisify(Client.prototype.removeBucket)
 
@@ -2911,3 +2884,4 @@ Client.prototype.selectObjectContent = promisify(Client.prototype.selectObjectCo
 
 // refactored API use promise internally
 Client.prototype.removeObject = callbackify(Client.prototype.removeObject)
+Client.prototype.listBuckets = callbackify(Client.prototype.listBuckets)

src/transformers.js

@@ -101,11 +101,6 @@ export function getCopyObjectTransformer() {
   return getConcater(xmlParsers.parseCopyObject)
 }
 
-// Parses listBuckets response.
-export function getListBucketTransformer() {
-  return getConcater(xmlParsers.parseListBucket)
-}
-
 // Parses listMultipartUploads response.
 export function getListMultipartTransformer() {
   return getConcater(xmlParsers.parseListMultipart)

src/xml-parsers.js

@@ -93,26 +93,6 @@ export function parseListMultipart(xml) {
 }
 
 // parse XML response to list all the owned buckets
-export function parseListBucket(xml) {
-  var result = []
-  var xmlobj = parseXml(xml)
-
-  if (!xmlobj.ListAllMyBucketsResult) {
-    throw new errors.InvalidXMLError('Missing tag: "ListAllMyBucketsResult"')
-  }
-  xmlobj = xmlobj.ListAllMyBucketsResult
-
-  if (xmlobj.Buckets) {
-    if (xmlobj.Buckets.Bucket) {
-      toArray(xmlobj.Buckets.Bucket).forEach((bucket) => {
-        var name = bucket.Name
-        var creationDate = new Date(bucket.CreationDate)
-        result.push({ name, creationDate })
-      })
-    }
-  }
-  return result
-}
 
 // parse XML response for bucket notification
 export function parseBucketNotification(xml) {