amazon-s3-url

library1.0.3jsnpmunverified

A small, dependency-free TypeScript library for formatting and parsing Amazon S3 URLs (v1.0.3). It supports virtual-hosted-style and path-style URLs, regional and legacy endpoints, and both s3:// and https:// protocols. The library provides types for S3 objects and URL formats, and exports functions formatS3Url, parseS3Url, and isS3Url. It does not validate bucket names or object keys against AWS rules, nor does it support S3 access points or Object Lambda. Commonly used in AWS SDK workflows for generating S3 URIs.

storage

npm install amazon-s3-url

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AMAZON-S3-URL

amazon-s3-url

storagejavascriptv1.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

formatS3Url

✓ import { formatS3Url } from 'amazon-s3-url'

✗ const formatS3Url = require('amazon-s3-url').formatS3Url

ESM and CJS both supported; named export.

parseS3Url

✓ import { parseS3Url } from 'amazon-s3-url'

✗ import parseS3Url from 'amazon-s3-url'

Default import does not exist; must use named import.

S3Object

✓ import { S3Object } from 'amazon-s3-url'

✗ import { S3Object } from 'amazon-s3-url'

TypeScript type import; also works with type-only imports: import type { S3Object } from 'amazon-s3-url'

S3UrlFormat

✓ import { S3UrlFormat } from 'amazon-s3-url'

✗ import { S3UrlFormat } from 'amazon-s3-url'

TypeScript type import; also works with type-only imports: import type { S3UrlFormat } from 'amazon-s3-url'

Shows formatting of S3 URLs in various styles, parsing a URL back to an object, and validation with isS3Url.

import { formatS3Url, parseS3Url, isS3Url } from 'amazon-s3-url'; const s3Object = { bucket: 'my-bucket', key: 'path/to/file.txt', region: 'us-west-2' }; // Format a URL: defaults to s3-global-path const url = formatS3Url(s3Object); console.log(url); // s3://my-bucket/path/to/file.txt // Format as HTTPS regional virtual-hosted style const httpsUrl = formatS3Url(s3Object, 'https-region-virtual-host'); console.log(httpsUrl); // https://my-bucket.s3.us-west-2.amazonaws.com/path/to/file.txt // Parse a URL const parsed = parseS3Url(httpsUrl); console.log(parsed); // { bucket: 'my-bucket', key: 'path/to/file.txt', region: 'us-west-2' } // Check if a string is an S3 URL console.log(isS3Url(url)); // true console.log(isS3Url('https://example.com')); // false

Debug

Known issues

gotchaLibrary does not validate bucket names or object keys against AWS rules; malformed S3 objects can produce invalid URLs.

fix

Validate bucket names and keys against AWS naming rules separately before calling formatS3Url.

affects: >=1.0.0

deprecatedPath-style URLs (e.g., https://s3.amazonaws.com/bucket/key) are deprecated by AWS and will be discontinued.

fix

Use virtual-hosted-style URLs (e.g., https://bucket.s3.amazonaws.com/key) for new integrations.

affects: >=1.0.0

gotchaLegacy endpoints (s3.amazonaws.com) are not supported in all AWS regions.

fix

Use regional endpoints (s3.<region>.amazonaws.com) for consistent support.

affects: >=1.0.0

gotchaThe 's3-global-path' format produces an s3:// URI (e.g., s3://bucket/key), which is not an HTTPS URL and may not be usable in browser fetch requests.

fix

Use https-based formats (e.g., 'https-region-virtual-host') if you need an HTTPS URL for HTTP clients.

affects: >=1.0.0

gotchaparseS3Url does not validate that the provided string matches any known S3 pattern; it may return an object with empty bucket/key if parsing fails.

fix

Always check parsed.bucket and parsed.key for truthiness before use.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: formatS3Url is not a function

Default import used: import formatS3Url from 'amazon-s3-url'

fix

Use named import: import { formatS3Url } from 'amazon-s3-url'

Module not found: Error: Can't resolve 'amazon-s3-url'

Package not installed or path incorrect

fix

Run npm install amazon-s3-url and ensure import path is correct.

Property 'region' does not exist on type 'S3Object'

Using TypeScript with strict mode and region is optional; must check for undefined

fix

Declare region as optional in your type or use conditional checks.

Require is not defined (ES modules)

Using CommonJS require in an ESM environment

fix

Use import syntax instead: import { formatS3Url } from 'amazon-s3-url'

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

31 hits · last 30 days

node

Resources

githubhttps://github.com/zirkelc/amazon-s3-url ↗

packageamazon-s3-url ↗

homepagehttps://github.com/zirkelc/amazon-s3-url ↗