@npcz/magic/dist/file-magic.d.ts

Emscripten port of libmagic (https://darwinsys.com/file/) with javascript interface

/**
 * Reproduces exactly the same values than in magic.h of libmagic but using
 * a much more type safe enum.
 */
export declare enum MagicFlags {
    /** No flags */
    MAGIC_NONE = 0,
    /** Turn on debugging */
    MAGIC_DEBUG = 1,
    /** Follow symlinks */
    MAGIC_SYMLINK = 2,
    /** Check inside compressed files */
    MAGIC_COMPRESS = 4,
    /** Look at the contents of devices */
    MAGIC_DEVICES = 4,
    /** Return the MIME type */
    MAGIC_MIME_TYPE = 16,
    /** Return all matches */
    MAGIC_CONTINUE = 32,
    /** Print warnings to stderr */
    MAGIC_CHECK = 64,
    /** Restore access time on exit - should only be used on systems that support it */
    MAGIC_PRESERVE_ATIME = 128,
    /** Don't convert unprintable chars */
    MAGIC_RAW = 256,
    /** Handle ENOENT etc as real errors */
    MAGIC_ERROR = 512,
    /** Return the MIME encoding */
    MAGIC_MIME_ENCODING = 1024,
    /** Return both the mime type and the encoding */
    MAGIC_MIME = 1040,
    /** Return the Apple creator/type */
    MAGIC_APPLE = 2048,
    /** Return a /-separated list of extensions */
    MAGIC_EXTENSION = 16777216,
    /** Check inside compressed files but not report compression */
    MAGIC_COMPRESS_TRANSP = 33554432,
    /** Equivalent to MAGIC_EXTENSION|MAGIC_MIME|MAGIC_APPLE  */
    MAGIC_NODESC = 16780304,
    /** Don't check for compressed files */
    MAGIC_NO_CHECK_COMPRESS = 4096,
    /** Don't check for tar files */
    MAGIC_NO_CHECK_TAR = 8192,
    /** Don't check magic entries */
    MAGIC_NO_CHECK_SOFT = 16384,
    /** Don't check application type */
    MAGIC_NO_CHECK_APPTYPE = 32768,
    /** Don't check for elf details */
    MAGIC_NO_CHECK_ELF = 65536,
    /** Don't check for text files */
    MAGIC_NO_CHECK_TEXT = 131072,
    /** Don't check for cdf files */
    MAGIC_NO_CHECK_CDF = 262144,
    /** Don't check for CSV files */
    MAGIC_NO_CHECK_CSV = 524288,
    /** Don't check tokens */
    MAGIC_NO_CHECK_TOKENS = 1048576,
    /** Don't check text encodings */
    MAGIC_NO_CHECK_ENCODING = 2097152,
    /** Don't check for JSON files */
    MAGIC_NO_CHECK_JSON = 4194304,
    /** No built-in tests; only consult the magic file */
    MAGIC_NO_CHECK_BUILTIN = 8368128
}
/**
 * Enhanced interface to the libmagic binding.
 */
export declare class FileMagic {
    /**
     * Path to the magic file.
     *
     * Can only be (and should be) changed before the first call to getInstance().
     *
     * This path must be correct and pointing to the location of the magic.mgc file.
     * By default, it is expected to be in the current script working directory.
     */
    static magicFile: string;
    /**
     * Default flags used by libmagic binding.
     *
     * These flags can customize the behavior of file type detection. The
     * default flags can be changed only before the first call to the
     * getInstance() method. After that, detection can always be customized
     * by providing specific flags to the detect() method.
     */
    static defaultFlags: MagicFlags;
    /**
     * The single instance of FileMagic.
     */
    private static _instance;
    /**
     * The binding static interface.
     */
    private static _binding;
    /**
     * The binding instance interface.
     */
    private _magic;
    /**
     * Private constructor to prevent creation of instances of this class
     * except through the getInstance() method.
     */
    private constructor();
    /**
     * Get the single instance of FileMagic.
     *
     * This method can be called as many times as needed to obtain the single
     * instance of FileMagic. During the first call, libmagic binding is
     * initialized using the magic file path and the flags current values
     * respectively in the magicFile and flags properties.
     *
     * @param locateFile custom function to locate the WASM file. This is
     * particularly helpful when the wasm file is moved away from the js
     * binding file or when it needs to be fetched via http.
     * @return a Promise of the single instance of FileMagic that resolves
     * after the binding is properly initialized, or rejects with an Error
     * when it fails.
     */
    static getInstance(locateFile?: (wasmFile: string, dir: string) => string): Promise<FileMagic>;
    /**
     * Get the flags currently used in the libmagic binding.
     *
     * These flags are a property of the class and therefore apply to all
     * instances of the binding created by calling new binding.MagicBinding().
     * They are set when calling the init() method and can be overridden during
     * the detect call.
     *
     * @example<caption>Making multiple detect calls with different flags</caption>
     * magic.detect(file, binding.MagicBinding.flags() | binding.MAGIC_MIME)
     *
     * @return the flags set for the binding instance.
     * @throws Error when used after the binding is closed.
     * @see init
     * @see detect
     */
    get flags(): MagicFlags;
    /**
     * Get the version of libmagic.
     *
     * @returns The version of libmagic, e.g. 835.
     * @throws Error when used after the binding is closed.
     */
    version(): number;
    /**
     * Destroy the binding and release any resources it was holding (e.g. memory,
     * file descriptors, etc...).
     *
     * This method must be called when the binding is no longer needed. After it
     * has been called, the binding can no longer be used and a new instance must
     * be created.
     */
    static close(): void;
    /**
     * Run libmagic detection for the given file to produce a description of
     * its content.
     *
     * There are three sets of tests, performed in this order: filesystem tests,
     * magic tests, and language tests. The first test that succeeds causes the
     * detection to complete.
     *
     * The detection result will usually contain one of the words *text* (the
     * file contains only printing characters and a few com-mon control characters
     * and is probably safe to read on an ASCII terminal), *executable* (the
     * file an executable file understandable by whatever operating system it was
     * made for), or *data* meaning anything else (data is usually ``binary'' or
     * non-printable).
     *
     * The filesystem tests are based on examining the return from a stat(2) system
     * call.  The library checks to see if the file is empty, or if it's some sort
     * of special file (sockets, symbolic links, or named pipes (FIFOs) on those
     * systems that implement them).
     *
     * The magic tests are used to check for files with data in particular fixed
     * formats.  The canonical example of this is a binary executable file. These
     * files have a ``magic number'' stored in a particular place near the beginning
     * of the file. The concept of a *'magic'* has been applied by extension to data
     * files.  Any file with some invariant identifier at a small fixed offset into
     * the file can usually be described in this way.  The information identifying
     * these files is read from the compiled magic file.
     *
     * If a file does not match any of the entries in the magic file, it is examined
     * to see if it seems to be a text file and identify the character set it uses.
     * Any file that cannot be identified as having been written in any of the character
     * sets known to libmagic is simply said to be *'data'*.
     *
     * @param path path the file to be detected.
     * @param flags specific flags to be used for this detection request. To use
     * the default flags for the binding, pass -1;
     * @return a string containing the detection result (type description, mime type,
     * mime encoding, etc...) when successful.
     * @throws Error with an error message when the detection fails or when used
     * after the binding is closed.
     */
    detect(path: string, flags?: MagicFlags): string;
    /**
     * Run libmagic detection for the given file to produce a string with the
     * mime type corresponding to its content.
     *
     * @param path path the file to be detected.
     * @return a string containing the mime type of the file contents (e.g.
     * text/plain) when successful.
     * @throws Error with an error message when the detection fails or when used
     * after the binding is closed.
     * @see detect
     */
    detectMimeType(path: string): string;
    /**
     * Run libmagic detection for the given file to produce a string with the
     * mime encoding corresponding to its content.
     *
     * @param path path the file to be detected.
     * @return a string containing the mime type of the file contents (e.g.
     * charset=us-ascii) when successful.
     * @throws Error with an error message when the detection fails or when used
     * after the binding is closed.
     * @see detect
     */
    detectMimeEncoding(path: string): string;
    /**
     * Run libmagic detection for the given file to produce a string with the
     * mime type and encoding corresponding to its content.
     *
     * @param path path the file to be detected.
     * @return a string containing the mime type of the file contents (e.g.
     * text/plain; charset=us-ascii) when successful.
     * @throws Error with an error message when the detection fails or when used
     * after the binding is closed.
     * @see detect
     */
    detectMime(path: string): string;
}