pinia-plugin-persist-state 0.1.1 → 0.1.2-beta.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2-beta.0]
+
+### Added
+- Added an object-based `createPersistStatePlugin` configuration to explicitly select `storage`, `databaseName`, `objectStoreName`, and `cryptKey`.
+- Added `persistenceKey` to persist a store under a stable or application-specific record key instead of its Pinia `$id`.
+- Added opt-in cache metadata and restore policies through `cache`, including `maxAge`, schema `version`, and expiration/version-mismatch actions.
+- Added `debounceMs` for trailing, per-store automatic persistence; automatic writes use a 200 ms delay by default.
+- Added `flushPersistedState()` to immediately write the latest store state and cancel a pending debounced write.
+- Added `transformState` to convert a filtered snapshot into an application-defined persistent representation before it is stored.
+- Added `fake-indexeddb` integration tests for real IndexedDB updates, connection reuse, selective deletion, database isolation, and transaction errors.
+
+### Changed
+- Retained the legacy positional `createPersistStatePlugin(storageOrDatabaseName?, cryptKey?)` signature for compatibility. Non-window-storage names are interpreted as IndexedDB database names using the `persistedStore` object store.
+- Replaced per-store `dbName` with `storage` to express a storage backend override without conflating the backend, IndexedDB database, and persisted record key.
+- IndexedDB now reuses open connections and waits for transaction completion before resolving storage operations.
+- The default IndexedDB model uses one application database, a stable object store, and one record per persisted Pinia store.
+- `removePersistedState()` is asynchronous and waits for prior writes to complete.
+- Window Storage remains responsible for serializing complete records; IndexedDB retains native values.
+- `null`, `undefined`, and values considered empty by `pinia-plugin-subscription` are intentionally omitted from persisted snapshots before `transformState` runs.
+
+### Fixed
+- Replaced IndexedDB read-then-update writes with atomic `put()` writes to prevent stale records from being rewritten.
+- Serialized persistence requests and discard superseded snapshots before writing, preventing older asynchronous writes from overwriting newer state.
+- Aligned package ESM metadata with the generated bundle by removing the reference to a nonexistent CommonJS artifact.
+- Aligned storage operations on asynchronous `Promise<void>` contracts so write and removal failures can propagate to callers.
+
+### Security
+- New encrypted values use AES-GCM with PBKDF2 and an independent random 16-byte salt plus 12-byte IV for every encrypted value.
+- Introduced the versioned encrypted payload format `v1:salt:iv:ciphertext`.
+- Preserved decryption support for legacy `iv:ciphertext` payloads generated with the historical salt.
+- Encrypted properties preserve JSON-compatible types including strings, numbers, booleans, arrays, and objects; unsupported values are rejected.
+
 ## [0.1.1]
 
 ### Fixed

package/README.md

@@ -4,23 +4,23 @@ A small Pinia plugin that adds persistence and optional encryption to your Pinia
 
 ---
 
-## 🔧 Features
+## Features
 
 - Persist store state to LocalStorage, SessionStorage or IndexedDB
 - Selective encryption for specific properties using Web Crypto (AES-GCM)
 - Per-store options via `storeOptions` when defining a store
 - Augmented store API: `persistState`, `remember`, `removePersistedState`, `watch`, `stopWatch`
-- Simple initialization through `createPersistStatePlugin(dbName?, cryptKey?)`
+- Explicit configuration of the persistence backend and IndexedDB storage
 - SSR-safe hydration flow: methods are injected immediately on client, persistence restore is executed during hydration lifecycle
 
 ---
 
-## ⚙️ Installation
+## Installation
 
 Install the package (example):
 
 ```bash
-npm install --save persist-pinia-state
+npm install --save pinia-plugin-persist-state
 ```
 
 Then register the plugin with Pinia in your app entry (see `src/main.ts`):
@@ -29,15 +29,18 @@ Then register the plugin with Pinia in your app entry (see `src/main.ts`):
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'
 import { createPlugin } from 'pinia-plugin-subscription'
-import { createPersistStatePlugin, PLUGIN_NAME } from 'persist-pinia-state'
+import { createPersistStatePlugin, PLUGIN_NAME } from 'pinia-plugin-persist-state'
 
 const app = createApp(App)
 const pinia = createPinia()
 
-// Pass `dbName` (e.g. 'localStorage', 'sessionStorage' or a DB name for IndexedDB)
-// and an optional `cryptKey` to enable encryption support
 pinia.use(createPlugin([
-  createPersistStatePlugin('localStorage', 'my-secret-key')
+  createPersistStatePlugin({
+    storage: 'indexedDB',
+    databaseName: 'my-application',
+    objectStoreName: 'persistedStore',
+    cryptKey: 'my-secret-key'
+  })
 ]))
 
 app.use(pinia)
@@ -47,10 +50,10 @@ For Nuxt/SSR projects, prefer `createHydrationPlugin` from `pinia-plugin-subscri
 
 ```ts
 import { createHydrationPlugin } from 'pinia-plugin-subscription'
-import { createPersistStatePlugin } from 'persist-pinia-state'
+import { createPersistStatePlugin } from 'pinia-plugin-persist-state'
 
 pinia.use(createHydrationPlugin([
-  createPersistStatePlugin('localStorage', 'my-secret-key')
+  createPersistStatePlugin({ storage: 'localStorage', cryptKey: 'my-secret-key' })
 ], {
   runtimeEnvironment: import.meta.client ? 'client' : 'server'
 }))
@@ -58,7 +61,7 @@ pinia.use(createHydrationPlugin([
 
 ---
 
-## 📚 Usage
+## Usage
 
 When defining a store you can pass `storeOptions` (type: `PersistedStoreOptions`) as part of the `defineStore` options. Example in `src/stores/test.ts`:
 
@@ -92,27 +95,38 @@ export const useTestStore = defineStore('testStore', () => {
 
 If `persist` or `watchMutation` are `true` the plugin will attempt to persist the store state using the configured persister: localStorage, sessionStorage or IndexedDB.
 
+`createPersistStatePlugin(storageOrDatabaseName?, cryptKey?)` remains supported for compatibility. A value of `'localStorage'` or `'sessionStorage'` selects that storage; any other string is interpreted as an IndexedDB database name and uses the default `persistedStore` object store.
+
 ---
 
-## 🔣 PersistedStoreOptions
+## PersistedStoreOptions
 
 Fields available when setting `storeOptions`:
 
-- `dbName?: string` — (Optional) Name of the database/storage to use to persist the store state (use only if different from the one defined in the plugin). Use `'localStorage'` or `'sessionStorage'` for window storage, or any other name to use IndexedDB.
+- `storage?: 'localStorage' | 'sessionStorage' | 'indexedDB'` — Optional backend override for this store. IndexedDB settings remain configured at plugin level.
+- `persistenceKey?: string` — Record key used for this store. Defaults to the Pinia `$id` and is useful for stable, readable or parameterized keys.
+- `cache?: CacheOptions` — Opt-in cache metadata and restore policy. Without it, the state is persisted in the historical raw format.
 - `excludedKeys?: string[]` — List of state properties that should NOT be persisted.
 - `persist?: boolean` — Enable or disable persistence for the store (default: `false`).
 - `persistedPropertiesToEncrypt?: string[]` — List of property names to be encrypted when persisted.
+- `transformState?: (state) => state` — Optional synchronous transformer applied to the filtered snapshot after selected properties are encrypted and before storage. Use it to convert application-specific values into a persistent representation.
 - `watchMutation?: boolean` — When `true`, plugin watches store mutations and automatically persists changes.
+- `debounceMs?: number` — Delay in milliseconds before an automatic persistence is written. Defaults to `200`; use `0` to persist each mutation immediately.
+
+`CacheOptions` supports `maxAge?: number`, `version?: number`, `onExpired?: 'ignore' | 'remove' | 'restore'`, and `onVersionMismatch?: 'ignore' | 'remove' | 'restore'`. Cache metadata is written only when `cache` is configured.
+
+`null` and `undefined` state values are intentionally omitted from persisted snapshots. Empty values handled by `pinia-plugin-subscription` are also omitted. `transformState` receives the resulting snapshot and must return the representation to persist; it must not mutate the store state. A transformer only changes the written representation, so use values that can be restored directly by the store or handle reconstruction in the store hydration flow.
 
 ---
 
-## 🧰 Augmented Store API
+## Augmented Store API
 
 When the plugin is active stores gain the following methods (see `PersistedStore` interface):
 
 - `persistState(): Promise<void>` — Immediately persist the current store state (ignores empty values and excluded keys).
+- `flushPersistedState(): Promise<void>` — Cancels a pending automatic persistence and immediately persists the current store state.
 - `remember(): Promise<void>` — Load persisted state and apply it to the store (used on plugin init).
-- `removePersistedState(): void` — Delete the persisted entry for this store.
+- `removePersistedState(): Promise<void>` — Delete the persisted entry for this store after any running write completes.
 - `watch(): void` — Start watching for mutations (sets `watchMutation = true`).
 - `stopWatch(): void` — Stop auto-persisting on mutations (sets `watchMutation = false`).
 
@@ -120,21 +134,23 @@ Note: encrypted properties are automatically decrypted when remembered (if a cry
 
 ---
 
-## 🔐 Encryption
+## Encryption
+
+Optionally supply a `cryptKey` when creating the plugin, e.g. `createPersistStatePlugin({ storage: 'localStorage', cryptKey: 'my-secret' })`.
+The plugin uses the Web Crypto API (PBKDF2 + AES-GCM) to encrypt properties listed in `persistedPropertiesToEncrypt` on each store. Only the specified properties will be encrypted. New encrypted values use a versioned `v1:salt:iv:ciphertext` format with a random salt and IV for every value; records in the previous `iv:ciphertext` format remain readable.
 
-Optionally supply a `cryptKey` when creating the plugin, e.g. `createPersistStatePlugin(undefined, 'my-secret')`.
-The plugin uses the Web Crypto API (PBKDF2 + AES-GCM) to encrypt properties listed in `persistedPropertiesToEncrypt` on each store. Only the specified properties will be encrypted.
+The storage adapter remains responsible for serializing the persisted record: Window Storage uses JSON and IndexedDB stores native values. Encryption encodes only the selected value and restores its JSON type (string, number, boolean, array, or object). Encrypted values must be JSON-serializable; functions, symbols, `undefined`, cyclic objects, and `BigInt` are not supported.
 
 --- 
 
-## 💡 Notes
+## Notes
 
 - The plugin augments Pinia store definitions using the `pinia-plugin-subscription` helper. It adds `storeOptions` to Pinia's `DefineStoreOptionsBase` type through declaration merging.
 - The $reset method is available for stores augmented by the plugin (also setup store 😁).
-- When using IndexedDB, the persister stores objects with a `storeName` key path.
+- With IndexedDB, `databaseName` identifies the application database, `objectStoreName` identifies the persisted record collection, and `persistenceKey` (or `$id`) identifies each record.
 
 ---
 
-## 📜 License
+## License
 
 MIT

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Reporting Security Vulnerabilities
 
-If you discover a security vulnerability in pinia-plugin-subscription, please do **NOT** open a public GitHub issue. Instead, please email the maintainers privately.
+If you discover a security vulnerability in pinia-plugin-persist-state, please do **NOT** open a public GitHub issue. Instead, please email the maintainers privately.
 
 **Email:** [Security Contact - reach out via GitHub profile]
 
@@ -30,7 +30,7 @@ We will:
 
 ## Security Best Practices
 
-When using pinia-plugin-subscription:
+When using pinia-plugin-persist-state:
 
 1. **Keep Dependencies Updated:** Regularly update Pinia, Vue, and other dependencies to the latest versions
 2. **Review Plugin Code:** Always review subscriber code before using in production
@@ -58,7 +58,7 @@ We monitor these dependencies for vulnerabilities and recommend keeping them upd
 
 This policy covers:
 
-- ✅ Code in the pinia-plugin-subscription repository
+- ✅ Code in the pinia-plugin-persist-state repository
 - ✅ Published npm packages
 - ✅ Security of the plugin API
 
@@ -72,4 +72,4 @@ This policy does NOT cover:
 
 For general security questions or concerns, open a private security advisory on GitHub.
 
-Thank you for helping keep pinia-plugin-subscription secure! 🔒
+Thank you for helping keep pinia-plugin-persist-state secure! 🔒