entangled-states é uma biblioteca que facilita o desenvolvimento de aplicações dinâmicas por meio dos padrões publish–subscribe e RPC utilizando o protocolo WebSocket.

O entangled-states pode ser usado para integração de

• páginas Web/PWA
• aplicativos Mobile com React Native
• aplicativos Mobile com soluções baseadas em WebView como Ionic e aplicações geradas com uso do Cordova/Phonegap
• aplicações de backend usando Node.js

Com entangled-states você pode:

• Criar Publicador de conteúdo no servidor em Node.js que envia mensagem para um Tópico a partir da consulta feita em um Repositório de dados.
• A partir da Web, aplicativo Mobile ou Node.js, Assinar um Tópico, recebendo as atualizações de forma compactada.
• Disponibilizar Métodos no Servidor Node.js que podem ser invocados pelos Clientes, permitindo receber respostas Síncronas (com Promises) para essa ação [RPC]
• No Servidor, a qualquer momento, solicitar a publicação de novos dados de um Tópico.
• Utilizar MongoDB, PostgreSQL ou qualqer outro SGBD como Repositório de dados.
• Utilizar Midlewares para ter um controle fino sobre a execução de Ações e Publicadores, permitindo, por exemplo, gerenciar Autenticação, Autorização de acesso ou Geração de Logs de execução.

No padrão publish–subscribe, também conhecido como pub-sub, Publicadores disponibilizam mensagens em Tópicos, os Assinantes podem então assinar/subscrever nestes tópicos e processar as mensagens recebidas.

O padrão RPC, Chamada Remota de Procedimento, acrônimo de Remote Procedure Call em inglês, permite que um Método (Action) do servidor possa ser invocado pelos Clientes.

No entangled-states o repositório de dados é usado para obter os dados para publicação em um tópico e também persistir o versionamento das mensagens.

É um repositório de dados. Existe uma implementação de repositório EM MEMÓRIA que é usado nos exemplos. Na documentação existe exemplos de criação de repositórios usando banco de dados Relacional (SQL) e até MongoDB.

O entangled-states define uma classe genérica para os repositórios, permitindo ao desenvolvedor implementar seu proprio repositório usando qualquer banco de dados que lhe interessa. Um repositório possui a seguinte estrutura:

class Repository<T> {
   find(criteria: AnyObject, options: AnyObject): Promise<Array<T>>;
   count(criteria: AnyObject, options: AnyObject): Promise<number>;
   findOne(criteria: AnyObject, options: AnyObject): Promise<T>;
   insert(data: Partial<T>, options: AnyObject): Promise<T>;
   update(criteria: AnyObject, data: Partial<T>, options: AnyObject): Promise<number>;
   remove(criteria: AnyObject, options: AnyObject): Promise<number>;
}

Os parâmetros comuns aos métodos do repositório são:

O entangled-states disponibiliza uma implementação de repositório em memória ( InMemoryRepository<T>), que pode ser usado para testes.

Exemplo Typescript/ES6

import { InMemoryRepository } from 'entangled-states';

const DB_USERS = new InMemoryRepository();

DB_USERS.insert(data)
    .then((row) => { })
    .catch((cause) => { });
    
// ou
try {
    let row = await DB_USERS.insert(data);
} catch (cause) {
    
}

Exemplo ES5

var InMemoryRepository = require("entangled-states").InMemoryRepository;

const DB_USERS = new InMemoryRepository();

DB_USERS.insert(data)
    .then(function(row) { })
    .catch(function(cause) { });

Como em outros sistemas pub-sub, os tópicos do entangled-states são os canais para transmitir mensagens de produtores para consumidores. O Tópico é o filtro de conteúdo que um cliente pode ter interesse em receber.

Existem dois tipos de tópicos LIVRES e COM IDENTIFICADOR.

• Um tópico livre é usado para funcionalidades genéricas, como por exemplo, receber notificações sobre a criação de novos itens em uma coleção no servidor.
• Já um tópico COM IDENTIFICADOR é usado para que o Cliente possa ser informado quando um item com identificador específico recebe atualizações, como por exemplo, em um sistema de e-comerce o cliente pode ser informado sobre a atualização do estoque ou preço de um produto específico.

O responsável pela criação dos tópicos, bem como a geração do seu conteúdo são os Publicadores.

Um Publicador é uma funcionalidade que permite disponibilizar o conteúdo de um Tópico. O Publicador utiliza um ou mais repositórios para consultar os dados que serão publicados.

Para criar um novo tópico, basta configura-lo usando o método create da classe Publishers, conforme.:

import { Publishers } from 'entangled-states';

// Tópico livre
Publishers.create({
   topic: 'listagemDeAlgo',
   query: {
      repository: meuRepository
   }
});

// Tópicos com identificador (detalheDeItem#ID)
Publishers.create({
   topic: 'detalheDeItem',
   idRequired: true,
   query: {
      repository: meuRepository,
      params: {
         id: '$id'
      }
   }
});

// Tópicos com identificador usado para listar dados de uma categoria
Publishers.create({
   topic: 'listagemDeCategoria',
   idRequired: true,
   query: {
      repository: meuRepository,
      params: {
         idCategoria: '$id'
      }
   }
});

As configurações de um Publicador disponíveis são:

Os dados publicados em um Tópico são provenientes da consulta em um ou mais repositórios. A consulta de um Publicador pode ser configurada usando os parametros abaixo.

Exemplo complexo No exemplo abaixo, é feito a criação de um tópico que entrega diversas informações sobre uma categoria de produtos a partir do ID (Obviamente esse exemplo pode ser substituído por apenas um repositório com os filtros desejados, mas o exemplo é apenas para demonstrar a aplicação de multiplas queries em um tópico).

// Publica detalhamento de uma categoria 
Publishers.create({
    topic: 'detalhesCategoria',
    idRequired: true,
    query: [
        {  // traz filhos da categoria solicitada
            repository: CATEGORIA_REPO,
            params: {
                categoriaPai: '$id'
            },
            // filtra categorias ativas
            filter: (row, index, rows, prevResults) => {
                return row.ativo === true;
            }
        },
        {  // conta produtos na categoria solicitada
            repository: CONTA_PRODUTOS_REPO,
            singleResult: true,
            params: {
                idCategoria: '$id'
            }
        },
        {  // detalhes da categoria solicitada
            repository: CATEGORIA_REPO,
            singleResult: true,
            params: {
                idCategoria: '$id'
            },
            extract: (rows, prevResults) => {
                let filhos: Array<Categoria> = prevResults[0];
                let contaProdutos: ContaProduto = prevResults[1][0]; // [1][0] = prevResult 1, item 0
                return {
                    ...rows[0], //   singleResult: true
                    totalProdutos: contaProdutos.total,
                    filhos: filhos
                }
            }
        }
   ]
});

A transfência das mensagens entre Cliente e Servidor é feito de forma compactada, usando um algoritmo de Delta Encoding (diff & patch) que garante o transporte apenas da diferença existente entre os dados conhecidos pelo cliente com os novos dados publicados no servidor, diminuindo o consumo de banda e latencia.

Sua aplicação Node.js. No servidor serão criados os publicadores de conteúdo e os métodos de ação. Nele também serão criados os repositórios de acesso aos dados.

Sua aplicação consumidora dos dados disponibilizados pelo servidor. Pode ser uma aplicação WEB, aplicativo Mobile ou até mesmo um outro servidor Node.js. O cliente pode se inscrever (SUBSCRIBER) para receber atualizações em um tópico ou até mesmo executar métodos disponibilizados pelo servidor.

Porque é legal :)

O entangled-states vai te ajudar se:

1. A principal necessidade da sua aplicação é receber atualizações em tempo real de forma ágil e leve
2. Sua aplicação não é do tamanho do Facebook (VEJA LIMITAÇÕES ABAIXO)
3. Você deseja padronizar/reutilizar o mecanismo de comunicação em páginas WEB, Aplicativo Mobile e Servidor
4. Você deseja diminuir consideravelmente o tamanho e quantidade de dados trafegados entre cliente e servidor por meio do algoritmo de compactação e delta implementado nessa solução

• Não permite (ainda) escalar para múltiplos servidores ou cores. Sua aplicação será single core.
• Não dá suporte (ainda) a WebSocket binário (ArrayBuffer). A transferência dos dados (compactados e delta) é somente do tipo Texto.
• Se estiver desenvolvendo páginas WEB, saiba que o motor de busca do Google não entende WebSocket, portanto, fazer uso exclusivamente de WebSocket para renderizar o conteúdo de sua página vai prejudicar as suas otimizações para mecanismos de busca - SEO

• Permitir escalar (sistema distribuido)
• Permitir Multi Tenancy
• Permitir transferencia binária