# ramsay

> Simple API for Redux Reducers

Latest version **1.1.6** (published 2023-01-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install ramsay
pnpm add ramsay
yarn add ramsay
bun add ramsay
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.6 |
| Published | 2023-01-22 |
| First published | 2022-11-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 30.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | William Gibson |
| Maintainers | darnfish |

## Links

- npm: https://www.npmjs.com/package/ramsay
- Repository: https://github.com/darnfish/ramsay
- npm.io page: https://npm.io/package/ramsay

## Dependencies (2)

- [redux](https://npm.io/package/redux.md) ^4.2.0
- [pluralize](https://npm.io/package/pluralize.md) ^8.0.0

## Recent versions

- 1.1.6 (latest) — 2023-01-22
- 1.1.5 — 2023-01-22
- 1.1.4 — 2023-01-22
- 1.1.3 — 2023-01-22
- 1.1.2 — 2023-01-20
- 1.1.1 — 2023-01-19
- 1.1.0 — 2023-01-19
- 1.0.1 — 2022-11-28
- 1.0.0 — 2022-11-27

## README

# Ramsay
Simple API for Redux Reducers.

If your Redux store looks like `store.users[id] = userObject`, then Ramsay is for you.

## Installation
```
yarn add ramsay
```

## Usage
```tsx
import Ramsay from 'ramsay'

interface User {
	id: string
	name: string
}

const users = new Ramsay<User>('users') // for non-TS users: const users = new Ramsay('users')

/**
 * If you have a different field for your object id, or a different type (default is string):
 * new Ramsay<{ _id: number }, '_id'>('users', { idKey: '_id' })
 **/

// This is your reducer
const reducer = users.createReducer()
const { store, dispatch } = configureStore({ reducer })

// This is how you add/update a single object
dispatch(users.update({ id: 1, name: 'William' }))

console.log(store) // { 1: { id: 1, name: 'William' } }

// This is how you add/update multiple objects
dispatch(users.updateMany([{ id: 2, name: 'Walter' }, { id: 3, name: 'Jesse' }]))

console.log(store) // { 1: { id: 1, name: 'William' }, 2: { id: 2, name: 'Walter' }, 3: { id: 3, name: 'Jesse' } }

// This is how you remove a single object
dispatch(users.remove(1))

console.log(store) // { 2: { id: 2, name: 'Walter' }, 3: { id: 3, name: 'Jesse' } }

// This is how you remove multiple objects
dispatch(users.removeMany([2, 3]))

console.log(store) // {}
```

### Custom Id Field and/or Type
You can customize which field Ramsay will use for indexing, in addition to the type of that field.

By default, Ramsay will scan for `id` on your object and assume it is a string.

To change this, adjust the following:
```ts
import Ramsay from 'ramsay'

interface User {
	_id: number
	name: string
}

const users = new Ramsay<User, '_id'>('users', { idKey: '_id' })
// for non-TS users: const users = new Ramsay('users', { idKey: '_id' })
```

If you're using TypeScript, Ramsay will automatically pick up the type of your id key field.

### Extending Reducers
You can add your own custom actions ontop of Ramsay using `extend` parameter on the `createReducer` method:
```ts
const reducer = users.createReducer((state, action, prefix) => {
	switch(action.type) {
	case `${PREFIX}/CUSTOM_ACTION`:
		return users.withState(state).manuallyUpdateObject(action.userId, oldUser => ({ counter: oldUser.counter + 1 }))
	}
})
```

These additional actions will not take priority over Ramsay's built-in reducers for `update`, `updateMany`, `remove`, and `removeMany`.

### Dispatch Functions
Ramsay can create custom dispatch functions which you can use to avoid importing your reducer. See below:
```ts
const users = new Ramsay('users')

const updateUser = users.createUpdateMethod()

updateUser({ id: 1, name: 'William' })
```

You can also pass in a default set of options into this create method. They will not take priority over any options declared inside the generated method.

```ts
const updateUsers = users.createUpdateManyMethod({ mapObject: user => ({ ...user, customChange: 1 }) })

updateUsers([{ id: 1, name: 'William' }])

// { 1: { id: 1, name: 'William', customChange: 1 } }
```

### Plural and Singular Overrides
Ramsay attempts to figure out the singular and plural versions of your model name for internal use. For example:
```
users:
- singular: user
- plural: users

messages:
- singular: message
- plural: messages

eventEnrollments:
- singular: eventEnrollment
- plural: eventEnrollments
```

In some instances, Ramsay can't figure out a singular or plural version of your model name (for instance, `cash`).

You can provide your own custom singular/plural names in the options:
```ts
new Ramsay('cash', {
	plurals: {
		plural: 'cashes',
		singular: 'cash'
	}
})
```

### Useful Information
* By default, an action with the type `RESET` will reset the state to a default empty object (`{}`). You can disable this functionality by setting `options.disableResetAction` to `true` in your initial config (e.g. `new Ramsay('users', { disableResetAction: true })`)

## License
MIT

---
_Source: https://npm.io/package/ramsay · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._