@d1g1tal/media-type 5.0.1 → 6.0.0

package/CHANGELOG.md

@@ -0,0 +1,153 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [6.0.0] - 2024-06-15
+
+### Changed
+- **Complete TypeScript conversion**: Converted all source and test files from JavaScript to TypeScript
+- **Test framework**: Migrated from Jest to Vitest with coverage support
+- Updated ESLint to modern flat config format
+- Enhanced README with badges, features, and migration guide
+- Updated package.json with proper TypeScript exports
+
+### Added
+- Native TypeScript type definitions with strict compiler options
+- TypeScript interfaces: `MediaTypeComponent`, `ParsedMediaType`
+- tsconfig.json with isolated declarations
+- Vitest configuration with UI and coverage (`@vitest/coverage-v8`, `@vitest/ui`)
+- `@types/node` dev dependency
+- Comprehensive CHANGELOG
+- Automated version script for releases
+
+## [5.0.2] - 2023-XX-XX
+
+### Fixed
+- Maintenance release with dependency updates
+
+## [5.0.0] - 2023-11-11
+
+### Changed
+- Switched to pnpm for package management
+- Switched license from MIT to ISC
+- Refactored `MediaTypeParameters` to extend Map directly (instead of wrapping)
+- Refactored parser to use class with static methods
+- Moved serializer functionality into `MediaType.toString()`
+- Changed package manager from npm/yarn to pnpm
+- Removed `esbuild-library` dependency in favor of simpler TypeScript compilation
+
+#### API Changes - BREAKING CHANGES
+
+##### Renamed Classes
+- **`MIMEType` → `MediaType`**: Main class renamed to reflect WHATWG terminology
+- **`MIMETypeParameters` → `MediaTypeParameters`**: Parameters class renamed accordingly
+
+##### Removed Methods
+The following methods have been **removed** from the `MediaType` class:
+- `isHTML()` - Removed (was marked as speculative in original package)
+- `isXML()` - Removed (was marked as speculative in original package)
+- `isJavaScript({ prohibitParameters })` - Removed (was marked as speculative in original package)
+
+**Migration Guide**: If you were using these methods, you'll need to implement your own checks:
+
+```typescript
+// Old (v4.x with whatwg-mimetype)
+if (mimeType.isHTML()) { /* ... */ }
+
+// New (v5.x with @d1g1tal/media-type)
+if (mediaType.essence === 'text/html') { /* ... */ }
+// or for more comprehensive HTML MIME type checking:
+const htmlTypes = ['text/html', 'application/xhtml+xml'];
+if (htmlTypes.includes(mediaType.essence)) { /* ... */ }
+```
+
+##### New Methods
+- **`matches(mediaType: MediaType | string): boolean`**: New method to check if media type matches a specified type
+  - Accepts either a `MediaType` instance or a string
+  - For strings: checks if the essence includes the string (e.g., `mediaType.matches('html')`)
+  - For `MediaType` instances: performs exact type/subtype comparison
+
+##### Constructor Changes
+- **Constructor signature change**: Now accepts optional second parameter for overriding parameters
+  ```typescript
+  // New in v5.0
+  const mediaType = new MediaType('text/html;charset=iso-8859-1', { charset: 'utf-8' });
+  // Results in: text/html;charset=utf-8
+  ```
+- **Removed object-only constructor**: Can no longer pass just an object to constructor
+  - Old: `new MIMEType({ type: 'text', subtype: 'html' })` ❌
+  - New: Must pass string as first parameter ✅
+
+##### Internal Architecture Changes
+- **`MediaTypeParameters` now extends `Map`**: Previously wrapped a Map, now directly extends it
+  - Reduces file size and complexity
+  - All Map methods directly available
+  - Still maintains media type-specific validation (case-insensitive parameter names, HTTP token validation)
+
+- **Parser refactored to class**: Module with exported functions converted to `MediaTypeParser` class with static methods
+- **Serializer merged**: Separate serializer module removed, `serialize` functionality moved into `MediaType.toString()`
+- **Utility optimizations**: Util functions moved directly into classes where used only once
+
+#### Module System Changes
+- Pure ES Modules (ESM) - no CommonJS support
+- Updated exports structure in package.json
+- Import extensions required: `.js` extensions must be used in TypeScript imports
+
+#### Properties Made Private
+- Internal `_type`, `_subtype`, and `_parameters` properties are now properly private
+- Access only through public getters
+- `type` and `subtype` are now read-only (getter-only)
+
+#### Development Experience
+- Added comprehensive ESLint configuration with TypeScript support
+- Added `eslint-plugin-jsdoc` for JSDoc validation
+- Improved test coverage with Vitest
+- Added coverage reporting with `@vitest/coverage-v8`
+- Web Platform Tests integration maintained and updated
+
+#### License Change
+- **License changed from MIT to ISC**
+- Maintainer changed to Jason DiMeo
+
+### Added
+- `matches()` method for media type comparison
+- Second constructor parameter for parameter overrides
+- Full TypeScript type definitions
+- Vitest UI support for interactive testing
+
+### Changed
+- Package name: `whatwg-mimetype` → `@d1g1tal/media-type`
+- License: MIT → ISC
+- Build system: esbuild-library → tsbuild
+- Test framework: Jest → Vitest
+- Package manager: npm/yarn → pnpm
+- Module system: CommonJS → Pure ESM
+
+### Removed
+- `isHTML()` method
+- `isXML()` method
+- `isJavaScript()` method
+- Object-only constructor signature
+- CommonJS support
+- Separate serializer module
+- `esbuild-library` dependency
+- `minipass-fetch` dev dependency (replaced with built-in fetch API)
+- `rimraf` dev dependency (tsbuild handles cleaning)
+
+## [4.x.x] - Previous versions
+
+See the original [whatwg-mimetype](https://github.com/jsdom/whatwg-mimetype) repository for version 4.x.x and earlier history.
+
+---
+
+## Original Package Information
+
+This package is a fork of [`whatwg-mimetype`](https://github.com/jsdom/whatwg-mimetype) by Domenic Denicola and contributors. The original package was licensed under MIT. This fork has been substantially rewritten with breaking changes and is licensed under ISC.
+
+**Original Author**: Domenic Denicola <d@domenic.me> (https://domenic.me/)
+**Current Maintainer**: Jason DiMeo <jason.dimeo@gmail.com>
+
+The original package contributors and their excellent work are acknowledged with gratitude.

package/README.md

@@ -1,11 +1,41 @@
 # Parse, serialize, and manipulate media types
 
-This package will parse [MIME types](https://mimesniff.spec.whatwg.org/#understanding-mime-types) into a structured format, which can then be manipulated and serialized:
+[![npm version](https://img.shields.io/npm/v/@d1g1tal/media-type.svg)](https://www.npmjs.com/package/@d1g1tal/media-type)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![Node Version](https://img.shields.io/node/v/@d1g1tal/media-type.svg)](https://nodejs.org)
 
-This version is using ES Modules instead of commonJS.
+> **Note**: This is a TypeScript rewrite and fork of the original [`whatwg-mimetype`](https://github.com/jsdom/whatwg-mimetype) package. See [CHANGELOG.md](./CHANGELOG.md) for migration information.
+
+This package will parse [MIME types](https://mimesniff.spec.whatwg.org/#understanding-mime-types) (also known as media types) into a structured format, which can then be manipulated and serialized according to the WHATWG MIME Sniffing Standard.
+
+## Features
+
+- ✅ **WHATWG Standard Compliant**: Implements the [WHATWG MIME Sniffing Standard](https://mimesniff.spec.whatwg.org/)
+- ✅ **Full TypeScript Support**: Written in TypeScript with complete type definitions
+- ✅ **Pure ES Modules**: Modern ESM-only package
+- ✅ **Zero Dependencies**: No runtime dependencies
+- ✅ **Extensive Testing**: Includes WHATWG web platform tests
+- ✅ **Lightweight**: Minimal bundle size
+
+## Installation
+
+```bash
+npm install @d1g1tal/media-type
+```
+
+```bash
+pnpm add @d1g1tal/media-type
+```
+
+```bash
+yarn add @d1g1tal/media-type
+```
+
+## Usage
 
 ```js
-import MediaType from '@d1g1tal/media-type';
+import { MediaType } from '@d1g1tal/media-type';
 
 const mediaType = new MediaType('Text/HTML;Charset="utf-8"');
 
@@ -28,6 +58,31 @@ Parsing is a fairly complex process; see [the specification](https://mimesniff.s
 
 This package's algorithms conform to those of the WHATWG [MIME Sniffing Standard](https://mimesniff.spec.whatwg.org/), and is aligned up to commit [8e9a7dd](https://github.com/whatwg/mimesniff/commit/8e9a7dd90717c595a4e4d982cd216e4411d33736).
 
+## Migration from whatwg-mimetype
+
+If you're migrating from the original `whatwg-mimetype` package, please review the [CHANGELOG.md](./CHANGELOG.md) for breaking changes. Key changes include:
+
+- **Class renamed**: `MIMEType` → `MediaType`
+- **Removed methods**: `isHTML()`, `isXML()`, `isJavaScript()` - implement your own checks using the `essence` property
+- **New method**: `matches(mediaType)` for flexible type matching
+- **Properties now read-only**: `type` and `subtype` can only be read via getters
+- **Constructor change**: Optional second parameter to override parsed parameters
+- **Pure ESM**: No CommonJS support
+
+### Quick Migration Example
+
+```typescript
+// Old (whatwg-mimetype v4.x)
+import MIMEType from 'whatwg-mimetype';
+const mimeType = new MIMEType('text/html');
+if (mimeType.isHTML()) { /* ... */ }
+
+// New (@d1g1tal/media-type v5.x)
+import { MediaType } from '@d1g1tal/media-type';
+const mediaType = new MediaType('text/html');
+if (mediaType.essence === 'text/html' || mediaType.matches('html')) { /* ... */ }
+```
+
 ## `MediaType` API
 
 This package's main module's export is a class, `MediaType`. Its constructor takes a string which it will attempt to parse into a media type; if parsing fails, an `Error` will be thrown.
@@ -51,8 +106,10 @@ As an alternative to the constructor, you can use `MediaType.parse(string)`. The
 
 ### Methods
 
-- `toString()` serializes the media type to a string
-- `matches(MediaType|string)`: Checks if the media type matches the specified type.
+- **`toString()`**: Serializes the media type to a string
+- **`matches(mediaType: MediaType | string)`**: Checks if the media type matches the specified type
+  - When passed a string: checks if the essence includes that string (e.g., `mediaType.matches('html')` returns `true` for `text/html`)
+  - When passed a `MediaType` instance: performs exact type/subtype comparison
 
 ## `MediaTypeParameters` API
 
@@ -83,4 +140,88 @@ console.assert(mediaType.toString() === 'x/x;a=b;c=d;e=F;q=X');
 
 // Throws:
 mediaType.parameters.set('@', 'x');
-```
+```
+
+## Additional Exports
+
+In addition to the main `MediaType` class, this package also exports:
+
+- **`MediaTypeParameters`**: The parameters class (extends `Map<string, string>`)
+- **`MediaTypeParser`**: Low-level parser with static methods
+- **Type exports**: `MediaTypeComponent`, `ParsedMediaType` (TypeScript types)
+
+```typescript
+import { 
+  MediaType, 
+  MediaTypeParameters, 
+  MediaTypeParser,
+  type MediaTypeComponent,
+  type ParsedMediaType 
+} from '@d1g1tal/media-type';
+```
+
+## Browser Support
+
+This package uses modern ES features and is designed for:
+- Modern browsers with ES6 module support
+- Maintained Node.js versions (see `browserslist` in package.json)
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run tests with coverage
+pnpm test:coverage
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run tests with UI
+pnpm test:ui
+
+# Build the package
+pnpm build
+
+# Lint
+pnpm lint
+```
+
+## About This Fork
+
+This project is a fork and substantial rewrite of the excellent [`whatwg-mimetype`](https://github.com/jsdom/whatwg-mimetype) package by Domenic Denicola and contributors.
+
+**Why fork?**
+- Complete TypeScript rewrite for better type safety
+- Modernize build tooling and dependencies
+- Optimize bundle size and performance
+- Maintain WHATWG standard compliance
+
+**Original Author**: Domenic Denicola  
+**Current Maintainer**: Jason DiMeo
+
+The original contributors' excellent work is acknowledged with gratitude. This fork maintains the same commitment to WHATWG standards compliance while providing a modern TypeScript-first experience.
+
+## License
+
+ISC License - see [LICENSE](./LICENSE) file for details.
+
+The original `whatwg-mimetype` package was licensed under MIT.
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+- All tests pass (`pnpm test`)
+- Code follows the ESLint configuration
+- TypeScript types are properly defined
+- Changes are documented in the CHANGELOG
+
+## Resources
+
+- [WHATWG MIME Sniffing Standard](https://mimesniff.spec.whatwg.org/)
+- [Original whatwg-mimetype package](https://github.com/jsdom/whatwg-mimetype)
+- [Issue Tracker](https://github.com/D1g1talEntr0py/media-type/issues)

package/dist/media-type.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Class representing the parameters for a media type record.
+ * This class extends a JavaScript Map<string, string>.
+ *
+ * However, MediaTypeParameters methods will always interpret their arguments
+ * as appropriate for media types, so parameter names will be lowercased,
+ * and attempting to set invalid characters will throw an Error.
+ *
+ * @see https://mimesniff.spec.whatwg.org
+ * @author D1g1talEntr0py <jason.dimeo@gmail.com>
+ */
+declare class MediaTypeParameters extends Map<string, string> {
+    /**
+     * Create a new MediaTypeParameters instance.
+     *
+     * @param entries An array of [ name, value ] tuples.
+     */
+    constructor(entries?: Iterable<[string, string]>);
+    /**
+     * Indicates whether the supplied name and value are valid media type parameters.
+     *
+     * @param name The name of the media type parameter to validate.
+     * @param value The media type parameter value to validate.
+     * @returns true if the media type parameter is valid, false otherwise.
+     */
+    static isValid(name: string, value: string): boolean;
+    /**
+     * Gets the media type parameter value for the supplied name.
+     *
+     * @param name The name of the media type parameter to retrieve.
+     * @returns The media type parameter value.
+     */
+    get(name: string): string | undefined;
+    /**
+     * Indicates whether the media type parameter with the specified name exists or not.
+     *
+     * @param name The name of the media type parameter to check.
+     * @returns true if the media type parameter exists, false otherwise.
+     */
+    has(name: string): boolean;
+    /**
+     * Adds a new media type parameter using the specified name and value to the MediaTypeParameters.
+     * If an parameter with the same name already exists, the parameter will be updated.
+     *
+     * @param name The name of the media type parameter to set.
+     * @param value The media type parameter value.
+     * @returns This instance.
+     */
+    set(name: string, value: string): this;
+    /**
+     * Removes the media type parameter using the specified name.
+     *
+     * @param name The name of the media type parameter to delete.
+     * @returns true if the parameter existed and has been removed, or false if the parameter does not exist.
+     */
+    delete(name: string): boolean;
+    /**
+     * Returns a string representation of the media type parameters.
+     *
+     * @returns The string representation of the media type parameters.
+     */
+    toString(): string;
+    /**
+     * Returns the name of this class.
+     *
+     * @returns The name of this class.
+     */
+    get [Symbol.toStringTag](): string;
+}
+
+/**
+ * Class used to parse media types.
+ * @see https://mimesniff.spec.whatwg.org/#understanding-mime-types
+ */
+declare class MediaType {
+    private readonly _type;
+    private readonly _subtype;
+    private readonly _parameters;
+    /**
+     * Create a new MediaType instance from a string representation.
+     * @param mediaType The media type to parse.
+     * @param parameters Optional parameters.
+     */
+    constructor(mediaType: string, parameters?: Record<string, string>);
+    /**
+     * Parses a media type string.
+     * @param mediaType The media type to parse.
+     * @returns The parsed media type or null if the mediaType cannot be parsed.
+     */
+    static parse(mediaType: string): MediaType | null;
+    /**
+     * Gets the type.
+     * @returns The type.
+     */
+    get type(): string;
+    /**
+     * Gets the subtype.
+     * @returns The subtype.
+     */
+    get subtype(): string;
+    /**
+     * Gets the media type essence (type/subtype).
+     * @returns The media type without any parameters
+     */
+    get essence(): string;
+    /**
+     * Gets the parameters.
+     * @returns The media type parameters.
+     */
+    get parameters(): MediaTypeParameters;
+    /**
+     * Checks if the media type matches the specified type.
+     *
+     * @param mediaType The media type to check.
+     * @returns true if the media type matches the specified type, false otherwise.
+     */
+    matches(mediaType: MediaType | string): boolean;
+    /**
+     * Gets the serialized version of the media type.
+     *
+     * @returns The serialized media type.
+     */
+    toString(): string;
+    /**
+     * Gets the name of the class.
+     * @returns The class name
+     */
+    get [Symbol.toStringTag](): string;
+}
+
+interface MediaTypeComponent {
+    position?: number;
+    input: string;
+    lowerCase?: boolean;
+    trim?: boolean;
+}
+interface ParsedMediaType {
+    type: string;
+    subtype: string;
+    parameters: MediaTypeParameters;
+}
+/**
+ * Parser for media types.
+ * @see https://mimesniff.spec.whatwg.org/#parsing-a-mime-type
+ * @author D1g1talEntr0py <jason.dimeo@gmail.com>
+ */
+declare class MediaTypeParser {
+    /**
+     * Function to parse a media type.
+     * @param input The media type to parse
+     * @returns An object populated with the parsed media type properties and any parameters.
+     */
+    static parse(input: string): ParsedMediaType;
+    /**
+     * Gets the name of this class.
+     * @returns The string tag of this class.
+     */
+    get [Symbol.toStringTag](): string;
+    /**
+     * Filters a component from the input string.
+     * @param options The options.
+     * @param charactersToFilter The characters to filter.
+     * @returns An object that includes the resulting string and updated position.
+     */
+    private static filterComponent;
+    /**
+     * Collects all the HTTP quoted strings.
+     * This variant only implements it with the extract-value flag set.
+     * @param input The string to process.
+     * @param position The starting position.
+     * @returns An array that includes the resulting string and updated position.
+     */
+    private static collectHttpQuotedString;
+    /**
+     * Generates an error message.
+     * @param component The component name.
+     * @param value The component value.
+     * @returns The error message.
+     */
+    private static generateErrorMessage;
+}
+
+export { MediaType, MediaTypeParameters, MediaTypeParser };
+export type { MediaTypeComponent, ParsedMediaType };