file-type 19.6.0 → 20.0.0

package/index.js

@@ -5,9 +5,9 @@ Node.js specific entry point.
 import {ReadableStream as WebReadableStream} from 'node:stream/web';
 import {pipeline, PassThrough, Readable} from 'node:stream';
 import * as strtok3 from 'strtok3';
-import {FileTypeParser, reasonableDetectionSizeInBytes} from './core.js';
+import {FileTypeParser as DefaultFileTypeParser, reasonableDetectionSizeInBytes} from './core.js';
 
-export class NodeFileTypeParser extends FileTypeParser {
+export class FileTypeParser extends DefaultFileTypeParser {
 	async fromStream(stream) {
 		const tokenizer = await (stream instanceof WebReadableStream ? strtok3.fromWebStream(stream, this.tokenizerOptions) : strtok3.fromStream(stream, this.tokenizerOptions));
 		try {
@@ -66,15 +66,21 @@ export class NodeFileTypeParser extends FileTypeParser {
 }
 
 export async function fileTypeFromFile(path, fileTypeOptions) {
-	return (new NodeFileTypeParser(fileTypeOptions)).fromFile(path, fileTypeOptions);
+	return (new FileTypeParser(fileTypeOptions)).fromFile(path, fileTypeOptions);
 }
 
 export async function fileTypeFromStream(stream, fileTypeOptions) {
-	return (new NodeFileTypeParser(fileTypeOptions)).fromStream(stream);
+	return (new FileTypeParser(fileTypeOptions)).fromStream(stream);
 }
 
 export async function fileTypeStream(readableStream, options = {}) {
-	return new NodeFileTypeParser(options).toDetectionStream(readableStream, options);
+	return new FileTypeParser(options).toDetectionStream(readableStream, options);
 }
 
-export {fileTypeFromTokenizer, fileTypeFromBuffer, fileTypeFromBlob, FileTypeParser, supportedMimeTypes, supportedExtensions} from './core.js';
+export {
+	fileTypeFromTokenizer,
+	fileTypeFromBuffer,
+	fileTypeFromBlob,
+	supportedMimeTypes,
+	supportedExtensions,
+} from './core.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "file-type",
-	"version": "19.6.0",
+	"version": "20.0.0",
 	"description": "Detect the file type of a file, stream, or data",
 	"license": "MIT",
 	"repository": "sindresorhus/file-type",
@@ -217,22 +217,40 @@
 		"fbx",
 		"vsdx",
 		"vtt",
-		"apk"
+		"apk",
+		"drc",
+		"lz4",
+		"potx",
+		"xltx",
+		"dotx",
+		"xltm",
+		"ots",
+		"odg",
+		"otg",
+		"otp",
+		"ott",
+		"xlsm",
+		"docm",
+		"dotm",
+		"potm",
+		"pptm",
+		"jar"
 	],
 	"dependencies": {
-		"get-stream": "^9.0.1",
-		"strtok3": "^9.0.1",
+		"@tokenizer/inflate": "^0.2.6",
+		"strtok3": "^10.0.1",
 		"token-types": "^6.0.0",
-		"uint8array-extras": "^1.3.0"
+		"uint8array-extras": "^1.4.0"
 	},
 	"devDependencies": {
 		"@tokenizer/token": "^0.3.0",
-		"@types/node": "^20.10.7",
+		"@types/node": "^22.10.5",
 		"ava": "^6.0.1",
-		"commonmark": "^0.30.0",
+		"commonmark": "^0.31.2",
+		"get-stream": "^9.0.1",
 		"noop-stream": "^1.0.0",
-		"tsd": "^0.30.3",
-		"xo": "^0.56.0"
+		"tsd": "^0.31.2",
+		"xo": "^0.60.0"
 	},
 	"xo": {
 		"envs": [

package/readme.md

@@ -16,13 +16,13 @@ We accept contributions for commonly used modern file formats, not historical or
 npm install file-type
 ```
 
-**This package is an ESM package. Your project needs to be ESM too. [Read more](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).**
+**This package is an ESM package. Your project needs to be ESM too. [Read more](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). For TypeScript + CommonJS, see [`load-esm`](https://github.com/Borewit/load-esm).**
 
 If you use it with Webpack, you need the latest Webpack version and ensure you configure it correctly for ESM.
 
 ## Usage
 
-#### Node.js
+### Node.js
 
 Determine file type from a file:
 
@@ -91,7 +91,7 @@ const write = fs.createWriteStream(`decrypted.${streamWithFileType.fileType.ext}
 streamWithFileType.pipe(write);
 ```
 
-#### Browser
+### Browser
 
 ```js
 import {fileTypeFromStream} from 'file-type';
@@ -178,10 +178,10 @@ A readable stream representing file data.
 
 Detect the file type of a [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob),
 
-[!TIP]
+> [!TIP]
 > A [`File` object](https://developer.mozilla.org/docs/Web/API/File) is a `Blob` and can be passed in here.
 
-It will **stream** the underlying Blob, and required a [ReadableStreamBYOBReader](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader) which **require Node.js ≥ 20**.
+It will **stream** the underlying Blob.
 
 The file type is detected by checking the [magic number](https://en.wikipedia.org/wiki/Magic_number_(programming)#Magic_numbers_in_files) of the blob.
 
@@ -204,6 +204,21 @@ console.log(await fileTypeFromBlob(blob));
 //=> {ext: 'txt', mime: 'text/plain'}
 ```
 
+> [!WARNING]
+> This method depends on [ReadableStreamBYOBReader](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader) which **requires Node.js ≥ 20**
+> and [may not be available in all modern browsers](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader#browser_compatibility).
+
+To work around this limitation, you can use an alternative approach to read and process the `Blob` without relying on streaming:
+
+```js
+import {fileTypeFromBuffer} from 'file-type';
+
+async function readFromBlobWithoutStreaming(blob) {
+	const buffer = await blob.arrayBuffer();
+	return fileTypeFromBuffer(buffer);
+}
+```
+
 #### blob
 
 Type: [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
@@ -325,46 +340,58 @@ Returns a `Set<string>` of supported MIME types.
 
 ## Custom detectors
 
-A custom detector is a function that allows specifying custom detection mechanisms.
+A custom file type detector.
 
-An iterable of detectors can be provided via the `fileTypeOptions` argument for the `FileTypeParser` constructor.
-In Node.js, you should use `NodeFileTypeParser`, which extends `FileTypeParser` and provides access to Node.js specific functions.
+Detectors can be added via the constructor options or by directly modifying `FileTypeParser#detectors`.
 
-The detectors are called before the default detections in the provided order.
+Detectors provided through the constructor options are executed before the default detectors.
 
-Custom detectors can be used to add new `FileTypeResults` or to modify return behaviour of existing `FileTypeResult` detections.
+Custom detectors allow for:
+- Introducing new `FileTypeResult` entries.
+- Modifying the detection behavior of existing `FileTypeResult` types.
 
-If the detector returns `undefined`, there are 2 possible scenarios:
+### Detector execution flow
 
-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.
+If a detector returns `undefined`, the following rules apply:
 
-Example detector array which can be extended and provided to each public method via the `fileTypeOptions` argument:
+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.
 
 ```js
-import {FileTypeParser} from 'file-type'; // or `NodeFileTypeParser` in Node.js
+import {FileTypeParser} from 'file-type';
 
-const customDetectors = [
-	async tokenizer => {
-		const unicornHeader = [85, 78, 73, 67, 79, 82, 78]; // 'UNICORN' as decimal string
+const unicornDetector = {
+	id: 'unicorn', // May be used to recognize the detector in the detector list
+  	async detect(tokenizer) {
+		const unicornHeader = [85, 78, 73, 67, 79, 82, 78]; // "UNICORN" in ASCII decimal
 
-		const buffer = new Uint8Array(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'};
 		}
 
 		return undefined;
-	},
-];
+	}
+}
 
-const buffer = new Uint8Array(new TextEncoder().encode('UNICORN'));
-const parser = new FileTypeParser({customDetectors}); // `NodeFileTypeParser({customDetectors})` in Node.js
+const buffer = new Uint8Array([85, 78, 73, 67, 79, 82, 78]);
+const parser = new FileTypeParser({customDetectors: [unicornDetector]});
 const fileType = await parser.fromBuffer(buffer);
-console.log(fileType);
+console.log(fileType); // {ext: 'unicorn', mime: 'application/unicorn'}
+```
+
+```ts
+/**
+@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>;
 ```
 
 ## Abort signal
@@ -372,7 +399,7 @@ console.log(fileType);
 Some async operations can be aborted by passing an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to the `FileTypeParser` constructor.
 
 ```js
-import {FileTypeParser} from 'file-type'; // or `NodeFileTypeParser` in Node.js
+import {FileTypeParser} from 'file-type';
 
 const abortController = new AbortController()
 
@@ -426,7 +453,11 @@ abortController.abort(); // Abort file-type reading from the Blob stream.
 - [`deb`](https://en.wikipedia.org/wiki/Deb_(file_format)) - Debian package
 - [`dmg`](https://en.wikipedia.org/wiki/Apple_Disk_Image) - Apple Disk Image
 - [`dng`](https://en.wikipedia.org/wiki/Digital_Negative) - Adobe Digital Negative image file
+- [`docm`](https://en.wikipedia.org/wiki/List_of_Microsoft_Office_filename_extensions) - Microsoft Word macro-enabled document
 - [`docx`](https://en.wikipedia.org/wiki/Office_Open_XML) - Microsoft Word document
+- [`dotm`](https://en.wikipedia.org/wiki/List_of_Microsoft_Office_filename_extensions) - Microsoft Word macro-enabled template
+- [`dotx`](https://en.wikipedia.org/wiki/List_of_Microsoft_Office_filename_extensions) - Microsoft Word template
+- [`drc`](https://en.wikipedia.org/wiki/Zstandard) - Google's Draco 3D Data Compression
 - [`dsf`](https://dsd-guide.com/sites/default/files/white-papers/DSFFileFormatSpec_E.pdf) - Sony DSD Stream File (DSF)
 - [`dwg`](https://en.wikipedia.org/wiki/.dwg) - Autodesk CAD file
 - [`elf`](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format) - Unix Executable and Linkable Format
@@ -453,6 +484,7 @@ abortController.abort(); // Abort file-type reading from the Blob stream.
 - [`indd`](https://en.wikipedia.org/wiki/Adobe_InDesign#File_format) - Adobe InDesign document
 - [`it`](https://wiki.openmpt.org/Manual:_Module_formats#The_Impulse_Tracker_format_.28.it.29) - Audio module format: Impulse Tracker
 - [`j2c`](https://en.wikipedia.org/wiki/JPEG_2000) - JPEG 2000
+- [`jar`](https://en.wikipedia.org/wiki/JAR_(file_format)) - Java archive
 - [`jls`](https://en.wikipedia.org/wiki/Lossless_JPEG#JPEG-LS) - Lossless/near-lossless compression standard for continuous-tone images
 - [`jp2`](https://en.wikipedia.org/wiki/JPEG_2000) - JPEG 2000
 - [`jpg`](https://en.wikipedia.org/wiki/JPEG) - Joint Photographic Experts Group image
@@ -463,6 +495,7 @@ abortController.abort(); // Abort file-type reading from the Blob stream.
 - [`ktx`](https://www.khronos.org/opengles/sdk/tools/KTX/file_format_spec/) - OpenGL and OpenGL ES textures
 - [`lnk`](https://en.wikipedia.org/wiki/Shortcut_%28computing%29#Microsoft_Windows) - Microsoft Windows file shortcut
 - [`lz`](https://en.wikipedia.org/wiki/Lzip) - Archive file
+- [`lz4`](https://en.wikipedia.org/wiki/LZ4_(compression_algorithm)) - Compressed archive created by one of a variety of LZ4 compression utilities
 - [`lzh`](https://en.wikipedia.org/wiki/LHA_(file_format)) - LZH archive
 - [`m4a`](https://en.wikipedia.org/wiki/M4A) - Audio-only MPEG-4 files
 - [`m4b`](https://en.wikipedia.org/wiki/M4B) - Audiobook and podcast MPEG-4 files, which also contain metadata including chapter markers, images, and hyperlinks
@@ -485,6 +518,7 @@ abortController.abort(); // Abort file-type reading from the Blob stream.
 - [`mxf`](https://en.wikipedia.org/wiki/Material_Exchange_Format) - Material Exchange Format
 - [`nef`](https://www.nikonusa.com/en/learn-and-explore/a/products-and-innovation/nikon-electronic-format-nef.html) - Nikon Electronic Format image file
 - [`nes`](https://fileinfo.com/extension/nes) - Nintendo NES ROM
+- [`odg`](https://en.wikipedia.org/wiki/OpenDocument) - OpenDocument for drawing
 - [`odp`](https://en.wikipedia.org/wiki/OpenDocument) - OpenDocument for presentations
 - [`ods`](https://en.wikipedia.org/wiki/OpenDocument) - OpenDocument for spreadsheets
 - [`odt`](https://en.wikipedia.org/wiki/OpenDocument) - OpenDocument for word processing
@@ -496,12 +530,19 @@ abortController.abort(); // Abort file-type reading from the Blob stream.
 - [`opus`](https://en.wikipedia.org/wiki/Opus_(audio_format)) - Audio file
 - [`orf`](https://en.wikipedia.org/wiki/ORF_format) - Olympus Raw image file
 - [`otf`](https://en.wikipedia.org/wiki/OpenType) - OpenType font
+- [`otg`](https://en.wikipedia.org/wiki/OpenDocument_technical_specification#Templates) - OpenDocument template for drawing
+- [`otp`](https://en.wikipedia.org/wiki/OpenDocument_technical_specification#Templates) - OpenDocument template for presentations
+- [`ots`](https://en.wikipedia.org/wiki/OpenDocument_technical_specification#Templates) - OpenDocument template for spreadsheets
+- [`ott`](https://en.wikipedia.org/wiki/OpenDocument_technical_specification#Templates) - OpenDocument template for word processing
 - [`parquet`](https://en.wikipedia.org/wiki/Apache_Parquet) - Apache Parquet
 - [`pcap`](https://wiki.wireshark.org/Development/LibpcapFileFormat) - Libpcap File Format
 - [`pdf`](https://en.wikipedia.org/wiki/Portable_Document_Format) - Portable Document Format
 - [`pgp`](https://en.wikipedia.org/wiki/Pretty_Good_Privacy) - Pretty Good Privacy
 - [`png`](https://en.wikipedia.org/wiki/Portable_Network_Graphics) - Portable Network Graphics
-- [`pptx`](https://en.wikipedia.org/wiki/Office_Open_XML) - Microsoft Powerpoint document
+- [`potm`](https://en.wikipedia.org/wiki/List_of_Microsoft_Office_filename_extensions) - Microsoft PowerPoint macro-enabled template
+- [`potx`](https://en.wikipedia.org/wiki/List_of_Microsoft_Office_filename_extensions) - Microsoft PowerPoint template
+- [`pptm`](https://en.wikipedia.org/wiki/List_of_Microsoft_Office_filename_extensions) - Microsoft PowerPoint macro-enabled document
+- [`pptx`](https://en.wikipedia.org/wiki/Office_Open_XML) - Microsoft PowerPoint document
 - [`ps`](https://en.wikipedia.org/wiki/Postscript) - Postscript
 - [`psd`](https://en.wikipedia.org/wiki/Adobe_Photoshop#File_format) - Adobe Photoshop document
 - [`pst`](https://en.wikipedia.org/wiki/Personal_Storage_Table) - Personal Storage Table file
@@ -533,7 +574,10 @@ abortController.abort(); // Abort file-type reading from the Blob stream.
 - [`woff2`](https://en.wikipedia.org/wiki/Web_Open_Font_Format) - Web Open Font Format
 - [`wv`](https://en.wikipedia.org/wiki/WavPack) - WavPack
 - [`xcf`](https://en.wikipedia.org/wiki/XCF_(file_format)) - eXperimental Computing Facility
+- [`xlsm`](https://en.wikipedia.org/wiki/List_of_Microsoft_Office_filename_extensions) - Microsoft Excel macro-enabled document
 - [`xlsx`](https://en.wikipedia.org/wiki/Office_Open_XML) - Microsoft Excel document
+- [`xltm`](https://en.wikipedia.org/wiki/List_of_Microsoft_Office_filename_extensions) - Microsoft Excel macro-enabled template
+- [`xltx`](https://en.wikipedia.org/wiki/List_of_Microsoft_Office_filename_extensions) - Microsoft Excel template
 - [`xm`](https://wiki.openmpt.org/Manual:_Module_formats#The_FastTracker_2_format_.28.xm.29) - Audio module format: FastTracker 2
 - [`xml`](https://en.wikipedia.org/wiki/XML) - eXtensible Markup Language
 - [`xpi`](https://en.wikipedia.org/wiki/XPInstall) - XPInstall file

package/supported.js

@@ -154,6 +154,23 @@ export const extensions = [
 	'vsdx',
 	'vtt',
 	'apk',
+	'drc',
+	'lz4',
+	'potx',
+	'xltx',
+	'dotx',
+	'xltm',
+	'ott',
+	'ots',
+	'otp',
+	'odg',
+	'otg',
+	'xlsm',
+	'docm',
+	'dotm',
+	'potm',
+	'pptm',
+	'jar',
 ];
 
 export const mimeTypes = [
@@ -307,4 +324,21 @@ export const mimeTypes = [
 	'application/x.autodesk.fbx', // Invented by us
 	'application/vnd.visio',
 	'application/vnd.android.package-archive',
+	'application/vnd.google.draco', // Invented by us
+	'application/x-lz4', // Invented by us
+	'application/vnd.openxmlformats-officedocument.presentationml.template',
+	'application/vnd.openxmlformats-officedocument.spreadsheetml.template',
+	'application/vnd.openxmlformats-officedocument.wordprocessingml.template',
+	'application/vnd.ms-excel.template.macroenabled.12',
+	'application/vnd.oasis.opendocument.text-template',
+	'application/vnd.oasis.opendocument.spreadsheet-template',
+	'application/vnd.oasis.opendocument.presentation-template',
+	'application/vnd.oasis.opendocument.graphics',
+	'application/vnd.oasis.opendocument.graphics-template',
+	'application/vnd.ms-excel.sheet.macroEnabled.12',
+	'application/vnd.ms-word.document.macroEnabled.12',
+	'application/vnd.ms-word.template.macroEnabled.12',
+	'application/vnd.ms-powerpoint.template.macroEnabled.12',
+	'application/vnd.ms-powerpoint.presentation.macroEnabled.12',
+	'application/java-archive',
 ];