s3mini 0.7.1 → 0.8.1

package/src/S3.ts

@@ -1,8 +1,22 @@
 'use strict';
 
 import * as C from './consts.js';
+import {
+  hexFromBuffer,
+  sha256,
+  hmac,
+  uriResourceEscape,
+  getByteSize,
+  sanitizeETag,
+  uriEscape,
+  parseXml,
+  escapeXml,
+  base64FromBuffer,
+  extractErrCode,
+  S3NetworkError,
+  S3ServiceError,
+} from './utils.js';
 import type * as IT from './types.js';
-import * as U from './utils.js';
 
 /**
  * S3 class for interacting with S3-compatible object storage services.
@@ -43,8 +57,8 @@ class S3mini {
    * @param {typeof fetch} [config.fetch=globalThis.fetch] - Custom fetch implementation to use for HTTP requests.
    * @throws {TypeError} Will throw an error if required parameters are missing or of incorrect type.
    */
-  readonly accessKeyId: string;
-  readonly secretAccessKey: string;
+  readonly #accessKeyId: string;
+  readonly #secretAccessKey: string;
   readonly endpoint: URL;
   readonly region: string;
   readonly bucketName: string;
@@ -66,8 +80,8 @@ class S3mini {
     fetch = globalThis.fetch,
   }: IT.S3Config) {
     this._validateConstructorParams(accessKeyId, secretAccessKey, endpoint);
-    this.accessKeyId = accessKeyId;
-    this.secretAccessKey = secretAccessKey;
+    this.#accessKeyId = accessKeyId;
+    this.#secretAccessKey = secretAccessKey;
     this.endpoint = new URL(this._ensureValidUrl(endpoint));
     this.region = region;
     this.bucketName = this._extractBucketName();
@@ -120,7 +134,7 @@ class S3mini {
           region: this.region,
           endpoint: this.endpoint.toString(),
           // Only include the first few characters of the access key, if it exists
-          accessKeyId: this.accessKeyId ? `${this.accessKeyId.substring(0, 4)}...` : undefined,
+          accessKeyId: this.#accessKeyId ? `${this.#accessKeyId.substring(0, 4)}...` : undefined,
         }),
       };
 
@@ -292,14 +306,14 @@ class S3mini {
       }
     }
     const canonicalRequest = `${method}\n${url.pathname}\n${this._buildCanonicalQueryString(query)}\n${canonicalHeaders}\n\n${signedHeaders}\n${C.UNSIGNED_PAYLOAD}`;
-    const stringToSign = `${C.AWS_ALGORITHM}\n${fullDatetime}\n${credentialScope}\n${U.hexFromBuffer(await U.sha256(canonicalRequest))}`;
+    const stringToSign = `${C.AWS_ALGORITHM}\n${fullDatetime}\n${credentialScope}\n${hexFromBuffer(await sha256(canonicalRequest))}`;
     if (shortDatetime !== this.signingKeyDate || !this.signingKey) {
       this.signingKeyDate = shortDatetime;
       this.signingKey = await this._getSignatureKey(shortDatetime);
     }
-    const signature = U.hexFromBuffer(await U.hmac(this.signingKey, stringToSign));
+    const signature = hexFromBuffer(await hmac(this.signingKey, stringToSign));
     headers[C.HEADER_AUTHORIZATION] =
-      `${C.AWS_ALGORITHM} Credential=${this.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+      `${C.AWS_ALGORITHM} Credential=${this.#accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
     return { url: url.toString(), headers };
   }
 
@@ -335,7 +349,7 @@ class S3mini {
       ...conditionalHeaders,
     };
 
-    const encodedKey = key ? U.uriResourceEscape(key) : '';
+    const encodedKey = key ? uriResourceEscape(key) : '';
     const { url, headers: signedHeaders } = await this._sign(method, encodedKey, filteredOpts, baseHeaders);
     if (Object.keys(query).length > 0) {
       withQuery = true; // append query string to signed URL
@@ -360,7 +374,7 @@ class S3mini {
    * const cleanEtag = s3.sanitizeETag('"abc123"'); // Returns: 'abc123'
    */
   public sanitizeETag(etag: string): string {
-    return U.sanitizeETag(etag);
+    return sanitizeETag(etag);
   }
 
   /**
@@ -376,7 +390,7 @@ class S3mini {
     `;
     const headers = {
       [C.HEADER_CONTENT_TYPE]: C.XML_CONTENT_TYPE,
-      [C.HEADER_CONTENT_LENGTH]: U.getByteSize(xmlBody),
+      [C.HEADER_CONTENT_LENGTH]: getByteSize(xmlBody),
     };
     const res = await this._signedRequest('PUT', '', {
       body: xmlBody,
@@ -457,7 +471,7 @@ class S3mini {
     this._checkPrefix(prefix);
     this._checkOpts(opts);
 
-    const keyPath = delimiter === '/' ? delimiter : U.uriEscape(delimiter);
+    const keyPath = delimiter === '/' ? delimiter : uriEscape(delimiter);
     const unlimited = !(maxKeys && maxKeys > 0);
     let remaining = unlimited ? Infinity : maxKeys;
     let token: string | undefined;
@@ -482,6 +496,47 @@ class S3mini {
     return all;
   }
 
+  /**
+   * Lists objects in the bucket with optional filtering and pagination using a continuation token.
+   * This method retrieves objects matching the criteria (paginated like listObjectsV2).
+   * @param {string} [delimiter='/'] - The delimiter to use for grouping objects.
+   * @param {string} [prefix=''] - The prefix to filter objects by.
+   * @param {number} [maxKeys] - The maximum number of keys to return. Uses a default value of 100.
+   * @param {string} [nextContinuationToken] - The nextContinuationToken to continue previous results. If not provided, starts from the beginning.
+   * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+   * @returns {Promise<{objects: IT.ListObject[] | null; nextContinuationToken?: string } | undefined | null>} A promise that resolves to an array of objects or null if the bucket is empty, along with nextContinuationToken if there are more reccords.
+   * @example
+   * // List all objects
+   * const { objects, nextContinuationToken } = await s3.listObjectsPaged();
+   *
+   * // List 200 objects with prefix
+   * const photos = await s3.listObjectsPaged('/', 'photos/', 200, "token...");
+   */
+  public async listObjectsPaged(
+    delimiter: string = '/',
+    prefix: string = '',
+    maxKeys: number = 100,
+    nextContinuationToken?: string,
+    opts: Record<string, unknown> = {},
+  ): Promise<{ objects: IT.ListObject[] | null; nextContinuationToken?: string } | undefined | null> {
+    this._checkDelimiter(delimiter);
+    this._checkPrefix(prefix);
+    this._checkOpts(opts);
+
+    const keyPath = delimiter === '/' ? delimiter : uriEscape(delimiter);
+    let token: string | undefined = nextContinuationToken;
+    const all: IT.ListObject[] = [];
+
+    const batchResult = await this._fetchObjectBatch(keyPath, prefix, maxKeys, token, opts);
+    if (batchResult === null) {
+      return null; // 404 - bucket not found
+    }
+
+    all.push(...batchResult.objects);
+    token = batchResult.continuationToken;
+    return { objects: all, nextContinuationToken: token };
+  }
+
   private async _fetchObjectBatch(
     keyPath: string,
     prefix: string,
@@ -546,7 +601,7 @@ class S3mini {
     objects: IT.ListObject[];
     continuationToken?: string;
   } {
-    const raw = U.parseXml(xmlText) as Record<string, unknown>;
+    const raw = parseXml(xmlText) as Record<string, unknown>;
 
     if (typeof raw !== 'object' || !raw || 'error' in raw) {
       this._log('error', `${C.ERROR_PREFIX}Unexpected listObjects response shape: ${JSON.stringify(raw)}`);
@@ -562,12 +617,37 @@ class S3mini {
 
   private _extractObjectsFromResponse(response: Record<string, unknown>): IT.ListObject[] {
     const contents = response.Contents || response.contents; // S3 v2 vs v1
+    const commonPrefixes = response.CommonPrefixes || response.commonPrefixes;
 
-    if (!contents) {
-      return [];
+    const objects: IT.ListObject[] = [];
+
+    // Extract regular objects from Contents
+    if (contents) {
+      if (Array.isArray(contents)) {
+        objects.push(...(contents as IT.ListObject[]));
+      } else {
+        objects.push(contents as IT.ListObject);
+      }
+    }
+
+    // Extract directory prefixes from CommonPrefixes
+    if (commonPrefixes) {
+      const prefixList = Array.isArray(commonPrefixes) ? commonPrefixes : [commonPrefixes];
+      for (const item of prefixList) {
+        const prefix = (item as Record<string, unknown>).Prefix || (item as Record<string, unknown>).prefix;
+        if (typeof prefix === 'string') {
+          objects.push({
+            Key: prefix,
+            Size: 0,
+            LastModified: new Date(0),
+            ETag: '',
+            StorageClass: '',
+          } as IT.ListObject);
+        }
+      }
     }
 
-    return Array.isArray(contents) ? (contents as IT.ListObject[]) : [contents as IT.ListObject];
+    return objects;
   }
 
   private _extractContinuationToken(response: Record<string, unknown>): string | undefined {
@@ -604,7 +684,7 @@ class S3mini {
     this._checkOpts(opts);
 
     const query = { uploads: '', ...opts };
-    const keyPath = delimiter === '/' ? delimiter : U.uriEscape(delimiter);
+    const keyPath = delimiter === '/' ? delimiter : uriEscape(delimiter);
 
     const res = await this._signedRequest(method, keyPath, {
       query,
@@ -618,7 +698,7 @@ class S3mini {
     //     etag: res.headers.get(C.HEADER_ETAG) ?? '',
     //   };
     // }
-    const raw = U.parseXml(await res.text()) as unknown;
+    const raw = parseXml(await res.text()) as unknown;
     if (typeof raw !== 'object' || raw === null) {
       throw new Error(`${C.ERROR_PREFIX}Unexpected listMultipartUploads response shape`);
     }
@@ -647,10 +727,11 @@ class S3mini {
       tolerated: [200, 404, 412, 304],
       headers: ssecHeaders ? { ...ssecHeaders } : undefined,
     });
-    if ([404, 412, 304].includes(res.status)) {
-      return null;
+    const s = res.status;
+    if (s === 200) {
+      return res.text();
     }
-    return res.text();
+    return null;
   }
 
   /**
@@ -671,10 +752,10 @@ class S3mini {
       tolerated: [200, 404, 412, 304],
       headers: ssecHeaders ? { ...ssecHeaders } : undefined,
     });
-    if ([404, 412, 304].includes(res.status)) {
-      return null;
+    if (res.status === 200) {
+      return res;
     }
-    return res;
+    return null;
   }
 
   /**
@@ -695,10 +776,10 @@ class S3mini {
       tolerated: [200, 404, 412, 304],
       headers: ssecHeaders ? { ...ssecHeaders } : undefined,
     });
-    if ([404, 412, 304].includes(res.status)) {
-      return null;
+    if (res.status === 200) {
+      return res.arrayBuffer();
     }
-    return res.arrayBuffer();
+    return null;
   }
 
   /**
@@ -719,10 +800,10 @@ class S3mini {
       tolerated: [200, 404, 412, 304],
       headers: ssecHeaders ? { ...ssecHeaders } : undefined,
     });
-    if ([404, 412, 304].includes(res.status)) {
-      return null;
+    if (res.status === 200) {
+      return res.json() as Promise<T>;
     }
-    return res.json() as Promise<T>;
+    return null;
   }
 
   /**
@@ -744,8 +825,8 @@ class S3mini {
         tolerated: [200, 404, 412, 304],
         headers: ssecHeaders ? { ...ssecHeaders } : undefined,
       });
-
-      if ([404, 412, 304].includes(res.status)) {
+      const s = res.status;
+      if (s === 404 || s === 412 || s === 304) {
         return { etag: null, data: null };
       }
 
@@ -753,7 +834,7 @@ class S3mini {
       if (!etag) {
         throw new Error(`${C.ERROR_PREFIX}ETag not found in response headers`);
       }
-      return { etag: U.sanitizeETag(etag), data: await res.arrayBuffer() };
+      return { etag: sanitizeETag(etag), data: await res.arrayBuffer() };
     } catch (err) {
       this._log('error', `Error getting object ${key} with ETag: ${String(err)}`);
       throw err;
@@ -775,12 +856,16 @@ class S3mini {
     key: string,
     wholeFile = true,
     rangeFrom = 0,
-    rangeTo = this.requestSizeInBytes,
+    rangeTo?: number,
     opts: Record<string, unknown> = {},
     ssecHeaders?: IT.SSECHeaders,
   ): Promise<Response> {
-    const rangeHdr: Record<string, string | number> = wholeFile ? {} : { range: `bytes=${rangeFrom}-${rangeTo - 1}` };
+    let rangeHdr: Record<string, string | number> = {};
 
+    if (!wholeFile) {
+      rangeHdr =
+        rangeTo === undefined ? { range: `bytes=${rangeFrom}-` } : { range: `bytes=${rangeFrom}-${rangeTo - 1}` };
+    }
     return this._signedRequest('GET', key, {
       query: { ...opts },
       headers: { ...rangeHdr, ...ssecHeaders },
@@ -867,7 +952,7 @@ class S3mini {
       throw new Error(`${C.ERROR_PREFIX}ETag not found in response headers`);
     }
 
-    return U.sanitizeETag(etag);
+    return sanitizeETag(etag);
   }
 
   /**
@@ -897,7 +982,7 @@ class S3mini {
     return this._signedRequest('PUT', key, {
       body: this._validateData(data),
       headers: {
-        [C.HEADER_CONTENT_LENGTH]: U.getByteSize(data),
+        [C.HEADER_CONTENT_LENGTH]: getByteSize(data),
         [C.HEADER_CONTENT_TYPE]: fileType,
         ...additionalHeaders,
         ...ssecHeaders,
@@ -935,7 +1020,7 @@ class S3mini {
       headers,
       withQuery: true,
     });
-    const parsed = U.parseXml(await res.text()) as Record<string, unknown>;
+    const parsed = parseXml(await res.text()) as Record<string, unknown>;
 
     if (parsed && typeof parsed === 'object') {
       // Check for both cases of InitiateMultipartUploadResult
@@ -990,12 +1075,12 @@ class S3mini {
       query,
       body,
       headers: {
-        [C.HEADER_CONTENT_LENGTH]: U.getByteSize(data),
+        [C.HEADER_CONTENT_LENGTH]: getByteSize(data),
         ...ssecHeaders,
       },
     });
 
-    return { partNumber, etag: U.sanitizeETag(res.headers.get('etag') || '') };
+    return { partNumber, etag: sanitizeETag(res.headers.get('etag') || '') };
   }
 
   /**
@@ -1025,7 +1110,7 @@ class S3mini {
     const xmlBody = this._buildCompleteMultipartUploadXml(parts);
     const headers = {
       [C.HEADER_CONTENT_TYPE]: C.XML_CONTENT_TYPE,
-      [C.HEADER_CONTENT_LENGTH]: U.getByteSize(xmlBody),
+      [C.HEADER_CONTENT_LENGTH]: getByteSize(xmlBody),
     };
 
     const res = await this._signedRequest('POST', key, {
@@ -1035,7 +1120,7 @@ class S3mini {
       withQuery: true,
     });
 
-    const parsed = U.parseXml(await res.text()) as Record<string, unknown>;
+    const parsed = parseXml(await res.text()) as Record<string, unknown>;
     if (parsed && typeof parsed === 'object') {
       // Check for both cases
       const result = parsed.completeMultipartUploadResult || parsed.CompleteMultipartUploadResult || parsed;
@@ -1048,7 +1133,7 @@ class S3mini {
         if (etag && typeof etag === 'string') {
           return {
             ...resultObj,
-            etag: U.sanitizeETag(etag),
+            etag: sanitizeETag(etag),
           } as IT.CompleteMultipartUploadResult;
         }
 
@@ -1089,7 +1174,7 @@ class S3mini {
       headers,
       withQuery: true,
     });
-    const parsed = U.parseXml(await res.text()) as Record<string, unknown>;
+    const parsed = parseXml(await res.text()) as Record<string, unknown>;
     if (
       parsed &&
       'error' in parsed &&
@@ -1220,7 +1305,7 @@ class S3mini {
     this._checkKey(sourceKey);
     this._checkKey(destinationKey);
 
-    const copySource = `/${this.bucketName}/${U.uriEscape(sourceKey)}`;
+    const copySource = `/${this.bucketName}/${uriEscape(sourceKey)}`;
 
     return this._executeCopyOperation(destinationKey, copySource, options);
   }
@@ -1312,7 +1397,7 @@ class S3mini {
   }
 
   private _parseCopyObjectResponse(xmlText: string): IT.CopyObjectResult {
-    const parsed = U.parseXml(xmlText) as Record<string, unknown>;
+    const parsed = parseXml(xmlText) as Record<string, unknown>;
     if (!parsed || typeof parsed !== 'object') {
       throw new Error(`${C.ERROR_PREFIX}Unexpected copyObject response format`);
     }
@@ -1323,7 +1408,7 @@ class S3mini {
       throw new Error(`${C.ERROR_PREFIX}ETag not found in copyObject response`);
     }
     return {
-      etag: U.sanitizeETag(etag),
+      etag: sanitizeETag(etag),
       lastModified: lastModified ? new Date(lastModified as string) : undefined,
     };
   }
@@ -1340,13 +1425,13 @@ class S3mini {
   }
 
   private async _deleteObjectsProcess(keys: string[]): Promise<boolean[]> {
-    const objectsXml = keys.map(key => `<Object><Key>${U.escapeXml(key)}</Key></Object>`).join('');
+    const objectsXml = keys.map(key => `<Object><Key>${escapeXml(key)}</Key></Object>`).join('');
     const xmlBody = '<Delete>' + objectsXml + '</Delete>';
     const query = { delete: '' };
-    const sha256base64 = U.base64FromBuffer(await U.sha256(xmlBody));
+    const sha256base64 = base64FromBuffer(await sha256(xmlBody));
     const headers = {
       [C.HEADER_CONTENT_TYPE]: C.XML_CONTENT_TYPE,
-      [C.HEADER_CONTENT_LENGTH]: U.getByteSize(xmlBody),
+      [C.HEADER_CONTENT_LENGTH]: getByteSize(xmlBody),
       [C.HEADER_AMZ_CHECKSUM_SHA256]: sha256base64,
     };
 
@@ -1356,7 +1441,7 @@ class S3mini {
       headers,
       withQuery: true,
     });
-    const parsed = U.parseXml(await res.text()) as Record<string, unknown>;
+    const parsed = parseXml(await res.text()) as Record<string, unknown>;
     if (!parsed || typeof parsed !== 'object') {
       throw new Error(`${C.ERROR_PREFIX}Failed to delete objects: ${JSON.stringify(parsed)}`);
     }
@@ -1444,7 +1529,7 @@ class S3mini {
       const res = await this._fetch(url, {
         method,
         headers,
-        body: ['GET', 'HEAD'].includes(method) ? undefined : body,
+        body: method === 'GET' || method === 'HEAD' ? undefined : body,
         signal: this.requestAbortTimeout ? AbortSignal.timeout(this.requestAbortTimeout) : undefined,
       });
       this._log('info', `Response status: ${res.status}, tolerated: ${toleratedStatusCodes.join(',')}`);
@@ -1454,9 +1539,9 @@ class S3mini {
       await this._handleErrorResponse(res);
       return res;
     } catch (err: unknown) {
-      const code = U.extractErrCode(err);
+      const code = extractErrCode(err);
       if (code && ['ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT', 'ECONNREFUSED'].includes(code)) {
-        throw new U.S3NetworkError(`S3 network error: ${code}`, code, err);
+        throw new S3NetworkError(`S3 network error: ${code}`, code, err);
       }
       throw err;
     }
@@ -1466,7 +1551,7 @@ class S3mini {
     if (headers.get('content-type') !== 'application/xml') {
       return {};
     }
-    const parsedBody = U.parseXml(body);
+    const parsedBody = parseXml(body);
     if (
       !parsedBody ||
       typeof parsedBody !== 'object' ||
@@ -1492,7 +1577,7 @@ class S3mini {
       'error',
       `${C.ERROR_PREFIX}Request failed with status ${res.status}: ${svcCode} - ${errorMessage},err body: ${errorBody}`,
     );
-    throw new U.S3ServiceError(`S3 returned ${res.status} – ${svcCode}`, res.status, svcCode, errorBody);
+    throw new S3ServiceError(`S3 returned ${res.status} – ${svcCode}`, res.status, svcCode, errorBody);
   }
 
   private _buildCanonicalQueryString(queryParams: Record<string, unknown>): string {
@@ -1505,10 +1590,10 @@ class S3mini {
       .join('&');
   }
   private async _getSignatureKey(dateStamp: string): Promise<ArrayBuffer> {
-    const kDate = await U.hmac(`AWS4${this.secretAccessKey}`, dateStamp);
-    const kRegion = await U.hmac(kDate, this.region);
-    const kService = await U.hmac(kRegion, C.S3_SERVICE);
-    return await U.hmac(kService, C.AWS_REQUEST_TYPE);
+    const kDate = await hmac(`AWS4${this.#secretAccessKey}`, dateStamp);
+    const kRegion = await hmac(kDate, this.region);
+    const kService = await hmac(kRegion, C.S3_SERVICE);
+    return await hmac(kService, C.AWS_REQUEST_TYPE);
   }
 }
 

package/src/utils.ts

@@ -3,7 +3,7 @@ import type { XmlValue, XmlMap, ListBucketResponse, ErrorWithCode } from './type
 
 const ENCODR = new TextEncoder();
 const chunkSize = 0x8000; // 32KB chunks
-const HEXS = '0123456789abcdef';
+const HEX_CHARS = new Uint8Array([48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 97, 98, 99, 100, 101, 102]);
 
 export const getByteSize = (data: unknown): number => {
   if (typeof data === 'string') {
@@ -23,13 +23,15 @@ export const getByteSize = (data: unknown): number => {
  * @param {ArrayBuffer} buffer The raw bytes.
  * @returns {string} Hexadecimal string
  */
+
 export const hexFromBuffer = (buffer: ArrayBuffer): string => {
   const bytes = new Uint8Array(buffer);
-  let hex = '';
-  for (const byte of bytes) {
-    hex += HEXS[byte >> 4]! + HEXS[byte & 0x0f]!;
+  const hex = new Uint8Array(bytes.length * 2);
+  for (let i = 0, j = 0; i < bytes.length; i++) {
+    hex[j++] = HEX_CHARS[bytes[i]! >> 4]!;
+    hex[j++] = HEX_CHARS[bytes[i]! & 0x0f]!;
   }
-  return hex;
+  return String.fromCodePoint(...hex);
 };
 
 /**
@@ -158,7 +160,7 @@ export const parseXml = (input: string): XmlValue => {
  * @param c Character to encode
  * @returns Percent-encoded character
  */
-const encodeAsHex = (c: string): string => `%${c.charCodeAt(0).toString(16).toUpperCase()}`;
+const encodeAsHex = (c: string): string => `%${(c.codePointAt(0) ?? 0).toString(16).toUpperCase()}`;
 
 /**
  * Escape a URI string using percent encoding
@@ -166,7 +168,7 @@ const encodeAsHex = (c: string): string => `%${c.charCodeAt(0).toString(16).toUp
  * @returns Escaped URI string
  */
 export const uriEscape = (uriStr: string): string => {
-  return encodeURIComponent(uriStr).replace(/[!'()*]/g, encodeAsHex);
+  return encodeURIComponent(uriStr).replaceAll(/[!'()*]/g, encodeAsHex);
 };
 
 /**