aleclarson / hegel Goto Github PK

Getting Started | Documentation

Hegel is a type checker for JavaScript with optional type annotations and preventing runtime type errors.

• No Runtime Type Errors. Hegel has a strong type system and soundness checks. This means that he finds any TypeError that may be thrown in runtime.
• Optional Type Annotation. Hegel has a high-level type inference which gives you the ability to drop a type annotation.
• Typed Errors. Hegel has a mechanism to inference and annotates which errors should be thrown by functions.
• Using d.ts as libraries definitions. Hegel has not a custom language for library typings description. We use a lot of existed .d.ts files as the source of typings for any libraries.
• Only JavaScript with types. Hegel has only type syntax, without any additional hard syntax sugar.

To read more about Hegel, check out Docs.

Benefits over TypeScript

1. No unexpected runtime errors

TypeScript never will guarantee that you will not have a Type Error at Runtime. Check TypeScript non-goals point 3. Hegel is on the opposite side. We try to implement a strong and sound type system that will guarantee that your program is valid.

As example (You can try it in our playground):

const numbers: Array<number> = [];

// HegelError: Type "Array<number>" is incompatible with type "Array<number | string>"
const numbersOrStrings: Array<string | number> = numbers;

numbersOrStrings[1] = "Hello, TypeError!";

// HegelError: Property "toFixed" does not exist in "Number | undefined" 
numbers[1].toFixed(1);

The same example with TypeScript (v3.8.3) compiles without any error, but you will have 2 TypeError in runtime.

2. Ability to skip type annotation

Hegel is targeting at really powerful type inference which gives an ability to write fewer type annotations.

As example (You can try it in our playground):

const promisify = fn => arg => Promise.resolve(fn(arg));

const id = promisify(x => x);

// And "upperStr" will be inferred as "Promise<string>"
const upperStr = id("It will be inferred").then(str => str.toUpperCase());

The same example with TypeScript (v3.8.3) will throw 2 errors and inference upperStr as Promise<any>.

3. Typed Errors

Hegel gives you information about errors that may be thrown by functions/methods.

Example of error type inference

// If you hover at function name you will see it type as "(unknown) => undefined throws RangeError | TypeError"
function assertPositiveNumber(value) {
    if (typeof value !== "number") {
        throw new TypeError("Given argument is not a number!");
    }
    if (value < 0) {
        throw new RangeError("Given number is not a positive number!");
    }
}

As you understand, you will have the same error type in try-catch block. Example:

try {
    assertPositiveNumber(4);
} catch(e) {
    // Hegel inference `e` type as "RangeError | TypeError | unknown"
}

The same example with TypeScript (v3.8.3) will throw one error and e type will be any.

Benefits over Flow

1. No custom library definition language

Flow.js has custom library definition languages and doesn't support the most popular TypeScript "d.ts" format. But for Hegel TypeScript "d.ts" it the only way to create type definition for library. So, every library which has TypeScript definitions should work with Hegel.

2. Better type inference

Hegel inferences function type by function declaration when Flow inferences function type by usage. As example (You can try it in our playground):

const id = x => x;
// Hegel inference type of "num" variable is "number"
let num = id(4);
// And type of "str" as "string"
let str = id("4");

The same example with Flow (v0.123.0) will inference both num and str as number | string.

3. Typed Errors

Hegel gives you information about errors that may be thrown by functions/methods.

Example of error type inference

// If you hover at function name you will see it type as "(unknown) => undefined throws RangeError | TypeError"
function assertPositiveNumber(value) {
    if (typeof value !== "number") {
        throw new TypeError("Given argument is not a number!");
    }
    if (value < 0) {
        throw new RangeError("Given number is not a positive number!");
    }
}

As you understand, you will have the same error type in try-catch block. Example:

try {
    assertPositiveNumber(4);
} catch(e) {
    // Hegel inference `e` type as "RangeError | TypeError | unknown"
}

The same example with Flow (v0.123.0) will inference e type as empty.

Installing

Step 1: check your Node.js version:

$ node -v
v12.0.0

Hegel was developed for current LTS version of Node.js (12.16.1). So, you need to have at least 12 version.

If you have less than 12 version of Node.js you may change it to 12 or latest by nvm.

Step 2: install @hegel/cli with npm globally or locally:

# globally
$ npm install -g @hegel/cli

# locally
$ npm install -D @hegel/cli

Finally. You already can use it into your JavaScript project:

# globally
$ hegel
No errors!

# locally
$ npx hegel
No errors!

Hegel has a zero-configuration, but if you want to change settings see Configuration Section.

Project Overview

There are few separated packages in Hegel project:

• @hegel/core: the main logic of analysis.
• @hegel/cli: CLI logic.
• @hegel/typings: typings for browser or node.js environment and for default global environment
• @hegel/language-server: language Server (which currently work with VS Code)
• @hegel/docs: documentation

Building Hegel from source

Hegel is written in JavaScript (Node.js 12 is required). Ensure that you have Git and Node.js 12 installed.

1. Clone the repo:

$ git clone [email protected]:JSMonk/hegel.git

2. Change to the @hegel/cli directory:

$ cd hegel/packages/cli

3. Install dependencies

$ npm i

4. That's all. You can build @hegel/cli:

npm run build

The resulting code will be compiled into the build directory. And you can debug it with default Node.js debugger:

node --inspect-brk ./build/index.js

Tests

Currently, all tests are written for @hegel/core, so, if you will change code inside @hegel/core package, you can run tests by:

npm run test

License

Hegel is MIT-licensed (LICENSE).