Skip to main content

Commands (Selector Pattern)

Configurator supports command-oriented applications using the selector pattern, which provides hierarchical command structures through schema options.

  • A property is marked with selector: true to indicate it selects between alternatives
  • Properties marked with selection: 'value' (or selection: true to use the property name) are only evaluated when the selector matches
  • You can define sub-commands within selection properties to build a command hierarchy
  • The command line parser recognizes these patterns and produces appropriate parsing behavior

For example, here's an app defining a command schema:

spm.js
import { Schema } from '@versionzero/configurator';

const schema = new Schema('object')
  .property('action', new Schema('string', { selector: true }))

  .property('install', new Schema('object', { selection: 'install' })
    .property('packages', new Schema('array')
      .property('*', new Schema('string'))
      .required()
    )
    .property('save', new Schema('boolean'))
    .property('save-dev', new Schema('boolean'))
    .property('global', new Schema('boolean'))
  )

  .property('test', new Schema('object', { selection: 'test' })
    .property('ignore-scripts', new Schema('boolean'))
  )

  .property('run', new Schema('object', { selection: 'run' })
    .property('workspace', new Schema('string'))
    .property('if-present', new Schema('boolean'))
    .property('script', new Schema('string').required())
  );

Running this with node spm.js --help produces:

Usage: spm [install|test|run [command-options]]

  install [options] <string...>
    --save (-s) [true|false]
    --save-dev (-S) [true|false]
    --global (-g) [true|false]

  test [options]
    --ignore-scripts (-i) [true|false]

  run [options] <string-value>
    --workspace (-w) <string-value>
    --if-present (-i) [true|false]

Running with node spm.js install --save foo bar yields

{
  "action": "install",
  "install": {
    "packages": [ "foo", "bar" ],
    "save": true
  }
}

The selector pattern provides several benefits:

  • The command line parser automatically recognizes the structure and parses hierarchically
  • Environment variables work consistently: SPM_INSTALL_SAVE, SPM_TEST_IGNORE_SCRIPTS, etc.
  • Only the selected command's properties are evaluated (properties for other commands are suppressed)
  • The pattern naturally supports nested sub-commands

In other words, Configurator commands don't actually "do" anything on their own; they simply provide structured hints for the command line to hierarchically assemble the configuration in a friendly manner. The actual work of interpreting what a command "means" is up to the application.

See the API documentation for Schema for more information on using the selector pattern.

(For a higher-level abstraction that builds on Configurator to provide executable code modules, see ModuleManager).