file-type

  • Version 20.0.0
  • Published
  • 102 kB
  • 4 dependencies
  • MIT license

Install

npm i file-type
yarn add file-type
pnpm add file-type

Overview

Detect the file type of a file, stream, or data

Index

Variables

variable supportedExtensions

const supportedExtensions: ReadonlySet<string>;
  • Supported file extensions.

variable supportedMimeTypes

const supportedMimeTypes: ReadonlySet<string>;
  • Supported MIME types.

Functions

function fileTypeFromBlob

fileTypeFromBlob: (blob: Blob) => Promise<FileTypeResult | undefined>;
  • Detect the file type of a [Blob](https://nodejs.org/api/buffer.html#class-blob) or [File](https://developer.mozilla.org/en-US/docs/Web/API/File).

    Parameter blob

    The [Blob](https://nodejs.org/api/buffer.html#class-blob) used for file detection.

    Returns

    The detected file type, or undefined when there is no match.

    Example 1

    import {fileTypeFromBlob} from 'file-type';
    const blob = new Blob(['<?xml version="1.0" encoding="ISO-8859-1" ?>'], {
    type: 'text/plain',
    endings: 'native'
    });
    console.log(await fileTypeFromBlob(blob));
    //=> {ext: 'txt', mime: 'text/plain'}

function fileTypeFromBuffer

fileTypeFromBuffer: (
buffer: Uint8Array | ArrayBuffer
) => Promise<FileTypeResult | undefined>;
  • Detect the file type of a Uint8Array, or ArrayBuffer.

    The file type is detected by checking the [magic number](https://en.wikipedia.org/wiki/Magic_number_(programming)#Magic_numbers_in_files) of the buffer.

    If file access is available, it is recommended to use .fromFile() instead.

    Parameter buffer

    An Uint8Array or ArrayBuffer representing file data. It works best if the buffer contains the entire file. It may work with a smaller portion as well.

    Returns

    The detected file type, or undefined when there is no match.

function fileTypeFromFile

fileTypeFromFile: (
filePath: string,
options?: { customDetectors?: Iterable<Detector> }
) => Promise<FileTypeResult | undefined>;
  • Detect the file type of a file path.

    The file type is detected by checking the [magic number](https://en.wikipedia.org/wiki/Magic_number_(programming)#Magic_numbers_in_files) of the file.

    This is for Node.js only.

    To read from a [File](https://developer.mozilla.org/docs/Web/API/File), see fileTypeFromBlob().

    The file type is detected by checking the [magic number](https://en.wikipedia.org/wiki/Magic_number_(programming)#Magic_numbers_in_files) of the buffer.

    Returns

    The detected file type and MIME type or undefined when there is no match.

function fileTypeFromStream

fileTypeFromStream: (
stream: AnyWebReadableStream<Uint8Array> | NodeReadableStream
) => Promise<FileTypeResult | undefined>;
  • Detect the file type of a [web ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).

    If the engine is Node.js, this may also be a [Node.js stream.Readable](https://nodejs.org/api/stream.html#stream_class_stream_readable).

    Direct support for Node.js streams will be dropped in the future, when Node.js streams can be converted to Web streams (see [toWeb()](https://nodejs.org/api/stream.html#streamreadabletowebstreamreadable-options)).

    The file type is detected by checking the [magic number](https://en.wikipedia.org/wiki/Magic_number_(programming)#Magic_numbers_in_files) of the buffer.

    Parameter stream

    A [web ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [Node.js stream.Readable](https://nodejs.org/api/stream.html#stream_class_stream_readable) streaming a file to examine.

    Returns

    A Promise for an object with the detected file type, or undefined when there is no match.

function fileTypeFromTokenizer

fileTypeFromTokenizer: (
tokenizer: ITokenizer
) => Promise<FileTypeResult | undefined>;
  • Detect the file type from an [ITokenizer](https://github.com/Borewit/strtok3#tokenizer) source.

    This method is used internally, but can also be used for a special "tokenizer" reader.

    A tokenizer propagates the internal read functions, allowing alternative transport mechanisms, to access files, to be implemented and used.

    Parameter tokenizer

    File source implementing the tokenizer interface.

    Returns

    The detected file type, or undefined when there is no match.

    An example is [@tokenizer/http](https://github.com/Borewit/tokenizer-http), which requests data using [HTTP-range-requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests). A difference with a conventional stream and the [*tokenizer*](https://github.com/Borewit/strtok3#tokenizer), is that it is able to *ignore* (seek, fast-forward) in the stream. For example, you may only need and read the first 6 bytes, and the last 128 bytes, which may be an advantage in case reading the entire file would take longer.

    Example 1

    import {makeTokenizer} from '@tokenizer/http';
    import {fileTypeFromTokenizer} from 'file-type';
    const audioTrackUrl = 'https://test-audio.netlify.com/Various%20Artists%20-%202009%20-%20netBloc%20Vol%2024_%20tiuqottigeloot%20%5BMP3-V2%5D/01%20-%20Diablo%20Swing%20Orchestra%20-%20Heroines.mp3';
    const httpTokenizer = await makeTokenizer(audioTrackUrl);
    const fileType = await fileTypeFromTokenizer(httpTokenizer);
    console.log(fileType);
    //=> {ext: 'mp3', mime: 'audio/mpeg'}

function fileTypeStream

fileTypeStream: {
(
readableStream: NodeReadableStream,
options?: StreamOptions
): Promise<ReadableStreamWithFileType>;
(webStream: AnyWebByteStream, options?: StreamOptions): Promise<any>;
};
  • Returns a Promise which resolves to the original readable stream argument, but with an added fileType property, which is an object like the one returned from fileTypeFromFile().

    This method can be handy to put in between a stream, but it comes with a price. Internally stream() builds up a buffer of sampleSize bytes, used as a sample, to determine the file type. The sample size impacts the file detection resolution. A smaller sample size will result in lower probability of the best file type detection.

    Parameter readableStream

    A [web ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) or [Node.js stream.Readable](https://nodejs.org/api/stream.html#stream_class_stream_readable), streaming a file to examine.

    Parameter options

    May be used to override the default sample size.

    Returns

    A Promise which resolves to the original readable stream argument, but with an added fileType property, which is an object like the one returned from fileTypeFromFile().

    Example 1

    import got from 'got';
    import {fileTypeStream} from 'file-type';
    const url = 'https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg';
    const stream1 = got.stream(url);
    const stream2 = await fileTypeStream(stream1, {sampleSize: 1024});
    if (stream2.fileType?.mime === 'image/jpeg') {
    // stream2 can be used to stream the JPEG image (from the very beginning of the stream)
    }

Classes

class FileTypeParser

class FileTypeParser extends DefaultFileTypeParser {}
  • Extending FileTypeParser with Node.js engine specific functions.

method fromFile

fromFile: (filePath: string) => Promise<FileTypeResult | undefined>;

    method fromStream

    fromStream: (
    stream: AnyWebReadableStream<Uint8Array> | NodeReadableStream
    ) => Promise<FileTypeResult | undefined>;
    • Parameter stream

      Node.js stream.Readable or web ReadableStream.

    method toDetectionStream

    toDetectionStream: {
    (
    readableStream: NodeReadableStream,
    options?: StreamOptions
    ): Promise<ReadableStreamWithFileType>;
    (webStream: any, options?: StreamOptions): Promise<any>;
    };
    • Works the same way as fileTypeStream, additionally taking into account custom detectors (if any were provided to the constructor).

    class TokenizerPositionError

    class TokenizerPositionError extends Error {}

      constructor

      constructor(message?: string);

        Type Aliases

        type AnyWebReadableByteStreamWithFileType

        type AnyWebReadableByteStreamWithFileType = AnyWebReadableStream<Uint8Array> & {
        readonly fileType?: FileTypeResult;
        };

          type AnyWebReadableStream

          type AnyWebReadableStream<G> = WebReadableStream<G> | ReadableStream<G>;
          • Either the Node.js ReadableStream or the lib.dom.d.ts ReadableStream. Related issue: https://github.com/DefinitelyTyped/DefinitelyTyped/pull/60377

          type Detector

          type Detector = {
          id: string;
          detect: (
          tokenizer: ITokenizer,
          fileType?: FileTypeResult
          ) => Promise<FileTypeResult | undefined>;
          };
          • A custom file type detector.

            Detectors can be added via the constructor options or by directly modifying FileTypeParser#detectors.

            Detectors provided through the constructor options are executed before the default detectors.

            Custom detectors allow for: - Introducing new FileTypeResult entries. - Modifying the detection behavior of existing FileTypeResult types.

            ### Detector execution flow

            If a detector returns undefined, the following rules apply:

            1. **No Tokenizer Interaction**: If the detector does not modify the tokenizer's position, the next detector in the sequence is executed. 2. **Tokenizer Interaction**: If the detector modifies the tokenizer's position (tokenizer.position is advanced), no further detectors are executed. In this case, the file type remains undefined, as subsequent detectors cannot evaluate the content. This is an exceptional scenario, as it prevents any other detectors from determining the file type.

            ### Example usage

            Below is an example of a custom detector array. This can be passed to the FileTypeParser via the fileTypeOptions argument.

            import {FileTypeParser} from 'file-type';
            const customDetectors = [
            async tokenizer => {
            const unicornHeader = [85, 78, 73, 67, 79, 82, 78]; // "UNICORN" in ASCII decimal
            const buffer = new Uint8Array(unicornHeader.length);
            await tokenizer.peekBuffer(buffer, {length: unicornHeader.length, mayBeLess: true});
            if (unicornHeader.every((value, index) => value === buffer[index])) {
            return {ext: 'unicorn', mime: 'application/unicorn'};
            }
            return undefined;
            },
            ];
            const buffer = new Uint8Array([85, 78, 73, 67, 79, 82, 78]);
            const parser = new FileTypeParser({customDetectors});
            const fileType = await parser.fromBuffer(buffer);
            console.log(fileType); // {ext: 'unicorn', mime: 'application/unicorn'}

            Parameter tokenizer

            The [tokenizer](https://github.com/Borewit/strtok3#tokenizer) used to read file content.

            Parameter fileType

            The file type detected by standard or previous custom detectors, or undefined if no match is found.

            Returns

            The detected file type, or undefined if no match is found.

          type FileTypeOptions

          type FileTypeOptions = {
          customDetectors?: Iterable<Detector>;
          };

            type FileTypeResult

            type FileTypeResult = {
            /**
            One of the supported [file types](https://github.com/sindresorhus/file-type#supported-file-types).
            */
            readonly ext: string;
            /**
            The detected [MIME type](https://en.wikipedia.org/wiki/Internet_media_type).
            */
            readonly mime: string;
            };

              type ReadableStreamWithFileType

              type ReadableStreamWithFileType = NodeReadableStream & {
              readonly fileType?: FileTypeResult;
              };

                type StreamOptions

                type StreamOptions = {
                /**
                The default sample size in bytes.
                @default 4100
                */
                readonly sampleSize?: number;
                };

                  Package Files (2)

                  Dependencies (4)

                  Dev Dependencies (8)

                  Peer Dependencies (0)

                  No peer dependencies.

                  Badge

                  To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                  You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/file-type.

                  • Markdown
                    [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/file-type)
                  • HTML
                    <a href="https://www.jsdocs.io/package/file-type"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>