Working with 64-bit Ids

Every Entity within an IModel is identified by a unique 64-bit integer Id. Since JavaScript does not natively support 64-bit integers, 64-bit Ids are instead represented as strings. Strings containing 64-bit Ids are distinguished from ordinary strings through use of the Id64String type alias. For example, a ViewDefinition element has Id64String members called categorySelectorId and displayStyleId that specify the Ids of the CategorySelector and DisplayStyle elements associated with the view.

Ids are particularly important in communication between the front-end and the back-end. For example, IModelConnection.queryEntityIds executes a query and returns the Ids of those entities satisfying the query; while IModelConnection.Elements.getProps accepts a set of element Ids and returns a JSON representation of each specified element.

The 64 bits of an Id are divided into two parts:

• The upper 24 bits contain the BriefcaseId identifying the briefcase that originally created the entity.
• The lower 40 bits contain the entity's local Id, unique and sequentially assigned within a single BriefcaseId. A local Id of 0 is illegal.

An Id is considered either "valid" (identifies an existing entity) or "invalid" (does not identify any existing entity). The latter is represented by the 64-bit value 0. An invalid Id does not necessarily indicate an error - for example, an Element that has no parent element stores an invalid Id as its parentId.

A BriefcaseId of 0xffffff indicates "no briefcase". It is used instead to produce "transient" Ids that refer to non-persistent entities. Transient Ids are chiefly used by Decorators to produce decoration graphics with which the user can interact by clicking on our mousing over them. IModelConnection.transientIds supplies a mechanism for obtaining a unique transient Id.

TypeScript representation of a 64-bit Id

A string must meet either of the following criteria to be considered a well-formed (i.e. normalized) representation of an Id:

• It holds the exact string "0", indicating an invalid Id (note, no leading "0x"); or
• It holds a well-formed hexadecimal representation of a non-zero 64-bit integer, indicating a valid Id.

A well-formed valid Id string meets the following criteria:

• Contains no uppercase letters.
• Contains no spaces.
• Begins with the prefix "0x".
• The first hexadecimal digit following the prefix is a non-zero hexadecimal digit (i.e., in the range [a-z1-9] (no leading zeros).
• If no briefcase Id is present, the remainder of the string consists of no more than 9 hexadecimal digits.
• If a briefcase Id is present, the remainder of the string consists of the briefcase Id as no more than 5 hexadecimal digits, followed by exactly 10 hexadecimal digits representing the local Id, of which one must be non-zero.

Id64String

The type alias Id64String is used extensively throughout the iTwin.js API to indicate that a function argument, return type, or object property is assumed to be a well-formed Id string according to the above criteria.

The Id64 namespace supplies functions for working with Id64Strings.

The following Id64 functions can produce well-formed Id64Strings:

• Id64.fromJSON produces an Id64String from its JSON representation.
• Id64.fromString normalizes a string value into a well-formed Id64String.
• Id64.fromLocalAndBriefcaseIds concatenates integer briefcase and local Ids into an Id64String.
• Id64.fromUint32Pair concatenates a pair of 32-bit integers into an Id64String.

Id64.fromJSON and Id64.fromString should be used when your code has a string value that may represent an Id but may not be well-formed - e.g., it may contain uppercase hexadecimal digits, leading or trailing whitespace, and so on. Examples include strings originating from user input or from some web service. Ids originating from calls to the back-end can be expected to be well-formed.

Id64 also provides functions for interrogating Id strings:

• Id64.isValid, Id64.isInvalid, and Id64.isTransient determine the type of Id represented by a well-formed Id string.
• Id64.isId64 determines whether an arbitrary string value contains a well-formed Id string.
• Id64.getLocalId and Id64.getBriefcaseId extract the local and briefcase Ids from a well-formed Id string.

Id64Set, Id64Array, and Id64Arg

It is often necessary to refer to a group of Ids. There are two type aliases for this purpose:

• Id64Set
• Id64Array

An Id64Array is more efficient memory-wise and insertion-wise, but does not enforce uniqueness (i.e. the same entry may appear multiple times in the group.) Id64Set enforces uniqueness and is more efficient for searching.

Note that both Id64Set and Id64Array are merely groups of strings. The type aliases simply indicate that the group should only contain well-formed Id strings.

Sometimes functions can accept one or more Ids. In this case the argument type is often declared to be Id64Arg. Id64Arg is merely a type alias for Id64String | Id64Array | Id64Set so that callers may supply either a single Id or a group of Ids. There is a convenience function Id64.toIdSet that converts an Id64Arg into an Id64Set. Then, is it simple to process the arguments with code like:

 public addCategories(arg: Id64Arg) { Id64.toIdSet(arg).forEach((id) => this.categories.add(id)); }