-
Notifications
You must be signed in to change notification settings - Fork 16
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: started updating vuepress docs
- Loading branch information
1 parent
092ecc8
commit 97dc773
Showing
31 changed files
with
791 additions
and
649 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # Extensibility | ||
|
|
||
| Harlem uses a combination of [extensions](extensions) and plugins to extend core functionality. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| # History Extension | ||
|
|
||
|  | ||
|
|
||
| This is the official history extension for Harlem. The history extension adds undo and redo capabilities to your store for easily integrating history features into your application. | ||
|
|
||
| ## Getting Started | ||
|
|
||
| Follow the steps below to get started using the history extension. | ||
|
|
||
| ### Installation | ||
|
|
||
| Before installing this extension make sure you have installed `@harlem/core`. | ||
|
|
||
| Install `@harlem/extension-history`: | ||
| ``` | ||
| npm install @harlem/extension-history | ||
| ``` | ||
| Or if you're using Yarn: | ||
| ``` | ||
| yarn add @harlem/extension-history | ||
| ``` | ||
|
|
||
| ### Registration | ||
|
|
||
| To get started simply register this extension with the store you wish to extend. | ||
|
|
||
| ```typescript | ||
| import historyExtension from '@harlem/extension-history'; | ||
|
|
||
| import { | ||
| createStore | ||
| } from '@harlem/core'; | ||
|
|
||
| const STATE = { | ||
| firstName: 'Jane', | ||
| lastName: 'Smith' | ||
| }; | ||
|
|
||
| const { | ||
| state, | ||
| getter, | ||
| mutation, | ||
| undo, | ||
| redo | ||
| } = createStore('example', STATE, { | ||
| extensions: [ | ||
| historyExtension({ | ||
| max: 50, | ||
| mutations: [ | ||
| { | ||
| name: 'set-name', | ||
| description: 'Set the current user\'s name' | ||
| } | ||
| ] | ||
| }) | ||
| ] | ||
| }); | ||
| ``` | ||
|
|
||
| The history extension adds 2 new methods to the store instance: `undo` and `redo`. | ||
|
|
||
|
|
||
| ## Usage | ||
|
|
||
| ### Options | ||
| The history extension method accepts an options object with the following properties: | ||
|
|
||
| - **max**: `number` - The maximum number of history steps to store. The default value is `50`. | ||
| - **mutations**: `object[]` - The mutations you wish to track. leaving this undefined will cause all mutations to be tracked. The default is undefined. | ||
| - **name**: `string` - The name of the mutation to track. This must match the name of a registered mutation. | ||
| - **description**: `string?` - An optional description of the mutations intentions. This is useful for displaying a list of commands in the UI. | ||
|
|
||
| ### Undoing/Redoing mutations | ||
| To undo or redo a mutation simply call the `undo` or `redo` methods returned from the store instance. | ||
|
|
||
| ## Considerations | ||
| Please keep the following points in mind when using this extension: | ||
|
|
||
| - This extension has a slight performance cost. Each tracked mutation is proxied and values are cloned pre/post mutation. If you are assigning/moving/deleting large object structures around state this cause a performance hit and increase in memory usage. It is recommended to keep mutations granular and precise when tracking them with the history (or trace) extension. | ||
| - This extension cannot handle untracked mutation side-effects. For example, say you have 2 mutations, `mutation1` and `mutation2`. Both mutations modify the same branch of state but `mutation1` is tracked by the history extension and `mutation2` is not. Undoing the changes from `mutation1` any time after running `mutation2` will cause changes from `mutation2` to be lost and unrecoverable. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| # Introduction | ||
|
|
||
| Extensions are per-store additions to Harlem's core functionaility. Extensions are often used for adding store features, changing store behaviour and various other low-level tasks. This is the primary method in which Harlem stores are extended. | ||
|
|
||
| Feel free to choose from some of the official extensions or write your own. See the [extensions documentation](extensions) from more information on the official set of extensions or how to author your own plugin. | ||
|
|
||
| ## Official Extensions | ||
|
|
||
| Here is a list of officially supported Harlem plugins. These plugins are not designed to suit every use-case but instead add basic functionality for common use-cases. | ||
|
|
||
| - [Action](action.html) (`@harlem/extension-action`) - Extends a store to support cancellable async actions. | ||
| - [History](history.html) (`@harlem/extension-history`) - Extends a store to support undo and redo capabilities. | ||
| - [Lazy](lazy.html) (`@harlem/extension-lazy`) - Extends a store to support lazy async getters. | ||
| - [Reset](reset.html) (`@harlem/extension-reset`) - Extends a store to support resetting a store back to it's original state. | ||
| - [Snapshot](snapshot.html) (`@harlem/extension-snapshot`) - Extends a store to support taking snapshots of state and applying it at a later stage. | ||
| - [Storage](storage.html) (`@harlem/extension-storage`) - Extends a store to support synchronising state to/from `localStorage` or `sessionStorage`. | ||
| - [Trace](trace.html) (`@harlem/extension-trace`) - Extends a store to support tracing granular changes to state during mutations. Useful for auditing during development. | ||
| - [Transaction](transaction.html) (`@harlem/extension-transaction`) - Extends a store to support rolling back multiple mutations if one fails. | ||
|
|
||
| If you require functionality to suit a specific use-case you can write your own extension. See [Writing your own extension](#writing-your-own-extension) below. | ||
|
|
||
| If you feel that there is a piece of common functionality that should be included as an official Harlem extension please open an issue providing a description of the extension, the intended API and, if possible, a working example in a codesandbox. | ||
|
|
||
| ## Writing your own extension |
Oops, something went wrong.