0.163.0 Change Notes

Breaking changes to Id64

The use of Id64 objects to represent 64-bit IDs was determined to produce measurable negative impact on both memory consumption and code execution time. This impact was amplified by inconsistencies within the iModel.js library - APIs dealing with 64-bit IDs would variously represent them as plain strings, Id64 objects, or either through use of the type alias Id64String = Id64 | string. Frequent conversion from one representation to another would often be required when using these APIs. The naming of some functions was also ambiguous.

To address these problems the following changes were made:

• The Id64String type alias was reduced to a simple alias for string. It now serves as a marker type indicating that a string variable or function argument is expected to conform to the semantics of a well-formed 64-bit ID.
• All function arguments, function return types, and class members of type Id64 were changed to Id64String.
• The Id64 class was turned into a namespace.
• Functions for validating, and interrogating Id64Strings were added to the Id64 namespace.
• The code for parsing, validating, and interrogating Id64Strings was optimized to execute more quickly.
• Id64.getLow() and Id64.getHigh() were renamed to Id64.getLocalId and Id64.getBriefcaseId.

See Working with IDs for an updated overview.

The pervasiveness of 64-bit IDs in iModel.js make these changes very likely to break existing code in consumers of the iModel.js packages. To adapt such code:

• Replace all usage of Id64 objects with Id64String.
• Replace all calls to the Id64 constructor with a call to one of the functions in Id64 returning an Id64String based on your input to the constructor:
  • If your input is a JSON representation of an ID - type string | undefined - use Id64.fromJSON.
  • If your input is a string, use Id64.fromString if the string is not known to already contain a well-formed ID; otherwise elide the call.
  • If your input is an array of 2 numbers indicating a briefcase ID and local ID, use Id64.fromLocalAndBriefcaseIds.
• Replace all calls to non-static Id64 methods with equivalent methods accepting an Id64String.
• Replace calls to equals and areEqual with the built-in comparison operators.

Breaking changes to Guid

To keep Id64 and Guid consistent, similar changes were done to the Guid class.

The following changes were made:

• The GuidString type alias was reduced to a simple alias for string. It now serves as a marker type indicating that a string variable or function argument is expected to conform to the semantics of a well-formed GUID.
• All function arguments, function return types, and class members of type Guid were changed to GuidString.
• The Guid class was turned into the Guid namespace.
• Functions for validating GuidStrings were added to the Guid namespace.

The pervasiveness of GUIDs in iModel.js make these changes very likely to break existing code in consumers of the iModel.js packages. To adapt such code:

• Replace all usage of Guid objects with GuidString.
• Replace all calls to the Guid constructor with a call to one of the functions from the Guid namespace returning an GuidString based on your input to the constructor
  • In particular, new Guid(true) is to be replaced by Guid.createValue().
• Replace all calls to non-static Guid methods with equivalent methods accepting an GuidString.
• Replace calls to equals and areEqual with the built-in comparison operators.

Breaking changes to RPC web server configuration

If you do not use IModelJsExpressServer to manage your backend web server, you must add a GET route that invokes WebAppRpcProtocol.handleOperationGetRequest to your express application. Cacheable RPC operations (including tile content requests) now use the HTTP GET method when configured using RpcConfiguration.

Last Updated: 13 June, 2024