You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/blog/typed-napi.md
+10-6Lines changed: 10 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -2,23 +2,25 @@
2
2
sidebar: false
3
3
---
4
4
5
-
# Improve Napi Typing
5
+
# ast-grep's Journey to Type Safety in Node API
6
6
7
-
> _Design, Define, Refine, and Confine: Crafting Balanced TypeScript Types_
7
+
> Recipe to Craft Balanced Types: _Design, Define, Refine, and Confine_
8
8
9
9
We're thrilled to introduce typed AST in [@ast-grep/napi], addressing a [long-requested feature](https://github.com/ast-grep/ast-grep/issues/48) for AST manipulation from the early days of this project.
10
10
11
11
In this blog post, we will delve into the challenges addressed by this feature and explore [the design](https://github.com/ast-grep/ast-grep/issues/1669) that shaped its implementation. _We also believe this post can serve as a general guide to crafting balanced TypeScript types._
12
12
13
-
## Why Type Safety Matters in AST
13
+

14
+
15
+
## Type Safety in AST
14
16
15
17
Working with Abstract Syntax Trees (ASTs) is complex. Even with AST [excellent](https://astexplorer.net/)[AST](https://ast-grep.github.io/playground.html)[tools](https://github.com/sxzz/ast-kit), handling all edge cases remains challenging.
16
18
17
19
Type information serves as a crucial safety net when writing AST manipulation code. It guides developers toward handling all possible cases and enables exhaustive checking to ensure complete coverage.
18
20
19
21
While `ast-grep/napi` has been a handy tool for programmatic AST processing, it previously lacked type information to help users write robust code. Thank to [Mohebifar](https://github.com/mohebifar) from [codemod](https://codemod.com/), we've now bridged this gap. Our solution generates types from parsers' metadata and employs TypeScript tricks to create an idiomatic API.
20
22
21
-
## Qualities of Good TypeScript Types
23
+
## Qualities of Good Types
22
24
23
25
Before diving into our implementation, let's explore what makes TypeScript definitions truly effective. In today's JavaScript ecosystem, creating a great library involves more than just intuitive APIs and thorough documentation – it requires thoughtful type definitions that enhance developer experience.
24
26
@@ -236,7 +238,7 @@ This approach, inspired by [Biome's Rowan API](https://github.com/biomejs/biome/
236
238
237
239
This hybrid approach gives developers the best of both worlds: strict type checking when types are known, with the flexibility to fall back to string-based typing when needed.
238
240
239
-
## Refine Type
241
+
## Refine Types
240
242
241
243
Now let's talk about how to refine the general node to a specific node in ast-grep/napi.
242
244
We've implemented two concise and idiomatic approaches in TypeScript: manual and automatic refinement.
@@ -409,6 +411,8 @@ sgNode.find({
409
411
})
410
412
```
411
413
414
+

415
+
412
416
## Ending
413
417
414
418
I'm incredibly excited about the future of AST manipulation in TypeScript.
@@ -419,4 +423,4 @@ As Theo aptly puts it in [his video](https://www.youtube.com/clip/Ugkxn2oomDuyQj
419
423
420
424
> There are very few devs that understands Rust deeply enough and compiler deeply enough that also care about TypeScript in web dev enough to build something for web devs in Rust
421
425
422
-
ast-grep is determined to bridge that gap between Rust and TypeScript!
426
+
ast-grep is determined to bridge that gap between Rust and TypeScript!
0 commit comments