ember-resources

ember-resources

An implementation of the Resource pattern in Ember.JS.

• Installation
• What is a Resource?
• API Documentation
• Docs on the Primitives
• Testing
• Cookbook
• Contributing
• Thanks

Compatibility

• ember-source v3.28+
• typescript v4.8+
• ember-auto-import v2+
• Glint v1.0.0-beta.3+

Installation

npm install ember-resources
# or
yarn add ember-resources
# or
ember install ember-resources

Or if you want to use main (unstable) from git, you can use this in your package.json:

"ember-resources": "github:NullVoxPopuli/ember-resources#dist"

Which comes from this branch from this automation

See: API Documentation for more examples.

Example (async utility)

import { trackedFunction } from 'ember-resources/util/function';

class MyClass {
  @tracked endpoint = 'starships';

  data = trackedFunction(this, async () => {
    let response = await fetch(`https://swapi.dev/api/${this.endpoint}`);
    let json = await response.json();

    return json.results;
  });

  get records() {
    return this.data.value ?? [];
  }
}

{{this.records}}

In this example, trackedFunction will make a call to StarWars API and if endpoint changes from starships to planets, the trackedFunction will automatically re-call the StarWars API to fetch the planets.

Example (function-based resource)

Visit the docs on function-based resources.

This alternate API is more general-purpose, but has the same behavior as the above example.

import { resource, use } from 'ember-resources';
import { TrackedObject } from 'tracked-built-ins';

class MyClass {
  @tracked endpoint = 'starships';

  @use load = resource(({ on }) => {
    let state = new TrackedObject({});
    let controller = new AbortController();

    on.cleanup(() => controller.abort());

    fetch(`https://swapi.dev/api/${this.endpoint}`, { signal: controller.signal })
      .then(response => response.json())
      .then(data => {
        state.value = data;
        // ...
      })
      .catch(error => {
        state.error = error;
        // ...
      });

    return state;
  });
}

{{#if this.load.value}}
  ...
{{else if this.load.error}}
  {{this.load.error}}
{{/if}}

What is a Resource?

Resources [...] bridge a gap between imperative programming and declarative programming.

Ember templates are declarative. When we design a component [...] we are specifying declaratively the HTML that should be rendered. If the data used in the templates ever updates, then Ember will update the rendered output as well, and we don't have to worry about the details. We don't have to tell Ember which specific steps to take, and when - it figures everything out for us.

pzuraq on "Introducing @use"

So.. what is a [[Resource]], really?

A Resource is a behavior that can be used in both templates and javascript.

In JavaScript

A Resource is an alternate API for

import { cached } from '@glimmer/tracking';
import { SomeClass } from '../somewhere';

class A {
  @cached
  get myResource() {
    return new SomeClass(this.args.foo)
  }
}

In this example, myResource returns an instance of a class and will re-create that class if @foo changes. That class can have its own internal state.

This requires at least 2 imports and 4 lines of code.

In Templates

A Resource is a stateful helper:

{{#let (my-resource @foo) as |someClassInstance|}}
  {{!-- ... --}}
{{/let}}

In this example, my-resource returns an instance of a class and will re-create that class if @foo changes. That class can have its own internal state and is available for use via the local variable myResource.

This requires a stateful helper by globally available to your app. Helpers are typically stateless, so this would go against most guidance on helpers.

Debugging and working with Resources

More information contained in the docs folder.

High-fidelity sourcemaps are provided in the original typescript. However, you must be using embroider to take advantage of them. Sourcemaps should work with ember-auto-import@v2+ in non-embroider builds as well, but is untested.

Note, ember-resources is not guaranteed to be compatible with usage within @computed getters. Only auto-tracking is supported.

Related addons

List of addons that use and wrap ember-resources to provide more specific functionality:

• ember-data-resources - resources for reactive data fetching with ember-data
• ember-use-sound - a resource for interacting with audio files

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.

Thanks

This library wouldn't be possible without the work of:

• @pzuraq

• @josemarluedke

• More information on Resources

• Inspiration, ember-could-get-used-to-this

So much appreciate for the work both you have put in to Resources <3

---

This is a V2-format Addon with V1 compatibility

Changelog

6.0.0

Major Changes

• #715 e8155b2 Thanks @NullVoxPopuli! - Drop support for TypeScript < 4.8 in order to support Glint.

• #778 901ae9a Thanks @NullVoxPopuli! - The map utility resource has changed its first type-argument for better inference.

  The utility already supported inference, so this change should not impact too many folks.

  <details><summary>Migration and Reasoning</summary>

  When explicit type-arguments were specified,

  class Demo {
    // previously
    a = map<Element>(this, {
      data: () => [
        /* ... list of Element(s) ... */
      ],
      map: (element) => {
        /* some transform */
      },
    });
  
    // now
    a = map<Element[]>(this, {
      data: () => [
        /* ... list of Element(s) ... */
      ],
      map: (element) => {
        /* some transform */
      },
    });
  }
  

  This is advantageous, because with @tsconfig/ember, the option noUncheckedIndexedAccess is enabled by default. This is a great strictness / quality option to have enabled, as arrays in javascript are mutable, and we can't guarantee that they don't change between index-accesses.

  However the map utility resource explicitly disallows the indicies to get out of sync with the source data.

  But!, with noUncheckedIndexedAccess, you can only infer so much before TS goes the safe route, and makes the returned type X | undefined.

  For example, in these type-tests:

  import { map } from "ember-resources/util/map";
  import { expectType } from "ts-expect";
  
  const constArray = [1, 2, 3];
  
  b = map(this, {
    data: () => constArray,
    map: (element) => {
      expectType<number>(element);
      return element;
    },
  });
  
  // index-access here is *safely* `| undefined`, due to `constArray` being mutable.
  expectType<number | undefined>(b[0]);
  expectType<number | undefined>(b.values()[0]);
  
  // but when we use a const as const array, we define a tuple,
  // and can correctly infer and return real values via index access
  const tupleArray = [1, 2, 3] as const;
  
  c = map(this, {
    data: () => tupleArray,
    map: (element) => {
      expectType<number>(element);
      return element;
    },
  });
  
  // No `| undefined` here
  expectType<number>(c[0]);
  expectType<number>(c.values()[0]);
  

  </details>

• #815 54e2b50 Thanks @NullVoxPopuli! - The RemoteData resource now has the same state changes and semantics as trackedFunction.

  Breaking Changes:

  • isResolved is only true when the request succeeds. During migration, you may use isFinished for previous behavior.

• #779 a471d9b Thanks @NullVoxPopuli! - trackedFunction has a new API and thus a major version release is required.

  Work by @lolmaus

  tl;dr: the breaking changes:

  • no more manual initial value
  • isResolved is only true on success

  other changes:

  • trackedFunction is a wrapper around ember-async-data's TrackedAsyncData
    • ember-async-data will need to be installed in the consumer's app to continue using trackedFunction This keeps installs minimal for folks using ember-resources and are not using trackedFunction
  • behavior is otherwise the same

  NOTE: trackedFunction is an example utility of how to use auto-tracking with function invocation, and abstract away the various states involved with async behavior. Now that the heavy lifting is done by ember-async-data, trackedFunction is now more of an example of how to integrated existing tracked utilities in to resources.

  <details><summary>Migration</summary>

  Previously, the state's isResolved property on trackedFunction was true on both success and error.

  now, isFinished can be used instead. isResolved is now only true when the function runs to completion without error, aligning with the semantics of promises.

  class Demo {
    foo = trackedFunction(this, async () => {
      /* ... */
    });
  
    <template>
      {{this.foo.isFinished}} =
        {{this.foo.isResolved}} or
        {{this.foo.isError}}
    </template>
  }
  

  Previously, trackedFunction could take an initial value for its second argument.

  class Demo {
    foo = trackedFunction(this, "initial value", async () => {
      /* ... */
    });
  }
  

  This has been removed, as initial value can be better maintained and made more explicit in user-space. For example:

  class Demo {
    foo = trackedFunction(this, async () => {
      /* ... */
    });
  
    get value() {
      return this.foo.value ?? "initial value";
    }
  }
  

  Or, in a template:

  {{#if this.foo.value}}
    {{this.foo.value}}
  {{else}}
    initial displayed content
  {{/if}}
  

  Or, in gjs/strict mode:

  const withDefault = (value) => value ?? 'initial value';
  
  class Demo extends Component {
    foo = trackedFunction(this, async () => { /* ... */ });
  
    <template>
      {{withDefault this.foo.value}}
    </template>
  }
  

  </details>

• #785 66cee0e Thanks @NullVoxPopuli! - The import path ember-resources/util/function-resource has been removed, as all the relevent exports have been available from ember-resources since v5.

Minor Changes

• #797 18adb86 Thanks @NullVoxPopuli! - 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>

  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>

  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:

  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;
    }
  }
  

• #778 f841a98 Thanks @NullVoxPopuli! - Use strictest possible settings with TypeScript so that consumers can't be stricter than this library

• #776 a99793e Thanks @NullVoxPopuli! - Glint is now supported starting with 1.0.0-beta.3

• #818 feeb2db Thanks @NullVoxPopuli! - RemoteData now checks the response's Content-Type header to decide whether to convert to JSON or Text

• #794 8989bbb Thanks @NullVoxPopuli! - New Utils: UpdateFrequency and FrameRate

  NOTE: for existing users of ember-resources, this addition has no impact on your bundle.

  <details><summary>FrameRate</summary>

  Utility that uses requestAnimationFrame to report how many frames per second the current monitor is rendering at.

  The result is rounded to two decimal places.

  import { FramRate } from "ember-resources/util/fps";
  
  <template>{{ FrameRate }}</template>;
  

  </details> <details><summary>UpdateFrequency</summary>

  Utility that will report the frequency of updates to tracked data.

  import { UpdateFrequency } from 'ember-resources/util/fps';
  
  export default class Demo extends Component {
    @tracked someProp;
  
    @use updateFrequency = UpdateFrequency(() => this.someProp);
  
    <template>
      {{this.updateFrequency}}
    </template>
  }
  

  NOTE: the function passed to UpdateFrequency may not set tracked data.

  </details>

Patch Changes

• #769 abaad4a Thanks @GreatWizard! - fix typo in map error message when checking if every datum is an object

• #828 24b540e Thanks @NullVoxPopuli! - ember-async-data@v1 is out, so since we're just now using it, that can be the minimum version. NOTE: ember-async-data's minimum ember-source is 4.8, so while things might work with earlier ember-source's it's not guaranteed.

• #826 50ad1ba Thanks @NullVoxPopuli! - When using RemoteData, isError should be true when the http status code is >= 400. Resolves #825". Previously, when you had a JSON response with 404 status code, isError would be false instead of true.

• #865 6df54b1 Thanks @NullVoxPopuli! - Add the last v4 LTS, ember-source v4.12, to the test matrix

• #806 00e8f2f Thanks @sergey-zhidkov! - trackedTask must return correct last value.

  Fixes the issue described at #793 If the task was called multiple times and the last returned value was null or undefined, then trackedTask will return the previous value instead of the current one.

• #838 acbf03d Thanks @NullVoxPopuli! - Fixes #835 - resolves regression introduced by PR: #808 which aimed to correctly return the previous task instance's value if the current task hasn't finished yet. The regression described by #835 was that if a task in cancelled (e.g.: dropped), it is considered finished, and that canceled task's value would be used instead of the last compuleted task. In normal ember-concurrency APIs, this is abstracted over via the .lastSuccessful property on the TaskProperty. The goal of the .value on trackedTask is to mimic the property chain: taskProperty.lastSuccessful?.value.

• #830 0767c08 Thanks @NullVoxPopuli! - Support TS 5.0

• #868 b6f78c9 Thanks @NullVoxPopuli! - Test against ember-concurrency@v3, and add it as an allowed peerDepnedency