Merge pull request #603 from NullVoxPopuli/improved-glint-support

Improved glint support with gts / <template>

Author: NullVoxPopuli

ember-resources/src/core/class-based/resource.ts

@@ -5,6 +5,8 @@ import { assert } from '@ember/debug';
 // @ts-ignore
 import { invokeHelper } from '@ember/helper';
 
+import { INTERNAL } from 'core/function-based/types';
+
 import { DEFAULT_THUNK, normalizeThunk } from '../utils';
 
 import type { Cache, Thunk } from '../types';
@@ -169,10 +171,89 @@ export class Resource<T = unknown> {
    */
   static from<T extends new (...args: any) => any>(
     this: T,
-    context: object,
+    context: InstanceType<new (...args: any) => any>,
     thunk?: Thunk | (() => unknown)
+  ): InstanceType<T>;
+
+  /**
+   * For use in the body of a class.
+   *
+   * `from` is what allows resources to be used in JS, they hide the reactivity APIs
+   * from the consumer so that the surface API is smaller.
+   *
+   * ```js
+   * import { Resource, use } from 'ember-resources';
+   *
+   * class SomeResource extends Resource {}
+   *
+   * class MyClass {
+   *   @use data = SomeResource.from(() => [ ... ]);
+   * }
+   * ```
+   */
+  static from<T extends new (...args: any) => any>(
+    this: T,
+    thunk: Thunk | (() => unknown)
+  ): InstanceType<T>;
+
+  static from<T extends new (...args: any) => any>(
+    this: T,
+    contextOrThunk: InstanceType<new (...args: any) => any> | Thunk | (() => unknown),
+    thunkOrUndefined?: undefined | Thunk | (() => unknown)
   ): InstanceType<T> {
-    return resourceOf(context, this, thunk);
+    /**
+     * This first branch is for
+     *
+     * ```js
+     * class Foo {
+     *   @use foo = SomeResource.from(() => [ ... ])
+     * }
+     * ```
+     *
+     * and in order to support this, we need to defer the passed
+     * thunk until when the decorator is accessed.
+     *
+     * The decorator mostly does what `resourceOf` is doing below, but
+     * a little more simply, because we don't have to deal with a Proxy.
+     *
+     */
+    if (typeof contextOrThunk === 'function') {
+      /**
+       * This cast is a little weird, because the narrowing from the
+       * typeof check, while removing `object` from `contextOrThunk` does
+       * add in `Function` to the type union and I don't know of a better way
+       * to manage the type narrowing here.
+       */
+      let thunk = contextOrThunk as Thunk | (() => unknown);
+
+      /**
+       * We have to lie here because TypeScript doesn't allow decorators
+       * to alter the type of a property.
+       *
+       * This is private API that the `@use` decorator understands,
+       * but is not supported for use by any other conusmer.
+       */
+      return {
+        thunk,
+        definition: this,
+        type: 'class-based',
+        [INTERNAL]: true,
+      } as unknown as InstanceType<T>;
+    }
+
+    /**
+     * This usage is for decorator-less usage
+     *
+     * ```js
+     * class Foo {
+     *   foo = SomeResource.from(this, () => [ ... ])
+     * }
+     * ```
+     *
+     * The only tradeoff is that a `this` needs to be passed.
+     *
+     */
+    return resourceOf(contextOrThunk, this, thunkOrUndefined);
   }
 
   // owner must be | unknown as to not

ember-resources/src/core/function-based/immediate-invocation.ts

@@ -3,11 +3,11 @@ import { createCache, getValue } from '@glimmer/tracking/primitives/cache';
 // @ts-ignore
 import { capabilities as helperCapabilities, invokeHelper, setHelperManager } from '@ember/helper';
 
-import type { resource } from './resource';
 import type { Cache } from './types';
 import type Owner from '@ember/owner';
 
-type ResourceFactory = (...args: any[]) => ReturnType<typeof resource>;
+type SpreadFor<T> = T extends Array<any> ? T : [T];
+type ResourceFactory<Value = any, Args = any[]> = (...args: SpreadFor<Args>) => Value;
 
 interface State {
   cache?: Cache;
@@ -130,10 +130,12 @@ class ResourceInvokerManager {
  *  })
  *  ```
  */
-export function resourceFactory(wrapperFn: ResourceFactory) {
+export function resourceFactory<Value = any, Args = any>(
+  wrapperFn: ResourceFactory<Value, Args>
+): (args: () => Args) => Value {
   setHelperManager(ResourceInvokerFactory, wrapperFn);
 
-  return wrapperFn;
+  return wrapperFn as unknown as (args: () => Args) => Value;
 }
 
 // Provide a singleton manager.

ember-resources/src/core/function-based/manager.ts

@@ -4,7 +4,7 @@ import { associateDestroyableChild, destroy, registerDestructor } from '@ember/d
 // @ts-ignore
 import { capabilities as helperCapabilities } from '@ember/helper';
 
-import type { Cache, Destructor, ResourceFunction } from './types';
+import type { Cache, Destructor, InternalFunctionResourceConfig, ResourceFunction } from './types';
 import type Owner from '@ember/owner';
 
 /**
@@ -23,7 +23,8 @@ class FunctionResourceManager {
    * Resources do not take args.
    * However, they can access tracked data
    */
-  createHelper(fn: ResourceFunction) {
+  createHelper(config: InternalFunctionResourceConfig) {
+    let { definition: fn } = config;
     /**
      * We have to copy the `fn` in case there are multiple
      * usages or invocations of the function.
@@ -58,7 +59,7 @@ class FunctionResourceManager {
     return { fn: thisFn, cache };
   }
 
-  getValue({ cache }: { cache: Cache }) {
+  getValue({ cache }: { fn: ResourceFunction; cache: Cache }) {
     let maybeValue = getValue(cache);
 
     if (typeof maybeValue === 'function') {

ember-resources/src/core/function-based/resource.ts

@@ -6,7 +6,7 @@ import { ResourceManagerFactory } from './manager';
 import { INTERNAL } from './types';
 import { wrapForPlainUsage } from './utils';
 
-import type { InternalIntermediate, ResourceFn, ResourceFunction } from './types';
+import type { InternalFunctionResourceConfig, ResourceFn, ResourceFunction } from './types';
 
 /**
  * `resource` is an alternative API to the class-based `Resource`.
@@ -153,7 +153,7 @@ export function resource<Value>(context: object, setup: ResourceFunction<Value>)
 export function resource<Value>(
   context: object | ResourceFunction<Value>,
   setup?: ResourceFunction<Value>
-): Value | InternalIntermediate<Value> | ResourceFn<Value> {
+): Value | InternalFunctionResourceConfig<Value> | ResourceFn<Value> {
   if (!setup) {
     assert(
       `When using \`resource\` with @use, ` +
@@ -162,23 +162,28 @@ export function resource<Value>(
       typeof context === 'function'
     );
 
+    let internalConfig: InternalFunctionResourceConfig<Value> = {
+      definition: context as ResourceFunction<Value>,
+      type: 'function-based',
+      [INTERNAL]: true,
+    };
+
     /**
      * Functions have a different identity every time they are defined.
      * The primary purpose of the `resource` wrapper is to individually
      * register each function with our helper manager.
      */
-    setHelperManager(ResourceManagerFactory, context);
+    setHelperManager(ResourceManagerFactory, internalConfig);
 
     /**
      * With only one argument, we have to do a bunch of lying to
      * TS, because we need a special object to pass to `@use`
      *
      * Add secret key to help @use assert against
      * using vanilla functions as resources without the resource wrapper
+     *
      */
-    (context as any)[INTERNAL] = true;
-
-    return context as ResourceFn<Value>;
+    return internalConfig as unknown as ResourceFn<Value>;
   }
 
   assert(
@@ -193,7 +198,13 @@ export function resource<Value>(
     typeof setup === 'function'
   );
 
-  setHelperManager(ResourceManagerFactory, setup);
+  let internalConfig: InternalFunctionResourceConfig<Value> = {
+    definition: setup as ResourceFunction<Value>,
+    type: 'function-based',
+    [INTERNAL]: true,
+  };
+
+  setHelperManager(ResourceManagerFactory, internalConfig);
 
-  return wrapForPlainUsage(context, setup);
+  return wrapForPlainUsage(context, internalConfig);
 }

ember-resources/src/core/function-based/types.ts

@@ -1,13 +1,10 @@
 export const INTERMEDIATE_VALUE = '__Intermediate_Value__';
 export const INTERNAL = '__INTERNAL__';
 
-/**
- * Secret args to allow `resource` to be used without
- * a decorator
- */
-export interface InternalIntermediate<Value> {
+export interface InternalFunctionResourceConfig<Value = unknown> {
+  definition: ResourceFunction<Value>;
+  type: 'function-based';
   [INTERNAL]: true;
-  [INTERMEDIATE_VALUE]: ResourceFunction<Value>;
 }
 
 export type Hooks = {

ember-resources/src/core/function-based/utils.ts

@@ -5,7 +5,7 @@ import { invokeHelper } from '@ember/helper';
 
 import { INTERMEDIATE_VALUE } from './types';
 
-import type { ResourceFunction } from './types';
+import type { InternalFunctionResourceConfig } from './types';
 
 /**
  * This is what allows resource to be used withotu @use.
@@ -14,7 +14,10 @@ import type { ResourceFunction } from './types';
  *
  * A resource not using use *must* be an object.
  */
-export function wrapForPlainUsage<Value>(context: object, setup: ResourceFunction<Value>) {
+export function wrapForPlainUsage<Value>(
+  context: object,
+  setup: InternalFunctionResourceConfig<Value>
+) {
   let cache: Cache;
 
   /*

ember-resources/src/core/use.ts

@@ -6,16 +6,23 @@ import { associateDestroyableChild } from '@ember/destroyable';
 import { invokeHelper } from '@ember/helper';
 
 import { INTERNAL } from './function-based/types';
+import { normalizeThunk } from './utils';
 
-import type { ResourceFunction } from './function-based/types';
+import type { InternalFunctionResourceConfig } from './function-based/types';
+import type { Thunk } from '[core-types]';
 
 interface Descriptor {
   initializer: () => unknown;
 }
 
-type ResourceInitializer = {
+interface ClassResourceConfig {
+  thunk: Thunk;
+  definition: unknown;
+  type: 'class-based';
   [INTERNAL]: true;
-} & ResourceFunction<unknown>;
+}
+
+type Config = ClassResourceConfig | InternalFunctionResourceConfig;
 
 /**
  * The `@use` decorator has two responsibilities
@@ -51,29 +58,42 @@ export function use(_prototype: object, key: string, descriptor?: Descriptor): v
 
   let { initializer } = descriptor;
 
+  assert(
+    `@use may only be used on initialized properties. For example, ` +
+      `\`@use foo = resource(() => { ... })\` or ` +
+      `\`@use foo = SomeResource.from(() => { ... });\``,
+    initializer
+  );
+
   // https://github.com/pzuraq/ember-could-get-used-to-this/blob/master/addon/index.js
   return {
     get(this: object) {
       let cache = caches.get(this);
 
       if (!cache) {
-        let fn = initializer.call(this);
+        let config = initializer.call(this) as Config;
 
         assert(
-          `Expected initialized value under @use to have used the \`resource\` wrapper function`,
-          isResourceInitializer(fn)
+          `Expected initialized value under @use to have used either the \`resource\` wrapper function, or a \`Resource.from\` call`,
+          INTERNAL in config
         );
 
-        cache = invokeHelper(this, fn);
-        caches.set(this as object, cache);
-        associateDestroyableChild(this, cache);
+        if (config.type === 'function-based') {
+          cache = invokeHelper(this, config);
+          caches.set(this as object, cache);
+          associateDestroyableChild(this, cache);
+        } else if (config.type === 'class-based') {
+          let { definition, thunk } = config;
+
+          cache = invokeHelper(this, definition, () => normalizeThunk(thunk));
+          caches.set(this as object, cache);
+          associateDestroyableChild(this, cache);
+        }
+
+        assert(`Failed to create cache for internal resource configuration object`, cache);
       }
 
       return getValue(cache);
     },
   } as unknown as void /* Thanks TS. */;
 }
-
-function isResourceInitializer(obj: unknown): obj is ResourceInitializer {
-  return typeof obj === 'function' && obj !== null && INTERNAL in obj;
-}

ember-resources/src/util/helper.ts

@@ -8,7 +8,9 @@ import { DEFAULT_THUNK, normalizeThunk } from '../core/utils';
 import type { Cache, Thunk } from '../core/types';
 import type ClassBasedHelper from '@ember/component/helper';
 import type { FunctionBasedHelper } from '@ember/component/helper';
-import type { Get, HelperLike } from '@glint/template';
+import type { HelperLike } from '@glint/template';
+
+type Get<T, K, Otherwise = unknown> = K extends keyof T ? T[K] : Otherwise;
 
 /**
  * @utility implemented with raw `invokeHelper` API, no classes from `ember-resources` used.