Package Exports

s3u
s3u/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (s3u) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

s3u

Description

S3 URL manipulation helper similar to standard URL class

Key features

Support different S3 providers
Support both Node.js and browser environment
Simple and lightweight
No dependencies
Typescript support
Built-in presigned URL generation

Installation

Install with npm:

npm install --save s3u

Usage

const { S3Url } = require('s3u');

const s3Url = new S3Url('https://mybucket.s3.amazonaws.com/');

// Changing attributes
s3Url.key = 'My file.txt';
s3Url.region = 'eu-west-2'

console.log(url.href);
// https://mybucket.s3.eu-west-2.amazonaws.com/My+file.txt

console.log(s3Url);
/*
S3Url {
  bucket: 'mybucket',
  bucketPosition: 'hostname',
  cdn: false,
  domain: 'amazonaws.com',
  error: null,
  hash: '',
  key: 'My file.txt',
  password: '',
  port: '',
  protocol: 'https:',
  provider: AmazonAwsProvider {
    domain: 'amazonaws.com',
    endpoint: 'https://s3.{region}.amazonaws.com',
    id: 'amazonaws.com',
    title: 'Amazon S3'
  },
  region: 'eu-west-2',
  search: '',
  sourceUrl: 'https://mybucket.s3.amazonaws.com/',
  username: ''
}
 */

// Making a http copy
const httpUrl = s3Url.clone({ protocol: 'http:' }).href;

// Generaing presigned URL, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
// env vars can be used instead of passing arguments
const presignedUrl = s3Url.sign({ accessKeyId, secretAccessKey });

Providers

Currently, the library is tested with the following providers:

Amazon S3
DigitalOcean Spaces
Stackpath Storage
Generic provider (Supports URL schema like bucket.region.example.com)

Adding a custom provider based on existed implementation:

const { s3Parser, S3Provider } = require('s3u');

s3Parser.addProvider(new S3Provider({
  domain: 'storage.example.com',
  title: 'Example provider',
}))

Adding a custom provider implementation

To add a parser for a custom provider you need to extend S3Provider class. You can use AmazonAwsProvider.js as an example.

const { s3Parser, S3Provider } = require('s3u');

class NewProvider extends S3Provider {
  buildHostName({ s3Url }) {
    return [
      s3Url.bucketPosition === 'hostname' && s3Url.bucket,
      'files',
      s3Url.domain || this.domain,
    ]
    .filter(Boolean)
    .join('.');
  }
}

s3Parser.addProvider(new NewProvider({
  domain: 'example.com',
  title: 'Example provider',
}))

License

Licensed under MIT.