ember-compatibility-helpers

What is ember-compatibility-helpers?

The ember-compatibility-helpers package provides utilities to help manage compatibility with different versions of Ember.js. It allows developers to write code that can adapt to different versions of Ember, making it easier to maintain and upgrade applications.

What are ember-compatibility-helpers's main functionalities?

Version Checks

This feature allows you to check the current version of Ember and conditionally execute code based on the version. The `gte` function checks if the current Ember version is greater than or equal to the specified version.

import { gte } from 'ember-compatibility-helpers';

if (gte('3.8.0')) {
  // Code for Ember 3.8.0 and above
} else {
  // Code for versions below Ember 3.8.0
}

Feature Flags

This feature allows you to check if a specific feature flag is enabled in the current Ember environment. This is useful for enabling or disabling features based on the environment or configuration.

import { isFeatureEnabled } from 'ember-compatibility-helpers';

if (isFeatureEnabled('some-feature')) {
  // Code for when the feature is enabled
} else {
  // Code for when the feature is disabled
}

Deprecation Warnings

This feature allows you to issue deprecation warnings in your code. The `deprecate` function helps you inform users of your addon or application about deprecated methods or features, providing a clear path for upgrades.

import { deprecate } from 'ember-compatibility-helpers';

deprecate('This method is deprecated, use newMethod instead', false, {
  id: 'my-addon.old-method',
  until: '4.0.0',
  url: 'http://example.com/deprecations/my-addon.old-method'
});

Other packages similar to ember-compatibility-helpers

ember-cli-deprecation-workflow

The ember-cli-deprecation-workflow package helps manage deprecations in Ember applications. It allows you to control which deprecations are shown and provides tools to handle deprecations during upgrades. Compared to ember-compatibility-helpers, it focuses more on managing deprecation warnings rather than version checks and feature flags.

ember-try

The ember-try package allows you to test your Ember application against multiple versions of Ember and other dependencies. It helps ensure compatibility across different versions. While ember-compatibility-helpers provides runtime checks and feature flags, ember-try focuses on testing and CI workflows.

README

ember-compatibility-helpers

Provides flags for features in Ember, allowing you to write code that will work with whatever version the consuming application is on. This addon is intended to help addon authors write backwards/forwards compatibility code.

The flags are replaced at build time with boolean literals (true or false) by a Babel transform. When ran through a minifier (with dead code elimination) the entire section will be stripped, meaning that the section of code which is not used will not be added to production builds - zero cost compatibility!

Installation

ember install ember-compatibility-helpers

Available Flags

import {
  // General functions for checking against Ember version
  gte,
  lte,

  // Flags for specific Ember functionality
  HAS_UNDERSCORE_ACTIONS,
  HAS_MODERN_FACTORY_INJECTIONS,

  IS_GLIMMER_2,
  IS_RECORD_DATA,

  SUPPORTS_FACTORY_FOR,
  SUPPORTS_GET_OWNER,
  SUPPORTS_SET_OWNER,
  SUPPORTS_NEW_COMPUTED,
  SUPPORTS_INVERSE_BLOCK,
  SUPPORTS_CLOSURE_ACTIONS,
  SUPPORTS_UNIQ_BY_COMPUTED
} from 'ember-compatibility-helpers';

More welcome, open an issue or a PR!

Version Identifiers

Version strings passed to version checker functions, such as gte or lte, must be fully qualified versions. Version ranges or shorthands are not supported.

// Do this:
lte('3.13.0-beta.1')

// Not this:
lte('3.12'); // won't work!
lte('^3.12.0'); // won't work!

Example Usage

Function usage:

import Component from '@ember/component';
import { computed } from '@ember/object';

import { gte } from 'ember-compatibility-helpers';

export default Component.extend({
  foo: computed({
    get() {
      return 'bar';
    }
  }),

  baz: computed({
    get() {
      // checks version against ember-source
      if (gte('3.1.0')) {
        return this.foo;
      } else {
        return this.get('foo');
      }
    }
  }),
  
  boo() {
    if (gte('my-addon-name', '3.5.0-beta.3')) {
      return {};
    } else {
      return Ember.Object.create({});
    }
  }
});

Flag usage:

import Component from '@ember/component';
import { computed } from '@ember/object';

import { SUPPORTS_NEW_COMPUTED } from 'ember-compatibility-helpers';

function fooMacro() {
  if (SUPPORTS_NEW_COMPUTED) {
    return computed({
      get() {
        return this.get('foo');
      },

      set(key, value) {
        this.set('foo', value);
        return value
      }
    });
  } else {
    return computed(function(key, value) {
      if (arguments.length === 2) {
        this.set('foo', value);
        return value;
      }

      return this.get('foo');
    })
  }
}

export default Component.extend({
  bar: fooMacro()
});

Development

• git clone <repository-url> this repository
• cd ember-compatibility-helpers
• yarn

Running Tests

• npm test