AmazonS3URI

A URI wrapper that can parse out information about an S3 URI.

Adapted from the AWS Java SDK AmazonS3URI, with the following differences:

• There is no preprocessing on the given URI string — encode special characters yourself if needed
• region is never null for a valid S3 URI; it defaults to us-east-1

Install

npm install amazon-s3-uri

Usage

const AmazonS3URI = require("amazon-s3-uri");

const { region, bucket, key, isPathStyle, isDualStack, versionId } =
  AmazonS3URI("https://bucket.s3.dualstack.us-east-1.amazonaws.com/key");
// region      → 'us-east-1'
// bucket      → 'bucket'
// key         → 'key'
// isPathStyle → false
// isDualStack → true
// versionId   → null

Works both as a constructor and as a plain function call:

const a = new AmazonS3URI("s3://bucket/key"); // constructor
const b = AmazonS3URI("s3://bucket/key");     // functional — returns a new instance

Throws TypeError for non-string input and Error for URIs that cannot be parsed as S3 endpoints.

Parsed properties

| Property | Type | Description | |---------------|------------------|-------------| | bucket | string \| null | Bucket name, or null if not present | | key | string \| null | Object key, or null if not present | | region | string | AWS region; defaults to us-east-1 | | isPathStyle | boolean | true when the bucket is in the path rather than the hostname | | isDualStack | boolean | true when the URI uses an S3 dualstack endpoint | | versionId | string \| null | Value of the versionId query parameter, or null | | uri | object | Parsed URL components (protocol, host, pathname, search, query, href, …) |

Supported URI formats

s3://bucket/key
https://s3.amazonaws.com/bucket/key                           (path-style, global)
https://s3-eu-west-1.amazonaws.com/bucket/key                 (path-style, regional)
https://s3.us-east-1.amazonaws.com/bucket/key                 (path-style, regional)
https://s3.dualstack.us-east-1.amazonaws.com/bucket/key       (path-style, dualstack)
https://bucket.s3.amazonaws.com/key                           (virtual-hosted, global)
https://bucket.s3-eu-west-1.amazonaws.com/key                 (virtual-hosted, regional)
https://bucket.s3.dualstack.us-east-1.amazonaws.com/key       (virtual-hosted, dualstack)
https://bucket.vpce-xxx.s3.us-east-1.vpce.amazonaws.com/key  (VPCE virtual-hosted)
https://vpce-xxx.s3.us-east-1.vpce.amazonaws.com/bucket/key  (VPCE path-style)

parseQueryString option

Pass true as the second argument to expose uri.query as a parsed object instead of a raw string:

const { uri, versionId } = AmazonS3URI(
  "https://bucket.s3.amazonaws.com/key?versionId=abc123",
  true
);
// uri.query → { versionId: 'abc123' }
// versionId → 'abc123'

License

MIT