pinia-plugin-persist-state 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+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).

package/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing to pinia-plugin-persist-state
+
+Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project.
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions with other contributors and maintainers.
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/pinia-plugin-persist-state.git
+   cd pinia-plugin-persist-state
+   ```
+3. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+4. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+## Development Workflow
+
+### Running Tests
+
+```bash
+npm run test          # Run tests in watch mode
+npm run test -- run   # Run tests once
+npm run coverage      # Generate coverage report
+```
+
+### Building
+
+```bash
+npm run build         # Run tests, build, and generate types
+```
+
+### Preview Changes
+
+```bash
+npm run dev           # Start development server
+npm run preview       # Preview production build
+```
+
+## Making Changes
+
+### Code Style
+
+- Follow the existing code style in the project
+- Use TypeScript for all new code
+- Ensure strict TypeScript compiler options are satisfied
+- Write descriptive variable and function names
+
+### Testing
+
+- Write tests for all new features and bug fixes
+- Ensure all existing tests pass before submitting
+- Aim for >80% code coverage
+
+### Commits
+
+- Write clear, descriptive commit messages
+- Use conventional commits format when possible:
+  - `feat:` for new features
+  - `fix:` for bug fixes
+  - `docs:` for documentation
+  - `test:` for tests
+  - `refactor:` for code refactoring
+  - `chore:` for build/dependencies
+
+Example:
+```
+feat: add support for custom reset callbacks
+
+- Implement resetStoreCallback in PluginSubscriberInterface
+- Add tests for reset functionality
+- Update documentation
+```
+
+## Submitting Changes
+
+1. **Push to your fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+2. **Create a Pull Request** on GitHub with:
+   - Clear title describing the change
+   - Detailed description of what changed and why
+   - Reference to related issues if applicable
+   - Test results showing coverage
+3. **Address review feedback** respectfully and promptly
+
+## Pull Request Guidelines
+
+- Keep PRs focused on a single feature or bug fix
+- Include tests for your changes
+- Update documentation if needed
+- Ensure CI checks pass
+- Request review from maintainers
+
+## Reporting Bugs
+
+Found a bug? Please create an issue on GitHub with:
+
+1. **Title:** Clear, concise description
+2. **Environment:** Node.js version, npm version, OS
+3. **Steps to Reproduce:** Minimal reproduction steps
+4. **Expected Behavior:** What should happen
+5. **Actual Behavior:** What actually happens
+6. **Additional Context:** Screenshots, error traces, etc.
+
+## Proposing Features
+
+Have an idea? Open a GitHub issue with:
+
+1. **Title:** Clear feature name
+2. **Description:** What problem does it solve?
+3. **Use Cases:** When would this be useful?
+4. **Proposed Solution:** How might it work?
+5. **Alternatives:** Other approaches considered
+
+## Release Process
+
+Maintainers will:
+
+1. Update `CHANGELOG.md` with changes
+2. Bump version in `package.json` following Semantic Versioning
+3. Create a git tag
+4. Publish to npm
+5. Create a GitHub release
+
+## Questions?
+
+- Check existing issues and discussions
+- Open a new GitHub discussion if needed
+- Contact maintainers via email
+
+Thank you for contributing! 🙏

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Alexandre Bidaud
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Alexandre Bidaud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,126 +1,126 @@
-# Persist Pinia State Plugin
-
-A small Pinia plugin that adds persistence and optional encryption to your Pinia stores. It integrates with browser storage (localStorage or sessionStorage) or IndexedDB and augments stores with convenient methods to persist, restore and control watching behavior.
-
----
-
-## 🔧 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?)`
-
----
-
-## ⚙️ Installation
-
-Install the package (example):
-
-```bash
-npm install --save persist-pinia-state
-```
-
-Then register the plugin with Pinia in your app entry (see `src/main.ts`):
-
-```ts
-import { createApp } from 'vue'
-import { createPinia } from 'pinia'
-import { createPlugin } from 'pinia-plugin-subscription'
-import { createPersistStatePlugin } from 'persist-pinia-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')
-], true))
-
-app.use(pinia)
-```
-
----
-
-## 📚 Usage
-
-When defining a store you can pass `storeOptions` (type: `PersistedStoreOptions`) as part of the `defineStore` options. Example in `src/stores/test.ts`:
-
-```ts
-// -- using defineAStore
-
-export const useTestStore = defineAStore('testStore', () => {
-  const myString = ref('Hello World')
-  const myStringEncrypted = ref('Sensitive Data')
-
-  return { myString, myStringEncrypted }
-}, {
-  persistedPropertiesToEncrypt: ['myStringEncrypted'],
-  watchMutation: true
-})
-
-// -- or using defineStore
-
-const storeOptions = {
-  persistedPropertiesToEncrypt: ['myStringEncrypted'],
-  watchMutation: true
-}
-
-export const useTestStore = defineStore('testStore', () => {
-  const myString = ref('Hello World')
-  const myStringEncrypted = ref('Sensitive Data')
-
-  return { myString, myStringEncrypted }
-}, { storeOptions })
-```
-
-If `persist` or `watchMutation` are `true` the plugin will attempt to persist the store state using the configured persister: localStorage, sessionStorage or IndexedDB.
-
----
-
-## 🔣 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.
-- `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.
-- `watchMutation?: boolean` — When `true`, plugin watches store mutations and automatically persists changes.
-
----
-
-## 🧰 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).
-- `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.
-- `watch(): void` — Start watching for mutations (sets `watchMutation = true`).
-- `stopWatch(): void` — Stop auto-persisting on mutations (sets `watchMutation = false`).
-
-Note: encrypted properties are automatically decrypted when remembered (if a crypto key was provided during plugin creation).
-
----
-
-## 🔐 Encryption
-
-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.
-
---- 
-
-## 💡 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.
-
----
-
-## 📜 License
-
-MIT
+# Persist Pinia State Plugin
+
+A small Pinia plugin that adds persistence and optional encryption to your Pinia stores. It integrates with browser storage (localStorage or sessionStorage) or IndexedDB and augments stores with convenient methods to persist, restore and control watching behavior.
+
+---
+
+## 🔧 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?)`
+
+---
+
+## ⚙️ Installation
+
+Install the package (example):
+
+```bash
+npm install --save persist-pinia-state
+```
+
+Then register the plugin with Pinia in your app entry (see `src/main.ts`):
+
+```ts
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import { createPlugin } from 'pinia-plugin-subscription'
+import { createPersistStatePlugin } from 'persist-pinia-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')
+], true))
+
+app.use(pinia)
+```
+
+---
+
+## 📚 Usage
+
+When defining a store you can pass `storeOptions` (type: `PersistedStoreOptions`) as part of the `defineStore` options. Example in `src/stores/test.ts`:
+
+```ts
+// -- using defineAStore
+
+export const useTestStore = defineAStore('testStore', () => {
+  const myString = ref('Hello World')
+  const myStringEncrypted = ref('Sensitive Data')
+
+  return { myString, myStringEncrypted }
+}, {
+  persistedPropertiesToEncrypt: ['myStringEncrypted'],
+  watchMutation: true
+})
+
+// -- or using defineStore
+
+const storeOptions = {
+  persistedPropertiesToEncrypt: ['myStringEncrypted'],
+  watchMutation: true
+}
+
+export const useTestStore = defineStore('testStore', () => {
+  const myString = ref('Hello World')
+  const myStringEncrypted = ref('Sensitive Data')
+
+  return { myString, myStringEncrypted }
+}, { storeOptions })
+```
+
+If `persist` or `watchMutation` are `true` the plugin will attempt to persist the store state using the configured persister: localStorage, sessionStorage or IndexedDB.
+
+---
+
+## 🔣 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.
+- `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.
+- `watchMutation?: boolean` — When `true`, plugin watches store mutations and automatically persists changes.
+
+---
+
+## 🧰 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).
+- `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.
+- `watch(): void` — Start watching for mutations (sets `watchMutation = true`).
+- `stopWatch(): void` — Stop auto-persisting on mutations (sets `watchMutation = false`).
+
+Note: encrypted properties are automatically decrypted when remembered (if a crypto key was provided during plugin creation).
+
+---
+
+## 🔐 Encryption
+
+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.
+
+--- 
+
+## 💡 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.
+
+---
+
+## 📜 License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,75 @@
+# Security Policy
+
+## 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.
+
+**Email:** [Security Contact - reach out via GitHub profile]
+
+Please include:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if available)
+
+We will:
+
+1. Acknowledge your report within 48 hours
+2. Investigate the issue thoroughly
+3. Work on a fix
+4. Release a patched version
+5. Credit you (if desired) in the release notes
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | ✅ Yes    |
+| < 0.1   | ❌ No     |
+
+## Security Best Practices
+
+When using pinia-plugin-subscription:
+
+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
+3. **Validate Store Data:** Validate data before storing in Pinia stores
+4. **Debug Mode:** Disable debug mode in production (set `false` when calling `createPlugin`)
+
+## Dependencies Security
+
+This project depends on:
+
+- **Pinia** - Vue state management
+- **Vue** - JavaScript framework
+
+We monitor these dependencies for vulnerabilities and recommend keeping them updated.
+
+## Vulnerability Disclosure Timeline
+
+- **Day 0:** Report received
+- **Day 1-2:** Initial assessment
+- **Day 3-7:** Fix development
+- **Day 7-14:** Security release
+- **Day 14:** Public disclosure
+
+## Scope
+
+This policy covers:
+
+- ✅ Code in the pinia-plugin-subscription repository
+- ✅ Published npm packages
+- ✅ Security of the plugin API
+
+This policy does NOT cover:
+
+- ❌ Security of Pinia or Vue (report to their respective projects)
+- ❌ Security of applications using this plugin
+- ❌ Social engineering attacks
+
+## Questions
+
+For general security questions or concerns, open a private security advisory on GitHub.
+
+Thank you for helping keep pinia-plugin-subscription secure! 🔒