Class @ember/debug

Module: @ember/debug

Show:

assert (description, condition) public

Module: @ember/debug

Defined in packages/@ember/debug/index.ts:134

Available since v1.0.0 

import { assert } from '@ember/debug';
description
String
Describes the expectation. This will become the text of the Error thrown if the assertion fails.
condition
Any
Must be truthy for the assertion to pass. If falsy, an exception will be thrown.

Verify that a certain expectation is met, or throw a exception otherwise.

This is useful for communicating assumptions in the code to other human readers as well as catching bugs that accidentally violates these expectations.

Assertions are removed from production builds, so they can be freely added for documentation and debugging purposes without worries of incuring any performance penalty. However, because of that, they should not be used for checks that could reasonably fail during normal usage. Furthermore, care should be taken to avoid accidentally relying on side-effects produced from evaluating the condition itself, since the code will not run in production.

1
2
3
4
5
6
7

import { assert } from '@ember/debug';

// Test for truthiness
assert('Must pass a string', typeof str === 'string');

// Fail unconditionally
assert('This code path should never be run');

debug (message) public

Module: @ember/debug

Defined in packages/@ember/debug/index.ts:174 

import { debug } from '@ember/debug';
message
String
A debug message to display.

Display a debug notice.

Calls to this function are not invoked in production builds.

1
2
3

import { debug } from '@ember/debug';

debug('I\'m a debug notice!');

deprecate (message, test, options) public

Module: @ember/debug

Defined in packages/@ember/debug/lib/deprecate.ts:185

Available since v1.0.0

message
String
A description of the deprecation.
test
Boolean
A boolean. If falsy, the deprecation will be displayed.
options
Object
id
String
A unique id for this deprecation. The id can be used by Ember debugging tools to change the behavior (raise, log or silence) for that specific deprecation. The id should be namespaced by dots, e.g. "view.helper.select".
until
String
The version of Ember when this deprecation warning will be removed.
for
String
A namespace for the deprecation, usually the package name
since
Object
Describes when the deprecation became available and enabled.
url
String
An optional url to the transition guide on the emberjs.com website.

Display a deprecation warning with the provided message and a stack trace (Chrome and Firefox only).

Ember itself leverages Semantic Versioning to aid projects in keeping up with changes to the framework. Before any functionality or API is removed, it first flows linearly through a deprecation staging process. The staging process currently contains two stages: available and enabled.

Deprecations are initially released into the 'available' stage. Deprecations will stay in this stage until the replacement API has been marked as a recommended practice via the RFC process and the addon ecosystem has generally adopted the change.

Once a deprecation meets the above criteria, it will move into the 'enabled' stage where it will remain until the functionality or API is eventually removed.

For application and addon developers, "available" deprecations are not urgent and "enabled" deprecations require action.

  • In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import { deprecate } from '@ember/debug';

deprecate(
  'Use of `assign` has been deprecated. Please use `Object.assign` or the spread operator instead.',
  false,
  {
    id: 'ember-polyfills.deprecate-assign',
    until: '5.0.0',
    url: 'https://deprecations.emberjs.com/v4.x/#toc_ember-polyfills-deprecate-assign',
    for: 'ember-source',
    since: {
      available: '4.0.0',
      enabled: '4.0.0',
    },
  }
);

registerDeprecationHandler (handler) public

Module: @ember/debug

Defined in packages/@ember/debug/lib/deprecate.ts:39

Available since v2.1.0 

import { registerDeprecationHandler } from '@ember/debug';
handler
Function
A function to handle deprecation calls.

Allows for runtime registration of handler functions that override the default deprecation behavior. Deprecations are invoked by calls to @ember/debug/deprecate. The following example demonstrates its usage by registering a handler that throws an error if the message contains the word "should", otherwise defers to the default handler.

1
2
3
4
5
6
7
8
9
10

import { registerDeprecationHandler } from '@ember/debug';

registerDeprecationHandler((message, options, next) => {
  if (message.indexOf('should') !== -1) {
    throw new Error(`Deprecation message with should: ${message}`);
  } else {
    // defer to whatever handler was registered before this one
    next(message, options);
  }
});

The handler function takes the following arguments:

  • message - The message received from the deprecation call.
  • options - An object passed in with the deprecation call containing additional information including:
    • id - An id of the deprecation in the form of package-name.specific-deprecation.
    • until - The Ember version number the feature and deprecation will be removed in.
  • next - A function that calls into the previously registered handler.

registerWarnHandler (handler) public

Module: @ember/debug

Defined in packages/@ember/debug/lib/warn.ts:24

Available since v2.1.0 

import { registerWarnHandler } from '@ember/debug';
handler
Function
A function to handle warnings.

Allows for runtime registration of handler functions that override the default warning behavior. Warnings are invoked by calls made to @ember/debug/warn. The following example demonstrates its usage by registering a handler that does nothing overriding Ember's default warning behavior.

1
2
3
4

import { registerWarnHandler } from '@ember/debug';

// next is not called, so no warnings get the default behavior
registerWarnHandler(() => {});

The handler function takes the following arguments:

  • message - The message received from the warn call.
  • options - An object passed in with the warn call containing additional information including:
    • id - An id of the warning in the form of package-name.specific-warning.
  • next - A function that calls into the previously registered handler.

runInDebug (func) public

Module: @ember/debug

Defined in packages/@ember/debug/index.ts:259

Available since v1.5.0 

import { runInDebug } from '@ember/debug';
func
Function
The function to be executed.

Run a function meant for debugging.

Calls to this function are removed from production builds, so they can be freely added for documentation and debugging purposes without worries of incuring any performance penalty.

1
2
3
4
5
6
7
8
9
10

import Component from '@ember/component';
import { runInDebug } from '@ember/debug';

runInDebug(() => {
  Component.reopen({
    didInsertElement() {
      console.log("I'm happy");
    }
  });
});

warn (message, test, options) public

Module: @ember/debug

Defined in packages/@ember/debug/lib/warn.ts:71

Available since v1.0.0 

import { warn } from '@ember/debug';
message
String
A warning to display.
test
Boolean
An optional boolean. If falsy, the warning will be displayed.
options
Object
An object that can be used to pass a unique `id` for this warning. The `id` can be used by Ember debugging tools to change the behavior (raise, log, or silence) for that specific warning. The `id` should be namespaced by dots, e.g. "ember-debug.feature-flag-with-features-stripped"

Display a warning with the provided message.

  • In a production build, this method is defined as an empty function (NOP). Uses of this method in Ember itself are stripped from the ember.prod.js build.
1
2
3
4
5
6
7

import { warn } from '@ember/debug';
import tomsterCount from './tomster-counter'; // a module in my project

// Log a warning if we have more than 3 tomsters
warn('Too many tomsters!', tomsterCount <= 3, {
  id: 'ember-debug.too-many-tomsters'
});