lemon-core/dist/cores/aws/aws-s3-service.d.ts

Lemon Serverless Micro-Service Platform

/// <reference types="node" />
/// <reference types="node" />
import AWS from 'aws-sdk';
import { CoreServices } from '../core-services';
import { Body } from 'aws-sdk/clients/s3';
/** ****************************************************************************************************************
 *  Core Types.
 ** ****************************************************************************************************************/
export declare type Metadata = AWS.S3.Metadata;
export declare type S3Object = AWS.S3.Object;
export interface TagSet {
    [key: string]: string;
}
/**
 * type: `HeadObjectResult`
 * - some properties of `HeadObjectOutput`
 */
export interface HeadObjectResult {
    ContentType: string;
    ContentLength: number;
    Metadata: Metadata;
    ETag: string;
    LastModified: string;
}
/**
 * type: `PutObjectResult`
 * - only some properties from origin-result.
 */
export interface PutObjectResult {
    Location: string;
    Bucket: string;
    Key: string;
    /**
     * An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL.
     */
    ETag: string;
    /**
     * Size of the body in bytes.
     */
    ContentLength?: number;
    /**
     * A standard MIME type describing the format of the object data.
     */
    ContentType?: string;
    /**
     * A map of metadata to store with the object in S3.
     */
    Metadata?: Metadata;
}
/**
 * type: `GetObjectResult`
 * - only some properties from origin-result.
 */
export interface GetObjectResult {
    /**
     * Size of the body in bytes.
     */
    ContentLength?: number;
    /**
     * A standard MIME type describing the format of the object data.
     */
    ContentType?: string;
    /**
     * A map of metadata to store with the object in S3.
     */
    Metadata?: Metadata;
    /**
     * Object data.
     */
    Body?: Body;
    /**
     * An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL.
     */
    ETag: string;
    /**
     * The number of tags, if any, on the object.
     */
    TagCount?: number;
}
/**
 * type: `ListObjectResult`
 * - only some properties from origin-result.
 */
export interface ListObjectResult {
    /** list of object infor */
    Contents: S3Object[];
    /** limit of each request */
    MaxKeys: number;
    /** total key-count read */
    KeyCount: number;
    /** flag to have more */
    IsTruncated?: boolean;
    /** valid only if truncated, and has more */
    NextContinuationToken?: string;
    /** internal error-string */
    error?: string;
}
export interface CoreS3Service extends CoreServices {
    bucket: (target?: string) => string;
    putObject: (body: string, key?: string, metadata?: Metadata, tags?: TagSet) => Promise<PutObjectResult>;
    getObject: (key: string) => Promise<any>;
    getDecodedObject: (key: string) => Promise<any>;
    getObjectTagging: (key: string) => Promise<TagSet>;
    deleteObject: (key: string) => Promise<void>;
}
/**
 * main service implement.
 */
export declare class AWSS3Service implements CoreS3Service {
    /**
     * environ name to use `bucket`
     */
    static ENV_S3_NAME: string;
    /**
     * default `bucket` name
     */
    static DEF_S3_BUCKET: string;
    /**
     * get name of this
     */
    name: () => string;
    /**
     * hello
     */
    hello: () => string;
    /**
     * get target endpoint by name.
     */
    bucket: (target?: string) => string;
    /**
     * retrieve metadata without returning the object
     *
     * @param {string} key
     * @return  metadata object / null if not exists
     */
    headObject: (key: string) => Promise<HeadObjectResult>;
    /**
     * upload a file to S3 Bucket
     *
     * ```js
     * const res = $s3.putObject(JSON.stringify({ message }), 'test.json');
     * // response would be like
     * {
     *  "Bucket": "lemon-hello-www",
     *  "ETag": "5e206.....8bd4c",
     *  "Key": "test.json",
     *  "Location": "https://lemon-hello-www.s3.ap-northeast-2.amazonaws.com/test.json",
     * }
     * ```
     *
     * @param {string|Buffer} content   content body
     * @param {string} key              (optional) S3 key to put
     * @param {Metadata} metadata       (optional) metadata to store
     * @param {object} tags             (optional) tag set
     */
    putObject: (content: string | Buffer, key?: string, metadata?: Metadata, tags?: TagSet) => Promise<PutObjectResult>;
    /**
     * get a file from S3 Bucket
     *
     * @param {string} key
     */
    getObject: (key: string) => Promise<GetObjectResult>;
    /**
     * return decoded Object from bucket file.
     *
     * @param {string} key  ex) 'hello-0001.json' , 'dist/hello-0001.json
     */
    getDecodedObject: <T = object>(key: string) => Promise<T>;
    /**
     * get tag-set of object
     *
     * @param {string} key
     */
    getObjectTagging: (key: string) => Promise<TagSet>;
    /**
     * delete object from bucket
     *
     * @param {string} key
     */
    deleteObject: (key: string) => Promise<void>;
    /**
     * list objects in bucket
     */
    listObjects: (options?: {
        /** keys that begin with the specified prefix. */
        prefix?: string;
        /** use to group keys */
        delimiter?: string;
        /** maximum number of keys returned in single request (default 10, max 1000) */
        limit?: number;
        /** flag to read all keys (each request contains `limit`) */
        unlimited?: boolean;
        /** same as NextContinuationToken */
        nextToken?: string;
        /** (optional) flag to throw error if error, or see `.error` in result */
        throwable?: boolean;
    }) => Promise<ListObjectResult>;
}