# @gxs/vue-atom

> A new type of atomic state management library for vue3

Latest version **0.2.0** (published 2021-10-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @gxs/vue-atom
pnpm add @gxs/vue-atom
yarn add @gxs/vue-atom
bun add @gxs/vue-atom
```

## Health

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

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2021-10-19 |
| First published | 2021-10-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 36.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | gsx114/usagisah |
| Maintainers | usagisah |
| Keywords | vue store, vue atom, vue-atom, vueAtom, @gxs, @gxs/vue-atom |

## Links

- npm: https://www.npmjs.com/package/@gxs/vue-atom
- npm.io page: https://npm.io/package/@gxs/vue-atom

## Dependencies (2)

- [vue](https://npm.io/package/vue.md) ^3.2.20
- [typescript](https://npm.io/package/typescript.md) ^4.4.4

## Recent versions

- 0.2.0 (latest) — 2021-10-19
- 0.1.1 — 2021-10-17
- 0.1.0 — 2021-10-17

## README

## vue-atom

- vue-atom是vue3的一个原子状态管理库。
  
- 在**composition api**的加持下使得共享状态变得非常简单，它甚至可以简化成仅仅一行`export const store = reactive(initState)`就能实现全组件的状态的共享。但是，这对于一个全局共享库来说过于简单，vue-atom在其之上做了最低程度的封装，例如：插件，状态关联，hook，使其好适用于各种规模的项目。
  
- vue-atom的定位不在于替代vuex，它是你的另一种状态管理的选择, 如果你听说过 **recoil.js** 这或许可以是你在vue下的选择。




## install

```bash
npm install @gxs/vue-atom -S
```




## 基本使用

```ts
// store.ts 创建
import { defineAtom } from "@gxs/vue-atom"
export const useAtom0 = defineAtom("root", { msg: "root atom" })

// 可以创建任意数量
export const useAtom1 = defineAtom("item", { msg: "item atom" })
```
``` vue
<script>
// any.vue
import { useAtom } from "store.ts"
const store = useAtom() // { msg: "root atom" }
</script>
```


## 高级应用

调用`defineAtom()`会创建一个工厂函数，该工厂函数静态的挂载了各种辅助管理的方法，它们被用于不同的场景。它的类型声明如下所示：
```ts
declare type AtomFactory<T = {}, S = {}, F = T> = {
    (prop?: unknown): F;
    computed<T, N>(name: string | symbol, options: {
        get: ComputedGetter<T>;
        set: ComputedSetter<T, N>;
    }): void;
    computed<T>(name: string | symbol, getter: ComputedGetter<T>): void;
    use(option: AtomFactory | ReturnType<useAtomPlugin>): AtomFactory;
    fork(atomFactory: AtomFactory): AtomFactory;
    onGetter<T>(fn: onGetter): AtomFactory;
    onChildMount(fn: onChildMount): AtomFactory;
    [PluginCustomProperty: string | symbol]: any;
} & S;
```

### [插件(`use`)🔗](https://github.com/gxs114/tz/tree/main/packages/VueAtom/example/plugin)

适用于特殊状态的复用。在初始化时会接收到每个被使用的`atom`的`name`,响应式对象，静态工厂函数，可以发挥想象去做喜欢的事.



### 状态关联(`fork` | `use`)

```ts
import { defineAtom } from "@gxs/vue-atom"
const rootAtom = defineAtom("root", { msg: "root atom" })
const child1Atom = defineAtom("atom1", { msg: "atom1" })

// 通过fork关联
child1Atom.fork(rootAtom)

// 通过use关联
rootAtom.use(child1Atom)

// 注册父Atom的钩子进行混入
rootAtom.onChildMount((options) => {
  const { child: { state } } = options
  if(child.name === "atom1") {
    state.MMM = "from parent mixin"
  }
})
```

每个`atom`就像是状态管理中的`component`，`vue-atom`提供了相关的**API**让多个`atom`进行关联, 关联后会触发`onChildMount`注册的回调函数。

使用起来的感觉和插件有点类似，它们之间的差异点主要有两项：
1. 关联会在内部记录关联的`atom`形成状态树
2. 两个`atom`存在依赖项但同时又都要被组件所使用，此时用插件会显得繁琐


### [hook🔗](https://github.com/gxs114/tz/tree/main/packages/VueAtom/example/hook)

`onGetter`，当获取时动态的决定返回

`onChildMount`，当自身作为其他`atom`的顶层依赖时自动触发




### [全部 example🔗](https://github.com/gxs114/tz/tree/main/packages/VueAtom/example)


## Q&A

1. 为什么`computed`被当成了静态属性进行使用而不是引用`vue`？
   
这是妥协后的处理，`computed`作为派发状态使用时需要依赖已经是响应式的状态，不然会无法响应式更新。但是在响应式是调用后的产物。

2. 为什么只处理的状态，而没有逻辑相关的处理？
   
在当下`hook`提供了强大的逻辑复用能力，所有与状态管理无关的业务逻辑都应该以**自定义hook的**方式被单独管理。

3. 代码过于分散，写起来像是面条，这是缺陷吗？
   
如开头的介绍，`vue-atom`只做用于管理状态最低程度的整合。通常情况下你不会在一个`atom`用用到所有的API，如果真的全用到了全部，甚至感觉还不够，你或许可以考虑将`vue-atom`二次封装，`useAtomValue`这个API会暴露`atom`内部维护的上下文，这对你或许有用。

4. 它与`Vuex`相比较优势是什吗？
   
体积小，类型化，灵活，与`composition api`共存，对于高要求的模块化项目支持更好，更强的可塑性。

5. 定位是什么？

状态的复杂度可以宏观的分为三类，低中高。
低：期望响应式的全局状态
中：在之前的基础上，期待一定的管理功能
高：期望按自己的想法来
`vue-atom`的定位是承上启下，对于中低要求都能开箱即用。对于高要求的大型项目，自身关联机制可以提供很好的底层支持，它不要求一定要在顶层进行关联，它可以是任意一个`atom`节点。

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