interface to config files for geenee projects.

📋 Why
💡 What
🔧 Usage
❗ About Configurations
📎 Creating Your Config File
📝 Dirs List
🔍 Custom File Filter
📌 Other Settings
🌟 Values in the Config File
🌀 API
- Functions
- Configuration Interface

📋 Why

It's a pain to maintain a geenee template.

💡 What

A Configuration type, as well as simple getConfig and setConfig functions to keep them stored in a file.

🔧 Usage

Add the package:

npm i gear-box

A config file in geenee is called config.yml and is stored in the root directory of a template.

You can read and write to the file easily:

  const templateDir = __dirname + '/template'

  const config = await getConfig(templateDir)

  // read and modify config...

  await setConfig(templateDir, config) // saves the new version

❗ About Configurations

Every template needs a config YAML file, which is $TEMPLATE/config.yml.

Check out the one for this package for an example.

📎 Creating Your Config File

Add the following, substituting as appropriate between the less than and greater than signs:

name: <Template Name>
version: 1.0
category: <Description>

For category, currently you can put whatever you'd like to describe it. You could probably put the name of a common Framework if it's relevant.

The category may be used soon for classification in a registry of shared templates. In theory, is should be possible to switch between templates of a shared type that meet criteria. You may also create switchable templates yourself, which will allow you to switch between various looks or other options.

📝 Dirs List

You also need to add a list of dirs. Use this as an example (you only need custom unless you also want dynamic components that connect to a server):

dirs:
    custom: src/custom
    components: src/components
    queries: src/components/source-props

The dirs are all relative to the code base generated by users of your app.

components is where any dynamically generated components will be.
static is a place where static files are generated.
custom is a place where they can put additional custom code.
queries is optional if you will be requiring queries to a backend.

🔍 Custom File Filter

You need to tell geenee what files to search for in a code base when testing or generating code. format.customFileFilter is a glob pattern.

This example (which is for a TypeScript code base), uses one pattern that captures ts and md files:

format:
  customFileFilter: '*.{ts,tsx,md}'

The suffixes shown can be replaced as needed. So for a Javascript code base, you could put '.{js}'. If you are using jsx, you could put '.{js, jsx}'.

As with all glob patterns, you can also list multiple patterns:

format:
  customFileFilter: '+(*.{ts,tsx,md)|.eslintignore}'

You can add other settings as specified below, but if you are following the sequence of steps to create a template you can return now.

📌 Other Settings

To get started, you can copy something like this sample into config.yml and modify as needed:

format:
  customFileFilter: '.{js,jsx,md}'

componentTypes:
  creation:
    suffix: CreationForm
    singular: true
  list:
    singular: false
  single:
    singular: true

dataFunctionTypes:
  selectable:
    components:
      - list
      - single
    requiresSource: true
    nodeType: selectable
  constrain:
    components: null
  create:
    components:
      - list
      - single
      - creation
  use:
    components:
      - list
      - single
    requiresSource: true
  property:
    components:
      - list
      - single

🌟 Values in the Config File

componentTypes [More documentation is planned shortly for component types.]
dataFunctionTypes [More documentation is planned shortly for data function types types.]

🌀 API

Functions

async function getConfig(templateDir: string): Promise<Configuration>

Returns a Configuration. Will return an error if the directory given does not exist, has no config.yml file, or has a defective one.

async setConfig(templateDir: string, config: Configuration)

Writes a config file config.yml based on config to the directory templateDir.

WARNING: Will simply overwrite an existing config.yml file.

Will return an error if the directory does not exist.

async setConfig(templateDir: string, config: Configuration)

function isValidConfig(obj:any):boolean

Checks whether the object is apparently a valid config. Currently very limited, simply checking for the highest level keys.

Configuration Interface

You can see the configuration interface code for precise information about the exported types.

YizYah/cogs-box