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.
- 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.
- 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>
.
- 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
.
- 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.
- 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
.
- 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
.
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.
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
Hegel is written in JavaScript (Node.js 12 is required). Ensure that you have Git and Node.js 12 installed.
- Clone the repo:
$ git clone [email protected]:JSMonk/hegel.git
- Change to the @hegel/cli directory:
$ cd hegel/packages/cli
- Install dependencies
$ npm i
- 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
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
Hegel is MIT-licensed (LICENSE).