v2.1.0

⚠️ Potential Breaking Change

The VerseRef.verseNum setter now clears the verse string and rejects negative values (#60).

The setter was a mis-port: it assigned the backing field and nothing else. It now matches the C# VerseRef.VerseNum it ports, which also clears the verse string and guards against negatives. Two behaviour changes follow.

1. Assigning verseNum now clears a range or segment

const vref = new VerseRef('LUK', '3', '4b-5a');
vref.verseNum = 9;

vref.verse; // was '4b-5a' (stale) → now '9'
vref.hasMultiple; // was true (stale) → now false

Previously the range or segment string survived the assignment, so verse and hasMultiple kept describing the old reference while verseNum described the new one. Any code that assigned verseNum and then read verse, hasMultiple, or toString() will now see the new verse number instead of the stale string.

2. Negative values now throw

vref.verseNum = -1; // throws VerseRefException('VerseNum can not be negative')

0 is still accepted. If you were assigning -1 to mean "no verse", use the verse string setter instead, which still yields verseNum === -1:

vref.verse = ''; // verseNum === -1, verse === ''

Are you affected?

Only if you assign to verseNum on an actual VerseRef instance. You are not affected if you assign to chapterNum/verseNum on a plain SerializedVerseRef (or any other plain object) — that is an interface with ordinary data properties and no setter.

// affected — VerseRef instance, setter runs
const vref = new VerseRef('LUK', '3', '4b-5a');
vref.verseNum = 9;

// not affected — plain object, no setter
const ref: SerializedVerseRef = { book: 'LUK', chapterNum: 3, verseNum: 4 };
ref.verseNum = 9;

If you want the old "set the number, keep the string" behaviour, set the string explicitly via the verse setter, which updates both consistently:

vref.verse = '9b-10a'; // verseNum === 9, verse === '9b-10a'

Why this is a minor bump rather than a major

A survey of known consumers — the paranext org, eten-tech-foundation/scripture-editors, sillsdev/scripture-forge-platform-extensions, and sillsdev/web-xforge — found no code that reaches this setter.

• In the paranext repos and scripture-editors, every verseNum assignment is on a plain SerializedVerseRef-shaped object, and the few VerseRef instantiations are read-only expressions that never store the instance.
• web-xforge is by far the heaviest VerseRef consumer — 27 files instantiate it and it does hold instances in variables and component fields — but it never assigns verseNum on any of them. Its only chapterNum assignments are to plain chapterNum: number fields on Angular components. It is also still on @sillsdev/scripture 1.x, so this release would not reach it regardless.

Details are in #60.

The change also restores the documented C# behaviour: the previous result was stale and internally inconsistent, not a contract worth preserving. It is flagged here as potentially breaking because the old setter did work, so external code outside the surveyed repos could in principle depend on it.

What's Changed

• fix VerseRef.verseNum setter mis-port by @irahopkinson in #60
• 2.1.0 by @irahopkinson in #63

Full Changelog: v2.0.6...v2.1.0