docs(declaration): add comments into generated declaration files

pubnub · May 15, 2024 · a36d78f · a36d78f
1 parent 5c14f33
commit a36d78f
Show file tree

Hide file tree

Showing 222 changed files with 10,450 additions and 55 deletions.
diff --git a/dist/web/pubnub.js b/dist/web/pubnub.js
@@ -3521,6 +3521,8 @@
 	 * Apply configuration default values.
 	 *
 	 * @param configuration - User-provided configuration.
+	 *
+	 * @internal
 	 */
 	const setDefaults$1 = (configuration) => {
 	    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;

diff --git a/lib/cbor/common.js b/lib/cbor/common.js
@@ -1,10 +1,25 @@
 "use strict";
+/**
+ * Cbor decoder module.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * CBOR data decoder.
+ *
+ * @internal
+ */
 class Cbor {
     constructor(decode, base64ToBinary) {
         this.decode = decode;
         this.base64ToBinary = base64ToBinary;
     }
+    /**
+     * Decode CBOR base64-encoded object.
+     *
+     * @param tokenString - Base64-encoded token.
+     *
+     * @returns Token object decoded from CBOR.
+     */
     decodeToken(tokenString) {
         let padding = '';
         if (tokenString.length % 4 === 3)

diff --git a/lib/core/components/abort_signal.js b/lib/core/components/abort_signal.js
@@ -10,6 +10,11 @@ class AbortError extends Error {
     }
 }
 exports.AbortError = AbortError;
+/**
+ * Event Engine stored effect processing cancellation signal.
+ *
+ * @internal
+ */
 class AbortSignal extends subject_1.Subject {
     constructor() {
         super(...arguments);

diff --git a/lib/core/components/base64_codec.js b/lib/core/components/base64_codec.js
@@ -2,12 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.encode = exports.decode = void 0;
 const BASE64_CHARMAP = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=';
+/**
+ * Decode a Base64 encoded string.
+ *
+ * @param paddedInput Base64 string with padding
+ * @returns ArrayBuffer with decoded data
+ *
+ * @internal
+ */
 function decode(paddedInput) {
+    // Remove up to last two equal signs.
     const input = paddedInput.replace(/==?$/, '');
     const outputLength = Math.floor((input.length / 4) * 3);
+    // Prepare output buffer.
     const data = new ArrayBuffer(outputLength);
     const view = new Uint8Array(data);
     let cursor = 0;
+    /**
+     * Returns the next integer representation of a sixtet of bytes from the input
+     * @returns sixtet of bytes
+     */
     function nextSixtet() {
         const char = input.charAt(cursor++);
         const index = BASE64_CHARMAP.indexOf(char);
@@ -17,14 +31,17 @@ function decode(paddedInput) {
         return index;
     }
     for (let i = 0; i < outputLength; i += 3) {
+        // Obtain four sixtets
         const sx1 = nextSixtet();
         const sx2 = nextSixtet();
         const sx3 = nextSixtet();
         const sx4 = nextSixtet();
+        // Encode them as three octets
         const oc1 = ((sx1 & 0b00111111) << 2) | (sx2 >> 4);
         const oc2 = ((sx2 & 0b00001111) << 4) | (sx3 >> 2);
         const oc3 = ((sx3 & 0b00000011) << 6) | (sx4 >> 0);
         view[i] = oc1;
+        // Skip padding bytes.
         if (sx3 != 64)
             view[i + 1] = oc2;
         if (sx4 != 64)
@@ -33,6 +50,14 @@ function decode(paddedInput) {
     return data;
 }
 exports.decode = decode;
+/**
+ * Encode `ArrayBuffer` as a Base64 encoded string.
+ *
+ * @param input ArrayBuffer with source data.
+ * @returns Base64 string with padding.
+ *
+ * @internal
+ */
 function encode(input) {
     let base64 = '';
     const encodings = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
@@ -42,25 +67,32 @@ function encode(input) {
     const mainLength = byteLength - byteRemainder;
     let a, b, c, d;
     let chunk;
+    // Main loop deals with bytes in chunks of 3
     for (let i = 0; i < mainLength; i = i + 3) {
+        // Combine the three bytes into a single integer
         chunk = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
-        a = (chunk & 16515072) >> 18;
-        b = (chunk & 258048) >> 12;
-        c = (chunk & 4032) >> 6;
-        d = chunk & 63;
+        // Use bitmasks to extract 6-bit segments from the triplet
+        a = (chunk & 16515072) >> 18; // 16515072 = (2^6 - 1) << 18
+        b = (chunk & 258048) >> 12; // 258048   = (2^6 - 1) << 12
+        c = (chunk & 4032) >> 6; // 4032     = (2^6 - 1) << 6
+        d = chunk & 63; // 63       = 2^6 - 1
+        // Convert the raw binary segments to the appropriate ASCII encoding
         base64 += encodings[a] + encodings[b] + encodings[c] + encodings[d];
     }
+    // Deal with the remaining bytes and padding
     if (byteRemainder == 1) {
         chunk = bytes[mainLength];
-        a = (chunk & 252) >> 2;
-        b = (chunk & 3) << 4;
+        a = (chunk & 252) >> 2; // 252 = (2^6 - 1) << 2
+        // Set the 4 least significant bits to zero
+        b = (chunk & 3) << 4; // 3   = 2^2 - 1
         base64 += encodings[a] + encodings[b] + '==';
     }
     else if (byteRemainder == 2) {
         chunk = (bytes[mainLength] << 8) | bytes[mainLength + 1];
-        a = (chunk & 64512) >> 10;
-        b = (chunk & 1008) >> 4;
-        c = (chunk & 15) << 2;
+        a = (chunk & 64512) >> 10; // 64512 = (2^6 - 1) << 10
+        b = (chunk & 1008) >> 4; // 1008  = (2^6 - 1) << 4
+        // Set the 2 least significant bits to zero
+        c = (chunk & 15) << 2; // 15    = 2^4 - 1
         base64 += encodings[a] + encodings[b] + encodings[c] + '=';
     }
     return base64;

diff --git a/lib/core/components/configuration.js b/lib/core/components/configuration.js
@@ -1,15 +1,39 @@
 "use strict";
+/**
+ * {@link PubNub} client configuration module.
+ */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeConfiguration = void 0;
 const uuid_1 = __importDefault(require("./uuid"));
+// --------------------------------------------------------
+// ----------------------- Defaults -----------------------
+// --------------------------------------------------------
+// region Defaults
+/**
+ * Whether encryption (if set) should use random initialization vector or not.
+ *
+ * @internal
+ */
 const USE_RANDOM_INITIALIZATION_VECTOR = true;
+/**
+ * Create {@link PubNub} client private configuration object.
+ *
+ * @param base - User- and platform-provided configuration.
+ * @param setupCryptoModule - Platform-provided {@link CryptoModule} configuration block.
+ *
+ * @returns `PubNub` client private configuration.
+ *
+ * @internal
+ */
 const makeConfiguration = (base, setupCryptoModule) => {
     var _a, _b, _c;
+    // Ensure that retry policy has proper configuration (if has been set).
     (_a = base.retryConfiguration) === null || _a === void 0 ? void 0 : _a.validate();
     (_b = base.useRandomIVs) !== null && _b !== void 0 ? _b : (base.useRandomIVs = USE_RANDOM_INITIALIZATION_VECTOR);
+    // Override origin value.
     base.origin = standardOrigin((_c = base.ssl) !== null && _c !== void 0 ? _c : false, base.origin);
     const cryptoModule = base.cryptoModule;
     if (cryptoModule)
@@ -98,6 +122,10 @@ const makeConfiguration = (base, setupCryptoModule) => {
             const sdk = Object.values(this._pnsdkSuffix).join(separator);
             return sdk.length > 0 ? separator + sdk : '';
         },
+        // --------------------------------------------------------
+        // ---------------------- Deprecated ----------------------
+        // --------------------------------------------------------
+        // region Deprecated
         getUUID() {
             return this.getUserId();
         },
@@ -110,13 +138,22 @@ const makeConfiguration = (base, setupCryptoModule) => {
         getCustomDecrypt() {
             return base.customDecrypt;
         } });
+    // Setup `CryptoModule` if possible.
     if (base.cipherKey)
         clientConfiguration.setCipherKey(base.cipherKey);
     else if (cryptoModule)
         clientConfiguration._cryptoModule = cryptoModule;
     return clientConfiguration;
 };
 exports.makeConfiguration = makeConfiguration;
+/**
+ * Decide {@lin PubNub} service REST API origin.
+ *
+ * @param secure - Whether preferred to use secured connection or not.
+ * @param origin - User-provided or default origin.
+ *
+ * @returns `PubNub` REST API endpoints origin.
+ */
 const standardOrigin = (secure, origin) => {
     const protocol = secure ? 'https://' : 'http://';
     if (typeof origin === 'string')

diff --git a/lib/core/components/cryptography/hmac-sha256.js b/lib/core/components/cryptography/hmac-sha256.js
@@ -1,4 +1,11 @@
 "use strict";
+/*eslint-disable */
+/*
+ CryptoJS v3.1.2
+ code.google.com/p/crypto-js
+ (c) 2009-2013 by Jeff Mott. All rights reserved.
+ code.google.com/p/crypto-js/wiki/License
+ */
 var CryptoJS = CryptoJS ||
     (function (h, s) {
         var f = {}, g = (f.lib = {}), q = function () { }, m = (g.Base = {
@@ -170,6 +177,7 @@ var CryptoJS = CryptoJS ||
         var t = (f.algo = {});
         return f;
     })(Math);
+// SHA256
 (function (h) {
     for (var s = CryptoJS, f = s.lib, g = f.WordArray, q = f.Hasher, f = s.algo, m = [], r = [], l = function (a) {
         return (4294967296 * (a - (a | 0))) | 0;
@@ -248,6 +256,7 @@ var CryptoJS = CryptoJS ||
     s.SHA256 = q._createHelper(f);
     s.HmacSHA256 = q._createHmacHelper(f);
 })(Math);
+// HMAC SHA256
 (function () {
     var h = CryptoJS, s = h.enc.Utf8;
     h.algo.HMAC = h.lib.Base.extend({
@@ -279,6 +288,7 @@ var CryptoJS = CryptoJS ||
         },
     });
 })();
+// Base64
 (function () {
     var u = CryptoJS, p = u.lib.WordArray;
     u.enc.Base64 = {
@@ -310,6 +320,7 @@ var CryptoJS = CryptoJS ||
         _map: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=',
     };
 })();
+// BlockCipher
 (function (u) {
     function p(b, n, a, c, e, j, k) {
         b = b + ((n & a) | (~n & c)) + e + k;
@@ -390,6 +401,7 @@ var CryptoJS = CryptoJS ||
         return s.create(p).compute(d, l);
     };
 })();
+// Cipher
 CryptoJS.lib.Cipher ||
     (function (u) {
         var p = CryptoJS, d = p.lib, l = d.Base, s = d.WordArray, t = d.BufferedBlockAlgorithm, r = p.enc.Base64, w = p.algo.EvpKDF, v = (d.Cipher = t.extend({
@@ -586,6 +598,7 @@ CryptoJS.lib.Cipher ||
             },
         }));
     })();
+// AES
 (function () {
     for (var u = CryptoJS, p = u.lib.BlockCipher, d = u.algo, l = [], s = [], t = [], r = [], w = [], v = [], b = [], x = [], q = [], n = [], a = [], c = 0; 256 > c; c++)
         a[c] = 128 > c ? c << 1 : (c << 1) ^ 283;
@@ -656,6 +669,7 @@ CryptoJS.lib.Cipher ||
     }));
     u.AES = p._createHelper(d);
 })();
+// Mode ECB
 CryptoJS.mode.ECB = (function () {
     var ECB = CryptoJS.lib.BlockCipherMode.extend();
     ECB.Encryptor = ECB.extend({