Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

megahertz/s3u

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

50 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

s3u

Tests npm version

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 (sync and promised versions)

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
// env vars can be used instead of passing arguments
const presignedUrl = await s3Url.sign({ accessKeyId, secretAccessKey });

Providers

Currently, the library is tested with the following providers:

  • Amazon S3
  • Cloudflare R2
  • 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.