file-type 16.5.4 → 21.3.4

package/core.d.ts

@@ -1,386 +1,253 @@
-/// <reference types="node"/>
-import {Readable as ReadableStream} from 'stream';
-import {ITokenizer} from 'strtok3/lib/core';
-
-declare namespace core {
-	type FileExtension =
-		| 'jpg'
-		| 'png'
-		| 'apng'
-		| 'gif'
-		| 'webp'
-		| 'flif'
-		| 'xcf'
-		| 'cr2'
-		| 'cr3'
-		| 'orf'
-		| 'arw'
-		| 'dng'
-		| 'nef'
-		| 'rw2'
-		| 'raf'
-		| 'tif'
-		| 'bmp'
-		| 'icns'
-		| 'jxr'
-		| 'psd'
-		| 'indd'
-		| 'zip'
-		| 'tar'
-		| 'rar'
-		| 'gz'
-		| 'bz2'
-		| '7z'
-		| 'dmg'
-		| 'mp4'
-		| 'mid'
-		| 'mkv'
-		| 'webm'
-		| 'mov'
-		| 'avi'
-		| 'mpg'
-		| 'mp2'
-		| 'mp3'
-		| 'm4a'
-		| 'ogg'
-		| 'opus'
-		| 'flac'
-		| 'wav'
-		| 'qcp'
-		| 'amr'
-		| 'pdf'
-		| 'epub'
-		| 'mobi'
-		| 'exe'
-		| 'swf'
-		| 'rtf'
-		| 'woff'
-		| 'woff2'
-		| 'eot'
-		| 'ttf'
-		| 'otf'
-		| 'ico'
-		| 'flv'
-		| 'ps'
-		| 'xz'
-		| 'sqlite'
-		| 'nes'
-		| 'crx'
-		| 'xpi'
-		| 'cab'
-		| 'deb'
-		| 'ar'
-		| 'rpm'
-		| 'Z'
-		| 'lz'
-		| 'cfb'
-		| 'mxf'
-		| 'mts'
-		| 'wasm'
-		| 'blend'
-		| 'bpg'
-		| 'docx'
-		| 'pptx'
-		| 'xlsx'
-		| '3gp'
-		| '3g2'
-		| 'jp2'
-		| 'jpm'
-		| 'jpx'
-		| 'mj2'
-		| 'aif'
-		| 'odt'
-		| 'ods'
-		| 'odp'
-		| 'xml'
-		| 'heic'
-		| 'cur'
-		| 'ktx'
-		| 'ape'
-		| 'wv'
-		| 'asf'
-		| 'dcm'
-		| 'mpc'
-		| 'ics'
-		| 'glb'
-		| 'pcap'
-		| 'dsf'
-		| 'lnk'
-		| 'alias'
-		| 'voc'
-		| 'ac3'
-		| 'm4b'
-		| 'm4p'
-		| 'm4v'
-		| 'f4a'
-		| 'f4b'
-		| 'f4p'
-		| 'f4v'
-		| 'mie'
-		| 'ogv'
-		| 'ogm'
-		| 'oga'
-		| 'spx'
-		| 'ogx'
-		| 'arrow'
-		| 'shp'
-		| 'aac'
-		| 'mp1'
-		| 'it'
-		| 's3m'
-		| 'xm'
-		| 'ai'
-		| 'skp'
-		| 'avif'
-		| 'eps'
-		| 'lzh'
-		| 'pgp'
-		| 'asar'
-		| 'stl'
-		| 'chm'
-		| '3mf'
-		| 'zst'
-		| 'jxl'
-		| 'vcf';
-
-	type MimeType =
-		| 'image/jpeg'
-		| 'image/png'
-		| 'image/gif'
-		| 'image/webp'
-		| 'image/flif'
-		| 'image/x-xcf'
-		| 'image/x-canon-cr2'
-		| 'image/x-canon-cr3'
-		| 'image/tiff'
-		| 'image/bmp'
-		| 'image/icns'
-		| 'image/vnd.ms-photo'
-		| 'image/vnd.adobe.photoshop'
-		| 'application/x-indesign'
-		| 'application/epub+zip'
-		| 'application/x-xpinstall'
-		| 'application/vnd.oasis.opendocument.text'
-		| 'application/vnd.oasis.opendocument.spreadsheet'
-		| 'application/vnd.oasis.opendocument.presentation'
-		| 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
-		| 'application/vnd.openxmlformats-officedocument.presentationml.presentation'
-		| 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
-		| 'application/zip'
-		| 'application/x-tar'
-		| 'application/x-rar-compressed'
-		| 'application/gzip'
-		| 'application/x-bzip2'
-		| 'application/x-7z-compressed'
-		| 'application/x-apple-diskimage'
-		| 'video/mp4'
-		| 'audio/midi'
-		| 'video/x-matroska'
-		| 'video/webm'
-		| 'video/quicktime'
-		| 'video/vnd.avi'
-		| 'audio/vnd.wave'
-		| 'audio/qcelp'
-		| 'audio/x-ms-asf'
-		| 'video/x-ms-asf'
-		| 'application/vnd.ms-asf'
-		| 'video/mpeg'
-		| 'video/3gpp'
-		| 'audio/mpeg'
-		| 'audio/mp4' // RFC 4337
-		| 'audio/opus'
-		| 'video/ogg'
-		| 'audio/ogg'
-		| 'application/ogg'
-		| 'audio/x-flac'
-		| 'audio/ape'
-		| 'audio/wavpack'
-		| 'audio/amr'
-		| 'application/pdf'
-		| 'application/x-msdownload'
-		| 'application/x-shockwave-flash'
-		| 'application/rtf'
-		| 'application/wasm'
-		| 'font/woff'
-		| 'font/woff2'
-		| 'application/vnd.ms-fontobject'
-		| 'font/ttf'
-		| 'font/otf'
-		| 'image/x-icon'
-		| 'video/x-flv'
-		| 'application/postscript'
-		| 'application/eps'
-		| 'application/x-xz'
-		| 'application/x-sqlite3'
-		| 'application/x-nintendo-nes-rom'
-		| 'application/x-google-chrome-extension'
-		| 'application/vnd.ms-cab-compressed'
-		| 'application/x-deb'
-		| 'application/x-unix-archive'
-		| 'application/x-rpm'
-		| 'application/x-compress'
-		| 'application/x-lzip'
-		| 'application/x-cfb'
-		| 'application/x-mie'
-		| 'application/x-apache-arrow'
-		| 'application/mxf'
-		| 'video/mp2t'
-		| 'application/x-blender'
-		| 'image/bpg'
-		| 'image/jp2'
-		| 'image/jpx'
-		| 'image/jpm'
-		| 'image/mj2'
-		| 'audio/aiff'
-		| 'application/xml'
-		| 'application/x-mobipocket-ebook'
-		| 'image/heif'
-		| 'image/heif-sequence'
-		| 'image/heic'
-		| 'image/heic-sequence'
-		| 'image/ktx'
-		| 'application/dicom'
-		| 'audio/x-musepack'
-		| 'text/calendar'
-		| 'text/vcard'
-		| 'model/gltf-binary'
-		| 'application/vnd.tcpdump.pcap'
-		| 'audio/x-dsf' // Non-standard
-		| 'application/x.ms.shortcut' // Invented by us
-		| 'application/x.apple.alias' // Invented by us
-		| 'audio/x-voc'
-		| 'audio/vnd.dolby.dd-raw'
-		| 'audio/x-m4a'
-		| 'image/apng'
-		| 'image/x-olympus-orf'
-		| 'image/x-sony-arw'
-		| 'image/x-adobe-dng'
-		| 'image/x-nikon-nef'
-		| 'image/x-panasonic-rw2'
-		| 'image/x-fujifilm-raf'
-		| 'video/x-m4v'
-		| 'video/3gpp2'
-		| 'application/x-esri-shape'
-		| 'audio/aac'
-		| 'audio/x-it'
-		| 'audio/x-s3m'
-		| 'audio/x-xm'
-		| 'video/MP1S'
-		| 'video/MP2P'
-		| 'application/vnd.sketchup.skp'
-		| 'image/avif'
-		| 'application/x-lzh-compressed'
-		| 'application/pgp-encrypted'
-		| 'application/x-asar'
-		| 'model/stl'
-		| 'application/vnd.ms-htmlhelp'
-		| 'model/3mf'
-		| 'image/jxl'
-		| 'application/zstd';
-
-	interface FileTypeResult {
-		/**
-		One of the supported [file types](https://github.com/sindresorhus/file-type#supported-file-types).
-		*/
-		readonly ext: FileExtension;
-
-		/**
-		The detected [MIME type](https://en.wikipedia.org/wiki/Internet_media_type).
-		*/
-		readonly mime: MimeType;
-	}
-
-	type ReadableStreamWithFileType = ReadableStream & {
-		readonly fileType?: FileTypeResult;
-	};
+/**
+Typings for primary entry point, Node.js specific typings can be found in index.d.ts
+*/
 
-	/**
-	Detect the file type of a `Buffer`, `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.
+import type {ReadableStream as WebReadableStream} from 'node:stream/web';
+import type {ITokenizer, AnyWebByteStream} from 'strtok3';
 
-	If file access is available, it is recommended to use `.fromFile()` instead.
+/**
+Either the Node.js ReadableStream or the `lib.dom.d.ts` ReadableStream.
+Related issue: https://github.com/DefinitelyTyped/DefinitelyTyped/pull/60377
+*/
+export type AnyWebReadableStream<G> = WebReadableStream<G> | ReadableStream<G>;
 
-	@param buffer - A buffer 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 and MIME type, or `undefined` when there is no match.
+export type FileTypeResult = {
+	/**
+	One of the supported [file types](https://github.com/sindresorhus/file-type#supported-file-types).
 	*/
-	function fromBuffer(buffer: Buffer | Uint8Array | ArrayBuffer): Promise<core.FileTypeResult | undefined>;
+	readonly ext: string;
 
 	/**
-	Detect the file type of a Node.js [readable stream](https://nodejs.org/api/stream.html#stream_class_stream_readable).
+	The detected [MIME type](https://en.wikipedia.org/wiki/Internet_media_type).
+	*/
+	readonly mime: string;
+};
 
-	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.
+/**
+Detect the file type of a `Uint8Array` or `ArrayBuffer`.
 
-	@param stream - A readable stream representing file data.
-	@returns The detected file type and MIME type, or `undefined` when there is no match.
-	*/
-	function fromStream(stream: ReadableStream): Promise<core.FileTypeResult | undefined>;
+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.
 
-	/**
-	Detect the file type from an [`ITokenizer`](https://github.com/Borewit/strtok3#tokenizer) source.
+If file access is available, it is recommended to use `.fromFile()` instead.
 
-	This method is used internally, but can also be used for a special "tokenizer" reader.
+@param 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.
+@param options - Options to override default behavior.
+@returns The detected file type, or `undefined` when there is no match.
+*/
+export function fileTypeFromBuffer(buffer: Uint8Array | ArrayBuffer, options?: FileTypeOptions): Promise<FileTypeResult | undefined>;
 
-	A tokenizer propagates the internal read functions, allowing alternative transport mechanisms, to access files, to be implemented and used.
+/**
+Detect the file type of a [web `ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
 
-	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.
+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.
 
-	```
-	import {makeTokenizer} = require('@tokenizer/http');
-	import FileType = require('file-type');
+@param stream - A [web `ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) streaming a file to examine.
+@param options - Options to override default behavior.
+@returns A `Promise` for an object with the detected file type, or `undefined` when there is no match.
+*/
+export function fileTypeFromStream(stream: AnyWebByteStream, options?: FileTypeOptions): Promise<FileTypeResult | undefined>;
 
-	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';
+/**
+Detect the file type from an [`ITokenizer`](https://github.com/Borewit/strtok3#tokenizer) source.
 
-	(async () => {
-		const httpTokenizer = await makeTokenizer(audioTrackUrl);
-		const fileType = await FileType.fromTokenizer(httpTokenizer);
+This method is used internally, but can also be used for a special "tokenizer" reader.
 
-		console.log(fileType);
-		//=> {ext: 'mp3', mime: 'audio/mpeg'}
-	})();
-	```
+A tokenizer propagates the internal read functions, allowing alternative transport mechanisms, to access files, to be implemented and used.
 
-	@param tokenizer - File source implementing the tokenizer interface.
-	@returns The detected file type and MIME type, or `undefined` when there is no match.
-	*/
-	function fromTokenizer(tokenizer: ITokenizer): Promise<core.FileTypeResult | undefined>;
+@param tokenizer - File source implementing the tokenizer interface.
+@param options - Options to override default behavior.
+@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
+```
+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'}
+```
+*/
+export function fileTypeFromTokenizer(tokenizer: ITokenizer, options?: FileTypeOptions): Promise<FileTypeResult | undefined>;
+
+/**
+Supported file extensions.
+*/
+export const supportedExtensions: ReadonlySet<string>;
+
+/**
+Supported MIME types.
+*/
+export const supportedMimeTypes: ReadonlySet<string>;
+
+export type StreamOptions = {
 	/**
-	Supported file extensions.
+	The default sample size in bytes.
+
+	@default 4100
 	*/
-	const extensions: Set<core.FileExtension>;
+	readonly sampleSize?: number;
+};
+
+/**
+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).
+
+@param blob - The [`Blob`](https://nodejs.org/api/buffer.html#class-blob) used for file detection.
+@param options - Options to override default behavior.
+@returns The detected file type, or `undefined` when there is no match.
+
+@example
+```
+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'}
+```
+*/
+export declare function fileTypeFromBlob(blob: Blob, options?: FileTypeOptions): Promise<FileTypeResult | undefined>;
+
+/**
+A custom file type detector.
+
+Custom file type detectors are plugins designed to extend the default detection capabilities.
+They allow support for uncommon file types, non-binary formats, or customized detection behavior.
+
+Detectors can be added via the constructor options or by modifying `FileTypeParser#detectors` directly.
+Detectors provided through the constructor are executed before the default ones.
+
+Detectors can be added via the constructor options or by directly modifying `FileTypeParser#detectors`.
+
+### Example adding a detector
+
+```js
+import {FileTypeParser} from 'file-type';
+import {detectXml} from '@file-type/xml';
+
+const parser = new FileTypeParser({customDetectors: [detectXml]});
+const fileType = await parser.fromFile('sample.kml');
+console.log(fileType);
+```
+
+### Available-third party file-type detectors
+
+- [@file-type/xml](https://github.com/Borewit/file-type-xml): Detects common XML file types, such as GLM, KML, MusicXML, RSS, SVG, and XHTML
+
+### 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 writing a custom detector
+
+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'}
+```
+
+@param tokenizer - The [tokenizer](https://github.com/Borewit/strtok3#tokenizer) used to read file content.
+@param 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.
+*/
+export type Detector = {
+	id: string;
+	detect: (tokenizer: ITokenizer, fileType?: FileTypeResult) => Promise<FileTypeResult | undefined>;
+};
+
+export type FileTypeOptions = {
+	customDetectors?: Iterable<Detector>;
 
 	/**
-	Supported MIME types.
+	Specifies the byte tolerance for locating the first MPEG audio frame (e.g. `.mp1`, `.mp2`, `.mp3`, `.aac`).
+
+	Allows detection to handle slight sync offsets between the expected and actual frame start. Common in malformed or incorrectly muxed files, which, while technically invalid, do occur in the wild.
+
+	A tolerance of 10 bytes covers most cases.
+
+ 	@default 0
 	*/
-	const mimeTypes: Set<core.MimeType>;
+	mpegOffsetTolerance?: number;
+};
+
+export declare class TokenizerPositionError extends Error {
+	constructor(message?: string);
+}
+
+export type AnyWebReadableByteStreamWithFileType = AnyWebReadableStream<Uint8Array> & {
+	readonly fileType?: FileTypeResult;
+};
+
+/**
+Workaround for using `bundler` as the module-resolution in TypeScript.
+*/
+export function fileTypeFromFile(filePath: string, options?: {customDetectors?: Iterable<Detector>}): Promise<FileTypeResult | undefined>;
+
+/**
+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 a stream pipeline, 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.
+*/
+export function fileTypeStream(webStream: AnyWebReadableStream<Uint8Array>, options?: StreamOptions): Promise<AnyWebReadableByteStreamWithFileType>;
+
+export declare class FileTypeParser {
 	/**
-	Detect the file type of a readable stream.
+	File type detectors.
 
-	@param readableStream - A [readable stream](https://nodejs.org/api/stream.html#stream_class_stream_readable) containing a file to examine.
-	@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 `FileType.fromFile()`.
+	Initialized with a single entry holding the built-in detector function.
+	*/
+	detectors: Detector[];
 
-	@example
-	```
-	import * as fs from 'fs';
-	import * as crypto from 'crypto';
-	import fileType = require('file-type');
+	constructor(options?: {customDetectors?: Iterable<Detector>; signal?: AbortSignal});
 
-	(async () => {
-		const read = fs.createReadStream('encrypted.enc');
-		const decipher = crypto.createDecipheriv(alg, key, iv);
-		const stream = await fileType.stream(read.pipe(decipher));
+	/**
+	Works the same way as {@link fileTypeFromBuffer}, additionally taking into account custom detectors (if any were provided to the constructor).
+	*/
+	fromBuffer(buffer: Uint8Array | ArrayBuffer): Promise<FileTypeResult | undefined>;
 
-		console.log(stream.fileType);
-		//=> {ext: 'mov', mime: 'video/quicktime'}
+	/**
+	Works the same way as {@link fileTypeFromTokenizer}, additionally taking into account custom detectors (if any were provided to the constructor).
+	*/
+	fromTokenizer(tokenizer: ITokenizer): Promise<FileTypeResult | undefined>;
 
-		const write = fs.createWriteStream(`decrypted.${stream.fileType.ext}`);
-		stream.pipe(write);
-	})();
-	```
+	/**
+	Works the same way as {@link fileTypeFromBlob}, additionally taking into account custom detectors (if any were provided to the constructor).
 	*/
-	function stream(readableStream: ReadableStream): Promise<core.ReadableStreamWithFileType>
-}
+	fromBlob(blob: Blob): Promise<FileTypeResult | undefined>;
 
-export = core;
+	/**
+	Works the same way as {@link fileTypeStream}, additionally taking into account custom detectors (if any were provided to the constructor).
+	*/
+	toDetectionStream(webStream: AnyWebReadableStream<Uint8Array>, options?: StreamOptions): Promise<AnyWebReadableByteStreamWithFileType>;
+}