Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dtgorski/typex
[TOOL/CLI] - Filter and examine Go type structures, interfaces and their transitive dependencies and relationships. Export structural types as TypeScript value object or bare type representations.
https://github.com/dtgorski/typex
cli export go golang struct tree type typescript
Last synced: 1 day ago
JSON representation
[TOOL/CLI] - Filter and examine Go type structures, interfaces and their transitive dependencies and relationships. Export structural types as TypeScript value object or bare type representations.
- Host: GitHub
- URL: https://github.com/dtgorski/typex
- Owner: dtgorski
- License: mit
- Created: 2020-03-24T21:02:44.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-09-15T22:02:29.000Z (about 1 year ago)
- Last Synced: 2024-08-01T19:41:38.233Z (3 months ago)
- Topics: cli, export, go, golang, struct, tree, type, typescript
- Language: Go
- Homepage:
- Size: 66.4 KB
- Stars: 197
- Watchers: 3
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go-extra - typex - Filter and examine Go type structures, interfaces and their transitive dependencies and relationships. Export structural types as TypeScript value object or bare type representations.|151|10|0|2020-03-24T21:02:44Z|2022-04-02T13:53:41Z| (Go Tools / Routers)
README
[](https://github.com/dtgorski/typex/issues)
[](https://goreportcard.com/report/github.com/dtgorski/typex)
[](https://github.com/avelino/awesome-go#user-content-go-tools)
## typex
Examine [Go](https://golang.org/) types and their transitive dependencies. Export results as TypeScript value objects (or types) declaration.
### Installation
```
go install github.com/dtgorski/typex@latest
```
### Synopsis
The CLI command ```typex``` filters and displays [Go](https://golang.org/) type structures, interfaces and their relationships across package boundaries.
It generates a type hierarchy tree with additional references to transitive dependencies vital for the filtered types.
As an additional feature, ```typex``` exports the result tree as a [TypeScript](https://www.typescriptlang.org/) projection representing value objects or bare types.
### Examples
**Go type hierarchy layout**
```
$ typex -f=Rune io/...
├── error interface {
│ Error() string
│ }
└── io
├── RuneReader interface {
│ ReadRune() (r rune, size int, err error)
│ }
└── RuneScanner interface {
io.RuneReader
ReadRune() (r rune, size int, err error)
UnreadRune() error
}
```
```
$ typex -f=Render github.com/dtgorski/typex/...
└── github.com
└── dtgorski
└── typex
└── internal
├── PathReplaceFunc func(string) string
├── go
│ └── TypeRender struct {
│ PathReplaceFunc internal.PathReplaceFunc
│ IncludeUnexported bool
│ }
└── ts
└── TypeRender struct {
PathReplaceFunc internal.PathReplaceFunc
IncludeUnexported bool
}
```
**TypeScript value object layout**
```
$ typex -f=File -l=ts-class mime/multipart
export module mime {
export module multipart {
export class FileHeader {
constructor(
readonly Filename: string,
readonly Header: net.textproto.MIMEHeader,
readonly Size: number,
) {}
}
}
}
export module net {
export module textproto {
export type MIMEHeader = Record
}
}
```
**TypeScript bare type layout**
```
$ typex -f=File -l=ts-type mime/multipart
export module mime {
export module multipart {
export type FileHeader = {
Filename: string,
Header: net.textproto.MIMEHeader,
Size: number,
}
}
}
export module net {
export module textproto {
export type MIMEHeader = Record
}
}
```
### TypeScript and reserved keywords
Basically, the names of types and fields will be exported from Go without modification.
Collisions with reserved keywords or standard type names in the target language may occur.
To avoid conflicts, you may use the JSON tag annotation for the exported fields of a struct as described in the [json.Marshal(...)](https://golang.org/pkg/encoding/json/#Marshal) documentation.
### TypeScript and exportable types
Due to fundamental language differences, ```typex``` is not capable of exporting all type declarations one-to-one. Refer to the type mapping table below.
Go channel, interface and function declarations will be omitted, references to these declarations will be typed with ```any```.
### TypeScript type mapping
TypeScript (resp. JavaScript aka ECMAScript) lacks a native integer number type.
The numeric type provided there is inherently a 64 bit float.
You should keep this in mind when working with exported numeric types - this includes `byte` and `rune` type aliases as well.
|Go native type|TypeScript type
| --- | ---
|```bool```|```boolean```
|```string```|```string```
|```map```|```Record```
|```struct``` ```(named)```|```T```
|```struct``` ```(anonymous)```|```{}```
|```array``` ```(slice)```|```T[]```
|```complex```[```64```|```128```]|```any```
|```chan```, ```func```, ```interface```|```any```
|```int```[```8```|```16```|```32```|```64```]|```number```
|```uint```[```8```|```16```|```32```|```64```]|```number```
|```byte```(=```uint8```)|```number```
|```rune```(=```int32```)|```number```
|```float```[```32```|```64```]|```number```
|```uintptr```|```number```
### Usage
```
$ typex -h
```
```
Usage: typex [options] package...
Examine Go types and their transitive dependencies. Export
results as TypeScript value objects (or types) declaration.
Options:
-f
Type name filter expression. Repeating the -f option
is allowed, all expressions aggregate to an OR query.
The filter can be a type name, a path part or
a regular expression. Especially in the latter case,
should be quoted or escaped correctly to avoid
errors during shell interpolation. Filters are case
sensitive, see examples below.
The result tree will contain additional references to
transitive dependencies vital for the filtered types.
-l
Modify the export layout. Available layouts are:
* "go": the default Go type dependency tree
* "ts-type": TypeScript type declaration projection
* "ts-class": TypeScript value object projection
-r :
Replace matching portions of in a fully
qualified type name with string. Repeating
the -r option is allowed, substitutions will perform
successively. can be a regular expression.
The path replacement/relocation can be used to modify
locations of type hierarchies, e.g. prune off the
"github.com" reference from qualified type name path
by omitting the part after the colon.
-t Go tests (files suffixed _test.go) will be included
in the result tree available for a filter expression
-u Unexported types (lowercase names) will be included
in the result tree available for a filter expression.
-x
Exclude type names from export. Repeating this option
is allowed, all expressions aggregate to an OR query.
The exclusion filter can be a type name, a path part
or a regular expression.
More options:
-h Display this usage help and exit.
-v Print program version and exit.
The 'package' argument denotes one or more package import path
patterns to be inspected. Patterns must be separated by space.
A pattern containing '...' specifies the active modules whose
modules paths match the pattern.
Examples:
$ typex -u go/...
$ typex -u -f=URL net/url
$ typex github.com/your/repository/...
$ typex -l=ts-type github.com/your/repository/...
$ typex -r=github.com:a/b/c github.com/your/repository/...
This tool relies heavily on Go's package managing subsystem and
is bound to its features and environmental execution context.
```
### Known issues
* Occasional(?) ```internal error``` from Go's package managing subsystem [has been reported](https://github.com/dtgorski/typex/issues/4) on Go 1.14.6 darwin/amd64. Newer Go versions >= 1.15 seem to be not affected.
### Disclaimer
The implementation and features of ```typex``` follow the [YAGNI](https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it) principle.
There is no claim for completeness or reliability.
### @dev
Try ```make```:
```
$ make
make help Displays this list
make clean Removes build/test artifacts
make build Builds a static binary to ./bin/typex
make debug Starts debugger [:2345] with ./bin/typex
make install Compiles and installs typex in Go environment
make test Runs tests, reports coverage
make tidy Formats source files, cleans go.mod
make sniff Checks format and runs linter (void on success)
```
### License
[MIT](https://opensource.org/licenses/MIT) - © dtg [at] lengo [dot] org