File.ts

import crypto from 'crypto';
import fs from 'fs';
import path from 'path';
import { Readable } from 'stream';
import type { GetObjectCommandOutput, S3Client } from '@aws-sdk/client-s3';
import { detectXml } from '@file-type/xml';
import contentDisposition from 'content-disposition';
import { fileTypeFromFile, FileTypeParser, ReadableStreamWithFileType } from 'file-type/node';
import { FormData, File as FormDataFile } from 'formdata-node';
import mime from 'mime-types';
import invariant from 'tiny-invariant';
import fetch, { Response } from '@smooai/fetch';
import ServerLogger from '@smooai/logger/AwsServerLogger';
import { FileContentMismatchError, FileMimeError, FileSizeError, FileValidationError } from './errors';

export { FileContentMismatchError, FileMimeError, FileSizeError, FileValidationError, FileValidationKind } from './errors';

const logger = new ServerLogger();

const parser = new FileTypeParser({
    customDetectors: [detectXml],
});

/**
 * Loads the AWS SDK on first S3 use rather than at import time.
 *
 * `require('@aws-sdk/client-s3')` costs ~110ms, and it used to be paid by every
 * consumer of this package on `import File from '@smooai/file'` — including the
 * many that only ever read local files. The two `import type`s above are erased
 * at compile time, so nothing pulls the SDK in until an S3 method is called.
 *
 * The dynamic import is memoised by the module system, so this is one load per
 * process, not one per call.
 */
const loadS3 = () => import('@aws-sdk/client-s3');
const loadPresigner = () => import('@aws-sdk/s3-request-presigner');

const buildS3Client = async (): Promise<S3Client> => {
    const { S3Client: Client } = await loadS3();
    return new Client({ apiVersion: '2023-11-01' });
};

/**
 * Bytes pulled from a stream up-front for magic-byte detection, before the rest
 * of the payload is left un-buffered.
 *
 * The same 64 KiB in all five ports (`LAZY_HEAD_BYTES` / `_HEAD_BYTES` /
 * `streamHeadBytes` / `LazyHeadBytes`). The value is pinned by the shared
 * contract fixture at `spec/lazy-stream-contract.json`, which every port's test
 * suite loads — change it here and four other suites go red.
 */
export const LAZY_HEAD_BYTES = 64 * 1024;

const toDetectionStream = (stream: NodeJS.ReadableStream) => parser.toDetectionStream(stream as Readable, { sampleSize: LAZY_HEAD_BYTES });

/**
 * Represents metadata about a file including its properties and attributes.
 * @interface
 * @example
 * const metadata: Metadata = {
 *   name: 'example.txt',
 *   mimeType: 'text/plain',
 *   size: 1024,
 *   extension: 'txt',
 *   url: 'https://example.com/file.txt',
 *   path: '/path/to/file.txt',
 *   hash: 'abc123',
 *   lastModified: new Date(),
 *   createdAt: new Date()
 * };
 */
export interface Metadata {
    name?: string;
    mimeType?: string;
    size?: number;
    extension?: string;
    url?: string;
    path?: string;
    response?: Response;
    hash?: string;
    lastModified?: Date;
    createdAt?: Date;
}

/**
 * A partial set of metadata properties that can be used as hints when creating a file.
 * @type {Partial<Metadata>}
 * @example
 * const hint: MetadataHint = {
 *   name: 'document.pdf',
 *   mimeType: 'application/pdf'
 * };
 */
export type MetadataHint = Partial<Metadata>;

/**
 * Enumeration of possible file sources.
 * @enum {string}
 * @example
 * const source = FileSource.Url; // For files loaded from URLs
 * const source = FileSource.Bytes; // For files created from byte arrays
 * const source = FileSource.File; // For files from the filesystem
 * const source = FileSource.Stream; // For files from streams
 * const source = FileSource.S3; // For files from Amazon S3
 */
export enum FileSource {
    Url = 'Url',
    Bytes = 'Bytes',
    File = 'File',
    Stream = 'Stream',
    S3 = 'S3',
}

/**
 * A class representing a file with various operations and properties.
 * This class provides methods to create, read, write, and manipulate files from different sources.
 * @class
 * @example
 * // Create a file from URL
 * const file = await File.createFromUrl('https://example.com/file.txt');
 *
 * // Create a file from local filesystem
 * const file = await File.createFromFile('/path/to/file.txt');
 *
 * // Create a file from S3
 * const file = await File.createFromS3('my-bucket', 'path/to/file.txt');
 *
 * // Create a file from bytes
 * const file = await File.createFromBytes(new Uint8Array([1, 2, 3]));
 *
 * // Create a file from stream
 * const file = await File.createFromStream(readableStream);
 */
export default class File {
    private s3ClientPromise: Promise<S3Client> | undefined;

    /** The instance's S3 client, built on first use. See {@link buildS3Client}. */
    private s3Client(): Promise<S3Client> {
        this.s3ClientPromise ??= buildS3Client();
        return this.s3ClientPromise;
    }

    private fileSource!: FileSource;
    private _stream!: ReadableStreamWithFileType;
    private _metadata!: Metadata;
    private bytes: ArrayBufferLike | undefined;

    private get stream(): ReadableStreamWithFileType {
        return this._stream;
    }

    private set stream(value: ReadableStreamWithFileType) {
        this._stream = value;
    }

    get metadata(): Metadata {
        return this._metadata;
    }

    get name(): string | undefined {
        return this._metadata.name;
    }

    get mimeType(): string | undefined {
        return this._metadata.mimeType;
    }

    get size(): number | undefined {
        return this._metadata.size;
    }

    get extension(): string | undefined {
        return this._metadata.extension;
    }

    get url(): string | undefined {
        return this._metadata.url;
    }

    get path(): string | undefined {
        return this._metadata.path;
    }

    get hash(): string | undefined {
        return this._metadata.hash;
    }

    get lastModified(): Date | undefined {
        return this._metadata.lastModified;
    }

    get createdAt(): Date | undefined {
        return this._metadata.createdAt;
    }

    get source(): FileSource {
        return this.fileSource;
    }

    /**
     * Whether the payload is still un-buffered — only the detection head has
     * been pulled and the rest is still in the source stream.
     *
     * Goes false once the bytes have been materialised, by {@link readFileBytes},
     * {@link pipeTo}, {@link uploadToS3}, or an eager constructor. Mirrors
     * `is_lazy` / `IsLazy` in the other ports.
     */
    get isLazy(): boolean {
        return this.bytes === undefined;
    }

    private set metadata(value: Metadata) {
        this._metadata = value;
    }

    private constructor(fileSource: FileSource, stream: ReadableStreamWithFileType, metadata: Metadata, bytes?: ArrayBufferLike) {
        logger.info({ metadata }, 'File created');
        this.fileSource = fileSource;
        this.stream = stream;
        this.metadata = metadata;
        this.bytes = bytes;
    }

    private clone(other: File): File {
        this.fileSource = other.fileSource;
        this.stream = other.stream;
        this.metadata = other.metadata;
        this.bytes = other.bytes;
        return this;
    }

    private async refresh() {
        if (this.fileSource === FileSource.File && this.metadata.path) {
            const newFile = await File.createFromFile(this.metadata.path);
            this.clone(newFile);
        } else if (this.fileSource === FileSource.S3 && this.metadata.url) {
            const [bucket, key] = this.metadata.url.replace('s3://', '').split('/', 2);
            const newFile = await File.createFromS3(bucket, key);
            this.clone(newFile);
        } else if (this.fileSource === FileSource.Url && this.metadata.url) {
            const newFile = await File.createFromUrl(this.metadata.url);
            this.clone(newFile);
        } else if (this.fileSource === FileSource.Bytes && this.bytes) {
            const newFile = await File.createFromBytes(this.bytes);
            this.clone(newFile);
        } else if (this.fileSource === FileSource.Stream && this.stream) {
            const newFile = await File.createFromStream(this.stream);
            this.clone(newFile);
        } else {
            throw new Error(`Cannot refresh file from source: ${this.fileSource}`);
        }
    }

    private static webStreamToNodeStream(webStream: ReadableStream): Readable {
        // Create a single reader instance for the entire lifetime of the node stream.
        const reader = webStream.getReader();

        return new Readable({
            async read() {
                try {
                    const { done, value } = await reader.read();
                    if (done) {
                        this.push(null);
                    } else {
                        // Ensure value is a Buffer; adjust if your data is already a Buffer
                        this.push(Buffer.from(value));
                    }
                } catch (error) {
                    this.destroy(error as Error);
                }
            },
        });
    }

    /**
     * Creates a new File instance from a URL.
     * @param {string} url - The URL to load the file from
     * @param {MetadataHint} [metadataHint] - Optional metadata hints
     * @returns {Promise<File>} A new File instance
     * @example
     * const file = await File.createFromUrl('https://example.com/file.txt');
     */
    static async createFromUrl(url: string, metadataHint?: MetadataHint): Promise<File> {
        const response = await fetch(url);
        invariant(response.body, 'Response body is missing');

        // Clone the stream so we can use it multiple times if needed
        const webStream = response.body as unknown as ReadableStream;
        const nodeStream = File.webStreamToNodeStream(webStream.tee()[0]);
        const typedStream = await toDetectionStream(nodeStream);

        const metadata = await File.getFileMetadata({
            metadataHint: {
                ...metadataHint,
                url,
            },
            fileSource: FileSource.Url,
            internalResponse: response,
            stream: typedStream,
        });
        return new File(FileSource.Url, typedStream, metadata);
    }

    /**
     * Creates a new File instance from an S3 bucket and key.
     * @param {string} bucket - The S3 bucket name
     * @param {string} key - The S3 object key
     * @param {MetadataHint} [metadataHint] - Optional metadata hints
     * @returns {Promise<File>} A new File instance
     * @example
     * const file = await File.createFromS3('my-bucket', 'path/to/file.txt');
     */
    static async createFromS3(bucket: string, key: string, metadataHint?: MetadataHint): Promise<File> {
        const { GetObjectCommand } = await loadS3();
        const command = new GetObjectCommand({
            Bucket: bucket,
            Key: key,
        });
        const s3Client = await buildS3Client();
        const response = await s3Client.send(command);
        invariant(response.Body, 'Response body is missing');

        const typedStream = await toDetectionStream(new Readable().wrap(response.Body as unknown as NodeJS.ReadableStream));

        const metadata = await File.getFileMetadata({
            metadataHint: {
                ...metadataHint,
                url: `s3://${bucket}/${key}`,
                name: path.basename(key),
            },
            fileSource: FileSource.S3,
            stream: typedStream,
            s3Response: response,
        });
        return new File(FileSource.S3, typedStream, metadata);
    }

    /**
     * Creates a new File instance from a byte array.
     * @param {ArrayBuffer} bytes - The byte array to create the file from
     * @param {MetadataHint} [metadataHint] - Optional metadata hints
     * @returns {Promise<File>} A new File instance
     * @example
     * const file = await File.createFromBytes(new Uint8Array([1, 2, 3]));
     */
    static async createFromBytes(bytes: ArrayBufferLike, metadataHint?: MetadataHint): Promise<File> {
        const nodeStream = new Readable();
        nodeStream.push(Buffer.from(bytes));
        nodeStream.push(null);
        nodeStream.pause();
        const typedStream = await toDetectionStream(nodeStream);

        const metadata = await File.getFileMetadata({
            metadataHint: {
                ...metadataHint,
                size: bytes.byteLength,
            },
            fileSource: FileSource.Bytes,
            stream: typedStream,
        });
        return new File(FileSource.Bytes, typedStream, metadata, bytes);
    }

    /**
     * Creates a new File instance from a Web `File` or `Blob` object — the kind you
     * get from Hono `c.req.formData()`, Next.js server actions, or browser `<input type="file">`.
     * Name and mime-type hints from the web File are preserved so validation and
     * uploads don't have to re-derive them.
     * @param {Blob | { name?: string; type?: string; arrayBuffer(): Promise<ArrayBuffer> }} webFile -
     *   A Web `File` or `Blob`. Only `arrayBuffer()` is required; `name` / `type` are read if present.
     * @param {MetadataHint} [metadataHint] - Optional metadata hints that override webFile's hints.
     * @returns {Promise<File>} A new File instance
     * @example
     * // In a Hono multipart route
     * const form = await c.req.formData();
     * const uploadedFile = form.get('file') as File;
     * const file = await SmooFile.createFromWebFile(uploadedFile);
     * await file.validate({ maxSize: 5 * 1024 * 1024, allowedMimes: ['image/png', 'image/jpeg'] });
     */
    static async createFromWebFile(webFile: Blob & { name?: string; type?: string }, metadataHint?: MetadataHint): Promise<File> {
        const bytes = await webFile.arrayBuffer();
        return File.createFromBytes(bytes, {
            name: webFile.name,
            mimeType: webFile.type || undefined,
            ...metadataHint,
        });
    }

    /**
     * Generates a presigned S3 PUT URL so a client can upload directly to S3
     * without routing bytes through the server. Optional `maxSize` is baked into
     * the signature so the client cannot upload a larger object than allowed.
     *
     * Centralizes the "server signs, client uploads" pattern so call sites don't
     * each manage their own S3 client and PutObjectCommand.
     *
     * @param options - Upload parameters
     * @param options.bucket - The S3 bucket name
     * @param options.key - The S3 object key the client will PUT to
     * @param options.contentType - Expected Content-Type header the client must send (signed)
     * @param options.expiresIn - URL validity in seconds (default 3600)
     * @param options.maxSize - Optional max content length in bytes; if provided,
     *   the signed URL will reject uploads larger than this via the
     *   `x-amz-content-length-range` check. Not all HTTP clients send this, so
     *   servers should still validate on a subsequent HEAD.
     * @returns {Promise<string>} The presigned URL
     * @example
     * const url = await SmooFile.createPresignedUploadUrl({
     *   bucket: Resource.Bucket.name,
     *   key: `avatars/${userId}.png`,
     *   contentType: 'image/png',
     *   expiresIn: 600,
     *   maxSize: 2 * 1024 * 1024,
     * });
     */
    static async createPresignedUploadUrl(options: {
        bucket: string;
        key: string;
        contentType?: string;
        expiresIn?: number;
        maxSize?: number;
    }): Promise<string> {
        const { bucket, key, contentType, expiresIn = 3600, maxSize } = options;
        const [{ PutObjectCommand }, { getSignedUrl }] = await Promise.all([loadS3(), loadPresigner()]);
        const client = await buildS3Client();
        const command = new PutObjectCommand({
            Bucket: bucket,
            Key: key,
            ContentType: contentType,
            ContentLength: maxSize,
        });
        return getSignedUrl(client, command, { expiresIn });
    }

    /**
     * Creates a new File instance from a local file path.
     * @param {string} filePath - The path to the local file
     * @param {MetadataHint} [metadataHint] - Optional metadata hints
     * @returns {Promise<File>} A new File instance
     * @example
     * const file = await File.createFromFile('/path/to/file.txt');
     */
    static async createFromFile(filePath: string, metadataHint?: MetadataHint): Promise<File> {
        const nodeStream = new Readable().wrap(fs.createReadStream(filePath)).pause();
        const typedStream = await toDetectionStream(nodeStream);

        const metadata = await File.getFileMetadata({
            metadataHint: {
                ...metadataHint,
                path: filePath,
                name: path.basename(filePath),
            },
            fileSource: FileSource.File,
            stream: typedStream,
        });
        return new File(FileSource.File, typedStream, metadata);
    }

    /**
     * Creates a new File instance from a readable stream, buffering the whole
     * payload up-front so `size` is exact and the bytes can be read repeatedly.
     *
     * Use {@link createFromStreamLazy} when the payload may be large: it pulls
     * only {@link LAZY_HEAD_BYTES} for detection and leaves the tail in the
     * stream.
     *
     * @param {NodeJS.ReadableStream} stream - The readable stream
     * @param {MetadataHint} [metadataHint] - Optional metadata hints
     * @returns {Promise<File>} A new File instance
     * @example
     * const file = await File.createFromStream(readableStream);
     */
    static async createFromStream(stream: NodeJS.ReadableStream, metadataHint?: MetadataHint): Promise<File> {
        const file = await File.createFromStreamLazy(stream, metadataHint);
        // Eager contract, matching `from_stream` in the other four ports: the
        // payload is in memory and `size` is the real byte count when we return.
        await file.readFileBytes();
        return file;
    }

    /**
     * Creates a new File instance from a readable stream **without** buffering
     * the whole payload.
     *
     * Only the first {@link LAZY_HEAD_BYTES} are pulled, for magic-byte
     * detection; the tail stays in the stream and is consumed by
     * {@link readFileBytes}, {@link iterBytes}, {@link pipeTo}, or
     * {@link uploadToS3}. This is the path that gets a multi-GB upload through
     * a memory-constrained process.
     *
     * `size` stays undefined unless you hint it or the source turned out to be
     * shorter than the detection head — the tail has not been measured yet.
     *
     * Mirrors `from_stream(lazy=True)` (Python), `from_stream_lazy` (Rust),
     * `NewFromStreamLazy` (Go) and `CreateFromStreamLazyAsync` (.NET). The
     * shared semantics are pinned by `spec/lazy-stream-contract.json`.
     *
     * @param {NodeJS.ReadableStream} stream - The readable stream
     * @param {MetadataHint} [metadataHint] - Optional metadata hints
     * @returns {Promise<File>} A new File instance
     * @example
     * const file = await File.createFromStreamLazy(req);
     * await file.validate({ allowedMimes: ['image/png'] }); // head is enough
     * await file.uploadToS3('bucket', 'key');               // tail streams through
     */
    static async createFromStreamLazy(stream: NodeJS.ReadableStream, metadataHint?: MetadataHint): Promise<File> {
        const nodeStream = new Readable().wrap(stream).pause();
        const head = await File.readHead(nodeStream);
        // A source that ran dry inside the head is already fully in memory, so
        // there is nothing to be lazy about — fall back to the eager shape and
        // report the exact size, exactly as the other four ports do.
        const sourceExhausted = head.byteLength < LAZY_HEAD_BYTES;

        // An exhausted source has already emitted 'end', and unshifting after that
        // throws — replay the head from a fresh stream instead. Otherwise put the
        // head back in front of the tail we haven't touched.
        let rest: Readable;
        if (sourceExhausted) {
            rest = Readable.from([head]).pause();
        } else {
            nodeStream.unshift(head);
            rest = nodeStream;
        }

        const typedStream = await toDetectionStream(rest);
        const metadata = await File.getFileMetadata({
            metadataHint: sourceExhausted ? { size: head.byteLength, ...metadataHint } : metadataHint,
            fileSource: FileSource.Stream,
            stream: typedStream,
        });
        const file = new File(FileSource.Stream, typedStream, metadata);
        if (sourceExhausted) {
            await file.readFileBytes();
        }
        return file;
    }

    /**
     * Pulls up to {@link LAZY_HEAD_BYTES} off a paused stream, leaving the rest.
     *
     * Deliberately not `for await ... break`: breaking out of a Readable's async
     * iterator destroys the stream, taking the tail with it.
     */
    private static readHead(stream: Readable): Promise<Buffer> {
        return new Promise((resolve, reject) => {
            const chunks: Buffer[] = [];
            let total = 0;

            const finish = (fn: () => void) => {
                stream.off('readable', onReadable);
                stream.off('end', onDone);
                stream.off('error', onError);
                fn();
            };
            const onReadable = () => {
                let chunk: Buffer | null;
                while (total < LAZY_HEAD_BYTES && (chunk = stream.read()) !== null) {
                    chunks.push(chunk);
                    total += chunk.byteLength;
                }
                if (total >= LAZY_HEAD_BYTES) {
                    finish(() => resolve(Buffer.concat(chunks)));
                }
            };
            const onDone = () => finish(() => resolve(Buffer.concat(chunks)));
            const onError = (error: Error) => finish(() => reject(error));

            stream.on('readable', onReadable);
            stream.on('end', onDone);
            stream.on('error', onError);
        });
    }

    private static getFilenameFromUrl(urlString: string | undefined): string | null {
        if (!urlString) {
            return null;
        }

        try {
            const url = new URL(urlString);
            const pathname = url.pathname;
            const filename = path.basename(pathname);
            // Return filename if it's non-empty and not just a directory indicator
            return filename && filename !== '/' ? filename : null;
        } catch (_error) {
            return null;
        }
    }

    static async getFileMetadata(options: {
        fileSource: FileSource;
        metadataHint?: MetadataHint;
        internalResponse?: Response;
        stream?: ReadableStreamWithFileType;
        s3Response?: GetObjectCommandOutput;
    }): Promise<Metadata> {
        let name: string | undefined = options.metadataHint?.name;
        let extension: string | undefined = options.metadataHint?.extension;
        let mimeType: string | undefined = options.metadataHint?.mimeType;
        let size: number | undefined = options.metadataHint?.size;
        let hash: string | undefined = options.metadataHint?.hash;
        let lastModified: Date | undefined = options.metadataHint?.lastModified;
        let createdAt: Date | undefined = options.metadataHint?.createdAt;
        const response = options.internalResponse ?? options.metadataHint?.response ?? (undefined as unknown as Response);
        const path = options.metadataHint?.path;
        const url = options.metadataHint?.url;

        let stream = options.stream;
        if (!stream && response?.body) {
            // @smooai/fetch should provide a Web ReadableStream
            const nodeStream = new Readable().wrap(response.body as unknown as NodeJS.ReadableStream).pause();
            stream = await toDetectionStream(nodeStream);
        }

        if (response) {
            const contentDispositionValue = response.headers.get('content-disposition');
            const contentType = response.headers.get('content-type');
            const contentLength = response.headers.get('content-length');
            const etag = response.headers.get('etag');
            const lastModifiedHeader = response.headers.get('last-modified');
            const contentMD5 = response.headers.get('content-md5');

            const disposition = contentDispositionValue ? contentDisposition.parse(contentDispositionValue) : undefined;
            name = disposition?.parameters?.filename ?? File.getFilenameFromUrl(url) ?? name;
            size = contentLength !== null && contentLength !== undefined ? Number(contentLength) : size;
            mimeType = contentType ?? (name ? mime.lookup(name) || null : null) ?? mimeType;

            if (etag) {
                hash = etag.replace(/"/g, '');
            } else if (contentMD5) {
                hash = contentMD5;
            }

            if (lastModifiedHeader) {
                lastModified = new Date(lastModifiedHeader);
            }

            logger.debug({ name, size, mimeType, hash, lastModified }, 'File metadata parsed from response headers');
        }

        if (options.s3Response) {
            const contentDispositionValue = options.s3Response.ContentDisposition;
            const contentType = options.s3Response.ContentType;
            const contentLength = options.s3Response.ContentLength;
            const etag = options.s3Response.ETag;
            const lastModifiedHeader = options.s3Response.LastModified;

            const disposition = contentDispositionValue ? contentDisposition.parse(contentDispositionValue) : undefined;
            name = disposition?.parameters?.filename ?? name;
            size = contentLength !== null && contentLength !== undefined ? Number(contentLength) : size;
            mimeType = contentType ?? (name ? mime.lookup(name) || null : null) ?? mimeType;

            if (etag) {
                hash = etag.replace(/"/g, '');
            }

            if (lastModifiedHeader) {
                lastModified = new Date(lastModifiedHeader);
            }

            logger.debug({ name, size, mimeType, hash, lastModified }, 'File metadata parsed from S3 response headers');
        }

        if (options.fileSource === FileSource.File && path) {
            const fileType = await fileTypeFromFile(path, {
                customDetectors: [detectXml],
            });
            mimeType = fileType && fileType.mime ? fileType.mime : mimeType;
            extension = fileType && fileType.ext ? fileType.ext : extension;

            const stats = await fs.promises.stat(path);
            size = stats.size;
            lastModified = stats.mtime;
            createdAt = stats.birthtime;

            logger.debug({ mimeType, extension, size, lastModified, createdAt }, 'File metadata parsed from file system');
        }

        if (!mimeType && name) {
            mimeType = (mime.lookup(name) || null) ?? mimeType;
            logger.debug({ mimeType }, 'Mime type detected from file name');
        }

        if (stream) {
            logger.debug('Detecting mime type from stream');
            mimeType = stream.fileType?.mime ?? mimeType;
            extension = stream.fileType?.ext ?? extension;
            logger.debug(`Detected mime type: ${mimeType}, extenstion: ${extension}`);
        }

        if (!extension && mimeType) {
            extension = (mime.extension(mimeType) || null) ?? extension;
        }

        return <Metadata>{
            name,
            mimeType,
            size,
            extension,
            url,
            path,
            hash,
            lastModified,
            createdAt,
        };
    }

    /**
     * Reads the file contents as bytes.
     * @returns {Promise<ArrayBuffer>} The file contents as an ArrayBuffer
     * @example
     * const bytes = await file.readFileBytes();
     */
    async readFileBytes(): Promise<ArrayBufferLike> {
        return (await this.toBuffer()).buffer as ArrayBufferLike;
    }

    /**
     * Yields the file contents chunk by chunk without ever holding the whole
     * payload in memory — the read side of lazy streaming, and the counterpart
     * to `iter_bytes` / `IterBytes` in the Python, Rust, and Go ports.
     *
     * Iterating a lazy file **consumes** the tail and does not cache it, so a
     * later {@link readFileBytes} sees only what remains. Call
     * {@link readFileBytes} instead when you need the bytes more than once.
     *
     * @example
     * for await (const chunk of file.iterBytes()) {
     *     hash.update(chunk);
     * }
     */
    async *iterBytes(): AsyncGenerator<Buffer, void, undefined> {
        if (this.bytes) {
            yield Buffer.from(this.bytes);
            return;
        }

        for await (const chunk of this.stream) {
            yield Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array);
        }
    }

    /**
     * Reads the file contents as a string.
     * @returns {Promise<string>} The file contents as a UTF-8 string
     * @example
     * const content = await file.readFileString();
     */
    async readFileString(): Promise<string> {
        const bytes = Buffer.from(await this.readFileBytes());
        return bytes.toString('utf-8');
    }

    /**
     * Reads the file contents and returns a base64-encoded string. Useful for
     * email attachments, data URLs, and APIs that require inline-encoded file bytes.
     * @returns {Promise<string>} The file contents encoded as base64
     * @example
     * const b64 = await file.toBase64();
     * sendEmail({ attachments: [{ filename: file.name, content: b64, encoding: 'base64' }] });
     */
    async toBase64(): Promise<string> {
        const bytes = await this.readFileBytes();
        return Buffer.from(bytes).toString('base64');
    }

    /**
     * Validates the file against size, allowed-mime, and content-vs-claim rules.
     * Throws a typed {@link FileValidationError} subclass on failure so callers
     * (e.g. HTTP routes) can cleanly map to a 400 response without parsing messages.
     *
     * @param options - Validation rules. Any subset may be provided.
     * @param options.maxSize - Maximum allowed size in bytes. Throws {@link FileSizeError} on failure.
     * @param options.allowedMimes - Allowlist of acceptable mime types. Throws {@link FileMimeError}
     *   if the file's mime type is not in the list. Uses the file's detected or hinted mime type.
     * @param options.expectedMimeType - If provided, compares the magic-byte-detected
     *   mime type against this expected value. Throws {@link FileContentMismatchError} if they
     *   disagree — the primary defense against mime-spoofing (e.g. a `.php` file uploaded as
     *   `image/png`). Pass the client-claimed `Content-Type` header here for upload validation.
     *
     * @example
     * // In a multipart upload route
     * try {
     *   await file.validate({
     *     maxSize: 5 * 1024 * 1024,
     *     allowedMimes: ['image/png', 'image/jpeg', 'image/webp'],
     *     expectedMimeType: uploadedFile.type, // the browser-sent Content-Type
     *   });
     * } catch (err) {
     *   if (err instanceof FileValidationError) {
     *     throw new HTTPException(400, { message: err.message });
     *   }
     *   throw err;
     * }
     */
    async validate(options: { maxSize?: number; allowedMimes?: readonly string[]; expectedMimeType?: string }): Promise<void> {
        const { maxSize, allowedMimes, expectedMimeType } = options;

        if (maxSize !== undefined) {
            const size = this.metadata.size;
            if (size === undefined || size > maxSize) {
                throw new FileSizeError(size, maxSize);
            }
        }

        if (allowedMimes !== undefined && allowedMimes.length > 0) {
            const mimeType = this.metadata.mimeType;
            if (!mimeType || !allowedMimes.includes(mimeType)) {
                throw new FileMimeError(mimeType, allowedMimes);
            }
        }

        if (expectedMimeType !== undefined) {
            // Magic-byte detection was performed during construction via
            // FileTypeParser.toDetectionStream — stream.fileType holds that result.
            // If detection disagrees with the caller's stated expectation, the
            // upload's content does not match what the client claimed.
            const detected = this._stream.fileType?.mime;
            if (!detected || detected !== expectedMimeType) {
                throw new FileContentMismatchError(expectedMimeType, detected);
            }
        }
    }

    /**
     * Converts the file to a FormData object.
     * @param {string} [attrName='file'] - The name of the form field
     * @returns {Promise<FormData>} A FormData object containing the file
     * @example
     * const formData = await file.toFormData('document');
     */
    async toFormData(attrName = 'file'): Promise<FormData> {
        const form = new FormData();
        form.append(attrName, new FormDataFile([await this.readFileBytes()], this.metadata.name ?? ''));
        return form;
    }

    /**
     * Returns a string representation of the file.
     * @returns {string} A JSON string containing the file metadata
     * @example
     * console.log(file.toString());
     */
    toString(): string {
        return JSON.stringify({
            ...this.metadata,
            fileSource: this.fileSource,
        });
    }

    /**
     * Saves the file to a new location on the filesystem.
     * @param {string} destinationPath - The path where the file should be saved
     * @returns {Promise<{original: File, newFile: File}>} The original and new file instances
     * @example
     * const { original, newFile } = await file.saveToFile('/path/to/new/location.txt');
     */
    async saveToFile(destinationPath: string): Promise<{ original: File; newFile: File }> {
        const writeStream = fs.createWriteStream(destinationPath);
        await this.pipeTo(writeStream);
        return {
            original: this,
            newFile: await File.createFromFile(destinationPath),
        };
    }

    /**
     * Moves the file to a new location on the filesystem.
     * @param {string} destinationPath - The new path for the file
     * @returns {Promise<File>} The new file instance
     * @example
     * const newFile = await file.moveTo('/path/to/new/location.txt');
     */
    async moveTo(destinationPath: string): Promise<File> {
        if (this.fileSource === FileSource.File && this.metadata.path) {
            const result = await this.saveToFile(destinationPath);
            await fs.promises.unlink(this.metadata.path);
            return result.newFile;
        } else {
            const result = await this.saveToFile(destinationPath);
            return result.newFile;
        }
    }

    /**
     * Deletes the file from the filesystem.
     * @returns {Promise<void>}
     * @example
     * await file.delete();
     */
    async delete(): Promise<void> {
        if (this.fileSource === FileSource.File && this.metadata.path) {
            await fs.promises.unlink(this.metadata.path);
        }
    }

    /**
     * Pipes the file contents to a writable stream.
     * @param {NodeJS.WritableStream} destination - The destination writable stream
     * @param {Object} options - Pipe options
     * @param {boolean} [options.saveBytes=true] - Whether to save the bytes in memory
     * @returns {Promise<void>}
     * @example
     * await file.pipeTo(writableStream);
     */
    async pipeTo(
        destination: NodeJS.WritableStream,
        options: {
            saveBytes?: boolean;
        } = { saveBytes: true },
    ): Promise<void> {
        const { saveBytes } = options;
        if (this.bytes) {
            const buffer = Buffer.from(this.bytes);
            return new Promise((resolve, reject) => {
                destination.write(buffer, (err) => {
                    if (err) reject(err);
                    resolve();
                });
            });
        }

        const reader = this.stream;
        const nodeStream = new Readable().wrap(reader);

        return new Promise((resolve, reject) => {
            nodeStream.on('error', reject);
            destination.on('error', reject);
            destination.on('finish', resolve);
            nodeStream.on('data', (chunk) => {
                if (saveBytes) {
                    this.bytes = Buffer.concat([!this.bytes ? Buffer.from([]) : Buffer.from(this.bytes), chunk]).buffer;
                }
            });

            nodeStream.pipe(destination);
        });
    }

    /**
     * Uploads the file to an S3 bucket.
     * @param {string} bucket - The S3 bucket name
     * @param {string} key - The S3 object key
     * @returns {Promise<void>}
     * @example
     * await file.uploadToS3('my-bucket', 'path/to/file.txt');
     */
    async uploadToS3(bucket: string, key: string): Promise<void> {
        const body = await this.toBuffer();

        const { PutObjectCommand } = await loadS3();
        const command = new PutObjectCommand({
            Bucket: bucket,
            Key: key,
            Body: body,
            ContentType: this.metadata.mimeType,
            ContentLength: body.byteLength,
            ContentDisposition: this.metadata.name ? `attachment; filename="${this.metadata.name}"` : undefined,
        });

        await (await this.s3Client()).send(command);
    }

    /**
     * Saves the file to S3 and returns both the original and new file instances.
     * @param {string} bucket - The S3 bucket name
     * @param {string} key - The S3 object key
     * @returns {Promise<{original: File, newFile: File}>} The original and new file instances
     * @example
     * const { original, newFile } = await file.saveToS3('my-bucket', 'path/to/file.txt');
     */
    async saveToS3(bucket: string, key: string): Promise<{ original: File; newFile: File }> {
        // Upload to S3 and create new file instance
        const body = await this.toBuffer();
        const { PutObjectCommand } = await loadS3();
        const command = new PutObjectCommand({
            Bucket: bucket,
            Key: key,
            Body: body,
            ContentType: this.metadata.mimeType,
            ContentLength: body.byteLength,
            ContentDisposition: this.metadata.name ? `attachment; filename="${this.metadata.name}"` : undefined,
        });

        await (await this.s3Client()).send(command);

        // Create new file instance
        const newFile = await File.createFromS3(bucket, key);

        return { original: this, newFile };
    }

    /**
     * Moves the file to S3 and returns the new file instance.
     * @param {string} bucket - The S3 bucket name
     * @param {string} key - The S3 object key
     * @returns {Promise<File>} The new file instance
     * @example
     * const newFile = await file.moveToS3('my-bucket', 'path/to/file.txt');
     */
    async moveToS3(bucket: string, key: string): Promise<File> {
        // Upload to S3 and get new file instance
        const { PutObjectCommand } = await loadS3();
        const command = new PutObjectCommand({
            Bucket: bucket,
            Key: key,
            Body: await this.toBuffer(),
            ContentType: this.metadata.mimeType,
            ContentLength: this.metadata.size,
            ContentDisposition: this.metadata.name ? `attachment; filename="${this.metadata.name}"` : undefined,
        });

        await (await this.s3Client()).send(command);

        // If this is a file on disk, delete it
        if (this.fileSource === FileSource.File && this.metadata.path) {
            await fs.promises.unlink(this.metadata.path);
        }

        return File.createFromS3(bucket, key);
    }

    /**
     * Checks if the file exists on the filesystem.
     * @returns {Promise<boolean>} Whether the file exists
     * @example
     * const exists = await file.exists();
     */
    async exists(): Promise<boolean> {
        if (this.fileSource === FileSource.File && this.metadata.path) {
            try {
                await fs.promises.access(this.metadata.path);
                return true;
            } catch {
                return false;
            }
        }
        return true; // For non-file sources, we assume they exist since we have their data
    }

    /**
     * Checks if the file is readable.
     * @returns {Promise<boolean>} Whether the file is readable
     * @example
     * const isReadable = await file.isReadable();
     */
    async isReadable(): Promise<boolean> {
        if (this.fileSource === FileSource.File && this.metadata.path) {
            try {
                await fs.promises.access(this.metadata.path, fs.constants.R_OK);
                return true;
            } catch {
                return false;
            }
        }
        return true; // For non-file sources, we assume they're readable since we have their data
    }

    /**
     * Checks if the file is writable.
     * @returns {Promise<boolean>} Whether the file is writable
     * @example
     * const isWritable = await file.isWritable();
     */
    async isWritable(): Promise<boolean> {
        if (this.fileSource === FileSource.File && this.metadata.path) {
            try {
                await fs.promises.access(this.metadata.path, fs.constants.W_OK);
                return true;
            } catch {
                return false;
            }
        }
        return false; // For non-file sources, we can't write back to them
    }

    /**
     * Calculates the SHA-256 checksum of the file.
     * @returns {Promise<string>} The file's checksum
     * @example
     * const checksum = await file.getChecksum();
     */
    async getChecksum(): Promise<string> {
        const bytes = await this.readFileBytes();
        const buffer = Buffer.from(bytes);
        const hash = crypto.createHash('sha256');
        hash.update(buffer);
        return hash.digest('hex');
    }

    /**
     * Updates the file's metadata.
     * @param {Partial<Metadata>} metadata - The metadata to update
     * @returns {Promise<void>}
     * @example
     * await file.setMetadata({ name: 'new-name.txt' });
     */
    async setMetadata(metadata: Partial<Metadata>): Promise<void> {
        this.metadata = {
            ...this.metadata,
            ...metadata,
        };
    }

    /**
     * Gets the file's filesystem stats.
     * @returns {Promise<fs.Stats | undefined>} The file's stats or undefined if not a filesystem file
     * @example
     * const stats = await file.getStats();
     */
    async getStats(): Promise<fs.Stats | undefined> {
        if (this.fileSource === FileSource.File && this.metadata.path) {
            return await fs.promises.stat(this.metadata.path);
        }
        return undefined;
    }

    /**
     * Appends content to the end of the file.
     * @param {string | Buffer} content - The content to append
     * @returns {Promise<void>}
     * @example
     * await file.append('Additional content');
     */
    async append(content: string | Buffer): Promise<void> {
        if (this.fileSource === FileSource.File && this.metadata.path) {
            const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
            await fs.promises.appendFile(this.metadata.path, buffer);
            await this.refresh();
        } else {
            throw new Error('Cannot append to non-file source');
        }
    }

    /**
     * Prepends content to the beginning of the file.
     * @param {string | Buffer} content - The content to prepend
     * @returns {Promise<void>}
     * @example
     * await file.prepend('New content at start');
     */
    async prepend(content: string | Buffer): Promise<void> {
        if (this.fileSource === FileSource.File && this.metadata.path) {
            const existingContent = Buffer.from(await this.readFileBytes());
            const newContent = Buffer.isBuffer(content) ? content : Buffer.from(content);
            await fs.promises.writeFile(this.metadata.path, Buffer.concat([newContent, existingContent]));
            await this.refresh();
        } else {
            throw new Error('Cannot prepend to non-file source');
        }
    }

    /**
     * Truncates the file to the specified size.
     * @param {number} size - The new size of the file
     * @returns {Promise<void>}
     * @example
     * await file.truncate(1000);
     */
    async truncate(size: number): Promise<void> {
        if (this.fileSource === FileSource.File && this.metadata.path) {
            await fs.promises.truncate(this.metadata.path, size);
            await this.refresh();
        } else {
            throw new Error('Cannot truncate non-file source');
        }
    }

    /**
     * Gets a signed URL for accessing an S3 file.
     * @param {number} [expiresIn=3600] - The number of seconds until the URL expires
     * @returns {Promise<string>} The signed URL
     * @example
     * const signedUrl = await file.getSignedUrl(7200); // URL expires in 2 hours
     */
    async getSignedUrl(expiresIn: number = 3600): Promise<string> {
        if (this.fileSource === FileSource.S3 && this.metadata.url) {
            const [bucket, key] = this.metadata.url.replace('s3://', '').split('/', 2);
            const [{ GetObjectCommand }, { getSignedUrl }] = await Promise.all([loadS3(), loadPresigner()]);
            const command = new GetObjectCommand({
                Bucket: bucket,
                Key: key,
            });
            return await getSignedUrl(await this.s3Client(), command, { expiresIn });
        }
        throw new Error('Cannot generate signed URL for non-S3 file');
    }

    /**
     * Drains the whole payload into memory and caches it.
     *
     * This used to be a single `await stream.read()`, which returns only what
     * the stream happens to have buffered — one chunk. Every file bigger than
     * one chunk was therefore silently truncated on its way through
     * `readFileBytes`, `getChecksum`, `toFormData` and `uploadToS3`.
     */
    private async toBuffer(): Promise<Buffer> {
        if (this.bytes) {
            return Buffer.from(this.bytes);
        }

        const chunks: Buffer[] = [];
        for await (const chunk of this.stream) {
            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array));
        }

        const buffer = Buffer.concat(chunks);
        // Slice off the backing ArrayBuffer rather than handing out `.buffer`,
        // which for a pooled Node Buffer is a slab shared with other Buffers.
        this.bytes = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
        this.metadata.size ??= buffer.byteLength;
        return Buffer.from(this.bytes);
    }
}