Skip to content

feat: introduce MagicStringError with concise, consistent messages - #324

Merged
antfu merged 1 commit into
Rich-Harris:masterfrom
antfubot:tame-baths-win
Aug 13, 2026
Merged

feat: introduce MagicStringError with concise, consistent messages#324
antfu merged 1 commit into
Rich-Harris:masterfrom
antfubot:tame-baths-win

Conversation

@antfubot

@antfubot antfubot commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

What & why

Error messages thrown by magic-string were ad hoc new Error / new TypeError strings with inconsistent casing and tone. This normalizes every throw site behind a single, consistent error type in the spirit of "errors worth reading".

Changes

  • Add MagicStringError (exported from the package entry) — the single error type thrown everywhere, extending Error.
    • Every message is prefixed with [MagicString] so its source is obvious at a glance.
    • Messages are short, lower-case, and consistent in tone, with any how-to-fix hint folded into the one message (e.g. insert() is deprecated, use appendLeft() or prependRight()).
  • Convert all throws across MagicString, Bundle, and SourceMap to MagicStringError, and unify the duplicated "content must be a string" checks.

Examples:

[MagicString] content must be a string, got object
[MagicString] cannot move a selection inside itself
[MagicString] cannot overwrite a zero-length range at 3, use appendLeft() or prependRight()
[MagicString] replaceAll() requires a global RegExp

Backward compatibility

MagicStringError extends Error, so instanceof Error and try/catch keep working. A few throw sites previously produced TypeError, but that concrete type was never documented, so consolidating on MagicStringError is not considered a breaking change. Only the human-readable message wording changes.

This PR was created with the help of an agent.

@antfubot antfubot changed the title feat!: introduce MagicStringError with actionable fixes feat!: introduce MagicStringError with concise, consistent messages Aug 13, 2026
@antfubot antfubot changed the title feat!: introduce MagicStringError with concise, consistent messages feat: introduce MagicStringError with concise, consistent messages Aug 13, 2026
Replace ad hoc `new Error`/`new TypeError` throws with a single
MagicStringError type. Every message is prefixed with `[MagicString]`
and kept short, lower-case, and consistent in tone, folding any
how-to-fix hint into the one message.

The concrete error type (previously a mix of `Error` and `TypeError`)
was never documented, so consolidating on MagicStringError — which still
extends `Error` — is not a breaking change.
@antfu
antfu merged commit 57080e7 into Rich-Harris:master Aug 13, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants