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.5+
• ember-auto-import v2+
• Glint 0.8.3+
  • Note that updates to glint support will not be covered by this library's adherance to SemVer. All glint-related updates will be bugfixes until Glint is declared stable.

Installation

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

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

5.2.2 (2022-08-27)

Bug Fixes

• cell: improve typings of the cell utility (5e3229d)