Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ts-arch/ts-arch
An architecture unit test framework for Typescript
https://github.com/ts-arch/ts-arch
Last synced: 8 days ago
JSON representation
An architecture unit test framework for Typescript
- Host: GitHub
- URL: https://github.com/ts-arch/ts-arch
- Owner: ts-arch
- License: mit
- Created: 2018-07-19T20:53:19.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-02-27T13:49:57.000Z (9 months ago)
- Last Synced: 2024-11-05T21:46:18.811Z (11 days ago)
- Language: TypeScript
- Homepage: https://ts-arch.github.io/ts-arch/
- Size: 1.92 MB
- Stars: 416
- Watchers: 8
- Forks: 23
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: code-of-conduct.md
Awesome Lists containing this project
README
# TSArch
It's a library for checking architecture conventions in TypeScript&JavaScript projects using any test framework. You check dependencies between files, folders and slices, check for cyclic dependencies and more. It's similar to ArchUnit but for TS/JS projects.
## Build status
[](https://github.com/ts-arch/ts-arch/actions/workflows/build.yaml)
## Installation
```bash
npm install --save-dev tsarch
```
## Usage
The project has currently two perspectives on architecture: file based architecture tests and slice based architecture tests.
### File API
```typescript
// imports and applies the jest extensions
import "tsarch/dist/jest"
// imports the files entrypoint
import {filesOfProject} from "tsarch"
describe("architecture", ()=> {
// architecture tests can take a while to finish
jest.setTimeout(60000);
// we use async await in combination with jest since this project uses asynchronous calls
it("business logic should not depend on the ui", async ()=> {
const rule = filesOfProject()
.inFolder("business")
.shouldNot()
.dependOnFiles()
.inFolder("ui")
await expect(rule).toPassAsync()
})
it("business logic should be cycle free", async ()=> {
const rule = filesOfProject()
.inFolder("business")
.should()
.beFreeOfCycles()
await expect(rule).toPassAsync()
})
})
```
An example without jest and further examples of the usage can be found in the integration tests
in `test/files/integration`.
### Slices API
Assume that you have an architecture diagram (Plant Uml) as part of your documentation
in the `docs` folder of your project.
```typescript
import "tsarch/dist/jest"
import {slicesOfProject} from "tsarch"
import * as path from "path"
describe("architecture", ()=> {
jest.setTimeout(60000);
it('the architecture adheres to the config', async () => {
const diagramLocation = path.resolve('docs', 'components.puml');
const rule = await slicesOfProject()
.definedBy('src/(**)/')
.should()
.adhereToDiagramInFile(diagramLocation)
await expect(rule).toPassAsync()
});
})
```
An example without jest and further examples of the usage can be found in the integration tests
in `test/slices/integration`.
### Path handling
The path of the project is always relative to a given `tsconfig.json`.
If no `tsconfig.json` is given `ts-arch` tries to find one in a parent
folder, e.g. if your `tsconfig.json` is in the same folder as your `src` folder, then all the paths
begin with `src/...`
## Dependency checks on nx monorepositories
`ts-arch` supports dependency checks on nx monorepositories. It reads the project graph
and makes it accessible for the slices api.
The following example illustrates this:
```typescript
import "tsarch/dist/jest"
import {slicesOfProject} from "tsarch"
import * as path from "path"
describe("architecture", ()=> {
jest.setTimeout(60000);
it('the architecture adheres to the diagram', async () => {
const diagramLocation = path.resolve('docs', 'components.puml');
const rule = await slicesOfNxProject()
.ignoringExternalDependencies()
.should()
.adhereToDiagramInFile(diagramLocation)
.check()
await expect(rule).toPassAsync()
});
})
```