file-type 21.3.3 → 22.0.0

package/{core.d.ts → source/index.d.ts}

@@ -1,9 +1,9 @@
 /**
-Typings for primary entry point, Node.js specific typings can be found in index.d.ts
+Typings for primary entry point.
 */
 
 import type {ReadableStream as WebReadableStream} from 'node:stream/web';
-import type {ITokenizer, AnyWebByteStream} from 'strtok3';
+import type {ITokenizer} from 'strtok3';
 
 /**
 Either the Node.js ReadableStream or the `lib.dom.d.ts` ReadableStream.
@@ -28,9 +28,9 @@ Detect the file type of a `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.
 
-If file access is available, it is recommended to use `.fromFile()` instead.
+In Node.js, it is recommended to use `fileTypeFromFile()` instead when reading from a file path.
 
-@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 buffer - A 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.
 */
@@ -41,11 +41,13 @@ Detect the file type of a [web `ReadableStream`](https://developer.mozilla.org/e
 
 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.
 
+If you have a Node.js `stream.Readable`, convert it with [`Readable.toWeb()`](https://nodejs.org/api/stream.html#streamreadabletowebstreamreadable-options).
+
 @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>;
+export function fileTypeFromStream(stream: AnyWebReadableStream<Uint8Array>, options?: FileTypeOptions): Promise<FileTypeResult | undefined>;
 
 /**
 Detect the file type from an [`ITokenizer`](https://github.com/Borewit/strtok3#tokenizer) source.
@@ -58,7 +60,7 @@ A tokenizer propagates the internal read functions, allowing alternative transpo
 @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.
+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 can *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
 ```
@@ -123,10 +125,8 @@ 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`.
+Detectors provided through the constructor are executed before the default ones.
 
 ### Example adding a detector
 
@@ -139,8 +139,11 @@ const fileType = await parser.fromFile('sample.kml');
 console.log(fileType);
 ```
 
-### Available-third party file-type detectors
+### Available third-party file-type detectors
 
+- [@file-type/av](https://github.com/Borewit/file-type-av): Improves detection of audio and video file formats, with accurate differentiation between the two
+- [@file-type/cfbf](https://github.com/Borewit/file-type-cfbf): Detects Compound File Binary Format (CFBF) based formats, such as Office 97–2003 documents and `.msi`.
+- [@file-type/pdf](https://github.com/Borewit/file-type-pdf): Detects PDF based file types, such as Adobe Illustrator
 - [@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
@@ -152,13 +155,14 @@ If a detector returns `undefined`, the following rules apply:
 
 ### 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.
+Below is an example of a custom detector. This can be passed to the `FileTypeParser` via the `customDetectors` option.
 
 ```
 import {FileTypeParser} from 'file-type';
 
-const customDetectors = [
-	async tokenizer => {
+const unicornDetector = {
+	id: 'unicorn',
+	async detect(tokenizer) {
 		const unicornHeader = [85, 78, 73, 67, 79, 82, 78]; // "UNICORN" in ASCII decimal
 
 		const buffer = new Uint8Array(unicornHeader.length);
@@ -168,11 +172,11 @@ const customDetectors = [
 		}
 
 		return undefined;
-	},
-];
+	}
+};
 
 const buffer = new Uint8Array([85, 78, 73, 67, 79, 82, 78]);
-const parser = new FileTypeParser({customDetectors});
+const parser = new FileTypeParser({customDetectors: [unicornDetector]});
 const fileType = await parser.fromBuffer(buffer);
 console.log(fileType); // {ext: 'unicorn', mime: 'application/unicorn'}
 ```
@@ -189,6 +193,11 @@ export type Detector = {
 export type FileTypeOptions = {
 	customDetectors?: Iterable<Detector>;
 
+	/**
+	An `AbortSignal` to cancel the detection.
+	*/
+	signal?: AbortSignal;
+
 	/**
 	Specifies the byte tolerance for locating the first MPEG audio frame (e.g. `.mp1`, `.mp2`, `.mp3`, `.aac`).
 
@@ -196,7 +205,7 @@ export type FileTypeOptions = {
 
 	A tolerance of 10 bytes covers most cases.
 
- 	@default 0
+	@default 0
 	*/
 	mpegOffsetTolerance?: number;
 };
@@ -210,16 +219,24 @@ export type AnyWebReadableByteStreamWithFileType = AnyWebReadableStream<Uint8Arr
 };
 
 /**
-Workaround for using `bundler` as the module-resolution in TypeScript.
+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.
+
+Only available in environments where `node:fs` is available, such as Node.js. To read from a [`File`](https://developer.mozilla.org/docs/Web/API/File), see `fileTypeFromBlob()`.
+
+@param filePath - The file path to examine.
+@param options - Options to override default behavior.
+@returns The detected file type and MIME type or `undefined` when there is no match.
 */
-export function fileTypeFromFile(filePath: string, options?: {customDetectors?: Iterable<Detector>}): Promise<FileTypeResult | undefined>;
+export function fileTypeFromFile(filePath: string, 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 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 function fileTypeStream(webStream: AnyWebReadableStream<Uint8Array>, options?: StreamOptions & FileTypeOptions): Promise<AnyWebReadableByteStreamWithFileType>;
 
 export declare class FileTypeParser {
 	/**
@@ -229,7 +246,7 @@ export declare class FileTypeParser {
 	*/
 	detectors: Detector[];
 
-	constructor(options?: {customDetectors?: Iterable<Detector>; signal?: AbortSignal});
+	constructor(options?: FileTypeOptions);
 
 	/**
 	Works the same way as {@link fileTypeFromBuffer}, additionally taking into account custom detectors (if any were provided to the constructor).
@@ -246,8 +263,18 @@ export declare class FileTypeParser {
 	*/
 	fromBlob(blob: Blob): Promise<FileTypeResult | undefined>;
 
+	/**
+	Works the same way as {@link fileTypeFromStream}, additionally taking into account custom detectors (if any were provided to the constructor).
+	*/
+	fromStream(stream: AnyWebReadableStream<Uint8Array>): Promise<FileTypeResult | undefined>;
+
+	/**
+	Works the same way as {@link fileTypeFromFile}, additionally taking into account custom detectors (if any were provided to the constructor). Only available where `node:fs` is available.
+	*/
+	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).
 	*/
-	toDetectionStream(webStream: AnyWebReadableStream<Uint8Array>, options?: StreamOptions): Promise<AnyWebReadableByteStreamWithFileType>;
+	toDetectionStream(webStream: AnyWebReadableStream<Uint8Array>, options?: StreamOptions & FileTypeOptions): Promise<AnyWebReadableByteStreamWithFileType>;
 }