or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md option-definitions.md parsing-options.md

tile.json

Option Definitions

Option definitions describe the command-line options your application accepts. Each definition specifies the option name, data type, behavior, and validation rules.

Capabilities

Basic Option Definition

The minimal requirement is just the option name. All other properties are optional with sensible defaults.

/**
 * Minimal option definition with just a name
 * Defaults: type=String, no alias, single value
 */
const optionDefinition = { name: 'file' };

Usage Examples:

import commandLineArgs from "command-line-args";

const options = [
  { name: 'file' },    // --file value
  { name: 'depth' }    // --depth value  
];

// Command: --file lib.js --depth 2
// Result: { file: 'lib.js', depth: '2' }

Type Conversion

The type property specifies a setter function that processes the option value, enabling type conversion and validation.

/**
 * Built-in type converter functions
 */
const String: (value: any) => string;  // Default type
const Number: (value: any) => number;
const Boolean: (value: any) => boolean;

/**
 * Custom type converter function
 * @param {any} value - The raw command-line value
 * @returns {any} Processed value
 */
type TypeConverter = (value: any) => any;

Usage Examples:

const options = [
  { name: 'file', type: String },       // Default: String
  { name: 'port', type: Number },       // Convert to number
  { name: 'verbose', type: Boolean },   // Boolean flag
];

// Command: --port 3000 --verbose
// Result: { port: 3000, verbose: true }

// Custom type converter
const options2 = [
  { 
    name: 'config', 
    type: (filename) => {
      if (!fs.existsSync(filename)) {
        throw new Error(`Config file not found: ${filename}`);
      }
      return JSON.parse(fs.readFileSync(filename, 'utf8'));
    }
  }
];

Short Aliases

Single character aliases provide convenient short options (getopt-style).

/**
 * Option definition with short alias
 * @property {string} alias - Single character (not digit or hyphen)
 */
interface OptionWithAlias {
  name: string;
  alias: string;  // Single character only
  type?: function;
}

Usage Examples:

const options = [
  { name: 'verbose', alias: 'v', type: Boolean },
  { name: 'output', alias: 'o', type: String },
  { name: 'count', alias: 'c', type: Number }
];

// These are equivalent:
// --verbose --output file.txt --count 5
// -v -o file.txt -c 5
// -voc 5 file.txt (combined short options)

Multiple Values

Options can collect multiple values into an array using multiple or lazyMultiple.

/**
 * Multiple value collection modes
 */
interface MultipleValueOption {
  name: string;
  multiple?: boolean;      // Greedy parsing: collects all following values
  lazyMultiple?: boolean;  // Non-greedy: stops at next option
}

Usage Examples:

// Greedy multiple (multiple: true)
const options = [
  { name: 'files', type: String, multiple: true }
];

// Command: --files one.js two.js three.js
// Result: { files: ['one.js', 'two.js', 'three.js'] }

// Non-greedy multiple (lazyMultiple: true)  
const options2 = [
  { name: 'files', lazyMultiple: true },
  { name: 'verbose', alias: 'v', type: Boolean, lazyMultiple: true }
];

// Command: --files one.js --files two.js -vvv
// Result: { files: ['one.js', 'two.js'], verbose: [true, true, true] }

Default Option

One option can be designated as the defaultOption to collect values that don't belong to any named option.

/**
 * Default option collects unaccounted values
 * Only one defaultOption allowed per definition set
 * Cannot be Boolean type
 */
interface DefaultOption {
  name: string;
  defaultOption: boolean;
  multiple?: boolean;  // Usually combined for collecting file lists
}

Usage Examples:

const options = [
  { name: 'files', multiple: true, defaultOption: true },
  { name: 'verbose', alias: 'v', type: Boolean }
];

// These are equivalent:
// --files one.js two.js --verbose
// one.js two.js --verbose
// Result: { files: ['one.js', 'two.js'], verbose: true }

Default Values

Options can have initial values that are used when the option is not specified.

/**
 * Option with default value
 * @property {any} defaultValue - Initial value when option not specified
 */
interface OptionWithDefault {
  name: string;
  defaultValue: any;
  type?: function;
}

Usage Examples:

const options = [
  { name: 'port', type: Number, defaultValue: 3000 },
  { name: 'files', multiple: true, defaultValue: ['index.js'] }
];

// Command: (no arguments)
// Result: { port: 3000, files: ['index.js'] }

// Command: --port 8080
// Result: { port: 8080, files: ['index.js'] }

// Command: --files app.js
// Result: { port: 3000, files: ['app.js'] }

Option Grouping

Options can be organized into named groups for structured output.

/**
 * Option with group assignment
 * @property {string|string[]} group - Group name(s) for this option
 */
interface GroupedOption {
  name: string;
  group: string | string[];
}

/**
 * Grouped output structure
 */
interface GroupedOutput {
  _all: object;           // All options
  _none?: object;         // Options without group
  [groupName: string]: object;  // Named groups
}

Usage Examples:

const options = [
  { name: 'verbose', group: 'standard' },
  { name: 'help', group: ['standard', 'main'] },
  { name: 'compress', group: ['server', 'main'] },
  { name: 'debug' }  // No group (goes to _none)
];

// Command: --verbose --debug --compress
// Result: {
//   _all: { verbose: true, debug: true, compress: true },
//   standard: { verbose: true },
//   server: { compress: true },
//   main: { compress: true },
//   _none: { debug: true }
// }

Unicode Support

Option names and aliases support Unicode characters for internationalization.

/**
 * Unicode option definitions
 */
const unicodeOptions = [
  { name: 'файл' },           // Cyrillic
  { name: '文件' },           // Chinese  
  { name: 'αρχείο', alias: 'α' }  // Greek with Greek alias
];

Validation Rules

Option definitions are validated automatically. Invalid definitions throw INVALID_DEFINITIONS errors:

Name Validation

Required: Every definition must have a name property
Unique: No duplicate names (case-sensitive, or case-insensitive if caseInsensitive: true)

Type Validation

Function Required: type property must be a function (String, Number, Boolean, or custom)

Alias Validation

Single Character: Aliases must be exactly one character
Not Numeric: Aliases cannot be digits (0-9)
Not Hyphen: Aliases cannot be the hyphen character (-)
Unique: No duplicate aliases

Default Option Validation

Single Default: Only one option can have defaultOption: true
Not Boolean: Boolean options cannot be the default option

Group Validation

Valid Groups: Group names are validated for basic structure

Validation Examples:

// ❌ Invalid definitions that throw INVALID_DEFINITIONS
const badOptions = [
  { },                                    // Missing name
  { name: 'file', type: 'String' },      // type must be function
  { name: 'output', alias: 'out' },      // alias too long
  { name: 'verbose', alias: '1' },       // numeric alias
  { name: 'help', alias: '-' },          // hyphen alias
  { name: 'file', defaultOption: true, type: Boolean }  // Boolean default
];

// ✅ Valid definitions
const goodOptions = [
  { name: 'file' },                      // Minimal valid
  { name: 'port', type: Number },        // With type
  { name: 'verbose', alias: 'v', type: Boolean },  // With alias
  { name: 'files', multiple: true, defaultOption: true }  // Multiple default
];

Version

Tile

Files