pinia-plugin-subscription 0.1.4 → 0.1.6-beta.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.6]
+
+### Added
+- Added `execution` and `hydrationScheduler` support on `PluginSubscriber` / `PluginSubscriberInterface`.
+- Added `createHydrationPlugin()` as the dedicated Nuxt / SSR hydration helper.
+- Added `PluginSubscriptionOptions` for hydration-specific runtime overrides without changing the default `createPlugin()` API.
+
+### Changed
+- The execution policy now defaults to the subscriber itself, with framework-specific overrides available only through the hydration helper.
+- `PluginSubscription` resolves hydration timing from the subscriber before falling back to the global runtime scheduler.
+
+### Fixed
+- Avoided SSR hydration crashes by allowing client-only Pinia plugins to be skipped on the server or deferred on the client.
+
+## [0.1.5]
+
+Minor change
+
+
 ## [0.1.4]
 
 ### Added
@@ -14,9 +33,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - `getDefineAStoreSetupContext()` now falls back to store ID lookup during plugin execution timing.
+- `defineAStoreSetup()` now stores setup contexts only for stores with `storeOptions.enhancedStore = true`.
+- `defineAStoreSetup()` now removes ID-indexed setup contexts after weak-map registration and on store disposal.
+- `defineAStoreSetup()` now logs setup-context map size transitions when `storeOptions.debug = true`.
 - Public exports now include `defineAStoreCtx`, `getEnhancedStore`, and `setEnhancedStore`.
 - GitHub Actions now publishes GitHub pre-releases to npm with the `beta` dist-tag.
 
+### Added
+- Added a Vitest performance-oriented test for setup-context tracking behavior with and without `enhancedStore`.
+
 ### Deprecated
 - `ctx.extensions.extending` is deprecated. Use `ctx.extensions.enhancedStore`.
 - `getExtendingStore()` is deprecated. Use `getEnhancedStore()`.

package/README.md

@@ -83,13 +83,58 @@ export const myStoreSubscriber: PluginSubscriberInterface = {
 
 - **Debug mode:** Specifies the name of the plugin(s) to debug as the second argument to `createPlugin` to enable detailed logging.
 - **Reset callbacks:** Define `resetStoreCallback` to run custom logic when a store is reset.
+- **SSR and hydration control:** Configure whether each subscribed plugin runs on the server, the client, or only after client hydration.
 
 ## API Reference
 
-### `createPlugin(subscribers: PluginSubscriber[], debug?: boolean): PiniaPlugin`
+### `createPlugin(subscribers: PluginSubscriber[], debug?: string[]): PiniaPlugin`
 
 Creates and returns a Pinia plugin from the provided `subscribers`. Each subscriber is invoked when a store is registered.
 
+### `createHydrationPlugin(subscribers: PluginSubscriber[], options?: PluginSubscriptionOptions): PiniaPlugin`
+
+Creates a Pinia plugin dedicated to SSR / Nuxt hydration orchestration. This helper is useful when a store plugin needs a runtime-specific scheduler or environment override without forcing every app to re-declare the plugin’s execution policy.
+
+```typescript
+import { createHydrationPlugin, PLUGIN_NAME as PPS } from 'pinia-plugin-subscription'
+
+pinia.use(createHydrationPlugin([
+  persistedStateSubscriber
+], {
+  debug: [PPS],
+  hydrationScheduler: (run) => {
+    nextTick(() => run())
+  }
+}))
+```
+
+### SSR / Nuxt hydration control
+
+The source of truth for hydration policy stays on the subscriber itself. For example, a client-only plugin should declare its execution directly:
+
+```typescript
+export const persistedStateSubscriber: PluginSubscriberInterface = {
+  name: 'persisted-state',
+  execution: {
+    environment: 'client',
+    hydration: 'defer',
+  },
+  hydrationScheduler: (run) => {
+    nextTick(() => run())
+  },
+  invoke: (context, debug) => {
+    // ...
+    return true
+  }
+}
+```
+
+Available execution options:
+
+- `environment: 'both' | 'client' | 'server'` — controls where the subscriber is allowed to run.
+- `hydration: 'immediate' | 'defer'` — on the client, `defer` schedules execution after hydration.
+- `hydrationScheduler` can be provided either on a subscriber or via `createHydrationPlugin()` to override the execution timing when needed.
+
 ### `defineAStoreCtx(id, setup, options?)`
 
 Use actions or access the state, added by one or more plugins, when defining the store.
@@ -111,10 +156,15 @@ export const useMyStore = defineAStoreCtx('myStore', (ctx) => {
 `ctx.extensions` now supports:
 - `enhancedStore`
 
+The setup context is indexed internally only when `storeOptions.enhancedStore` is set to `true` (this is enabled automatically by `defineAStoreCtx`).
+The temporary lookup by store id is now cleaned as soon as the weak-map association is established (and on store dispose), which limits map growth over time.
+When `storeOptions.debug` is `true`, setup-context map size transitions are logged for observability.
+
 ### `PluginSubscriberInterface`
 
 An object with at least an `invoke(context: PiniaPluginContext, debug?: boolean)` method, plus optional properties:
 
+- `execution?: { environment?: 'both' | 'client' | 'server'; hydration?: 'immediate' | 'defer' }`
 - `resetStoreCallback?: (store?: any) => void`
 - `storeOnActionSubscription?: { store, callback }` (getter)
 - `storeMutationSubscription?: { store, callback }` (getter)
@@ -143,6 +193,18 @@ import { addStore } from './src/extending-pinia-store/plugins/stores'
 class ExtendingStoreSubscriber extends PluginSubscriber<StoreExtension> {
   constructor() {
     super('extendsPiniaStore', StoreExtension.customizeStore.bind(StoreExtension))
+
+    // Controls when this subscriber may run and whether it should wait for hydration on the client.
+    this.execution = {
+      environment: 'client',
+      hydration: 'defer',
+    }
+
+    // Optional framework-specific scheduler for deferred execution.
+    this.hydrationScheduler = (run) => {
+      nextTick(() => run())
+    }
+
     this.pluginCreated = addStore
   }
 }
@@ -150,6 +212,12 @@ class ExtendingStoreSubscriber extends PluginSubscriber<StoreExtension> {
 export const extendingStoreSubscriber = new ExtendingStoreSubscriber()
 ```
 
+This example shows the recommended pattern for SSR / Nuxt-safe plugins:
+
+- `execution.environment` restricts the subscriber to `'both'`, `'client'`, or `'server'`
+- `execution.hydration` is `'immediate'` by default and can be set to `'defer'` when the plugin must wait for client hydration
+- `hydrationScheduler` lets you override the runtime scheduling behavior, for example with Nuxt/Vue `nextTick()`
+
 ## The `Store` Class — Summary
 
 The `Store` class (see [src/core/Store.ts](src/core/Store.ts)) is a wrapper around a `PiniaStore` providing: