Release Preview

[github-actions]

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.

Releases

ember-resources@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.

  Migration and Reasoning

  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]);

• #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.

  Migration

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

• #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.

  Example property usage

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

  Example inline usage

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

  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.

  FrameRate

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

  UpdateFrequency

  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.

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 RemoteData: if status is >= 400, isError should be true #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 trackedTask returns last task value if current task value is null or undefined #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 Incorrect value returned when last task was dropped #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