file-type 19.1.0 → 19.2.0

package/core.d.ts

@@ -341,12 +341,12 @@ If file access is available, it is recommended to use `.fromFile()` instead.
 export function fileTypeFromBuffer(buffer: Uint8Array | ArrayBuffer): Promise<FileTypeResult | undefined>;
 
 /**
-Detect the file type of a Node.js [readable stream](https://nodejs.org/api/stream.html#stream_class_stream_readable).
+Detect the file type of a [web `ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
 
 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 Node.js Readable stream or Web API Readable Stream representing file data. The Web Readable stream **must be a byte stream**.
-@returns The detected file type, or `undefined` when there is no match.
+@param stream - A [web `ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) streaming a file to examine.
+@returns A `Promise` for an object with the detected file type, or `undefined` when there is no match.
 */
 export function fileTypeFromStream(stream: AnyWebReadableStream<Uint8Array>): Promise<FileTypeResult | undefined>;
 

package/index.d.ts

@@ -3,19 +3,24 @@ Typings for Node.js specific entry point.
 */
 
 import type {Readable as NodeReadableStream} from 'node:stream';
-import type {FileTypeResult, StreamOptions, AnyWebReadableStream} from './core.js';
+import type {FileTypeResult, StreamOptions, AnyWebReadableStream, Detector} from './core.js';
 import {FileTypeParser} from './core.js';
 
 export type ReadableStreamWithFileType = NodeReadableStream & {
 	readonly fileType?: FileTypeResult;
 };
 
+/**
+Extending `FileTypeParser` with Node.js engine specific functions.
+*/
 export declare class NodeFileTypeParser extends FileTypeParser {
 	/**
-	@param stream - Node.js `stream.Readable` or Web API `ReadableStream`.
+	@param stream - Node.js `stream.Readable` or web `ReadableStream`.
 	*/
 	fromStream(stream: AnyWebReadableStream<Uint8Array> | NodeReadableStream): Promise<FileTypeResult | undefined>;
 
+	fromFile(filePath: string): Promise<FileTypeResult | undefined>;
+
 	/**
 	Works the same way as {@link fileTypeStream}, additionally taking into account custom detectors (if any were provided to the constructor).
 	*/
@@ -25,13 +30,30 @@ export declare class NodeFileTypeParser extends FileTypeParser {
 /**
 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
 @returns The detected file type and MIME type or `undefined` when there is no match.
 */
-export function fileTypeFromFile(path: string): Promise<FileTypeResult | undefined>;
+export function fileTypeFromFile(filePath: string, options?: {customDetectors?: Iterable<Detector>}): 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.
+@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): Promise<FileTypeResult | undefined>;
 
 /**

package/index.js

@@ -16,6 +16,15 @@ export class NodeFileTypeParser extends FileTypeParser {
 		}
 	}
 
+	async fromFile(path) {
+		const tokenizer = await strtok3.fromFile(path);
+		try {
+			return await super.fromTokenizer(tokenizer);
+		} finally {
+			await tokenizer.close();
+		}
+	}
+
 	async toDetectionStream(readableStream, options = {}) {
 		const {default: stream} = await import('node:stream');
 		const {sampleSize = reasonableDetectionSizeInBytes} = options;
@@ -53,13 +62,7 @@ export class NodeFileTypeParser extends FileTypeParser {
 }
 
 export async function fileTypeFromFile(path, fileTypeOptions) {
-	const tokenizer = await strtok3.fromFile(path);
-	try {
-		const parser = new FileTypeParser(fileTypeOptions);
-		return await parser.fromTokenizer(tokenizer);
-	} finally {
-		await tokenizer.close();
-	}
+	return (new NodeFileTypeParser(fileTypeOptions)).fromFile(path, fileTypeOptions);
 }
 
 export async function fileTypeFromStream(stream, fileTypeOptions) {
@@ -70,4 +73,4 @@ export async function fileTypeStream(readableStream, options = {}) {
 	return new NodeFileTypeParser().toDetectionStream(readableStream, options);
 }
 
-export {fileTypeFromBuffer, fileTypeFromBlob, FileTypeParser, supportedMimeTypes, supportedExtensions} from './core.js';
+export {fileTypeFromTokenizer, fileTypeFromBuffer, fileTypeFromBlob, FileTypeParser, supportedMimeTypes, supportedExtensions} from './core.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "file-type",
-	"version": "19.1.0",
+	"version": "19.2.0",
 	"description": "Detect the file type of a Uint8Array/ArrayBuffer",
 	"license": "MIT",
 	"repository": "sindresorhus/file-type",
@@ -208,7 +208,7 @@
 		"fbx"
 	],
 	"dependencies": {
-		"strtok3": "^7.1.0",
+		"strtok3": "^8.0.0",
 		"token-types": "^6.0.0",
 		"uint8array-extras": "^1.3.0"
 	},

package/readme.md

@@ -14,7 +14,7 @@ We accept contributions for commonly used modern file formats, not historical or
 npm install file-type
 ```
 
-**This package is a 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).**
 
 If you use it with Webpack, you need the latest Webpack version and ensure you configure it correctly for ESM.
 
@@ -130,6 +130,10 @@ A buffer representing file data. It works best if the buffer contains the entire
 
 Detect the file type of a file path.
 
+This is for Node.js only.
+
+To read from a [`File`](https://developer.mozilla.org/docs/Web/API/File), see [`fileTypeFromBlob()`](#filetypefromblobblob).
+
 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 a `Promise` for an object with the detected file type:
@@ -147,7 +151,11 @@ The file path to parse.
 
 ### fileTypeFromStream(stream)
 
-Detect the file type of a [Node.js readable stream](https://nodejs.org/api/stream.html#stream_class_stream_readable) or a [Web API ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
+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.
 
@@ -166,11 +174,14 @@ A readable stream representing file data.
 
 ### fileTypeFromBlob(blob)
 
-Detect the file type of a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
+Detect the file type of a [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob),
+
+[!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**.
 
-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.
+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.
 
 Returns a `Promise` for an object with the detected file type:
 
@@ -316,6 +327,7 @@ Returns a `Set<string>` of supported MIME types.
 A custom detector is a function that allows specifying custom detection mechanisms.
 
 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.
 
 The detectors are called before the default detections in the provided order.
 
@@ -331,7 +343,7 @@ If the detector returns `undefined`, there are 2 possible scenarios:
 Example detector array which can be extended and provided to each public method via the `fileTypeOptions` argument:
 
 ```js
-import {FileTypeParser} from 'file-type';
+import {FileTypeParser} from 'file-type'; // or `NodeFileTypeParser` in Node.js
 
 const customDetectors = [
 	async tokenizer => {
@@ -349,7 +361,7 @@ const customDetectors = [
 ];
 
 const buffer = new Uint8Array(new TextEncoder().encode('UNICORN'));
-const parser = new FileTypeParser({customDetectors});
+const parser = new FileTypeParser({customDetectors}); // `NodeFileTypeParser({customDetectors})` in Node.js
 const fileType = await parser.fromBuffer(buffer);
 console.log(fileType);
 ```