docs: Add release tags and export symbols from entry point (#405)

Enable stricter api-extractor flags to lint our tsdoc. 
Trim definitions file to be public symbols only.

NODE-2837

Author: nbbeeken

api-extractor.json

@@ -9,7 +9,7 @@
   },
   "dtsRollup": {
     "enabled": true,
-    "untrimmedFilePath": "<projectFolder>/<unscopedPackageName>.d.ts"
+    "publicTrimmedFilePath": "<projectFolder>/<unscopedPackageName>.d.ts"
   },
   "tsdocMetadata": {
     "enabled": false
@@ -23,28 +23,16 @@
     },
     "extractorMessageReporting": {
       "default": {
-        "logLevel": "warning"
+        "logLevel": "error"
       },
       "ae-internal-missing-underscore": {
-        "logLevel": "error",
-        "addToApiReportFile": false
-      },
-      "ae-missing-release-tag": {
         "logLevel": "none",
         "addToApiReportFile": false
-      },
-      "ae-incompatible-release-tags": {
-        "logLevel": "none",
-        "addToApiReportFile": false
-      },
-      "ae-unresolved-link": {
-        "addToApiReportFile": false,
-        "logLevel": "error"
       }
     },
     "tsdocMessageReporting": {
       "default": {
-        "logLevel": "none"
+        "logLevel": "error"
       }
     }
   }

src/binary.ts

@@ -3,21 +3,27 @@ import { ensureBuffer } from './ensure_buffer';
 import type { EJSONOptions } from './extended_json';
 import { parseUUID, UUIDExtended } from './uuid';
 
-type BinarySequence = Uint8Array | Buffer | number[];
+/** @public */
+export type BinarySequence = Uint8Array | Buffer | number[];
 
+/** @public */
 export interface BinaryExtendedLegacy {
   $type: string;
   $binary: string;
 }
 
+/** @public */
 export interface BinaryExtended {
   $binary: {
     subType: string;
     base64: string;
   };
 }
 
-/** A class representation of the BSON Binary type. */
+/**
+ * A class representation of the BSON Binary type.
+ * @public
+ */
 export class Binary {
   _bsontype!: 'Binary';
 

src/bson.ts

@@ -5,12 +5,6 @@ import { DBRef } from './db_ref';
 import { Decimal128 } from './decimal128';
 import { Double } from './double';
 import { ensureBuffer } from './ensure_buffer';
-import {
-  deserialize as EJSON_deserialize,
-  parse as EJSON_parse,
-  serialize as EJSON_serialize,
-  stringify as EJSON_stringify
-} from './extended_json';
 import { Int32 } from './int_32';
 import { Long } from './long';
 import { Map } from './map';
@@ -24,7 +18,8 @@ import { serializeInto as internalSerialize, SerializeOptions } from './parser/s
 import { BSONRegExp } from './regexp';
 import { BSONSymbol } from './symbol';
 import { Timestamp } from './timestamp';
-
+export { BinaryExtended, BinaryExtendedLegacy, BinarySequence } from './binary';
+export { CodeExtended } from './code';
 export {
   BSON_BINARY_SUBTYPE_BYTE_ARRAY,
   BSON_BINARY_SUBTYPE_DEFAULT,
@@ -61,6 +56,24 @@ export {
   JS_INT_MAX,
   JS_INT_MIN
 } from './constants';
+export { DBRefLike } from './db_ref';
+export { Decimal128Extended } from './decimal128';
+export { DoubleExtended } from './double';
+export { EJSON, EJSONOptions } from './extended_json';
+export { Int32Extended } from './int_32';
+export { LongExtended } from './long';
+export { MaxKeyExtended } from './max_key';
+export { MinKeyExtended } from './min_key';
+export { ObjectIdExtended, ObjectIdLike } from './objectid';
+export { BSONRegExpExtended, BSONRegExpExtendedLegacy } from './regexp';
+export { BSONSymbolExtended } from './symbol';
+export {
+  LongWithoutOverrides,
+  LongWithoutOverridesClass,
+  TimestampExtended,
+  TimestampOverrides
+} from './timestamp';
+export { UUIDExtended } from './uuid';
 export { SerializeOptions, DeserializeOptions };
 export {
   Code,
@@ -83,13 +96,7 @@ export {
   ObjectId as ObjectID
 };
 
-export const EJSON = {
-  parse: EJSON_parse,
-  stringify: EJSON_stringify,
-  serialize: EJSON_serialize,
-  deserialize: EJSON_deserialize
-};
-
+/** @public */
 export interface Document {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   [key: string]: any;
@@ -106,6 +113,7 @@ let buffer = Buffer.alloc(MAXSIZE);
  * Sets the size of the internal serialization buffer.
  *
  * @param size - The desired size for the internal serialization buffer
+ * @public
  */
 export function setInternalBufferSize(size: number): void {
   // Resize the internal serialization buffer if needed
@@ -119,6 +127,7 @@ export function setInternalBufferSize(size: number): void {
  *
  * @param object - the Javascript object to serialize.
  * @returns Buffer object containing the serialized object.
+ * @public
  */
 export function serialize(object: Document, options: SerializeOptions = {}): Buffer {
   // Unpack the options
@@ -164,6 +173,7 @@ export function serialize(object: Document, options: SerializeOptions = {}): Buf
  * @param object - the Javascript object to serialize.
  * @param finalBuffer - the Buffer you pre-allocated to store the serialized BSON object.
  * @returns the index pointing to the last written byte in the buffer.
+ * @public
  */
 export function serializeWithBufferAndIndex(
   object: Document,
@@ -199,6 +209,7 @@ export function serializeWithBufferAndIndex(
  *
  * @param buffer - the buffer containing the serialized set of BSON documents.
  * @returns returns the deserialized Javascript Object.
+ * @public
  */
 export function deserialize(
   buffer: Buffer | ArrayBufferView | ArrayBuffer,
@@ -207,6 +218,7 @@ export function deserialize(
   return internalDeserialize(ensureBuffer(buffer), options);
 }
 
+/** @public */
 export type CalculateObjectSizeOptions = Pick<
   SerializeOptions,
   'serializeFunctions' | 'ignoreUndefined'
@@ -217,6 +229,7 @@ export type CalculateObjectSizeOptions = Pick<
  *
  * @param object - the Javascript object to calculate the BSON byte size for
  * @returns size of BSON object in bytes
+ * @public
  */
 export function calculateObjectSize(
   object: Document,
@@ -242,6 +255,7 @@ export function calculateObjectSize(
  * @param docStartIndex - the index in the documents array from where to start inserting documents.
  * @param options - additional options used for the deserialization.
  * @returns next index in the buffer after deserialization **x** numbers of documents.
+ * @public
  */
 export function deserializeStream(
   data: Buffer | ArrayBufferView | ArrayBuffer,

src/code.ts

@@ -1,11 +1,15 @@
 import type { Document } from './bson';
 
+/** @public */
 export interface CodeExtended {
   $code: string | Function;
   $scope?: Document;
 }
 
-/** A class representation of the BSON Code type. */
+/**
+ * A class representation of the BSON Code type.
+ * @public
+ */
 export class Code {
   _bsontype!: 'Code';
 

src/constants.ts

@@ -1,96 +1,104 @@
-// BSON MAX VALUES
+/** @internal */
 export const BSON_INT32_MAX = 0x7fffffff;
+/** @internal */
 export const BSON_INT32_MIN = -0x80000000;
-
+/** @internal */
 export const BSON_INT64_MAX = Math.pow(2, 63) - 1;
+/** @internal */
 export const BSON_INT64_MIN = -Math.pow(2, 63);
 
-// JS MAX PRECISE VALUES
-// Any integer up to 2^53 can be precisely represented by a double.
+/**
+ * Any integer up to 2^53 can be precisely represented by a double.
+ * @internal
+ */
 export const JS_INT_MAX = Math.pow(2, 53);
-// Any integer down to -2^53 can be precisely represented by a double.
+
+/**
+ * Any integer down to -2^53 can be precisely represented by a double.
+ * @internal
+ */
 export const JS_INT_MIN = -Math.pow(2, 53);
 
-/** Number BSON Type */
+/** Number BSON Type @internal */
 export const BSON_DATA_NUMBER = 1;
 
-/** String BSON Type */
+/** String BSON Type @internal */
 export const BSON_DATA_STRING = 2;
 
-/** Object BSON Type */
+/** Object BSON Type @internal */
 export const BSON_DATA_OBJECT = 3;
 
-/** Array BSON Type */
+/** Array BSON Type @internal */
 export const BSON_DATA_ARRAY = 4;
 
-/** Binary BSON Type */
+/** Binary BSON Type @internal */
 export const BSON_DATA_BINARY = 5;
 
-/** Binary BSON Type */
+/** Binary BSON Type @internal */
 export const BSON_DATA_UNDEFINED = 6;
 
-/** ObjectId BSON Type */
+/** ObjectId BSON Type @internal */
 export const BSON_DATA_OID = 7;
 
-/** Boolean BSON Type */
+/** Boolean BSON Type @internal */
 export const BSON_DATA_BOOLEAN = 8;
 
-/** Date BSON Type */
+/** Date BSON Type @internal */
 export const BSON_DATA_DATE = 9;
 
-/** null BSON Type */
+/** null BSON Type @internal */
 export const BSON_DATA_NULL = 10;
 
-/** RegExp BSON Type */
+/** RegExp BSON Type @internal */
 export const BSON_DATA_REGEXP = 11;
 
-/** Code BSON Type */
+/** Code BSON Type @internal */
 export const BSON_DATA_DBPOINTER = 12;
 
-/** Code BSON Type */
+/** Code BSON Type @internal */
 export const BSON_DATA_CODE = 13;
 
-/** Symbol BSON Type */
+/** Symbol BSON Type @internal */
 export const BSON_DATA_SYMBOL = 14;
 
-/** Code with Scope BSON Type */
+/** Code with Scope BSON Type @internal */
 export const BSON_DATA_CODE_W_SCOPE = 15;
 
-/** 32 bit Integer BSON Type */
+/** 32 bit Integer BSON Type @internal */
 export const BSON_DATA_INT = 16;
 
-/** Timestamp BSON Type */
+/** Timestamp BSON Type @internal */
 export const BSON_DATA_TIMESTAMP = 17;
 
-/** Long BSON Type */
+/** Long BSON Type @internal */
 export const BSON_DATA_LONG = 18;
 
-/** Decimal128 BSON Type */
+/** Decimal128 BSON Type @internal */
 export const BSON_DATA_DECIMAL128 = 19;
 
-/** MinKey BSON Type */
+/** MinKey BSON Type @internal */
 export const BSON_DATA_MIN_KEY = 0xff;
 
-/** MaxKey BSON Type */
+/** MaxKey BSON Type @internal */
 export const BSON_DATA_MAX_KEY = 0x7f;
 
-/** Binary Default Type */
+/** Binary Default Type @internal */
 export const BSON_BINARY_SUBTYPE_DEFAULT = 0;
 
-/** Binary Function Type */
+/** Binary Function Type @internal */
 export const BSON_BINARY_SUBTYPE_FUNCTION = 1;
 
-/** Binary Byte Array Type */
+/** Binary Byte Array Type @internal */
 export const BSON_BINARY_SUBTYPE_BYTE_ARRAY = 2;
 
-/** Binary Deprecated UUID Type @deprecated Please use BSON_BINARY_SUBTYPE_UUID_NEW */
+/** Binary Deprecated UUID Type @deprecated Please use BSON_BINARY_SUBTYPE_UUID_NEW @internal */
 export const BSON_BINARY_SUBTYPE_UUID = 3;
 
-/** Binary UUID Type */
+/** Binary UUID Type @internal */
 export const BSON_BINARY_SUBTYPE_UUID_NEW = 4;
 
-/** Binary MD5 Type */
+/** Binary MD5 Type @internal */
 export const BSON_BINARY_SUBTYPE_MD5 = 5;
 
-/** Binary User Defined Type */
+/** Binary User Defined Type @internal */
 export const BSON_BINARY_SUBTYPE_USER_DEFINED = 128;

src/db_ref.ts

@@ -3,17 +3,22 @@ import type { EJSONOptions } from './extended_json';
 import type { ObjectId } from './objectid';
 import { isObjectLike } from './parser/utils';
 
+/** @public */
 export interface DBRefLike {
   $ref: string;
   $id: ObjectId;
   $db?: string;
 }
 
+/** @internal */
 export function isDBRefLike(value: unknown): value is DBRefLike {
   return isObjectLike(value) && value['$id'] != null && value['$ref'] != null;
 }
 
-/** A class representation of the BSON DBRef type. */
+/**
+ * A class representation of the BSON DBRef type.
+ * @public
+ */
 export class DBRef {
   _bsontype!: 'DBRef';
 
@@ -49,7 +54,7 @@ export class DBRef {
   get namespace(): string {
     return this.collection;
   }
-  /** @internal */
+
   set namespace(value: string) {
     this.collection = value;
   }

src/decimal128.ts

@@ -153,11 +153,15 @@ function invalidErr(string: string, message: string) {
   throw new TypeError(`"${string}" is not a valid Decimal128 string - ${message}`);
 }
 
+/** @public */
 export interface Decimal128Extended {
   $numberDecimal: string;
 }
 
-/** A class representation of the BSON Decimal128 type. */
+/**
+ * A class representation of the BSON Decimal128 type.
+ * @public
+ */
 export class Decimal128 {
   _bsontype!: 'Decimal128';