npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

helical

v0.4.3

Published

Helical is a general purpose code generator. It takes a data model definition and a set of templates (called generators) and generates an output

Downloads

21

Readme

helical

Helical is a general purpose code generator. It takes a data model definition and a set of templates (called generators) and generates an output.

Data model definition

It is just a JSON file with no given structure. The structure depends on the templates used. This file can be stored at any location.

Manifest and generators

You need a manifest file and a set of templates. You have to put all of them in the same directory. The templates can be in subdirectories, but the manifest file must always be in the root of the directory and it must be called helical.json.

The templating language used in all the templates is nunjucks

The manifest file is a JSON file with two sections:

  • generators
  • options

Here there is an example:

{
  "generators": [
    {
      "source": "generators/entity.js",
      "path": "models/{{ object.name | lower }}.js",
      "foreach": "entities"
    },
    {
      "source": "generators/endpoint.js",
      "path": "controllers/{{ ancestors[0].name | lower }}-{{ object.action | lower }}.js",
      "foreach": "entities.endpoints"
    },
    {
      "source": "generators/app.js",
      "path": "index.js",
      "foreach": ""
    }
  ],
  "options": [
    {
      "name": "css",
      "describe": "CSS preprocessor",
      "type": "string",
      "choices": ["less", "sass"]
    }
  ]
}

And this could be a data model suitable of being processed by these generators:

{
  "projectName": "project_name",
  "entities": [
    {
      "name": "User",
      "fields": [
        {
          "name": "email",
          "type": "string"
        },
        {
          "name": "name",
          "type": "string"
        }
      ],
      "endpoints": [
        {
          "action": "show",
          "method": "get"
        },
        {
          "action": "create",
          "method": "post"
        },
        {
          "action": "edit",
          "method": "put"
        },
        {
          "action": "delete",
          "method": "delete"
        }
      ]
    }
  ]
}

Generators

Every generator must have at least these attributes: source, path and foreach.

  • source: this is the relative path to the template.
  • path: this is an inline template to generate the output filename.
  • foreach: tells helical which objects should be processed by this generator. Leave it empty if you only want to execute this template once for the whole data model.

In the example above for the first generator helical will loop over all the entities in your data model. And for each entity it will run the entity.js template. If the data model file contains an entity with { "name": "User" } then after processing that entity the output will be stored in a file called models/user.js.

Every template, including the inlined templates to generate the filename (path attribute), will receive these objects:

  • object: the object being processed.
  • ancestors: an array of ancestor objects.
  • root: the root of the data model.
  • options: see section options below.

In the example above the second generator will be processed for each endpoint of each entity. Every time the endpoint.js template is processed it will receive these objects:

  • object: the endpoint being processed.
  • ancestors: in this example ancestors[0] will reference the parent entity of this endpoint.
  • root: the root of the data model.

Options

Optionally you can define an array of options in your helical.json file. These are values that the user can pass in the command line interface to the generators. Each option has the following attributes:

  • name. The name of the option. If you have an option called css in your templates you can use options.css to access the value
  • describe (optional). A description of this option
  • type (optional). The type of this option. Can be string, array, boolean, count or string. See the yargs documentation about this.
  • choices (optional). You can specify an array of allowed values for this option.
  • default (optional). The default value for this option.

If you specify a not boolean option and there's not a default value and the user didn't specify the option in the command line then the application will exit with a message like this:

Usage: helical --model model.json --generator /path/to/some-generator

Options:
  --model, -m      The data model file                                                             [string] [required]
  --generator, -g  The directory that contains the helical generator                               [string] [required]
  --output, -o     Output directory                                                                [string] [required]
  --force, -f      Override files existing files                                                             [boolean]
  -h, --help       Show help                                                                                 [boolean]
  --css            CSS preprocessor                                      [string] [required] [choices: "less", "sass"]

Missing required argument: css

Static files

You can create a static directory and everything on it will be copied to the output directory. This is a good place to put files that are not plain text such as images, fonts, or simply plain text files that don't need to be processed.

Next steps message

You can render a message after all the files are generated creating a template next-steps.txt. This template will have access to the root and options objects.

Overriding files

By default helical will not override existing files. But you can use the --force option to change this behavior.

Watching for file changes

While developing helical generators or just to see interactively how the generators change when editing your data model, you can use the --watch option in the command line.

Note: files starting with a dot (.) are ignored.

Error notifications

If you want to get notified when an error occurs processing any file, parsing the model, etc. you can use the --notify option. Right now it only notifies about errors, but in a future it will notify if the whole process got fixed if you change any file and it was giving errors previously.

# Installation

npm install helical -g

Example

In this repository there is an example in the example directory. You can run it with:

helical \
  --model example/model.json \
  --generator example \
  --output output \
  --css less

This is the output:

Wrote output/models/user.js
Wrote output/controllers/user-show.js
Wrote output/controllers/user-create.js
Wrote output/controllers/user-edit.js
Wrote output/controllers/user-delete.js
Wrote output/index.js

Skipping objects

You can avoid some objects to be processed by returning an empty file name in the path attribute of a generator. Example:

{
  "source": "endpoint.js",
  "path": "{% if object.action != 'delete' %}controllers/{{ ancestors[0].name | lower }}-{{ object.action | lower }}.js{% endif %}",
  "foreach": "entities.endpoints"
}

In this case endpoints with "action": "delete" won't generate any output.