ember-modifier

What is ember-modifier?

The ember-modifier package provides a way to create reusable, composable, and encapsulated behavior for DOM elements in Ember.js applications. It allows developers to define custom modifiers that can be applied to elements in templates, enabling a clean separation of concerns and enhancing code maintainability.

What are ember-modifier's main functionalities?

Creating a Simple Modifier

This feature demonstrates how to create a simple modifier that focuses an input element when it is inserted into the DOM. The `focusInput` modifier is defined and then applied to an input element in a template.

```javascript
// app/modifiers/focus-input.js
import { modifier } from 'ember-modifier';

export default modifier(function focusInput(element) {
  element.focus();
});

// Usage in a template
<input {{focus-input}} />
```

Modifier with Arguments

This feature shows how to create a modifier that accepts arguments. The `setAttribute` modifier takes an attribute name and value as arguments and sets the attribute on the element.

```javascript
// app/modifiers/set-attribute.js
import { modifier } from 'ember-modifier';

export default modifier(function setAttribute(element, [attribute, value]) {
  element.setAttribute(attribute, value);
});

// Usage in a template
<div {{set-attribute 'data-test' 'example'}}></div>
```

Modifier with Cleanup

This feature illustrates how to create a modifier that adds an event listener to an element and cleans up the listener when the element is removed from the DOM. The `addEventListener` modifier adds a specified event listener and returns a cleanup function to remove the listener.

```javascript
// app/modifiers/add-event-listener.js
import { modifier } from 'ember-modifier';

export default modifier(function addEventListener(element, [event, handler]) {
  element.addEventListener(event, handler);

  return () => {
    element.removeEventListener(event, handler);
  };
});

// Usage in a template
<button {{add-event-listener 'click' this.handleClick}}>Click me</button>
```

Other packages similar to ember-modifier

ember-on-modifier

The ember-on-modifier package provides a simple way to add event listeners to elements in Ember.js templates using the `{{on}}` modifier. It is similar to the `addEventListener` feature of ember-modifier but is more focused on handling events in a declarative manner. While ember-on-modifier is great for straightforward event handling, ember-modifier offers more flexibility for creating complex and reusable behaviors.

README

ember-modifier

This addon provides an API for authoring element modifiers in Ember. It mirrors Ember's helper API, with variations for writing both simple function-based modifiers and more complicated class-based modifiers.

• Compatibility
  • TypeScript
• Installation
• Philosophy
  • Whoa whoa whoa, hold on, what's a "side effect"?
  • Managing "side effects" effectively
  • Should modifiers always be self-contained?
• Usage
  • Function-Based Modifiers
    • Generating a Function-Based Modifier
    • Example without Cleanup
    • Example with Cleanup
  • Class-Based Modifiers
    • Generating a Class Modifier
    • Example without Cleanup
    • Example with Cleanup
    • Example with Service Injection
    • API
• TypeScript
  • The Signature type
  • Examples with TypeScript
    • Function-based modifier
    • Class-based
  • Additional reading
• API Differences
  • API differences from ember-functional-modifiers
  • API differences from ember-class-based-modifier
  • API differences from ember-oo-modifiers
• History
• Contributing
• License

Compatibility

• Ember.js v3.24 or above
• Ember CLI v2.13 or above
• Node.js v12 or above

TypeScript

This project follows the current draft of the Semantic Versioning for TypeScript Types proposal.

• Currently supported TypeScript versions: v4.2, v4.3, v4.4, v4.5, and v4.6
• Compiler support policy: simple majors
• Public API: all published types not in a -private module are public

Installation

ember install ember-modifier

Philosophy

Modifiers are a basic primitive for interacting with the DOM in Ember. For example, Ember ships with a built-in modifier, {{on}}:

<button {{on "click" @onClick}}>
  {{@text}}
</button>

All modifiers get applied to elements directly this way (if you see a similar value that isn't in an element, it is probably a helper instead), and they are passed the element when applying their effects.

Conceptually, modifiers take tracked, derived state, and turn it into some sort of side effect related in some way to the DOM element they are applied to.

Whoa whoa whoa, hold on, what's a "side effect"?

A "side effect" is something that happens in programming all the time. Here's an example of one in an Ember component that attempts to make a button like in the first example, but without modifiers:

// 🛑 DO NOT COPY THIS 🛑
import Component from '@glimmer/component';

export default class MyButton extends Component {
  get setupEventHandler() {
    document.querySelector('#my-button').addEventListener(this.args.onClick);

    return undefined;
  }
}

<button id="#my-button">
  {{this.setupEventHandler}}

  {{@text}}
</button>

We can see by looking at the setupEventListener getter that it isn't actually returning a value. Instead, it always returns undefined. However, it also adds the @onClick argument as an event listener to the button in the template when the getter is run, as the template is rendering, which is a side effect

• it is an effect of running the code that doesn't have anything to do with the "main" purpose of that code, in this case to return a dynamically computed value. In fact, this code doesn't compute a value at all, so this component is misusing the getter in order to run its side effect whenever it is rendered in the template.

Unmanaged side effects can make code very difficult to reason about, since any function could be updating a value elsewhere. In fact, the code above is very buggy:

1. If the @onClick argument ever changes, it won't remove the old event listener, it'll just keep adding new ones.
2. It won't remove the old event listener when the component is removed.
3. It uses a document element selector that may not be unique, and it has no guarantee that the element will exist when it runs.
4. It will run in Fastboot/Server Side Rendering, where no DOM exists at all, and it'll throw errors because of this.

However, there are lots of times where its difficult to write code that doesn't have side effects. Sometimes it would mean having to rewrite a large portion of an application. Sometimes, like in the case of modifying DOM, there isn't a clear way to do it at all with just getters and components.

This is where modifiers come in. Modifiers exist as a way to bridge the gap between derived state and side effects in way that is contained and consistent, so that users of a modifier don't have to think about them.

Managing "side effects" effectively

Let's look again at our original example:

<button {{on "click" @onClick}}>
  {{@text}}
</button>

We can see pretty clearly from this template that Ember will:

1. Create a <button> element
2. Append the contents of the @text argument to that button
3. Add a click event handler to the button that runs the @onClick argument

If @text or @onClick ever change, Ember will keep everything in sync for us. We don't ever have to manually set element.textContent or update anything ourselves. In this way, we can say the template is declarative - it tells Ember what we want the output to be, and Ember handles all of the bookkeeping itself.

Here's how we could implement the {{on}} modifier so that it always keeps things in sync correctly:

import { modifier } from 'ember-modifier';

export default modifier((element, [eventName, handler]) => {
  element.addEventListener(eventName, handler);

  return () => {
    element.removeEventListener(eventName, handler);
  }
});

Here, we setup the event listener using the positional parameters passed to the modifier. Then, we return a destructor - a function that undoes our setup, and is effectively the opposite side effect. This way, if the @onClick handler ever changes, we first teardown the first event listener we added - leaving the element in its original state before the modifier ever ran - and then setup the new handler.

This is what allows us to treat the {{on}} modifier as if it were just like the {{@text}} value we put in the template. While it is side effecting, it knows how to setup and teardown that side effect and manage its state. The side effect is contained - it doesn't escape into the rest of our application, it doesn't cause other unrelated changes, and we can think about it as another piece of declarative, derived state. Just another part of the template!

In general, when writing modifiers, especially general purpose/reusable modifiers, they should be designed with this in mind. Which specific effects are they trying to accomplish, how to manage them effectively, and how to do it in a way that is transparent to the user of the modifier.

Usage

This addon does not provide any modifiers out of the box. Instead, this library allows you to write your own. There are two ways to write modifiers:

1. Function-based modifiers
2. Class-based modifiers

These are analogous to Ember's Helper APIs, helper and Helper.

Function-Based Modifiers

modifier is an API for writing simple modifiers. For instance, you could implement Ember's built-in {{on}} modifier like so with modifier:

// /app/modifiers/on.js
import { modifier } from 'ember-modifier';

export default modifier((element, [eventName, handler]) => {
  element.addEventListener(eventName, handler);

  return () => {
    element.removeEventListener(eventName, handler);
  }
});

Function-based modifiers consist of a function that receives:

1. The element
2. An array of positional arguments
3. An object of named arguments

modifier((element, positional, named) => { /* */ });

This function runs the first time when the element the modifier was applied to is inserted into the DOM, and it autotracks while running. Any tracked values that it accesses will be tracked, including the arguments it receives, and if any of them changes, the function will run again.¹

The modifier can also optionally return a destructor. The destructor function will be run just before the next update, and when the element is being removed entirely. It should generally clean up the changes that the modifier made in the first place.

Generating a Function-Based Modifier

To create a modifier (and a corresponding integration test), run:

ember g modifier scroll-top

Example without Cleanup

For example, if you wanted to implement your own scrollTop modifier (similar to this), you may do something like this:

// app/modifiers/scroll-top.js
import { modifier } from 'ember-modifier';

export default modifier((element, [scrollPosition]) => {
  element.scrollTop = scrollPosition;
})

<div class="scroll-container" {{scroll-top @scrollPosition}}>
  {{yield}}
</div>

Example with Cleanup

If the functionality you add in the modifier needs to be torn down when the element is removed, you can return a function for the teardown method.

For example, if you wanted to have your elements dance randomly on the page using setInterval, but you wanted to make sure that was canceled when the element was removed, you could do:

// app/modifiers/move-randomly.js
import { modifier } from 'ember-modifier';

const { random, round } = Math;

export default modifier(element => {
  const id = setInterval(() => {
    const top = round(random() * 500);
    const left = round(random() * 500);
    element.style.transform = `translate(${left}px, ${top}px)`;
  }, 1000);

  return () => clearInterval(id);
});

<button {{move-randomly}}>
  {{yield}}
</button>

Class-Based Modifiers

Sometimes you may need to do something more complicated than what can be handled by function-based modifiers. For instance:

1. You may need to inject services and access them
2. You may need fine-grained control of updates, either for performance or convenience reasons, and don't want to teardown the state of your modifier every time only to set it up again.
3. You may need to store some local state within your modifier.

In these cases, you can use a class-based modifier instead. Here's how you would implement the {{on}} modifier with a class:

import Modifier from 'ember-modifier';
import { registerDestructor } from '@ember/destroyable';

function cleanup(instance: OnModifier) {
  let { element, event, handler } = instance;

  if (element && event && handler) {
    element.removeEventListener(event, handler);

    instance.element = null;
    instance.event = null;
    instance.handler = null;
  }
}

export default class OnModifier extends Modifier {
  element = null;
  event = null;
  handler = null;

  modify(element, [event, handler]) {
    this.addEventListener(element, event, handler);
    registerDestructor(this, cleanup)
  }

  // methods for reuse
  addEventListener = (element, event, handler) => {
    // Store the current element, event, and handler for when we need to remove
    // them during cleanup.
    this.element = element;
    this.event = event;
    this.handler = handler;

    element.addEventListener(event, handler);
  };
}

While this is slightly more complicated than the function-based version, but that complexity comes along with much more control.

As with function-based modifiers, the lifecycle hooks of class modifiers are tracked. When they run, then any values they access will be added to the modifier, and the modifier will update if any of those values change.

Generating a Class Modifier

To create a modifier (and a corresponding integration test), run:

ember g modifier scroll-top --class

Example without Cleanup

For example, let's say you want to implement your own {{scroll-position}} modifier (similar to this).

This modifier can be attached to any element and accepts a single positional argument. When the element is inserted, and whenever the argument is updated, it will set the element's scrollTop property to the value of its argument.

(Note that this example does not require the use of a class, and could be implemented equally well with a function-based modifier!)

// app/modifiers/scroll-position.js
import Modifier from 'ember-modifier';

export default class ScrollPositionModifier extends Modifier {
  modify(element, [scrollPosition], { relative }) {
    if(relative) {
      element.scrollTop += scrollPosition;
    } else {
      element.scrollTop = scrollPosition;
    }
  }
}

Usage:

{{!-- app/components/scroll-container.hbs --}}

<div
  class="scroll-container"
  style="width: 300px; heigh: 300px; overflow-y: scroll"
  {{scroll-position this.scrollPosition relative=false}}
>
  {{yield this.scrollToTop}}
</div>

// app/components/scroll-container.js

import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';

export default class ScrollContainerComponent extends Component {
  @tracked scrollPosition = 0;

  @action scrollToTop() {
    this.scrollPosition = 0;
  }
}

{{!-- app/templates/application.hbs --}}

<ScrollContainer as |scroll|>
  A lot of content...

  <button {{on "click" scroll}}>Back To Top</button>
</ScrollContainer>

Example with Cleanup

If the functionality you add in the modifier needs to be torn down when the modifier is removed, you can use registerDestructor from @ember/destroyable.

For example, if you want to have your elements dance randomly on the page using setInterval, but you wanted to make sure that was canceled when the modifier was removed, you could do this:

// app/modifiers/move-randomly.js

import Modifier from 'ember-modifier';
import { registerDestructor } from '@ember/destroyable'

const { random, round } = Math;
const DEFAULT_DELAY = 1000;

function cleanup(instance) {
  if (instance.setIntervalId !== null) {
    clearInterval(instance.setIntervalId);
    instance.setIntervalId = null;
  }
}

export default class MoveRandomlyModifier extends Modifier {
  element = null;
  setIntervalId = null;

  constructor(owner, args) {
    super(owner, args);
    registerDestructor(this, cleanup);
  }

  modify(element, _, { delay }) {
    // Save off the element the first time for convenience with #moveElement
    if (!this.element) {
      this.element = element;
    }

    // Reset from any previous state.
    cleanup(this);

    this.setIntervalId = setInterval(this.#moveElement, delay ?? DEFAULT_DELAY);
  }

  #moveElement = (element) => {
    let top = round(random() * 500);
    let left = round(random() * 500);
    this.element.style.transform = `translate(${left}px, ${top}px)`;
  };
}

Usage:

<div {{move-randomly}}>
  Catch me if you can!
</div>

Example with Service Injection

You can also use services into your modifier, just like any other class in Ember.

For example, suppose you wanted to track click events with ember-metrics:

// app/modifiers/track-click.js

import { inject as service } from '@ember/service';
import Modifier from 'ember-modifier';
import { registerDestructor } from '@ember/destroyable';

function cleanup(instance) {
  instance.element?.removeEventListener('click', instance.onClick, true);
}

export default class TrackClick extends Modifier {
  @service metrics;

  constructor(owner, args) {
    super(owner, args);
    registerDestructor(this, this.cleanup);
  }

  modify(element, [eventName], options) {
    this.element = element;
    this.eventName = eventName;
    this.options = options;

    this.cleanup();
    element.addEventListener('click', this.onClick, true);
  }

  onClick = () => {
    this.metrics.trackEvent(this.eventName, this.options);
  };
}

Usage:

<button {{track-click "like-button-click" page="some page" title="some title"}}>
  Click Me!
</button>

API

constructor(owner, args)

Constructor for the modifier. You must call super(...arguments) before performing other initialization.

modify(element, positionalArgs, namedArgs)

The primary hook for running a modifier. It gets called when the modifier is installed on the element, and any time any tracked state it uses changes. That tracked state can be from its arguments, which are auto-tracked, or from any other kind of tracked state, including but not limited to state on injected services.

Deprecated

These fields and hooks exist on the class until 4.0. You should migrate away from them to use modify() and the @ember/destroyable API as appropriate. (See MIGRATIONS.md).

element

The DOM element the modifier is attached to.

args: { positional: Array, named: Object }

The arguments passed to the modifier. args.positional is an array of positional arguments, and args.named is an object containing the named arguments. (See below for a discussion of the types.)

isDestroying

true if the modifier is in the process of being destroyed, or has already been destroyed.

isDestroyed

true if the modifier has already been destroyed.

didReceiveArguments()

Called when the modifier is installed and anytime the arguments are updated.

didUpdateArguments()

Called anytime the arguments are updated but not on the initial install. Called before didReceiveArguments.

didInstall()

Called when the modifier is installed on the DOM element. Called after didReceiveArguments.

willRemove()

Called when the DOM element is about to be destroyed; use for removing event listeners on the element and other similar clean-up tasks. Deprecated since 2.0. Prefer willDestroy().

willDestroy()

Called when the modifier itself is about to be destroyed; use for teardown code. Called after willRemove.

Lifecycle Summary

Note: this table only applies to the legacy lifecycle hooks. modify() is mutually exclusive with all hooks except the constructor, and runs on installation and update, but not remove.

Key:

• (#) Indicates the order of invocation for the lifecycle event.
• ❌ Indicates that the method is not invoked for a given lifecycle / property is not available.
• ✔️ Indicates that the property is available during the invocation of the given method.

hook name	Create	Install	Update	Remove	this.element	this.args
constructor()	✔️	❌	❌	❌	❌	after super()
didUpdateArguments()	❌	❌	(1)	❌	✔️	✔️
didReceiveArguments()	❌	(1)	(2)	❌	✔️	✔️
didInstall()	❌	(2)	❌	❌	✔️	✔️
willRemove()	❌	❌	❌	(1)	✔️	✔️
willDestroy()	❌	❌	❌	(2)	✔️	✔️

TypeScript

Both the function- and class-based APIs can be used with TypeScript!

Before checking out the Examples with Typescript below, there is an important caveat you should understand about type safety!

There are, today, two basic approaches you can take to dealing with your modifier's arguments and element in a type safe way:

1. You can use a type definition which specifies those for the outside world, relying on tooling like Glint to check that the invocation is correct, and treat input as safe accordingly.
2. You can provide the minimal public interface which all modifiers conform to, and do runtime type checking with assert calls to make your internal implementation safe.

If you have a code base which is strictly typed from end to end, including with template type checking via Glint, then (1) is a great choice. If you have a mixed code base, or are publishing an addon for others to use, then it's usually best to do both (1) and (2)!

To handle runtime checking, for non-type-checked templates (including projects not yet using Glint or supporting external callers), you should act as though the arguments passed to your modifier can be anything. They’re typed as unknown by default, which means by default TypeScript will require you to work out the type passed to you at runtime. For example, with the ScrollPositionModifier shown above, you can combine TypeScript’s type narrowing with the default types for the class to provide runtime errors if the caller passes the wrong types, while providing safety throughout the rest of the body of the modifier. Here, modify would be guaranteed to have the correct types for scrollPosition and relative:

import Modifier from 'ember-modifier';
import { assert } from '@ember/debug';

export class ScrollPositionModifier extends ClassBasedModifier {
  modify(element, [scrollPosition], { relative }) {
    assert(,
      `first argument to 'scroll-position' must be a number, but ${scrollPosition} was ${typeof scrollPosition}`,
      typeof scrollPosition === "number"
    );

    assert(
      `'relative' argument to 'scroll-position' must be a boolean, but ${relative} was ${typeof relative}`,
      typeof relative === "boolean"
    );

    if (relative) {
      element.scrollTop += scrollPosition;
    } else {
      element.scrollTop = scrollPosition;
    }
  }
}

If you were writing for a fully-typed context, you can define your Modifier with a Signature interface, similar to the way you would define your signature for a Glimmer Component:

// app/modifiers/scroll-position.ts
import Modifier from 'ember-modifier';

interface ScrollPositionModifierSignature {
  Args: {
    Positional: [number];
    Named: {
      relative: boolean;
    };
  };
}

export default class ScrollPositionModifier
    extends Modifier<ScrollPositionModifierSignature> {
  modify(element, [scrollPosition], { relative }) {
    if (relative) {
      element.scrollTop += scrollPosition;
    } else {
      element.scrollTop = scrollPosition;
    }
  }
}

Besides supporting integration with Glint, this also provides nice hooks for documentation tooling. Note, however, that it can result in much worse feedback in tests or at runtime if someone passes the wrong kind of arguments to your modifier and you haven't included assertions: users who pass the wrong thing will just have the modifier fail. For example, if you fail to pass the positional argument, scrollPosition would simply be undefined, and then element.scrollTop could end up being set to NaN. Whoops! For that reason, if your modifier will be used by non-TypeScript consumers, you should both publish the types for it and add dev-time assertions:

// app/modifiers/scroll-position.ts
import Modifier from 'ember-modifier';

interface ScrollPositionModifierSignature {
  Args: {
    Positional: [scrollPosition: number];
    Named: {
      relative: boolean;
    };
  };
  Element: Element; // not required: it'll be set by default
}

export default class ScrollPositionModifier
    extends Modifier<ScrollPositionModifierSignature> {
  modify(element, [scrollPosition], { relative }) {
    assert(,
      `first argument to 'scroll-position' must be a number, but ${scrollPosition} was ${typeof scrollPosition}`,
      typeof scrollPosition === "number"
    );

    assert(
      `'relative' argument to 'scroll-position' must be a boolean, but ${relative} was ${typeof relative}`,
      typeof relative === "boolean"
    );

    if (relative) {
      element.scrollTop += scrollPosition;
    } else {
      element.scrollTop = scrollPosition;
    }
  }
}

The Signature type

The Signature for a modifier is the combination of the positional and named arguments it receives and the element to which it may be applied.

interface Signature {
  Args: {
    Named: {
      [argName: string]: unknown;
    };
    Positional: unknown[];
  };
  Element: Element;
}

When writing a signature yourself, all of those are optional: the types for modifiers will fall back to the correct defaults of Element, an object for named arguments, and an array for positional arguments. You can apply a signature when defining either a function-based or a class-based modifier.

In a function-based modifier, the callback arguments will be inferred from the signature, so you do not need to specify the types twice:

interface MySignature {
  Element: HTMLMediaElement;
  Args: {
    Named: {
      when: boolean;
    };
    Positional: [];
  };
}

const play = modifier<MySignature>((el, _, { when: shouldPlay }) => {
  if (shouldPlay) {
    el.play();
  } else {
    el.pause();
  }
})

You never need to specify a signature in this way for a function-based modifier: you can simply write the types inline instead:

const play = modifier(
  (el: HTMLMediaElement, _: [], { when: shouldPlay }: { when: boolean}) => {
    if (shouldPlay) {
      el.play();
    } else {
      el.pause();
    }
  }
);

However, the explicit modifier<Signature>(...) form is tested to keep working, since it can be useful for documentation!

The same basic approach works with a class-based modifier:

interface MySignature {
  // ...
}

export default class MyModifier extends Modifier<MySignature> {
  // ...
}

In that case, the element and args will always have the right types throughout the body. Since the type of args in the constructor are derived from the signature, you can use the ArgsFor type helper to avoid having to write the type out separately:

import Modifier, { ArgsFor } from 'ember-modifier';

interface MySignature {
  // ...
}

export default class MyModifier extends Modifier<MySignature> {
  constructor(owner: unknown, args: ArgsFor<MySignature>) {
    // ...
  }
}

ArgsFor isn't magic: it just takes the Args from the Signature you provide and turns it into the right shape for the constructor: the Named type ends up as the named field and the Positional type ends up as the type for args.positional, so you could write it out yourself if you preferred:

import Modifier from 'ember-modifier';

interface MySignature {
  // ...
}

export default class MyModifier extends Modifier<MySignature> {
  constructor(
    owner: unknown,
    args: {
      named: MySignature['Args']['Named'];
      positional: MySignature['Args']['Positional'];
    }
  ) {
    // ...
  }
}

Examples with TypeScript

Function-based modifier

Let’s look at a variant of the move-randomly example from above, implemented in TypeScript, and now requiring a named argument, the maximum offset. Using the recommended combination of types and runtime type-checking, it would look like this:

// app/modifiers/move-randomly.js
import { modifier } from 'ember-modifier';
import { assert } from '@ember/debug';

const { random, round } = Math;

export default modifier(
  (element: HTMLElement, _: [], named: { maxOffset: number }
) => {
  assert(
    'move-randomly can only be installed on HTML elements!',
    element instanceof HTMLElement
  );

  const { maxOffset } = named;
  assert(
    `The 'max-offset' argument to 'move-randomly' must be a number, but was ${typeof maxOffset}`,
    typeof maxOffset === "number"
  );

  const id = setInterval(() => {
    const top = round(random() * maxOffset);
    const left = round(random() * maxOffset);
    element.style.transform = `translate(${left}px, ${top}px)`;
  }, 1000);

  return () => clearInterval(id);
});

A few things to notice here:

1. TypeScript correctly infers the base types of the arguments for the function passed to the modifier; you don't need to specify what element or positional or named are unless you are doing like we are in this example and providing a usefully more-specific type to callers.

2. If we returned a teardown function which had the wrong type signature, that would also be an error.

   If we return a value instead of a function, for example:

   export default modifier((element, _, named) => {
     // ...
   
     return id;
   });
   

   TypeScript will report:

   Type 'Timeout' is not assignable to type 'void | Teardown'.
   

   Likewise, if we return a function with the wrong signature, we will see the same kinds of errors. If we expected to receive an argument in the teardown callback, like this:

   export default modifier((element, _, named) => {
     // 
   
     return (interval: number) => clearTimeout(interval);
   });
   

   TypeScript will report:

   Type '(interval: number) => void' is not assignable to type 'void | Teardown'.
   

Class-based

To support correctly typing args in the constructor for the case where you do runtime type checking, we supply an ArgsFor type utility. (This is useful because the Signature type, matching Glimmer Component and other "invokable" items in Ember/Glimmer, has capital letters for the names of the types, while args.named and args.positional are lower-case.) Here’s how that would look with a fully typed modifier that alerts "This is a typesafe modifier!" an amount of time after receiving arguments that depends on the length of the first argument and an optional multiplier (a nonsensical thing to do, but one that illustrates a fully type-safe class-based modifier):

import Modifier, { ArgsFor, PositionalArgs, NamedArgs } from 'ember-modifier';
import { assert } from '@ember/debug';

interface NeatSignature {
  Args: {
    Named: {
      multiplier?: number;
    };
    Positional: [string];
  }
}


function cleanup(instance: Neat) => {
  if (instance.interval) {
    clearInterval(instance.interval);
  }
}

export default class Neat extends Modifier<NeatSignature> {
  interval?: number;

  constructor(owner: unknown, args: ArgsFor<NeatSignature>) {
    super(owner, args);
    registerDestructor(this, cleanup);
  }

  modify(
    element: Element,
    [lengthOfInput]: PositionalArgs<NeatSignature>,
    { multiplier }: NamedArgs<NeatSignature>
  ) {
    assert(
  	  `positional arg must be 'string' but was ${typeof lengthOfInput}`,
  	  typeof lengthOfInput === 'string'
  	);

    assert(
    	`'multiplier' arg must be a number but was ${typeof multiplier}`,
    	multiplier ? typeof multiplier === "number" : true
    );

    multiplier = modifier ?? 1000;

    let updateTime = multiplier * lengthOfInput;
    this.interval = setInterval(() => {
      element.innerText =
        `Behold, a type safe modifier moved after ${updateTime / 1000}s`;
    }, updateTime)
  }
}

Additional reading

See this pull request comment for background discussion about using TypeScript with your Modifiers.

API Differences

API differences from ember-functional-modifiers

• Renamed package to ember-modifier
• Renamed makeFunctionalModifier to modifier, and to a named export instead of the default
• Removed isRemoving flag from modifier destructors. In cases where fine-grained control over the lifecycle is needed, class modifiers should be used instead.
• Removed service injection from functional modifiers. In cases where services are needed, class modifiers should be used instead.

API differences from ember-class-based-modifier

• Renamed package to ember-modifier
• Removed classic API

API differences from ember-oo-modifiers

• Renamed package to ember-modifier.
• Removed classic API
• No Modifier.modifier() function.
• Arguments, both positional and named, are available on this.args.
• Named arguments do not become properties on the modifier instance.
• Arguments are not passed to life-cycle hooks.
• Renamed didInsertElement to didInstall and willDestroyElement to willRemove. This is to emphasize that when the modifier is installed or removed, the underlying element may not be freshly inserted or about to go away. Therefore, it is important to perform clean-up work in the willRemove to reverse any modifications you made to the element.
• Changed life-cycle hook order: didReceiveArguments fires before didInstall, and didUpdateArguments fires before didReceiveArguments, mirroring the classic component life-cycle hooks ordering.
• Added willDestroy, isDestroying and isDestroyed with the same semantics as Ember objects and Glimmer components.

History

This addon is the next iteration of both ember-class-based-modifier and ember-functional-modifiers. Some breaking changes to the APIs have been made. For a list of differences, see the API differences section.

Huge thanks to @sukima and @spencer516 for their contributions! This project is based on their work, and wouldn't have been possible without them!

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.

Footnotes

1. As with autotracking in general, “changes” here actually means that the tracked property was set—even if it was set to the same value. This is because autotracking does not cache the values of properties, only the last time they changed. See this blog post for a deep dive on how it works! ↩