Merge pull request #995 from emberjs/ts-defs-only

Feature: introduce native (ambient) TS types

.github/workflows/ci.yml

@@ -64,3 +64,26 @@ jobs:
         run: yarn install --frozen-lockfile
       - name: test
         run: node_modules/.bin/ember try:one ${{ matrix.ember-try-scenario }} --skip-cleanup
+
+  types:
+    runs-on: ubuntu-latest
+
+    needs: test
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ts-version:
+          - 4.8
+          - 4.9
+          - next
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: volta-cli/action@v4
+      - name: install dependencies
+        run: yarn install --frozen-lockfile
+      - name: install TS version
+        run: yarn install --dev typescript@${{matrix.ts-version}}
+      - name: test types
+        run: yarn test:types

README.md

@@ -20,6 +20,9 @@ Requirements
 * Ember.js v3.28 or above
 * Ember CLI v3.28 or above
 * Node.js v14 or above
+- TypeScript 4.8 and 4.9
+  - SemVer policy: [simple majors](https://www.semver-ts.org/#simple-majors)
+  - The public API is defined by the [Usage][#usage] section below.
 
 If you need support for Node 13 or older Ember CLI versions please use v4.x
 of this addon.

docs/migration.md

@@ -2,6 +2,52 @@
 Migration Guide
 ==============================================================================
 
+Migrating to native TypeScript support in v6.1.0
+------------------------------------------------------------------------------
+
+The types for the QUnit `TestContext` provided by the `ember-qunit` and `@ember/test-helpers` types on DefinitelyTyped made a choice to prioritize convenience over robustness when it came to what methods and values were available on `this` in any given test: they made *all* methods availabe regardless of what your setup actually involved. For example, this totally invalid code would have passed the type checker:
+
+```ts
+import { module, test } from 'qunit';
+import { setupTest } from 'ember-qunit';
+import { hbs } from 'ember-cli-htmlbars';
+
+module('bad times', function (hooks) {
+  setupTest(hooks);
+
+  test('this will not *run* correctly', async function (assert) {
+    await this.render(hbs`<p>whoopsie</p>`);
+  });
+})
+```
+
+To resolve this, you need to explicitly specify what `this` is for different kinds of tests:
+
+```ts
+import { module, test } from 'qunit';
+import { setupTest } from 'ember-qunit';
+import type { RenderingTextContext } from '@ember/test-helpers';
+import { hbs } from 'ember-cli-htmlbars';
+
+module('better times', function (hooks) {
+  setupTest(hooks);
+
+  test(
+    'this will not *run* correctly',
+    async function (this: RenderingTextContext, assert) {
+      await this.render(hbs`<p>whoopsie</p>`);
+    }
+  );
+})
+```
+
+While annoying, this is accurate and prevents the annoying mismatch. Combined with support for using local scope with `<template>` (see [Ember RFC 0785][rfc-0785]), available since v2.8 of `@ember/test-helpers`, the need to specify the `this` will go away entirely over time.
+
+[rfc-0785]: https://rfcs.emberjs.com/id/0785-remove-set-get-in-tests
+
+To use these public types, you also will need to add `@glimmer/interfaces` and `@glimmer/reference` to your `devDependencies`, since of `@ember/test-helpers` uses them (indirectly) in its public APIs, and `ember-qunit` uses `@ember/test-helpers` in turn.
+
+
 Upgrading from v4.x to v5.0.0
 ------------------------------------------------------------------------------
 

package.json

@@ -21,6 +21,7 @@
     "doc": "doc",
     "test": "tests"
   },
+  "types": "types/index.d.ts",
   "scripts": {
     "build": "ember build --environment=production",
     "lint": "npm-run-all --print-name --aggregate-output --continue-on-error --parallel \"lint:!(fix)\"",
@@ -29,6 +30,7 @@
     "lint:js:fix": "eslint . --fix",
     "start": "ember serve",
     "test": "npm-run-all --print-name \"lint\" \"test:*\"",
+    "test:types": "tsc --noEmit --project types",
     "test:ember": "ember test",
     "test:ember-compatibility": "ember try:each"
   },
@@ -47,9 +49,14 @@
     "@babel/core": "^7.20.5",
     "@babel/eslint-parser": "^7.19.1",
     "@ember/optional-features": "^2.0.0",
-    "@ember/test-helpers": "^2.8.1",
+    "@ember/test-helpers": "^2.9.1",
     "@embroider/test-setup": "^2.0.2",
     "@glimmer/component": "^1.1.2",
+    "@glimmer/interfaces": "^0.84.2",
+    "@glimmer/reference": "^0.84.2",
+    "@tsconfig/ember": "^1.1.0",
+    "@types/qunit": "^2.19.3",
+    "@types/rsvp": "^4.0.4",
     "ember-angle-bracket-invocation-polyfill": "^3.0.2",
     "ember-cli": "~4.8.0",
     "ember-cli-dependency-checker": "^3.3.1",
@@ -59,26 +66,55 @@
     "ember-disable-prototype-extensions": "^1.1.3",
     "ember-load-initializers": "^2.1.2",
     "ember-resolver": "^8.0.3",
-    "ember-source": "~4.9.1",
+    "ember-source": "~4.8.3",
     "ember-source-channel-url": "^3.0.0",
     "ember-try": "^2.0.0",
     "eslint": "^8.29.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-disable-features": "^0.1.3",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^4.2.1",
+    "expect-type": "^0.15.0",
     "loader.js": "^4.7.0",
     "npm-run-all": "^4.1.5",
     "prettier": "2.8.0",
     "qunit": "^2.19.2",
     "release-it": "^15.5.0",
     "release-it-lerna-changelog": "^5.0.0",
+    "typescript": "^4.9.4",
     "webpack": "^5.75.0"
   },
   "peerDependencies": {
     "@ember/test-helpers": "^2.4.0",
+    "@glimmer/interfaces": "^0.84.2",
+    "@glimmer/reference": "^0.84.2",
+    "@types/ember-resolver": "^5.0.13",
+    "@types/ember__test": "^4.0.1",
+    "@types/ember__test-helpers": "^2.8.2",
+    "@types/rsvp": "^4.0.4",
+    "ember-source": "^3.28 || ^4.0",
     "qunit": "^2.13.0"
   },
+  "peerDependenciesMeta": {
+    "@types/ember__test": {
+      "optional": true
+    },
+    "@types/ember-resolver": {
+      "optional": true
+    },
+    "@types/ember__test-helpers": {
+      "optional": true
+    },
+    "@types/rsvp": {
+      "optional": true
+    },
+    "@glimmer/interfaces": {
+      "optional": true
+    },
+    "@glimmer/reference": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": "14.* || 16.* || >= 18"
   },