Amazon S3 URL Formatter and Parser

This small and dependency-free library is designed to help you check, format and parse Amazon S3 URLs.
Please note that this library does only rudimentary URL validation on the structure of the URL. It currently does not validate bucket names and object keys against the rules defined in the AWS documentation.

Amazon S3 URL Formats

Amazon S3 supports a combination of different styles:

$3

The difference between these two styles is how the bucket name is included in the URL, either as part of the hostname or as part of the pathname.
- Virtual-hosted-style URLs have the bucket name as part of the host: .s3.amazonaws.com/
- Path-style URLs have the bucket name as part of the path, e.g. s3.amazonaws.com//

> [!WARNING]
> Path-style URLs will be discontinued in the future See Amazon S3 backward compatibility for more information.

$3

The difference between these two styles is if the region is included in the URL.

- Regional URLs use the regional endpoint s3..amazonaws.com
- Legacy URLs use the global endpoint s3.amazonaws.com

> [!WARNING]
> Only some regions support legacy-style URLs. See Amazon S3 backward compatibility for more information.

$3

The choice whether to use s3:// or https:// depends on the client used to access the S3 bucket.

$3

The global format s3:/// is the S3 URI that is used by the AWS management console. This format is only available with the s3:// protocol.

Installation

``bash

npm

npm install amazon-s3-url

yarn

yarn add amazon-s3-url

pnpm

pnpm add amazon-s3-url
`

Usage

The library defines the types S3Object and S3UrlFormat and it exports three functions formatS3Url, parseS3Url and isS3Url.

$3

This type represents an S3 object and has the properties bucket and key. The region property is optional and can be used to specify the region of the S3 bucket.

`ts
type S3Object = {
bucket: string;
key: string;
region?: string;
};

const s3Object: S3Object = {
bucket: 'bucket',
key: 'key',
region: 'us-west-1'
};
`

$3

This type represents the format of an S3 URL.

The format has the structure --