We are currently using VerseRef and ScriptureReference in our TS/JS code to represent a location in scripture. However, they both suffer from problems, albeit different ones.
VerseRef:
Can serialize to JSON properly using JSON.stringify(), but when deserialized doesn't become a VerseRef again automatically using JSON.parse() since VerseRef is a class.
VerseRef objects fail instanceof checks when passed between realms (MDN term - think "security domain").
Cannot represent more complex ideas like combined verses that exist in some translations where more than 1 version from the source is turned into a single unit in the destination. In a VerseRef this might look like MAT 1:2-3.
SerializedVerseRef already exists and doesn't suffer from any of these problems. Its main downfall is that it doesn't include its own functions to do things like convert a book ID to a book number, but there are helper classes (e.g., Canon) that can help.
Ira, TJ, and I agreed that using SerializedVerseRef is probably best for passing around pointers to scripture locations. In specific cases where we know a VerseRef will stay within a module we can always convert a SerializedVerseRef into a VerseRef to get access to the helper functions.
To Do:
[ ] Convert all uses of ScriptureReference to SerializedVerseRef in our TS/JS code.
[ ] Remove the ScriptureReference type altogether from platform-bible-utils.
[ ] Review all uses of VerseRef and convert them to SerializedVerseRef if they involve any data flowing in or out of the module. For internal uses within a module, uses of VerseRef can remain as-is.
Note that C# code does not need to change. The C# serialization routines already handle VerseRefs appropriately, and C# VerseRef objects don't have the same problems as JS VerseRef objects. The two runtimes handle object types fundamentally differently.
We are currently using
VerseRefandScriptureReferencein our TS/JS code to represent a location in scripture. However, they both suffer from problems, albeit different ones.VerseRef:JSON.stringify(), but when deserialized doesn't become aVerseRefagain automatically usingJSON.parse()sinceVerseRefis a class.VerseRefobjects failinstanceofchecks when passed between realms (MDN term - think "security domain").thisand context loss if not handled carefully.ScriptureReference:VerseRefthis might look likeMAT 1:2-3.SerializedVerseRef already exists and doesn't suffer from any of these problems. Its main downfall is that it doesn't include its own functions to do things like convert a book ID to a book number, but there are helper classes (e.g.,
Canon) that can help.Ira, TJ, and I agreed that using
SerializedVerseRefis probably best for passing around pointers to scripture locations. In specific cases where we know a VerseRef will stay within a module we can always convert aSerializedVerseRefinto aVerseRefto get access to the helper functions.To Do:
ScriptureReferencetoSerializedVerseRefin our TS/JS code.ScriptureReferencetype altogether fromplatform-bible-utils.VerseRefand convert them toSerializedVerseRefif they involve any data flowing in or out of the module. For internal uses within a module, uses ofVerseRefcan remain as-is.deserializefrom https://github.com/paranext/paranext-core/pull/1353.Note that C# code does not need to change. The C# serialization routines already handle
VerseRefs appropriately, and C#VerseRefobjects don't have the same problems as JSVerseRefobjects. The two runtimes handle object types fundamentally differently.