TypeScript AST Query library
npm install cannabis
TypeScript AST Query Selector library
Based on the powerful astq AST Query engine and syntax language.
- Playground
- Usage
* From string
* From ts.Node
* Loading projects
- Custom Attributes
* @text
* @name
* @modifiers
* @type
* @expression
- Custom Functions
* isFunctionLike()
* extendsAnyNamed(name)
* implementsAnyNamed(name)
* sourceFile(node?)
* findReferences(node?)
* debug(...args?)
- Query Syntax
- TODO
Try out this interactive TypeScript AST Query editor with examples to understand what this is all about.
``
npm install cannabis
`ts
import { queryAst } from 'cannabis'
const code =
function f(o: any){
for(let i in o)
console.log(i)
}
class A{
private method1(){
for(var name in this)
this.n.push(name)
}
}
// match Blocks containing ForInStatement direct children
const query = '//Block [ /ForInStatement ]'
const { result, error} = queryAst(query, code1)
if(error){
// there was a query syntax error
}else{
result.map(node=>console.log(node.getStart(), node.getEnd()))
}
cannabis supports AST Nodes of type File and Directory, so it's possible to load a project or folder or sets of files as AST Nodes.
`
TODO example
In general attributes will return a value if there is something to return, empty array, empty string, false or 0 for those types if there is no value to return, and null if thevalue is an object or there was an error.
@text - string
returns current node's text as in ts.Node#getText(). Example:
// VariableDeclaration [ @text!~'2' ]
@name - string
There are node kinds that have name, like InterfaceDeclaration, and others that don't, like IfStatement. Example: // * [ @name=='f' && @modifiers=~'export' ]
@modifiers - string
A comma separated modifier names in "export","default","declare","abstract","public","protected","private","readonly","static","async","const".
Example:
// PropertyDeclaration [ @modifiers=~'private' || @modifiers=~'protected' ]
If the node has no modifiers at all it returns empty string.
@type - string
Returns current node's type string representation.
If type is not declared it will be inferrer form usage.
If type doesn't apply to current node it will return empty string.
Examples:
// VariableDeclaration [ @type=='Date[]'],
// Parameter [ @type=='boolean' || @type=='number']
@expression - Node (ts-morph Node instance)
Returns a AST Node if the node has an expression, or null other wise.
Examples:
TODO
Gets the literal text of a literal-like node , example
// LiteralString [compareText({forbidden}, @literalText, 'verb:equals,caseSensitive:true']
Returns the position of current node in its source file.
Returns the position of current node's end, in its source file.
Returns the amount of characters of current node.
Return current node's body node, or null if it doesn't have a body.
Returns the text of comments before this node.
Returns the text of comments after this node.
Returns a child-index based path for the node, similar to src/services/login/loginService/2/1
Returns a node kind based path for the node, like src/services/login/loginService/InterfaceDeclaration/Identifier. Notice that unlike @indexPath, this doesn't necessarily points to the node.
Returns a node-name based path for current node, like src/services/login/loginService/LoginService/method1/param1. Notice that unlike @indexPath, this doesn't necessarily points to the node. If a node doesn't have a name, its kind name will be printed in the path instead.
* isFunctionLike(arg?) - boolean
Returns true if current node kind is function like, this is a callable node like FunctionDeceleration, MethodDeclaration, ArrowFunction, etc.
Examples:
//* [ isFunctionLike() && type() != ConstructorDeclaration]
Supports two signatures:
extendsAnyNamed(name: string) - boolean - boolean
Returns true if current node (or given node given as parameter) extends any class or interface (directly or indirectly) which name is included in parameter. If names is a string then it will be split using ','. //ClassDeclaration [extendsAnyNamed('Base,ExternalBase')]
Example: : Returns true if current node ClassDeclaration extends (directly or indirectly) a class named 'Base' OR 'ExternalBase'.
Example: Identifier [extendsAnyNamed(parent(), {names}): Returns true if current node's parent extends (directly or indirectly) a type with name included in names parameter.
Take into account that it will search across all extends HeritageClauses, (directly or indirectly) so it's an expensive operation. Also remember that an interface can extend both interfaces and classes. Examples:
extendsAllNamed
implementsAnyNamed(name: string): boolean
Returns true if current node (class declaration) implements recursively an interface with given name.
Take into account that it will search across all implemented HeritageClauses of all interfaces implemented by super classes and also interfaces extended by super interfaces, recursively.
Examples:
## sourceFile
sourceFile(node?: ASTNode): ASTNode | null
Returns current sourceFile Node.
(node?: ASTNode): ASTNode[]
Returns an array of Nodes which are referencing current node. If a project was used as starting node, and current node is exported, then it could return references of nodes in other files.
If an argument is passed it will return the references of that node.
Examples:
Find unused variables:
// VariableDeclaration [@modifiers!~'export' && count(findReferences())==0]
Passing a node argument:
// Identifier [@name=='Foo22' && count(findReferences(parent()))>=0]
Examples:
// Identifier [..//* && debug(count(findReferences()), kindName(), @name) && count(findReferences())==2]
includes(a: string | any[], b: any): boolean
parent(arg?ASTNode): ASTNode|null
children(arg?:ASTNode): ASTNode[]`
* ASTQ Query syntax
* Based on https://github.com/rse/astq
* This is a very WIP project...
* Helper functions to reference high level AST concepts will be added & documented
See TODO.md