ember-macro-helpers
Ember macro helpers for making your own fancy macros!
Check out the following projects to see this addon in use:
- https://github.com/kellyselden/ember-awesome-macros
- https://github.com/ember-decorators/ember-decorators
- https://github.com/stefanpenner/ember-moment
- https://github.com/cibernox/ember-cpm
Compatibility
- Ember.js v3.4 or above
- Ember CLI v2.13 or above
- Node.js v8 or above
Installation
ember install ember-macro-helpers
Usage
import nameOfMacro from 'ember-macro-helpers/name-of-macro';
// or
import { nameOfMacro } from 'ember-macro-helpers';
Contents
API
computed
createClassComputed
curriedComputed
lazyComputed
lazyCurriedComputed
literal
raw
reads
writable
computed
computed
behaves like Ember.computed
with some extra benefits.
It will pass you resolved values:
;; ;
You can compose using any of Ember's built-in macros:
;;; ;
or you can compose using a macro library like ember-awesome-macros
:
;;; ;
It respects enumerable helpers:
;; ;
It resolves property expansion for you:
;; ;
This is also your best friend if you want to make your own macros that support composing out-of-the-box.
For example, here is an implementation of a macro that adds two numbers together:
// app/macros/add.js; { // The incoming keys can be key strings, raw values, or other macros. // It makes no difference to you. // `computed` will resolve them for you. return ;}
Then you can use it like this:
;; ;
createClassComputed
This creates a class-based computed. This is useful when not the value, but the key being watched is variable. It rewrites your computed property when needed.
See ember-classy-computed for the inspiration source.
If you want an array macro that will respond when someone changes the array property they want to watch:
// app/macros/filter-by.js;; // the first param is the observer list // it refers to incoming keys // the bool is whether a value change should recreate the macro // the array key false // the array property is dynamic, and is responsible for the macro being rewritten true // any static properties after the last dynamic property are optional // you could leave this off if you want false // the second param is the callback function where you create your computed property // it is passed in the values of the properties you marked true above { // when `key` changes, we need to watch a new property on the array // since our computed property is now invalid, we need to create a new one return ; };
And then we consume this macro like normal:
;;;; ;
curriedComputed
This is a shorthand version of computed
. It allows you to create macros like this:
// app/macros/add.js; { // At this point, the keys no long matter. // You are provided the resolved values for you to perform your operation. return value1 + value2;};
lazyComputed
This is the lazy resolving version of computed
. The difference is instead of being provided the resolved values, you are provided the unresolved keys and a resolving function. This is useful if you want to optimize your macros and have early returns without calculating every key eagerly.
The API differs only slightly from computed
:
// app/macros/and.js; { return ;}
lazyCurriedComputed
This is the combination of lazyComputed
and curriedComputed
.
literal
alias for raw
raw
This allows you to escape string literals to be used in macros.
Normally, a string means it will look up the property on the object context:
;; ;
But if you just want to use the value without making an object property, you can use the raw
macro:
;;; ;
The usefulness is more apparent when using complex macros, for example, when using the string split
macro from ember-awesome-macros
:
;;; ;
reads
alias for writable
writable
This is a setting API for read-only macros.
Given the following read-only macro called sum
:
; { return readOnly;}
and its usage:
key1: 1key2: 2result:
If you try and set result
, you will get a read-only exception.
If you want to bring back the setting functionality, you can wrap it in the writable
macro:
key1: 1key2: 2result:
Now, setting result
will remove the macro and replace it with your value.
If you want to do something unique when setting, you can provide a set callback:
key1: 1key2: 2result: // setting this will not overwrite your macro
or:
key1: 1key2: 2result: // same as above, but shorthand
Setting result
here will not remove your macro, but will update result
with the return value.
Custom macros
The addon provides a way of creating your own custom macros. The easiest way is to use the blueprint generator:
ember generate macro my-custom-macro
This will generate an example macro and its associated test. The comments in these files will get you started.
More explanation is given in the introduction video.
Test helpers
This comes with a compute
helper. Here is a sample usage:
;; // ... ;
View all the possible ways to use here.
Contributing
See the Contributing guide for details.
License
This project is licensed under the MIT License.