@ukab/storage

Ukab Storage Module

The library is compitable with both ESM and CommonJS. You can use this package with any framework or even with NodeJS native http module.

Usage

Save file

const ukab = require('@ukab/storage');

const storage = ukab.Initiate(/* override config */);

const result = await storage.disk(/* default is 'local' */).put('path/to/file.txt');

console.log(result) // { key:string }

const { Storage, LocalDriver, DEFAULT_CONF } = require('@ukab/storage');

const storage = new Storage(DEFAULT_CONF);
store.driver('local', LocalDriver);

const result = await storage.disk(/* default is 'local' */).put('path/to/file.txt', {key:'custom-file-name.txt', folder:'custom-folder'});

console.log(result) // { key:string }

Delete file will only delete for valid key, path is auto generated based on config

await store.disk().delete(result.key)

Stat of file

const stat = await store.disk().stat(result.key)

Stream file

const stream = await store.disk().stream(result.key)

// within range
// const stream = await store.disk().stream(result.key, {start:4000, end:10000})

// with range header: range=unit,start,end
// const stream = await store.disk().stream(result.key, {range:ctx.get('range')})

S3 Driver

install aws s3 sdk.

npm i @aws-sdk/client-s3

register s3 driver

import { S3Driver } from '@ukab/storage/drivers/s3.js';

store.driver('s3', new S3Driver(config));

S3 config

export interface IS3DiskConfig extends IDiskConfig {
  // s3 api endpoint
  endpoint: string,
  region: string,
  key: string,
  secret: string,
  bucket: string,
  // used in genrating s3 object location url,
  // without it location be like: `${config.endpoint}/${config.bucket}/${result.key}`
  url: string,

  // if you want to handle requests on your own
  serviceProvider?(c: IS3DiskConfig): (command: string, input: any) => Promise<any>
}

Config

{
  // default disk
  default: 'local',
  // disks config
  disks: {
    // local disk config
    local: {
      // which driver to use
      driver: 'local',
      // root directory
      root: 'storage/local',
     
     // each disk can have access control layer, 
     // to use different disk options during runtime.
     // this depends on driver, does it support acl or not.
     // currently, only `LocalDriver` supports acl.
     // so you can use one disk for both public and private files
     // acl: {
     // private: { root:'storage/private' },
     // }
    },
    // private disk config
    private: {
      driver: 'local',
      root: 'storage/private',

      // rootResolver(root: string, base: string)
      // keyResolver(source: FileSource, file:NodeJs.Dict<any>)
    },
    // public disk config
    public: {
      driver: 'local',
      root: 'storage/public',

      // you can add extra keys required for driver
      // [key:string]:any
    },
    // s3 disk config
    s3: {
      driver: 's3',
      endpoint: process.env.S3_ENDPOINT,
      region: process.env.S3_REGION,
      key: process.env.S3_ACCESS_KEY_ID,
      secret: process.env.S3_SECRET_ACCESS_KEY,
      bucket: process.env.S3_BUCKET,
      url: process.env.S3_URL,
    },
  },
  // each disk can have its own root resolver
  // convert relative disk root to absolute path 
  // by default, it appends `current working directory` to disk root
  rootResolver(root: string, base: string),

  // each disk can have its own key resolver
  // generate key path for file, default is folder/y/m/basename.ext or y/m/basename.ext
  // only works with string as file source
  // @param {string|Buffer|Stream} source
  // @param  {{folder:string,key:string, /*extra, whatever added by user*/}} file
  keyResolver(source: FileSource, file:NodeJs.Dict<any>)
}

Changelogs

v1.0.0-beta.2

• typings support update

v1.0.0-beta.3

• typings update
• try to guess mime in disk.istream()