Entity e normalização de dados

Entities têm uma chave primária. Isso permite acesso fácil por meio de uma tabela de consulta. Assim, é simples encontrar, atualizar, criar ou excluir os mesmos dados, não importa em qual endpoint eles foram usados.

State

Response

[
  { "id": 1, "title": "this is an entity" },
  { "id": 2, "title": "this is the second entity" }
]

Endpoint

const getPresentations = new Endpoint(
  () => fetch(`/presentations`).then(res => res.json()),
  { schema: new Collection([Presentation]) },
);

Entity

class Presentation extends Entity {
  id = '';
  title = '';

  static key = 'Presentation';
}

Component

PresentationsPage.vue

<script setup lang="ts">
  import { useSuspense } from '@data-client/vue';
  import { getPresentations } from './api/Presentation';

  const presentations = await useSuspense(getPresentations);
</script>

<template>
  <div v-for="presentation in presentations" :key="presentation.pk()">
    {{ presentation.title }}
  </div>
</template>

Extrair entities de uma resposta é conhecido como normalização (normalization). Acessar uma resposta reverte o processo por meio da desnormalização (denormalization).

Igualdade referencial global

Usar entities estende a garantia de igualdade referencial global do Reactive Data Client para além da granularidade de uma resposta inteira de endpoint.

Mutações e dados dinâmicos

Quando um endpoint altera dados, isso é conhecido como efeito colateral. Marcar um endpoint com sideEffect: true informa ao Reactive Data Client que esse endpoint não é idempotente e, portanto, não deve ser permitido em hooks que podem chamar o endpoint um número arbitrário de vezes, como useSuspense() ou useFetch()

Ao incluir os dados alterados na resposta do endpoint, o Reactive Data Client consegue atualizar quaisquer entities que extrai por meio do schema especificado.

Create

import { RestEndpoint, schema } from '@data-client/rest';

const todoCreate = new RestEndpoint({
  urlPrefix: 'https://jsonplaceholder.typicode.com',
  path: '/todos',
  method: 'POST',
  schema: new Collection([Todo]).push,
});

Exemplo de uso

NewTodoForm.vue

<script setup lang="ts">
  import { useController } from '@data-client/vue';
  import { todoCreate } from './api/Todo';
  import Form from './Form.vue';
  import FormField from './FormField.vue';

  const ctrl = useController();
  const handleSubmit = (e: Event) =>
    ctrl.fetch(todoCreate, new FormData(e.target as HTMLFormElement));
</script>

<template>
  <Form @submit="handleSubmit">
    <FormField name="title" />
  </Form>
</template>

Update

import { RestEndpoint } from '@data-client/rest';

const todoUpdate = new RestEndpoint({
  urlPrefix: 'https://jsonplaceholder.typicode.com',
  path: '/todos/:id',
  method: 'PUT',
  schema: Todo,
});

Exemplo de uso

UpdateTodoForm.vue

<script setup lang="ts">
  import { useController, useSuspense } from '@data-client/vue';
  import { todoDetail, todoUpdate } from './api/Todo';
  import Form from './Form.vue';
  import FormField from './FormField.vue';

  const props = defineProps<{ id: number }>();
  const todo = await useSuspense(todoDetail, () => ({ id: props.id }));
  const ctrl = useController();
  const handleSubmit = (e: Event) =>
    ctrl.fetch(
      todoUpdate,
      { id: props.id },
      new FormData(e.target as HTMLFormElement),
    );
</script>

<template>
  <Form @submit="handleSubmit" :initialValues="todo">
    <FormField name="title" />
  </Form>
</template>

Delete

import { Invalidate, RestEndpoint } from '@data-client/rest';

const todoDelete = new RestEndpoint({
  urlPrefix: 'https://jsonplaceholder.typicode.com',
  path: '/todos/:id',
  method: 'DELETE',
  schema: new Invalidate(Todo),
});

Exemplo de uso

TodoWithDelete.vue

<script setup lang="ts">
  import { useController } from '@data-client/vue';
  import { todoDelete, type Todo } from './api/Todo';

  defineProps<{ todo: Todo }>();
  const ctrl = useController();
</script>

<template>
  <div>
    {{ todo.title }}
    <button @click="ctrl.fetch(todoDelete, { id: todo.id })">Delete</button>
  </div>
</template>

informação

As mutações atualizam automaticamente o cache normalizado, resultando em dados consistentes e atualizados.

Schema

Schemas são uma definição declarativa de como processar respostas

• onde esperar Entities
• Funções para desserializar campos

import { RestEndpoint, Collection } from '@data-client/rest';

const getTodoList = new RestEndpoint({
  urlPrefix: 'https://jsonplaceholder.typicode.com',
  path: '/todos',
  schema: new Collection([Todo]),
});

Colocar nossa Entity Todo em uma Collection de array nos permite adicionar com push ou com unshift novos Todos a ela com facilidade.

Além do array, há alguns outros 'schemas' disponíveis para vários padrões. Os dois primeiros (Object e Array) têm atalhos que usam literais de objeto e de array.

Tipo de dado	Mutável	Schema	Descrição	Queryable
Objeto	✅	Entity	um único objeto único	✅
	✅	Union(Entity)	objetos polimórficos (A | B)	✅
	🛑	Object	chaves conhecidas estaticamente	🛑
		Invalidate(Entity)	excluir uma entity	🛑
Lista	✅	Collection(Array)	listas expansíveis	✅
	🛑	Array	listas imutáveis	🛑
		All	lista de todas as entities de um tipo	✅
Mapa	✅	Collection(Values)	mapas expansíveis	✅
	🛑	Values	mapas imutáveis	🛑
Scalar	✅	Scalar	campos de entity dependentes de lens	✅
qualquer		Query(Queryable)	transformações personalizadas memoizadas	✅
		Lazy(Schema)	desnormalização adiada	✅

Saiba mais

Aninhamento

Além disso, as próprias Entities podem especificar schemas aninhados por meio de um membro static schema.

Entity

import { Entity } from '@data-client/endpoint';

class Todo extends Entity {
  id = 0;
  user = User.fromJS();
  title = '';
  completed = false;

  static key = 'Todo';

  static schema = {
    user: User,
  };
}

class User extends Entity {
  id = 0;
  username = '';

  static key = 'User';
}

Response

{
  "id": 5,
  "user": {
    "id": 10,
    "username": "bob"
  },
  "title": "Write some Entities",
  "completed": false
}

Saiba mais

Representações de dados

Além disso, funções podem ser usadas como schema. Elas serão chamadas durante a desnormalização. Isso pode ser útil com representações como bignumber ou temporal instant

import { Entity } from '@data-client/endpoint';

class Todo extends Entity {
  id = 0;
  user = User.fromJS();
  title = '';
  completed = false;
  dueDate = Temporal.Instant.fromEpochMilliseconds(0);

  static key = 'Todo';

  static schema = {
    user: User,
    dueDate: Temporal.Instant.from,
  };
}

informação

Graças à garantia de igualdade referencial global, a construção dos membros ocorre apenas uma vez por atualização.

Inspeção do store (depuração)

A extensão de navegador DevTools pode ser instalada para inspecionar e depurar o store.

Guia de depuração do Data Client »

Benchmarks

A memoização em nível de Entity entrega desempenho de desnormalização até 20x maior e propagação de mutações até 90x mais rápida em comparação com abordagens não normalizadas. Veja a página completa de Desempenho para os resultados dos benchmarks de normalização, bem como benchmarks completos da integração com React.