feat(composables): add usePatches

Author: vinpogo

README.md

@@ -1,5 +1,18 @@
 # Vue utilities
 
+## Composables
+
+A collection of useful Vue composables.
+
+- Package: [packages/composables](packages/composables)
+- Docs: [packages/composables/README.md](packages/composables/README.md)
+
+Install:
+
+```bash
+pnpm add @vingy/composables
+```
+
 ## Vuebugger
 
 Vue Devtools helper for debugging composables and reactive state. Add `debug()` to expose values in Devtools without production overhead.

packages/composables/README.md

@@ -0,0 +1,49 @@
+# Composables
+
+A collection of Vue composables for managing optimistic updates.
+
+## Features
+
+- Apply local patches to state while preserving them when server updates arrive
+- Automatic cleanup of redundant patches that match server state
+- Immutable updates powered by [Mutative](https://mutative.js.org/)
+
+## Quick Start
+
+```bash
+pnpm add @vingy/composables
+```
+
+## Usage
+
+### `usePatches`
+
+Manage optimistic updates that automatically clean up when server data arrives.
+
+```ts
+import { usePatches } from '@vingy/composables'
+
+const { data, patch, reset } = usePatches({
+  count: 0,
+  name: 'John',
+})
+
+// Apply optimistic update
+patch((draft) => {
+  draft.count++
+})
+
+// When server update arrives, matching patches are removed
+data.value = serverResponse
+
+// Or reset all patches manually
+reset()
+```
+
+**Returns:**
+
+- `data` - Reactive state with patches applied
+- `patches` - Current patches (readonly)
+- `patch(fn)` - Add optimistic update
+- `removePatch(fn)` - Remove specific patch
+- `reset()` - Clear all patches

packages/composables/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@vingy/composables",
+  "version": "0.0.0",
+  "description": "A collection of useful composables.",
+  "keywords": [
+    "composable",
+    "composition-api",
+    "state",
+    "vue"
+  ],
+  "license": "MIT",
+  "author": "vingy",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vinpogo/vue-utils"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w"
+  },
+  "dependencies": {
+    "mutative": "catalog:"
+  },
+  "devDependencies": {},
+  "peerDependencies": {
+    "vue": "catalog:"
+  },
+  "packageManager": "pnpm@10.30.1+sha512.3590e550d5384caa39bd5c7c739f72270234b2f6059e13018f975c313b1eb9fefcc09714048765d4d9efe961382c312e624572c0420762bdc5d5940cdf9be73a"
+}

packages/composables/src/index.ts

@@ -0,0 +1 @@
+export { usePatches } from './usePatches'

packages/composables/src/usePatches.ts

@@ -0,0 +1,57 @@
+import { create, type Draft } from 'mutative'
+import {
+  readonly,
+  ref,
+  toValue,
+  watchEffect,
+  type MaybeRefOrGetter,
+  type Ref,
+} from 'vue'
+
+type Patch<T> = (data: Draft<T>) => void
+
+export const usePatches = <
+  TState extends Record<string | number | symbol, any>,
+>(
+  initialData: MaybeRefOrGetter<TState>,
+) => {
+  const data = ref(toValue(initialData)) as Ref<TState>
+
+  const patches = ref<Patch<TState>[]>([]) as Ref<
+    Patch<TState>[]
+  >
+  const patch = (patch: Patch<TState>) =>
+    patches.value.push(patch)
+  const removePatch = (patch: Patch<TState>) =>
+    (patches.value = patches.value.filter(
+      (p) => p !== patch,
+    ))
+  const reset = () => (patches.value = [])
+
+  const flush = () => {
+    let d = data.value
+    patches.value.forEach((patch) => {
+      const patchedData = create<TState>(d, (draft) => {
+        patch(draft)
+      })
+      if (patchedData === d) {
+        removePatch(patch)
+      }
+      d = patchedData
+    })
+
+    data.value = d
+  }
+
+  watchEffect(() => {
+    flush()
+  })
+
+  return {
+    data,
+    patches: readonly(patches),
+    patch,
+    removePatch,
+    reset,
+  }
+}

packages/composables/src/usePatches.unit.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import { nextTick } from 'vue'
+import { usePatches } from './usePatches'
+
+describe('patches', () => {
+  it('no patches returns initial data', () => {
+    const initialData = { foo: 'bar' }
+    const { data } = usePatches(initialData)
+
+    expect(data.value).toEqual(initialData)
+  })
+
+  it('applies patch to data', async () => {
+    const initialData = { foo: 'bar' }
+    const { data, patch } = usePatches(initialData)
+    patch((data) => (data.foo = 'new value'))
+
+    await nextTick()
+
+    expect(data.value.foo).toBe('new value')
+  })
+
+  it('applies multiple patches to data', async () => {
+    const initialData = { foo: 'bar', fo: 'baz' }
+    const { data, patch } = usePatches(initialData)
+    patch((data) => (data.foo = 'new value'))
+    patch((data) => (data.fo = 'another value'))
+
+    await nextTick()
+    expect(data.value.foo).toBe('new value')
+    expect(data.value.fo).toBe('another value')
+  })
+
+  it('automatically cleans redundant patches', async () => {
+    const initialData = { foo: 'bar', bar: 'baz' }
+    const { data, patches, patch } = usePatches(initialData)
+
+    patch((data) => (data.foo = 'new value'))
+    patch((data) => (data.bar = 'new value'))
+    data.value = { foo: 'race condition', bar: 'new value' }
+
+    await nextTick()
+    expect(patches.value).toHaveLength(1)
+    expect(data.value).toEqual({
+      foo: 'new value',
+      bar: 'new value',
+    })
+  })
+
+  it('removes all patches', async () => {
+    const initialData = { foo: 'bar', bar: 'baz' }
+    const { data, patches, patch, reset } =
+      usePatches(initialData)
+    patch((data) => (data.foo = 'new value'))
+    patch((data) => (data.bar = 'new value'))
+    reset()
+
+    await nextTick()
+    expect(patches.value).toHaveLength(0)
+    expect(data.value).toEqual({ foo: 'bar', bar: 'baz' })
+  })
+})

packages/composables/tsdown.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  dts: true,
+  entry: 'src/index.ts',
+  format: 'esm',
+  inlineOnly: false,
+})

pnpm-lock.yaml

@@ -13,6 +13,7 @@ catalogs:
     '@vitest/browser-playwright': 4.1.2
     '@vue/devtools-api': ^8.0.5
     '@vue/tsconfig': ^0.8.1
+    mutative: ^1.3.0
     oxfmt: ^0.43.0
     oxlint: ^1.58.0
     pinia: ^3.0.4