file-type 16.5.4 → 21.3.4

package/index.d.ts

@@ -1,27 +1,98 @@
-/// <reference types="node"/>
-import {Readable as ReadableStream} from 'stream';
-import * as core from './core';
+/**
+Typings for Node.js specific entry point.
+*/
+
+import type {Readable as NodeReadableStream} from 'node:stream';
+import type {AnyWebByteStream} from 'strtok3';
+import {
+	type FileTypeResult,
+	type StreamOptions,
+	type AnyWebReadableStream,
+	type AnyWebReadableByteStreamWithFileType,
+	type FileTypeOptions,
+	FileTypeParser as DefaultFileTypeParser,
+} from './core.js';
+
+export type ReadableStreamWithFileType = NodeReadableStream & {
+	readonly fileType?: FileTypeResult;
+};
+
+/**
+Extending `FileTypeParser` with Node.js engine specific functions.
+*/
+export declare class FileTypeParser extends DefaultFileTypeParser {
+	/**
+	@param stream - Node.js `stream.Readable` or web `ReadableStream`.
+	*/
+	fromStream(stream: AnyWebReadableStream<Uint8Array> | NodeReadableStream): Promise<FileTypeResult | undefined>;
+
+	fromFile(filePath: string): Promise<FileTypeResult | undefined>;
 
-export type ReadableStreamWithFileType = core.ReadableStreamWithFileType;
-export type FileTypeResult = core.FileTypeResult;
-export type FileExtension = core.FileExtension;
-export type MimeType = core.MimeType;
+	/**
+	Works the same way as {@link fileTypeStream}, additionally taking into account custom detectors (if any were provided to the constructor).
+	*/
+	toDetectionStream(readableStream: NodeReadableStream, options?: FileTypeOptions & StreamOptions): Promise<ReadableStreamWithFileType>;
+	toDetectionStream(webStream: AnyWebReadableStream<Uint8Array>, options?: FileTypeOptions & StreamOptions): Promise<AnyWebReadableByteStreamWithFileType>;
+}
 
 /**
 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.
 
-@param path - The file path to parse.
 @returns The detected file type and MIME type or `undefined` when there is no match.
 */
-export function fromFile(path: string): Promise<core.FileTypeResult | undefined>;
-
-export {
-	fromBuffer,
-	fromStream,
-	fromTokenizer,
-	extensions,
-	mimeTypes,
-	stream
-} from './core';
+export function fileTypeFromFile(filePath: string, options?: FileTypeOptions): 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.
+
+@param 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.
+@param options - Options to override default behaviour.
+ @returns A `Promise` for an object with the detected file type, or `undefined` when there is no match.
+*/
+export function fileTypeFromStream(stream: AnyWebReadableStream<Uint8Array> | NodeReadableStream, options?: FileTypeOptions): 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 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.
+
+@param 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.
+@param 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
+```
+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)
+}
+```
+*/
+export function fileTypeStream(readableStream: NodeReadableStream, options?: FileTypeOptions & StreamOptions): Promise<ReadableStreamWithFileType>;
+export function fileTypeStream(webStream: AnyWebByteStream, options?: FileTypeOptions & StreamOptions): Promise<AnyWebReadableByteStreamWithFileType>;
+
+export * from './core.js';

package/index.js

@@ -1,32 +1,163 @@
-'use strict';
-const strtok3 = require('strtok3');
-const core = require('./core');
-
-async function fromFile(path) {
-	const tokenizer = await strtok3.fromFile(path);
-	try {
-		return await core.fromTokenizer(tokenizer);
-	} finally {
-		await tokenizer.close();
+/**
+Node.js specific entry point.
+*/
+
+import {ReadableStream as WebReadableStream} from 'node:stream/web';
+import {pipeline, PassThrough, Readable} from 'node:stream';
+import fs from 'node:fs/promises';
+import {constants as fileSystemConstants} from 'node:fs';
+import * as strtok3 from 'strtok3';
+import {
+	FileTypeParser as DefaultFileTypeParser,
+	reasonableDetectionSizeInBytes,
+	normalizeSampleSize,
+} from './core.js';
+
+function isTokenizerStreamBoundsError(error) {
+	if (
+		!(error instanceof RangeError)
+		|| error.message !== 'offset is out of bounds'
+		|| typeof error.stack !== 'string'
+	) {
+		return false;
 	}
+
+	// Some malformed or non-byte Node.js streams can surface this tokenizer-internal range error.
+	// Note: This stack-trace check is fragile and may break if strtok3 restructures its internals.
+	return /strtok3[/\\]lib[/\\]stream[/\\]/.test(error.stack);
 }
 
-const fileType = {
-	fromFile
-};
+export class FileTypeParser extends DefaultFileTypeParser {
+	async fromStream(stream) {
+		this.options.signal?.throwIfAborted();
+		const tokenizer = await (stream instanceof WebReadableStream ? this.createTokenizerFromWebStream(stream) : strtok3.fromStream(stream, this.getTokenizerOptions()));
+		try {
+			return await super.fromTokenizer(tokenizer);
+		} catch (error) {
+			if (isTokenizerStreamBoundsError(error)) {
+				return;
+			}
 
-Object.assign(fileType, core);
+			throw error;
+		} finally {
+			// TODO: Remove this when `strtok3.fromStream()` closes the underlying Readable instead of only aborting tokenizer reads.
+			if (
+				stream instanceof Readable
+				&& !stream.destroyed
+			) {
+				stream.destroy();
+			}
+		}
+	}
+
+	async fromFile(path) {
+		this.options.signal?.throwIfAborted();
+		// TODO: Remove this when `strtok3.fromFile()` safely rejects non-regular filesystem objects without a pathname race.
+		const fileHandle = await fs.open(path, fileSystemConstants.O_RDONLY | fileSystemConstants.O_NONBLOCK);
+		const fileStat = await fileHandle.stat();
+		if (!fileStat.isFile()) {
+			await fileHandle.close();
+			return;
+		}
 
-Object.defineProperty(fileType, 'extensions', {
-	get() {
-		return core.extensions;
+		const tokenizer = new strtok3.FileTokenizer(fileHandle, {
+			...this.getTokenizerOptions(),
+			fileInfo: {
+				path,
+				size: fileStat.size,
+			},
+		});
+		return super.fromTokenizer(tokenizer);
 	}
-});
 
-Object.defineProperty(fileType, 'mimeTypes', {
-	get() {
-		return core.mimeTypes;
+	async toDetectionStream(readableStream, options = {}) {
+		if (!(readableStream instanceof Readable)) {
+			return super.toDetectionStream(readableStream, options);
+		}
+
+		const {sampleSize = reasonableDetectionSizeInBytes} = options;
+		const {signal} = this.options;
+		const normalizedSampleSize = normalizeSampleSize(sampleSize);
+
+		signal?.throwIfAborted();
+
+		return new Promise((resolve, reject) => {
+			let isSettled = false;
+
+			const cleanup = () => {
+				readableStream.off('error', onError);
+				readableStream.off('readable', onReadable);
+				signal?.removeEventListener('abort', onAbort);
+			};
+
+			const settle = (callback, value) => {
+				if (isSettled) {
+					return;
+				}
+
+				isSettled = true;
+				cleanup();
+				callback(value);
+			};
+
+			const onError = error => {
+				settle(reject, error);
+			};
+
+			const onAbort = () => {
+				if (!readableStream.destroyed) {
+					readableStream.destroy();
+				}
+
+				settle(reject, signal.reason);
+			};
+
+			const onReadable = () => {
+				(async () => {
+					try {
+						const pass = new PassThrough();
+						const outputStream = pipeline ? pipeline(readableStream, pass, () => {}) : readableStream.pipe(pass);
+						const chunk = readableStream.read(normalizedSampleSize) ?? readableStream.read() ?? new Uint8Array(0);
+						try {
+							pass.fileType = await this.fromBuffer(chunk);
+						} catch (error) {
+							if (error instanceof strtok3.EndOfStreamError) {
+								pass.fileType = undefined;
+							} else {
+								settle(reject, error);
+							}
+						}
+
+						settle(resolve, outputStream);
+					} catch (error) {
+						settle(reject, error);
+					}
+				})();
+			};
+
+			readableStream.on('error', onError);
+			readableStream.once('readable', onReadable);
+			signal?.addEventListener('abort', onAbort, {once: true});
+		});
 	}
-});
+}
+
+export async function fileTypeFromFile(path, options) {
+	return (new FileTypeParser(options)).fromFile(path, options);
+}
+
+export async function fileTypeFromStream(stream, options) {
+	return (new FileTypeParser(options)).fromStream(stream);
+}
+
+export async function fileTypeStream(readableStream, options = {}) {
+	return new FileTypeParser(options).toDetectionStream(readableStream, options);
+}
 
-module.exports = fileType;
+export {
+	fileTypeFromTokenizer,
+	fileTypeFromBuffer,
+	fileTypeFromBlob,
+	supportedMimeTypes,
+	supportedExtensions,
+} from './core.js';

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "file-type",
-	"version": "16.5.4",
-	"description": "Detect the file type of a Buffer/Uint8Array/ArrayBuffer",
+	"version": "21.3.4",
+	"description": "Detect the file type of a file, stream, or data",
 	"license": "MIT",
 	"repository": "sindresorhus/file-type",
 	"funding": "https://github.com/sindresorhus/file-type?sponsor=1",
@@ -10,18 +10,39 @@
 		"email": "sindresorhus@gmail.com",
 		"url": "https://sindresorhus.com"
 	},
+	"type": "module",
+	"exports": {
+		".": {
+			"node": {
+				"types": "./index.d.ts",
+				"import": "./index.js",
+				"module-sync": "./index.js"
+			},
+			"default": {
+				"types": "./core.d.ts",
+				"import": "./core.js",
+				"module-sync": "./core.js"
+			}
+		},
+		"./core": {
+			"types": "./core.d.ts",
+			"default": "./core.js"
+		},
+		"./node": {
+			"types": "./index.d.ts",
+			"default": "./index.js"
+		}
+	},
+	"sideEffects": false,
 	"engines": {
-		"node": ">=10"
+		"node": ">=20"
 	},
 	"scripts": {
-		"ava": "ava --serial --verbose",
 		"test": "xo && ava && tsd"
 	},
 	"files": [
 		"index.js",
 		"index.d.ts",
-		"browser.js",
-		"browser.d.ts",
 		"core.js",
 		"core.d.ts",
 		"supported.js",
@@ -44,6 +65,8 @@
 		"check",
 		"is",
 		"exif",
+		"elf",
+		"macho",
 		"exe",
 		"binary",
 		"buffer",
@@ -101,6 +124,7 @@
 		"eot",
 		"ttf",
 		"otf",
+		"ttc",
 		"ico",
 		"flv",
 		"ps",
@@ -124,6 +148,7 @@
 		"pptx",
 		"xlsx",
 		"3gp",
+		"j2c",
 		"jp2",
 		"jpm",
 		"jpx",
@@ -173,7 +198,6 @@
 		"it",
 		"s3m",
 		"xm",
-		"ai",
 		"skp",
 		"avif",
 		"eps",
@@ -185,31 +209,82 @@
 		"3mf",
 		"zst",
 		"jxl",
-		"vcf"
+		"vcf",
+		"jls",
+		"pst",
+		"dwg",
+		"parquet",
+		"class",
+		"arj",
+		"cpio",
+		"ace",
+		"avro",
+		"icc",
+		"fbx",
+		"vsdx",
+		"vtt",
+		"apk",
+		"drc",
+		"lz4",
+		"potx",
+		"xltx",
+		"dotx",
+		"xltm",
+		"ots",
+		"odg",
+		"otg",
+		"otp",
+		"ott",
+		"xlsm",
+		"docm",
+		"dotm",
+		"potm",
+		"pptm",
+		"jar",
+		"jmp",
+		"rm",
+		"sav",
+		"ppsm",
+		"ppsx",
+		"tar.gz",
+		"reg",
+		"dat"
 	],
-	"devDependencies": {
-		"@types/node": "^13.1.4",
-		"ava": "^2.3.0",
-		"noop-stream": "^0.1.0",
-		"read-chunk": "^3.2.0",
-		"tsd": "^0.11.0",
-		"xo": "^0.25.3"
-	},
 	"dependencies": {
-		"readable-web-to-node-stream": "^3.0.0",
-		"strtok3": "^6.2.4",
-		"token-types": "^4.1.1"
+		"@tokenizer/inflate": "^0.4.1",
+		"strtok3": "^10.3.4",
+		"token-types": "^6.1.1",
+		"uint8array-extras": "^1.4.0"
+	},
+	"devDependencies": {
+		"@tokenizer/token": "^0.3.0",
+		"@types/node": "^25.3.3",
+		"ava": "^7.0.0",
+		"commonmark": "^0.31.2",
+		"get-stream": "^9.0.1",
+		"noop-stream": "^1.0.0",
+		"tsd": "^0.33.0",
+		"xo": "^0.60.0"
 	},
 	"xo": {
 		"envs": [
 			"node",
 			"browser"
 		],
+		"ignores": [
+			"fixture"
+		],
 		"rules": {
 			"no-inner-declarations": "warn",
 			"no-await-in-loop": "warn",
-			"promise/prefer-await-to-then": "warn",
-			"prefer-named-capture-group": "off"
+			"no-bitwise": "off",
+			"@typescript-eslint/no-unsafe-assignment": "off",
+			"unicorn/text-encoding-identifier-case": "off",
+			"unicorn/switch-case-braces": "off",
+			"unicorn/prefer-top-level-await": "off"
 		}
+	},
+	"ava": {
+		"serial": true
 	}
 }