ember-resources

ember-resources

An implementation of the Resource pattern in Ember.JS.

• Installation
• What is a Resource?
• API Documentation

• Contributing
• Thanks

Compatibility

• ember-source v3.25+
• typeScript v4.2+
• ember-auto-import v2+

Installation

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

Example

import { trackedFunction } from 'ember-resources';

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.

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.

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