lean-s3 0.7.1 → 0.7.3

package/dist/index.d.ts

@@ -57,7 +57,7 @@ type DeleteObjectsError = {
     message: string;
     versionId: string;
 };
-interface S3FilePresignOptions {
+interface S3FilePresignOptions extends OverridableS3ClientOptions {
     contentHash?: Buffer;
     /** Seconds. */
     expiresIn?: number;
@@ -67,6 +67,27 @@ interface S3FilePresignOptions {
     acl?: Acl;
     /** `Content-Type` of the file. */
     type?: string;
+    /**
+     * Headers to set on the response of the S3 service.
+     */
+    response?: {
+        /**
+         * Used to set the file name that browsers display when downloading the file.
+         *
+         * @example
+         * ```js
+         * client.presign("foo.jpg", {
+         *   response: {
+         *     contentDisposition: {
+         *       type: "attachment",
+         *       filename: "download.jpg",
+         *     },
+         *   },
+         * });
+         * ```
+         */
+        contentDisposition?: ContentDisposition;
+    };
 }
 type ListObjectsOptions = {
     bucket?: string;
@@ -311,9 +332,21 @@ declare class S3Client {
      *   expiresIn: 3600 // 1 hour
      * });
      * ```
+     *
+     * @example
+     * ```js
+     * client.presign("foo.jpg", {
+     *   expiresIn: 3600 // 1 hour
+     *   response: {
+     *     contentDisposition: {
+     *       type: "attachment",
+     *       filename: "download.jpg",
+     *     },
+     *   },
+     * });
+     * ```
      */
-    presign(path: string, { method, expiresIn, // TODO: Maybe rename this to expiresInSeconds
-    storageClass, contentLength, type, acl, region: regionOverride, bucket: bucketOverride, endpoint: endpointOverride, }?: S3FilePresignOptions & OverridableS3ClientOptions): string;
+    presign(path: string, optio2ns?: S3FilePresignOptions): string;
     createMultipartUpload(key: string, options?: CreateMultipartUploadOptions): Promise<CreateMultipartUploadResult>;
     /**
      * @remarks Uses [`ListMultipartUploads`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html).
@@ -538,5 +571,16 @@ type BucketInfo = {
     dataRedundancy?: string;
     type?: string;
 };
+/**
+ * Represents valid values for the [`Content-Disposition`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Disposition) header.
+ */
+type ContentDisposition = AttachmentContentDisposition | InlineContentDisposition;
+type InlineContentDisposition = {
+    type: "inline";
+};
+type AttachmentContentDisposition = {
+    type: "attachment";
+    filename?: string;
+};
 
-export { type AbortMultipartUploadOptions, type Acl, type BucketCorsRule, type BucketCorsRules, type BucketCreationOptions, type BucketDeletionOptions, type BucketExistsOptions, type BucketInfo, type BucketLocationInfo, type ByteSource, type ChecksumAlgorithm, type ChecksumType, type CompleteMultipartUploadOptions, type CompleteMultipartUploadResult, type CreateFileInstanceOptions, type CreateMultipartUploadOptions, type CreateMultipartUploadResult, type DeleteBucketCorsOptions, type DeleteObjectsError, type DeleteObjectsOptions, type DeleteObjectsResult, type GetBucketCorsOptions, type GetBucketCorsResult, type HttpMethod, type ListMultipartUploadsOptions, type ListMultipartUploadsResult, type ListObjectsIteratingOptions, type ListObjectsOptions, type ListObjectsResult, type ListPartsOptions, type ListPartsResult, type MultipartUpload, type MultipartUploadPart, type OverridableS3ClientOptions, type PresignableHttpMethod, type PutBucketCorsOptions, S3BucketEntry, S3Client, type S3ClientOptions, S3Error, type S3ErrorOptions, S3File, type S3FileDeleteOptions, type S3FileExistsOptions, type S3FilePresignOptions, type S3FileWriteOptions, S3Stat, type S3StatOptions, type StorageClass, type UndiciBodyInit, type UploadPartOptions, type UploadPartResult };
+export { type AbortMultipartUploadOptions, type Acl, type AttachmentContentDisposition, type BucketCorsRule, type BucketCorsRules, type BucketCreationOptions, type BucketDeletionOptions, type BucketExistsOptions, type BucketInfo, type BucketLocationInfo, type ByteSource, type ChecksumAlgorithm, type ChecksumType, type CompleteMultipartUploadOptions, type CompleteMultipartUploadResult, type ContentDisposition, type CreateFileInstanceOptions, type CreateMultipartUploadOptions, type CreateMultipartUploadResult, type DeleteBucketCorsOptions, type DeleteObjectsError, type DeleteObjectsOptions, type DeleteObjectsResult, type GetBucketCorsOptions, type GetBucketCorsResult, type HttpMethod, type InlineContentDisposition, type ListMultipartUploadsOptions, type ListMultipartUploadsResult, type ListObjectsIteratingOptions, type ListObjectsOptions, type ListObjectsResult, type ListPartsOptions, type ListPartsResult, type MultipartUpload, type MultipartUploadPart, type OverridableS3ClientOptions, type PresignableHttpMethod, type PutBucketCorsOptions, S3BucketEntry, S3Client, type S3ClientOptions, S3Error, type S3ErrorOptions, S3File, type S3FileDeleteOptions, type S3FileExistsOptions, type S3FilePresignOptions, type S3FileWriteOptions, S3Stat, type S3StatOptions, type StorageClass, type UndiciBodyInit, type UploadPartOptions, type UploadPartResult };

package/dist/index.js

@@ -202,7 +202,7 @@ function buildRequestUrl(endpoint, bucket, region, path) {
   const result = new URL(endpointWithBucketAndRegion);
   const pathPrefix = result.pathname.endsWith("/") ? result.pathname : `${result.pathname}/`;
   const pathSuffix = replacedBucket ? normalizePath(path) : `${normalizedBucket}/${normalizePath(path)}`;
-  result.pathname = pathPrefix + pathSuffix.replaceAll(":", "%3A").replaceAll("+", "%2B").replaceAll("(", "%28").replaceAll(")", "%29").replaceAll(",", "%2C");
+  result.pathname = pathPrefix + pathSuffix.replaceAll(":", "%3A").replaceAll("+", "%2B").replaceAll("(", "%28").replaceAll(")", "%29").replaceAll(",", "%2C").replaceAll("'", "%27").replaceAll("*", "%2A");
   return result;
 }
 function replaceDomainPlaceholders(endpoint, bucket, region) {
@@ -346,6 +346,32 @@ function ensureValidPath(path) {
   return path;
 }
 
+// src/assertNever.ts
+function assertNever(v) {
+  throw new TypeError(`Expected value not to have type ${typeof v}`);
+}
+
+// src/encode.ts
+function getContentDispositionHeader(value) {
+  switch (value.type) {
+    case "inline":
+      return "inline";
+    case "attachment": {
+      const { filename } = value;
+      if (typeof filename === "undefined") {
+        return "attachment";
+      }
+      const encoded = encodeURIComponent(filename);
+      return `attachment;filename="${encoded}";filename*=UTF-8''${encoded}`;
+    }
+    default:
+      assertNever(value);
+  }
+}
+function encodeURIComponentExtended(value) {
+  return encodeURIComponent(value).replaceAll(":", "%3A").replaceAll("+", "%2B").replaceAll("(", "%28").replaceAll(")", "%29").replaceAll(",", "%2C").replaceAll("'", "%27").replaceAll("*", "%2A");
+}
+
 // src/S3Client.ts
 var write = Symbol("write");
 var stream = Symbol("stream");
@@ -471,50 +497,58 @@ var S3Client = class {
    *   expiresIn: 3600 // 1 hour
    * });
    * ```
+   *
+   * @example
+   * ```js
+   * client.presign("foo.jpg", {
+   *   expiresIn: 3600 // 1 hour
+   *   response: {
+   *     contentDisposition: {
+   *       type: "attachment",
+   *       filename: "download.jpg",
+   *     },
+   *   },
+   * });
+   * ```
    */
-  presign(path, {
-    method = "GET",
-    expiresIn = 3600,
-    // TODO: Maybe rename this to expiresInSeconds
-    storageClass,
-    contentLength,
-    type,
-    acl,
-    region: regionOverride,
-    bucket: bucketOverride,
-    endpoint: endpointOverride
-  } = {}) {
+  presign(path, optio2ns = {}) {
+    const contentLength = optio2ns.contentLength ?? void 0;
     if (typeof contentLength === "number") {
       if (contentLength < 0) {
         throw new RangeError("`contentLength` must be >= 0.");
       }
     }
+    const method = optio2ns.method ?? "GET";
+    const contentType = optio2ns.type ?? void 0;
+    const region = optio2ns.region ?? this.#options.region;
+    const bucket = optio2ns.bucket ?? this.#options.bucket;
+    const endpoint = optio2ns.endpoint ?? this.#options.endpoint;
+    const responseOptions = optio2ns.response;
+    const contentDisposition = responseOptions?.contentDisposition;
+    const responseContentDisposition = contentDisposition ? getContentDispositionHeader(contentDisposition) : void 0;
+    const res = buildRequestUrl(endpoint, bucket, region, path);
     const now2 = /* @__PURE__ */ new Date();
     const date = getAmzDate(now2);
-    const options = this.#options;
-    const region = regionOverride ?? options.region;
-    const bucket = bucketOverride ?? options.bucket;
-    const endpoint = endpointOverride ?? options.endpoint;
-    const res = buildRequestUrl(endpoint, bucket, region, path);
     const query = buildSearchParams(
-      `${options.accessKeyId}/${date.date}/${region}/s3/aws4_request`,
+      `${this.#options.accessKeyId}/${date.date}/${region}/s3/aws4_request`,
       date,
-      expiresIn,
-      typeof contentLength === "number" || typeof type === "string" ? typeof contentLength === "number" && typeof type === "string" ? "content-length;content-type;host" : typeof contentLength === "number" ? "content-length;host" : typeof type === "string" ? "content-type;host" : "" : "host",
+      optio2ns.expiresIn ?? 3600,
+      typeof contentLength === "number" || typeof contentType === "string" ? typeof contentLength === "number" && typeof contentType === "string" ? "content-length;content-type;host" : typeof contentLength === "number" ? "content-length;host" : typeof contentType === "string" ? "content-type;host" : "" : "host",
       unsignedPayload,
-      storageClass,
-      options.sessionToken,
-      acl
+      optio2ns.storageClass,
+      this.#options.sessionToken,
+      optio2ns.acl,
+      responseContentDisposition
     );
-    const dataDigest = typeof contentLength === "number" || typeof type === "string" ? createCanonicalDataDigest(
+    const dataDigest = typeof contentLength === "number" || typeof contentType === "string" ? createCanonicalDataDigest(
       method,
       res.pathname,
       query,
-      typeof contentLength === "number" && typeof type === "string" ? {
+      typeof contentLength === "number" && typeof contentType === "string" ? {
         "content-length": String(contentLength),
-        "content-type": type,
+        "content-type": contentType,
         host: res.host
-      } : typeof contentLength === "number" ? { "content-length": String(contentLength), host: res.host } : typeof type === "string" ? { "content-type": type, host: res.host } : {},
+      } : typeof contentLength === "number" ? { "content-length": String(contentLength), host: res.host } : typeof contentType === "string" ? { "content-type": contentType, host: res.host } : {},
       unsignedPayload
     ) : createCanonicalDataDigestHostOnly(
       method,
@@ -525,8 +559,8 @@ var S3Client = class {
     const signingKey = this.#keyCache.computeIfAbsent(
       date,
       region,
-      options.accessKeyId,
-      options.secretAccessKey
+      this.#options.accessKeyId,
+      this.#options.secretAccessKey
     );
     const signature = signCanonicalDataHash(
       signingKey,
@@ -1409,7 +1443,7 @@ var S3Client = class {
     });
   }
 };
-function buildSearchParams(amzCredential, date, expiresIn, headerList, contentHashStr, storageClass, sessionToken, acl) {
+function buildSearchParams(amzCredential, date, expiresIn, headerList, contentHashStr, storageClass, sessionToken, acl, responseContentDisposition) {
   let res = "";
   if (acl) {
     res += `X-Amz-Acl=${encodeURIComponent(acl)}&`;
@@ -1418,7 +1452,7 @@ function buildSearchParams(amzCredential, date, expiresIn, headerList, contentHa
   if (contentHashStr) {
     res += `&X-Amz-Content-Sha256=${contentHashStr}`;
   }
-  res += `&X-Amz-Credential=${encodeURIComponent(amzCredential)}`;
+  res += `&X-Amz-Credential=${encodeURIComponentExtended(amzCredential)}`;
   res += `&X-Amz-Date=${date.dateTime}`;
   res += `&X-Amz-Expires=${expiresIn}`;
   if (sessionToken) {
@@ -1428,6 +1462,9 @@ function buildSearchParams(amzCredential, date, expiresIn, headerList, contentHa
   if (storageClass) {
     res += `&X-Amz-Storage-Class=${storageClass}`;
   }
+  if (responseContentDisposition) {
+    res += `&response-content-disposition=${encodeURIComponentExtended(responseContentDisposition)}`;
+  }
   return res;
 }
 function ensureParsedXml(text) {
@@ -1447,11 +1484,6 @@ function ensureParsedXml(text) {
   }
 }
 
-// src/assertNever.ts
-function assertNever(v) {
-  throw new TypeError(`Expected value not to have type ${typeof v}`);
-}
-
 // src/S3File.ts
 var S3File = class _S3File {
   #client;

package/package.json

@@ -2,7 +2,7 @@
   "name": "lean-s3",
   "author": "Niklas Mollenhauer",
   "license": "MIT",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "A server-side S3 API for the regular user.",
   "keywords": [
     "s3",