s3mini 0.7.0 → 0.8.0

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.
@@ -11,7 +25,7 @@ import * as U from './utils.js';
  *
  * @class
  * @example
- * const s3 = new CoreS3({
+ * const s3 = new S3mini({
  *   accessKeyId: 'your-access-key',
  *   secretAccessKey: 'your-secret-key',
  *   endpoint: 'https://your-s3-endpoint.com/bucket-name',
@@ -43,15 +57,15 @@ 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;
   readonly requestSizeInBytes: number;
   readonly requestAbortTimeout?: number;
   readonly logger?: IT.Logger;
-  readonly fetch: typeof fetch;
+  readonly _fetch: typeof fetch;
   private signingKeyDate?: string;
   private signingKey?: ArrayBuffer;
 
@@ -66,15 +80,15 @@ 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();
     this.requestSizeInBytes = requestSizeInBytes;
     this.requestAbortTimeout = requestAbortTimeout;
     this.logger = logger;
-    this.fetch = fetch;
+    this._fetch = (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => fetch(input, init);
   }
 
   private _sanitize(obj: unknown): unknown {
@@ -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)}`);
@@ -604,7 +659,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 +673,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 +702,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 +727,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 +751,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 +775,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 +800,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 +809,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;
@@ -867,7 +923,7 @@ class S3mini {
       throw new Error(`${C.ERROR_PREFIX}ETag not found in response headers`);
     }
 
-    return U.sanitizeETag(etag);
+    return sanitizeETag(etag);
   }
 
   /**
@@ -897,7 +953,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 +991,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 +1046,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 +1081,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 +1091,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 +1104,7 @@ class S3mini {
         if (etag && typeof etag === 'string') {
           return {
             ...resultObj,
-            etag: U.sanitizeETag(etag),
+            etag: sanitizeETag(etag),
           } as IT.CompleteMultipartUploadResult;
         }
 
@@ -1089,7 +1145,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 +1276,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 +1368,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 +1379,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 +1396,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 +1412,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)}`);
     }
@@ -1441,10 +1497,10 @@ class S3mini {
   ): Promise<Response> {
     this._log('info', `Sending ${method} request to ${url}`, `headers: ${JSON.stringify(headers)}`);
     try {
-      const res = await this.fetch(url, {
+      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 +1510,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 +1522,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 +1548,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 +1561,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.fromCharCode(...hex);
 };
 
 /**
@@ -153,6 +155,38 @@ export const parseXml = (input: string): XmlValue => {
   return Object.keys(result).length > 0 ? result : unescapeXml(xmlContent.trim());
 };
 
+// export const parseXml = (input: string): XmlValue => {
+//   const xml = input.replace(/<\?xml[^?]*\?>\s*/, '');
+//   const result: XmlMap = {};
+//   let i = 0;
+//   const len = xml.length;
+
+//   while (i < len) {
+//     const tagStart = xml.indexOf('<', i);
+//     if (tagStart === -1 || xml[tagStart + 1] === '/') {
+//       break;
+//     }
+
+//     const tagEnd = xml.indexOf('>', tagStart);
+//     const tag = xml.slice(tagStart + 1, tagEnd);
+//     const closeTag = `</${tag}>`;
+//     const closeIdx = xml.indexOf(closeTag, tagEnd);
+
+//     if (closeIdx === -1) {
+//       i = tagEnd + 1;
+//       continue;
+//     }
+
+//     const inner = xml.slice(tagEnd + 1, closeIdx);
+//     const node = inner.includes('<') ? parseXml(inner) : unescapeXml(inner);
+
+//     const cur = result[tag];
+//     result[tag] = cur === undefined ? node : Array.isArray(cur) ? [...cur, node] : [cur, node];
+//     i = closeIdx + closeTag.length;
+//   }
+//   return Object.keys(result).length ? result : unescapeXml(xml.trim());
+// };
+
 /**
  * Encode a character as a URI percent-encoded hex value
  * @param c Character to encode