feat: Extend the `UploadedFile` class to include all required properties and methods

[3m1n3nc3]

Description

Currently, the UploadedFile class in @h3ravel/http only provides minimal functionality via:

• createFromBase()
• moveTo()

To achieve feature parity with modern frameworks and provide developers with a complete set of file handling utilities, this class should be extended with additional methods and properties.

Goal

Enhance the UploadedFile class to include robust file management and inspection methods, covering file storage, retrieval, metadata, and validation.

Proposed Additions

Existing

• createFromBase()
• moveTo()

New Methods

1. path(): string — Returns the full temporary or stored file path.
2. extension(): string — Returns the file extension.
3. hashName(path?: string): string — Generates a unique hash-based filename.
4. dimensions(): Promise<{ width: number; height: number }> — Gets image dimensions (for image files).
5. fake(): UploadedFile — Generates a fake file instance (for testing).
6. store(path: string, options?: StoreOptions): Promise<string> — Stores the file in a given directory.
7. storePublicly(path: string, options?: StoreOptions): Promise<string> — Stores file in a public location.
8. storePubliclyAs(path: string, name: string, options?: StoreOptions): Promise<string> — Stores public file with a custom name.
9. storeAs(path: string, name: string, options?: StoreOptions): Promise<string> — Stores file with a specified name.
10. get(): Buffer | Promise<Buffer> — Reads the file content.
11. clientExtension(): string — Returns the client-provided file extension.
12. getClientMimeType(): string — Returns the MIME type reported by the client.
13. getError(): number | null — Returns any upload error code.
14. isValid(): boolean — Checks if the uploaded file is valid.
15. move(destination: string, name?: string): Promise<string> — Moves file to a given destination.
16. parseFilesize(size: number): string — Converts a size in bytes to a human-readable format.
17. getErrorMessage(): string | null — Returns a human-readable upload error message.

Tasks

• Review the current implementation of UploadedFile.
• Define the StoreOptions interface (e.g. { visibility?: 'private' | 'public'; disk?: string }).
• Implement all proposed methods.
• Ensure file operations integrate with the filesystem abstraction (Flydrive integration if available).
• Add helper imports for mime detection and image dimension extraction (e.g. image-size, mime-types).
• Write unit tests for all new methods.
• Document each method and property with JSDoc annotations.

Acceptance Criteria

• All new methods implemented and tested.
• Class supports file inspection, movement, storage, and metadata access.
• Integration with storage drivers (@h3ravel/filesystem) if available.
• Works seamlessly in both Node and H3 environments.
• Backward compatible with existing moveTo and createFromBase.
• All methods are fully typed and documented.

Difficulty

Advanced