Skip to content

Latest commit

 

History

History
142 lines (98 loc) · 4.47 KB

README.md

File metadata and controls

142 lines (98 loc) · 4.47 KB

ember-resources

npm version CI An implementation of the Resource pattern in Ember.JS.

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.

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-array-map-resource - provides a useArrayMap function which returns a resource that reactively maps data per-element, so that when the overall collection is dirtied, only the changed/new/removed elements affect the mapped collection
  • 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:

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

This is a V2-format Addon with V1 compatibility