chizu 0.2.26 → 0.2.28

package/README.md

@@ -1,17 +1,22 @@
 <div align="center">
   <img src="/media/logo.png" width="475" />
+
+[![Checks](https://github.com/Wildhoney/Chizu/actions/workflows/checks.yml/badge.svg)](https://github.com/Wildhoney/Chizu/actions/workflows/checks.yml)
+
 </div>
 
 Strongly typed React framework using generators and efficiently updated views alongside the publish-subscribe pattern.
 
+**[View Live Demo →](https://wildhoney.github.io/Chizu/)**
+
 ## Contents
 
 1. [Benefits](#benefits)
 1. [Getting started](#getting-started)
-1. [Handling errors](#handling-errors)
-1. [Distributed actions](#distributed-actions)
+1. [Error handling](#error-handling)
+<!-- 1. [Distributed actions](#distributed-actions)
 1. [Module dispatch](#module-dispatch)
-1. [Associated context](#associated-context)
+1. [Associated context](#associated-context) -->
 
 ## Benefits
 
@@ -21,86 +26,133 @@ Strongly typed React framework using generators and efficiently updated views al
 - Mostly standard JavaScript without quirky rules and exceptions.
 - Clear separation of concerns between business logic and markup.
 - First-class support for skeleton loading using generators.
-- Strongly typed throughout &ndash; styles, actions and views.
-- Avoid vendor lock-in with framework agnostic libraries such as [Shoelace](https://shoelace.style/).
+- Strongly typed throughout &ndash; dispatches, models, etc&hellip;
 - Easily communicate between actions using distributed actions.
-- State is mutated sequentially ([FIFO](<https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)>)) and deeply merged for queued mutations.
+- Bundled decorators for common action functionality such as consecutive mode.
 
 ## Getting started
 
-Actions are responsible for mutating the state of the view. In the below example the `name` is dispatched from the view to the actions, the state is updated and the view is rendered with the updated value.
+Actions are responsible for mutating the state of the view. In the below example the `name` is dispatched from the view to the actions, the state is updated and the view is rendered with the updated value. We use the `Actions` type to ensure type safety for our actions class.
 
 ```tsx
-export default <Actions<Module>>function Actions(module) {
-  return {
-    [Action.Name](name) {
-      return module.actions.produce((draft) => {
-        draft.name = name;
-      });
-    },
-  };
+const model: Model = {
+  name: null,
 };
+
+export class Actions {
+  static Name = createAction<string>();
+}
+
+export default function useNameActions() {
+  return useActions<Model, typeof Actions>(
+    model,
+    class {
+      [Actions.Name] = utils.set("name");
+    },
+  );
+}
 ```
 
 ```tsx
 export default function Profile(props: Props): React.ReactElement {
+  const [model, actions] = useNameActions();
+
   return (
-    <Scope<Module> using={{ model, actions, props }}>
-      {(module) => (
-        <>
-          <p>Hey {module.model.name}</p>
+    <>
+      <p>Hey {model.name}</p>
 
-          <button
-            onClick={() => module.actions.dispatch([Action.Name, randomName()])}
-          >
-            Switch profile
-          </button>
-        </>
-      )}
-    </Scope>
+      <button onClick={() => actions.dispatch(Actions.Name, randomName())}>
+        Switch profile
+      </button>
+    </>
   );
 }
 ```
 
-You can perform asynchronous operations in the action which will cause the associated view to render a second time:
+You can perform asynchronous operations in the action which will cause the associated view to render a second time &ndash; as we're starting to require more control in our actions we&apos;ll move to our own fine-tuned action instead of `utils.set`:
 
 ```tsx
-export default <Actions<Module>>function Actions(module) {
-  return {
-    async *[Action.Name]() {
-      yield module.actions.produce((draft) => {
-        draft.name = null;
-      });
+const model: Model = {
+  name: null,
+};
 
-      const name = await fetch(/* ... */);
+export class Actions {
+  static Name = createAction();
+}
 
-      return module.actions.produce((draft) => {
-        draft.name = name;
-      });
+export default function useNameActions() {
+  const nameAction = useAction<Model, typeof Actions.Name>(async (context) => {
+    context.actions.produce((draft) => {
+      draft.name = null;
+    });
+
+    const name = await fetch(/* ... */);
+
+    context.actions.produce((draft) => {
+      draft.name = name;
+    });
+  });
+
+  return useActions<Model, typeof Actions>(
+    model,
+    class {
+      [Actions.Name] = nameAction;
     },
-  };
-};
+  );
+}
 ```
 
 ```tsx
 export default function Profile(props: Props): React.ReactElement {
+  const [model, actions] = useNameActions();
+
   return (
-    <Scope<Module> using={{ model, actions, props }}>
-      {(module) => (
-        <>
-          <p>Hey {module.model.name}</p>
+    <>
+      <p>Hey {model.name}</p>
 
-          <button onClick={() => module.actions.dispatch([Action.Name])}>
-            Switch profile
-          </button>
-        </>
-      )}
-    </Scope>
+      <button onClick={() => actions.dispatch(Actions.Name)}>
+        Switch profile
+      </button>
+    </>
   );
 }
 ```
 
-However in the above example where the name is fetched asynchronously, there is no feedback to the user &ndash; we can improve that significantly by using the `module.actions.annotate` and `module.validate` helpers:
+## Error handling
+
+Chizu provides a simple way to catch errors that occur within your actions. You can use the `ActionError` component to wrap your application and provide an error handler. This handler will be called whenever an error is thrown in an action.
+
+```tsx
+import { ActionError } from "chizu";
+
+const App = () => (
+  <ActionError handler={(error) => console.error(error)}>
+    <Profile />
+  </ActionError>
+);
+```
+
+## Handling states
+
+```ts
+import { Op } from "chizu";
+
+// Mark a value as pending with an operation
+context.actions.produce((model) => {
+  model.name = context.actions.annotate(Op.Update, "New Name");
+});
+
+// Check pending state
+actions.inspect.name.pending(); // true
+
+// Get remaining count of pending operations
+actions.inspect.name.remaining(); // 1 (next: actions.inspect.name.draft())
+
+// Check specific operation
+actions.inspect.name.is(Op.Update); // true
+```
+
+<!-- However in the above example where the name is fetched asynchronously, there is no feedback to the user &ndash; we can improve that significantly by using the `module.actions.annotate` and `module.validate` helpers:
 
 ```tsx
 export default <Actions<Module>>function Actions(module) {
@@ -142,52 +194,7 @@ export default function ProfileView(props: Props): React.ReactElement {
 }
 ```
 
-## Handling errors
-
-Most errors are likely to occur in the actions because the views should be free of side effects. First and foremost it's recommended that errors be encoded into your corresponding module using a library such as [`neverthrow`[(https://github.com/supermacro/neverthrow)] &ndash; that way you can effectively identify which properties are fallible and render the DOM accordingly:
-
-```tsx
-export default <Actions<Module>>function Actions(module) {
-  return {
-    *[Action.Name]() {
-      yield module.actions.produce((draft) => {
-        draft.name = null;
-      });
-
-      const name = await fetch(/* ... */);
-
-      return module.actions.produce((draft) => {
-        draft.name = name ? Result.Just(name) : Result.Nothing();
-      });
-    },
-  };
-};
-```
-
-However in eventualities where an error has not been caught in an action then the `Lifecycle.Error` is the next best thing &ndash; use it to display a toast message and log it your chosen error log service.
-
-Additionally when rendering an error may be thrown which prevents the DOM from updating as you'd expect &ndash; perhaps a side effect has delivered an unexpected data structure. In those cases again `Lifecycle.Error` is your friend. When such an error is thrown the component boundary will be switched to `Boundary.Error` which you detect using `module.boundary.is(Boundary.Error)` and switch to an alternative markup that _should_ render, within that you could display a button to attempt recovery &ndash; simply call an action again and update the meta to switch the boundary back to `Boundary.Default`:
-
-```tsx
-export default <Actions<Module>>function Actions(module) {
-  return {
-    *[Action.Recover]() {
-      yield module.actions.produce((draft) => {
-        draft.name = null;
-      });
-
-      const name = await fetch(/* ... */);
 
-      return module.actions.produce((draft, meta) => {
-        meta.boundary = Boundary.Default;
-        draft.name = name;
-      });
-    },
-  };
-};
-```
-
-If the component again throws an error after attempting recovery, it will simply switch back to the `Boundary.Error` again.
 
 ## Distributed actions
 
@@ -269,4 +276,4 @@ export default function Profile(props: Props): React.ReactElement {
     </Scope>
   );
 }
-```
+``` -->

package/dist/action/index.d.ts

@@ -0,0 +1,19 @@
+import { Action, Payload } from '../types';
+/**
+ * Defines a new action with a given payload type.
+ *
+ * @template T The type of the payload that the action will carry.
+ * @param {string} [name] An optional name for the action, used for debugging purposes.
+ * @returns {Payload<T>} A new action object.
+ */
+export declare function createAction<T = never>(name?: string): Payload<T>;
+/**
+ * Defines a new distributed action with a given payload type.
+ * Distributed actions can be shared across different modules.
+ *
+ * @template T The type of the payload that the action will carry.
+ * @param {string} [name] An optional name for the action, used for debugging purposes.
+ * @returns {Payload<T>} A new distributed action object.
+ */
+export declare function createDistributedAction<T = never>(name?: string): Payload<T>;
+export declare function isDistributedAction(action: Action): boolean;