file-type 19.6.0 → 20.0.0

package/core.d.ts

@@ -11,327 +11,16 @@ Related issue: https://github.com/DefinitelyTyped/DefinitelyTyped/pull/60377
 */
 export type AnyWebReadableStream<G> = WebReadableStream<G> | ReadableStream<G>;
 
-export 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'
-	| 'elf'
-	| 'macho'
-	| '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'
-	| 'j2c'
-	| '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'
-	| 'jls'
-	| 'pst'
-	| 'dwg'
-	| 'parquet'
-	| 'class'
-	| 'arj'
-	| 'cpio'
-	| 'ace'
-	| 'avro'
-	| 'icc'
-	| 'fbx'
-	| 'vsdx'
-	| 'vtt'
-	| 'apk'
-	; // eslint-disable-line semi-style
-
-export 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/wav'
-	| 'audio/qcelp'
-	| 'audio/x-ms-asf'
-	| 'video/x-ms-asf'
-	| 'application/vnd.ms-asf'
-	| 'video/mpeg'
-	| 'video/3gpp'
-	| 'audio/mpeg'
-	| 'audio/mp4' // RFC 4337
-	| 'video/ogg'
-	| 'audio/ogg'
-	| 'audio/ogg; codecs=opus'
-	| 'application/ogg'
-	| 'audio/x-flac'
-	| 'audio/ape'
-	| 'audio/wavpack'
-	| 'audio/amr'
-	| 'application/pdf'
-	| 'application/x-elf'
-	| 'application/x-mach-binary'
-	| '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/j2c'
-	| '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'
-	| 'text/vtt'
-	| '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'
-	| 'image/jls'
-	| 'application/vnd.ms-outlook'
-	| 'image/vnd.dwg'
-	| 'application/x-parquet'
-	| 'application/java-vm'
-	| 'application/x-arj'
-	| 'application/x-cpio'
-	| 'application/x-ace-compressed'
-	| 'application/avro'
-	| 'application/vnd.iccprofile'
-	| 'application/x.autodesk.fbx'
-	| 'application/vnd.visio'
-	| 'application/vnd.android.package-archive'
-	; // eslint-disable-line semi-style
-
 export type FileTypeResult = {
 	/**
 	One of the supported [file types](https://github.com/sindresorhus/file-type#supported-file-types).
 	*/
-	readonly ext: FileExtension;
+	readonly ext: string;
 
 	/**
 	The detected [MIME type](https://en.wikipedia.org/wiki/Internet_media_type).
 	*/
-	readonly mime: MimeType;
+	readonly mime: string;
 };
 
 /**
@@ -387,12 +76,12 @@ export function fileTypeFromTokenizer(tokenizer: ITokenizer): Promise<FileTypeRe
 /**
 Supported file extensions.
 */
-export const supportedExtensions: ReadonlySet<FileExtension>;
+export const supportedExtensions: ReadonlySet<string>;
 
 /**
 Supported MIME types.
 */
-export const supportedMimeTypes: ReadonlySet<MimeType>;
+export const supportedMimeTypes: ReadonlySet<string>;
 
 export type StreamOptions = {
 	/**
@@ -425,31 +114,35 @@ console.log(await fileTypeFromBlob(blob));
 export declare function fileTypeFromBlob(blob: Blob): Promise<FileTypeResult | undefined>;
 
 /**
-Function that allows specifying custom detection mechanisms.
+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.
 
-An iterable of detectors can be provided via the `fileTypeOptions` argument for the {@link FileTypeParser.constructor}.
+Custom detectors allow for:
+- Introducing new `FileTypeResult` entries.
+- Modifying the detection behavior of existing `FileTypeResult` types.
 
-The detectors are called before the default detections in the provided order.
+### Detector execution flow
 
-Custom detectors can be used to add new `FileTypeResults` or to modify return behavior of existing `FileTypeResult` detections.
+If a detector returns `undefined`, the following rules apply:
 
-If the detector returns `undefined`, there are 2 possible scenarios:
+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.
 
-1. The detector has not read from the tokenizer, it will be proceeded with the next available detector.
-2. The detector has read from the tokenizer (`tokenizer.position` has been increased).
-	In that case no further detectors will be executed and the final conclusion is that file-type returns undefined.
-	Note that this an exceptional scenario, as the detector takes the opportunity from any other detector to determine the file type.
+### Example usage
 
-Example detector array which can be extended and provided via the fileTypeOptions argument:
+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' as decimal string
+		const unicornHeader = [85, 78, 73, 67, 79, 82, 78]; // "UNICORN" in ASCII decimal
 
-		const buffer = Buffer.alloc(7);
+		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'};
@@ -459,17 +152,20 @@ const customDetectors = [
 	},
 ];
 
-const buffer = Buffer.from('UNICORN');
+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);
+console.log(fileType); // {ext: 'unicorn', mime: 'application/unicorn'}
 ```
 
-@param tokenizer - The [tokenizer](https://github.com/Borewit/strtok3#tokenizer) used to read the file content from.
-@param fileType - The file type detected by the standard detections or a previous custom detection, or `undefined`` if no matching file type could be found.
-@returns The detected file type, or `undefined` when there is no match.
+@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 = (tokenizer: ITokenizer, fileType?: FileTypeResult) => Promise<FileTypeResult | undefined>;
+export type Detector = {
+	id: string;
+	detect: (tokenizer: ITokenizer, fileType?: FileTypeResult) => Promise<FileTypeResult | undefined>;
+};
 
 export type FileTypeOptions = {
 	customDetectors?: Iterable<Detector>;
@@ -491,9 +187,14 @@ This method can be handy to put in a stream pipeline, but it comes with a price.
 export function fileTypeStream(webStream: AnyWebReadableStream<Uint8Array>, options?: StreamOptions): Promise<AnyWebReadableByteStreamWithFileType>;
 
 export declare class FileTypeParser {
-	detectors: Iterable<Detector>;
+	/**
+	File type detectors.
+
+	Initialized with a single entry holding the built-in detector function.
+	*/
+	detectors: Detector[];
 
-	constructor(options?: {customDetectors?: Iterable<Detector>; signal: AbortSignal});
+	constructor(options?: {customDetectors?: Iterable<Detector>; signal?: AbortSignal});
 
 	/**
 	Works the same way as {@link fileTypeFromBuffer}, additionally taking into account custom detectors (if any were provided to the constructor).