hermes-io 2.2.4 → 2.2.6

package/README.md

@@ -1,5 +1,15 @@
 # hermes-io
-A lightweight javascript library that allows communication between Reactjs components by using the observer pattern and the hook api.
+A lightweight javascript library that allows communication between components by using the observer pattern and the hook api.
+
+# Summary
+- [Installation](#installation)
+- [Get started](#get-started)
+- [Observer](#observer)
+- [Context](#context)
+- [useObserver](#useobserver-hook)
+- [notify](#notify)
+- Devtools (TODO)
+
 
 # Installation
 ```
@@ -7,63 +17,155 @@ npm i hermes-io --save
 ```
 
 # Get started
-In order to use `hermes-io` you need to create a react project by using something like [Create-react-app](https://create-react-app.dev/), hermes-io is Reactjs hook that communication between components,
-let's see it in action, follow the next example:
+`hermes-io` is a set of toolkits that combined allows communication between components let's explore every tool by following the `sneaker store example`:
+
+# Observer
+`hermes-io` provide an `Observer` class to create instances that can be `subscribable` that means many subscribers can listen for notifications on the instance by using the method `subscribe`, check the following example:
+
+We are exporting an `object` with two instances of the class `Observer` each key of the object has invidual propuses one for handle notifications about `add` a product and the other for `remove` a product.
+
+```javascript
+// observers/products.js
+import { Observer } from "hermes-io";
+
+export default {
+  add: new Observer(),
+  remove: new Observer(),
+};
+```
+
+# Context
+`NOTICE` this concept has nothing to do with the `react context api`.
+
+`hermes-io` provide a `Context` class to create instances that can be used to create `notification context` that means that only notification 
+submited on on specific context will be listened otherwise will be ignored, you can think on this like a `whitelist` let's analyze the following example:
+
+In our sneaker store we have a `product list` and a `shopping car` the user can `add` a `product` to the `shopping car`
+and also can `remove` a `product`, in both cases the one component can talk to the other by using `notifications` 
+on one specific observer and update the `ui`, this leads us to any part of the code with access to the observers can trigger `unexpected behaviors`,
+there is when the concept of a `context` comes in, the context constrains the observer by telling which `notifications` must listen.
+
+```javascript
+import { Context } from 'hermes-io';
+
+export const products = new Context('Product');
+export const shoppingCar = new Context('ShoppingCar');
+```
+ 
+
+```javascript
+const sneakerList = [
+  {
+    id: '1',
+    name: 'Jordan',
+    image: '/assets/images/jordan_3.webp',
+    description: 'Air Jordan 3 Retro OG',
+    price: '250'
+  },
+  {
+    id: '2',
+    image: '/assets/images/addidas.webp',
+    description: 'Bad Bunny Forum Buckle Low sneakers',
+    name: 'Adidas Forum',
+    price: '200'
+  },
+  {
+    id: '3',
+    image: '/assets/images/addidas.webp',
+    description: 'Bad Bunny Forum Buckle Low sneakers',
+    name: 'Adidas Forum',
+    price: '200'
+  }
+]
+
+const productsStore = new Map();
+productsStore.set('collection', sneakerList); 
+```
+
+# useObserver (hook)
+`hermes-io` provide a `react custom hook` to integrate `Observer` with `Context`, this hook can be used to subscribe listeners and receive `notifications` under cetains contrains provided by the `notification context`, let's analize this in detail.
+
+| key      | value             | required | description                                                                                                                                                     |
+|----------|-------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| observer | Observer instance | true     | An instance of the class Observer                                                                                                                               |
+| listener | Function          | true     | A standar javascript function                                                                                                                                   |
+| contexts | Context[]    | true     | An array of instances of the class Context, when a notification comes and is not signed with any of the contexts in the array the listener never will be called |
+
 
 ```javascript
-// observers.js
-export const AddProductObserver = new Observer();
-export const RemoveProductObserver = new Observer();
-
-
-// App.js
-import { useState } from 'react';
-import { useObserver, Observer } from 'hermes-io';
-import { RemoveProductObserver, AddProductObserver } from './observers';
-import { Products } from './components/Products';
-import { ShoppingCar } from './components/ShoppingCar';
-
-export const App = (props = {}) => {
-  const [productsToBy, setProductsToBy] = useState([]);
-  const productsStore = useProductStore(); // get products from some store
-  const products = productsStore.get();
+ import { useObserver } from "hermes-io";
   
-  const handleRemoveProduct = (product = {}) => {
-    const newProducts = [...productsToBy].filter(({ id = '' }) => id !== product.id);
-    setProductsToBy(newProducts);
-     productsStore.remove(product);
+ useObserver({
+   observer: ProductsObservers.add,
+   listener: handleAddProduct,
+   contexts: [contexts.products],
+ });
+```
+
+```javascript
+import React, { useState } from "react";
+import Products from "./components/Products/Products"
+import ShoppingCar from "./components/ShoppingCar/ShoppingCar";
+import { useObserver } from "hermes-io";
+import ProductsObservers from './observers/products';
+import theme from '@theme';
+import * as contexts from './contexts';
+
+const filterSelectes = (collection) => collection.filter((item) => item.selected); //filter selectes products
+
+function App() {
+  const [products, setProducts] = useState(ProductsStore.get('collection'));
+  
+  const handleRemoveProduct = ({ value: product = {} }) => {
+    product.selected = false;
+    setProducts([...ProductsStore.get('collection')]);
   };
   
-  const handleAddProduct = (product = {}) => {
-    setProductsToBy([...productsToBy, product]);
-    productsStore.update(product, { selected: true });  
+  const handleAddProduct = ({ value: product = {} }) => {
+    product.selected = true;
+    setProducts([...ProductsStore.get('collection')]);
   };
   
   useObserver({
-    observer: AddProductObserver,
+    observer: ProductsObservers.add,
     listener: handleAddProduct,
-    from: ['products-list'],
+    contexts: [contexts.products],
   });
   
   useObserver({
-    observer: RemoveProductObserver,
+    observer: ProductsObservers.remove,
     listener: handleRemoveProduct,
-    from: ['shopping-car'],
+    contexts: [contexts.shoppingCar, contexts.products],
   });
-  
-  return <div>
-    <Products data={products} />
-    <ShoppingCar data={productsToBy}/>
-  </div>
-};
 
+  return (
+    <>
+      <ShoppingCar data={filterSelectes(products)} />
+      <Products data={products} />
+    </>
+  );
+}
 
+export default App;
+
+```
+# Notify
+Is a method that allows sending notifications to the `subscribers` of a specific `observer` signed with a `context` that way we create a `notification context`, let's see this in details:
+  
+  | key     | value   | required | description                       |
+|---------|---------|----------|-----------------------------------|
+| value   | any     | true     | Payload with business information |
+| context | context | true     | A context instance                |
+  
+
+```javascript
 // ShoppingCar.js
-import { RemoveProductObserver } from '../observers';
+import ProductsObservers from './observers/products';
+import * as contexts from '../contexts';
 
 export const ShoppingCar = (props = {}) => {
   const handleRemoveProduct = (product = {}) => {
-    RemoveProductObserver.notify({ value: product, from 'shopping-car' });
+    ProductsObservers.remove.notify({ value: product, context: contexts.shoppingCar });
   };
   return <div>
     <ul>
@@ -80,15 +182,17 @@ export const ShoppingCar = (props = {}) => {
     </ul>
   </div>
 };
-
+```
+```javascript
 // Products.js
-import { AddProductObserver } from '../observers';
+import ProductsObservers from './observers/products';
+import * as contexts from '../contexts';
 
 export const Products = (props = {}) => {
   const { data = [] } = props; 
   
   const handleAddProduct = (product = {}) => {
-    AddProductObserver.notify({ value: product, from 'products-list' });
+    ProductsObservers.add.notify({ value: product, context: contexts.products });
   };
   
   return <ul>
@@ -104,7 +208,6 @@ export const Products = (props = {}) => {
      }
   </ul>
 };
-
 ```
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermes-io",
-  "version": "2.2.4",
+  "version": "2.2.6",
   "description": "A lightweight javascript library that allows communication between Reactjs components by using the observer pattern and the hook api",
   "main": "index.js",
   "scripts": {

package/examples/sneaker-store/. quokka

@@ -1,25 +0,0 @@
-{
-  "babel": {
-    "presets": [
-      "react-app"
-    ]
-  },
-  "plugins": [
-    "alias-quokka-plugin",
-    "jsdom-quokka-plugin"
-  ],
-  "alias": {
-    "@core": "./src/core",
-    "@components": "./src/core/components",
-    "@contexts": "./src/core/contexts",
-    "@factory": "./src/core/factory",
-    "@hooks": "./src/core/hooks",
-    "@utils": "./src/core/utils",
-    "@libs": "./src/libs",
-    "@constants": "./src/core/constants",
-    "@translations": "./src/core/translations",
-    "@theme": "./src/core/theme",
-    "@routes": "./src/core/routes"
-  },
-  "node": "~/.nvm/versions/node/v16.18.1/bin/node"
-}

package/examples/sneaker-store/.editorconfig

@@ -1,32 +0,0 @@
-# EditorConfig is awesome: https://EditorConfig.org
-
-# top-most EditorConfig file
-root = true
-
-# Unix-style newlines with a newline ending every file
-[*]
-end_of_line = lf
-insert_final_newline = true
-
-# Matches multiple files with brace expansion notation
-# Set default charset
-[*.{js,py}]
-charset = utf-8
-
-# 4 space indentation
-[*.py]
-indent_style = space
-indent_size = 4
-
-# Tab indentation (no size specified)
-[Makefile]
-indent_style = tab
-
-# Indentation override for all JS under lib directory
-[*.js]
-indent_style = space
-indent_size = 2
-
-[{package.json,.travis.yml}]
-indent_style = space
-indent_size = 2

package/examples/sneaker-store/.eslintrc.js

@@ -1,24 +0,0 @@
-module.exports = {
-    "env": {
-        "browser": true,
-        "es2021": true
-    },
-    "extends": [
-        "eslint:recommended",
-        "plugin:react/recommended"
-    ],
-    "overrides": [
-    ],
-    "parserOptions": {
-        "ecmaVersion": "latest",
-        "sourceType": "module"
-    },
-    "plugins": [
-        "react"
-    ],
-    "rules": {
-        "react/prop-types": "off",
-        "no-unused-vars": 0,
-        "react/display-name": 0
-    }
-}

package/examples/sneaker-store/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 Esneyder Amin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/examples/sneaker-store/README.md

@@ -1 +0,0 @@
-# atomic-client

package/examples/sneaker-store/config-overrides.js

@@ -1,35 +0,0 @@
-const path = require("path");
-
-module.exports = {
-  webpack: function (config) {
-    config.devtool = "source-map";
-    config.resolve = {
-      extensions: [".js", ".html"],
-      alias: {
-        "@actions": path.resolve(__dirname, "src/core/actions"),
-        "@core": path.resolve(__dirname, "src/core"),
-        "@views": path.resolve(__dirname, "src/core/views"),
-        "@components": path.resolve(__dirname, "src/core/views/components"),
-        "@factory": path.resolve(__dirname, "src/core/factory"),
-        "@hooks": path.resolve(__dirname, "src/core/views/hooks"),
-        "@constants": path.resolve(__dirname, "src/core/constants"),
-        "@contexts": path.resolve(__dirname, "src/core/contexts"),
-        "@observers": path.resolve(__dirname, "src/core/observers"),
-        "@theme": path.resolve(__dirname, "src/core/theme"),
-        "@src": path.resolve(__dirname, "src"),
-        "hermes-io": path.resolve(__dirname, "../../"),
-        "react": path.resolve(__dirname, "../../node_modules/react"),
-      },
-    };
-    config.module.rules.push({
-      test: /\.js$/,
-      loader: "esbuild-loader",
-      options: {
-        loader: "jsx",
-        target: "es2020",
-      },
-    });
-    console.log(JSON.stringify(config));
-    return config;
-  },
-};

package/examples/sneaker-store/jsconfig.json

@@ -1,20 +0,0 @@
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "actions/*": ["src/core/actions/*"],
-      "@core/*": ["src/core/*"],
-      "@views/*": ["src/core/views/*"],
-      "@components/*": ["src/core/views/components/*"],
-      "@factory/*": ["src/core/factory/*"],
-      "@hooks/*": ["src/core/views/hooks/*"],
-      "@constants": ["src/core/constants"],
-      "@observers/*": ["src/core/observers/*"],
-      "@contexts/*": ["src/core/contexts"],
-      "@src/*": ["src/*"],
-      "@hermes-io/*": ["../../*"],
-      "react": ["../../node_modules/react"]
-    }
-  },
-  "exclude": ["node_modules"]
-}