pinia-plugin-subscription 0.2.1 → 1.0.0-beta.0

package/docs/authoring-plugins.md

@@ -27,7 +27,7 @@ Two authoring styles are available:
    no classes.
 2. **`PluginSubscriber` abstract class + `Store` subclass** — recommended
    for richer plugins: the `Store` subclass wraps the pinia store with
-   helpers (state extension, subscriptions, debug logging).
+   helpers (state extension, subscriptions, structured tracing).
 
 ## Your first subscriber: a plain object
 
@@ -37,7 +37,7 @@ Two authoring styles are available:
 export const myStoreSubscriber = {
   name: 'my-plugin',
 
-  invoke: (context, debug) => {
+  invoke: (context) => {
     // context contains `store`, `options`, `pinia`
     console.log('store registered', context.store.$id)
 
@@ -58,7 +58,7 @@ import type { PluginSubscriberInterface } from 'pinia-plugin-subscription'
 export const myStoreSubscriber: PluginSubscriberInterface = {
   name: 'my-plugin',
 
-  invoke: (context, debug) => {
+  invoke: (context) => {
     console.log('store registered', context.store.$id)
 
     return true
@@ -82,17 +82,16 @@ pinia.use(createPlugin([myStoreSubscriber]))
 
 | Member | Type | Description |
 | --- | --- | --- |
-| `name` (required) | `string` | Unique plugin name; also used by the debug filter. |
-| `invoke` (required) | `(context: PiniaPluginContext, debug: boolean) => boolean` | Called when a store is registered. Return `false` to skip the store. |
+| `name` (required) | `string` | Unique plugin name. |
+| `invoke` (required) | `(context: PiniaPluginContext) => boolean` | Called when a store is registered. Return `false` to skip the store. |
 | `execution` | `PluginExecutionOptions` | Where/when the subscriber runs — see [Execution policy & SSR](#execution-policy--ssr). |
 | `hydrationScheduler` | `(run: () => void) => void` | Custom scheduler used when hydration is deferred. |
-| `hydrate` | `(context, debug) => void \| Promise<void>` | SSR-safe initialization hook; guaranteed to run before `afterHydration`. |
-| `afterHydration` | `(context, debug) => void \| Promise<void>` | Post-hydration lifecycle hook. |
+| `hydrate` | `(context) => void \| Promise<void>` | SSR-safe initialization hook; guaranteed to run before `afterHydration`. |
+| `afterHydration` | `(context) => void \| Promise<void>` | Post-hydration lifecycle hook. |
 | `resetStoreCallback` | `(store?: Store) => void` | Custom logic executed when a registered store is reset. |
 | `storeOnActionSubscription` | `{ store, callback }` (getter) | Action subscription forwarded to the returned store's `$onAction`, including after deferred hydration; removed on store disposal. |
 | `storeMutationSubscription` | `{ store, callback }` (getter) | Mutation subscription forwarded to pinia's `$subscribe`. |
 | `subscriptions` | `Record<string, PluginSubscription>` | Plugin-specific subscription functions exposed to other plugins. |
-| `console` | `Console` | Custom console used for debug logging. |
 
 All members except `name` and `invoke` are optional.
 
@@ -117,7 +116,7 @@ checks when they call your plugin's custom methods.
 Constructor:
 
 ```ts
-constructor(pluginName: string, createInstance: CreateInstance, pluginConsole?: Console)
+constructor(pluginName: string, createInstance: CreateInstance)
 ```
 
 | Member | Kind | Description |
@@ -136,20 +135,19 @@ constructor(pluginName: string, createInstance: CreateInstance, pluginConsole?:
 import { PluginSubscriber, Store } from 'pinia-plugin-subscription'
 
 class MyPlugin extends Store {
-  constructor(store, options, debug = false) {
-    super(store, options, debug)
+  constructor(store, options) {
+    super(store, options)
     this.doSomething()
   }
 
   doSomething() {
-    this.debugLog('doSomething', this.store.$id)
+    this.trace('my-plugin:doSomething', () => ({ storeId: this.store.$id }))
   }
 }
 
 class MyPluginSubscriber extends PluginSubscriber {
   constructor() {
-    super('my-plugin', (store, options, debug, customConsole) =>
-      new MyPlugin(store, options, debug, customConsole))
+    super('my-plugin', (store, options) => new MyPlugin(store, options))
   }
 }
 
@@ -165,13 +163,13 @@ class MyPlugin extends Store {
   protected override _className: string = 'MyPlugin'
   protected static override _requiredKeys?: string[] = ['my-plugin-option']
 
-  constructor(store, options, debug = false) {
-    super(store, options, debug)
+  constructor(store, options) {
+    super(store, options)
     this.doSomething()
   }
 
   doSomething(): void {
-    this.debugLog('doSomething', this.store.$id)
+    this.trace('my-plugin:doSomething', () => ({ storeId: this.store.$id }))
   }
 }
 
@@ -195,7 +193,7 @@ export const myStoreSubscriber = new MyPluginSubscriber()
 
 `Store` wraps a pinia store (`PiniaStore`) and exposes:
 
-**Properties:** `debug`, `options`, `state`, `store`.
+**Properties:** `options`, `state`, `store`.
 
 **Methods:**
 
@@ -208,8 +206,9 @@ export const myStoreSubscriber = new MyPluginSubscriber()
 | `getStatePropertyValue(propertyName)` | Reads a state property, unwrapping refs. |
 | `storeSubscribe` (getter/setter) | Factory for pinia's `$subscribe` (`{ store, callback }`). |
 | `onAction` (getter/setter) | Factory for pinia's `$onAction` (`{ store, callback }`). |
-| `static customizeStore(store, options, debug?)` | Recommended factory; guarded by `_requiredKeys` (see above). |
-| `debugLog(message, args)` | Conditional logging, active in debug mode. |
+| `static customizeStore(store, options)` | Recommended factory; guarded by `_requiredKeys` (see above). |
+| `trace(namespace, payload?)` | Emits a structured trace event scoped to the store. |
+| `traceError(namespace, error, payload?)` | Emits an error event, or rethrows it when no listener matches. |
 | `stateHas(property)` / `storeHas(property)` | Safe `hasOwnProperty` checks on state / store. |
 | `getValue(value)` | Unwraps a ref or returns the value as-is. |
 | `isOptionApi()` | Whether the store uses the options API. |
@@ -234,7 +233,7 @@ export const persistedStateSubscriber = {
   hydrationScheduler: (run) => {
     nextTick(() => run())
   },
-  invoke: (context, debug) => {
+  invoke: (context) => {
     // ...
     return true
   }
@@ -256,7 +255,7 @@ export const persistedStateSubscriber: PluginSubscriberInterface = {
   hydrationScheduler: (run) => {
     nextTick(() => run())
   },
-  invoke: (context, debug) => {
+  invoke: (context) => {
     // ...
     return true
   }
@@ -395,7 +394,7 @@ Guidelines:
 - Always declare **optional** keys with names specific enough to avoid
   collisions (prefer `myPluginOption` over `options`).
 - At runtime, merged options are delivered to your subscriber's
-  `invoke(context, debug)` through `context.options.storeOptions` — no
+  `invoke(context)` through `context.options.storeOptions` — no
   extra wiring needed.
 - Never redeclare `DefineStoreOptionsBase` or `PiniaCustomProperties`; only
   this package owns those augmentations.

package/docs/using-plugins.md

@@ -22,8 +22,8 @@ Plugins built on `pinia-plugin-subscription` share a common contract:
 - **`$reset` on registered stores** — every store registered by the plugin
   gains a `$reset()` method that restores its initial state, including
   setup-style stores where pinia does not provide one natively.
-- **Per-plugin debug mode** — pass plugin names to `createPlugin()` to
-  enable detailed logging for those plugins only.
+- **Runtime-filtered tracing** — register trace listeners and filter events by
+  source, namespace, scope, or level.
 - **SSR-safe execution** — each plugin declares where (`client`, `server`
   or `both`) and when (`immediate` or deferred after hydration) it runs.
 - **State rollback on action failure** — actions listed in the
@@ -46,15 +46,14 @@ Compatible plugins expose **subscribers** that are passed to
 ```js
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'
-import { createPlugin, PLUGIN_NAME } from 'pinia-plugin-subscription'
+import { createPlugin } from 'pinia-plugin-subscription'
 import { myStoreSubscriber } from './plugins/my-store'
 import App from './App.vue'
 
 const app = createApp(App)
 const pinia = createPinia()
 
-// Second argument (optional): names of the plugins to debug.
-pinia.use(createPlugin([myStoreSubscriber], [PLUGIN_NAME]))
+pinia.use(createPlugin([myStoreSubscriber]))
 
 app.use(pinia)
 app.mount('#app')
@@ -66,12 +65,12 @@ The TypeScript version is identical — `createPlugin()` is fully typed and
 requires no generics:
 
 ```ts
-import { createPlugin, PLUGIN_NAME } from 'pinia-plugin-subscription'
+import { createPlugin } from 'pinia-plugin-subscription'
 import type { PluginSubscriberInterface } from 'pinia-plugin-subscription'
 
 const subscribers: PluginSubscriberInterface[] = [myStoreSubscriber]
 
-pinia.use(createPlugin(subscribers, [PLUGIN_NAME]))
+pinia.use(createPlugin(subscribers))
 ```
 
 ## Defining stores: `defineAStore`
@@ -232,9 +231,7 @@ export const useMyStore = defineAStoreCtx('myStore', (ctx) => {
 
 `defineAStoreCtx()` enables the `enhancedStore` store option automatically.
 The internal setup-context lookup is cleaned up as soon as the store is
-associated (and on store dispose), which limits map growth over time. When
-`storeOptions.debug` is `true`, setup-context map size transitions are
-logged for observability.
+associated (and on store dispose), which limits map growth over time.
 
 ## `$reset` on registered stores
 
@@ -316,17 +313,27 @@ try {
   (forwarded to the action via `apply()`).
 - The original error is rethrown after the state is restored.
 
-## Debug mode
+## Tracing
 
-Pass the names of the plugins you want to inspect as the second argument of
-`createPlugin()`:
+Register listeners independently from plugin construction:
 
 ```js
-pinia.use(createPlugin([myStoreSubscriber], [PLUGIN_NAME, 'my-plugin']))
+import {
+  addTraceListener,
+  createConsoleTraceListener,
+  createPlugin
+} from 'pinia-plugin-subscription'
+
+addTraceListener({
+  ...createConsoleTraceListener(),
+  filter: event => event.scope === 'cart'
+})
+
+pinia.use(createPlugin([myStoreSubscriber]))
 ```
 
-Matching plugins then emit detailed logs (registration, execution policy,
-hydration lifecycle).
+Filters run in real time and can target a source, namespace, store scope, or
+trace level without passing diagnostic options through subscribers.
 
 ## SSR / Nuxt
 
@@ -334,16 +341,47 @@ The package is SSR-safe by design. Each compatible plugin declares its own
 execution policy, so nothing browser-only runs on the server unless the
 plugin explicitly allows it.
 
+For request isolation, create the app, Pinia instance, trace registry, and
+plugin inside the per-request app factory. Do not store the registry or the
+`createPlugin()` result at module scope: both retain request-associated
+listeners or plugin state. A new registry per request also avoids races
+between concurrent requests; do not clear a shared registry when one request
+finishes.
+
+```js
+import { createSSRApp } from 'vue'
+import { createPinia } from 'pinia'
+import { createPlugin, createTracerRegistry } from 'pinia-plugin-subscription'
+import App from './App.vue'
+import { subscribers } from './subscribers'
+
+export function createRequestApp(traceListener) {
+  const app = createSSRApp(App)
+  const pinia = createPinia()
+  const traceRegistry = createTracerRegistry()
+
+  traceRegistry.addTraceListener(traceListener)
+  pinia.use(createPlugin(subscribers, {
+    createTracer: traceRegistry.createTracer
+  }))
+  app.use(pinia)
+
+  return { app, pinia }
+}
+```
+
+Call `createRequestApp()` once for each incoming SSR request. The request's
+listener is then reachable only through that request's registry and plugin.
+
 When a plugin needs a runtime-specific scheduler or environment override —
 without forcing every app to re-declare the plugin's execution policy —
 register it through the dedicated hydration helper:
 
 ```js
 import { nextTick } from 'vue'
-import { createHydrationPlugin, PLUGIN_NAME } from 'pinia-plugin-subscription'
+import { createHydrationPlugin } from 'pinia-plugin-subscription'
 
 pinia.use(createHydrationPlugin([persistedStateSubscriber], {
-  debug: [PLUGIN_NAME],
   hydrationScheduler: (run) => {
     nextTick(() => run())
   }
@@ -355,7 +393,6 @@ pinia.use(createHydrationPlugin([persistedStateSubscriber], {
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `debug` | `string[]` | Plugin names to debug. |
 | `execution` | `PluginExecutionOptions` | Global execution policy override. |
 | `hydrationScheduler` | `(run: () => void) => void` | Scheduler used for deferred hydration. |
 | `runtimeEnvironment` | `'client' \| 'server'` | Forces the runtime environment. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pinia-plugin-subscription",
-  "version": "0.2.1",
+  "version": "1.0.0-beta.0",
   "description": "Pinia plugin for Vue.js that helps building Pinia plugins by centralizing subscriber registration and providing a Store base class for store helpers.",
   "type": "module",
   "sideEffects": false,
@@ -69,7 +69,8 @@
     "dev:library": "vite",
     "test": "vitest",
     "coverage": "vitest run --coverage",
-    "build": "vitest && vite build && tsc --emitDeclarationOnly --outDir dist && node scripts/measure-bundle.mjs",
+    "build": "vitest && vite build && tsc --emitDeclarationOnly --outDir dist && npm run check:leaks && node scripts/measure-bundle.mjs",
+    "check:leaks": "node scripts/check-dist-leaks.mjs",
     "bundle:check": "vite build --config vite.config.ts && node scripts/measure-bundle.mjs",
     "build:demo": "vite --config vite.demo.config.ts build",
     "preview": "vite preview --config vite.demo.config.ts"

package/dist/chunks/index-DKdl-fiq.js

@@ -1,337 +0,0 @@
-var f = Object.defineProperty;
-var S = (s, t, e) => t in s ? f(s, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : s[t] = e;
-var n = (s, t, e) => S(s, typeof t != "symbol" ? t + "" : t, e);
-import { isRef as b, ref as y, toRef as C } from "vue";
-import { defineStore as g } from "pinia";
-class L {
-  constructor(t, e, r) {
-    n(this, "_console");
-    n(this, "_createInstance");
-    n(this, "_name");
-    n(this, "_pluginOptions");
-    n(this, "_storeInstance");
-    n(this, "_resetStoreCallback");
-    n(this, "_storeOnActionSubscription");
-    n(this, "_storeMutationSubscription");
-    n(this, "_subscriptions");
-    n(this, "pluginCreated");
-    n(this, "execution");
-    n(this, "hydrationScheduler");
-    this._name = t, this._createInstance = e, r && (this._console = r);
-  }
-  get console() {
-    return this._console ?? console;
-  }
-  get name() {
-    return this._name;
-  }
-  get storeInstance() {
-    return this._storeInstance;
-  }
-  get pluginOptions() {
-    return this._pluginOptions ?? {};
-  }
-  set pluginOptions(t) {
-    this._pluginOptions = t;
-  }
-  get resetStoreCallback() {
-    return this._resetStoreCallback;
-  }
-  get storeOnActionSubscription() {
-    return this._storeOnActionSubscription;
-  }
-  get storeMutationSubscription() {
-    return this._storeMutationSubscription;
-  }
-  get subscriptions() {
-    return this._subscriptions;
-  }
-  set subscriptions(t) {
-    this._subscriptions = t;
-  }
-  afterHydration(t, e) {
-  }
-  hydrate(t, e) {
-  }
-  invoke({ store: t, options: e }, r) {
-    return this._storeInstance = this._createInstance(t, { ...e, ...this.pluginOptions }, r, this.console), this._storeInstance ? (this._subscriptions = this._storeInstance.getSubscriptions(), this._storeMutationSubscription = this._storeInstance.storeSubscribe, this._storeOnActionSubscription = this._storeInstance.onAction, this.pluginCreated && this.pluginCreated(t), !0) : !1;
-  }
-}
-class A {
-  constructor(t, e) {
-    n(this, "_console");
-    n(this, "_debug", !1);
-    this._debug = t, e && (this._console = e);
-  }
-  get console() {
-    return this._console ?? console;
-  }
-  set console(t) {
-    this._console = t;
-  }
-  get debug() {
-    return this._debug;
-  }
-  set debug(t) {
-    this._debug = t;
-  }
-  debugLog(...t) {
-    this._debug && (Array.isArray(t) && (t[0] = `${this._className} - ${t[0]}`), this.console.log(...t));
-  }
-  logError(...t) {
-    this.console.error(...t);
-  }
-}
-const p = /* @__PURE__ */ new WeakMap(), c = /* @__PURE__ */ new Map(), l = /* @__PURE__ */ new WeakSet(), O = 50;
-function x(s) {
-  return s?.storeOptions?.debug === !0;
-}
-function h(s, t, e) {
-  if (!x(t))
-    return;
-  const r = c.size;
-  console.debug(`[defineAStoreSetup] ${s} - ${e} (contextsById=${r})`), r >= O && console.warn(`[defineAStoreSetup] contextsById reached ${r} entries`);
-}
-function $(s, t, e) {
-  if (l.has(s) || typeof s.$dispose != "function")
-    return;
-  const r = s.$dispose;
-  s.$dispose = (...o) => (p.delete(s), c.delete(t), h(t, e, "dispose cleanup"), r.apply(s, o)), l.add(s);
-}
-function N(s, t, e) {
-  const r = e ? { storeOptions: e } : {};
-  return typeof t == "function" ? d(
-    s,
-    t,
-    r
-  ) : m(
-    s,
-    t,
-    r
-  );
-}
-function T(s, t, e) {
-  const r = e ? { storeOptions: { ...e, enhancedStore: !0 } } : { storeOptions: { enhancedStore: !0 } };
-  return d(
-    s,
-    t,
-    r
-  );
-}
-function d(s, t, e) {
-  const r = {
-    id: s,
-    extensions: {}
-  }, o = e?.storeOptions?.enhancedStore === !0, i = g(
-    s,
-    () => t(r),
-    e
-  );
-  return Object.assign(((...u) => {
-    o && (c.set(s, r), h(s, e, "registered context by id"));
-    const a = i(...u);
-    return o && (p.set(a, r), c.delete(s), h(s, e, "moved context to weak map"), $(a, s, e)), a;
-  }), i);
-}
-function m(s, t, e) {
-  return e && (t = { ...t, ...e ?? {} }), g(s, t);
-}
-const I = /* @__PURE__ */ new Set(["_", "$"]);
-function w(s) {
-  return I.has(s[0]);
-}
-function E(s) {
-  const t = s;
-  return p.get(s) ?? (typeof t?.$id == "string" ? c.get(t.$id) : void 0);
-}
-function k(s) {
-  const t = s.extensions.enhancedStore ?? s.extensions.extending;
-  if (!t)
-    throw new Error(`${s.id}Store - getEnhancedStore - Error: enhanced store is required`);
-  return t;
-}
-function M(s, t) {
-  s.extensions.enhancedStore = t, s.extensions.extending = t;
-}
-function W(s) {
-  return console.warn(`${s.id}Store - getExtendingStore is deprecated. Use getEnhancedStore instead.`), k(s);
-}
-function F(s, t) {
-  return `${s}-${t.$id}`;
-}
-function P(s) {
-  return s ? Array.isArray(s) ? s.length === 0 : typeof s == "object" ? Object.keys(s).length === 0 : typeof s == "string" ? s.trim() === "" : !1 : !(typeof s == "boolean" || typeof s == "number");
-}
-class q extends A {
-  constructor(e, r, o = !1, i) {
-    super(o, i);
-    n(this, "_className", "Store");
-    n(this, "_onAction");
-    n(this, "_options");
-    n(this, "_store");
-    n(this, "_subscriptions", {});
-    n(this, "_storeSubscribe");
-    if (this._options = r.storeOptions, this._store = e, this._options?.enhancedStore) {
-      const u = E(this.store);
-      u && M(u, this.store);
-    }
-  }
-  get onAction() {
-    if (this._onAction)
-      return () => ({
-        store: this.store,
-        callback: this._onAction
-      });
-  }
-  set onAction(e) {
-    this._onAction = e;
-  }
-  get options() {
-    return this._options;
-  }
-  get state() {
-    return this._store.$state;
-  }
-  set state(e) {
-    this._store.$state = e;
-  }
-  get store() {
-    return this._store;
-  }
-  get storeSubscribe() {
-    if (this._storeSubscribe)
-      return () => ({
-        store: this.store,
-        callback: this._storeSubscribe
-      });
-  }
-  set storeSubscribe(e) {
-    this._storeSubscribe = e;
-  }
-  addToState(e, r) {
-    this.isOptionApi() || b(r) || (r = y(r)), this.state[e] = r, this.store[e] = C(this.state, e);
-  }
-  addSubscription(e, r, o) {
-    this._subscriptions[e] = { subscription: r, ...o ?? {} };
-  }
-  afterHydration() {
-  }
-  static customizeStore(e, r, o = !1, i) {
-    if (r.storeOptions && this.hasRequiredKeys(r.storeOptions))
-      return new this(e, r, o, i);
-  }
-  getOption(e) {
-    return this.options && this.options[e];
-  }
-  getStatePropertyValue(e) {
-    return this.getValue(this.state[e]);
-  }
-  getSubscriptions() {
-    if (!P(this._subscriptions))
-      return this._subscriptions;
-  }
-  getValue(e) {
-    return e?.__v_isRef ? e.value : e;
-  }
-  hasDeniedFirstChar(e) {
-    return w(e);
-  }
-  static hasRequiredKeys(e) {
-    return this._requiredKeys !== void 0 && this._requiredKeys?.every((r) => !!e[r]);
-  }
-  hydrate() {
-  }
-  isOptionApi() {
-    return this.store._isOptionsAPI;
-  }
-  stateHas(e) {
-    return Object.prototype.hasOwnProperty.call(this.state, e);
-  }
-  storeHas(e) {
-    return Object.prototype.hasOwnProperty.call(this.store, e);
-  }
-}
-n(q, "_requiredKeys");
-const _ = "pinia-plugin-subscription", B = (s, t = "white") => `background-color: ${s}; color: ${t}; padding: 1px; margin-right: 5px; font-size: 12px`;
-function D(s, t) {
-  if (!s)
-    throw new Error("Style instructions are required");
-  console.log(
-    "%c%s",
-    s,
-    t.shift(),
-    ...t
-  );
-}
-class K {
-  constructor() {
-    n(this, "_bgColor", "#ffec73");
-    n(this, "_color", "green");
-    n(this, "_icon", "🍍⚡");
-    n(this, "_errorBgColor", "#d24545");
-    n(this, "_errorColor", "white");
-    n(this, "_errorIcon", "🍍⚠️");
-    n(this, "_styles", {
-      error: { bgColor: this._errorBgColor, color: this._errorColor, icon: this._errorIcon },
-      info: { bgColor: this._bgColor, color: this._color, icon: this._icon }
-    });
-  }
-  formatMessage(t, e) {
-    return ` [${e} ${_}] - ${t} `;
-  }
-  generateStyle(t) {
-    return B(t.bgColor, t.color);
-  }
-  getStyleDefinition(t) {
-    return this._styles[t ?? "info"];
-  }
-  log(...t) {
-    this.useLog(
-      this.getStyleDefinition(),
-      t
-    );
-  }
-  error(...t) {
-    this.useLog(
-      this.getStyleDefinition("error"),
-      t
-    );
-  }
-  rebuildArgs(t, e) {
-    if (typeof t == "string")
-      return [this.formatMessage(t, e)];
-    if (Array.isArray(t))
-      return [this.formatMessage(t.shift(), e), ...t ?? []];
-  }
-  useLog(t, e) {
-    D(
-      this.generateStyle(t),
-      this.rebuildArgs(e, t.icon)
-    );
-  }
-}
-class R extends K {
-  constructor() {
-    super(...arguments);
-    n(this, "_pluginName", _);
-  }
-}
-const V = new R();
-export {
-  K as C,
-  A as D,
-  V as P,
-  q as S,
-  L as a,
-  T as b,
-  E as c,
-  N as d,
-  k as e,
-  W as f,
-  F as g,
-  w as h,
-  P as i,
-  _ as p,
-  M as s
-};
-//# sourceMappingURL=index-DKdl-fiq.js.map