pinia-plugin-subscription 0.1.5 → 0.1.6-beta.1

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.
+- Added optional `hydrate()` and `afterHydration()` lifecycle hooks to the subscriber and base `Store` contract for SSR-safe initialization logic.
+
+### 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.
+- The base `Store` class now exposes lifecycle stubs so browser-only bootstrap code can be triggered after the plugin is accepted for execution instead of during construction.
+
+### Fixed
+- Avoided SSR hydration crashes by allowing client-only Pinia plugins to be skipped on the server or deferred on the client.
+- Prevented browser-only initialization from running during server-side store creation by moving hydration bootstrap behind the subscriber lifecycle hooks.
+
+## [0.1.5]
+
+Minor change
+
+
 ## [0.1.4]
 
 ### Added
@@ -15,9 +37,14 @@ 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.
@@ -112,11 +157,17 @@ export const useMyStore = defineAStoreCtx('myStore', (ctx) => {
 - `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' }`
+- `hydrationScheduler?: (run: () => void) => void`
+- `hydrate?: (context, debug) => void | Promise<void>` — optional hook for SSR-safe store initialization after the subscriber is accepted for execution
+- `afterHydration?: (context, debug) => void | Promise<void>` — optional lifecycle hook for post-hydration work
 - `resetStoreCallback?: (store?: any) => void`
 - `storeOnActionSubscription?: { store, callback }` (getter)
 - `storeMutationSubscription?: { store, callback }` (getter)
@@ -138,6 +189,7 @@ The project provides an abstract `PluginSubscriber` implementation (see [src/plu
 **Example:**
 
 ```typescript
+import { nextTick } from 'vue'
 import PluginSubscriber from 'pinia-plugin-subscription'
 import StoreExtension from './src/extending-pinia-store/core/StoreExtension'
 import { addStore } from './src/extending-pinia-store/plugins/stores'
@@ -145,13 +197,41 @@ 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
   }
+
+  override hydrate() {
+    if (typeof window === 'undefined') {
+      return
+    }
+
+    // Safe browser-only initialization. This is only called when the policy allows it.
+    return this.storeInstance?.hydrate?.()
+  }
 }
 
 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()`
+- `hydrate()` / `afterHydration()` are optional lifecycle hooks for browser-only initialization and post-hydration work; they help keep SSR-sensitive logic out of constructors
+
 ## The `Store` Class — Summary
 
 The `Store` class (see [src/core/Store.ts](src/core/Store.ts)) is a wrapper around a `PiniaStore` providing: