@juzi/file-box 1.7.0

package/dist/cjs/src/file-box.d.ts

@@ -0,0 +1,209 @@
+/**
+ * File Box
+ * https://github.com/huan/file-box
+ *
+ * 2018 Huan LI <zixia@zixia.net>
+ */
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import type * as HTTP from 'http';
+import { Readable, Writable } from 'stream';
+import { FileBoxJsonObject, FileBoxOptions, FileBoxType, Metadata, Pipeable, UuidLoader, UuidSaver } from './file-box.type.js';
+import type { FileBoxInterface } from './interface.js';
+declare class FileBox implements Pipeable, FileBoxInterface {
+    /**
+     *
+     * Static Properties
+     *
+     */
+    static readonly version: string;
+    /**
+     * Symbol.hasInstance: instanceof
+     *
+     * @link https://www.keithcirkel.co.uk/metaprogramming-in-es6-symbols/
+     */
+    static [Symbol.hasInstance](lho: any): lho is FileBoxInterface;
+    /**
+     * Check if obj satisfy FileBox interface
+     */
+    static valid(target: any): target is FileBoxInterface;
+    /**
+     * Check if obj satisfy FileBox interface
+     */
+    static validInterface(target: any): target is FileBoxInterface;
+    /**
+     * loose check instance of FileBox
+     */
+    static validInstance(target: any): target is FileBox;
+    static fromUrl(url: string, options?: {
+        headers?: HTTP.OutgoingHttpHeaders;
+        name?: string;
+        size?: number;
+        md5?: string;
+    }): FileBox;
+    /**
+     * @deprecated use `fromUrl(url, options)` instead
+     */
+    static fromUrl(url: string, name?: string, headers?: HTTP.OutgoingHttpHeaders): FileBox;
+    /**
+     * Alias for `FileBox.fromFile()`
+     *
+     * @alias fromFile
+     */
+    static fromFile(path: string, name?: string, md5?: string): FileBox;
+    /**
+     * TODO: add `FileBoxStreamOptions` with `size` support (@huan, 202111)
+     */
+    static fromStream(stream: Readable, name?: string, md5?: string): FileBox;
+    static fromBuffer(buffer: Buffer, name?: string, md5?: string): FileBox;
+    /**
+     * @param base64
+     * @param name the file name of the base64 data
+     */
+    static fromBase64(base64: string, name?: string, md5?: string): FileBox;
+    /**
+     * dataURL: `data:image/png;base64,${base64Text}`,
+     */
+    static fromDataURL(dataUrl: string, name?: string, md5?: string): FileBox;
+    /**
+     *
+     * @param qrCode the value of the QR Code. For example: `https://github.com`
+     */
+    static fromQRCode(qrCode: string, md5?: string): FileBox;
+    protected static uuidToStream?: UuidLoader;
+    protected static uuidFromStream?: UuidSaver;
+    static fromUuid(uuid: string, options?: {
+        name?: string;
+        size?: number;
+        md5?: string;
+    }): FileBox;
+    /**
+     * @deprecated use `fromUuid(name, options)` instead
+     */
+    static fromUuid(uuid: string, name?: string, md5?: string): FileBox;
+    /**
+     * UUID Type FielBox Loader
+     */
+    static setUuidLoader(loader: UuidLoader): void;
+    /**
+     * UUID Type FielBox Saver
+     */
+    static setUuidSaver(saver: UuidSaver): void;
+    /**
+     *
+     * @static
+     * @param {(FileBoxJsonObject | string)} obj
+     * @returns {FileBox}
+     */
+    static fromJSON(obj: FileBoxJsonObject | string): FileBox;
+    /**
+     *
+     * Instance Properties
+     *
+     */
+    readonly version: string;
+    /**
+     * 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()`
+     */
+    readonly _type: FileBoxType;
+    get type(): FileBoxType;
+    /**
+     * 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?: number;
+    get size(): number;
+    /**
+     * File MD5 Sum
+     */
+    readonly md5: undefined | string;
+    /**
+     * @deprecated: use `mediaType` instead. will be removed after Dec 31, 2022
+     */
+    mimeType: string;
+    /**
+     * (Internet) Media Type is the proper technical term of `MIME Type`
+     *  @see https://stackoverflow.com/a/9277778/1123955
+     *
+     * @example 'text/plain'
+     */
+    protected _mediaType?: string;
+    get mediaType(): string;
+    protected _name: string;
+    get name(): string;
+    protected _metadata?: Metadata;
+    get metadata(): Metadata;
+    set metadata(data: Metadata);
+    /**
+     * Lazy load data: (can be serialized to JSON)
+     *  Do not read file to Buffer until there's a consumer.
+     */
+    private readonly base64?;
+    private readonly remoteUrl?;
+    private readonly qrCode?;
+    private readonly uuid?;
+    /**
+     * Can not be serialized to JSON
+     */
+    private readonly buffer?;
+    private readonly localPath?;
+    private readonly stream?;
+    private readonly headers?;
+    constructor(options: FileBoxOptions);
+    ready(): Promise<void>;
+    /**
+     * @todo use http.get/gets instead of Request
+     */
+    protected _syncUrlMetadata(): Promise<void>;
+    /**
+     *
+     * toXXX methods
+     *
+     */
+    toString(): string;
+    toJSON(): FileBoxJsonObject;
+    toStream(): Promise<Readable>;
+    /**
+     * https://stackoverflow.com/a/16044400/1123955
+     */
+    private _transformBufferToStream;
+    private _transformBase64ToStream;
+    private _transformFileToStream;
+    private _transformUrlToStream;
+    private _transformQRCodeToStream;
+    /**
+     * save file
+     *
+     * @param filePath save file
+     */
+    toFile(filePath?: string, overwrite?: boolean): Promise<void>;
+    toBase64(): Promise<string>;
+    /**
+     * dataUrl: `data:image/png;base64,${base64Text}',
+     */
+    toDataURL(): Promise<string>;
+    toBuffer(): Promise<Buffer>;
+    toQRCode(): Promise<string>;
+    toUuid(): Promise<string>;
+    /**
+     *
+     * toXXX methods END
+     *
+     */
+    pipe<T extends Writable>(destination: T): T;
+}
+export { FileBox, };
+//# sourceMappingURL=file-box.d.ts.map

package/dist/cjs/src/file-box.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-box.d.ts","sourceRoot":"","sources":["../../../src/file-box.ts"],"names":[],"mappings":"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"}