Separate internal APIs from public ones (#568)

Includes the following:
* Marks internal modules and class members with @internal tag which is supported by both tsc and typedoc
* Fixes typedoc flags, so that it now ignores internal stuff
* Excludes internal modules and members from tsc output
* Excludes source maps from tsc output
* Moves typings for long and bluebird into non-dev dependencies, as TS users need them (see #537)
* Adds test for declarations produced by tsc
* Also includes some code improvements, like reformatting, interface extraction, etc.

Author: puzpuzpuz

.npmignore

@@ -1,4 +1,5 @@
 .idea/
+.vscode/
 .nyc_output/
 benchmark/
 code_samples/
@@ -7,6 +8,8 @@ docs/
 scripts/
 src/
 test/
+tsconfig.json
+typedoc.json
 .editorconfig
 .eslintignore
 .eslintrc.js
@@ -15,6 +18,5 @@ test/
 DOCUMENTATION.md
 download-remote-controller.js
 *.iml
-.editorconfig
 *.jar
 *.log

DOCUMENTATION.md

@@ -2694,7 +2694,7 @@ An example configuration is shown below.
 ```javascript
 const readFile = util.promisify(fs.readFile);
 
-class SSLFactory {
+class SSLOptionsFactory {
     async init(properties) {
         const promises = [];
         this.keepOrder = properties.userDefinedProperty1;
@@ -2732,7 +2732,7 @@ const cfg = {
     network: {
         ssl: {
             enabled: true,
-            sslOptionsFactory: new SSLFactory(),
+            sslOptionsFactory: new SSLOptionsFactory(),
             sslOptionsFactoryProperties: {
                 caPath: 'ca.pem',
                 keyPath: 'key.pem',
@@ -2744,7 +2744,7 @@ const cfg = {
 };
 ```
 
-The client calls the method `init` with the properties section defined in the configuration. Then the client calls the method `getSSLOptions` of `SSLFactory` to create the `options` object.
+The client calls the `init()` method with the `properties` configuration option. Then the client calls the `getSSLOptions()` method of `SSLOptionsFactory` to create the `options` object.
 
 ## 8.2. Credentials
 

package.json

@@ -3,13 +3,14 @@
     "version": "4.0.0",
     "description": "Hazelcast - open source In-Memory Data Grid - client for Node.js",
     "main": "lib/index.js",
+    "types": "lib/index.d.ts",
     "dependencies": {
         "bluebird": "3.7.2",
-        "long": "4.0.0"
+        "@types/bluebird": "3.5.32",
+        "long": "4.0.0",
+        "@types/long": "4.0.1"
     },
     "devDependencies": {
-        "@types/bluebird": "^3.5.32",
-        "@types/long": "^4.0.1",
         "@types/node": "^8.10.60",
         "@typescript-eslint/eslint-plugin": "^2.34.0",
         "@typescript-eslint/parser": "^2.34.0",
@@ -24,6 +25,7 @@
         "rimraf": "^3.0.2",
         "sinon": "^9.0.2",
         "thrift": "^0.12.0",
+        "typedoc": "^0.18.0",
         "typescript": "^3.9.5",
         "winston": "^3.2.1"
     },
@@ -35,10 +37,11 @@
         "compile": "tsc",
         "pretest": "node download-remote-controller.js",
         "test": "mocha --recursive",
+        "validate-user-code": "tsc --build test/user_code/tsconfig.json",
         "precoverage": "node download-remote-controller.js",
         "coverage": "rimraf coverage && nyc node_modules/mocha/bin/_mocha -- --recursive --reporter-options mochaFile=report.xml --reporter mocha-junit-reporter",
         "pregenerate-docs": "rimraf docs",
-        "generate-docs": "typedoc --out docs/ --exclude **/codec/**/* src/ --excludeExternals --ignoreCompilerErrors --excludePrivate",
+        "generate-docs": "typedoc --options typedoc.json",
         "lint": "eslint --ext .ts ."
     },
     "repository": {
@@ -57,6 +60,5 @@
     "bugs": {
         "url": "https://github.com/hazelcast/hazelcast-nodejs-client/issues"
     },
-    "homepage": "https://github.com/hazelcast/hazelcast-nodejs-client#readme",
-    "typings": "./lib/index"
+    "homepage": "https://github.com/hazelcast/hazelcast-nodejs-client#readme"
 }

src/Address.ts

@@ -19,7 +19,30 @@ import {CLUSTER_DATA_FACTORY_ID, CLUSTER_DATA_ADDRESS_CLASS_ID} from './ClusterD
 import {DataInput, DataOutput} from './serialization/Data';
 import {IdentifiedDataSerializable} from './serialization/Serializable';
 
-export class Address implements IdentifiedDataSerializable {
+/**
+ * Represents a network address (e.g. of the client or a cluster member).
+ */
+export interface Address {
+
+    /**
+     * Host name or IP address.
+     */
+    host: string;
+
+    /**
+     * Port number.
+     */
+    port: number;
+
+    /**
+     * Returns string representation of the address.
+     */
+    toString(): string;
+
+}
+
+/** @internal */
+export class AddressImpl implements Address, IdentifiedDataSerializable {
 
     factoryId = CLUSTER_DATA_FACTORY_ID;
     classId = CLUSTER_DATA_ADDRESS_CLASS_ID;
@@ -49,7 +72,7 @@ export class Address implements IdentifiedDataSerializable {
         output.writeUTF(this.host);
     }
 
-    equals(other: Address): boolean {
+    equals(other: AddressImpl): boolean {
         if (other === this) {
             return true;
         }

src/BitsUtil.ts

@@ -13,7 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/** @ignore *//** */
 
+/** @internal */
 export class BitsUtil {
     static BYTE_SIZE_IN_BYTES = 1;
     static BOOLEAN_SIZE_IN_BYTES = 1;

src/BuildInfo.ts

@@ -13,9 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/** @ignore *//** */
 
 const clientVersion = require('../package.json').version;
 
+/** @internal */
 export class BuildInfo {
 
     public static readonly UNKNOWN_VERSION_ID = -1;

src/ClientInfo.ts

@@ -17,6 +17,9 @@
 import {Address} from './Address';
 import {UUID} from './core/UUID';
 
+/**
+ * Local information of the client.
+ */
 export class ClientInfo {
 
     /**
@@ -43,4 +46,5 @@ export class ClientInfo {
      * Set of all labels of this client.
      */
     labels: Set<string>;
+
 }

src/ClientMessage.ts

@@ -13,17 +13,21 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/** @ignore *//** */
 
 import {BitsUtil} from './BitsUtil';
 import {ClientConnection} from './network/ClientConnection';
 import {FixSizedTypesCodec} from './codec/builtin/FixSizedTypesCodec';
 
 const MESSAGE_TYPE_OFFSET = 0;
 const CORRELATION_ID_OFFSET = MESSAGE_TYPE_OFFSET + BitsUtil.INT_SIZE_IN_BYTES;
+/** @internal */
 export const RESPONSE_BACKUP_ACKS_OFFSET = CORRELATION_ID_OFFSET + BitsUtil.LONG_SIZE_IN_BYTES;
+/** @internal */
 export const PARTITION_ID_OFFSET = CORRELATION_ID_OFFSET + BitsUtil.LONG_SIZE_IN_BYTES;
 const FRAGMENTATION_ID_OFFSET = 0;
 
+/** @internal */
 export const DEFAULT_FLAGS = 0;
 const BEGIN_FRAGMENT_FLAG = 1 << 15;
 const END_FRAGMENT_FLAG = 1 << 14;
@@ -34,8 +38,10 @@ const END_DATA_STRUCTURE_FLAG = 1 << 11;
 const IS_NULL_FLAG = 1 << 10;
 const IS_EVENT_FLAG = 1 << 9;
 
+/** @internal */
 export const SIZE_OF_FRAME_LENGTH_AND_FLAGS = BitsUtil.INT_SIZE_IN_BYTES + BitsUtil.SHORT_SIZE_IN_BYTES;
 
+/** @internal */
 export class Frame {
     content: Buffer;
     flags: number;
@@ -105,10 +111,14 @@ export class Frame {
     }
 }
 
+/** @internal */
 export const NULL_FRAME = new Frame(Buffer.allocUnsafe(0), IS_NULL_FLAG);
+/** @internal */
 export const BEGIN_FRAME = new Frame(Buffer.allocUnsafe(0), BEGIN_DATA_STRUCTURE_FLAG);
+/** @internal */
 export const END_FRAME = new Frame(Buffer.allocUnsafe(0), END_DATA_STRUCTURE_FLAG);
 
+/** @internal */
 export class ClientMessage {
     startFrame: Frame;
     endFrame: Frame;

src/ClusterDataFactory.ts

@@ -13,16 +13,20 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/** @ignore *//** */
 
 import {IdentifiedDataSerializable} from './serialization/Serializable';
-import {Address} from './Address';
+import {AddressImpl} from './Address';
 
+/** @internal */
 export const CLUSTER_DATA_FACTORY_ID = 0;
+/** @internal */
 export const CLUSTER_DATA_ADDRESS_CLASS_ID = 1;
 
+/** @internal */
 export function clusterDataFactory(classId: number): IdentifiedDataSerializable {
     if (classId === CLUSTER_DATA_ADDRESS_CLASS_ID) {
-        return new Address();
+        return new AddressImpl();
     }
     return null;
 }

src/DataStoreHashMap.ts

@@ -13,9 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/** @ignore *//** */
 
 import {Data} from './serialization/Data';
 
+/** @internal */
 export class DataKeyedHashMap<T> {
 
     size: number;

src/DistributedObjectInfo.ts

@@ -13,7 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/** @ignore *//** */
 
+/** @internal */
 export class DistributedObjectInfo {
     serviceName: string;
     name: string;