rwalle / acorn-types Goto Github PK

@marijnh

I have been creating these functions in my own project:

function isLiteral (node: acorn.Node): node is Literal {
    return node.type === 'Literal';
}

function isCallExpression (node: acorn.Node): node is CallExpression {
    return node.type === 'CallExpression';
}

I assume that after the proper typing is available, downstream users will start to adopt them and creating type guards themselves, and likely many of these. It would be nice if acorn provides these as built-in JavaScript functions, and then these type declaration files also provide the matching functions with the type guard signature.

A small pain point related to this is that when I was using acorn I found it a bit surprising that the "type" values are not recorded in some sort of enum, and as a result I need to do node.type === 'TaggedTemplateExpression' and make sure I don't have a typo. Having these functions should help.

This GitHub issue probably belongs to acorn. I can bring this up later once the current work is done. For now I want to know your opinion on this.

Since our API is very stable, and I don't expect these to have to change very often, I was thinking to just copy the d.ts files into the Acorn repository, without any of the supporting machinery, and maintain them there, going forward. Does that sound reasonable to you?

Are you aware of anything we should address before publishing the new types?

If we were to have a type that is a union of all possible type-tagged node types (the @types/estree types use Node for this, but we'd need another type, say AnyNode),

type AnyNode = Statement | Expression | SwitchCase | CatchClaush | ...

Then we can use Extract<AnyNode, {type: someNodeName}> to get the node type(s)* with a given name, and use that in a mapped type to magically get the right function type for every walk function.

export type AncestorVisitors<TState> = {
  [type in AnyNode["type"]]?: (node: Extract<AnyNode, {type: type}>, state: TState, ancestors: Node[]) => void
}

(* note that the current walkers are too narrow—FunctionDeclaration walkers must also accept AnonymousDefaultExportedFunctionDeclaration nodes)

I'm not quite sure what the difference between the various TypeScript-specific namespace/module features is, but in all my other projects, I just use .d.ts files structured like ES modules (export interface ... etc), and it works great.

It seems messy (removing a property to add it back with a different type) compared to, in some cases (FunctionBody, ModuleSpecifier, StaticBlock) just duplicating a few field or in others (ForOfStatement, ArrowFunctionExpression, AssignmentProperty) introducing base interfaces with the shared properties.

Same for the other similar types. My first impulse was that we could do away with these by giving ClassDeclaration an optional id property and just putting a ClassDeclaration in there, but I guess that loses valuable information (the non-nullability of id in a real class declaration).

So given that I'd suggest renaming these AnonymousClassDeclaration/AnonymousFunctionDeclaration.

Would putting optional properties for this on Literal instead cause any real trouble? I guess you can no longer define a function that takes, precisely, a RegExpLiteral, but I'm not sure that's important enough to warrant the extra exported types.

That loses the information that this is going to hold either a MemberExpression or a CallExpression, and tells TS only that it's going to hold some Node object with an optional property.

I'd suggest inlining optional into MemberExpression and CallExpression, and making the type of ChainExpression.expression just MemberExpression | CallExpression.

Since using types when writing plugins is not going to be a reality anyway (you'd need the entire internal Parser API for that, and that would be way too much to put into the types that normal users are going to use), I think it would make sense to omit anything not mentioned in the readme from the types. So that means most of the properties on Parser, stuff like token contexts, identifier character test functions, whitespace regexps, and most of the properties that TokenType has.