UNPKG

6.42 kBTypeScriptView Raw
1declare module '@ember/-internals/glimmer/lib/helper' {
2 /**
3 @module @ember/component
4 */
5 import { FrameworkObject } from '@ember/object/-internals';
6 import type { Arguments, HelperManager } from '@glimmer/interfaces';
7 import type { DirtyableTag } from '@glimmer/validator';
8 export const RECOMPUTE_TAG: unique symbol;
9 type GetOr<T, K, Else> = K extends keyof T ? T[K] : Else;
10 type Args<S> = GetOr<S, 'Args', {}>;
11 type DefaultPositional = unknown[];
12 type Positional<S> = GetOr<Args<S>, 'Positional', DefaultPositional>;
13 type Named<S> = GetOr<Args<S>, 'Named', object>;
14 type Return<S> = GetOr<S, 'Return', unknown>;
15 export interface HelperFactory<T> {
16 isHelperFactory: true;
17 create(): T;
18 }
19 export interface HelperInstance<S> {
20 compute(positional: Positional<S>, named: Named<S>): Return<S>;
21 destroy(): void;
22 [RECOMPUTE_TAG]: DirtyableTag;
23 }
24 const IS_CLASSIC_HELPER: unique symbol;
25 export interface SimpleHelper<S> {
26 compute: (positional: Positional<S>, named: Named<S>) => Return<S>;
27 }
28 const SIGNATURE: unique symbol;
29 /**
30 Ember Helpers are functions that can compute values, and are used in templates.
31 For example, this code calls a helper named `format-currency`:
32
33 ```app/templates/application.hbs
34 <Cost @cents={{230}} />
35 ```
36
37 ```app/components/cost.hbs
38 <div>{{format-currency @cents currency="$"}}</div>
39 ```
40
41 Additionally a helper can be called as a nested helper.
42 In this example, we show the formatted currency value if the `showMoney`
43 named argument is truthy.
44
45 ```handlebars
46 {{if @showMoney (format-currency @cents currency="$")}}
47 ```
48
49 Helpers defined using a class must provide a `compute` function. For example:
50
51 ```app/helpers/format-currency.js
52 import Helper from '@ember/component/helper';
53
54 export default class extends Helper {
55 compute([cents], { currency }) {
56 return `${currency}${cents * 0.01}`;
57 }
58 }
59 ```
60
61 Each time the input to a helper changes, the `compute` function will be
62 called again.
63
64 As instances, these helpers also have access to the container and will accept
65 injected dependencies.
66
67 Additionally, class helpers can call `recompute` to force a new computation.
68
69 @class Helper
70 @extends CoreObject
71 @public
72 @since 1.13.0
73 */
74 export default interface Helper<S = unknown> {
75 /**
76 Override this function when writing a class-based helper.
77
78 @method compute
79 @param {Array} positional The positional arguments to the helper
80 @param {Object} named The named arguments to the helper
81 @public
82 @since 1.13.0
83 */
84 compute(positional: Positional<S>, named: Named<S>): Return<S>;
85 }
86 export default class Helper<S = unknown> extends FrameworkObject {
87 static isHelperFactory: boolean;
88 static [IS_CLASSIC_HELPER]: boolean;
89 /** @deprecated */
90 static helper: typeof helper;
91 [RECOMPUTE_TAG]: DirtyableTag;
92 private [SIGNATURE];
93 init(properties: object | undefined): void;
94 /**
95 On a class-based helper, it may be useful to force a recomputation of that
96 helpers value. This is akin to `rerender` on a component.
97
98 For example, this component will rerender when the `currentUser` on a
99 session service changes:
100
101 ```app/helpers/current-user-email.js
102 import Helper from '@ember/component/helper'
103 import { service } from '@ember/service'
104 import { observer } from '@ember/object'
105
106 export default Helper.extend({
107 session: service(),
108
109 onNewUser: observer('session.currentUser', function() {
110 this.recompute();
111 }),
112
113 compute() {
114 return this.get('session.currentUser.email');
115 }
116 });
117 ```
118
119 @method recompute
120 @public
121 @since 1.13.0
122 */
123 recompute(): void;
124 }
125 export function isClassicHelper(obj: object): boolean;
126 export const CLASSIC_HELPER_MANAGER:
127 | import('@glimmer/interfaces').Helper<object>
128 | import('@glimmer/manager').CustomHelperManager<object>;
129 class Wrapper<S = unknown> implements HelperFactory<SimpleHelper<S>> {
130 compute: (positional: Positional<S>, named: Named<S>) => Return<S>;
131 readonly isHelperFactory = true;
132 constructor(compute: (positional: Positional<S>, named: Named<S>) => Return<S>);
133 create(): SimpleHelper<S>;
134 }
135 class SimpleClassicHelperManager implements HelperManager<() => unknown> {
136 capabilities: import('@glimmer/interfaces').HelperCapabilities;
137 createHelper(definition: Wrapper, args: Arguments): () => unknown;
138 getValue(fn: () => unknown): unknown;
139 getDebugName(definition: Wrapper): string;
140 }
141 export const SIMPLE_CLASSIC_HELPER_MANAGER: SimpleClassicHelperManager;
142 /**
143 * The type of a function-based helper.
144 *
145 * @note This is *not* user-constructible: it is exported only so that the type
146 * returned by the `helper` function can be named (and indeed can be exported
147 * like `export default helper(...)` safely).
148 */
149 export type FunctionBasedHelper<S> = abstract new () => FunctionBasedHelperInstance<S>;
150 export abstract class FunctionBasedHelperInstance<S> extends Helper<S> {
151 protected abstract __concrete__: never;
152 }
153 /**
154 In many cases it is not necessary to use the full `Helper` class.
155 The `helper` method create pure-function helpers without instances.
156 For example:
157
158 ```app/helpers/format-currency.js
159 import { helper } from '@ember/component/helper';
160
161 export default helper(function([cents], {currency}) {
162 return `${currency}${cents * 0.01}`;
163 });
164 ```
165
166 @static
167 @param {Function} helper The helper function
168 @method helper
169 @for @ember/component/helper
170 @public
171 @since 1.13.0
172 */
173 export function helper<P extends DefaultPositional, N extends object, R = unknown>(
174 helperFn: (positional: P, named: N) => R
175 ): FunctionBasedHelper<{
176 Args: {
177 Positional: P;
178 Named: N;
179 };
180 Return: R;
181 }>;
182 export function helper<S>(
183 helperFn: (positional: Positional<S>, named: Named<S>) => Return<S>
184 ): FunctionBasedHelper<S>;
185 export {};
186}