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

Author: ntucker

.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)

.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

README.md

@@ -373,7 +373,7 @@ For the small price of 9kb gziped.    [🏁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>

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

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]

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

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,

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.
 
 :::

docs/rest/api/schema.Entity.md renamed to 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();

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