Nana's Plush Muppet

    ember-resources
    TypeScript icon, indicating that this package has built-in type declarations

    5.6.2 • Public • Published

    ember-resources

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

    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:

    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

    Keywords

    Install

    npm i ember-resources

    DownloadsWeekly Downloads

    14,790

    Version

    5.6.2

    License

    MIT

    Unpacked Size

    298 kB

    Total Files

    105

    Last publish

    Collaborators

    • nullvoxpopuli