Tparserr NPM | npm.io

tparserr

Typescript Type Parser

Motivation

Ability to extract basic dumbed down type descriptions for a target file(s)/dir in order for said type descriptions to be potentially used by later libraries for automating/generating various dev QoL utilities.
Very opinionated in its intent, this library does not aspire to become a be-all and end-all parser and will only include more complex types as and when needed - due to the fact that the majority of real-life type entities are fairly basic.

Installing

npm install --save tparserr

Usage

cli

within a project

npx tparserr generate -f=./src/lib/models/User.ts -o=./User.json

installed as global npm package

tparserr generate -d=./using-tparserr/src/lib/models -o=./types.json

options

Usage: tparserr generate [options]

Options:
      --version                        Show version number             [boolean]
  -f, --file                           File path to load and generate   [string]
  -d, --dir                            Dir path to load and generate    [string]
  -o, --output                         Output file path      [string] [required]
      --includeOnlyExports             If to include only exported types
                                                      [boolean] [default: false]
      --includeOnlyRequiredProperties  If to include only required properties
                                                      [boolean] [default: false]
      --includeNestedClassNames        If to include nested class names
                                                      [boolean] [default: false]
      --enableDecorators               If to enable decorators
                                                      [boolean] [default: false]
  -h, --help                           Show help                       [boolean]

Programatic

Given a target file

// __dirname + ../targetFiles/Entity.ts
export class Entiy {
    id: number;

    names?: Array<string>;

    createdAt: CaptureTimestamp;

    enabled: boolean;
}

class CaptureTimestamp {
    value: Date;

    createdBy?: string;
}

Attempting to parse said file e.g.

// index.ts
import { Parserr } from 'tparserr';

async function main() {
    const output = await Parserr.parse({
        files: ['../targetFiles/Entity.ts'],
        callerBaseDir: __dirname
    });

    console.log(JSON.stringify(output));
}

main().catch(console.error);

Would yield a result of

[
    {
        "name": "Entiy",
        "type": "object",
        "properties": {
            "id": {
                "type": "number",
                "required": true
            },
            "names": {
                "type": "array",
                "items": {
                    "type": "string"
                },
                "required": false
            },
            "createdAt": {
                "type": "object",
                "properties": {
                    "value": {
                        "type": "Date",
                        "required": true
                    },
                    "createdBy": {
                        "type": "string",
                        "required": false
                    }
                },
                "required": true
            },
            "enabled": {
                "type": "boolean",
                "required": true
            }
        }
    },
    {
        "name": "CaptureTimestamp",
        "type": "object",
        "properties": {
            "value": {
                "type": "Date",
                "required": true
            },
            "createdBy": {
                "type": "string",
                "required": false
            }
        }
    }
]

Alternative pathing options

If the typescript files you are attempting to parse are within the current source-code, it might be handy to:

Resolve the relative paths against the current `cwd`

// e.g. given a file of ./models/User.ts
const output = await Parserr.parse({
    files: [path.resolve('./src/lib/models/User.ts')]
});

Enable `enableSourceFilePathing` config to make use of https://github.com/razmat145/tspathrr in order to resolve the relative paths against the `tsconfig` opts

This uses rootDir and outDir typescript compiler opts in order to properly resolve the file absolute path against the __dirname and process.cwd()

// e.g. given a file of ./models/User.ts
const output = await Parserr.parse({
    files: ['./models/User.ts'],
    callerBaseDir: __dirname,
    enableSourceFilePathing: true
});

Decorators

The actual decorator implementations is not important, from tparserr's POV decorators are extracted as annotations in { name, args } pairs.

Note: when enableDecorators is set, tparserr will use experimentalDecorators and emitDecoratorMetadata compiler options when creating the ts.Program

Given target file

@Name('ABC User')
export class User {
    @Required()
    id: number;

    @Optional()
    phone?: Array<string>;

    @MaxLength(101)
    address: string;

    @Optional()
    active: boolean;
}

The output would then contain a description of the used decorators and their args

[
    {
        "name": "User",
        "type": "object",
        "properties": {
            "id": {
                "type": "number",
                "required": true,
                "annotations": [
                    {
                        "name": "Required"
                    }
                ]
            },
            "phone": {
                "type": "array",
                "items": {
                    "type": "string"
                },
                "required": false,
                "annotations": [
                    {
                        "name": "Optional"
                    }
                ]
            },
            "address": {
                "type": "string",
                "required": true,
                "annotations": [
                    {
                        "name": "MaxLength",
                        "args": [
                            101
                        ]
                    }
                ]
            },
            "active": {
                "type": "boolean",
                "required": true,
                "annotations": [
                    {
                        "name": "Optional"
                    }
                ]
            }
        },
        "annotations": [
            {
                "name": "Name",
                "args": [
                    "ABC User"
                ]
            }
        ]
    }
]

Configuration

interface IParserOpts {
    /**
     * Input files to parse
     * Usually absolute paths unless *callerBaseDir* is provided (see below)
     */
    files?: Array<string>;

    // Declaring the intention to use relative paths
    useRelativePaths?: boolean; // defaults to false

    /**
     * Callers base dir - Must be provided when using relative path file(s)/targetDir 
     * or a mix of absolute and relative files
     * 
     * Note: see relative paths limitations
     */
    callerBaseDir?: string;

    // Input dir - to be used instead of *files*
    targetDir?: string;

    // If to parse only exports/default exports
    includeOnlyExports?: boolean; // defaults to false

    // If to include only required properties
    includeOnlyRequiredProperties?: boolean; // defaults to false

    // If to include the neste class names
    includeNestedClassNames?: boolean; // defaults to false
    
    // If to enable the extract of decorator descriptions
    enableDecorators?: boolean; // defaults to false
    
    // If to enable the use of tspathrr to resolve relative paths
    enableSourceFilePathing?: boolean // defaults to false
    
    /**
     * Logger to use instead of console if provided
     * 
     * Note: the logger will be usually used at debug and error log levels
     */
    logger?: ILogger // defaults to console
}

(Known) Limitations

Relative Paths - Absolute paths work best, but when providing relative paths and a calledBaseDir as __dirname, one has to make sure he takes into account the relative path in relation to the execution context. When building a TS program, the execution of said program will actually take place within the /dist folder and thus __dirname will have the path of the e.g. /dist/caller.js
Decorators - When decorator annotation extraction is enabled via enableDecorators, the base tsconfig.json might require experimentalDecorators and emitDecoratorMetadata compiler options to be enabled - they have to be enabled anyway in order to even decorate target classes.
Export Defaults - Using export default MyClass; on a separate line than where it's defined will not work when includeOnlyExports is enabled - doing so makes the ts.Node loose it's ExportDefault modifier.