enhance: schema.Entity -> EntityMixin (#3243)

reactive · Oct 13, 2024 · 43a955c · 43a955c
1 parent f81737c
commit 43a955c
Show file tree

Hide file tree

Showing 30 changed files with 272 additions and 271 deletions.
diff --git a/.changeset/four-terms-leave.md b/.changeset/four-terms-leave.md
@@ -0,0 +1,5 @@
+---
+'@data-client/normalizr': patch
+---
+
+Update README to link to [EntityMixin](https://dataclient.io/rest/api/EntityMixin)
diff --git a/.changeset/wise-seals-cross.md b/.changeset/wise-seals-cross.md
@@ -0,0 +1,22 @@
+---
+'@data-client/endpoint': patch
+'@data-client/graphql': patch
+'@data-client/rest': patch
+---
+
+`schema.Entity` -> [EntityMixin](https://dataclient.io/rest/api/EntityMixin)
+
+```ts
+import { EntityMixin } from '@data-client/rest';
+
+export class Article {
+  id = '';
+  title = '';
+  content = '';
+  tags: string[] = [];
+}
+
+export class ArticleEntity extends EntityMixin(Article) {}
+```
+
+We keep `schema.Entity` for legacy, and add schema.EntityMixin and [EntityMixin](https://dataclient.io/rest/api/EntityMixin) as direct export
diff --git a/README.md b/README.md
@@ -373,7 +373,7 @@ For the small price of 9kb gziped. &nbsp;&nbsp; [🏁Get started now](https://da
 <tbody><tr>
 <td rowSpan="4"><a href="https://en.wikipedia.org/wiki/Object_(computer_science)">Object</a></td>
 <td align="center">✅</td>
-<td><a href="https://dataclient.io/rest/api/Entity">Entity</a>, <a href="https://dataclient.io/rest/api/schema.Entity">schema.Entity</a> mixin</td>
+<td><a href="https://dataclient.io/rest/api/Entity">Entity</a>, <a href="https://dataclient.io/rest/api/EntityMixin">EntityMixin</a></td>
 <td>single <em>unique</em> object</td>
 <td align="center">✅</td>
 </tr>

diff --git a/__tests__/new.ts b/__tests__/new.ts
@@ -1,19 +1,21 @@
+import { Temporal } from '@js-temporal/polyfill';
+import React, { createContext, useContext } from 'react';
+
 import {
   schema,
   Endpoint,
   resource,
   RestEndpoint,
   Schema,
   Entity,
+  EntityMixin,
   RestGenerics,
   hookifyResource,
   RestType,
   RestInstance,
   Resource,
   ResourceOptions,
 } from '@data-client/rest';
-import { Temporal } from '@js-temporal/polyfill';
-import React, { createContext, useContext } from 'react';
 
 /** Represents data with primary key being from 'id' field. */
 export class IDEntity extends Entity {
@@ -44,7 +46,7 @@ export class VisSettings extends Entity implements Vis {
 
   static key = 'VisSettings';
 }
-export class VisSettingsFromMixin extends schema.Entity(Vis) {
+export class VisSettingsFromMixin extends EntityMixin(Vis) {
   static cmpIncoming(
     existingMeta: { date: number; fetchedAt: number },
     incomingMeta: { date: number; fetchedAt: number },
@@ -179,7 +181,7 @@ class ArticleData {
   readonly author: User | null = null;
   readonly tags: string[] = [];
 }
-export class ArticleFromMixin extends schema.Entity(ArticleData, {
+export class ArticleFromMixin extends EntityMixin(ArticleData, {
   schema: { author: User },
 }) {}
 class ArticleEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {}

diff --git a/docs/core/getting-started/resource.md b/docs/core/getting-started/resource.md
@@ -139,7 +139,7 @@ export const TodoResource = {
   <PkgInstall pkgs="@data-client/endpoint" />
 
 Pre-existing TypeScript definitions can be used in <abbr title="Reactive Data Client">Data Client</abbr> with
-[Endpoint](/rest/api/Endpoint) and [schema.Entity](/rest/api/schema.Entity).
+[Endpoint](/rest/api/Endpoint) and [EntityMixin](/rest/api/EntityMixin).
 
 <TypeScriptEditor row={false}>
 
@@ -187,7 +187,7 @@ export const deleteTodo = (body: Partial<Todo>) =>
 ```
 
 ```typescript title="TodoResource"
-import { schema, Endpoint } from '@data-client/endpoint';
+import { schema, EntityMixin, Endpoint } from '@data-client/endpoint';
 import {
   Todo,
   getTodo,
@@ -198,7 +198,7 @@ import {
   deleteTodo,
 } from './existing/Todo';
 
-export const TodoEntity = schema.Entity(Todo, { key: 'Todo' });
+export const TodoEntity = EntityMixin(Todo, { key: 'Todo' });
 
 export const TodoResource = {
   get: new Endpoint(getTodo, { schema: TodoEntity }),
@@ -289,5 +289,5 @@ To aid in defining `Resources`, composable and extensible protocol specific help
 [Image/binary](../guides/img-media.md), [Websockets+SSE](../concepts/managers.md#data-stream).
 
 To use existing API definitions, or define your own protocol specific helpers, use
-[Endpoint](/rest/api/Endpoint) and [schema.Entity](/rest/api/schema.Entity) from [@data-client/endpoint](https://www.npmjs.com/package/@data-client/endpoint).
+[Endpoint](/rest/api/Endpoint) and [EntityMixin](/rest/api/EntityMixin) from [@data-client/endpoint](https://www.npmjs.com/package/@data-client/endpoint).
 [See `Async/Promise` tab above]
diff --git a/docs/core/shared/_VoteDemo.mdx b/docs/core/shared/_VoteDemo.mdx
@@ -16,7 +16,7 @@ export class Post extends Entity {
   static key = 'Post';
 
   static schema = {
-    author: schema.Entity(
+    author: EntityMixin(
       class User {
         id = 0;
       },

diff --git a/docs/rest/README.md b/docs/rest/README.md
@@ -82,17 +82,17 @@ export const ArticleResource = resource({
 <TypeScriptEditor>
 
 ```typescript title="User" collapsed
-import { schema } from '@data-client/rest';
+import { EntityMixin } from '@data-client/rest';
 
 export class User {
   id = '';
   username = '';
 }
-export class UserEntity extends schema.Entity(User) {}
+export class UserEntity extends EntityMixin(User) {}
 ```
 
 ```typescript title="Article"
-import { schema, resource } from '@data-client/rest';
+import { EntityMixin, resource } from '@data-client/rest';
 import { UserEntity } from './User';
 
 export class Article {
@@ -104,7 +104,7 @@ export class Article {
   createdAt = Temporal.Instant.fromEpochSeconds(0);
 }
 
-export class ArticleEntity extends schema.Entity(Article, {
+export class ArticleEntity extends EntityMixin(Article, {
   schema: {
     author: UserEntity,
     createdAt: Temporal.Instant.from,

diff --git a/docs/rest/api/Entity.md b/docs/rest/api/Entity.md
@@ -95,7 +95,7 @@ Entities are bound to Endpoints using [resource.schema](./resource.md#schema) or
 
 :::tip
 
-If you already have your classes defined, [schema.Entity](./schema.Entity.md) mixin can also be
+If you already have your classes defined, [EntityMixin](./EntityMixin.md) mixin can also be
 used to make Entities.
 
 :::

diff --git a/docs/rest/api/schema.Entity.md → docs/rest/api/EntityMixin.md b/docs/rest/api/schema.Entity.md → docs/rest/api/EntityMixin.md
@@ -1,6 +1,6 @@
 ---
-title: schema.Entity - Entity mixin
-sidebar_label: schema.Entity
+title: EntityMixin - Declarative unique objects for pre-existing classes
+sidebar_label: EntityMixin
 ---
 
 <head>
@@ -12,16 +12,16 @@ import LanguageTabs from '@site/src/components/LanguageTabs';
 import { RestEndpoint } from '@data-client/rest';
 import TypeScriptEditor from '@site/src/components/TypeScriptEditor';
 
-# schema.Entity
+# EntityMixin
 
 `Entity` defines a single _unique_ object.
 
-If you already have classes for your data-types, `schema.Entity` mixin may be for you.
+If you already have classes for your data-types, `EntityMixin` mixin may be for you.
 
 <TypeScriptEditor>
 
 ```typescript {10}
-import { schema } from '@data-client/rest';
+import { EntityMixin } from '@data-client/rest';
 
 export class Article {
   id = '';
@@ -30,7 +30,7 @@ export class Article {
   tags: string[] = [];
 }
 
-export class ArticleEntity extends schema.Entity(Article) {}
+export class ArticleEntity extends EntityMixin(Article) {}
 ```
 
 </TypeScriptEditor>
@@ -48,7 +48,7 @@ class User {
   username = '';
   createdAt = Temporal.Instant.fromEpochSeconds(0);
 }
-class UserEntity extends schema.Entity(User, {
+class UserEntity extends EntityMixin(User, {
   pk: 'username',
   key: 'User',
   schema: { createdAt: Temporal.Instant.from },
@@ -75,7 +75,7 @@ class Thread {
   slug = '';
   content = '';
 }
-class ThreadEntity extends schema.Entity(Thread, {
+class ThreadEntity extends EntityMixin(Thread, {
   pk(value) {
     return [value.forum, value.slug].join(',');
   },
@@ -94,7 +94,7 @@ Specifies the [Entity.schema](./Entity.md#schema)
 
 ## Methods
 
-`schema.Entity` mixin has the same [methods as the Entity](./Entity.md#lifecycle) class.
+`EntityMixin` mixin has the same [methods as the Entity](./Entity.md#lifecycle) class.
 
 ## const vs class
 
@@ -118,8 +118,8 @@ export class Article {
   tags: string[] = [];
 }
 
-export class ArticleEntity extends schema.Entity(Article) {}
-export const ArticleEntity2 = schema.Entity(Article);
+export class ArticleEntity extends EntityMixin(Article) {}
+export const ArticleEntity2 = EntityMixin(Article);
 
 const article: ArticleEntity = ArticleEntity.fromJS();
 const articleFails: ArticleEntity2 = ArticleEntity2.fromJS();

diff --git a/examples/benchmark/schemas.js b/examples/benchmark/schemas.js
@@ -1,4 +1,4 @@
-import { Entity, schema } from './dist/index.js';
+import { Entity, EntityMixin, schema } from './dist/index.js';
 
 export class BuildTypeDescription extends Entity {
   id = '';
@@ -13,7 +13,7 @@ export class BuildTypeDescription extends Entity {
 export class BuildTypeDescriptionEmpty extends Entity {
   static key = 'BuildTypeDescription';
 }
-export const BuildTypeDescriptionEntity = schema.Entity(
+export const BuildTypeDescriptionEntity = EntityMixin(
   class {
     id = '';
     internalId = 'bt17590';
@@ -51,7 +51,7 @@ export class ProjectWithBuildTypesDescriptionEmpty extends Entity {
 
   static key = 'ProjectWithBuildTypesDescription';
 }
-export const ProjectWithBuildTypesDescriptionEntity = schema.Entity(
+export const ProjectWithBuildTypesDescriptionEntity = EntityMixin(
   class {
     id = '';
     internalId = 'project3239';

diff --git a/examples/benchmark/src/index.ts b/examples/benchmark/src/index.ts
@@ -5,4 +5,4 @@ export {
   MemoCache,
 } from '@data-client/normalizr';
 export * from '@data-client/core';
-export { Endpoint, Entity, schema } from '@data-client/endpoint';
+export { Endpoint, Entity, EntityMixin, schema } from '@data-client/endpoint';
diff --git a/packages/endpoint/README.md b/packages/endpoint/README.md
@@ -42,10 +42,10 @@ export const updateTodo = (id: string, body: Partial<Todo>) =>
 ### 2) Turn them into Resources
 
 ```typescript
-import { schema, Endpoint } from '@data-client/endpoint';
+import { EntityMixin, Endpoint } from '@data-client/endpoint';
 import { Todo, getTodoList, updateTodo } from './existing';
 
-export const TodoEntity = schema.Entity(Todo, { key: 'Todo' });
+export const TodoEntity = EntityMixin(Todo, { key: 'Todo' });
 
 export const TodoResource = {
   get: new Endpoint(getTodo, {
@@ -221,7 +221,7 @@ Networking definition: [Endpoints](https://dataclient.io/rest/api/Endpoint)
 <tbody><tr>
 <td rowSpan="4"><a href="https://en.wikipedia.org/wiki/Object_(computer_science)">Object</a></td>
 <td align="center">✅</td>
-<td><a href="https://dataclient.io/rest/api/Entity">Entity</a>, <a href="https://dataclient.io/rest/api/schema.Entity">schema.Entity</a> mixin</td>
+<td><a href="https://dataclient.io/rest/api/Entity">Entity</a>, <a href="https://dataclient.io/rest/api/EntityMixin">EntityMixin</a></td>
 <td>single <em>unique</em> object</td>
 <td align="center">✅</td>
 </tr>

diff --git a/packages/endpoint/src-4.0-types/schemas/EntityTypes.d.ts b/packages/endpoint/src-4.0-types/schemas/EntityTypes.d.ts
@@ -48,7 +48,7 @@ export interface IEntityClass<TBase extends Constructor = any> {
   ): string | number | undefined;
   /** Return true to merge incoming data; false keeps existing entity
    *
-   * @see https://dataclient.io/docs/api/schema.Entity#shouldUpdate
+   * @see https://dataclient.io/docs/api/Entity#shouldUpdate
    */
   shouldUpdate(
     existingMeta: {
@@ -64,7 +64,7 @@ export interface IEntityClass<TBase extends Constructor = any> {
   ): boolean;
   /** Determines the order of incoming entity vs entity already in store
    *
-   * @see https://dataclient.io/docs/api/schema.Entity#shouldReorder
+   * @see https://dataclient.io/docs/api/Entity#shouldReorder
    * @returns true if incoming entity should be first argument of merge()
    */
   shouldReorder(
@@ -81,12 +81,12 @@ export interface IEntityClass<TBase extends Constructor = any> {
   ): boolean;
   /** Creates new instance copying over defined values of arguments
    *
-   * @see https://dataclient.io/docs/api/schema.Entity#merge
+   * @see https://dataclient.io/docs/api/Entity#merge
    */
   merge(existing: any, incoming: any): any;
   /** Run when an existing entity is found in the store
    *
-   * @see https://dataclient.io/docs/api/schema.Entity#mergeWithStore
+   * @see https://dataclient.io/docs/api/Entity#mergeWithStore
    */
   mergeWithStore(
     existingMeta: {
@@ -102,7 +102,7 @@ export interface IEntityClass<TBase extends Constructor = any> {
   ): any;
   /** Run when an existing entity is found in the store
    *
-   * @see https://dataclient.io/docs/api/schema.Entity#mergeMetaWithStore
+   * @see https://dataclient.io/docs/api/Entity#mergeMetaWithStore
    */
   mergeMetaWithStore(
     existingMeta: {

diff --git a/packages/endpoint/src/index.ts b/packages/endpoint/src/index.ts
@@ -15,6 +15,7 @@ export * as schema from './schema.js';
 // Clue 1) It only happens with types mentioned in return types of other types
 export type { Array, Invalidate, Collection, DefaultArgs } from './schema.js';
 export { default as Entity } from './schemas/Entity.js';
+export { default as EntityMixin } from './schemas/EntityMixin.js';
 export { default as validateRequired } from './validateRequired.js';
 export { INVALID } from './special.js';
 export type {