Implement experiment for: emberjs/rfcs#905

Author: NullVoxPopuli

.changeset/hip-fishes-agree.md

@@ -0,0 +1,74 @@
+---
+"ember-resources": minor
+---
+
+Add link() and @link, importable from `ember-resources/link`.
+
+NOTE: for existing users of `ember-resources`, this addition has no impact on your bundle.
+
+<details><summary>Example property usage</summary>
+
+```js
+import { link } from 'ember-resources/link';
+
+class MyClass {  ... }
+
+export default class Demo extends Component {
+  // This usage does now allow passing args to `MyClass`
+  @link(MyClass) myInstance;
+}
+```
+
+</details>
+
+<details><summary>Example inline usage</summary>
+
+```js
+import Component from '@glimmer/component';
+import { cached } from '@glimmer/tracking';
+import { link } from 'ember-resources/link';
+
+export default class Demo extends Component {
+  // To pass args to `MyClass`, you must use this form
+  // NOTE though, that `instance` is linked to the `Demo`s lifecycle.
+  //  So if @foo is changing frequently, memory pressure will increase rapidly
+  //  until the `Demo` instance is destroyed.
+  // 
+  //  Resources are a better fit for this use case, as they won't add to memory pressure.
+  @cached
+  get myFunction() {
+    let instance = new MyClass(this.args.foo);
+
+    return link(instance, this);
+  }
+}
+```
+
+</details>
+
+
+This abstracts away the following boilerplate:
+```js 
+import { getOwner, setOwner } from '@ember/owner';
+import { associateDestroyableChild } from '@ember/destroyable';
+
+class MyClass { /* ... */ }
+
+export default class Demo extends Component {
+  @cached 
+  get myInstance() {
+    let instance = new MyClass();
+    
+    associateDestroyableChild(this, instance);
+    
+    let owner = getOwner(this);
+
+    if (owner) {
+      setOwner(instance, owner);
+    }
+
+    return instance;
+  }
+}
+```
+

ember-resources/package.json

@@ -12,6 +12,7 @@
     "./core": "./dist/core/index.js",
     "./core/class-based": "./dist/core/class-based/index.js",
     "./core/function-based": "./dist/core/function-based/index.js",
+    "./link": "./dist/link.js",
     "./service": "./dist/service.js",
     "./util": "./dist/util/index.js",
     "./util/cell": "./dist/util/cell.js",
@@ -33,6 +34,9 @@
       "core": [
         "dist/core/index.d.ts"
       ],
+      "link": [
+        "dist/link.d.ts"
+      ],
       "service": [
         "dist/service.d.ts"
       ],

ember-resources/src/link.ts

@@ -0,0 +1,127 @@
+import { getOwner, setOwner } from '@ember/application';
+import { assert } from '@ember/debug';
+import { associateDestroyableChild } from '@ember/destroyable';
+
+import type { Stage1DecoratorDescriptor } from '[core-types]';
+
+/**
+ * A util to abstract away the boilerplate of linking of "things" with an owner
+ * and making them destroyable.
+ *
+ * ```js
+ * import Component from '@glimmer/component';
+ * import { cached } from '@glimmer/tracking';
+ * import { link } from 'ember-resources/link';
+ *
+ * export default class Demo extends Component {
+ *   @cached
+ *   get myFunction() {
+ *     let instance = new MyClass(this.args.foo);
+ *
+ *     return link(instance, this);
+ *   }
+ * }
+ * ```
+ *
+ * NOTE: If args change, as in this example, memory pressure will increase,
+ *       as the linked instance will be held on to until the host object is destroyed.
+ */
+export function link<Child extends object>(child: Child, parent: object): Child;
+
+/**
+ * A util to abstract away the boilerplate of linking of "things" with an owner
+ * and making them destroyable.
+ *
+ *
+ * Example as a class property:
+ * ```js
+ * import { link } from 'ember-resources/link';
+ *
+ * class MyClass {  ... }
+ *
+ * export default class Demo extends Component {
+ *   @link(MyClass) myInstance;
+ * }
+ * ```
+ *
+ * Example inline usage:
+ * ```js
+ * import Component from '@glimmer/component';
+ * import { cached } from '@glimmer/tracking';
+ * import { link } from 'ember-resources/link';
+ *
+ * export default class Demo extends Component {
+ *   @cached
+ *   get myFunction() {
+ *     let instance = new MyClass(this.args.foo);
+ *
+ *     return link(instance, this);
+ *   }
+ * }
+ * ```
+ */
+export function link(prototype: object, key: string, descriptor: Stage1DecoratorDescriptor): void;
+
+export function link(...args: [object, string, Stage1DecoratorDescriptor] | [object, object]) {
+  if (args.length === 3) {
+    return linkDecorator(...args);
+  }
+
+  return directLink(...args);
+}
+
+function directLink(child: object, parent: object) {
+  associateDestroyableChild(parent, child);
+
+  let owner = getOwner(parent);
+
+  if (owner) {
+    setOwner(child, owner);
+  }
+
+  return child;
+}
+
+function linkDecorator(
+  _prototype: object,
+  key: string,
+  descriptor?: Stage1DecoratorDescriptor
+): void {
+  if (!descriptor) return;
+
+  assert(`@link can only be used with string-keys`, typeof key === 'string');
+
+  let { initializer } = descriptor;
+
+  assert(
+    `@link may only be used on initialized properties. For example, ` +
+      `\`@link foo = new MyClass();\``,
+    initializer
+  );
+
+  let caches = new WeakMap<object, any>();
+
+  // https://github.com/pzuraq/ember-could-get-used-to-this/blob/master/addon/index.js
+  return {
+    get(this: object) {
+      let child = caches.get(this);
+
+      if (!child) {
+        child = initializer.call(this);
+
+        associateDestroyableChild(this, child);
+
+        let owner = getOwner(this);
+
+        if (owner) {
+          setOwner(child, owner);
+        }
+
+        caches.set(this, child);
+        assert(`Failed to create cache for internal resource configuration object`, child);
+      }
+
+      return child;
+    },
+  } as unknown as void /* Thanks TS. */;
+}

test-app/tests/link-test.ts

@@ -0,0 +1,54 @@
+import { setOwner } from '@ember/owner';
+import Service, { service } from '@ember/service';
+import { module, test } from 'qunit';
+import { setupTest } from 'ember-qunit';
+
+import { link } from 'ember-resources/link';
+
+module('@link', function (hooks) {
+  setupTest(hooks);
+
+  class FooService extends Service {
+    foo = 2;
+  }
+
+  test('it works', async function (assert) {
+    this.owner.register('service:foo', FooService);
+
+    class Demo {
+      @service declare foo: FooService;
+    }
+
+    class TestDemo {
+      @link(Demo) declare demo: Demo;
+    }
+
+    let testDemo = new TestDemo();
+
+    setOwner(testDemo, this.owner);
+
+    assert.strictEqual(testDemo.demo.foo.foo, 2);
+  });
+});
+
+module('link', function (hooks) {
+  setupTest(hooks);
+
+  class FooService extends Service {
+    foo = 2;
+  }
+
+  test('it works', async function (assert) {
+    this.owner.register('service:foo', FooService);
+
+    class Demo {
+      @service declare foo: FooService;
+    }
+
+    let demo = new Demo();
+
+    link(demo, this);
+
+    assert.strictEqual(demo.foo.foo, 2);
+  });
+});