refactor statObject (#1187)

* refactor

* refactor

* up

* up

* up

* up

* format code

* up

* error message

* unify import name

* Update docs/API.md

---------

Co-authored-by: Prakash Senthil Vel <[email protected]>

Author: trim21

README.md

@@ -201,7 +201,7 @@ The full API Reference is available here.
 - [get-partialobject.js](https://github.com/minio/minio-js/blob/master/examples/get-partialobject.js)
 - [remove-object.js](https://github.com/minio/minio-js/blob/master/examples/remove-object.js)
 - [remove-incomplete-upload.js](https://github.com/minio/minio-js/blob/master/examples/remove-incomplete-upload.js)
-- [stat-object.js](https://github.com/minio/minio-js/blob/master/examples/stat-object.js)
+- [stat-object.mjs](https://github.com/minio/minio-js/blob/master/examples/stat-object.mjs)
 - [get-object-retention.js](https://github.com/minio/minio-js/blob/master/examples/get-object-retention.js)
 - [put-object-retention.js](https://github.com/minio/minio-js/blob/master/examples/put-object-retention.js)
 - [put-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/put-object-tagging.js)

README_zh_CN.md

@@ -170,7 +170,7 @@ mc ls play/europetrip/
 * [get-partialobject.js](https://github.com/minio/minio-js/blob/master/examples/get-partialobject.js)
 * [remove-object.js](https://github.com/minio/minio-js/blob/master/examples/remove-object.js)
 * [remove-incomplete-upload.js](https://github.com/minio/minio-js/blob/master/examples/remove-incomplete-upload.js)
-* [stat-object.js](https://github.com/minio/minio-js/blob/master/examples/stat-object.js)
+* [stat-object.mjs](https://github.com/minio/minio-js/blob/master/examples/stat-object.mjs)
 
 #### 完整示例 : Presigned操作
 * [presigned-getobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-getobject.js)

docs/API.md

@@ -1274,23 +1274,15 @@ Gets metadata of an object.
 **Example**
 
 ```js
-minioClient.statObject('mybucket', 'photo.jpg', function (err, stat) {
-  if (err) {
-    return console.log(err)
-  }
-  console.log(stat)
-})
+const stat = await minioClient.statObject('mybucket', 'photo.jpg')
+console.log(stat)
 ```
 
 **Example stat on a version of an object**
 
 ```js
-minioClient.statObject('mybucket', 'photo.jpg', { versionId: 'my-versionId' }, function (err, stat) {
-  if (err) {
-    return console.log(err)
-  }
-  console.log(stat)
-})
+const stat = await minioClient.statObject('mybucket', 'photo.jpg', { versionId: 'my-versionId' })
+console.log(stat)
 ```
 
 <a name="removeObject"></a>

examples/stat-object.js examples/stat-object.mjsexamples/stat-object.js renamed to examples/stat-object.mjs

@@ -17,26 +17,26 @@
 // Note: YOUR-ACCESSKEYID, YOUR-SECRETACCESSKEY, my-bucketname
 // and my-objectname are dummy values, please replace them with original values.
 
-var Minio = require('minio')
+import * as Minio from 'minio'
 
-var s3Client = new Minio.Client({
+const s3Client = new Minio.Client({
   endPoint: 's3.amazonaws.com',
   accessKey: 'YOUR-ACCESSKEYID',
   secretKey: 'YOUR-SECRETACCESSKEY',
 })
 // Get stat information for my-objectname.
-s3Client.statObject('my-bucketname', 'my-objectname', function (e, stat) {
-  if (e) {
-    return console.log(e)
-  }
+try {
+  const stat = await s3Client.statObject('my-bucketname', 'my-objectname')
   console.log(stat)
-})
+} catch (e) {
+  console.log(e)
+}
 
 // Get stat information for a specific version of 'my-objectname'
 //Bucket must be versioning enabled.
-s3Client.statObject('my-bucketname', 'my-objectname', { versionId: 'my-uuid' }, function (e, stat) {
-  if (e) {
-    return console.log(e)
-  }
+try {
+  const stat = await s3Client.statObject('my-bucketname', 'my-objectname', { versionId: 'my-uuid' })
   console.log(stat)
-})
+} catch (e) {
+  console.log(e)
+}

src/internal/client.ts

@@ -12,6 +12,8 @@ import { DEFAULT_REGION } from '../helpers.ts'
 import { signV4 } from '../signing.ts'
 import { Extensions } from './extensions.ts'
 import {
+  extractMetadata,
+  getVersionId,
   isAmazonEndpoint,
   isBoolean,
   isDefined,
@@ -26,6 +28,7 @@ import {
   isValidPort,
   isVirtualHostStyle,
   makeDateLong,
+  sanitizeETag,
   toSha256,
   uriEscape,
   uriResourceEscape,
@@ -34,7 +37,16 @@ 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, BucketItemFromList, IRequest, RequestHeaders, Transport } from './type.ts'
+import type {
+  Binary,
+  BucketItemFromList,
+  BucketItemStat,
+  IRequest,
+  RequestHeaders,
+  ResponseHeader,
+  Transport,
+} from './type.ts'
+import type { StatObjectOpts } from './type.ts'
 import type { UploadedPart } from './xml-parser.ts'
 import * as xmlParsers from './xml-parser.ts'
 
@@ -779,6 +791,34 @@ export class TypedClient {
     delete this.regionMap[bucketName]
   }
 
+  /**
+   * Stat information of the object.
+   */
+  async statObject(bucketName: string, objectName: string, statOpts: StatObjectOpts = {}): Promise<BucketItemStat> {
+    if (!isValidBucketName(bucketName)) {
+      throw new errors.InvalidBucketNameError('Invalid bucket name: ' + bucketName)
+    }
+    if (!isValidObjectName(objectName)) {
+      throw new errors.InvalidObjectNameError(`Invalid object name: ${objectName}`)
+    }
+
+    if (!isObject(statOpts)) {
+      throw new errors.InvalidArgumentError('statOpts should be of type "object"')
+    }
+
+    const query = qs.stringify(statOpts)
+    const method = 'HEAD'
+    const res = await this.makeRequestAsyncOmit({ method, bucketName, objectName, query })
+
+    return {
+      size: parseInt(res.headers['content-length'] as string),
+      metaData: extractMetadata(res.headers as ResponseHeader),
+      lastModified: new Date(res.headers['last-modified'] as string),
+      versionId: getVersionId(res.headers as ResponseHeader),
+      etag: sanitizeETag(res.headers.etag),
+    }
+  }
+
   /**
    * Remove the specified object.
    * @deprecated use new promise style API

src/internal/type.ts

@@ -1,8 +1,6 @@
 import type * as http from 'node:http'
 import type { Readable as ReadableStream } from 'node:stream'
 
-import type { MetadataItem } from '../minio'
-
 export type Binary = string | Buffer
 
 // nodejs IncomingHttpHeaders is Record<string, string | string[]>, but it's actually this:
@@ -66,6 +64,11 @@ export interface IncompleteUploadedBucketItem {
   size: number
 }
 
+export interface MetadataItem {
+  Key: string
+  Value: string
+}
+
 export interface ItemBucketMetadataList {
   Items: MetadataItem[]
 }
@@ -111,3 +114,15 @@ export interface BucketStream<T> extends ReadableStream {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   on(event: string | symbol, listener: (...args: any[]) => void): this
 }
+
+export interface BucketItemStat {
+  size: number
+  etag: string
+  lastModified: Date
+  metaData: ItemBucketMetadata
+  versionId?: string | null
+}
+
+export type StatObjectOpts = {
+  versionId?: string
+}

src/minio.d.ts

@@ -20,11 +20,13 @@ import type {
   BucketItem,
   BucketItemCopy,
   BucketItemFromList,
+  BucketItemStat,
   BucketItemWithMetadata,
   BucketStream,
   IncompleteUploadedBucketItem,
   ItemBucketMetadata,
   ItemBucketMetadataList,
+  MetadataItem,
 } from './internal/type.ts'
 
 export * from './helpers.ts'
@@ -34,12 +36,14 @@ export type {
   BucketItem,
   BucketItemCopy,
   BucketItemFromList,
+  BucketItemStat,
   BucketItemWithMetadata,
   BucketStream,
   ClientOptions,
   IncompleteUploadedBucketItem,
   ItemBucketMetadata,
   ItemBucketMetadataList,
+  MetadataItem,
   NoResultCallback,
   RemoveOptions,
 }
@@ -89,25 +93,13 @@ export type Encryption = EncryptionConfig | EmptyObject
 export type Retention = RetentionOptions | EmptyObject
 export type IsoDate = string
 
-export interface BucketItemStat {
-  size: number
-  etag: string
-  lastModified: Date
-  metaData: ItemBucketMetadata
-}
-
 export interface PostPolicyResult {
   postURL: string
   formData: {
     [key: string]: any
   }
 }
 
-export interface MetadataItem {
-  Key: string
-  Value: string
-}
-
 export interface UploadedObjectInfo {
   etag: string
   versionId: string | null
@@ -375,9 +367,6 @@ export class Client extends TypedClient {
     conditions: CopyConditions,
   ): Promise<BucketItemCopy>
 
-  statObject(bucketName: string, objectName: string, callback: ResultCallback<BucketItemStat>): void
-  statObject(bucketName: string, objectName: string): Promise<BucketItemStat>
-
   removeObjects(bucketName: string, objectsList: string[], callback: NoResultCallback): void
   removeObjects(bucketName: string, objectsList: string[]): Promise<void>
 

src/minio.js

@@ -1048,61 +1048,6 @@ export class Client extends TypedClient {
     return readStream
   }
 
-  // Stat information of the object.
-  //
-  // __Arguments__
-  // * `bucketName` _string_: name of the bucket
-  // * `objectName` _string_: name of the object
-  // * `statOpts`  _object_ : Version of the object in the form `{versionId:'my-uuid'}`. Default is `{}`. (optional).
-  // * `callback(err, stat)` _function_: `err` is not `null` in case of error, `stat` contains the object information:
-  //   * `stat.size` _number_: size of the object
-  //   * `stat.etag` _string_: etag of the object
-  //   * `stat.metaData` _string_: MetaData of the object
-  //   * `stat.lastModified` _Date_: modified time stamp
-  //   * `stat.versionId` _string_: version id of the object if available
-  statObject(bucketName, objectName, statOpts = {}, cb) {
-    if (!isValidBucketName(bucketName)) {
-      throw new errors.InvalidBucketNameError('Invalid bucket name: ' + bucketName)
-    }
-    if (!isValidObjectName(objectName)) {
-      throw new errors.InvalidObjectNameError(`Invalid object name: ${objectName}`)
-    }
-    // backward compatibility
-    if (isFunction(statOpts)) {
-      cb = statOpts
-      statOpts = {}
-    }
-
-    if (!isObject(statOpts)) {
-      throw new errors.InvalidArgumentError('statOpts should be of type "object"')
-    }
-    if (!isFunction(cb)) {
-      throw new TypeError('callback should be of type "function"')
-    }
-
-    var query = querystring.stringify(statOpts)
-    var method = 'HEAD'
-    this.makeRequest({ method, bucketName, objectName, query }, '', [200], '', true, (e, response) => {
-      if (e) {
-        return cb(e)
-      }
-
-      // We drain the socket so that the connection gets closed. Note that this
-      // is not expensive as the socket will not have any data.
-      response.on('data', () => {})
-
-      const result = {
-        size: +response.headers['content-length'],
-        metaData: extractMetadata(response.headers),
-        lastModified: new Date(response.headers['last-modified']),
-        versionId: getVersionId(response.headers),
-        etag: sanitizeETag(response.headers.etag),
-      }
-
-      cb(null, result)
-    })
-  }
-
   // Remove all the objects residing in the objectsList.
   //
   // __Arguments__
@@ -2811,7 +2756,6 @@ Client.prototype.fGetObject = promisify(Client.prototype.fGetObject)
 Client.prototype.putObject = promisify(Client.prototype.putObject)
 Client.prototype.fPutObject = promisify(Client.prototype.fPutObject)
 Client.prototype.copyObject = promisify(Client.prototype.copyObject)
-Client.prototype.statObject = promisify(Client.prototype.statObject)
 Client.prototype.removeObjects = promisify(Client.prototype.removeObjects)
 
 Client.prototype.presignedUrl = promisify(Client.prototype.presignedUrl)
@@ -2851,6 +2795,7 @@ Client.prototype.selectObjectContent = promisify(Client.prototype.selectObjectCo
 
 // refactored API use promise internally
 Client.prototype.removeObject = callbackify(Client.prototype.removeObject)
+Client.prototype.statObject = callbackify(Client.prototype.statObject)
 Client.prototype.removeBucket = callbackify(Client.prototype.removeBucket)
 Client.prototype.listBuckets = callbackify(Client.prototype.listBuckets)
 Client.prototype.removeBucketReplication = callbackify(Client.prototype.removeBucketReplication)