or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-time-integration.mdcli-commands.mdfeature-system.mdindex.mdutilities.md
tile.json

utilities.mddocs/

Utility Functions

Helper functions for configuration path resolution and template string processing. These utilities are used internally by the addon and are available for external use by other addons or applications.

Capabilities

Configuration Path Resolution

Resolves the path to the optional features configuration file, supporting both standard and custom addon configurations.

/**
 * Get the path to the optional-features.json configuration file
 * @param project - Ember project instance
 * @returns Relative path to the configuration file
 */
function getConfigPath(project: EmberProject): string;

Usage Example:

const { getConfigPath } = require('@ember/optional-features/utils');

// In an addon or build script
let configPath = getConfigPath(this.project);
// Returns: "./config/optional-features.json" (standard)
// Returns: "./custom-config/optional-features.json" (custom)

// Read the configuration
let config = JSON.parse(fs.readFileSync(configPath, 'utf8'));

Behavior:

  • Default path: "./config/optional-features.json"
  • Custom path: Uses ember-addon.configPath from package.json if specified
  • Path format: Always returns a relative path starting with "./"

Custom Configuration Example:

// package.json
{
  "name": "my-ember-addon",
  "ember-addon": {
    "configPath": "custom-config"
  }
}

This would result in getConfigPath() returning "./custom-config/optional-features.json".

Template String Joining

Joins template literal strings and interpolated values into a single string.

/**
 * Join template literal strings with interpolated values
 * @param strings - Template literal string parts
 * @param ...args - Interpolated values
 * @returns Joined string with all interpolations
 */
function join(strings: TemplateStringsArray, ...args: any[]): string;

Usage Example:

const { join } = require('@ember/optional-features/utils');

let name = 'ember-app';
let version = '1.0.0';

let result = join`Building ${name} version ${version}`;
// Result: "Building ember-app version 1.0.0"

// Can also be called with explicit arrays
let result2 = join(['Hello ', ' world!'], 'beautiful');
// Result: "Hello beautiful world!"

Behavior:

  • Interleaves string parts with interpolated arguments
  • Handles any number of interpolated values
  • Preserves the exact structure of template literals
  • Returns a single concatenated string

Template String Stripping

Removes common indentation from template literal strings, useful for creating clean multi-line strings in code.

/**
 * Strip common indentation from template literal strings
 * @param strings - Template literal string parts  
 * @param ...args - Interpolated values
 * @returns String with common indentation removed and clean formatting
 */
function strip(strings: TemplateStringsArray, ...args: any[]): string;

Usage Example:

const { strip } = require('@ember/optional-features/utils');

// Multi-line string with indentation
let message = strip`
  This is a multi-line message
  that spans several lines
  with consistent indentation.
`;

// Result (indentation removed):
// "This is a multi-line message\nthat spans several lines\nwith consistent indentation."

// With interpolation
let feature = 'jquery-integration';
let description = strip`
  Enabling ${feature}...
  
  This will add jQuery to your application.
  Make sure this is what you want to do.
`;

Behavior:

  • Removes leading empty line if present
  • Detects common indentation from the first non-empty line
  • Strips that amount of indentation from all lines
  • Preserves relative indentation between lines
  • Trims trailing whitespace from the final line
  • Handles interpolated values correctly

Detailed Processing:

  1. Join interpolations: Combines template strings with arguments
  2. Split into lines: Breaks the string into individual lines
  3. Remove leading empty line: Drops first line if it's empty
  4. Detect base indentation: Uses indentation of first remaining line
  5. Strip indentation: Removes base indentation from all lines
  6. Clean trailing whitespace: Trims final line if it's only whitespace
  7. Rejoin: Combines lines back into a single string

Internal Usage

These utilities are used throughout the @ember/optional-features addon:

Configuration Management

// Loading feature configuration
let configPath = getConfigPath(this.project);
let features = this.project.require(configPath);

User Interface Messages

// CLI command help text
const USAGE_MESSAGE = strip`
  Usage:
  
    To list all available features, run ${chalk.bold('ember feature:list')}.
    To enable a feature, run ${chalk.bold('ember feature:enable some-feature')}.
`;

Feature Callback Messages

// Interactive prompts in feature callbacks
console.log(strip`
  Enabling ${chalk.bold('template-only-glimmer-components')}...
  
  This will change the semantics for template-only components.
  Some notable differences include...
`);

External Usage

Other addons can use these utilities for their own configuration and messaging needs:

Custom Configuration Files

// In another addon
const { getConfigPath } = require('@ember/optional-features/utils');

// Adapt for your own config file
let basePath = getConfigPath(this.project);
let myConfigPath = basePath.replace('optional-features.json', 'my-addon-config.json');

Clean Multi-line Strings

// In build scripts or documentation generation
const { strip } = require('@ember/optional-features/utils');

let documentation = strip`
  # ${packageName}
  
  This package provides ${description}.
  
  ## Installation
  
  npm install ${packageName}
`;

Type Definitions

// Template literal types for TypeScript users
type TemplateStringsArray = readonly string[] & {
  readonly raw: readonly string[];
};

// Project interface used by getConfigPath
interface EmberProject {
  root: string;
  pkg: {
    'ember-addon'?: {
      configPath?: string;
    };
  };
  config(): any;
  require(path: string): any;
  resolveSync(path: string): string;
}