componentsjs-generator

Components-Generator.js

This is a tool to automatically generate .jsonld component files from TypeScript classes for the Components.js dependency injection framework.

Before you use this tool, it is recommended to first read the Components.js documentation.

Getting started

1. Install as a dev dependency

npm install -D componentsjs-generator

or

yarn add -D componentsjs-generator

2. Declare components in package.json

If you are already using Components.js, you already have this.

Add the following entries to package.json:

{
  ...
  "lsd:module": "https://linkedsoftwaredependencies.org/bundles/npm/my-package",
  "lsd:components": "components/components.jsonld",
  "lsd:contexts": {
    "https://linkedsoftwaredependencies.org/bundles/npm/my-package/^1.0.0/components/context.jsonld": "components/context.jsonld"
  },
  "lsd:importPaths": {
    "https://linkedsoftwaredependencies.org/bundles/npm/my-package/^1.0.0/components/": "components/",
    "https://linkedsoftwaredependencies.org/bundles/npm/my-package/^1.0.0/config/": "config/"
  },
  ...
}

On each line, make sure to replace my-package with your package name.

3. (optional) Add generate script

Call componentsjs-generator as a npm script by adding a scripts entry to your package.json:

{
  ...,
  "scripts": {
    ...
    "build": "npm run build:ts && npm run build:components",
    "build:ts": "tsc",
    "build:components": "componentsjs-generator",
    "prepare": "npm run build",
    ...
  }
}

This is only a recommended way of calling componentsjs-generator, you are free to call it in a different way that better suits your pipeline.

4. (optional) Ignore generated components files

Since we automatically generate the components files, we do not have to check them into version control systems like git. So we can add the following line to .gitignore:

components

If you do this, make sure that the components folder is published to npm by adding the following to your package.json:

{
  ...
  "files": [
    ....
    "components/**/*.jsonld",
    "config/**/*.json",
    ....
  ],
  ....
}

Usage

When invoking componentsjs-generator, this tool will automatically generate .jsonld components files for all TypeScript files that are exported by the current package.

Generates component file for a package
Usage:
  componentsjs-generator
  Options:
       -p path/to/package   The directory of the package to look in, defaults to working directory
       -s lib               Relative path to directory containing source files, defaults to 'lib'
       -c components        Relative path to directory that will contain components files, defaults to 'components'
       -e jsonld            Extension for components files (without .), defaults to 'jsonld'
       --help               Show information about this command

Note: This generator will read .d.ts files, so it is important that you invoke the TypeScript compiler (tsc) before using this tool.

How it works

For each exported TypeScript class, its constructor will be checked, and component parameters will be generated based on the TypeScript type annotations.

Example

TypeScript class:

/**
 * This is a great class!
 */
export class MyClass extends OtherClass {
  /**
   * @param paramA - My parameter
   */
  constructor(paramA: boolean, paramB: number) {
  
  }
}

Component file:

{
  "@context": [
    "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^1.0.0/components/context.jsonld"
  ],
  "@id": "npmd:my-package",
  "components": [
    {
      "@id": "ex:MyFile#MyClass",
      "@type": "Class",
      "requireElement": "MyClass",
      "extends": "ex:OtherFile#OtherClass",
      "comment": "This is a great class!",
      "parameters": [
        {
          "@id": "ex:MyFile#MyClass_paramA",
          "range": "xsd:boolean",
          "comment": "My parameter",
          "unique": true,
          "required": true
        },
        {
          "@id": "ex:MyFile#MyClass_paramB",
          "range": "xsd:integer",
          "unique": true,
          "required": true
        }
      ],
      "constructorArguments": [
        { "@id": "ex:MyFile#MyClass_paramA" },
        { "@id": "ex:MyFile#MyClass_paramB" }
      ]
    }
  ]
}

Arguments

Each argument in the constructor of the class must be one of the following:

• A primitive type such as boolean, number, string, which will be mapped to an XSD type
• Another class, which will be mapped to the component @id.
• A hash or interface containing key-value pairs where each value matches one of the possible options. Nesting is allowed.
• An array of any of the allowed types.

Here is an example that showcases all of these options:

import {Logger} from "@comunica/core";
export class SampleActor {
   constructor(args:HashArg, testArray:HashArg[], numberSample: number, componentExample: Logger) {}
}
export interface HashArg {
   args: NestedHashArg;
   arraySample: NestedHashArg[];
}
export interface NestedHashArg extends ExtendsTest {
   test: boolean;
   componentTest: Logger;
}
export interface ExtendsTest {
   stringTest: String;
}

Argument tags

Using comment tags, arguments can be customized.

Tags

Tag	Action
@ignored	This field will be ignored.
@default {<value>}	The default attribute of the parameter will be set to <value>
@range {<type>}	The range attribute of the parameter will be set to <type>. You can only use values that fit the type of field. Options: boolean, int, integer, number, byte, long, float, decimal, double, string. For example, if your field has the type number, you could explicitly mark it as a float by using @range {float}. See the documentation.

Examples

Tagging constructor fields:

TypeScript class:

export class MyActor {
    /**
     * @param myByte - This is an array of bytes @range {byte}
     * @param ignoredArg - @ignored
     */ 
    constructor(myByte: number[], ignoredArg: string) {

    }
}

Component file:

{
  "components": [
    {
      "parameters": [
        {
          "@id": "my-actor#TestClass#myByte",
          "range": "xsd:byte",
          "required": false,
          "unique": false,
          "comment": "This is an array of bytes"
        }
      ],
      "constructorArguments": [
        {
          "@id": "my-actor#TestClass#myByte"
        }
      ]
    }
  ]
}

Tagging interface fields:

TypeScript class:

export class MyActor {
  constructor(args: IActorBindingArgs) {
    super(args)
  }
}

export interface IActorBindingArgs {
  /**
   * This field is very important
   * @range {float}
   * @default {5.0}
   */
   floatField?: number;
}

Component file:

{
  "components": [
    {
      "parameters": [
        {
          "@id": "my-actor#floatField",
          "range": "xsd:float",
          "required": false,
          "unique": true,
          "default": "5.0",
          "comment": "This field is very important"
        }
      ],
      "constructorArguments": [
        {
          "fields": [
            {
              "keyRaw": "floatField",
              "value": "my-actor#floatField"
            }
          ]
        }
      ]
    }
  ]
}

License

Components.js is written by Ruben Taelman.

This code is copyrighted by Ghent University – imec and released under the MIT license.

Changelog

v1.4.0 - 2020-11-06

Added

• Translate Record type aliases into hashes, Closes #47

Changed

• Be less strict in how typings are defined in package.json

<a name="v1.3.0"></a>