InferJS-Library: Overview

InferJS-Library allows you to easily add runtime type checking by utilizing JSDoc multi-line comments in both client and server side JavaScript. The library is part of a bigger project named InferJS.

InferJS is provided with an InferJS-Compiler. The compiler interprets your JSDoc comments from your source code and compiles them into an InferObject file, that you can import into any JavaScript file.

With this library, you can also enable extended type checking and narrow down your data types with @infer expectation rules. Check out the examples below, to see how InferJS can save you time and money from costly bugs through development and release.

• Live Example

Built With

• JSDoc Version 3+
• Node.js Version 12+
• NPM Version 5+
• Webpack Version 5+
• Visual Studio Code

  InferJS-Library: Installation

To install the latest version of InferJS-Library locally with npm:

Install: [Locally]()

npm install inferjs-library --save

Install: [Globally]()

npm install -g inferjs-library

Optional: If you would like to download the repo source code with git:

git clone https://github.com/Codevendor/inferjs-library.git

  InferJS-Library: Browser Version Instructions

If you would like to use the InferJS-Library from the browser, please select a precompiled/minified version and module type from the dist folder. There are 3 types of modules supported (esmodule,commonjs,script). The latest folder contains the latest version of the library.

Optional: Compiling the Latest Version of InferJS-Library

If you are missing the dist folder or would like to compile the latest version, follow the steps below.

Install Webpack

To build yourself, you will need to install Webpack version 5+ with the following commands. The commands need to be run from where the package.json is located. Or you can install them globally with the -g identifier.

Webpack Latest Install

// Local Install
npm install --save-dev webpack
npm install --save-dev webpack-cli

or

// Global Install
npm install -g --save-dev webpack
npm install -g --save-dev webpack-cli

The latest version of webpack 5+ automatically installs the terser-webpack-plugin with it. If it doesn't, you will need to install it as well, from where the package.json is located. The Terser plugin is used for minimizing/compressing the library code for use in the browser.

Optional - Terser Webpack Plugin

• Required if webpack 4-

  npm install terser-webpack-plugin --save-dev

After the node modules under devDependencies are installed, you can run the build process from where the package.json is located.

npm run build

  InferJS-Library: Compiling InferObject Files

In order to use the InferJS-Library, you will need to compile an InferObject with the InferJS-Compiler.

For more information on installing the InferJS-Compiler and its usage click here.

  InferJS-Library: Usage

Browser - Usage Instructions

Copy one of the minimized inferjs-{version}.min.js from the dist folder to your website. Copy the pre-compiled [InferObject]() file to your website, that was created with the InferJS-Compiler.

Add both to your webpage for type checking. You only need to recompile with the InferJS-Compiler, if you change your JSDoc multi-line comments, @param, @type, @inferid or @infer tags.

Below are examples for using InferJS-Library in your code.

Browser ESModule Import Example - Client side

<script type="module">
  import { InferObject } from "./inferobject.js";
  import { InferJS } from "./esmodule/inferjs-{version}.min.js";
  const inferjs = new InferJS(InferObject);
</script>

Browser JavaScript Script Tag Sync Example - Client Side

<script src="https://github.com/Codevendor/inferjs-library/raw/main/inferobject.js"></script>
<script src="https://github.com/Codevendor/inferjs-library/raw/main/script/inferjs-{version}.min.js"></script>
<script>
const inferjs = new InferJS(InferObject);
</script>

Node.js ESModule Import - Server Side

import { InferObject } from "./inferobject.js";
import { InferJS } from "./esmodule/inferjs-{version}.min.js";
const inferjs = new InferJS(InferObject);

Node.js CommonJS Require - Server Side

const InferObject = require("./inferobject.js");
const InferJS = require("./commonjs/inferjs-{version}.min.js");
const inferjs = new InferJS(InferObject);

There are many ways to utilize the InferJS-Library. The example above, imports in the pre-compiled [InferObject]() file that was created with the InferJS-Compiler. Intialize the InferJS-Library class with the [InferObject]() file you want to use.

// Intialize through constructor
const inferjs = new InferJS(InferObject);

// or intialize through property
const inferjs = new InferJS();
inferjs.inferObject = InferObject;

Once the InferJS-Library and [InferObject]() file are included at the top of your file you can then utilize the type checking features. Below is an example of how to create a JSDoc multi-line comment for type checking.

Custom JSDoc Multiline Comment with Custom Infer Expectations

/**
 * Test case scenario for JavaScript inferjs function.
 * @category tests
 * @function foo
 * @param {string} msg - The message to send through console.log().
 * @param {(number|string)} id - The id of the message.
 * @param {boolean} [send=true] - Whether to send your message.
 * @infer {string} msg {STRING-NOT-EMPTY} - Checks if string is not empty.
 * @inferid foo
 */
function foo(msg, id, send) {

    inferjs.check('foo', arguments);
}

// Example Normal Call
foo('test', 1234, true);

  InferJS-Library: Type Checking with JSDoc [@param]()

The JSDoc tag @param below specifies a method's parameter type(s), name and description.

Fomart for [@param]():

• @param {[type]()} paramName - description
• @param {([type]()|[type]())} paramName - description

Single type check example:

/**
 * @param {string} msg - The message to send through console.log().
 */

Multi type check example:

/**
 * @param {(null|string)} msg - The message to send through console.log().
 */

InferJS-Library reads the precompiled [InferObject]() file and uses it to process all type checking and inferred expectations.

Below is a list of standard and extended types that can be checked:

  InferJS-Library: Expectation Checking with Tag [@infer]()

InferJS-Library also allows for extended type checking with the custom @infer tag. Add one or multiple @infer tags to any parameter type. This will allow for narrowing your types down through expectations.

Below is an simple example of @infer:

Fomart for [@infer]():

• @infer {[type]()} paramName {[expectation]()} - description
• @infer {([type]()|[type]())} paramName {([expectation]()|[expectation]())} - description

/**
 * @infer {string} msg {STRING-NOT-EMPTY} - Checks if string is not empty.
 */

The @infer tag is so versatile you can attach it to multiple types in a group and specify multiple narrowing and values to check against, like so:

/**
 * @infer {(number|string)} msg {INT32|STRING-NOT-EMPTY} - Checks if string is not empty and is an integer32.
 * @infer {array} arrname {IN-ARRAY=a,b,c,d,e} - Checks if a,b,c,d is in array.
 * @infer {object} objname {PROPS=id,name} - Checks if objname has properties id and name.
 */

  InferJS-Library: Tag [@infer]() Expectation Types

There are many extended expectation types for narrowing your types down with your @infer tags.

Below is a list of common rule expectation types:

  InferJS-Library: Linking with Tag [@inferid]()

The tag @inferid is a unique identifier for linking InferJS-Library behind the scenes. It is required for each method, property or field, you would like to check.

This special tag, allows code to still work, while JavaScript is compressed/minified or obfuscated. All Infers are stored in a precompiled InferObject file. This makes it easy to write in your static data types and not have to worry about type checking them during JavaScript Runtime execution.

@inferid can be anything you want as a name, but must be unique per item you want to check.

Below is an example of @inferid:

Fomart for [@inferid]():

• [@inferid]() uniqueId

/**
 * @inferid foo
 */

  InferJS-Library: Running InferJS Checks with Method [check()]()

To check all your types and expectations, you need to call the InferJS-Library method check(). It needs to be added at the beginning of each method(s) starting closure or below each variable you would like to check.

Example Check All Method Params:

function foo(){
  inferjs.check('Your - @inferid', arguments);
}

Example Check Field or Variable:

var a = 'foo';
inferjs.check('Your - @inferid', a);  

  InferJS Library: Type Checking Errors

In InferJS-Library you have the option to throw or return exception from the check() method. Thrown errors come with tons of information for debugging your types and expectations.

Below are examples of exception type responses from InferJS-Library.

> InferTypeError Example:

InferTypeError: Incorrect third parameter type in:
File: /path/to/test1.js
Line: 14
@inferid: foo
@function: ( msg: <string>, id: <number>, objectTester: <object> )
@param: objectTester
Expected Type: object
Actual Type: null

> InferExpectError Example:

InferExpectError: Incorrect first parameter, failed infer expectation type check in:
File: /path/to/test1.js
Line: 14
@inferid: foo
@function: foo( msg: <string|number|null>, id: <number|string>, send: <boolean> )
@param: msg
Expectation Type: STRING-NOT-EMPTY
Expectation Value: "1234"
Argument Value: ""

For more examples, please refer to the Documentation

  InferJS-Library: Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag enhancement. Don't forget to give the project a [⭐ star](), Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

  InferJS-Library: License

Distributed under the MIT License. See LICENSE.txt for more information.

  InferJS-Library: Support Related

• InferJS-Library Documentation - Information documentation for the InferJS-Library.
• InferJS-Library Issues - Direct all questions about the InferJS-Library