# amazon-s3-uri

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

Latest version **1.0.0** (published 2026-04-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install amazon-s3-uri
pnpm add amazon-s3-uri
yarn add amazon-s3-uri
bun add amazon-s3-uri
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-04-30 |
| First published | 2016-10-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=20.0.0 |
| Dependencies | 0 |
| Unpacked size | 14.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 26 |
| Author | Frantz Gauthier |
| Maintainers | frantz |
| Keywords | aws, s3, uri, parser |

## Links

- npm: https://www.npmjs.com/package/amazon-s3-uri
- Repository: https://github.com/frantz/amazon-s3-uri
- Homepage: https://github.com/frantz/amazon-s3-uri#readme
- Issues: https://github.com/frantz/amazon-s3-uri/issues
- npm.io page: https://npm.io/package/amazon-s3-uri

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2026-04-30
- 0.3.0 — 2026-04-30
- 0.2.0 — 2026-04-30
- 0.1.1 — 2021-04-06
- 0.1.0 — 2020-10-03
- 0.0.3 — 2017-08-11
- 0.0.2 — 2016-10-26
- 0.0.1 — 2016-10-26

## README

# AmazonS3URI

[![Actions Status](https://github.com/frantz/amazon-s3-uri/workflows/test/badge.svg)](https://github.com/frantz/amazon-s3-uri/actions)
[![codecov](https://codecov.io/gh/frantz/amazon-s3-uri/branch/master/graph/badge.svg)](https://codecov.io/gh/frantz/amazon-s3-uri)

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

Adapted from the [AWS Java SDK `AmazonS3URI`](https://github.com/aws/aws-sdk-java/blob/master/aws-java-sdk-s3/src/main/java/com/amazonaws/services/s3/AmazonS3URI.java), 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

```sh
npm install amazon-s3-uri
```

## Usage

```js
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:

```js
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:

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

## License

MIT

---
_Source: https://npm.io/package/amazon-s3-uri · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._