https://github.com/jakesidsmith/tsassert
Check TypeScript types against assertion comments
https://github.com/jakesidsmith/tsassert
Last synced: 3 months ago
JSON representation
Check TypeScript types against assertion comments
- Host: GitHub
- URL: https://github.com/jakesidsmith/tsassert
- Owner: JakeSidSmith
- License: mit
- Created: 2020-01-05T17:07:26.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-20T07:56:12.000Z (11 months ago)
- Last Synced: 2024-12-30T14:14:16.917Z (5 months ago)
- Language: TypeScript
- Homepage: https://npmjs.org/package/@jakesidsmith/tsassert
- Size: 205 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# tsassert
**Check TypeScript types against assertion comments**
[](https://circleci.com/gh/JakeSidSmith/tsassert)
## About
This library provides an easy way for library publishers (and anyone else that wants) to assert the output types of their APIs, and ensure that these do not regress over time.
I would recommend adding a tsassert command to your tests and or continuous integration pipeline.
## Requirements
You must be using a reasonably recent version of node. Guaranteed to work with node 12. May work with older versions.
You must be using TypeScript 3 (this is a peer dependency).
## The syntax
Simply add a comment with the following structure to the end of the line, or on the line above:
```ts
// @tsassert: ExpectedTypeHere
```
Basic examples:
```ts
// Assert variable types
const myNumber = 1; // @tsassert: number
// @tsassert: number
const myOtherNumber = 2;
// Assert return type of function
sendMessage('Hello'); // @tsassert: Promise
// @tsassert: Promise
sendMessage('Hello again');
// Assert type of class instance
new MyClass(abc); // @tsassert: MyClass
// @tsassert: MyClass
new MyClass(abc);
```
Example in tests:
```ts
describe('my getter', () => {
it('should return undefined if any values in the path are nullable', () => {
// @tsassert: string | undefined
const result = get(obj, ['a', 'b', 'c']);
expect(result).toBe(undefined);
});
});
```
## Install
```shell
npm i @jakesidsmith/tsassert -D
```
`-D` (`--save-dev`) will automatically add this to your `package.json` and `package-lock.json`.
## Run the checks
```shell
tsassert [options]
```
Examples:
```shell
# Use root tsconfig and check all files
tsassert
# Specify a tsconfig manually
tsassert --project tsconfig.json
# Specify a pattern to match files against
tsassert --project tsconfig.json 'src/**/*.ts'
# Specify multiple files or patterns
tsassert file-1.ts file-2.ts
# Verbose output (output globs and matched file paths)
tsassert --verbose
```
The `project` option defaults to `./tsconfig.json`.
If you don't specify a file or pattern tsassert will use the `include` and `exclude` from your `tsconfig.json`.
If your `tsconfig.json` has an `exclude` option, these files will not be checked even if your manually provided glob matches them.
If you want to include a file that is excluded by your `tsconfig.json` you should extend the config, override the `exclude` property and provide this `tsconfig.json` as the `--project` argument e.g. `tsassert --project tsconfig.tsassert.json`.
Regardless of your includes or excludes `node_modules` will always be excluded.
Run `tsassert --help` for a full list of options.
## Contributing
### Setup
Ensure you are using a compatible version of NodeJS (16) and NPM (8).
If you're using NVM you can simply:
```shell
nvm use
```
And ensure you have NPM 8 installed globally:
```shell
npm i npm@8 -g
```
Then run a clean install to get fresh dependencies:
```shell
npm ci
```
### Scripts
Run type-checking, linting and tests with:
```shell
npm test
```
You can fix formatting issues by running:
```shell
npm run prettier
```