npm package: @filipigustavo/react-enc-dec
Description: A simple library to hide values in localStorage easily.
Author: Filipi Gustavo Boltão Silva
Latest version: 0.1.1

# React Enc-Dec

A simple library to hide values in localStorage easily.

See this lib in action [here](https://filipigustavo.github.io/react-enc-dec/)

## Installing

In your project's terminal:

```bash
$ npm i @filipigustavo/react-enc-dec
```

## Usage

The `useHash` hook returns `enc`, `dec`, `remove`, `renew` and `clear` methods, in addition to `index` variable.

Use it to save encrypted data and get it from localStorage.

useHash generates two basic keys in your localStorage for each instance you create:

- index ([globalPrefix]\_[prefix]\_index)
- security ([globalPrefix]\_[prefix]\_security)

### Params

useHash hook accepts a configuration object with:

#### `prefix?: string`

By default useHash uses `""`.

#### `globalPrefix?: string`

By default useHash uses `"ed"`.

#### `Generator?: AbstractGenerator<H>`

By default useHash uses internal `HashGenerator` class.

#### `notAllowedKeyCallback?: (err: Error) => void`

By default useHash use a function with `alert(err)`.

**All this parameters are optional.**

### Returns

#### `enc: (key: string, value: any) => void`

It's used to encrypt data and save in localStorage. `enc('my-key', 'my-value')`

In localStorage, the generated key is `[globalPrefix]_[prefix]_[key]`

#### `dec: (key: string) => string`

It's used to get decrypted value from localStorage. `const myValue = dec('my-key')`

#### `remove: (key: string) => void`

It's used to remove value from localStorage. `remove('my-key')`

#### `renew: () => void`

It's used to renew the security hash and re-encrypt all the values related to this instance. `renew()`

#### `clear: () => void`

It's used to erase instance's index and remove all related keys. `clear()`

#### `index: string`

This variable can be used by you to control all the variables from instance.

```jsx
<>
  {index.map(item => <button onClick={() => remove(item)}>Remove<button>)}
</>
```

- You can have one or more instances in your application using `globalPrefix` and `prefix` in `useHash`.
- You can change the way `useHash` generates security hash using `Generator` and passing your own `AbstractGenerator<H>` class.
- You can do whatever you want with the error related to `NOT_ALLOWED_KEY`. Not allowed keys is `index` and `security`.

## Example: simple usage

You can see this lib in action with advanced examples [here](https://filipigustavo.github.io/react-enc-dec/)

```jsx
import { useState } from 'react'
import { useHash } from '@filipigustavo/react-enc-dec'

function App() {
  const { enc, dec } = useHash({})
  const [raw, setRaw] = useState('')
  const [decrypted, setDecrypted] = useState('')
  
  const handleEnc = () => enc('local-storage-key', raw)

  const handleDec = () => {
    const val = dec('local-storage-key')
    setDecrypted(val)
  }

  return (
    <div>
      <h1>Enc/Dec</h1>

      <div>
        <input value={raw} onChange={(ev) => setRaw(ev.target.value)} />
        <button onClick={handleEnc}>Encrypt data</button>
        <button onClick={handleDec}>Decrypt data</button>
        <br />
        Decrypted Value: {decrypted}
      </div>
    </div>
  )
}

export default App
```

If you want another namespaced instance, just pass a `prefix` in configuration object of `useHash`. You can have so many instances you want combining `globalPrefix` and (or just) `prefix`.

```js
// default usage
const { enc, dec } = useHash({})
// using with a namespace
const { enc: enc2, dec: dec2 } = useHash({ prefix: 'my_prefix' })
```

**IMPORTANT**: Don't forget to always use the same `prefix` and `globalPrefix` to get data from this new instance.

## Changing the way `useHash` generates security hash

To do it, you should make a class that extends `AbstractGenerator` with `generateHashParts` and `handleHash` methods.

`AbstractGenerator` accepts a Generic type. `generateHashParts` should return the same type declared in the class and `handleHash` accepts a parameter with these type and always returns a `string`.

#### `AbstractGenerator<H>`

This is the base class that works with hashs. You should extend it and implement `generateHashParts` and `handleHash` methods.

#### `generateHashParts(): H`

This method generates the base to make the real hash. This value will be persisted in localStorage.

#### `handleHash(hash: H): string`

This method takes the value generated by `generateHashParts` and transforms it in the real hash used to encrypt/decrypt data. This value WILL NOT be persisted in localStorage.

```ts
import AbstractGenerator from '@filipigustavo/react-enc-dec'

class NewGenerator extends AbstractGenerator<string[]> {
  generateHashParts: TGenerateHashParts<string[]> = () => {
    const randomNum = () => `${Math.floor(Math.random() * 10)}`

    return [randomNum(), randomNum(), randomNum()]
  }

  handleHash: THandleHash<string[]> = (localhashs: string[]) => {
    const key: string = localhashs.sort().join('')

    return key
  }
}

export default NewGenerator
```

Now you can use your new hash class in useHash hook object configuration:

```js
const { enc, dec } = useHash({ Generator: NewGenerator })
```