@juzi/file-box 1.7.0

package/dist/esm/src/file-box.js

@@ -0,0 +1,775 @@
+/**
+ * File Box
+ * https://github.com/huan/file-box
+ *
+ * 2018 Huan LI <zixia@zixia.net>
+ */
+/* eslint no-use-before-define: off */
+import * as FS from 'fs';
+import * as PATH from 'path';
+import * as URL from 'url';
+import mime from 'mime';
+import { PassThrough, } from 'stream';
+import { instanceToClass, looseInstanceOfClass, interfaceOfClass, } from 'clone-class';
+import { VERSION, } from './config.js';
+import { FileBoxType, } from './file-box.type.js';
+import { dataUrlToBase64, httpHeaderToFileName, httpHeadHeader, httpStream, streamToBuffer, } from './misc.js';
+import { bufferToQrValue, qrValueToStream, } from './qrcode.js';
+import { sizedChunkTransformer, } from './pure-functions/sized-chunk-transformer.js';
+const EMPTY_META_DATA = Object.freeze({});
+const UNKNOWN_SIZE = -1;
+let interfaceOfFileBox = (_) => false;
+let looseInstanceOfFileBox = (_) => false;
+class FileBox {
+    /**
+     *
+     * Static Properties
+     *
+     */
+    static version = VERSION;
+    /**
+     * Symbol.hasInstance: instanceof
+     *
+     * @link https://www.keithcirkel.co.uk/metaprogramming-in-es6-symbols/
+     */
+    static [Symbol.hasInstance](lho) {
+        return this.validInterface(lho);
+    }
+    /**
+     * Check if obj satisfy FileBox interface
+     */
+    static valid(target) {
+        return this.validInstance(target) || this.validInterface(target);
+    }
+    /**
+     * Check if obj satisfy FileBox interface
+     */
+    static validInterface(target) {
+        return interfaceOfFileBox(target);
+    }
+    /**
+     * loose check instance of FileBox
+     */
+    static validInstance(target) {
+        return looseInstanceOfFileBox(target);
+    }
+    /**
+     * fromUrl()
+     */
+    static fromUrl(url, nameOrOptions, headers) {
+        let name;
+        let size;
+        let md5;
+        if (typeof nameOrOptions === 'object') {
+            headers = nameOrOptions.headers;
+            name = nameOrOptions.name;
+            size = nameOrOptions.size;
+            md5 = nameOrOptions.md5;
+        }
+        else {
+            name = nameOrOptions;
+        }
+        if (!name) {
+            const parsedUrl = new URL.URL(url);
+            name = parsedUrl.pathname;
+        }
+        const options = {
+            headers,
+            md5,
+            name,
+            size,
+            type: FileBoxType.Url,
+            url,
+        };
+        return new this(options);
+    }
+    /**
+     * Alias for `FileBox.fromFile()`
+     *
+     * @alias fromFile
+     */
+    static fromFile(path, name, md5) {
+        if (!name) {
+            name = PATH.parse(path).base;
+        }
+        const options = {
+            md5,
+            name,
+            path,
+            type: FileBoxType.File,
+        };
+        return new this(options);
+    }
+    /**
+     * TODO: add `FileBoxStreamOptions` with `size` support (@huan, 202111)
+     */
+    static fromStream(stream, name, md5) {
+        const options = {
+            md5,
+            name: name || 'stream.dat',
+            stream,
+            type: FileBoxType.Stream,
+        };
+        return new this(options);
+    }
+    static fromBuffer(buffer, name, md5) {
+        const options = {
+            buffer,
+            md5,
+            name: name || 'buffer.dat',
+            type: FileBoxType.Buffer,
+        };
+        return new this(options);
+    }
+    /**
+     * @param base64
+     * @param name the file name of the base64 data
+     */
+    static fromBase64(base64, name, md5) {
+        const options = {
+            base64,
+            md5,
+            name: name || 'base64.dat',
+            type: FileBoxType.Base64,
+        };
+        return new this(options);
+    }
+    /**
+     * dataURL: `data:image/png;base64,${base64Text}`,
+     */
+    static fromDataURL(dataUrl, name, md5) {
+        return this.fromBase64(dataUrlToBase64(dataUrl), name || 'data-url.dat', md5);
+    }
+    /**
+     *
+     * @param qrCode the value of the QR Code. For example: `https://github.com`
+     */
+    static fromQRCode(qrCode, md5) {
+        const options = {
+            md5,
+            name: 'qrcode.png',
+            qrCode,
+            type: FileBoxType.QRCode,
+        };
+        return new this(options);
+    }
+    static uuidToStream;
+    static uuidFromStream;
+    /**
+     * @param uuid the UUID of the file. For example: `6f88b03c-1237-4f46-8db2-98ef23200551`
+     * @param name the name of the file. For example: `video.mp4`
+     */
+    static fromUuid(uuid, nameOrOptions) {
+        let name;
+        let size;
+        let md5;
+        if (typeof nameOrOptions === 'object') {
+            name = nameOrOptions.name;
+            size = nameOrOptions.size;
+            md5 = nameOrOptions.md5;
+        }
+        else {
+            name = nameOrOptions;
+        }
+        const options = {
+            md5,
+            name: name || `${uuid}.dat`,
+            size,
+            type: FileBoxType.Uuid,
+            uuid,
+        };
+        return new this(options);
+    }
+    /**
+     * UUID Type FielBox Loader
+     */
+    static setUuidLoader(loader) {
+        if (Object.prototype.hasOwnProperty.call(this, 'uuidToStream')) {
+            throw new Error('this FileBox has been set resolver before, can not set twice');
+        }
+        this.uuidToStream = loader;
+    }
+    /**
+     * UUID Type FielBox Saver
+     */
+    static setUuidSaver(saver) {
+        if (Object.prototype.hasOwnProperty.call(this, 'uuidFromStream')) {
+            throw new Error('this FileBox has been set register before, can not set twice');
+        }
+        this.uuidFromStream = saver;
+    }
+    /**
+     *
+     * @static
+     * @param {(FileBoxJsonObject | string)} obj
+     * @returns {FileBox}
+     */
+    static fromJSON(obj) {
+        if (typeof obj === 'string') {
+            obj = JSON.parse(obj);
+        }
+        /**
+         * Huan(202111): compatible with old FileBox.toJSON() key: `boxType`
+         *  this is a breaking change made by v1.0
+         *
+         *  convert `obj.boxType` to `obj.type`
+         *  (will be removed after Dec 31, 2022)
+         */
+        if (!obj.type && 'boxType' in obj) {
+            obj.type = obj['boxType'];
+        }
+        let fileBox;
+        switch (obj.type) {
+            case FileBoxType.Base64:
+                fileBox = this.fromBase64(obj.base64, obj.name, obj.md5);
+                break;
+            case FileBoxType.Url:
+                fileBox = this.fromUrl(obj.url, {
+                    md5: obj.md5,
+                    name: obj.name,
+                    size: obj.size,
+                });
+                break;
+            case FileBoxType.QRCode:
+                fileBox = this.fromQRCode(obj.qrCode, obj.md5);
+                break;
+            case FileBoxType.Uuid:
+                fileBox = this.fromUuid(obj.uuid, {
+                    md5: obj.md5,
+                    name: obj.name,
+                    size: obj.size,
+                });
+                break;
+            default:
+                throw new Error(`unknown filebox json object{type}: ${JSON.stringify(obj)}`);
+        }
+        if (obj.metadata) {
+            fileBox.metadata = obj.metadata;
+        }
+        return fileBox;
+    }
+    /**
+     *
+     * Instance Properties
+     *
+     */
+    version = VERSION;
+    /**
+     * We are using a getter for `type` is because
+     *  getter name can be enumurated by the `Object.hasOwnProperties()`*
+     *    but property name can not.
+     *
+     *  * required by `validInterface()`
+     */
+    _type;
+    get type() { return this._type; }
+    /**
+     * the Content-Length of the file
+     *  `SIZE_UNKNOWN(-1)` means unknown
+     *
+     * @example
+     * ```ts
+     * const fileBox = FileBox.fromUrl('http://example.com/image.png')
+     * await fileBox.ready()
+     * console.log(fileBox.size)
+     * // > 102400 <- this is the size of the remote image.png
+     * ```
+     */
+    _size;
+    get size() {
+        if (this._size) {
+            return this._size;
+        }
+        return UNKNOWN_SIZE;
+    }
+    /**
+     * File MD5 Sum
+     */
+    md5;
+    /**
+     * @deprecated: use `mediaType` instead. will be removed after Dec 31, 2022
+     */
+    mimeType = 'application/unknown';
+    /**
+     * (Internet) Media Type is the proper technical term of `MIME Type`
+     *  @see https://stackoverflow.com/a/9277778/1123955
+     *
+     * @example 'text/plain'
+     */
+    _mediaType;
+    get mediaType() {
+        if (this._mediaType) {
+            return this._mediaType;
+        }
+        return 'application/unknown';
+    }
+    _name;
+    get name() {
+        return this._name;
+    }
+    _metadata;
+    get metadata() {
+        if (this._metadata) {
+            return this._metadata;
+        }
+        return EMPTY_META_DATA;
+    }
+    set metadata(data) {
+        if (this._metadata) {
+            throw new Error('metadata can not be modified after set');
+        }
+        this._metadata = { ...data };
+        Object.freeze(this._metadata);
+    }
+    /**
+     * Lazy load data: (can be serialized to JSON)
+     *  Do not read file to Buffer until there's a consumer.
+     */
+    base64;
+    remoteUrl;
+    qrCode;
+    uuid;
+    /**
+     * Can not be serialized to JSON
+     */
+    buffer;
+    localPath;
+    stream;
+    headers;
+    constructor(options) {
+        // Only keep `basename` in this.name
+        this._name = PATH.basename(options.name);
+        this._type = options.type;
+        /**
+         * Unknown file type MIME: `'application/unknown'`
+         *  @see https://stackoverflow.com/a/6080707/1123955
+         */
+        this._mediaType = mime.getType(this.name) ?? undefined;
+        this.md5 = options.md5;
+        switch (options.type) {
+            case FileBoxType.Buffer:
+                this.buffer = options.buffer;
+                this._size = options.buffer.length;
+                break;
+            case FileBoxType.File:
+                if (!options.path) {
+                    throw new Error('no path');
+                }
+                this.localPath = options.path;
+                this._size = FS.statSync(this.localPath).size;
+                break;
+            case FileBoxType.Url:
+                if (!options.url) {
+                    throw new Error('no url');
+                }
+                this.remoteUrl = options.url;
+                if (options.headers) {
+                    this.headers = options.headers;
+                }
+                if (options.size) {
+                    this._size = options.size;
+                }
+                else {
+                    /**
+                     * Add a background task to fetch remote file name & size
+                     *
+                     * TODO: how to improve it?
+                     */
+                    // this.syncUrlMetadata().catch(console.error)
+                }
+                break;
+            case FileBoxType.Stream:
+                this.stream = options.stream;
+                if (options.size) {
+                    this._size = options.size;
+                }
+                break;
+            case FileBoxType.QRCode:
+                if (!options.qrCode) {
+                    throw new Error('no QR Code');
+                }
+                this.qrCode = options.qrCode;
+                break;
+            case FileBoxType.Base64:
+                if (!options.base64) {
+                    throw new Error('no Base64 data');
+                }
+                this.base64 = options.base64;
+                this._size = Buffer.byteLength(options.base64, 'base64');
+                break;
+            case FileBoxType.Uuid:
+                if (!options.uuid) {
+                    throw new Error('no UUID data');
+                }
+                this.uuid = options.uuid;
+                if (options.size) {
+                    this._size = options.size;
+                }
+                break;
+            default:
+                throw new Error(`unknown options(type): ${JSON.stringify(options)}`);
+        }
+    }
+    async ready() {
+        switch (this.type) {
+            case FileBoxType.Url:
+                await this._syncUrlMetadata();
+                break;
+            case FileBoxType.QRCode:
+                if (this.size === UNKNOWN_SIZE) {
+                    this._size = (await this.toBuffer()).length;
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    /**
+     * @todo use http.get/gets instead of Request
+     */
+    async _syncUrlMetadata() {
+        /**
+         * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition
+         *  > Content-Disposition: attachment; filename="cool.html"
+         */
+        if (this.type !== FileBoxType.Url) {
+            throw new Error('type is not Url');
+        }
+        if (!this.remoteUrl) {
+            throw new Error('no url');
+        }
+        const headers = await httpHeadHeader(this.remoteUrl);
+        const httpFilename = httpHeaderToFileName(headers);
+        if (httpFilename) {
+            this._name = httpFilename;
+        }
+        if (!this.name) {
+            throw new Error('NONAME');
+        }
+        const httpMediaType = headers['content-type'] || (httpFilename && mime.getType(httpFilename));
+        if (httpMediaType) {
+            this._mediaType = httpMediaType;
+        }
+        if (headers['content-length']) {
+            this._size = Number(headers['content-length']);
+        }
+    }
+    /**
+     *
+     * toXXX methods
+     *
+     */
+    toString() {
+        return [
+            'FileBox#',
+            FileBoxType[this.type],
+            '<',
+            this.name,
+            '>',
+        ].join('');
+    }
+    toJSON() {
+        const objCommon = {
+            md5: this.md5,
+            metadata: this.metadata,
+            name: this.name,
+        };
+        if (typeof this.size !== 'undefined') {
+            objCommon.size = this.size;
+        }
+        let obj;
+        switch (this.type) {
+            case FileBoxType.Url: {
+                if (!this.remoteUrl) {
+                    throw new Error('no url');
+                }
+                const objUrl = {
+                    headers: this.headers,
+                    type: FileBoxType.Url,
+                    url: this.remoteUrl,
+                };
+                obj = {
+                    ...objCommon,
+                    ...objUrl,
+                };
+                break;
+            }
+            case FileBoxType.QRCode: {
+                if (!this.qrCode) {
+                    throw new Error('no qr code');
+                }
+                const objQRCode = {
+                    qrCode: this.qrCode,
+                    type: FileBoxType.QRCode,
+                };
+                obj = {
+                    ...objCommon,
+                    ...objQRCode,
+                };
+                break;
+            }
+            case FileBoxType.Base64: {
+                if (!this.base64) {
+                    throw new Error('no base64 data');
+                }
+                const objBase64 = {
+                    base64: this.base64,
+                    type: FileBoxType.Base64,
+                };
+                obj = {
+                    ...objCommon,
+                    ...objBase64,
+                };
+                break;
+            }
+            case FileBoxType.Uuid: {
+                if (!this.uuid) {
+                    throw new Error('no uuid data');
+                }
+                const objUuid = {
+                    type: FileBoxType.Uuid,
+                    uuid: this.uuid,
+                };
+                obj = {
+                    ...objCommon,
+                    ...objUuid,
+                };
+                break;
+            }
+            default:
+                void this.type;
+                throw new Error('FileBox.toJSON() can only work on limited FileBoxType(s). See: <https://github.com/huan/file-box/issues/25>');
+        }
+        /**
+         * Huan(202111): compatible with old FileBox.toJSON() key: `boxType`
+         *  this is a breaking change made by v1.0
+         *
+         *  save `obj.type` a copy to `obj.boxType`
+         *  (will be removed after Dec 31, 2022)
+         */
+        obj['boxType'] = obj.type;
+        return obj;
+    }
+    async toStream() {
+        let stream;
+        switch (this.type) {
+            case FileBoxType.Buffer:
+                stream = this._transformBufferToStream();
+                break;
+            case FileBoxType.File:
+                stream = this._transformFileToStream();
+                break;
+            case FileBoxType.Url:
+                stream = await this._transformUrlToStream();
+                break;
+            case FileBoxType.Stream:
+                if (!this.stream) {
+                    throw new Error('no stream');
+                }
+                /**
+                  * Huan(202109): the stream.destroyed will not be `true`
+                  *   when we have read all the data
+                  *   after we change some code.
+                  * The reason is unbase64 : this.base64,
+                  type   : FileBoxType.Base64,known... so we change to check `readable`
+                  */
+                if (!this.stream.readable) {
+                    throw new Error('The stream is not readable. Maybe has already been consumed, and now it was drained. See: https://github.com/huan/file-box/issues/50');
+                }
+                stream = this.stream;
+                break;
+            case FileBoxType.QRCode:
+                if (!this.qrCode) {
+                    throw new Error('no QR Code');
+                }
+                stream = await this._transformQRCodeToStream();
+                break;
+            case FileBoxType.Base64:
+                if (!this.base64) {
+                    throw new Error('no base64 data');
+                }
+                stream = this._transformBase64ToStream();
+                break;
+            case FileBoxType.Uuid: {
+                if (!this.uuid) {
+                    throw new Error('no uuid data');
+                }
+                const FileBoxKlass = instanceToClass(this, FileBox);
+                if (!FileBoxKlass.uuidToStream) {
+                    throw new Error('need to call FileBox.setUuidLoader() to set UUID loader first.');
+                }
+                stream = await FileBoxKlass.uuidToStream.call(this, this.uuid);
+                break;
+            }
+            default:
+                throw new Error('not supported FileBoxType: ' + FileBoxType[this.type]);
+        }
+        return stream;
+    }
+    /**
+     * https://stackoverflow.com/a/16044400/1123955
+     */
+    _transformBufferToStream(buffer) {
+        const bufferStream = new PassThrough();
+        bufferStream.end(buffer || this.buffer);
+        /**
+         * Use small `chunks` with `toStream()` #44
+         * https://github.com/huan/file-box/issues/44
+         */
+        return bufferStream.pipe(sizedChunkTransformer());
+    }
+    _transformBase64ToStream() {
+        if (!this.base64) {
+            throw new Error('no base64 data');
+        }
+        const buffer = Buffer.from(this.base64, 'base64');
+        return this._transformBufferToStream(buffer);
+    }
+    _transformFileToStream() {
+        if (!this.localPath) {
+            throw new Error('no url(path)');
+        }
+        return FS.createReadStream(this.localPath);
+    }
+    async _transformUrlToStream() {
+        return new Promise((resolve, reject) => {
+            if (this.remoteUrl) {
+                httpStream(this.remoteUrl, this.headers)
+                    .then(resolve)
+                    .catch(reject);
+            }
+            else {
+                reject(new Error('no url'));
+            }
+        });
+    }
+    async _transformQRCodeToStream() {
+        if (!this.qrCode) {
+            throw new Error('no QR Code Value found');
+        }
+        const stream = qrValueToStream(this.qrCode);
+        return stream;
+    }
+    /**
+     * save file
+     *
+     * @param filePath save file
+     */
+    async toFile(filePath, overwrite = false) {
+        if (this.type === FileBoxType.Url) {
+            if (!this.mediaType || !this.name) {
+                await this._syncUrlMetadata();
+            }
+        }
+        const fullFilePath = PATH.resolve(filePath || this.name);
+        const exist = FS.existsSync(fullFilePath);
+        if (exist && !overwrite) {
+            throw new Error(`FileBox.toFile(${fullFilePath}): file exist. use FileBox.toFile(${fullFilePath}, true) to force overwrite.`);
+        }
+        const writeStream = FS.createWriteStream(fullFilePath);
+        /**
+          * Huan(202109): make sure the file can be opened for writting
+          *   before we pipe the stream to it
+          */
+        await new Promise((resolve, reject) => writeStream
+            .once('open', resolve)
+            .once('error', reject));
+        /**
+          * Start pipe
+          */
+        await new Promise((resolve, reject) => {
+            writeStream
+                .once('close', resolve)
+                .once('error', reject);
+            this.pipe(writeStream);
+        });
+    }
+    async toBase64() {
+        if (this.type === FileBoxType.Base64) {
+            if (!this.base64) {
+                throw new Error('no base64 data');
+            }
+            return this.base64;
+        }
+        const buffer = await this.toBuffer();
+        return buffer.toString('base64');
+    }
+    /**
+     * dataUrl: `data:image/png;base64,${base64Text}',
+     */
+    async toDataURL() {
+        const base64Text = await this.toBase64();
+        if (!this.mediaType) {
+            throw new Error('no mediaType found');
+        }
+        const dataUrl = [
+            'data:',
+            this.mediaType,
+            ';base64,',
+            base64Text,
+        ].join('');
+        return dataUrl;
+    }
+    async toBuffer() {
+        if (this.type === FileBoxType.Buffer) {
+            if (!this.buffer) {
+                throw new Error('no buffer!');
+            }
+            return this.buffer;
+        }
+        const stream = new PassThrough();
+        this.pipe(stream);
+        const buffer = await streamToBuffer(stream);
+        return buffer;
+    }
+    async toQRCode() {
+        if (this.type === FileBoxType.QRCode) {
+            if (!this.qrCode) {
+                throw new Error('no QR Code!');
+            }
+            return this.qrCode;
+        }
+        const buf = await this.toBuffer();
+        const qrValue = await bufferToQrValue(buf);
+        return qrValue;
+    }
+    async toUuid() {
+        if (this.type === FileBoxType.Uuid) {
+            if (!this.uuid) {
+                throw new Error('no uuid found for a UUID type file box!');
+            }
+            return this.uuid;
+        }
+        const FileBoxKlass = instanceToClass(this, FileBox);
+        if (!FileBoxKlass.uuidFromStream) {
+            throw new Error('need to use FileBox.setUuidSaver() before dealing with UUID');
+        }
+        const stream = new PassThrough();
+        this.pipe(stream);
+        return FileBoxKlass.uuidFromStream.call(this, stream);
+    }
+    /**
+     *
+     * toXXX methods END
+     *
+     */
+    pipe(destination) {
+        this.toStream()
+            .then(stream => {
+            stream.on('error', e => {
+                destination.emit('error', e);
+            });
+            return stream.pipe(destination);
+        })
+            .catch(e => destination.emit('error', e));
+        return destination;
+    }
+}
+/**
+ * Huan(202110): lazy initialize `interfaceOfClass(FileBox)`
+ *  because we only can reference a class after its declaration
+ */
+interfaceOfFileBox = interfaceOfClass(FileBox)();
+looseInstanceOfFileBox = looseInstanceOfClass(FileBox);
+export { FileBox, };
+//# sourceMappingURL=file-box.js.map