Merge pull request #148 from dfreeman/extensible-types

Update types for extensibility

package.json

@@ -20,11 +20,12 @@
     "problems": "tsc -p tsconfig.json --noEmit",
     "start": "webpack-dev-server",
     "storybook": "yarn build && yarn workspace basic-example-app storybook",
-    "test": "yarn format:check && yarn lint && testem ci && yarn test:babel-plugins && yarn test:prettier",
+    "test": "yarn format:check && yarn lint && testem ci && yarn test:babel-plugins && yarn test:types && yarn test:prettier",
     "test:babel-plugins": "mocha -r esm --timeout 5000 packages/@glimmerx/babel-preset/test packages/@glimmerx/eslint-plugin/test/lib/rules",
     "test:ember": "yarn workspace basic-addon ember try:one",
     "test:prettier": "mocha -r esm packages/@glimmerx/prettier-plugin-component-templates/test",
     "test:playground": "yarn workspace glimmerx-playground test",
+    "test:types": "tsc --noEmit --project type-tests",
     "test:watch": "testem"
   },
   "browserslist": {
@@ -51,6 +52,7 @@
     "@typescript-eslint/parser": "^4.18.0",
     "babel-loader": "^8.0.6",
     "eslint": "^7.29.0",
+    "expect-type": "^0.13.0",
     "fs-extra": "^9.0.0",
     "lerna": "^3.20.2",
     "prettier": "^2.3.1",

packages/@glimmerx/component/index.ts

@@ -1,8 +1,21 @@
-import { default as Component } from '@glimmer/component';
-
 export { default } from '@glimmer/component';
 export { tracked } from '@glimmer/tracking';
 
-export function hbs(_strings: TemplateStringsArray): Component {
+// This type exists to provide a non-user-constructible, non-subclassable
+// type representing the conceptual "instance type" of a template-only component.
+// The abstract field of type `never` prevents subclassing in userspace of
+// the value returned from `hbs`.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export declare abstract class TemplateComponentInstance<S> {
+  protected abstract __concrete__: never;
+}
+
+// By making `TemplateComponent` abstract and impossible to subclass
+// (see above), we prevent users from attempting to instantiate a the
+// return value of `hbs` themselves, while leaving a hook for tools
+// like Glint to augment the type.
+export type TemplateComponent<S> = abstract new () => TemplateComponentInstance<S>;
+
+export function hbs<S>(_strings: TemplateStringsArray): TemplateComponent<S> {
   throw new Error('hbs template should have been compiled at build time');
 }

packages/@glimmerx/helper/index.ts

@@ -1,2 +1,13 @@
-export { helper, Helper } from './src/helper';
-export { fn } from '@glimmer/helper';
+export { helper, HelperFunction, Helper } from './src/helper';
+
+import { fn as glimmerFn } from '@glimmer/helper';
+
+declare const Brand: unique symbol;
+
+// This interface provides an extension point for tools like
+// Glint to augment with template-specific type information.
+export interface FnHelper {
+  [Brand]: 'helper:fn';
+}
+
+export const fn = glimmerFn as FnHelper;

packages/@glimmerx/helper/src/helper.ts

@@ -5,14 +5,29 @@ interface HelperOptions {
   services: Record<string, unknown>;
 }
 
-export type Helper<T = unknown, U = unknown> = (
+export type HelperFunction<T = unknown, U = unknown> = (
   positional: T,
   named: U,
   options: HelperOptions
 ) => unknown;
 
+// This type exists to provide a non-user-constructible, non-subclassable
+// type representing the conceptual "instance type" of a helper.
+// The abstract field of type `never` prevents subclassing in userspace of
+// the value returned from `helper()`.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export declare abstract class HelperInstance<S> {
+  protected abstract __concrete__: never;
+}
+
+// Making `Helper` a bare constructor type allows for type parameters to be
+// preserved when `helper()` is passed a generic function. By making it
+// `abstract` and impossible to subclass (see above), we prevent users from
+// attempting to instantiate a return value from `helper()`.
+export type Helper<S> = abstract new () => HelperInstance<S>;
+
 interface BasicHelperBucket {
-  fn: Helper;
+  fn: HelperFunction;
   args: Arguments;
   ownerProxy: Record<string, unknown>;
 }
@@ -24,7 +39,7 @@ class BasicHelperManager implements HelperManager<BasicHelperBucket> {
 
   constructor(private owner: Owner | undefined) {}
 
-  createHelper(fn: Helper, args: Arguments) {
+  createHelper(fn: HelperFunction, args: Arguments) {
     const { owner } = this;
 
     const ownerProxy = new Proxy(
@@ -54,8 +69,17 @@ class BasicHelperManager implements HelperManager<BasicHelperBucket> {
 
 const basicHelperManagerFactory = (owner: Owner | undefined) => new BasicHelperManager(owner);
 
-export function helper<T, U>(helperFunction: Helper<T, U>) {
+export function helper<P extends unknown[], N, R>(
+  helperFunction: (positional: P, named: N, options: HelperOptions) => R
+): Helper<{ Args: { Named: N; Positional: P }; Return: R }> {
   setHelperManager(basicHelperManagerFactory, helperFunction);
 
-  return helperFunction;
+  // Despite actually returning the given function, from a template's
+  // perspective its associated helper manager now makes it something
+  // different. It wouldn't be legal to invoke it according to its
+  // original type any more, and we need to reflect that.
+  return helperFunction as unknown as Helper<{
+    Args: { Named: N; Positional: P };
+    Return: R;
+  }>;
 }

packages/@glimmerx/modifier/index.ts

@@ -1 +1,13 @@
-export { on, action } from '@glimmer/modifier';
+import { action, on as glimmerOn } from '@glimmer/modifier';
+
+declare const Brand: unique symbol;
+
+// This interface provides an extension point for tools like
+// Glint to augment with template-specific type information.
+export interface OnModifier {
+  [Brand]: 'modifier:on';
+}
+
+const on = glimmerOn as OnModifier;
+
+export { on, action };

tsconfig.json

@@ -23,6 +23,7 @@
     "experimentalDecorators": true            /* Enables experimental support for ES7 decorators. */
   },
   "exclude": [
-    "./packages/@glimmerx/storybook"
+    "./packages/@glimmerx/storybook",
+    "./type-tests"
   ]
 }

type-tests/component.ts

@@ -0,0 +1,22 @@
+import { expectTypeOf } from 'expect-type';
+import { hbs, TemplateComponent } from '@glimmerx/component';
+
+declare module '@glimmerx/component' {
+  // For the purposes of testing, make the instance type dependent on the `S` parameter,
+  // even if in practice the variance wouldn't be quite right.
+  export interface TemplateComponentInstance<S> {
+    value: S;
+  }
+}
+
+type SignatureOf<T> = T extends TemplateComponent<infer S> ? S : unknown;
+
+interface GreetSignature {
+  Args: { target: string };
+}
+
+export const InferredGreet: TemplateComponent<GreetSignature> = hbs`Hello, {{@target}}`;
+
+export const ExplicitGreet = hbs<GreetSignature>`Hello, {{@target}}`;
+
+expectTypeOf<SignatureOf<typeof ExplicitGreet>>().toEqualTypeOf<GreetSignature>();

type-tests/helper.ts

@@ -0,0 +1,24 @@
+import { expectTypeOf } from 'expect-type';
+import { helper, Helper, fn, FnHelper } from '@glimmerx/helper';
+
+declare module '@glimmerx/helper/dist/commonjs/src/helper' {
+  // For the purposes of testing, make the instance type dependent on the `S` parameter,
+  // even if in practice the variance wouldn't be quite right.
+  export interface HelperInstance<S> {
+    signature: S;
+  }
+}
+
+type SignatureOf<T> = T extends Helper<infer S> ? S : unknown;
+
+expectTypeOf(fn).toEqualTypeOf<FnHelper>();
+
+const myHelper = helper((_: [], { arg }: { arg: string }) => arg);
+
+expectTypeOf<SignatureOf<typeof myHelper>>().toEqualTypeOf<{
+  Args: {
+    Positional: [];
+    Named: { arg: string };
+  };
+  Return: string;
+}>();

type-tests/modifier.ts

@@ -0,0 +1,4 @@
+import { expectTypeOf } from 'expect-type';
+import { on, OnModifier } from '@glimmerx/modifier';
+
+expectTypeOf(on).toEqualTypeOf<OnModifier>();

type-tests/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.json",
+  "exclude": []
+}

yarn.lock

@@ -12134,6 +12134,11 @@ expand-tilde@^2.0.0, expand-tilde@^2.0.2:
   dependencies:
     homedir-polyfill "^1.0.1"
 
+expect-type@^0.13.0:
+  version "0.13.0"
+  resolved "https://registry.yarnpkg.com/expect-type/-/expect-type-0.13.0.tgz#916646a7a73f3ee77039a634ee9035efe1876eb2"
+  integrity sha512-CclevazQfrqo8EvbLPmP7osnb1SZXkw47XPPvUUpeMz4HuGzDltE7CaIt3RLyT9UQrwVK/LDn+KVcC0hcgjgDg==
+
 express@^4.10.7, express@^4.16.4, express@^4.17.1:
   version "4.17.1"
   resolved "https://registry.yarnpkg.com/express/-/express-4.17.1.tgz#4491fc38605cf51f8629d39c2b5d026f98a4c134"