open-index/open-npm huggingface dataset:
npm package: @harker-robo/prettier-config
Description: Code style definitions for Harker Robotics
Author: Aarav Borthakur
Latest version: 1.0.0

# prettier-config
Code style definitions for Harker Robotics. 

## Installation
Install this package locally and [prettier](https://www.npmjs.com/package/prettier) globally.

    npm i -g prettier
    npm i --save-dev @harker-robo/prettier-config

## Usage
1. Add the `prettier` key in package.json
```jsonc
// package.json
{
    ...
    "prettier": "@harker-robo/prettier-config"
}
```

2. Run the formatter.
```
prettier ./* -w
```

## Links
* [Ignoring files](https://prettier.io/docs/en/ignore.html)
* [Overriding configuration](https://prettier.io/docs/en/configuration.html)
* [GitHub integration](https://github.com/marketplace/actions/prettier-action)
* [Editor integration](https://prettier.io/docs/en/editors.html)
npm package: @harlem/core
Description: Powerfully simple global state management for Vue 3
Author: Andrew Courtice
Latest version: 3.1.8

# Harlem Core

This is the core harlem package. Head over to [harlemjs.com](https://harlemjs.com) to get started or take a look at the [demo](https://andrewcourtice.github.io/harlem) to see it in action.


## Getting Started

Getting started with Harlem is easy. Just follow the steps below and you'll be up and running in no time.

### Installation

Install `@harlem/core` and any [plugins](/plugins/)/[extensions](/extensions/) you wish to include.

```bash
# yarn
yarn add @harlem/core

# npm
npm install @harlem/core
```


### Register the Harlem Vue plugin

Register the Harlem plugin with your Vue app instance:
```typescript
import App from './app.vue';

import {
    createVuePLugin
} from '@harlem/core';

createApp(App)
    .use(createVuePlugin())
    .mount('#app');
```


### Create your first store

Create your store and define any getters, actions or mutations:

```typescript
import {
    createStore
} from '@harlem/core';

// The initial state for this store
const STATE = {
    firstName: 'John',
    lastName: 'Smith'
};

// Create the store, specifying the name and intial state
export const {
    state, 
    getter,
    mutation,
    action,
    ...store
} = createStore('user', STATE);

export const fullName = getter('fullname', state => `${state.firstName} ${state.lastName}`);

export const setFirstName = mutation('set-first-name', (state, payload: string) => {
    state.firstName = payload;
});

export const setLastName = mutation('set-last-name', (state, payload: string) => {
    state.lastName = payload;
});

export const loadDetails = action('load-details', async (id: string, mutate) => {
    const response = await fetch(`/api/details/${id}`);
    const details = await response.json();

    mutate(state => {
        state.details = details;
    });
});
```

### Use your store in your app

To use your store in your app just import the parts of it you need.

```html
<template>
    <div class="app">
        <h1>Hello {{ fullName }}</h1>
        <button @click="loadDetails()">Load Details</button>
        <input type="text" v-model="firstName" placeholder="First name">
        <input type="text" v-model="lastName" placeholder="Last name">
    </div>
</template>

<script lang="ts" setup>
import {
    computed
} from 'vue';

import {
    state,
    fullName,
    setFirstName,
    setLastName,
    loadDetails
} from './stores/user';

const firstName = computed({
    get: () => state.firstName,
    set: value => setFirstName(value)
});

const lastName = computed({
    get: () => state.lastName,
    set: value => setLastName(value)
});
</script>
```
npm package: @harlem/extension-history
Description: The official history extension for Harlem
Author: Andrew Courtice
Latest version: 3.1.8

# Harlem History Extension (preview)

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`.

```bash
yarn add @harlem/extension-history
# or
npm install @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';

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 several new methods to the store instance (highlighted above).


## 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.
npm package: @harlem/extension-lazy
Description: The official lazy extension for Harlem
Author: Andrew Courtice
Latest version: 3.1.8

# Harlem Lazy Extension

The lazy extension adds the ability to define asynchronous getters that are automatically re-evaluated when the referenced state (or other reactive objects) change.

## Getting Started

Follow the steps below to get started using the lazy extension.

### Installation

Before installing this extension make sure you have installed `harlem`.

```bash
yarn add @harlem/extension-lazy
# or
npm install @harlem/extension-lazy
```

### Registration

To get started simply register this extension with the store you wish to extend.

```typescript
import lazyExtension from '@harlem/extension-lazy';

import {
    createStore
} from 'harlem';

const STATE = {
    firstName: 'Jane',
    lastName: 'Smith'
};

const {
    state,
    getter,
    mutation,
    lazy
} = createStore('example', STATE, {
    extensions: [
        lazyExtension()
    ]
});
```

The lazy extension adds a single `lazy` method to the store instance.


## Usage

### Defining a lazy getter
Defining a lazy getter is very similar to defining a normal getter with a few differences - the getter body is async, includes an `onInvalidate` method parameter and the return type is an array with 2 values. The `lazy` method also accepts a 3rd argument which is the getter's default value while it is evaluating.

```typescript
export default lazy('mapped-data', async (state, onInvalidate) => {
    return doSomethingAsync(state.details);
});
```

In order for this extension to function correctly you must access any reactive values you want to trigger the getter's re-evaluation **before** the first `await` statement. This is because the lazy getter uses `watchEffect` internally which does not wait for async methods to finish in order to track dependencies. For more information read [this article](https://antfu.me/posts/async-with-composition-api) by Anthony Fu.

#### onInvalidate
The `onInvalidate` method supplied to the getter body is used to handle when the getter's evaluation is cancelled. The `onInvalidate` is forwarded directly from Vue's `watchEffect`.


### Using a lazy getter
The lazy getter returns an array with 2 values. The first value is a `computed` with the return value of the getter's async body. The second value is a `computed` boolean indicating whether the getter is re-evaluating.

```typescript
const [
    value,
    isEvaluating
] = lazy('mapped-data', async (state, onInvalidate) => {
    return doSomethingAsync(state.details);
});
```

### Specifying a default value
Due to the async nature of the getter the return value of the body may be undefined until it is finished evaluating for the first time. To get around this you can specify what the default value should be.

```typescript
export default lazy('mapped-data', async (state, onInvalidate) => {
    return doSomethingAsync(state.details);
}, 'some default value');
```
npm package: @harlem/extension-trace
Description: The official trace extension for Harlem
Author: Andrew Courtice
Latest version: 3.1.8

# Harlem Trace Extension

The trace extension adds the ability to trace granular changes to state. It is useful for detailed auditing of state changes or as a building block of undo/redo functionality.

## Getting Started

Follow the steps below to get started using the trace extension.

### Installation

Before installing this extension make sure you have installed `harlem`.

```bash
yarn add @harlem/extension-trace
# or
npm install @harlem/extension-trace
```

### Registration

To get started simply register this extension with the store you wish to extend.

```typescript
import traceExtension from '@harlem/extension-trace';

import {
    createStore
} from 'harlem';

const STATE = {
    firstName: 'Jane',
    lastName: 'Smith'
};

const {
    state,
    getter,
    mutation,
    startTrace,
    stopTrace,
    onTraceResult,
} = createStore('example', STATE, {
    extensions: [
        traceExtension({
            autoStart: true,
            debug: true,
        })
    ]
});
```

The trace extension adds several new methods to the store instance (highlighted above).


## Usage

### Options
The storage extension method accepts an options object with the following properties:
- **autoStart**: `boolean` - Indicates whether to start tracing automatically after the store is created. Default value is `false`.
- **debug**: `boolean` - Enables debug mode. This logs all trace results to the console. Default value is `false`.


### Manually starting/stopping tracing
Tracing can be manually started or stopped at any time using the `startTrace` and `stopTrace` methods. The `startTrace` method accepts an optional `gates` parameter which is an array of strings representing the proxy gates to catch during tracing. The default gate is `set`.

See [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/Proxy#handler_functions) for a full list of proxy gates available.

The only gates currently available for tracing are `get`, `set` and `deleteProperty`.


### Handling trace results
The `onTraceResult` method lets you handle the result when one of the specified gates is accessed during a trace. The method takes a single function parameter with a `result` as it's only argument.

```typescript
const listener = onTraceResult(result => console.log(result));

// To cleanup:
listener.dispose();
```

The `result` object has the following properties:
- **path**: `string` - The path at which the trace gate was triggered. Eg. `/user/details/roles[0]/id`.
- **gate**: `string` - The gate this result was triggered for.
- **nodes**: `(string | number)[]` - The nodes traversed when this gate was triggered. Given the above path, this value would be `['user', 'details', 'roles', 0]`.
- **prop**: `string | number` - The prop that triggered the gate. Eg. `id`.
- **oldValue**: `unknown` - The value before the change.
- **newValue**: `unknown` - The value after the change.
npm package: @harlem/extension-transaction
Description: The official transaction extension for Harlem
Author: Andrew Courtice
Latest version: 3.1.8

# Harlem Transaction Extension

The transaction extension adds the ability to rollback a set of mutations in the event of an error.

## Getting Started

Follow the steps below to get started using the transaction extension.

### Installation

Before installing this extension make sure you have installed `harlem`.

```bash
yarn add @harlem/extension-transaction
# or
npm install @harlem/extension-transaction
```

### Registration

To get started simply register this extension with the store you wish to extend.

```typescript
import transactionExtension from '@harlem/extension-transaction';

import {
    createStore
} from 'harlem';

const STATE = {
    firstName: 'Jane',
    lastName: 'Smith'
};

const {
    state,
    getter,
    mutation,
    transaction,
    onBeforeTransaction,
    onAfterTransaction,
    onTransactionSuccess,
    onTransactionError,
} = createStore('example', STATE, {
    extensions: [
        transactionExtension()
    ]
});
```

The transaction extension adds several new methods to the store instance (highlighted above).


## Usage

### Defining a transaction
A transaction can be defined the same way you define any other core functionality (eg. `getter`, `mutation` etc.).

```typescript
export default transaction('my-transaction', (payload, mutate) => {
    /*
    Any mutations run during this method
    will be rolled back if an error occurs
    */
});
```

- This extension comes with a performance cost. The entire state tree is cloned and stored before a transaction is run in order to rollback in the event of an error.
- This extension does not protect against issues attempting to roll back state in async scenarios
npm package: @harlem/plugin-devtools
Description: The official Vue devtools plugin for Harlem
Author: Andrew Courtice
Latest version: 3.1.8

# Harlem Devtools Plugin

The devtools plugin integrates Harlem into the Vue developer tools allowing you to see and edit your stores in real-time.

## Installation

To get started make sure you have the Vue developer tools installed in your browser. The Vue devtools can be installed here:
- [Chrome](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
- [Edge](https://microsoftedge.microsoft.com/addons/detail/vuejs-devtools/olofadcdnkkjdfgjcmjaadnlehnnihnl)
- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools)

Before installing the devtools plugin make sure you have installed `@harlem/core`.

```bash
yarn add @harlem/plugin-devtools
# or
npm install @harlem/plugin-devtools
```

The devtools extension is already included with Harlem when using the `harlem` package.


## Usage

Create an instance of the plugin and register it with Harlem:
```typescript
import App from './app.vue';
import devtoolsPlugin from '@harlem/plugin-devtools';

import {
    createVuePlugin
} from 'harlem';

createApp(App)
    .use(createVuePlugin({
        plugins: [
            devtoolsPlugin({
                label: 'My State'
            })
        ]
    }))
    .mount('#app');
```

3. Open your Vue devtools to see your stores.


### Options

- **label**: `string?` - the name that will appear in the Vue devtools pane. The default is 'Harlem'.
- **color**: `number?` - a Hexadecimal number indicating the color to be used on the timeline for Harlem events. The default is `0x40c48d`.

*(?) indicates an optional field*
npm package: @harlem/plugin-reset
Description: The official reset plugin for Harlem
Author: Andrew Courtice
Latest version: 1.3.2
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

<p align="center">
    <a href="https://harlemjs.com">
        <img src="https://raw.githubusercontent.com/andrewcourtice/harlem/main/docs/src/.vuepress/public/assets/images/logo-192.svg" alt="Harlem"/>
    </a>
</p>

# Harlem Reset Plugin

![npm](https://img.shields.io/npm/v/@harlem/plugin-reset)

This is the official Harlem plugin for resetting stores to their initial state.

<!-- TOC depthfrom:2 -->

- [Getting started](#getting-started)

<!-- /TOC -->

## Getting started

Before installing the reset plugin make sure you have installed `@harlem/core`.

1. Install `@harlem/plugin-reset`:
```
npm install @harlem/plugin-reset
```
Or if you're using Yarn:
```
yarn add @harlem/plugin-reset
```

2. Create an instance of the plugin and register it with Harlem:
```typescript
import App from './app.vue';

import harlem from '@harlem/core';
import createResetPlugin from '@harlem/plugin-reset';

createApp(App)
    .use(harlem, {
        plugins: [
            createResetPlugin()
        ]
    })
    .mount('#app');
```

3. Call the reset method with the name of the store you wish to reset:
```typescript
import {
    reset
} from '@harlem/plugin-reset';

export default function() {
    reset('my-store');
}
```
npm package: @harlem/plugin-snapshot
Description: The official snapshot plugin for Harlem
Author: Andrew Courtice
Latest version: 1.3.2
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

<p align="center">
    <a href="https://harlemjs.com">
        <img src="https://raw.githubusercontent.com/andrewcourtice/harlem/main/docs/src/.vuepress/public/assets/images/logo-192.svg" alt="Harlem"/>
    </a>
</p>

# Harlem Snapshot Plugin

![npm](https://img.shields.io/npm/v/@harlem/plugin-snapshot)

This is the official Harlem plugin for taking state snapshots and applying them when convenient.

<!-- TOC depthfrom:2 -->

- [Getting started](#getting-started)

<!-- /TOC -->

## Getting started

Before installing the snapshot plugin make sure you have installed `@harlem/core`.

1. Install `@harlem/plugin-snapshot`:
```
npm install @harlem/plugin-snapshot
```
Or if you're using Yarn:
```
yarn add @harlem/plugin-snapshot
```

2. Create an instance of the plugin and register it with Harlem:
```typescript
import App from './app.vue';

import harlem from '@harlem/core';
import createSnapshotPlugin from '@harlem/plugin-snapshot';

createApp(App)
    .use(harlem, {
        plugins: [
            createSnapshotPlugin()
        ]
    })
    .mount('#app');
```

3. Call the snapshot method with the name of the store you wish to snapshot:
```typescript
import {
    snapshot
} from '@harlem/plugin-snapshot';

export default function() {
    const snap = snapshot('my-store');

    // ...
}
```

4. Apply the snapshot:
```typescript
const snap = snapshot('my-store');

snap.apply(); // Apply the snapshot over the top of current state
snap.apply(true) // Replace state with the current snapshot
```
npm package: @harlem/plugin-ssr
Description: The official server-side rendering plugin for Harlem
Author: Andrew Courtice
Latest version: 3.1.8

# Harlem Server-Side Rendering Plugin

The SSR plugin adds support for using Harlem in a Vue server-side rendered application.

## Installation

Before installing the ssr plugin make sure you have installed `harlem`.

```bash
yarn add @harlem/plugin-ssr
# or
npm install @harlem/plugin-ssr
```

## Usage

### Server

Create an instance of the plugin and register it with Harlem on the **server**:
```typescript
import App from './app.vue';

import {
    createVuePlugin
} from 'harlem';

import {
    createServerSSRPlugin
} from '@harlem/plugin-ssr';

createSSRApp(App)
    .use(createVuePlugin({
        plugins: [
            createServerSSRPlugin()
        ]
    }));
```

Generate the bridging script block and insert it into the server-rendered content:
```typescript
import {
    renderToString
} from '@vue/server-renderer';

import {
    getBridgingScriptBlock
} from '@harlem/plugin-ssr';

let output = await renderToString(app);
output += getBridgingScriptBlock();
```

### Client

Create an instance of the plugin and register it with Harlem on the **client**:
```typescript
import App from './app.vue';

import {
    createVuePlugin
} from 'harlem';

import {
    createClientSSRPlugin
} from '@harlem/plugin-ssr';

createApp(App)
    .use(createVuePlugin({
        plugins: [
            createClientSSRPlugin()
        ]
    }));
```

Types that are not support by JSON serialisation will not be transferred from server to client. See the MDN documentation on JSON serialisation for more information: [MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
npm package: @harlem/plugin-transaction
Description: The official transaction plugin for Harlem
Author: Andrew Courtice
Latest version: 1.3.2
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

<p align="center">
    <a href="https://harlemjs.com">
        <img src="https://raw.githubusercontent.com/andrewcourtice/harlem/main/docs/src/.vuepress/public/assets/images/logo-192.svg" alt="Harlem"/>
    </a>
</p>

# Harlem Transaction Plugin

![npm](https://img.shields.io/npm/v/@harlem/plugin-transaction)

This is the official Harlem plugin for adding transactions to your stores. This plugin works similar to a SQL Database transaction in that if an error occurs during the transaction, all mutations that have taken place will be rolled-back.

This is particularly useful for updating state in multiple stores or multiple branches in the same store at the same time.

<!-- TOC depthfrom:2 -->

- [Getting started](#getting-started)

<!-- /TOC -->

## Getting started

Before installing the transaction plugin make sure you have installed `@harlem/core`.

1. Install `@harlem/plugin-transaction`:
```
npm install @harlem/plugin-transaction
```
Or if you're using Yarn:
```
yarn add @harlem/plugin-transaction
```

2. Create an instance of the plugin and register it with Harlem:
```typescript
import App from './app.vue';

import harlem from '@harlem/core';
import createTransactionPlugin from '@harlem/plugin-transaction';

createApp(App)
    .use(harlem, {
        plugins: [
            createTransactionPlugin()
        ]
    })
    .mount('#app');
```

3. Define a transaction that utilises multiple mutations:
```typescript
import {
    transaction
} from '@harlem/plugin-transaction';

import {
    setUserDetails,
    setUserPermissions
} from './mutations';

import {
    getUserDetails,
    getUserPermissions
} from './services';

/*
The setUserPermissions has an error in it causing
the transaction to fail in which case the user details
mutation will be rolled back.
*/
const setUserData = transaction('setUserData', payload => {
    const {
        details,
        permissions
    } = payload;

    setUserDetails(details);
    setUserPermissions(permissions);
});

/*
Here is an example action that loads some data
about a user and updates the store
*/
export async function loadUserData(userId) {
    const [
        details,
        permissions
    ] = await Promise.all([
        getUserDetails(userId),
        getUserPermissions(userId),
    ]);

    setUserData({
        details,
        permissions
    });
}
```