pinia-plugin-subscription 0.0.0-beta.19 → 0.0.0-beta.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +71 -90
  2. package/dist/types/index.d.ts +4 -4
  3. package/dist/types/plugin.d.ts +1 -1
  4. package/dist/types/store.d.ts +1 -2
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -10,122 +10,109 @@
10
10
 
11
11
  The main goal is to offer a clear API for writing reusable Pinia plugins and to make it easy to extend stores from plugin code.
12
12
 
13
- ### Basic usage
13
+ ## Installation
14
14
 
15
- 1. Import the plugin factory and register your subscribers with Pinia:
15
+ Ensure Pinia is installed, then register the plugin in your `main.ts`:
16
16
 
17
17
  ```typescript
18
- // main.ts
19
18
  import { createApp } from 'vue'
20
19
  import { createPinia } from 'pinia'
21
20
  import { createPlugin } from 'pinia-plugin-subscription'
22
- import myStoreSubscriber from './src/core/my-store'
21
+ import { myStoreSubscriber } from './src/core/my-store'
23
22
  import App from './App.vue'
24
23
 
25
24
  const app = createApp(App)
26
25
  const pinia = createPinia()
27
26
 
28
- // Register plugin (subscribers array, debug = list of target plugins)
29
- pinia.use(createPlugin([myStoreSubscriber], ['my-plugin']))
27
+ // Register plugin (subscribers array, debug mode)
28
+ pinia.use(createPlugin([myStoreSubscriber], true))
30
29
 
31
30
  app.use(pinia)
32
31
  app.mount('#app')
33
32
  ```
34
33
 
35
- 2. A subscriber example using a `Store` subclass:
34
+ ## Usage — Examples
35
+
36
+ **1) Subscriber using a `Store` subclass:**
36
37
 
37
38
  ```typescript
38
- import { PluginSubscriber, Store } from 'pinia-plugin-subscription';
39
- import { PluginConsole } from "../../system/log";
39
+ import PluginSubscriber from 'pinia-plugin-subscription'
40
+ import { Store } from 'pinia-plugin-subscription'
40
41
 
41
42
  class MyPlugin extends Store {
42
43
  constructor(store, options, debug = false) {
43
44
  super(store, options, debug)
44
45
  this.doSomething()
45
46
  }
46
- // ...
47
47
  }
48
48
 
49
49
  class MyPluginSubscriber extends PluginSubscriber<MyPlugin> {
50
- constructor() {
51
- super(
52
- "my-plugin",
53
- MyPlugin.customizeStore.bind(MyPlugin),
54
- PluginConsole
55
- )
56
- }
50
+ constructor() {
51
+ super('my-plugin', MyPlugin.customizeStore.bind(MyPlugin))
52
+ }
57
53
  }
54
+
55
+ export const myStoreSubscriber = new MyPluginSubscriber()
58
56
  ```
59
57
 
60
- 3. A subscriber example implement PluginSubscriberInterface:
58
+ **2) Simple subscriber implementing `PluginSubscriberInterface`:**
61
59
 
62
60
  ```typescript
63
61
  import type { PluginSubscriberInterface } from 'pinia-plugin-subscription'
64
62
 
65
- export const myStoreSubscriber = {
66
- name: 'my-plugin'
63
+ export const myStoreSubscriber: PluginSubscriberInterface = {
64
+ name: 'my-plugin',
65
+
67
66
  invoke: (context, debug) => {
68
- doAnotherthing(context)
67
+ // context contains `store`, `options`, `pinia`
68
+ console.log('store registered', context.store.$id)
69
+
70
+ return true
71
+ },
72
+
73
+ resetStoreCallback: (store) => {
74
+ console.log('store reset:', store.$id)
69
75
  }
70
76
  }
71
77
  ```
72
78
 
73
- ### Advanced usage
74
-
75
- #### Debug mode
79
+ ## Advanced Features
76
80
 
77
- Enable debug mode to log store changes and target plugins internal actions :
81
+ - **Debug mode:** Pass `true` as the second argument to `createPlugin` to enable detailed logging and plugin filtering.
82
+ - **Reset callbacks:** Define `resetStoreCallback` to run custom logic when a store is reset.
78
83
 
79
- ```typescript
80
- pinia.use(createPlugin([subscriber], ['my-plugin', 'external-plugin']))
81
- ```
84
+ ## API Reference
82
85
 
83
- #### Reset store callbacks
86
+ ### `createPlugin(subscribers: PluginSubscriber[], debug?: boolean): PiniaPlugin`
84
87
 
85
- Subscribers may define `resetStoreCallback` to run custom logic when a store reset is handled by the plugin.
88
+ Creates and returns a Pinia plugin from the provided `subscribers`. Each subscriber is invoked when a store is registered.
86
89
 
87
- ```typescript
88
- const subscriber = {
89
- invoke: (context, debug) => {
90
- console.log('Store changed:', context.store.$state)
91
- },
92
- resetStoreCallback: (store) => {
93
- console.log('Store reset:', store.$id)
94
- }
95
- }
96
- ```
90
+ ### `PluginSubscriberInterface`
97
91
 
98
- ## API
92
+ An object with at least an `invoke(context: PiniaPluginContext, debug?: boolean)` method, plus optional properties:
99
93
 
100
- ### `createPlugin(subscribers: PluginSubscriber[], debug?: boolean): PiniaPlugin`
94
+ - `resetStoreCallback?: (store?: any) => void`
95
+ - `storeOnActionSubscription?: { store, callback }` (getter)
96
+ - `storeMutationSubscription?: { store, callback }` (getter)
97
+ - `subscriptions?: Record<string, Function>` (plugin-specific subscription functions)
101
98
 
102
- Creates a Pinia plugin from the provided `subscribers` and optional `debug` flag. Each subscriber will be invoked with the Pinia plugin context when a store is registered.
99
+ ## The `PluginSubscriber` Abstract Class
103
100
 
104
- ### `PluginSubscriberInterface`
101
+ The project provides an abstract `PluginSubscriber` implementation (see [src/plugins/pluginSubscriber.ts](src/plugins/pluginSubscriber.ts)) to simplify creating reusable subscribers.
105
102
 
106
- The `PluginSubscriberInterface` 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:
103
+ **Typical usage:**
107
104
 
108
- - **`resetStoreCallback?: (store?: Store) => void`**: callback invoked when the store is reset.
109
- - **`storeOnActionSubscription?: StoreOnActionSubscription`**: provides a native Pinia `onAction` subscription via a getter returning `{ store, callback }`.
110
- - **`storeMutationSubscription?: StoreMutationSubscription`**: provides a native mutation subscription (`store.$subscribe`) via a getter returning `{ store, callback }`.
111
- - **`subscriptions: PluginSubscriptions | undefined`**: an object listing plugin-specific subscription functions (see `Store.addSubscription`).
112
-
113
- These additions make it easier for subscribers to integrate with Pinia's native event cycle and to expose reusable extension points.
114
-
115
- ## The `PluginSubscriber` class (abstract)
116
-
117
- The project provides an abstract `PluginSubscriber` implementation ([src/plugins/pluginSubscriber.ts](src/plugins/pluginSubscriber.ts)) that makes it easy to create reusable subscribers:
118
-
119
- - Constructor: `new PluginSubscriber(pluginName: string, createInstanceFunction: CreateInstance)`
120
- - 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:
121
- - `subscriptions` (from `store.getSubscriptions()`)
122
- - `storeMutationSubscription` (from `store.storeSubscribe`)
123
- - `storeOnActionSubscription` (from `store.onAction`)
124
- - optionally a `pluginCreated(store)` hook called after initialization
105
+ - The subscriber instantiates a `Store` (or subclass) via a factory (`MyStore.customizeStore`).
106
+ - The instance exposes:
107
+ - `subscriptions` (from `getSubscriptions()`)
108
+ - `storeMutationSubscription` (from `storeSubscribe`)
109
+ - `storeOnActionSubscription` (from `onAction`)
110
+ - optional `pluginCreated(store)` hook called after initialization
125
111
 
112
+ **Example:**
126
113
 
127
114
  ```typescript
128
- import PluginSubscriber from './src/plugins/pluginSubscriber'
115
+ import PluginSubscriber from 'pinia-plugin-subscription'
129
116
  import StoreExtension from './src/extending-pinia-store/core/StoreExtension'
130
117
  import { addStore } from './src/extending-pinia-store/plugins/stores'
131
118
 
@@ -139,40 +126,34 @@ class ExtendingStoreSubscriber extends PluginSubscriber<StoreExtension> {
139
126
  export const extendingStoreSubscriber = new ExtendingStoreSubscriber()
140
127
  ```
141
128
 
142
- 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.
129
+ ## The `Store` Class — Summary
143
130
 
144
- ## The `Store` class (summary)
131
+ The `Store` class (see [src/core/Store.ts](src/core/Store.ts)) is a wrapper around a `PiniaStore` providing:
145
132
 
146
- The `Store` class (in [src/core/Store.ts](src/core/Store.ts)) is a base wrapper around a `PiniaStore` exposing helpers:
133
+ - **Properties:** `debug`, `options`, `state`, `store`.
134
+ - **Useful methods:**
135
+ - `addToState(name, value?)` — adds a property to store state and exposes it as a `Ref` when appropriate.
136
+ - `addSubscription(pluginName, subscription)` — registers a plugin-specific subscription function.
137
+ - `getSubscriptions()` — returns registered subscriptions.
138
+ - `storeSubscribe` (getter/setter) — factory for `store.$subscribe` ({ store, callback }).
139
+ - `onAction` (getter/setter) — factory for `onAction` ({ store, callback }).
140
+ - `static customizeStore(store, options, debug?)` — recommended factory for class instantiation.
141
+ - `debugLog(message, args)` — conditional logging.
142
+ - Helpers: `stateHas()`, `storeHas()`, `getValue()`.
147
143
 
148
- - Properties: `debug`, `options`, `state`, `store`.
149
- - Useful methods:
150
- - `addToState(name, value?)`: adds a property to the store state and exposes it as a `Ref` on the store when appropriate.
151
- - `addSubscription(pluginName, subscription)`: registers a plugin-specific subscription function (accessible via `getSubscriptions`).
152
- - `getSubscriptions()`: returns subscriptions registered with `addSubscription` (or `undefined`).
153
- - `storeSubscribe` (getter/setter): exposes a mutation subscription callback (`store.$subscribe`) as a factory returning `{ store, callback }`.
154
- - `onAction` (getter/setter): exposes a Pinia `onAction` callback in the same form.
155
- - `static customizeStore(store, options, debug?)`: instantiate the class (or subclass) when `options.storeOptions` is present.
156
- - `debugLog(message, args)`: conditional logging when `debug` is true.
157
- - `hasDeniedFirstChar(property)`, `getOption(...)`, `getValue(value)`, `getStatePropertyValue(...)`.
158
- - `isOptionApi()`: true when the store uses Pinia Options API.
144
+ ## Testing
159
145
 
160
- Other small helpers exposed: `stateHas(property)`, `storeHas(property)` and `getValue` to retrieve the real value of a `Ref` or a raw value.
161
-
162
- `Store.customizeStore(...)` is the recommended entry point used by subscribers to create store helper instances.
163
-
164
-
165
- ## Testing
146
+ This plugin is tested with Vitest. Coverage reports are available in the `coverage/` directory:
166
147
 
167
- This plugin is tested with Vitest. Coverage (from the included coverage report at [coverage/index.html](coverage/index.html)):
148
+ - Statements: **97.64%** (83/85)
149
+ - Branches: **86.53%** (45/52)
150
+ - Functions: **100%** (38/38)
151
+ - Lines: **97.59%** (81/83)
168
152
 
169
- - Statements: **97.64%** (83/85)
170
- - Branches: **86.53%** (45/52)
171
- - Functions: **100%** (38/38)
172
- - Lines: **97.59%** (81/83)
153
+ ## Contributing
173
154
 
174
- ---
155
+ Pull requests are welcome. Please respect the project's coding style and add tests for new features.
175
156
 
176
157
  ## License
177
158
 
178
- MIT
159
+ MIT
package/dist/types/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { PiniaPlugin, PiniaPluginContext, Store as PiniaStore, StateTree } from "pinia"
1
+ import type { PiniaPlugin, PiniaPluginContext, Store as PiniaStore, StateTree, StoreDefinition } from "pinia"
2
2
  import type { Console } from "./log"
3
3
  import type {
4
4
  PluginSubscriber as PluginSubscriberInterface,
@@ -8,7 +8,7 @@ import type {
8
8
  StoreMutationSubscription,
9
9
  StoreMutationSubscriptionCallback
10
10
  } from "./plugin"
11
- import type { DefineAugmentedStore, StatePropertyValue, StoreOptions, StoreOptionsPropertyValue } from "./store"
11
+ import type { StatePropertyValue, StoreOptions, StoreOptionsPropertyValue } from "./store"
12
12
 
13
13
 
14
14
  declare module 'pinia-plugin-subscription' {
@@ -16,7 +16,7 @@ declare module 'pinia-plugin-subscription' {
16
16
 
17
17
  export function createPlugin(subscribers: PluginSubscriberInterface[], debug?: string[]): PiniaPlugin;
18
18
 
19
- export function defineAStore<TStore, TState>(id: string, storeDefinition: () => AnyObject, storeOptions?: StoreOptions): DefineAugmentedStore<TStore, TState>
19
+ export function defineAStore<TStore, TState>(id: string, storeDefinition: () => AnyObject, storeOptions?: StoreOptions): StoreDefinition & TState & TStore
20
20
 
21
21
  export function isEmpty(value: any): boolean
22
22
 
@@ -131,5 +131,5 @@ export interface SearchCollectionCriteria {
131
131
  [key: number | string | symbol]: boolean | number | string;
132
132
  }
133
133
  export { Console, LogType, StyleDefinition as ConsoleStyleDefinition, StyleDefinitionKeys as ConsoleStyleDefinitionKeys, StyleDefinitions as ConsoleStyleDefinitions } from './log';
134
- export type { CustomStore, DefineAugmentedStore, PluginStoreOptions, StatePropertyValue, StoreOptions, StoreOptionsPropertyValue } from "./store";
134
+ export type { CustomStore, PluginStoreOptions, StatePropertyValue, StoreOptions, StoreOptionsPropertyValue } from "./store";
135
135
  export type { PluginSubscriber as PluginSubscriberInterface, StoreMutationSubscriptionCallback, StoreOnActionCallbackParameters } from "./plugin";
package/dist/types/plugin.d.ts CHANGED
@@ -8,7 +8,7 @@ export interface PluginSubscriber {
8
8
  resetStoreCallback?: (store?: Store) => void;
9
9
  storeOnActionSubscription?: StoreOnActionSubscription;
10
10
  storeMutationSubscription?: StoreMutationSubscription;
11
- subscriptions: PluginSubscriptions | undefined;
11
+ subscriptions?: PluginSubscriptions;
12
12
  }
13
13
  export interface NativePiniaSubscriptionReturn<Callback> {
14
14
  store: Store;
package/dist/types/store.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import type { AnyObject } from ".";
2
2
  import type { PiniaCustomProperties, Store, StoreDefinition } from "pinia";
3
3
  import type { Ref } from "vue";
4
- export type CustomStore<TStore, TState> = Store & PiniaCustomProperties & StoreDefinition & TStore & TState;
4
+ export type CustomStore<TStore, TState> = Store & TStore & TState & PiniaCustomProperties & StoreDefinition;
5
5
  export type DefineAugmentedStore<TStore, TState> = (args?: any) => CustomStore<TStore, TState>;
6
6
  export type ObjectBaseProperty = Record<string, OptionBaseProperty | OptionBaseProperty[]>;
7
7
  export type OptionBaseProperty = string | number | boolean | null | undefined | object | Function;
@@ -12,4 +12,3 @@ export type StatePropertyValue = StdStatePropertyValue | Ref<StdStatePropertyVal
12
12
  type StdStatePropertyValue = AnyObject | boolean | null | number | string | undefined;
13
13
  export type StoreOptions = Record<string, StoreOptionsPropertyValue>;
14
14
  export type StoreOptionsPropertyValue = OptionBaseProperty | OptionBaseProperty[] | ObjectBaseProperty | ObjectBaseProperty[];
15
- export {};
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "author": "Alexandre Bidaud <alexbidaud85@gmail.com> (https://github.com/AlxBDo)",
3
3
  "name": "pinia-plugin-subscription",
4
- "version": "0.0.0-beta.19",
4
+ "version": "0.0.0-beta.20",
5
5
  "type": "module",
6
6
  "exports": {
7
7
  ".": {