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

package/dist/types/trace.d.ts

@@ -0,0 +1,121 @@
+import type { AnyObject } from './index';
+import type Tracer from '../system/Tracer';
+export interface AddTraceListenerOptions {
+    filterMode?: TraceListenerFilterMode;
+    groupBy?: TraceListenerGroupBy;
+}
+export interface ConsoleTraceEventArgs extends Omit<TraceEvent, 'level' | 'timestamp'> {
+}
+export type ConsoleTraceEvent = Array<string | ConsoleTraceEventArgs>;
+/**
+ * A trace listener that supports grouping of trace events.
+ */
+export interface ConsoleTraceGroupListener extends Omit<TraceListener, 'filter'> {
+    createGroup: (key: string) => void;
+    logGroup: (key: string) => void;
+}
+/**
+ * Severity of a trace event.
+ * `error` events are delivered to matching listeners, or reported with `console.error` when none match.
+ */
+export type TraceLevel = 'debug' | 'error';
+/**
+ * Cheap descriptor of an event, built before the payload is resolved.
+ * Filters receive this object so that discarded events never allocate a payload.
+ */
+export interface TraceEventMetadata {
+    /** Label describing the event, e.g. `Subscription:Delivery`. */
+    label: string;
+    /** Severity of the trace event. */
+    level: TraceLevel;
+    /** Structured, colon separated identifier, e.g. `subscription:delivery`. */
+    namespace: string;
+    /** Instance the event belongs to, usually a Pinia `store.$id`. */
+    scope?: string;
+    /** Emitting class name, e.g. `PluginSubscription`. */
+    source: string;
+}
+/**
+ * A resolved trace event, handed over to listeners.
+ */
+export interface TraceEvent extends TraceEventMetadata {
+    error?: unknown;
+    payload?: AnyObject;
+    timestamp: number;
+}
+type TraceFilterCriterionComparator = 'equals' | 'contains' | 'startsWith' | 'endsWith';
+export interface TraceFilterCriterion {
+    comparator: TraceFilterCriterionComparator;
+    target: keyof TraceEventMetadata;
+    value: string;
+}
+export interface TraceFilterFactoryCriterion extends Omit<TraceFilterCriterion, 'comparator'> {
+    comparator?: TraceFilterCriterionComparator;
+}
+export type TraceFilterFactoryParam = {
+    handler?: TraceHandler;
+    filter: TraceFilter | TraceFilterFactoryCriterion[];
+};
+/**
+ * Event data. Prefer the function form: it is only invoked when a listener
+ * actually consumes the event, keeping unobserved tracing allocation free.
+ */
+export type TracePayload = AnyObject | (() => AnyObject);
+/**
+ * Determines whether a trace event should be delivered to a listener.
+ * @param event The metadata of the trace event.
+ * @returns `true` if the event should be delivered to the listener, otherwise `false`.
+ */
+export type TraceFilter = (event: TraceEventMetadata) => boolean;
+export interface TraceGroupListener extends ConsoleTraceGroupListener, TraceListener {
+    groupBy: TraceListenerGroupBy;
+}
+/**
+ * Handles a trace event.
+ * @param event The resolved trace event to handle.
+ */
+export type TraceHandler = (event: TraceEvent) => void;
+export interface TraceListener {
+    /** Evaluated on every event; return `true` to receive it. */
+    filter: TraceFilter;
+    /** Handles the trace event when it passes the filter. */
+    handler: TraceHandler;
+}
+export type TraceListenerFilterMode = 'every' | 'some';
+export type TraceListenerGroupBy = keyof TraceEventMetadata;
+/** Removes a previously registered listener. */
+export type TraceListenerRemover = () => void;
+export type TraceRegistry = {
+    /**
+     * Registers a trace listener and returns its remover.
+     * Listeners are evaluated in registration order.
+     * @param listener The trace listener to register.
+     * @returns A function that removes the registered listener when called.
+     */
+    addTraceListener: (listener: TraceListener | TraceFilterFactoryParam, filterMode?: 'every' | 'some') => TraceListenerRemover;
+    /**
+     * Clears all registered trace listeners.
+     */
+    clearTraceListeners: () => void;
+    /**
+     * Creates a new tracer instance.
+     * @param source The source of the tracer, usually the class name.
+     * @param options Optional tracer options.
+     * @returns A new tracer instance.
+     */
+    createTracer: (source: string, options?: TracerOptions) => Tracer;
+    /**
+     * Checks if there are any registered trace listeners.
+     * @returns True if there are registered trace listeners, otherwise false.
+     */
+    hasTraceListeners: () => boolean;
+};
+export interface TracerHandler {
+    closeGroup: (payload: TraceEvent) => undefined;
+    createTracer: (source: string) => Tracer;
+    startGroup: (payload: TraceEvent) => undefined;
+}
+export interface TracerOptions {
+    scope?: string;
+}
+export {};

package/dist/utils/store.d.ts

@@ -1,6 +1,7 @@
 import type { DefineStoreOptions, SetupStoreDefinition, StateTree, Store, StoreDefinition, _GettersTree } from "pinia";
 import type { AnyObject } from "../types";
-import type { DefineAStoreDefinition, DefineAStoreSetupContext, EmptyExtensions, PluginStoreOptions, StoreOptions } from "../types/store";
+import type { DefineAStoreDefinition, DefineAStoreSetupContext, EmptyExtensions, StoreOptions } from "../types/store";
+import type { PluginStoreOptions } from "../types/plugin";
 export declare const itemState: {
     '@id': undefined;
     id: undefined;

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,10 @@ 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(label, payload?, scope?, namespace?)` | Emits a structured trace event. The default scope is the wrapped store ID. |
+| `traceError(label, error, payload?, scope?, namespace?)` | Emits an error event; if no listener matches, reports it with `console.error` without rethrowing it. |
+| `classNameAddedToTraceNamespace` (getter/setter) | Controls whether the store class name is prefixed to trace labels; enabled by default. |
 | `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 +234,7 @@ export const persistedStateSubscriber = {
   hydrationScheduler: (run) => {
     nextTick(() => run())
   },
-  invoke: (context, debug) => {
+  invoke: (context) => {
     // ...
     return true
   }
@@ -256,7 +256,7 @@ export const persistedStateSubscriber: PluginSubscriberInterface = {
   hydrationScheduler: (run) => {
     nextTick(() => run())
   },
-  invoke: (context, debug) => {
+  invoke: (context) => {
     // ...
     return true
   }
@@ -360,6 +360,35 @@ const mySubscriber = {
 This keeps the server render deterministic and prevents browser-only
 initialization from crashing Nuxt or SSR builds.
 
+### Emitting trace events
+
+Use `trace()` and `traceError()` from a `Store` subclass to emit structured
+events. The first argument is a human-readable label; by default the store
+class name is prefixed to it and the normalized label becomes the namespace.
+Pass an explicit fourth `namespace` argument to control the namespace, or set
+`classNameAddedToTraceNamespace = false` to omit the class prefix. Prefer a
+payload factory so data is not built unless a listener consumes the event:
+
+```ts
+class CartStore extends Store {
+  reportItems(): void {
+    this.trace(
+      'cart:items',
+      () => ({ items: this.state.items }),
+      this.store.$id,
+      'cart:items'
+    )
+  }
+}
+```
+
+`createTracerRegistry()` and `createConsoleTraceListener()` are available
+from `pinia-plugin-subscription/helpers`. Register listeners on a registry
+and pass its `createTracer` factory through `createPlugin()` options to
+connect them to plugin and store events. Listener filters can be callbacks
+over event metadata or criteria using `equals`, `contains`, `startsWith` and
+`endsWith` comparisons.
+
 ## Typing per-store options: `StoreOptionsExtensions` (TypeScript)
 
 This package is the only one allowed to augment pinia's
@@ -395,7 +424,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.
@@ -403,6 +432,6 @@ Guidelines:
 ## Reference implementation
 
 The demo app ships a complete plugin implementation in
-[`src/demo/extending-pinia-store/`](../src/demo/extending-pinia-store/): a
+[`demo/`](../demo/): a
 `PluginSubscriber` subclass, a `Store` subclass, option typing and SSR
 guards. Run `npm run dev` to explore it live.

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,46 @@ 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 {
+  createConsoleTraceListener,
+  createTracerRegistry
+} from 'pinia-plugin-subscription/helpers'
+import {
+  createPlugin
+} from 'pinia-plugin-subscription'
+
+const traceRegistry = createTracerRegistry()
+
+traceRegistry.addTraceListener({
+  ...createConsoleTraceListener(),
+  filter: event => event.scope === 'cart'
+})
+
+pinia.use(createPlugin([myStoreSubscriber], {
+  createTracer: traceRegistry.createTracer
+}))
 ```
 
-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.
+You can also use comparison criteria (`equals`, `contains`, `startsWith` or
+`endsWith`) instead of a filter callback; criteria are combined with `every`
+by default or `some` when requested. If criteria are provided without a
+handler, the registry uses its styled console listener.
+
+```js
+traceRegistry.addTraceListener({
+  filter: [
+    { target: 'scope', value: 'cart' },
+    { target: 'namespace', comparator: 'startsWith', value: 'pluginsubscription:subscription:' }
+  ]
+}, 'every')
+```
 
 ## SSR / Nuxt
 
@@ -334,16 +360,48 @@ 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 } from 'pinia-plugin-subscription'
+import { createTracerRegistry } from 'pinia-plugin-subscription/helpers'
+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 +413,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.1",
   "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"