or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-ember-cli-deprecation-workflow

Provides a comprehensive deprecation management workflow for Ember applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ember-cli-deprecation-workflow@3.4.x

To install, run

npx @tessl/cli install tessl/npm-ember-cli-deprecation-workflow@3.4.0

index.mddocs/

ember-cli-deprecation-workflow

ember-cli-deprecation-workflow is an Ember CLI addon that provides a comprehensive deprecation management workflow for Ember applications. It helps developers systematically address deprecations during Ember upgrades by controlling console output, collecting deprecation data, and enabling incremental deprecation resolution.

Package Information

  • Package Name: ember-cli-deprecation-workflow
  • Package Type: npm (Ember CLI addon)
  • Language: JavaScript (with TypeScript definitions)
  • Installation: ember install ember-cli-deprecation-workflow

Core Imports

import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow';

For named exports:

import { 
  detectWorkflow, 
  flushDeprecations, 
  handleDeprecationWorkflow, 
  deprecationCollector 
} from 'ember-cli-deprecation-workflow';

Basic Usage

// 1. Create app/deprecation-workflow.js
import setupDeprecationWorkflow from 'ember-cli-deprecation-workflow';

setupDeprecationWorkflow({
  throwOnUnhandled: false,
  workflow: [
    { handler: 'silence', matchId: 'some.deprecation.id' },
    { handler: 'log', matchMessage: /pattern/ },
    { handler: 'throw', matchId: 'critical.deprecation' }
  ]
});

// 2. Import in app/app.js
import './deprecation-workflow';

// 3. Collect deprecations during testing
// Run in browser console: deprecationWorkflow.flushDeprecations()

Architecture

ember-cli-deprecation-workflow is built around several key components:

  • Setup Function: Main configuration entry point that registers deprecation handlers
  • Workflow Engine: Matches deprecations against configured rules using ID or message patterns
  • Handler System: Three modes (silence, log, throw) for processing matched deprecations
  • Collection System: Gathers deprecation IDs during runtime for configuration generation
  • Global API: Runtime access to deprecation management functionality

Constants

Log Rate Limit

Maximum number of log messages per deprecation before rate limiting takes effect.

/** Maximum number of console log messages per deprecation ID */
const LOG_LIMIT: number = 100;

Capabilities

Main Configuration

Primary function to set up the deprecation workflow system with custom configuration.

/**
 * Sets up deprecation workflow with custom configuration
 * @param config - Optional configuration object
 */
function setupDeprecationWorkflow(config?: DeprecationWorkflowConfig): void;

interface DeprecationWorkflowConfig {
  /** Throw error for deprecations that don't match any workflow rule */
  throwOnUnhandled?: boolean;
  /** Array of workflow rules for handling specific deprecations */
  workflow?: Workflow[];
}

interface WorkflowMatchId {
  /** How to handle the matched deprecation */
  handler?: 'silence' | 'log' | 'throw';
  /** Match deprecations by their unique ID (string or regex) */
  matchId: string | RegExp;
}

interface WorkflowMatchMessage {
  /** How to handle the matched deprecation */
  handler?: 'silence' | 'log' | 'throw';
  /** Match deprecations by their message content (string or regex) */
  matchMessage: string | RegExp;
}

type Workflow = WorkflowMatchId | WorkflowMatchMessage;

Usage Examples:

// Basic setup with no configuration (uses defaults)
setupDeprecationWorkflow();

// Setup with throwOnUnhandled enabled
setupDeprecationWorkflow({
  throwOnUnhandled: true
});

// Setup with specific workflow rules
setupDeprecationWorkflow({
  workflow: [
    { handler: 'silence', matchId: 'ember-data.deprecation' },
    { handler: 'log', matchMessage: /template/ },
    { handler: 'throw', matchId: 'critical.breaking.change' }
  ]
});

// Handler is optional - defaults to application or console behavior
setupDeprecationWorkflow({
  workflow: [
    { matchId: 'some.deprecation' }, // Uses default behavior
    { handler: 'silence', matchMessage: /pattern/ }
  ]
});

Deprecation Collection and Flushing

Generate configuration code from collected deprecations during runtime.

/**
 * Generate JavaScript configuration code from collected deprecations
 * @param options - Optional flush configuration with destructuring default
 * @returns Generated JavaScript code string for deprecation workflow setup
 */
function flushDeprecations(options?: {
  /** Default handler for newly discovered deprecations (defaults to 'silence') */
  handler?: 'silence' | 'log' | 'throw';
  /** Existing configuration to merge with collected deprecations (defaults to empty config) */
  config?: DeprecationWorkflowConfig;
}): string;

Usage Examples:

// Flush with default 'silence' handler
const config = deprecationWorkflow.flushDeprecations();

// Flush with 'log' handler for new deprecations
const config = deprecationWorkflow.flushDeprecations({ handler: 'log' });

// Flush and merge with existing configuration
const existingConfig = { throwOnUnhandled: true, workflow: [] };
const config = deprecationWorkflow.flushDeprecations({ 
  handler: 'silence',
  config: existingConfig 
});

// Note: Only newly collected deprecations not already in existing config will be added

Workflow Detection

Determine which workflow rule matches a given deprecation.

/**
 * Detect which workflow rule matches a deprecation
 * @param config - Deprecation workflow configuration
 * @param message - Deprecation message
 * @param options - Deprecation metadata from Ember
 * @returns Matching workflow rule or undefined
 */
function detectWorkflow(
  config: DeprecationWorkflowConfig, 
  message: string, 
  options: DeprecationOptions
): Workflow | undefined;

interface DeprecationOptions {
  /** Unique identifier for the deprecation */
  id?: string;
  /** Version when the feature was deprecated */
  since?: string;
  /** Version when the feature will be removed */
  until?: string;
  /** Description of what is being deprecated */
  for?: string;
}

Deprecation Handling

Core function that processes deprecations according to workflow configuration.

/**
 * Handle a deprecation according to workflow configuration
 * @param config - Deprecation workflow configuration
 * @param message - Deprecation message
 * @param options - Deprecation metadata
 * @param next - Callback to pass control to next handler
 */
function handleDeprecationWorkflow(
  config: DeprecationWorkflowConfig,
  message: string,
  options: DeprecationOptions,
  next: (message: string, options: DeprecationOptions) => void
): void;

Deprecation Collection

Collect deprecation IDs for later configuration generation.

/**
 * Collect deprecation IDs for configuration generation
 * @param message - Deprecation message
 * @param options - Deprecation metadata
 * @param next - Callback to continue deprecation chain
 */
function deprecationCollector(
  message: string, 
  options: DeprecationOptions, 
  next: (message: string, options: DeprecationOptions) => void
): void;

Handler Types

Silence Handler

Completely suppresses deprecation output with no console logging.

{ handler: 'silence', matchId: 'some.deprecation.id' }

Log Handler

Allows normal deprecation logging with rate limiting (maximum 100 messages per deprecation).

{ handler: 'log', matchMessage: /template-related/ }

Throw Handler

Converts deprecation to thrown error, halting execution. Warning: May break application.

{ handler: 'throw', matchId: 'critical.breaking.change' }

Global Runtime API

The addon exposes global functionality for runtime deprecation management.

interface DeprecationWorkflowGlobal {
  /** Global access to flush deprecations function */
  flushDeprecations(options?: {
    handler?: 'silence' | 'log' | 'throw';
    config?: DeprecationWorkflowConfig;
  }): string;
  /** Collected deprecation data */
  deprecationLog: {
    /** Set of unique deprecation IDs encountered */
    messages: Set<string>;
  };
  /** Count of log messages per deprecation (for rate limiting, initialized on first log) */
  logCounts?: Record<string, number>;
}

/** Global deprecation workflow instance */
declare const deprecationWorkflow: DeprecationWorkflowGlobal;

Usage Examples:

// Access collected deprecation IDs
console.log(deprecationWorkflow.deprecationLog.messages);

// Generate configuration from collected deprecations
const config = deprecationWorkflow.flushDeprecations();

// Check log counts for rate limiting
console.log(deprecationWorkflow.logCounts);

Ember CLI Addon Configuration

Configure the addon behavior in your Ember CLI build.

interface EmberCLIDeprecationWorkflowConfig {
  /** Force enable/disable the addon (bypasses test detection) */
  enabled?: boolean;
}

Usage in ember-cli-build.js:

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    'ember-cli-deprecation-workflow': {
      enabled: true // Force enable in development even without tests
    }
  });
  return app.toTree();
};

Matcher Patterns

String Matching

Exact string matching for deprecation IDs or messages.

{ handler: 'silence', matchId: 'ember-data.deprecation.exact-match' }
{ handler: 'log', matchMessage: 'Exact deprecation message' }

Regular Expression Matching

Pattern-based matching using JavaScript RegExp objects.

{ handler: 'silence', matchId: /^ember-data\./ }
{ handler: 'log', matchMessage: /template.*deprecated/ }

Error Handling

Unhandled Deprecation Errors

When throwOnUnhandled: true, unmatched deprecations throw errors:

// Throws: Error with original deprecation message
setupDeprecationWorkflow({ throwOnUnhandled: true });

Explicit Throw Handler Errors

When using handler: 'throw', matched deprecations throw formatted errors:

// Throws: Error("Deprecation message (id: deprecation.id)")
// If no id provided: Error("Deprecation message (id: unknown)")
{ handler: 'throw', matchId: 'some.deprecation' }

Automatic Setup Behavior

The addon automatically includes a vendor bridge script that attempts to call setupDeprecationWorkflow() with no configuration when the addon is loaded. This provides basic deprecation collection even without explicit configuration.

// Vendor bridge behavior (automatic)
try {
  require('ember-cli-deprecation-workflow').default();
} catch (e) {
  // Silently fails if addon not available
}

Production Build Behavior

  • Deprecation handling is automatically disabled in production builds
  • All handlers (silence, log, throw) only operate in development/test environments
  • Production builds exclude deprecation workflow code entirely

Workflow Process

  1. Installation: ember install ember-cli-deprecation-workflow
  2. Initial Setup: Create app/deprecation-workflow.js with setupDeprecationWorkflow()
  3. Import: Add import './deprecation-workflow'; to app/app.js
  4. Collection: Run tests/app to encounter deprecations
  5. Flush: Execute deprecationWorkflow.flushDeprecations() in browser console
  6. Configuration: Copy generated code to replace app/deprecation-workflow.js content
  7. Incremental Resolution: Change individual deprecations from silence to throw, fix, and remove