feat(build): publish types as part of `@ember/test-helpers` #1196

buschtoens · 2022-02-27T06:58:42Z

Build and publish the TypeScript .d.ts files as part of @ember/test-helpers to obsolete @types/ember__test-helpers.

DefinitelyTyped/DefinitelyTyped#59014

Fixes emberjs#596. Includes a fix for building from `.ts` source files. documentationjs/documentation#1484

buschtoens · 2022-02-27T07:04:59Z

package.json

@@ -61,7 +61,7 @@
    "@typescript-eslint/parser": "^4.29.0",
    "broccoli-babel-preset-typescript": "^1.0.1",
    "broccoli-merge-trees": "^4.2.0",
-    "documentation": "^13.2.5",
+    "documentation": "npm:@buschtoens/documentation@13.2.6",


We may want to consider taking this opportunity to switch to a more well-maintained tool, like API Extractor. That would also improve the .d.ts build process.

@chriskrycho

Should I keep pointing at my fork here?

Or should we switch to a different tool like API Extractor first? If so, ...

Which tool would you prefer?

Should this be split out into an extra PR that is merged before this one?

Or do you have a completely different solution to this in mind?

I think you're exactly right directionally! Let's see if we can get TypeDoc wired up to do what we want. TypeDoc is almost certainly what we're going to end up using for Ember itself; it is how we are doing all of our TS-powered docs-generation at LinkedIn; and it is what I've used most successfully on other TS projects.

(API Extractor is (a) barely maintained at this point and (b) uninterested in supporting anything other than single-entry-point Node-style packages. TypeDoc is well-maintained, open to contributions, and actively working on supporting things like package exports maps. If we find gaps, let's help fix them there!)

chriskrycho · 2022-08-18T21:11:06Z

I just remembered this existed! 😓 @buschtoens if you can rebase and update, we'll get it published.

chriskrycho

Had a couple comments in flight. I'm sure there will be more.

chriskrycho · 2022-03-29T18:41:32Z

addon-test-support/@ember/test-helpers/-internal/deprecations.ts

@@ -93,6 +93,7 @@ if (typeof URLSearchParams !== 'undefined') {
  if (disabledDeprecations) {
    registerDeprecationHandler((message, options, next) => {
      if (!disabledDeprecations.includes(options.id)) {
+        // @ts-expect-error https://github.com/DefinitelyTyped/DefinitelyTyped/pull/59014


Let's avoid referring to DT-specific issues if possible, because these comments will get stale very quickly as a result. Documenting why they don't work and linking to an issue which tracks it seems fine.

chriskrycho · 2022-03-29T19:51:05Z

addon-test-support/@ember/test-helpers/-internal/view.ts

+/**
+ * @internal
+ * @see {@link https://github.com/glimmerjs/glimmer-vm/blob/v0.84.0/packages/@glimmer/interfaces/lib/template.d.ts#L29-L55}
+ */
+type Template = {};


At least for this one, we probably want to use the same "opaque type" trick we are using for similar interfaces across the ecosystem (with an eye to unifying all of them as we go forward). Otherwise, as a return type, it's usable as "any old object" and people can "construct" it themselves.

Suggested change

/**

* @internal

* @see {@link https://github.com/glimmerjs/glimmer-vm/blob/v0.84.0/packages/@glimmer/interfaces/lib/template.d.ts#L29-L55}

*/

type Template = {};

declare const Brand: unique symbol;

declare class Opaque<T> {

private [Brand]: T;

}

/**

* @internal

* @see {@link https://github.com/glimmerjs/glimmer-vm/blob/v0.84.0/packages/@glimmer/interfaces/lib/template.d.ts#L29-L55}

*/

interface Template extends Opaque<'Template'> {}

This provides a value that is only constructible internally (and via methods we provide) rather than something which folks can just pass an object as (and have it potentially go 💥).

Note that it's fine to do type Template = ... as long as you don't care about it being interface-mergable later, and in fact that's a useful tool for exactly that scenario (where you want to make the type "closed" rather than "open"):

type Template = Opaque<'Template'>;

buschtoens · 2022-08-18T21:12:40Z

@chriskrycho Sure! I'll try to get to it in the next hours. Thanks for picking this up again. 🥳

chriskrycho · 2022-08-18T21:25:50Z

So sorry I let it sit for so long! Just fell off my radar, as these things do!

chriskrycho · 2022-08-18T23:31:18Z

@buschtoens also relevant: #1234, which… may… supersede this? (I had obviously really forgotten about this PR. 😢)

chriskrycho · 2022-12-15T22:32:28Z

Going to go ahead and close this as superseded by a number of other commits; thanks again for getting it started @buschtoens!

buschtoens added 15 commits February 27, 2022 01:29

chore(tsc): enable strict

44e50e0

chore(deps): update @ember/types incl. sub-deps

e2f5cf2

fix: use Resolver type from ember-resolver

5329570

refactor: augment Backburner types instead of overriding

10fef01

fix(setupApplicationContext): Router & RouterService types

c6debf7

fix(setupRenderingContext): OutletView type

b93a74c

fix(typeIn): fillOut returns Promise<void>

4b7326b

[REVERT ME] fix: registerWarnHandler & registerDeprecationHandler

ad75db9

DefinitelyTyped/DefinitelyTyped#59014

chore(gitignore): exclude *.d.ts.map

df54aac

chore(build): extensible build hooks

3cb9747

chore(build): include API.md

1ae1199

chore(build): publish types

d8c18dd

chore(pkg): pin [email protected]

11701c1

fix(build): use @buschtoens/documentation

ad08e73

Fixes emberjs#596. Includes a fix for building from `.ts` source files. documentationjs/documentation#1484

docs: re-build outdated API.md

824aedd

buschtoens commented Feb 27, 2022

View reviewed changes

chriskrycho requested changes Aug 18, 2022

View reviewed changes

chriskrycho closed this Dec 15, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(build): publish types as part of `@ember/test-helpers` #1196

feat(build): publish types as part of `@ember/test-helpers` #1196

buschtoens commented Feb 27, 2022

buschtoens Feb 27, 2022

buschtoens Aug 18, 2022 •

edited

Loading

chriskrycho Aug 19, 2022

chriskrycho commented Aug 18, 2022

chriskrycho left a comment

chriskrycho Mar 29, 2022

chriskrycho Mar 29, 2022

buschtoens commented Aug 18, 2022

chriskrycho commented Aug 18, 2022

chriskrycho commented Aug 18, 2022

chriskrycho commented Dec 15, 2022

-/**
- * @internal
- * @see {@link https://github.com/glimmerjs/glimmer-vm/blob/v0.84.0/packages/@glimmer/interfaces/lib/template.d.ts#L29-L55}
- */
-type Template = {};
+declare const Brand: unique symbol;
+declare class Opaque<T> {
+  private [Brand]: T;
+}
+/**
+ * @internal
+ * @see {@link https://github.com/glimmerjs/glimmer-vm/blob/v0.84.0/packages/@glimmer/interfaces/lib/template.d.ts#L29-L55}
+ */
+interface Template extends Opaque<'Template'> {}

feat(build): publish types as part of @ember/test-helpers #1196

feat(build): publish types as part of @ember/test-helpers #1196

Conversation

buschtoens commented Feb 27, 2022

buschtoens Feb 27, 2022

Choose a reason for hiding this comment

buschtoens Aug 18, 2022 • edited Loading

Choose a reason for hiding this comment

chriskrycho Aug 19, 2022

Choose a reason for hiding this comment

chriskrycho commented Aug 18, 2022

chriskrycho left a comment

Choose a reason for hiding this comment

chriskrycho Mar 29, 2022

Choose a reason for hiding this comment

chriskrycho Mar 29, 2022

Choose a reason for hiding this comment

buschtoens commented Aug 18, 2022

chriskrycho commented Aug 18, 2022

chriskrycho commented Aug 18, 2022

chriskrycho commented Dec 15, 2022

feat(build): publish types as part of `@ember/test-helpers` #1196

feat(build): publish types as part of `@ember/test-helpers` #1196

buschtoens Aug 18, 2022 •

edited

Loading