[ID3v2] Version Enum

[benrr101]

This is big change, but it's effectively minuscule. ID3v2 major version was originally just a number. So there was a lot of checks to make sure that the number is within the right range, etc, etc. This isn't amazing in terms of type safety. So, in thic change, I'm introducing an enum type for ID3v2 major version. The enum values are the same as the numerical values from before. Additionally, typescript allows implicit conversion between enums and numbers. So, effectively it isn't technically a breaking change.

This is some setup work that will make it easier for me to split up the ID3v2 tag types into different classes per major version - immutable tag versions.

[Copilot]

Pull request overview

Introduces typed ID3v2 version and flag enums across tag parsing, frame rendering, and tests while reorganizing ID3v2 header/footer classes.

Changes:

• Adds Id3v2Version and centralizes related enums.
• Migrates ID3v2 APIs and tests from numeric versions to enum values.
• Renames header/footer implementations and updates documentation, imports, and linting.

Reviewed changes

Copilot reviewed 71 out of 71 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
.eslintrc.js	Enforces safe enum comparisons.
src/index.ts	Updates public ID3v2 exports.
src/sandwich/startTag.ts	Uses renamed tag header.
src/sandwich/endTag.ts	Uses enum-based footer handling.
src/id3v2/enums.ts	Adds version, flag, and utility enums.
src/id3v2/frameIdentifiers.ts	Renders identifiers by version enum.
src/id3v2/id3v2Tag.ts	Migrates tag version logic and flags.
src/id3v2/tagHeader.ts	Migrates tag headers to version enums.
src/id3v2/tagFooter.ts	Migrates tag footers to version enums.
src/id3v2/tagHeaderExtended.ts	Migrates extended-header parsing.
src/id3v2/frames/frame.ts	Updates base frame version APIs.
src/id3v2/frames/frameHeader.ts	Updates frame-header version handling.
src/id3v2/frames/frameFactory.ts	Propagates enums through frame creation.
src/id3v2/frames/attachmentFrame.ts	Migrates attachment frame versions.
src/id3v2/frames/commentsFrame.ts	Migrates comments frames.
src/id3v2/frames/eventTimeCodeFrame.ts	Centralizes event enums and versions.
src/id3v2/frames/genreFrame.ts	Uses enums for genre encoding rules.
src/id3v2/frames/musicCdIdentifierFrame.ts	Migrates MCDI frames.
src/id3v2/frames/playCountFrame.ts	Migrates play-count frames.
src/id3v2/frames/popularimeterFrame.ts	Migrates popularimeter frames.
src/id3v2/frames/privateFrame.ts	Migrates private frames.
src/id3v2/frames/relativeVolumeFrame.ts	Centralizes channel and version enums.
src/id3v2/frames/synchronizedLyricsFrame.ts	Centralizes synchronized-text enums.
src/id3v2/frames/termsOfUseFrame.ts	Migrates terms-of-use frames.
src/id3v2/frames/textInformationFrame.ts	Migrates version-specific text behavior.
src/id3v2/frames/uniqueFileIdentifierFrame.ts	Migrates UFID frames.
src/id3v2/frames/unknownFrame.ts	Migrates unknown frames.
src/id3v2/frames/unsynchronizedLyricsFrame.ts	Migrates lyrics frames.
src/id3v2/frames/urlLinkFrame.ts	Migrates URL frames.
src/id3v2/frames/userTextInformationFrame.ts	Migrates user-text frames.
src/id3v2/frames/userUrlLinkFrame.ts	Migrates user-URL frames.
test-unit/combinedTagTests.ts	Uses direct picture imports.
test-unit/flac/flacFileTests.ts	Updates ID3v2 flags and imports.
test-unit/matroska/matroskaTagCollectionTests.ts	Uses direct module imports.
test-unit/matroska/utils.ts	Uses direct byte-vector imports.
test-unit/riff/riffFileTests.ts	Updates ID3v2 flag enum usage.
test-unit/sandwich/endTagTests.ts	Updates footer-flag tests.
test-unit/sandwich/sandwichTagTests.ts	Updates footer-flag tests.
test-unit/xiph/resources.ts	Uses direct module imports.
test-unit/id3v2/attachmentsFrameTests.ts	Migrates attachment tests to enums.
test-unit/id3v2/commentsFrameTests.ts	Migrates comments-frame tests.
test-unit/id3v2/eventTimeCodeFrameTests.ts	Migrates event-frame tests.
test-unit/id3v2/frameConstructorTests.ts	Updates shared constructor contracts.
test-unit/id3v2/frameFactoryTests.ts	Migrates frame-factory tests.
test-unit/id3v2/frameHeaderTests.ts	Migrates frame-header tests.
test-unit/id3v2/frameIdentifiersTests.ts	Consolidates enum-based render tests.
test-unit/id3v2/frameTests.ts	Migrates base-frame tests.
test-unit/id3v2/genreFrameTests.ts	Migrates genre-frame tests.
test-unit/id3v2/id3v2TagTests.ts	Migrates tag-level version tests.
test-unit/id3v2/musicCdIdentifierFrameTests.ts	Migrates MCDI tests.
test-unit/id3v2/playCountFrameTests.ts	Migrates play-count tests.
test-unit/id3v2/popularimeterFrameTests.ts	Migrates popularimeter tests.
test-unit/id3v2/privateFrameTests.ts	Migrates private-frame tests.
test-unit/id3v2/relativeVolumeFrameTests.ts	Migrates relative-volume tests.
test-unit/id3v2/synchronizedLyricsFrameTests.ts	Migrates synchronized-lyrics tests.
test-unit/id3v2/tagExtendedHeaderTests.ts	Removes superseded extended-header tests.
test-unit/id3v2/tagFooterTests.ts	Expands enum-based footer tests.
test-unit/id3v2/tagHeaderExtendedTests.ts	Adds renamed extended-header tests.
test-unit/id3v2/tagHeaderTests.ts	Migrates tag-header tests.
test-unit/id3v2/termsOfUseFrameTests.ts	Migrates terms-of-use tests.
test-unit/id3v2/textInformationFrameTests.ts	Migrates text-frame tests.
test-unit/id3v2/uniqueFileIdentifierFrameTests.ts	Migrates UFID tests.
test-unit/id3v2/unknownFrameTests.ts	Migrates unknown-frame tests.
test-unit/id3v2/unsynchronizedLyricsFrameTests.ts	Migrates lyrics-frame tests.
test-unit/id3v2/urlLinkFrameTests.ts	Migrates URL-frame tests.
test-unit/id3v2/userTextInformationFrameTests.ts	Migrates user-text tests.
test-unit/id3v2/userUrlLinkFrameTests.ts	Migrates user-URL tests.
docs/modules.md	Updates documented header name.
docs/classes/Id3v2TagHeader.md	Updates tag-header class documentation.
docs/classes/Id3v2TagFooter.md	Updates footer parameter documentation.
docs/enums/Id3v2TagHeaderFlags.md	Updates tag-header flag documentation.

Suppressed comments (1)

src/id3v2/tagHeader.ts:137

• Changing the parameter type to an enum removed the runtime range checks that this setter previously performed. JavaScript callers (and TypeScript casts/number values) can still pass 1 or 5; the setter now stores that value and tag rendering can emit an invalid ID3v2 major-version byte. Restore the runtime guards in addition to the enum type.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 67 out of 67 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

src/id3v2/tagHeader.ts:117

• Checking _majorVersion bypasses Id3v2Settings.forceDefaultVersion. For example, a loaded v2 tag forced to render as the default v3 still rejects ExtendedHeader/ExperimentalIndicator, even though majorVersion reports v3 and the old implementation validated that effective version. Use the getter for both compatibility checks.
  src/id3v2/tagHeader.ts:137
• The enum annotation does not enforce values at runtime, but this setter removed the previous byte/range checks. JavaScript callers (or TypeScript casts) can now assign 1 or 5, after which render() writes an invalid ID3 major-version byte. Preserve the runtime validation while accepting Id3v2Version.