Extend file type (updated)

core.d.ts

@@ -421,6 +421,9 @@ export function fileTypeStream(readableStream: ReadableStream, options?: StreamO
 /**
 Detect the file type of a [`Blob`](https://nodejs.org/api/buffer.html#class-blob).
 
+@param blob
+@returns The detected file type and MIME type, or `undefined` when there is no match.
+
 @example
 ```
 import {fileTypeFromBlob} from 'file-type';
@@ -435,3 +438,93 @@ console.log(await fileTypeFromBlob(blob));
 ```
 */
 export declare function fileTypeFromBlob(blob: Blob): Promise<FileTypeResult | undefined>;
+
+/**
+Function that allows specifying custom detection mechanisms.
+
+An iterable of detectors can be provided via the fileTypeOptions argument for the {@link FileTypeParser.constructor}.
+
+The detectors are called before the default detections in the provided order.
+
+Custom detectors can be used to add new FileTypeResults or to modify return behaviour of existing FileTypeResult detections.
+
+If the detector returns `undefined`, there are 2 possible scenarios:
+
+	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 detector array which can be extended and provided via the fileTypeOptions argument:
+
+```js
+const customDetectors = [
+	async tokenizer => {
+		const unicornHeader = [85, 78, 73, 67, 79, 82, 78]; // "UNICORN" as decimal string
+		const buffer = Buffer.alloc(7);
+		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;
+	}
+]
+
+	Example usage:
+
+```js
+const buffer = ...
+const parser = new FileTypeParser({customDetectors});
+const fileType = await parser.fromBuffer(buffer);
+
+	fromStream(...), fromTokenizer(...), fromBlob(...) and toDetectingStream(...) are available in the same manner.
+
+ @param tokenizer - An [`ITokenizer`](https://github.com/Borewit/strtok3#tokenizer) usable as source of the examined file.
+ @param fileType - FileTypeResult detected by the standard detections or a previous custom detection. Undefined if no matching fileTypeResult could be found.
+ @returns supposedly detected file extension and MIME type as a FileTypeResult-like object, or `undefined` when there is no match.
+*/
+export type Detector = (tokenizer: ITokenizer, fileType?: FileTypeResult) => Promise<FileTypeResult | undefined>;
+
+export type FileTypeOptions = {
+	customDetectors?: Iterable<Detector>;
+};
+
+export declare class TokenizerPositionError extends Error {
+	constructor(message?: string);
+}
+
+export declare class FileTypeParser {
+	detectors: Iterable<Detector>;
+
+	constructor(options?: {customDetectors?: Iterable<Detector>});
+
+	/**
+	 *
+	 * Works the same way as {@link fileTypeFromBuffer}, additionally taking into account custom detectors (if any were provided to the constructor).
+	 */
+	fromBuffer(buffer: Uint8Array | ArrayBuffer): 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: ReadableStream): Promise<FileTypeResult | undefined>;
+
+	/**
+	 *
+	 * Works the same way as {@link fileTypeFromTokenizer}, additionally taking into account custom detectors (if any were provided to the constructor).
+	 */
+	fromTokenizer(tokenizer: ITokenizer): Promise<FileTypeResult | undefined>;
+
+	/**
+	 *
+	 * Works the same way as {@link fileTypeFromBlob}, additionally taking into account custom detectors (if any were provided to the constructor).
+	 */
+	fromBlob(blob: Blob): Promise<FileTypeResult | undefined>;
+
+	/**
+	 *
+	 * Works the same way as {@link fileTypeStream}, additionally taking into account custom detectors (if any were provided to the constructor).
+	 */
+	toDetectingStream(readableStream: ReadableStream, options?: StreamOptions): Promise<FileTypeResult | undefined>;
+}

core.js

@@ -11,31 +11,15 @@ import {extensions, mimeTypes} from './supported.js';
 const minimumBytes = 4100; // A fair amount of file-types are detectable within this range.
 
 export async function fileTypeFromStream(stream) {
-	const tokenizer = await strtok3.fromStream(stream);
-	try {
-		return await fileTypeFromTokenizer(tokenizer);
-	} finally {
-		await tokenizer.close();
-	}
+	return new FileTypeParser().fromStream(stream);
 }
 
 export async function fileTypeFromBuffer(input) {
-	if (!(input instanceof Uint8Array || input instanceof ArrayBuffer)) {
-		throw new TypeError(`Expected the \`input\` argument to be of type \`Uint8Array\` or \`Buffer\` or \`ArrayBuffer\`, got \`${typeof input}\``);
-	}
-
-	const buffer = input instanceof Uint8Array ? input : new Uint8Array(input);
-
-	if (!(buffer?.length > 1)) {
-		return;
-	}
-
-	return fileTypeFromTokenizer(strtok3.fromBuffer(buffer));
+	return new FileTypeParser().fromBuffer(input);
 }
 
 export async function fileTypeFromBlob(blob) {
-	const buffer = await blob.arrayBuffer();
-	return fileTypeFromBuffer(new Uint8Array(buffer));
+	return new FileTypeParser().fromBlob(blob);
 }
 
 function _check(buffer, headers, options) {
@@ -60,16 +44,98 @@ function _check(buffer, headers, options) {
 }
 
 export async function fileTypeFromTokenizer(tokenizer) {
-	try {
-		return new FileTypeParser().parse(tokenizer);
-	} catch (error) {
-		if (!(error instanceof strtok3.EndOfStreamError)) {
-			throw error;
+	return new FileTypeParser().fromTokenizer(tokenizer);
+}
+
+export class FileTypeParser {
+	constructor(options) {
+		this.detectors = options?.customDetectors;
+
+		this.fromTokenizer = this.fromTokenizer.bind(this);
+		this.fromBuffer = this.fromBuffer.bind(this);
+		this.parse = this.parse.bind(this);
+	}
+
+	async fromTokenizer(tokenizer) {
+		const initialPosition = tokenizer.position;
+
+		for (const detector of this.detectors || []) {
+			const fileType = await detector(tokenizer);
+			if (fileType) {
+				return fileType;
+			}
+
+			if (initialPosition !== tokenizer.position) {
+				return undefined; // Cannot proceed scanning of the tokenizer is at an arbitrary position
+			}
 		}
+
+		return this.parse(tokenizer);
+	}
+
+	async fromBuffer(input) {
+		if (!(input instanceof Uint8Array || input instanceof ArrayBuffer)) {
+			throw new TypeError(`Expected the \`input\` argument to be of type \`Uint8Array\` or \`Buffer\` or \`ArrayBuffer\`, got \`${typeof input}\``);
+		}
+
+		const buffer = input instanceof Uint8Array ? input : new Uint8Array(input);
+
+		if (!(buffer?.length > 1)) {
+			return;
+		}
+
+		return this.fromTokenizer(strtok3.fromBuffer(buffer));
+	}
+
+	async fromBlob(blob) {
+		const buffer = await blob.arrayBuffer();
+		return this.fromBuffer(new Uint8Array(buffer));
+	}
+
+	async fromStream(stream) {
+		const tokenizer = await strtok3.fromStream(stream);
+		try {
+			return await this.fromTokenizer(tokenizer);
+		} finally {
+			await tokenizer.close();
+		}
+	}
+
+	async toDetectingStream(readableStream, options = {}) {
+		const {default: stream} = await import('node:stream');
+		const {sampleSize = minimumBytes} = options;
+
+		return new Promise((resolve, reject) => {
+			readableStream.on('error', reject);
+
+			readableStream.once('readable', () => {
+				(async () => {
+					try {
+						// Set up output stream
+						const pass = new stream.PassThrough();
+						const outputStream = stream.pipeline ? stream.pipeline(readableStream, pass, () => {}) : readableStream.pipe(pass);
+
+						// Read the input stream and detect the filetype
+						const chunk = readableStream.read(sampleSize) ?? readableStream.read() ?? Buffer.alloc(0);
+						try {
+							pass.fileType = await this.fromBuffer(chunk);
+						} catch (error) {
+							if (error instanceof strtok3.EndOfStreamError) {
+								pass.fileType = undefined;
+							} else {
+								reject(error);
+							}
+						}
+
+						resolve(outputStream);
+					} catch (error) {
+						reject(error);
+					}
+				})();
+			});
+		});
 	}
-}
 
-class FileTypeParser {
 	check(header, options) {
 		return _check(this.buffer, header, options);
 	}
@@ -211,7 +277,7 @@ class FileTypeParser {
 			}
 
 			await tokenizer.ignore(id3HeaderLength);
-			return fileTypeFromTokenizer(tokenizer); // Skip ID3 header, recursion
+			return this.fromTokenizer(tokenizer); // Skip ID3 header, recursion
 		}
 
 		// Musepack, SV7
@@ -1602,39 +1668,8 @@ class FileTypeParser {
 	}
 }
 
-export async function fileTypeStream(readableStream, {sampleSize = minimumBytes} = {}) {
-	const {default: stream} = await import('node:stream');
-
-	return new Promise((resolve, reject) => {
-		readableStream.on('error', reject);
-
-		readableStream.once('readable', () => {
-			(async () => {
-				try {
-					// Set up output stream
-					const pass = new stream.PassThrough();
-					const outputStream = stream.pipeline ? stream.pipeline(readableStream, pass, () => {}) : readableStream.pipe(pass);
-
-					// Read the input stream and detect the filetype
-					const chunk = readableStream.read(sampleSize) ?? readableStream.read() ?? Buffer.alloc(0);
-					try {
-						const fileType = await fileTypeFromBuffer(chunk);
-						pass.fileType = fileType;
-					} catch (error) {
-						if (error instanceof strtok3.EndOfStreamError) {
-							pass.fileType = undefined;
-						} else {
-							reject(error);
-						}
-					}
-
-					resolve(outputStream);
-				} catch (error) {
-					reject(error);
-				}
-			})();
-		});
-	});
+export async function fileTypeStream(readableStream, options = {}) {
+	return new FileTypeParser().toDetectingStream(readableStream, options);
 }
 
 export const supportedExtensions = new Set(extensions);

fixture/fixture.unicorn

@@ -0,0 +1 @@
+UNICORN FILE CONTENT

index.d.ts

@@ -1,13 +1,14 @@
-import type {FileTypeResult} from './core.js';
+import type {FileTypeResult, FileTypeOptions} from './core.js';
 
 /**
 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 buffer.
 
 @param path - The file path to parse.
+@param fileTypeOptions - Optional: An options object including the `customDetectors` property as an Iterable of Detector functions. Those are called in the order provided.
 @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(path: string, fileTypeOptions?: FileTypeOptions): Promise<FileTypeResult | undefined>;
 
 export * from './core.js';

index.js

@@ -1,10 +1,11 @@
 import * as strtok3 from 'strtok3';
-import {fileTypeFromTokenizer} from './core.js';
+import {FileTypeParser} from './core.js';
 
-export async function fileTypeFromFile(path) {
+export async function fileTypeFromFile(path, fileTypeOptions) {
 	const tokenizer = await strtok3.fromFile(path);
 	try {
-		return await fileTypeFromTokenizer(tokenizer);
+		const parser = new FileTypeParser(fileTypeOptions);
+		return await parser.fromTokenizer(tokenizer);
 	} finally {
 		await tokenizer.close();
 	}