# feather-state

> A feather light state framework

Latest version **1.1.15** (published 2025-01-18) · ISC license · 0 weekly downloads

## Install

```sh
npm install feather-state
pnpm add feather-state
yarn add feather-state
bun add feather-state
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.15 |
| Published | 2025-01-18 |
| First published | 2023-12-22 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 26.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | ingermarien@gmail.com |
| Maintainers | ingermarie |

## Links

- npm: https://www.npmjs.com/package/feather-state
- Repository: https://github.com/ingermarie/feather-state
- Homepage: https://github.com/ingermarie/feather-state#readme
- Issues: https://github.com/ingermarie/feather-state/issues
- npm.io page: https://npm.io/package/feather-state

## Recent versions

- 1.1.15 (latest) — 2025-01-18
- 1.1.14 — 2025-01-18
- 1.1.13 — 2024-12-27
- 1.1.12 — 2024-12-22
- 1.1.11 — 2024-12-22
- 1.1.10 — 2024-01-19
- 1.1.9 — 2024-01-13
- 1.1.8 — 2024-01-07
- 1.1.7 — 2024-01-06
- 1.1.6 — 2024-01-06
- 1.1.5 — 2024-01-01
- 1.1.4 — 2024-01-01
- 1.1.3 — 2024-01-01
- 1.1.2 — 2023-12-30
- 1.1.1 — 2023-12-30
- … 5 more at https://npm.io/package/feather-state/versions

## README

# Feather State
![gzip](https://img.shields.io/badge/gzip-468_bytes-green)
![license](https://img.shields.io/badge/license-ISC-blue)
![version](https://img.shields.io/badge/npm-v1.1.15-blue)

✨ A feather light state framework ✨ 468 bytes minified and gzipped - no dependencies

Companion framework:
- [feather-render](https://www.npmjs.com/package/feather-render)

Live examples:
- [Feather To-Do app](https://codesandbox.io/p/devbox/feather-to-do-app-k5ss8j)
- [Feather To-Do app (inline)](https://codesandbox.io/p/devbox/feather-to-do-inline-4zt7ls)

[![coffee](https://img.shields.io/badge/Buy_me_a_coffee%3F_❤️-634832)](https://www.paypal.com/paypalme/featherframework)

## Getting started
### Package
```
npm i feather-state
```

### ...or inline
```html
<head>
  <script src="feather-state.min.js"></script>
</head>
<body>
  <script>
    const { store } = window.__feather__ || {};
  </script>
</body>
```

## Index
Usage
- [Basic syntax](#basic-syntax)

Documentation
- [`store()`](#store)

Examples
- [Object values](#object-values)
- [Primitive values](#primitive-values)

## Usage
### Basic syntax
```ts
import { store } from 'feather-state';

const { watch, ...state } = store({
  completeCount: 1,
  todos: [{
    title: 'Todo 1',
    done: true
  }, {
    title: 'Todo 2',
    done: false
  }]
});

watch(state, 'todos', (next, prev) => {
  console.log(next, prev);
});

function addTodo(title: string): void {
  const newTodo = {
    title: title,
    done: false
  };
  state.todos = [
    ...todoStore.todos,
    newTodo
  ];
};
```

## Documentation
### `store()`
```ts
const { watch, state } = store(null);
const { watch, state } = store(undefined);
const { watch, state } = store(true);
const { watch, state } = store(0);
const { watch, state } = store('Hello, World!');
const { watch, state } = store(['Item 1', 'Item 2']);
const { watch, ...state } = store({ key: 'value' });
```
#### Parameters
- `state` - value

#### Return values
- `state` | `...state` - value
- `watch()` - watch for shallow mutations

### `store().watch()`
```ts
const unwatch = watch(parent, 'key', (next, prev) => {
  console.log(next, prev);
});
```
#### Parameters
- `parent` - parent object of watched value
- `key` - key of watched value
- `callback()` - function called when value changes

#### Return value
- `unwatch()` - function to unwatch value

## Examples
### Object values
```ts
const { watch, ...state } = store({
  isPlaying: true,
  playPauseAriaLabel: 'Pause'
});

watch(state, 'isPlaying', (next) => {
  if (next) {
    videoEl.play();
    state.playPauseAriaLabel = 'Pause';
  } else {
    videoEl.pause();
    state.playPauseAriaLabel = 'Play';
  }
});

const handleVisibilitychange = () => {
  if (document.visibilityState === "visible") {
    state.isPlaying = true;
  } else {
    state.isPlaying = false;
  }
};
```

### Primitive values
```ts
const { watch, ...isPlaying } = store(true);
const playPauseAriaLabel = store('Pause');

watch(isPlaying, 'state', (next) => {
  if (next) {
    videoEl.play();
    playPauseAriaLabel.state = 'Pause';
  } else {
    videoEl.pause();
    playPauseAriaLabel.state = 'Play';
  }
});

const handleVisibilitychange = () => {
  if (document.visibilityState === "visible") {
    isPlaying.state = true;
  } else {
    isPlaying.state = false;
  }
};
```

## Roadmap 🚀
- Find more performant way of unwatching values
- Cleaner way of referencing values in watcher parameters
- Get even tinier in size

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