file-type 21.3.3 → 22.0.0

package/source/index.test-d.ts

@@ -0,0 +1,53 @@
+import {ReadableStream as NodeReadableStream} from 'node:stream/web';
+import {expectType} from 'tsd';
+import {
+	type FileTypeResult,
+	type FileTypeResult as FileTypeResultBrowser,
+	type AnyWebReadableByteStreamWithFileType,
+	fileTypeFromBlob,
+	fileTypeFromBuffer,
+	fileTypeFromFile,
+	fileTypeFromStream,
+	fileTypeStream,
+	FileTypeParser,
+} from './index.js';
+
+// `fileTypeStream`: accepts StreamOptions & FileTypeOptions
+(async () => {
+	const webStream = new ReadableStream<Uint8Array>();
+	expectType<AnyWebReadableByteStreamWithFileType>(await fileTypeStream(webStream, {sampleSize: 256}));
+	expectType<AnyWebReadableByteStreamWithFileType>(await fileTypeStream(webStream, {sampleSize: 256, customDetectors: []}));
+	expectType<AnyWebReadableByteStreamWithFileType>(await fileTypeStream(webStream, {signal: AbortSignal.timeout(1000)}));
+})();
+
+// `FileTypeParser`: tests generic input types and options
+(async () => {
+	const fileTypeParser = new FileTypeParser({customDetectors: [], signal: AbortSignal.timeout(1000)});
+	const fileTypeParserWithMpeg = new FileTypeParser({mpegOffsetTolerance: 10});
+	const webStream = new ReadableStream<Uint8Array>();
+	const nodeWebStream = new NodeReadableStream<Uint8Array>();
+
+	expectType<FileTypeResult | undefined>(await fileTypeParser.fromStream(webStream));
+	expectType<FileTypeResult | undefined>(await fileTypeParser.fromStream(nodeWebStream));
+
+	expectType<AnyWebReadableByteStreamWithFileType>(await fileTypeParser.toDetectionStream(webStream, {sampleSize: 256}));
+})();
+
+// `fileTypeFromStream`: accepts FileTypeOptions
+(async () => {
+	const webStream = new ReadableStream<Uint8Array>();
+	expectType<FileTypeResult | undefined>(await fileTypeFromStream(webStream, {signal: AbortSignal.timeout(1000)}));
+})();
+
+// Test that Blob overload returns browser-specific result
+expectType<Promise<FileTypeResultBrowser | undefined>>(fileTypeFromBlob(new Blob([])));
+
+// `fileTypeFromFile`: accepts a file path and options
+expectType<Promise<FileTypeResult | undefined>>(fileTypeFromFile('file.bin'));
+expectType<Promise<FileTypeResult | undefined>>(fileTypeFromFile('file.bin', {signal: AbortSignal.timeout(1000)}));
+
+// `FileTypeParser#fromFile`: accepts a file path
+(async () => {
+	const fileTypeParser = new FileTypeParser();
+	expectType<Promise<FileTypeResult | undefined>>(fileTypeParser.fromFile('file.bin'));
+})();

package/source/parser.js

@@ -0,0 +1,65 @@
+export const maximumUntrustedSkipSizeInBytes = 16 * 1024 * 1024;
+
+export class ParserHardLimitError extends Error {}
+
+export function getSafeBound(value, maximum, reason) {
+	if (
+		!Number.isFinite(value)
+		|| value < 0
+		|| value > maximum
+	) {
+		throw new ParserHardLimitError(`${reason} has invalid size ${value} (maximum ${maximum} bytes)`);
+	}
+
+	return value;
+}
+
+export async function safeIgnore(tokenizer, length, {maximumLength = maximumUntrustedSkipSizeInBytes, reason = 'skip'} = {}) {
+	const safeLength = getSafeBound(length, maximumLength, reason);
+	await tokenizer.ignore(safeLength);
+}
+
+export async function safeReadBuffer(tokenizer, buffer, options, {maximumLength = buffer.length, reason = 'read'} = {}) {
+	const length = options?.length ?? buffer.length;
+	const safeLength = getSafeBound(length, maximumLength, reason);
+	return tokenizer.readBuffer(buffer, {
+		...options,
+		length: safeLength,
+	});
+}
+
+export function checkBytes(buffer, headers, options) {
+	options = {
+		offset: 0,
+		...options,
+	};
+
+	for (const [index, header] of headers.entries()) {
+		// If a bitmask is set
+		if (options.mask) {
+			// If header doesn't equal `buf` with bits masked off
+			if (header !== (options.mask[index] & buffer[index + options.offset])) {
+				return false;
+			}
+		} else if (header !== buffer[index + options.offset]) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+export function hasUnknownFileSize(tokenizer) {
+	const fileSize = tokenizer.fileInfo.size;
+	return (
+		!Number.isFinite(fileSize)
+		|| fileSize === Number.MAX_SAFE_INTEGER
+	);
+}
+
+export function hasExceededUnknownSizeScanBudget(tokenizer, startOffset, maximumBytes) {
+	return (
+		hasUnknownFileSize(tokenizer)
+		&& tokenizer.position - startOffset > maximumBytes
+	);
+}

package/{supported.js → source/supported.js}

@@ -1,3 +1,5 @@
+// MIME media subtypes prefixed with `x-ft-` are custom and defined by us. They are neither formally registered with IANA nor based on any informal conventions.
+
 export const extensions = [
 	'jpg',
 	'png',
@@ -179,6 +181,9 @@ export const extensions = [
 	'tar.gz',
 	'reg',
 	'dat',
+	'key',
+	'numbers',
+	'pages',
 ];
 
 export const mimeTypes = [
@@ -262,7 +267,7 @@ export const mimeTypes = [
 	'application/x-unix-archive',
 	'application/x-rpm',
 	'application/x-compress',
-	'application/x-lzip',
+	'application/lzip',
 	'application/x-cfb',
 	'application/x-mie',
 	'application/mxf',
@@ -291,8 +296,8 @@ export const mimeTypes = [
 	'model/gltf-binary',
 	'application/vnd.tcpdump.pcap',
 	'audio/x-dsf', // Non-standard
-	'application/x.ms.shortcut', // Invented by us
-	'application/x.apple.alias', // Invented by us
+	'application/x-ms-shortcut', // Informal, used by freedesktop.org shared-mime-info
+	'application/x-ft-apple.alias',
 	'audio/x-voc',
 	'audio/vnd.dolby.dd-raw',
 	'audio/x-m4a',
@@ -332,11 +337,11 @@ export const mimeTypes = [
 	'application/x-ace-compressed',
 	'application/avro',
 	'application/vnd.iccprofile',
-	'application/x.autodesk.fbx', // Invented by us
+	'application/x-ft-fbx',
 	'application/vnd.visio',
 	'application/vnd.android.package-archive',
-	'application/vnd.google.draco', // Invented by us
-	'application/x-lz4', // Invented by us
+	'application/x-ft-draco',
+	'application/x-lz4', // Informal, used by freedesktop.org shared-mime-info
 	'application/vnd.openxmlformats-officedocument.presentationml.template',
 	'application/vnd.openxmlformats-officedocument.spreadsheetml.template',
 	'application/vnd.openxmlformats-officedocument.wordprocessingml.template',
@@ -357,4 +362,7 @@ export const mimeTypes = [
 	'application/x-ms-regedit',
 	'application/x-ft-windows-registry-hive',
 	'application/x-jmp-data',
+	'application/vnd.apple.keynote',
+	'application/vnd.apple.numbers',
+	'application/vnd.apple.pages',
 ];

package/{util.js → source/tokens.js}

@@ -32,7 +32,7 @@ Checks whether the TAR checksum is valid.
 @returns {boolean} `true` if the TAR checksum is valid, otherwise `false`.
 */
 export function tarHeaderChecksumMatches(arrayBuffer, offset = 0) {
-	const readSum = Number.parseInt(new StringType(6).get(arrayBuffer, 148).replace(/\0.*$/, '').trim(), 8); // Read sum in header
+	const readSum = Number.parseInt(new StringType(6).get(arrayBuffer, 148).replace(/\0.*$/v, '').trim(), 8); // Read sum in header
 	if (Number.isNaN(readSum)) {
 		return false;
 	}
@@ -55,6 +55,6 @@ ID3 UINT32 sync-safe tokenizer token.
 28 bits (representing up to 256MB) integer, the msb is 0 to avoid "false syncsignals".
 */
 export const uint32SyncSafeToken = {
-	get: (buffer, offset) => (buffer[offset + 3] & 0x7F) | ((buffer[offset + 2]) << 7) | ((buffer[offset + 1]) << 14) | ((buffer[offset]) << 21),
+	get: (buffer, offset) => (buffer[offset + 3] & 0x7F) | ((buffer[offset + 2] & 0x7F) << 7) | ((buffer[offset + 1] & 0x7F) << 14) | ((buffer[offset] & 0x7F) << 21),
 	len: 4,
 };

package/index.d.ts

@@ -1,98 +0,0 @@
-/**
-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>;
-
-	/**
-	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.
-
-@returns The detected file type and MIME type or `undefined` when there is no match.
-*/
-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,126 +0,0 @@
-/**
-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);
-}
-
-export class FileTypeParser extends DefaultFileTypeParser {
-	async fromStream(stream) {
-		const tokenizer = await (stream instanceof WebReadableStream ? strtok3.fromWebStream(stream, this.getTokenizerOptions()) : strtok3.fromStream(stream, this.getTokenizerOptions()));
-		try {
-			return await super.fromTokenizer(tokenizer);
-		} catch (error) {
-			if (isTokenizerStreamBoundsError(error)) {
-				return;
-			}
-
-			throw error;
-		} finally {
-			await tokenizer.close();
-		}
-	}
-
-	async fromFile(path) {
-		// 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;
-		}
-
-		const tokenizer = new strtok3.FileTokenizer(fileHandle, {
-			...this.getTokenizerOptions(),
-			fileInfo: {
-				path,
-				size: fileStat.size,
-			},
-		});
-		try {
-			return await super.fromTokenizer(tokenizer);
-		} finally {
-			await tokenizer.close();
-		}
-	}
-
-	async toDetectionStream(readableStream, options = {}) {
-		if (!(readableStream instanceof Readable)) {
-			return super.toDetectionStream(readableStream, options);
-		}
-
-		const sampleSize = normalizeSampleSize(options.sampleSize ?? reasonableDetectionSizeInBytes);
-
-		return new Promise((resolve, reject) => {
-			readableStream.on('error', reject);
-
-			readableStream.once('readable', () => {
-				(async () => {
-					try {
-						// Set up output stream
-						const pass = new PassThrough();
-						const outputStream = pipeline ? pipeline(readableStream, pass, () => {}) : readableStream.pipe(pass);
-
-						// Read the input stream and detect the filetype
-						const chunk = readableStream.read(sampleSize) ?? readableStream.read() ?? new Uint8Array(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);
-					}
-				})();
-			});
-		});
-	}
-}
-
-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);
-}
-
-export {
-	fileTypeFromTokenizer,
-	fileTypeFromBuffer,
-	fileTypeFromBlob,
-	supportedMimeTypes,
-	supportedExtensions,
-} from './core.js';