Allows stronger types emulation for Typescript in runtime by adding checks for actual type. With it you can rely on your Typescript code more in most cases. Throws error if passed type is different from what you expect (like in C# or similar languages), making your Typescript application behaves similar to application written in strong typed language. Current version supports checking primitive types (String, Number) and Objects for type name equality.
If you tried this, please leave some feedback as issue in repo.
Typescript gives huge benefit of compilation and static code analysis. But in runtime we still have pure Javascript. As Language itself it serves for its purpose, and it's very fast nowadays. But when we design complicated systems, we need to have better sense of code! Like we do in languages like C# (which obviously has a own drawbacks and complexities). The mission and the most important idea of this project is to make Typescript / Javascript programming more predictable and runtime safer, make it closer to strong typed languages, functioning at the junction of flexibility and type strength. This will allow to rely on the code more, even when you write library which will be used by other projects, and you don't know how.
npm install ts-stronger-types --savethis lib will be used in runtime, so add to 'dependencies', NOT 'devDependencies'
you need to have Typescript in your project with enabled decorators
In the current version there is @Typed() decorator, applicable for functions. Just apply it to your function as first decorator in the sequence:
import { Typed } from 'ts-stronger-types';
@Typed()
public multiplyChecked(num: number, num2: number): number {
return num * num2;
}As result, you will keep types checking NOT only during code compilation, but in Runtime as well.
In case of correct runtime values, function is just executed and result is returned.
But when passed arguments have unexpected types, execution will end up with Exception (Error) or log entry if configured.
You can emulate this incorrect behavior through any in test scenario:
const value: any = { v: 3};
const result = service.multiplyChecked(2, value);
// TypeError: Argument: [object Object] has type: object different from expected type: numberIn this case no error will be thrown, but console.log will push message.
As you know, decorators are not supported outside of TS classes.
Starting from version 0.1.4 there is checked function, which helps to check types in runtime of standalone functions:
import { checked } from 'ts-stronger-types';
checked<Number, Number>(doubleNumber, value, Number, Number);There is the configuration which can turn on / off features of the library.
export interface TypedOptions {
enable: boolean;
throwError: boolean;
checkArgumentLength: boolean;
}- enable / disable all checks
- enable / disable throwing errors
- enable / disable checks of argument length
Default - all is true
You can use one of the following options to configure:
import { Typed } from 'ts-stronger-types';
@Typed({throwError: false, checkArgumentLength: false})
public multiplyChecked(num: number, num2: number): number {
return num * num2;
}This setting has the biggest priority.
import { TypedConfig } from 'ts-stronger-types';
TypedConfig.set({
enable: true,
throwError: true,
checkArgumentLength: true,
});This setting has the second priority.
You can turn on / off the whole feature using environment variable TYPED.
Config tries to read and parse value from 'process.env.TYPED', it can have value like 'true', 'yes' or 1 for enabling and 'false', 'no' or 0 for disabling.
For example, your .env file can have: TYPED = false
const customLogger = (message: string) => void {
// do whatever you want with message
};
TypedConfig.set({ customLogger });
The main motivation is to have system which behaves more like strong type language, but can function in Javascript ecosystem. I described it in more details in the article at kononov.space. In russian at the moment, translation will be soon.
- arguments length
- type of each argument (should be equal to type of parameter in reflect-metadata)
- type of return value (should be equal to return type in reflect-metadata)
- number
- string
- date
- boolean
- array
- class
Due to current limitations of Typescript / Javascript we cannot verify in runtime following types:
- interfaces. Each interface doesn't have prototype and it's name is undefined in runtime.
- type of array members. This is due to lack of reflect-metadata for arrays in Typescript. Potentially it can be done in future if TS team bring needed metadata
Performance overhead is very minimal. Measurements where taken with console.time.
First Run
| part | foreach | for |
|---|---|---|
| clean_func | 0.113ms | 0.080ms |
| metadata | 0.208ms | 0.148ms |
| typeof | 0.063ms | 0.045ms |
| foreach | 0.303ms | 0.163ms |
| checked_func | 0.785ms | 0.515ms |
Second Run
| part | foreach | for |
|---|---|---|
| clean_func | 0.113ms | 0.080ms |
| metadata | 0.012ms | 0.031ms |
| typeof | 0.002ms | 0.001ms |
| foreach | 0.066ms | 0.040ms |
| checked_func | 0.140ms | 0.221ms |
- 0.0.4 - initial code, documentation, tests and
@Typed()decorator itself. - 0.1.0 - verification of classes, arrays, return types, code refactoring, 64 tests added, settings
- 0.1.5 - updates and new experimental standalone function check
- migrated
ts-lint=>eslint - updated all dependent libs to the latest version, including
"typescript": "^4.0.5", - merged suggested PR with better error messages
- merged suggested PR with custom logger
- use setting
no-implicit-any - use setting
no-explicit-any, except tests - change
Error=>TypeError - add ability to check types of a standalone function (not in class) -
checkedfunction
- migrated
- Add ability to use this decorator for class itself, not just for particular function
- Maybe some global checks, but not sure would it be possible
- Please add more suggestions by finding me in twitter @ValentinKononov
Post issues in github/ts-runtime-checker/issues
- Author - @ValentinKononov
Thanks!