From 16b844e82b641fc55a90e278f06dc2abe6944172 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 14 Jul 2023 10:16:33 -0400 Subject: [PATCH] Update function-based resource in-editor docs --- .changeset/nine-hairs-cry.md | 5 +++++ ember-resources/src/core/class-based/resource.ts | 11 +++++++++++ .../src/core/function-based/resource.ts | 15 +++------------ 3 files changed, 19 insertions(+), 12 deletions(-) create mode 100644 .changeset/nine-hairs-cry.md diff --git a/.changeset/nine-hairs-cry.md b/.changeset/nine-hairs-cry.md new file mode 100644 index 000000000..d14d5f6fd --- /dev/null +++ b/.changeset/nine-hairs-cry.md @@ -0,0 +1,5 @@ +--- +"ember-resources": patch +--- + +Update in-editor docs on the function resource diff --git a/ember-resources/src/core/class-based/resource.ts b/ember-resources/src/core/class-based/resource.ts index 029ed0ee0..3ae0ef7ec 100644 --- a/ember-resources/src/core/class-based/resource.ts +++ b/ember-resources/src/core/class-based/resource.ts @@ -51,6 +51,17 @@ declare const __ResourceArgs__: unique symbol; * which requires that the "State machine interpreter" * is stopped when you are discarding the parent context (such as a component). * + * _When would you reach for the class-based `Resource` instead of the function-based `resource`?_ + * + * - the capabilities of the function-based resource and class-based resource are almost identical. + * the main difference is that function-based resources may represent a single a value + * (which could, itself, be a class instance, or object with properties), + * class-based-resources expose the whole class instance to the consumer. + * + * - function-based resources, however, are much easier to work with and understand, and have + * better intellisense capabilities. + * + * * An example * ```js * import { Resource } from 'ember-resources'; diff --git a/ember-resources/src/core/function-based/resource.ts b/ember-resources/src/core/function-based/resource.ts index 2bd122779..9c9eb9c29 100644 --- a/ember-resources/src/core/function-based/resource.ts +++ b/ember-resources/src/core/function-based/resource.ts @@ -9,8 +9,7 @@ import { wrapForPlainUsage } from './utils'; import type { InternalFunctionResourceConfig, ResourceFn, ResourceFunction } from './types'; /** - * `resource` is an alternative API to the class-based `Resource`. - * It may provide a single read-only value and provides a way to optionally cleanup. + * `resource` provides a single reactive read-only value with lifetime and may have cleanup. * * Arguments passed to the `resource` function: * ```js @@ -31,15 +30,6 @@ import type { InternalFunctionResourceConfig, ResourceFn, ResourceFunction } fro * ); * ``` * - * When would you reach for the class-based `Resource`? - * - the capabilities of the function-based resource and class-based resource are identical, - * with the exception that function-based resources may represent a single value, rather than - * an object with properties/methods (the only option with class-based resources) - * - * A function-resource - * - _must_ return a value. - * - cannot, itself, be async - but can interact with promises and update a value - * * Example using `fetch` + `AbortController` * ```js * import { use, resource } from 'ember-resources'; @@ -80,7 +70,8 @@ import type { InternalFunctionResourceConfig, ResourceFn, ResourceFunction } fro * * * Example using strict mode + `