enhance: createResource() -> resource() (#3158)

reactive · Jul 21, 2024 · 34e2e51 · 34e2e51
1 parent 8003ebb
commit 34e2e51
Show file tree

Hide file tree

Showing 67 changed files with 329 additions and 317 deletions.
diff --git a/.changeset/silent-bananas-relax.md b/.changeset/silent-bananas-relax.md
@@ -0,0 +1,7 @@
+---
+'@data-client/rest': patch
+---
+
+createResource() -> [resource()](https://dataclient.io/rest/api/resource)
+
+Note: `createResource` is still exported (it is the same)
diff --git a/README.md b/README.md
@@ -70,13 +70,13 @@ class Article extends Entity {
 ### Create [collection of API Endpoints](https://dataclient.io/docs/getting-started/resource)
 
 ```typescript
-const UserResource = createResource({
+const UserResource = resource({
   path: '/users/:id',
   schema: User,
   optimistic: true,
 });
 
-const ArticleResource = createResource({
+const ArticleResource = resource({
   path: '/articles/:id',
   schema: Article,
   searchParams: {} as { author?: string },
@@ -276,7 +276,7 @@ For the small price of 9kb gziped. &nbsp;&nbsp; [🏁Get started now](https://da
 
 - Networking definition
   - [Endpoints](https://dataclient.io/rest/api/Endpoint): [RestEndpoint](https://dataclient.io/rest/api/RestEndpoint), [GQLEndpoint](https://dataclient.io/graphql/api/GQLEndpoint)
-  - [Resources](https://dataclient.io/docs/getting-started/resource): [createResource()](https://dataclient.io/rest/api/createResource), [hookifyResource()](https://dataclient.io/rest/api/hookifyResource)
+  - [Resources](https://dataclient.io/docs/getting-started/resource): [resource()](https://dataclient.io/rest/api/resource), [hookifyResource()](https://dataclient.io/rest/api/hookifyResource)
 - [Data model](https://dataclient.io/docs/concepts/normalization)
   - [Entity](https://dataclient.io/rest/api/Entity), [schema.Entity](https://dataclient.io/rest/api/schema.Entity) mixin, [GQLEntity](https://dataclient.io/graphql/api/GQLEntity)
   - [Object](https://dataclient.io/rest/api/Object)

diff --git a/__tests__/new.ts b/__tests__/new.ts
@@ -1,7 +1,7 @@
 import {
   schema,
   Endpoint,
-  createResource,
+  resource,
   RestEndpoint,
   Schema,
   Entity,
@@ -78,7 +78,7 @@ export class VisEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {
     return super.getRequestInit(body);
   }
 }
-const VisSettingsResourceBase = createResource({
+const VisSettingsResourceBase = resource({
   path: 'http\\://test.com/vis-settings/:id',
   schema: VisSettings,
   Endpoint: VisEndpoint,
@@ -114,7 +114,7 @@ export const VisSettingsResource = {
     },
   }),
 };
-const VisSettingsResourceBaseFromMixin = createResource({
+const VisSettingsResourceBaseFromMixin = resource({
   path: 'http\\://test.com/vis-settings/:id',
   schema: VisSettingsFromMixin,
   Endpoint: VisEndpoint,
@@ -167,7 +167,7 @@ export class User extends Entity {
     return this.id?.toString();
   }
 }
-export const UserResource = createResource({
+export const UserResource = resource({
   path: 'http\\://test.com/user/:id',
   schema: User,
 });
@@ -207,15 +207,15 @@ export class ArticleFromMixin extends schema.Entity(ArticleData, {
 class ArticleEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {}
 
 interface ArticleGenerics {
-  /** @see https://dataclient.io/rest/api/createResource#path */
+  /** @see https://dataclient.io/rest/api/resource#path */
   readonly path?: string;
-  /** @see https://dataclient.io/rest/api/createResource#schema */
+  /** @see https://dataclient.io/rest/api/resource#schema */
   readonly schema: Schema;
   /** Only used for types */
-  /** @see https://dataclient.io/rest/api/createResource#body */
+  /** @see https://dataclient.io/rest/api/resource#body */
   readonly body?: any;
   /** Only used for types */
-  /** @see https://dataclient.io/rest/api/createResource#searchParams */
+  /** @see https://dataclient.io/rest/api/resource#searchParams */
   readonly searchParams?: any;
 }
 function createArticleResource<O extends ArticleGenerics>({
@@ -237,7 +237,7 @@ function createArticleResource<O extends ArticleGenerics>({
   > extends Endpoint<O> {
     urlPrefix = `http://test.com/${urlRoot}`;
   }
-  const resource = createResource({
+  const BaseResource = resource({
     path: '/:id',
     schema,
     Endpoint: EndpointUrlRootOverride,
@@ -256,7 +256,7 @@ function createArticleResource<O extends ArticleGenerics>({
       }),
     }));
   if (!optimistic) {
-    return (resource as any).extend({
+    return (BaseResource as any).extend({
       partialUpdate: {
         getOptimisticResponse: (snap, params, body) => ({
           id: params.id,
@@ -268,7 +268,7 @@ function createArticleResource<O extends ArticleGenerics>({
       },
     });
   }
-  return resource as any;
+  return BaseResource as any;
 }
 export const ArticleResource = createArticleResource({ schema: Article });
 export const ArticleSlugResource = createArticleResource({
@@ -277,7 +277,7 @@ export const ArticleSlugResource = createArticleResource({
 
 export const AuthContext = createContext('');
 
-const ContextAuthdArticleResourceBase = createResource({
+const ContextAuthdArticleResourceBase = resource({
   path: 'http\\://test.com/article/:id',
   schema: Article,
 });
@@ -527,7 +527,7 @@ export const CoolerArticleDetail = new Endpoint(
 export class IndexedUser extends User {
   static readonly indexes = ['username'];
 }
-export const IndexedUserResource = createResource({
+export const IndexedUserResource = resource({
   path: 'http\\://test.com/user/:id',
   schema: IndexedUser,
 });
@@ -642,7 +642,7 @@ export const UnionSchema = new schema.Union(
   },
   'type',
 );
-const UnionResourceBase = createResource({
+const UnionResourceBase = resource({
   path: '/union/:id',
   schema: UnionSchema,
 });

diff --git a/docs/core/README.md b/docs/core/README.md
@@ -336,10 +336,10 @@ At this point we've defined `todoDetail`, `todoList` and `todoUpdate`. You might
 that these endpoint definitions share some logic and information. For this reason Reactive Data Client
 encourages extracting shared logic among endpoints.
 
-[Resources](/rest/api/createResource) are collections of endpoints that operate on the same data.
+[Resources](/rest/api/resource) are collections of endpoints that operate on the same data.
 
 ```typescript
-import { Entity, createResource } from '@data-client/rest';
+import { Entity, resource } from '@data-client/rest';
 
 class Todo extends Entity {
   id = 0;
@@ -352,7 +352,7 @@ class Todo extends Entity {
   }
 }
 
-const TodoResource = createResource({
+const TodoResource = resource({
   urlPrefix: 'https://jsonplaceholder.typicode.com',
   path: '/todos/:id',
   schema: Todo,

diff --git a/docs/core/api/Controller.md b/docs/core/api/Controller.md
@@ -257,7 +257,7 @@ To refresh while continuing to display stale data - [Controller.fetch](#fetch).
 
 Use [schema.Invalidate](/rest/api/Invalidate) to invalidate every endpoint that contains a given entity.
 
-For REST try using [Resource.delete](/rest/api/createResource#delete)
+For REST try using [Resource.delete](/rest/api/resource#delete)
 
 ```ts
 // deletes MyResource(5)

diff --git a/docs/core/api/useCache.md b/docs/core/api/useCache.md
@@ -31,7 +31,7 @@ delay: 500,
 ]} row>
 
 ```ts title="UserResource" collapsed
-import { Entity, createResource } from '@data-client/rest';
+import { Entity, resource } from '@data-client/rest';
 
 export class User extends Entity {
   id = '';
@@ -42,7 +42,7 @@ export class User extends Entity {
   }
   static key = 'User';
 }
-export const UserResource = createResource({
+export const UserResource = resource({
   path: '/users/:id',
   schema: User,
 }).extend('current', {
@@ -115,7 +115,7 @@ more information about type handling
 
 | Expiry Status | Returns      | Conditions                                                                                                                                                                   |
 | ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Invalid       | `undefined`  | not in store, [deletion](/rest/api/createResource#delete), [invalidation](./Controller.md#invalidate), [invalidIfStale](../concepts/expiry-policy.md#endpointinvalidifstale) |
+| Invalid       | `undefined`  | not in store, [deletion](/rest/api/resource#delete), [invalidation](./Controller.md#invalidate), [invalidIfStale](../concepts/expiry-policy.md#endpointinvalidifstale) |
 | Stale         | denormalized | (first-render, arg change) & [expiry &lt; now](../concepts/expiry-policy.md)                                                                                                 |
 | Valid         | denormalized | fetch completion                                                                                                                                                             |
 |               | `undefined`  | `null` used as second argument                                                                                                                                               |

diff --git a/docs/core/api/useDLE.md b/docs/core/api/useDLE.md
@@ -26,7 +26,7 @@ In case you cannot use [suspense](../getting-started/data-dependency.md#async-fa
 <HooksPlayground fixtures={listFixtures} row>
 
 ```typescript title="ProfileResource" collapsed
-import { Entity, createResource } from '@data-client/rest';
+import { Entity, resource } from '@data-client/rest';
 
 export class Profile extends Entity {
   id: number | undefined = undefined;
@@ -40,7 +40,7 @@ export class Profile extends Entity {
   static key = 'Profile';
 }
 
-export const ProfileResource = createResource({
+export const ProfileResource = resource({
   path: '/profiles/:id',
   schema: Profile,
 });
@@ -77,7 +77,7 @@ render(<ProfileList />);
 
 | Expiry Status | Fetch           | Data         | Loading | Error             | Conditions                                                                                                                                                                   |
 | ------------- | --------------- | ------------ | ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Invalid       | yes<sup>1</sup> | `undefined`  | true    | false             | not in store, [deletion](/rest/api/createResource#delete), [invalidation](./Controller.md#invalidate), [invalidIfStale](../concepts/expiry-policy.md#endpointinvalidifstale) |
+| Invalid       | yes<sup>1</sup> | `undefined`  | true    | false             | not in store, [deletion](/rest/api/resource#delete), [invalidation](./Controller.md#invalidate), [invalidIfStale](../concepts/expiry-policy.md#endpointinvalidifstale) |
 | Stale         | yes<sup>1</sup> | denormalized | false   | false             | (first-render, arg change) & [expiry &lt; now](../concepts/expiry-policy.md)                                                                                                 |
 | Valid         | no              | denormalized | false   | maybe<sup>2</sup> | fetch completion                                                                                                                                                             |
 |               | no              | `undefined`  | false   | false             | `null` used as second argument                                                                                                                                               |
@@ -140,7 +140,7 @@ function useDLE<
 <HooksPlayground fixtures={detailFixtures} row>
 
 ```typescript title="ProfileResource" collapsed
-import { Entity, createResource } from '@data-client/rest';
+import { Entity, resource } from '@data-client/rest';
 
 export class Profile extends Entity {
   id: number | undefined = undefined;
@@ -154,7 +154,7 @@ export class Profile extends Entity {
   static key = 'Profile';
 }
 
-export const ProfileResource = createResource({
+export const ProfileResource = resource({
   path: '/profiles/:id',
   schema: Profile,
 });
@@ -194,7 +194,7 @@ render(<ProfileDetail />);
 <TypeScriptEditor row={false}>
 
 ```ts title="Resources" collapsed
-import { Entity, createResource } from '@data-client/rest';
+import { Entity, resource } from '@data-client/rest';
 
 export class Post extends Entity {
   id = 0;
@@ -207,7 +207,7 @@ export class Post extends Entity {
   }
   static key = 'Post';
 }
-export const PostResource = createResource({
+export const PostResource = resource({
   path: '/posts/:id',
   schema: Post,
 });
@@ -229,7 +229,7 @@ export class User extends Entity {
   }
   static key = 'User';
 }
-export const UserResource = createResource({
+export const UserResource = resource({
   urlPrefix: 'https://jsonplaceholder.typicode.com',
   path: '/users/:id',
   schema: User,

diff --git a/docs/core/api/useFetch.md b/docs/core/api/useFetch.md
@@ -37,7 +37,7 @@ function MasterPost({ id }: { id: number }) {
 
 | Expiry Status | Fetch           | Returns     | Conditions                                                                                            |
 | ------------- | --------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
-| Invalid       | yes<sup>1</sup> | Promise     | not in store, [deletion](/rest/api/createResource#delete), [invalidation](./Controller.md#invalidate) |
+| Invalid       | yes<sup>1</sup> | Promise     | not in store, [deletion](/rest/api/resource#delete), [invalidation](./Controller.md#invalidate) |
 | Stale         | yes<sup>1</sup> | Promise     | (first-render, arg change) & [expiry &lt; now](../concepts/expiry-policy.md)                          |
 | Valid         | no              | `undefined` | fetch completion                                                                                      |
 |               | no              | `undefined` | `null` used as second argument                                                                        |

diff --git a/docs/core/api/useQuery.md b/docs/core/api/useQuery.md
@@ -100,7 +100,7 @@ export class User extends Entity {
   }
   static key = 'User';
 }
-export const UserResource = createResource({
+export const UserResource = resource({
   path: '/users/:id',
   schema: User,
 });

diff --git a/docs/core/api/useSuspense.md b/docs/core/api/useSuspense.md
@@ -44,7 +44,7 @@ values={[
 <HooksPlayground fixtures={detailFixtures} row>
 
 ```typescript title="ProfileResource" collapsed
-import { Entity, createResource } from '@data-client/rest';
+import { Entity, resource } from '@data-client/rest';
 
 export class Profile extends Entity {
   id: number | undefined = undefined;
@@ -58,7 +58,7 @@ export class Profile extends Entity {
   static key = 'Profile';
 }
 
-export const ProfileResource = createResource({
+export const ProfileResource = resource({
   path: '/profiles/:id',
   schema: Profile,
 });
@@ -139,7 +139,7 @@ Cache policy is [Stale-While-Revalidate](https://tools.ietf.org/html/rfc5861) by
 
 | Expiry Status | Fetch           | Suspend | Error             | Conditions                                                                                                                                                                   |
 | ------------- | --------------- | ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Invalid       | yes<sup>1</sup> | yes     | no                | not in store, [deletion](/rest/api/createResource#delete), [invalidation](./Controller.md#invalidate), [invalidIfStale](../concepts/expiry-policy.md#endpointinvalidifstale) |
+| Invalid       | yes<sup>1</sup> | yes     | no                | not in store, [deletion](/rest/api/resource#delete), [invalidation](./Controller.md#invalidate), [invalidIfStale](../concepts/expiry-policy.md#endpointinvalidifstale) |
 | Stale         | yes<sup>1</sup> | no      | no                | (first-render, arg change) & [expiry &lt; now](../concepts/expiry-policy.md)                                                                                                 |
 | Valid         | no              | no      | maybe<sup>2</sup> | fetch completion                                                                                                                                                             |
 |               | no              | no      | no                | `null` used as second argument                                                                                                                                               |
@@ -196,7 +196,7 @@ function useSuspense<
 <HooksPlayground fixtures={listFixtures} row>
 
 ```typescript title="ProfileResource" collapsed
-import { Entity, createResource } from '@data-client/rest';
+import { Entity, resource } from '@data-client/rest';
 
 export class Profile extends Entity {
   id: number | undefined = undefined;
@@ -210,7 +210,7 @@ export class Profile extends Entity {
   static key = 'Profile';
 }
 
-export const ProfileResource = createResource({
+export const ProfileResource = resource({
   path: '/profiles/:id',
   schema: Profile,
 });
@@ -268,7 +268,7 @@ function PostWithAuthor() {
 <TypeScriptEditor row={false}>
 
 ```ts title="Resources" collapsed
-import { Entity, createResource } from '@data-client/rest';
+import { Entity, resource } from '@data-client/rest';
 
 export class Post extends Entity {
   id = 0;
@@ -281,7 +281,7 @@ export class Post extends Entity {
   }
   static key = 'Post';
 }
-export const PostResource = createResource({
+export const PostResource = resource({
   path: '/posts/:id',
   schema: Post,
 });
@@ -303,7 +303,7 @@ export class User extends Entity {
   }
   static key = 'User';
 }
-export const UserResource = createResource({
+export const UserResource = resource({
   urlPrefix: 'https://jsonplaceholder.typicode.com',
   path: '/users/:id',
   schema: User,

diff --git a/docs/core/concepts/atomic-mutations.md b/docs/core/concepts/atomic-mutations.md
@@ -24,14 +24,14 @@ Reactive Data Client uses your schema definitions to understand how to normalize
 an `entity table` and `result table`. Of course, this means that there is only ever one copy
 of a given `entity`. Aside from providing consistency when using different response endpoints,
 this means that by providing an accurate schema definition, Reactive Data Client can automatically keep
-all data uses consistent and fresh. The default update endpoints [Resource.update](/rest/api/createResource#update) and
-[Resource.partialUpdate](/rest/api/createResource#partialupdate) both do this automatically. [Read more about defining other
+all data uses consistent and fresh. The default update endpoints [Resource.update](/rest/api/resource#update) and
+[Resource.partialUpdate](/rest/api/resource#partialupdate) both do this automatically. [Read more about defining other
 update endpoints](/rest/guides/side-effects)
 
 ## Delete
 
 Reactive Data Client automatically deletes entity entries [schema.Invalidate](/rest/api/Invalidate) is used.
-[Resource.delete](/rest/api/createResource#delete)
+[Resource.delete](/rest/api/resource#delete)
 provides such an endpoint.
 
 ## Create