@creditkarma/thrift-parser

TypeScript Thrift Parser

A parser for Thrift written in TypeScript. The resulting AST can be used to codegen JavaScript from a Thrift file, or just to inspect the Thrift structure.

Usage

A successful parse returns a ThriftDocument object. An unsuccessful parse returns a ThriftErrors object.

import { parse, ThriftDocument } from '@creditkarma/thrift-parser'


const rawThrift: string =`
  struct MyStruct {
    1: required i32 id
  }
`;

const thriftAST: ThriftDocument | ThriftErrors = parse(rawThrift);

switch(thriftAST.type) {
  case 'ThriftDocument':
    // Do something with valid AST
  case 'ThriftErrors':
    // Report or recover from errors
}

You can also use Thrift Parser from the command line or npm scripts. When using from the command line the generated AST is saved to file as JSON.

$ thrift-parser --rootDir thrift --outDir thrift-json --fastFail false some_file.thrift

In this usage there are three options:

• --rootDir: where to initiate file search and save
• --outDir: relative to rootDir where to save output files
• --fastFail: If true fail on first error encountered

Build

$ npm install
$ npm run build

Test

$ npm test

AST Structure

The root of the returned AST is either a ThriftDocument (successful parse) or a ThriftErrors (unsuccessful parse).

ThriftDocument

{
  type: "ThriftDocument",
  body: Array<ThriftStatement>
}

ThriftErrors

{
  type: "ThriftErrors",
  errors: Array<ThriftError>
}

ThriftError

A descriptor of what went wrong while parsing the specified Thrift source.

{
  type: "ParseError" | "ScanError",
  message: string,
  loc: TextLocation
}

Thrift Statements

Thrift Statements represent each of the main constructs that can be defined in Thrift source.

NamespaceDefinition

namespace <identifier> <identifier>

{
  type: "NamespaceDefinition",
  scope: Identifier,
  name: Identifier
}

IncludeDefinition

include '<path>'"

{
  type: "IncludeDefinition",
  path: StringLiteral
}

TypedefDefinition

typedef <field-type> <identifier>

{
  type: "TypedefDefinition",
  name: Identifier,
  definitionType: FieldType
}

ConstDefinition

const <field-type> <identifier> = <initializer>

{
  type: "ConstDefinition",
  name: Identifier,
  fieldType: FieldType,
  initializer: ConstValue,
}

EnumDefinition

enum <identifier> { <members> }

{
  type: "EnumDefinition",
  name: Identifier,
  members: Array<EnumMember>
}

StructDefinition

struct <identifier> { <fields> }

{
  type: "StructDefinition",
  name: Identifier,
  fields: Array<FieldDefinition>
}

UnionDefinition

union <identifier> { <fields> }

{
  type: "UnionDefinition",
  name: Identifier,
  fields: Array<FieldDefinition>
}

ExceptionDefinition

exception <identifier> { <fields> }

{
  type: "ExceptionDefinition",
  name: Identifier,
  fields: Array<FieldDefinition>
}

ServiceDefinition

service <identifier> (extends <identifier>)? { <functions> }

{
  type: "ServiceDefinition",
  name: Identifier,
  extends: Identifier | null,
  functions: Array<FunctionDefinition>
}

Viewing with ASTExplorer

ASTExplorer is a web app for visualizing ASTs. You type source. It shows you the resulting syntax tree based on the parser you've selected. I've included the integrations for this parser. To get that up and running you'll need to clone ASTExplorer.

$ git clone https://github.com/fkling/astexplorer.git
$ cd astexplorer/website
$ npm install

You will now need to install thrift-parser for ASTExplorer

$ npm install @creditkarma/thrift-parser

Cool, now we need to copy some stuff into the ASTExplorer project.

If the ASTExplorer project and the @creditkarma/thrift-parser project are siblings you can type this into the temrinal (from astexplorer/website)...

$ cp -r ../../thrift-parser/astexplorer/thrift ./src/parsers/thrift

You'll now need to build ASTExplorer and start the server

$ npm run build
$ npm start

By default this will start ASTExplorer on localhost:8080

There is a dropdown to select the language you want to use, choose 'Thrift IDL'

Note: I have had some trouble getting npm run build to work. However, the watch build is much more reliable.

$ npm run watch

Then in another terminal window run start.

$ npm start

Contributing

For more information about contributing new features and bug fixes, see our Contribution Guidelines. External contributors must sign Contributor License Agreement (CLA)

License

This project is licensed under Apache License Version 2.0