pinia-plugin-subscription 0.0.0-beta.1 → 0.0.0-beta.3

package/README.md

@@ -37,7 +37,7 @@ app.mount('#app')
 
 ```typescript
 // src/core/my-store.ts
-import Store from './src/core/Store'
+import { Store } from 'pinia-plugin-subscription'
 
 class MyStore extends Store {
   constructor(store, options, debug = false) {
@@ -112,7 +112,43 @@ export const myStoreSubscriber = {
 
  ### `PluginSubscriber`
 
- An object with at least an `invoke(context: PiniaPluginContext, debug?: boolean)` method. Optionally a `resetStoreCallback(store)` method can be provided.
+The `PluginSubscriber` interface has been extended: it's still an object with at least an `invoke(context: PiniaPluginContext, debug?: boolean)` method, but it can now expose several useful properties for plugins:
+
+- **`resetStoreCallback?: (store?: Store) => void`**: callback invoked when the store is reset.
+- **`storeOnActionSubscription?: StoreOnActionSubscription`**: provides a native Pinia `onAction` subscription via a getter returning `{ store, callback }`.
+- **`storeMutationSubscription?: StoreMutationSubscription`**: provides a native mutation subscription (`store.$subscribe`) via a getter returning `{ store, callback }`.
+- **`subscriptions: PluginSubscriptions | undefined`**: an object listing plugin-specific subscription functions (see `Store.addSubscription`).
+
+These additions make it easier for subscribers to integrate with Pinia's native event cycle and to expose reusable extension points.
+
+## The `PluginSubscriber` class (abstract)
+
+The project provides an abstract `PluginSubscriber` implementation ([src/plugins/pluginSubscriber.ts](src/plugins/pluginSubscriber.ts)) that makes it easy to create reusable subscribers:
+
+- Constructor: `new PluginSubscriber(pluginName: string, createInstanceFunction: CreateInstance)`
+- Main behavior: in `invoke(context, debug)` the class creates a helper instance (`Store` or subclass) via the `createInstanceFunction` (typically `MyStore.customizeStore`) and exposes on the instance:
+  - `subscriptions` (from `store.getSubscriptions()`)
+  - `storeMutationSubscription` (from `store.storeSubscribe`)
+  - `storeOnActionSubscription` (from `store.onAction`)
+  - optionally a `pluginCreated(store)` hook called after initialization
+
+
+```typescript
+import PluginSubscriber from './src/plugins/pluginSubscriber'
+import StoreExtension from './src/extending-pinia-store/core/StoreExtension'
+import { addStore } from './src/extending-pinia-store/plugins/stores'
+
+class ExtendingStoreSubscriber extends PluginSubscriber<StoreExtension> {
+  constructor() {
+    super('extendsPiniaStore', StoreExtension.customizeStore.bind(StoreExtension))
+    this.pluginCreated = addStore
+  }
+}
+
+export const extendingStoreSubscriber = new ExtendingStoreSubscriber()
+```
+
+Here `ExtendingStoreSubscriber` provides a `createInstanceFunction` that returns a `StoreExtension` instance if `options.storeOptions` is present, and sets a `pluginCreated` hook (here `addStore`) to run plugin-specific logic once the instance is ready.
 
  ## The `Store` class (summary)
 
@@ -121,11 +157,17 @@ export const myStoreSubscriber = {
  - Properties: `debug`, `options`, `state`, `store`.
  - Useful methods:
    - `addToState(name, value?)`: adds a property to the store state and exposes it as a `Ref` on the store when appropriate.
+   - `addSubscription(pluginName, subscription)`: registers a plugin-specific subscription function (accessible via `getSubscriptions`).
+   - `getSubscriptions()`: returns subscriptions registered with `addSubscription` (or `undefined`).
+   - `storeSubscribe` (getter/setter): exposes a mutation subscription callback (`store.$subscribe`) as a factory returning `{ store, callback }`.
+   - `onAction` (getter/setter): exposes a Pinia `onAction` callback in the same form.
    - `static customizeStore(store, options, debug?)`: instantiate the class (or subclass) when `options.storeOptions` is present.
    - `debugLog(message, args)`: conditional logging when `debug` is true.
    - `hasDeniedFirstChar(property)`, `getOption(...)`, `getValue(value)`, `getStatePropertyValue(...)`.
    - `isOptionApi()`: true when the store uses Pinia Options API.
 
+Other small helpers exposed: `stateHas(property)`, `storeHas(property)` and `getValue` to retrieve the real value of a `Ref` or a raw value.
+
  `Store.customizeStore(...)` is the recommended entry point used by subscribers to create store helper instances.