RFC#560 - {{eq}}, {{neq}} as keywords

Add equality helpers and register them as built-in keywords so they
no longer need to be imported in strict-mode (gjs/gts) templates.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: NullVoxPopuli

packages/@ember/helper/index.ts

@@ -8,8 +8,10 @@ import {
   hash as glimmerHash,
   array as glimmerArray,
   concat as glimmerConcat,
+  eq as glimmerEq,
   get as glimmerGet,
   fn as glimmerFn,
+  neq as glimmerNeq,
 } from '@glimmer/runtime';
 import { element as glimmerElement, uniqueId as glimmerUniqueId } from '@ember/-internals/glimmer';
 import { type Opaque } from '@ember/-internals/utility-types';
@@ -511,4 +513,52 @@ export interface ElementHelper extends Opaque<'helper:element'> {}
 export const uniqueId = glimmerUniqueId;
 export type UniqueIdHelper = typeof uniqueId;
 
+/**
+ * The `{{eq}}` helper returns `true` if its two arguments are strictly equal
+ * (`===`). Takes exactly two arguments.
+ *
+ * ```js
+ * import { eq } from '@ember/helper';
+ *
+ * <template>
+ *   {{if (eq @status "active") "Active" "Inactive"}}
+ * </template>
+ * ```
+ *
+ * In strict-mode (gjs/gts) templates, `eq` is available as a keyword and
+ * does not need to be imported.
+ *
+ * @method eq
+ * @param {unknown} left
+ * @param {unknown} right
+ * @return {boolean}
+ * @public
+ */
+export const eq = glimmerEq as unknown as EqHelper;
+export interface EqHelper extends Opaque<'helper:eq'> {}
+
+/**
+ * The `{{neq}}` helper returns `true` if its two arguments are strictly
+ * not equal (`!==`). Takes exactly two arguments.
+ *
+ * ```js
+ * import { neq } from '@ember/helper';
+ *
+ * <template>
+ *   {{if (neq @status "active") "Not active" "Active"}}
+ * </template>
+ * ```
+ *
+ * In strict-mode (gjs/gts) templates, `neq` is available as a keyword and
+ * does not need to be imported.
+ *
+ * @method neq
+ * @param {unknown} left
+ * @param {unknown} right
+ * @return {boolean}
+ * @public
+ */
+export const neq = glimmerNeq as unknown as NeqHelper;
+export interface NeqHelper extends Opaque<'helper:neq'> {}
+
 /* eslint-enable @typescript-eslint/no-empty-object-type */

packages/@ember/template-compiler/lib/compile-options.ts

@@ -1,4 +1,4 @@
-import { array, fn, hash } from '@ember/helper';
+import { array, eq, fn, hash, neq } from '@ember/helper';
 import { on } from '@ember/modifier';
 import { assert } from '@ember/debug';
 import {
@@ -26,8 +26,10 @@ export const RUNTIME_KEYWORDS_NAME = '__ember_keywords__';
 
 export const keywords: Record<string, unknown> = {
   array,
+  eq,
   fn,
   hash,
+  neq,
   on,
 };
 

packages/@ember/template-compiler/lib/plugins/auto-import-builtins.ts

@@ -36,6 +36,12 @@ export default function autoImportBuiltins(env: EmberASTPluginEnvironment): ASTP
         if (isHash(node, hasLocal)) {
           rewriteKeyword(env, node, 'hash', '@ember/helper');
         }
+        if (isEq(node, hasLocal)) {
+          rewriteKeyword(env, node, 'eq', '@ember/helper');
+        }
+        if (isNeq(node, hasLocal)) {
+          rewriteKeyword(env, node, 'neq', '@ember/helper');
+        }
       },
       MustacheStatement(node: AST.MustacheStatement) {
         if (isArray(node, hasLocal)) {
@@ -47,6 +53,12 @@ export default function autoImportBuiltins(env: EmberASTPluginEnvironment): ASTP
         if (isHash(node, hasLocal)) {
           rewriteKeyword(env, node, 'hash', '@ember/helper');
         }
+        if (isEq(node, hasLocal)) {
+          rewriteKeyword(env, node, 'eq', '@ember/helper');
+        }
+        if (isNeq(node, hasLocal)) {
+          rewriteKeyword(env, node, 'neq', '@ember/helper');
+        }
       },
     },
   };
@@ -94,3 +106,17 @@ function isHash(
 ): node is (AST.MustacheStatement | AST.SubExpression) & { path: AST.PathExpression } {
   return isPath(node.path) && node.path.original === 'hash' && !hasLocal('hash');
 }
+
+function isEq(
+  node: AST.MustacheStatement | AST.SubExpression,
+  hasLocal: (k: string) => boolean
+): node is (AST.MustacheStatement | AST.SubExpression) & { path: AST.PathExpression } {
+  return isPath(node.path) && node.path.original === 'eq' && !hasLocal('eq');
+}
+
+function isNeq(
+  node: AST.MustacheStatement | AST.SubExpression,
+  hasLocal: (k: string) => boolean
+): node is (AST.MustacheStatement | AST.SubExpression) & { path: AST.PathExpression } {
+  return isPath(node.path) && node.path.original === 'neq' && !hasLocal('neq');
+}

packages/@glimmer-workspace/integration-tests/test/keywords/eq-runtime-test.ts

@@ -0,0 +1,60 @@
+import {
+  GlimmerishComponent,
+  jitSuite,
+  RenderTest,
+  test,
+} from '@glimmer-workspace/integration-tests';
+
+import { template } from '@ember/template-compiler/runtime';
+
+class KeywordEqRuntime extends RenderTest {
+  static suiteName = 'keyword helper: eq (runtime)';
+
+  @test
+  'explicit scope'() {
+    const compiled = template('{{if (eq a b) "yes" "no"}}', {
+      strictMode: true,
+      scope: () => ({ a: 1, b: 1 }),
+    });
+    this.renderComponent(compiled);
+    this.assertHTML('yes');
+  }
+
+  @test
+  'implicit scope'() {
+    let a = 1;
+    let b = 1;
+    hide(a);
+    hide(b);
+    const compiled = template('{{if (eq a b) "yes" "no"}}', {
+      strictMode: true,
+      eval() {
+        return eval(arguments[0]);
+      },
+    });
+    this.renderComponent(compiled);
+    this.assertHTML('yes');
+  }
+
+  @test
+  'no eval and no scope'() {
+    class Foo extends GlimmerishComponent {
+      static {
+        template('{{if (eq this.a this.b) "yes" "no"}}', {
+          strictMode: true,
+          component: this,
+        });
+      }
+      a = 1;
+      b = 1;
+    }
+    this.renderComponent(Foo);
+    this.assertHTML('yes');
+  }
+}
+
+jitSuite(KeywordEqRuntime);
+
+const hide = (variable: unknown) => {
+  new Function(`return (${JSON.stringify(variable)});`);
+};

packages/@glimmer-workspace/integration-tests/test/keywords/eq-test.ts

@@ -0,0 +1,60 @@
+import { DEBUG } from '@glimmer/env';
+import { jitSuite, RenderTest, test } from '@glimmer-workspace/integration-tests';
+
+import { template } from '@ember/template-compiler';
+import { eq } from '@ember/helper';
+
+class KeywordEq extends RenderTest {
+  static suiteName = 'keyword helper: eq';
+
+  @test
+  'returns true for equal numbers'() {
+    let a = 1;
+    let b = 1;
+    const compiled = template('{{if (eq a b) "yes" "no"}}', {
+      strictMode: true,
+      scope: () => ({ eq, a, b }),
+    });
+    this.renderComponent(compiled);
+    this.assertHTML('yes');
+  }
+
+  @test
+  'returns false for unequal numbers'() {
+    let a = 1;
+    let b = 2;
+    const compiled = template('{{if (eq a b) "yes" "no"}}', {
+      strictMode: true,
+      scope: () => ({ eq, a, b }),
+    });
+    this.renderComponent(compiled);
+    this.assertHTML('no');
+  }
+
+  @test
+  'returns true for equal strings'() {
+    let a = 'hello';
+    let b = 'hello';
+    const compiled = template('{{if (eq a b) "yes" "no"}}', {
+      strictMode: true,
+      scope: () => ({ eq, a, b }),
+    });
+    this.renderComponent(compiled);
+    this.assertHTML('yes');
+  }
+
+  @test({ skip: !DEBUG })
+  'throws if not called with exactly two arguments'(assert: Assert) {
+    let a = 1;
+    const compiled = template('{{eq a}}', {
+      strictMode: true,
+      scope: () => ({ eq, a }),
+    });
+
+    assert.throws(() => {
+      this.renderComponent(compiled);
+    }, /`eq` expects exactly two arguments/);
+  }
+}
+
+jitSuite(KeywordEq);

packages/@glimmer-workspace/integration-tests/test/keywords/neq-runtime-test.ts

@@ -0,0 +1,60 @@
+import {
+  GlimmerishComponent,
+  jitSuite,
+  RenderTest,
+  test,
+} from '@glimmer-workspace/integration-tests';
+
+import { template } from '@ember/template-compiler/runtime';
+
+class KeywordNeqRuntime extends RenderTest {
+  static suiteName = 'keyword helper: neq (runtime)';
+
+  @test
+  'explicit scope'() {
+    const compiled = template('{{if (neq a b) "yes" "no"}}', {
+      strictMode: true,
+      scope: () => ({ a: 1, b: 2 }),
+    });
+    this.renderComponent(compiled);
+    this.assertHTML('yes');
+  }
+
+  @test
+  'implicit scope'() {
+    let a = 1;
+    let b = 2;
+    hide(a);
+    hide(b);
+    const compiled = template('{{if (neq a b) "yes" "no"}}', {
+      strictMode: true,
+      eval() {
+        return eval(arguments[0]);
+      },
+    });
+    this.renderComponent(compiled);
+    this.assertHTML('yes');
+  }
+
+  @test
+  'no eval and no scope'() {
+    class Foo extends GlimmerishComponent {
+      static {
+        template('{{if (neq this.a this.b) "yes" "no"}}', {
+          strictMode: true,
+          component: this,
+        });
+      }
+      a = 1;
+      b = 2;
+    }
+    this.renderComponent(Foo);
+    this.assertHTML('yes');
+  }
+}
+
+jitSuite(KeywordNeqRuntime);
+
+const hide = (variable: unknown) => {
+  new Function(`return (${JSON.stringify(variable)});`);
+};

packages/@glimmer-workspace/integration-tests/test/keywords/neq-test.ts

@@ -0,0 +1,48 @@
+import { DEBUG } from '@glimmer/env';
+import { jitSuite, RenderTest, test } from '@glimmer-workspace/integration-tests';
+
+import { template } from '@ember/template-compiler';
+import { neq } from '@ember/helper';
+
+class KeywordNeq extends RenderTest {
+  static suiteName = 'keyword helper: neq';
+
+  @test
+  'returns true for unequal numbers'() {
+    let a = 1;
+    let b = 2;
+    const compiled = template('{{if (neq a b) "yes" "no"}}', {
+      strictMode: true,
+      scope: () => ({ neq, a, b }),
+    });
+    this.renderComponent(compiled);
+    this.assertHTML('yes');
+  }
+
+  @test
+  'returns false for equal numbers'() {
+    let a = 1;
+    let b = 1;
+    const compiled = template('{{if (neq a b) "yes" "no"}}', {
+      strictMode: true,
+      scope: () => ({ neq, a, b }),
+    });
+    this.renderComponent(compiled);
+    this.assertHTML('no');
+  }
+
+  @test({ skip: !DEBUG })
+  'throws if not called with exactly two arguments'(assert: Assert) {
+    let a = 1;
+    const compiled = template('{{neq a}}', {
+      strictMode: true,
+      scope: () => ({ neq, a }),
+    });
+
+    assert.throws(() => {
+      this.renderComponent(compiled);
+    }, /`neq` expects exactly two arguments/);
+  }
+}
+
+jitSuite(KeywordNeq);

packages/@glimmer/runtime/index.ts

@@ -33,10 +33,12 @@ export {
 } from './lib/environment';
 export { array } from './lib/helpers/array';
 export { concat } from './lib/helpers/concat';
+export { eq } from './lib/helpers/eq';
 export { fn } from './lib/helpers/fn';
 export { get } from './lib/helpers/get';
 export { hash } from './lib/helpers/hash';
 export { invokeHelper } from './lib/helpers/invoke';
+export { neq } from './lib/helpers/neq';
 export { on } from './lib/modifiers/on';
 export { renderComponent, renderMain, renderSync } from './lib/render';
 export { DynamicScopeImpl, ScopeImpl } from './lib/scope';

packages/@glimmer/runtime/lib/helpers/eq.ts

@@ -0,0 +1,9 @@
+import { DEBUG } from '@glimmer/env';
+
+export const eq = (...args: unknown[]) => {
+  if (DEBUG && args.length !== 2) {
+    throw new Error(`\`eq\` expects exactly two arguments, but received ${args.length}.`);
+  }
+
+  return args[0] === args[1];
+};

packages/@glimmer/runtime/lib/helpers/neq.ts

@@ -0,0 +1,9 @@
+import { DEBUG } from '@glimmer/env';
+
+export const neq = (...args: unknown[]) => {
+  if (DEBUG && args.length !== 2) {
+    throw new Error(`\`neq\` expects exactly two arguments, but received ${args.length}.`);
+  }
+
+  return args[0] !== args[1];
+};