Promote bentleyjs-core APIs

common/api/bentleyjs-core.api.md

@@ -17,7 +17,7 @@ export function areEqualPossiblyUndefined<T, U>(t: T | undefined, u: U | undefin
 // @public
 export function asInstanceOf<T>(obj: any, constructor: Constructor<T>): T | undefined;
 
-// @beta
+// @public
 export function assert(condition: boolean, msg?: string): asserts condition;
 
 // @alpha
@@ -70,7 +70,7 @@ export class BeEvent<T extends Listener> {
     removeListener(listener: T, scope?: any): boolean;
 }
 
-// @beta
+// @public
 export class BeEventList<T extends Listener> {
     get(name: string): BeEvent<T>;
     remove(name: string): void;
@@ -146,7 +146,7 @@ export enum BriefcaseStatus {
     VersionNotFound = 131077
 }
 
-// @beta
+// @public
 export class ByteStream {
     constructor(buffer: ArrayBuffer | SharedArrayBuffer, subView?: {
         byteOffset: number;
@@ -165,7 +165,6 @@ export class ByteStream {
     get nextInt32(): number;
     get nextUint16(): number;
     get nextUint32(): number;
-    // (undocumented)
     nextUint32s(numUint32s: number): Uint32Array;
     get nextUint8(): number;
     readBytes(readPos: number, numBytes: number): Uint8Array;
@@ -266,19 +265,17 @@ export function compareStringsOrUndefined(lhs?: string, rhs?: string): number;
 // @public
 export function compareWithTolerance(a: number, b: number, tolerance?: number): number;
 
-// @beta
+// @public (undocumented)
 export type CompressedId64Set = string;
 
-// @beta
+// @public
 export namespace CompressedId64Set {
     export function compressArray(ids: Id64Array): CompressedId64Set;
     export function compressIds(ids: OrderedId64Iterable): CompressedId64Set;
     export function compressSet(ids: Id64Set): CompressedId64Set;
     export function decompressArray(compressedIds: CompressedId64Set, out?: Id64Array): Id64Array;
     export function decompressSet(compressedIds: CompressedId64Set, out?: Id64Set): Id64Set;
-    // @alpha
     export function iterable(ids: CompressedId64Set): OrderedId64Iterable;
-    // @alpha
     export function iterator(ids: CompressedId64Set): Iterator<Id64String>;
 }
 
@@ -1144,7 +1141,7 @@ export class LRUMap<K, V> extends LRUCache<K, V> {
     constructor(limit: number);
 }
 
-// @alpha
+// @public
 export class MutableCompressedId64Set implements OrderedId64Iterable {
     [Symbol.iterator](): Iterator<string, any, undefined>;
     constructor(ids?: CompressedId64Set);
@@ -1160,7 +1157,7 @@ export class MutableCompressedId64Set implements OrderedId64Iterable {
     reset(ids?: CompressedId64Set): void;
     }
 
-// @beta
+// @public
 export class ObservableSet<T> extends Set<T> {
     constructor(elements?: Iterable<T> | undefined);
     // @internal (undocumented)
@@ -1191,17 +1188,16 @@ export enum OpenMode {
 // @public
 export type OrderedComparator<T, U = T> = (lhs: T, rhs: U) => number;
 
-// @alpha (undocumented)
+// @public
 export class OrderedId64Array extends SortedArray<Id64String> {
     constructor();
-    // (undocumented)
     get ids(): OrderedId64Iterable;
 }
 
-// @beta
+// @public (undocumented)
 export type OrderedId64Iterable = Iterable<Id64String>;
 
-// @beta
+// @public
 export namespace OrderedId64Iterable {
     export function areEqualSets(ids1: OrderedId64Iterable, ids2: OrderedId64Iterable): boolean;
     export function compare(lhs: Id64String, rhs: Id64String): number;
@@ -1225,7 +1221,7 @@ export class OrderedSet<T> extends ReadonlyOrderedSet<T> {
     delete(value: T): boolean;
 }
 
-// @beta
+// @public
 export function partitionArray<T>(array: T[], criterion: (element: T) => boolean): number;
 
 // @public
@@ -1261,7 +1257,7 @@ export class PriorityQueue<T> implements Iterable<T> {
     protected _swap(a: number, b: number): void;
 }
 
-// @beta
+// @public
 export class ProcessDetector {
     static get isAndroidAppBackend(): boolean;
     static get isAndroidAppFrontend(): boolean;

common/api/summary/bentleyjs-core.exports.csv

@@ -4,21 +4,21 @@ beta;AbandonedError
 internal;addClientRequestContext: (metaData: any) => void
 public;areEqualPossiblyUndefined
 public;asInstanceOf
-beta;assert(condition: boolean, msg?: string): asserts condition
+public;assert(condition: boolean, msg?: string): asserts condition
 alpha;AsyncMutex
 alpha;AsyncMutexUnlockFnType = () => void
 beta;AuthStatus
 public;base64StringToUint8Array(base64: string): Uint8Array
 public;BeDuration
 public;BeEvent
-beta;BeEventList
+public;BeEventList
 public;BentleyError 
 public;BentleyLoggerCategory
 public;BentleyStatus
 public;BeTimePoint
 beta;BeUiEvent
 beta;BriefcaseStatus
-beta;ByteStream
+public;ByteStream
 public;ChangeSetApplyOption
 beta;ChangeSetStatus
 public;ClientRequestContext
@@ -32,10 +32,8 @@ public;comparePossiblyUndefined
 public;compareStrings(a: string, b: string): number
 public;compareStringsOrUndefined(lhs?: string, rhs?: string): number
 public;compareWithTolerance(a: number, b: number, tolerance?: number): number
-beta;CompressedId64Set = string
-beta;CompressedId64Set
-alpha;iterable(ids: CompressedId64Set): OrderedId64Iterable
-alpha;iterator(ids: CompressedId64Set): Iterator
+public;CompressedId64Set = string
+public;CompressedId64Set
 public;ComputePriorityFunction
 public;Config
 public;Constructor
@@ -84,19 +82,19 @@ public;lowerBound
 public;LRUCache
 public;LRUDictionary
 public;LRUMap
-alpha;MutableCompressedId64Set 
-beta;ObservableSet
+public;MutableCompressedId64Set 
+public;ObservableSet
 beta;OneAtATimeAction
 public;OpenMode
 public;OrderedComparator
-alpha;OrderedId64Array 
-beta;OrderedId64Iterable = Iterable
-beta;OrderedId64Iterable
+public;OrderedId64Array 
+public;OrderedId64Iterable = Iterable
+public;OrderedId64Iterable
 public;OrderedSet
-beta;partitionArray
+public;partitionArray
 public;PerfLogger 
 public;PriorityQueue
-beta;ProcessDetector
+public;ProcessDetector
 public;ReadonlyOrderedSet
 public;ReadonlySortedArray
 beta;RepositoryStatus

common/changes/@bentley/bentleyjs-core/bentleyjs-core-release-tags_2021-03-31-20-18.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@bentley/bentleyjs-core",
+      "comment": "Promote APIs to public.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@bentley/bentleyjs-core",
+  "email": "22944042+pmconne@users.noreply.github.com"
+}

core/bentley/src/Assert.ts

@@ -6,15 +6,16 @@
  * @module Utils
  */
 
-// @todo Needs to be commented out in a production environment.
 /**
- * Assert by throwing a programmer error.
+ * Asserts that a condition is `true`, and in development builds throws an error if it is not.
+ * This is an [assertion function](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions) that alters the
+ * behavior of the TypeScript compiler.
  * @param condition The result of a boolean expression.
  * @param msg An optional message to include in the thrown exception. Defaults to "Programmer Error".
  * @throws Error containing the specified message if condition is false.
  * @note This function should be used to validate conditions that should never realistically occur, or
  * which indicate a misuse of the API which should be eliminated during development.
- * @beta Need strategy for removing assert in production builds
+ * @public
  */
 export function assert(condition: boolean, msg?: string): asserts condition {
   if (!condition)

core/bentley/src/BeEvent.ts

@@ -138,15 +138,14 @@ export class BeUiEvent<TEventArgs> extends BeEvent<(args: TEventArgs) => void> {
 /**
  * A list of BeEvent objects, accessible by an event name.
  * This class may be used instead of explicitly declaring each BeEvent as a member of a containing class.
- * @beta Is this class used?
+ * @public
  */
 export class BeEventList<T extends Listener> {
   private _events: { [name: string]: BeEvent<T> | undefined } = {};
 
   /**
-   * Gets the BeEvent associated with a name.
+   * Gets the event associated with the specified name, creating the event if it does not already exist.
    * @param name The name of the event.
-   * @note the BeEvent will be created if none existed before this call.
    */
   public get(name: string): BeEvent<T> {
     let event = this._events[name];
@@ -159,7 +158,7 @@ export class BeEventList<T extends Listener> {
   }
 
   /**
-   * Removes the BeEvent associated with a name.
+   * Removes the event associated with a name.
    * @param name The name of the event.
    */
   public remove(name: string): void {

core/bentley/src/ByteStream.ts

@@ -9,11 +9,12 @@
 import { assert } from "./Assert";
 import { Id64, Id64String } from "./Id";
 
-/** Allows the contents of an ArrayBuffer to be consumed sequentially using methods to extract
+/** Allows the contents of an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
+ * to be consumed sequentially using methods to extract
  * data of a particular type from the bytes beginning at the current read position.
  * Methods and properties beginning with 'next' consume data at the current read position and advance it
  * by the size of the data read. The read position can also be directly adjusted by the caller.
- * @beta
+ * @public
  */
 export class ByteStream {
   private readonly _view: DataView;
@@ -39,33 +40,35 @@ export class ByteStream {
   /** Returns true if the current read position has been advanced past the end of the stream */
   public get isPastTheEnd(): boolean { return this.curPos > this.length; }
 
-  /** The current read position as an index into the stream of bytes */
+  /** The current read position as an index into the stream of bytes. */
   public get curPos(): number { return this._curPos; }
   public set curPos(pos: number) { this._curPos = pos; assert(!this.isPastTheEnd); }
 
-  /** Add the specified number of bytes to the current read position */
+  /** Adds the specified number of bytes to the current read position */
   public advance(numBytes: number): boolean { this.curPos = (this.curPos + numBytes); return !this.isPastTheEnd; }
   /** Subtracts the specified number of bytes from the current read position */
   public rewind(numBytes: number): boolean { if (this.curPos - numBytes < 0) return false; this.curPos = this.curPos - numBytes; return true; }
   /** Resets the current read position to the beginning of the stream */
   public reset(): void { this.curPos = 0; }
 
-  /** Read a uint8 at the current read position and advance by 1 byte. */
+  /** Read a unsigned 8-bit integer from the current read position and advance by 1 byte. */
   public get nextUint8(): number { return this.read(1, (view) => view.getUint8(this.curPos)); }
-  /** Read a uint16 at the current read position and advance by 2 bytes. */
+  /** Read an unsigned 16-bit integer from the current read position and advance by 2 bytes. */
   public get nextUint16(): number { return this.read(2, (view) => view.getUint16(this.curPos, true)); }
-  /** Read a uint32 at the current read position and advance by 4 bytes. */
+  /** Read an unsigned 32-bit integer from the current read position and advance by 4 bytes. */
   public get nextUint32(): number { return this.read(4, (view) => view.getUint32(this.curPos, true)); }
-  /** Read an int32 at the current read position and advance by 4 bytes. */
+  /** Read a signed 32-bit integer from the current read position and advance by 4 bytes. */
   public get nextInt32(): number { return this.read(4, (view) => view.getInt32(this.curPos, true)); }
-  /** Read a 32-bit floating point number at the current read position and advance by 4 bytes. */
+  /** Read a 32-bit floating point number from the current read position and advance by 4 bytes. */
   public get nextFloat32(): number { return this.read(4, (view) => view.getFloat32(this.curPos, true)); }
-  /** Read a 64-bit floating point number at the current read position and advance by 8 bytes. */
+  /** Read a 64-bit floating point number from the current read position and advance by 8 bytes. */
   public get nextFloat64(): number { return this.read(8, (view) => view.getFloat64(this.curPos, true)); }
-  /** Read a uint64 at the current read position, advance by 8 bytes, and return the uint64 value as an Id64String. */
+  /** Read an unsigned 64-bit integer from the current read position, advance by 8 bytes, and return the 64-bit value as an Id64String. */
   public get nextId64(): Id64String { return Id64.fromUint32Pair(this.nextUint32, this.nextUint32); }
 
-  /** Read the next numBytes bytes into a Uint8Array and advance by numBytes. */
+  /** Read the specified number of bytes beginning at the current read position into a Uint8Array and advance by the specified number of byte.
+   * @param numBytes The number of bytes to read.
+   */
   public nextBytes(numBytes: number): Uint8Array {
     const bytes = new Uint8Array(this.arrayBuffer, this.curPos + this._byteOffset, numBytes);
     this.advance(numBytes);
@@ -77,6 +80,7 @@ export class ByteStream {
     return new Uint8Array(this.arrayBuffer, readPos + this._byteOffset, numBytes);
   }
 
+  /** Read the specified number of unsigned 32-bit integers from the current read position and advance the read position. */
   public nextUint32s(numUint32s: number): Uint32Array {
     const numBytes = numUint32s * 4;
     const uint32s = new Uint32Array(this.arrayBuffer, this.curPos + this._byteOffset, numUint32s);