bloc-react - npm Package Compare versions

Comparing version 0.0.15 to 0.0.16

package.json

 {
   "name": "bloc-react",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "scripts": {
@@ -73,4 +73,12 @@ "dev": "vite",
       "src/lib/**/*.{ts,tsx}"
-    ]
+    ],
+    "coverageThreshold": {
+      "global": {
+        "branches": 100,
+        "functions": 100,
+        "lines": 100,
+        "statements": 100
+      }
+    }
   }
 }

readme.md

 
 # BLoC React
 
-[![codecov](https://codecov.io/gh/jsnanigans/bloc-react/branch/main/graph/badge.svg?token=0FPH6ZMZD3)](https://codecov.io/gh/jsnanigans/bloc-react)
+[![codecov](https://codecov.io/gh/jsnanigans/bloc-react/branch/main/graph/badge.svg?token=0FPH6ZMZD3)](https://codecov.io/gh/jsnanigans/bloc-react) 
 [![liscence](https://img.shields.io/badge/license-MIT-purple.svg)](https://opensource.org/licenses/MIT)
@@ -9,3 +9,3 @@ [![Known Vulnerabilities](https://snyk.io/test/github/jsnanigans/bloc-react/badge.svg)](https://snyk.io/test/github/jsnanigans/bloc-react)
 ---
-[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=jsnanigans_bloc-react&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=jsnanigans_bloc-react)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=jsnanigans_bloc-react&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=jsnanigans_bloc-react) 
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=jsnanigans_bloc-react&metric=security_rating)](https://sonarcloud.io/dashboard?id=jsnanigans_bloc-react)
@@ -43,4 +43,6 @@ [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=jsnanigans_bloc-react&metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=jsnanigans_bloc-react)
   
-export default function CounterButton() {  
- const [count, { increment }] = useBloc(CounterCubit); return <button onClick={() => increment()}>count is: {count}</button>; }  
+const Counter: FC = (): ReactElement => {
+  const [value, { increment }] = useBloc(CounterCubit);
+  return <button onClick={() => increment()}>count is: {value}</button>;
+}
 ```  
@@ -50,3 +52,3 @@
 # Documentation
-[TODO]
+
 ## BlocReact
@@ -56,3 +58,3 @@ The `BlocReact` class handles the global state and manages all communication between individual BLoCs.
 ```typescript  
-const state = new BlocReact([new MyBloc(), new MyCubit()]);  
+const state = new BlocReact([new MyBloc(), new MyCubit()]);
 ```  
@@ -71,3 +73,3 @@
 ## Cubit
-A Cubit is a simplofied version `Bloc` class. Create your custom Cubit by extending the `Cubit` class, pass the initial state to the `super` constructor.
+A Cubit is a simplified version `Bloc` class. Create your custom Cubit by extending the `Cubit` class, pass the initial state to the `super` constructor.
 
@@ -77,41 +79,47 @@ The Cubits' state is updated by calling the `this.emit` method with the new state.
 ```typescript
-export default class CounterCubit extends Cubit<number> {  
-  constructor() {  
-    super(0);  
-  }  
-  
-  increment = (): void => {  
-    this.emit(this.state + 1);  
-  };  
-  decrement = (): void => {  
-    this.emit(this.state - 1);  
-  };  
+export default class CounterCubit extends Cubit<number> {
+  constructor() {
+    super(0);
+  }
+
+  increment = (): void => {
+    this.emit(this.state + 1);
+  };
 }
 ```
 
+In the react component you can then call the public methods like `increment` in this example
+
+```ts
+const Counter: FC = (): ReactElement => {
+  const [value, { increment }] = useBloc(CounterCubit);
+  return <button onClick={() => increment()}>count is: {value}</button>;
+}
+```
+
 ## Bloc
-Most of the time the `Cubit` class will be the easiest way to manage a peace of state but for the more critical parts of your application where there can be various reasons why the state changes to the same value, for example user authentication. It might be nice to know if the user got logged out because an error occured, the token expired or if they just clickd on the logout button.
+Most of the time the `Cubit` class will be the easiest way to manage a piece of state but for the more critical parts of your application where there can be various reasons why the state changes to the same value, for example user authentication. It might be nice to know if the user got logged out because an error occurred, the token expired or if they just clicked on the logout button.
 This is especially helpful when debugging some unexpected behaviour.
 
-in the `BlocObserver` you can then use the `onTransition` to see why the state changes, it will pass the previous state, the event itself and the next state.
+In the `BlocObserver` you can then use the `onTransition` to see why the state changes, it will pass the previous state, the event itself and the next state.
 
 ```typescript
-export enum AuthEvent {  
-  unknown = "unknown",  
-  authenticated = "authenticated",  
-  unauthenticated = "unauthenticated",  
-}  
-  
-export default class AuthBloc extends Bloc<AuthEvent, boolean> {  
-  constructor() {  
-    super(false)  
-  
-    this.mapEventToState = (event) => {  
-      switch (event) {  
-        case AuthEvent.unknown:  
-          return false;  
-        case AuthEvent.unauthenticated:  
-          return false;  
-        case AuthEvent.authenticated:  
-          return true;  
+export enum AuthEvent {
+  unknown = "unknown",
+  authenticated = "authenticated",
+  unauthenticated = "unauthenticated",
+}
+
+export default class AuthBloc extends Bloc<AuthEvent, boolean> {
+  constructor() {
+    super(false)
+
+    this.mapEventToState = (event) => {
+      switch (event) {
+        case AuthEvent.unknown:
+          return false;
+        case AuthEvent.unauthenticated:
+          return false;
+        case AuthEvent.authenticated:
+          return true;
     }
@@ -126,3 +134,3 @@ };
 const Component: FC = (): ReactElement => {  
-  const [state, bloc] = useBloc<AuthBloc>(AuthBloc);  
+  const [state, bloc] = useBloc(AuthBloc);  
   return <>  
@@ -135,8 +143,68 @@ {state === true && <Button onClick={() => bloc.add(AuthEvent.unauthenticated)}>Logout</Button>}
 ## useBloc
-[TODO: Add docs for hook]
+The main way to use the BLoCs in your UI will be with the `useBloc` hook, the first parameter is the class constructor of the Bloc you want to use.
+The second parameters are [options](#options) to configure how that hook behaves.
 
+The return value of `useBloc` is an array of two items, the first is the state of your BLoC, the second is the class which controls that part of the state.
+
+### Options
+
+#### shouldUpdate
+Decide whether the returned state value should be updated or not. Will have no effect if `subscribe` is false.
+```ts
+const [state] = useBloc(CounterCubit, {
+	// `state` is only updated if the count is even
+	shouldUpdate: (event) => event.nextState % 2 === 0,
+});
+```
+
+#### subscribe
+If `false`, the returned state will never be updated. Use this if you only need access to the BLoC class.
+```ts
+// we only need the `bloc` to call `bloc.increment` for example.
+const [, bloc] = useBloc(CounterCubit, {
+	subscribe: false,
+});
+```
+
+
 ## BlocProvider
-[TODO: Add docs for hook alternative for class components]
+Create a local state on demand with the `BlocProvider`. A context is created that then is available in the children of the BlocProvider.  When the global and the local state both have the same Bloc, the local one is used.
+In the `create` property, pass a function that returns a new instance of the Bloc you want to provide.
 
+```ts
+const Counter: FC = (): ReactElement => {
+  return <div>
+    <BlocProvider<CounterCubit>
+      create={() => new CounterCubit()}
+    >
+	    <Counter />
+    </BlocProvider>
+  </div>;
+}
+```
+
 ## BlocBuilder
-[TODO: Add docs for local state]
+If you can't or don't want to use the `useBloc` hook to access the bloc state you an alternatively opt for the `BlocBuilder` which is just a *Higher Order Component* that uses useBloc under the hood.
+
+The `blocClass` property takes a class constructor of a Bloc and provides an instance of that class in the `builder` property.
+
+The values passed into the callback for `builder` are the same you would get from the `useBloc` hook.
+
+You can also pass the `shouldUpdate` property to the `BlocBuilder` which works the same as the option of the same name for the `useBloc` hook.
+
+```ts
+class Counter extends Component {
+  render() {
+    return <BlocBuilder<CounterCubit>
+      blocClass={CounterCubit}
+      builder={([value, { increment }]) => (
+        <div>
+          <Button onClick={() => increment()}>{value}</Button>
+        </div>
+      )}
+    />;  
+  }  
+}
+```
+
+The BlocBuilder can also be used to set the scope which can help performance when you don't want to rerender the whole component every time the state changes.

No alert changes

Improved metrics

Total package byte prevSize

78660

increased by3.52%

Number of lines in readme file

203

increased by51.49%

No dependency changes