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

package/CHANGELOG.md

@@ -8,10 +8,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
-- Moved the demo application from `src/demo/` to the repository-level `demo/` directory, separating example code from the library source and tracking the demo files in version control.
+- `storeMutationSubscription` now supports several subscribers per store, like `storeOnActionSubscription`: a single `$subscribe` is registered per store and dispatches to every callback. A failing callback is reported through `traceError` without blocking the others, subscriber names are tracked, and the hook is unsubscribed when the store is disposed
+- `storeOnActionSubscription` now receives the Pinia plugin context; action trace labels include the invoked action name
 
 ### Added
+- Added `addScopesListener(scopes, context?)` to `createTracerRegistry()` for grouping events from selected store scopes; documented in `docs/tracing.md`
+- `traceGroups` glossary, exported from `pinia-plugin-subscription/helpers`, building the `groupId` emitted by `PluginSubscription` (`onActionAfter`, `onActionError`, `onMutation`, `reset`); documented in `docs/tracing.md`
+- `createPluginSubscriber(name, invoke, optionalProps?)` factory, exported from `pinia-plugin-subscription/helpers`, to build plain-object subscribers; documented in `docs/authoring-plugins.md` and used by the demo plugin
+- Added a dedicated tracing guide, `docs/tracing.md`; the README now only presents tracing and links to it
+- Moved the API reference, import subpaths, development, `Store` summary and testing sections from `README.md` to `docs/authoring-plugins.md`
+- `createTracerRegistry({ redact })`: opt-in redaction of event payloads before they reach listeners. `true` masks a default list of sensitive keys (`password`, `token`, `secret`, `authorization`, API/private keys, `credential`, `cookie`, `cipher`...); an object adds custom `keys`, a `replacement`, or drops the defaults with `includeDefaults: false`. It works on a copy, covers arrays/`Map`/`Set`, handles circular references, and replaces the payload by `__traceRedactionError` if redaction fails. `defaultRedactedKeys` and `TraceRedactOptions` are exported
+- `createTracerRegistry({ enabled })`: tracing is now disabled by default in production builds (`process.env.NODE_ENV === 'production'`); `addListener()` becomes a no-op unless `enabled: true` is passed. `enabled: false` forces it off in any environment. Error reporting through `console.error` is unchanged
 - Added `createTracerRegistry()` to create isolated trace listeners and tracers for each application or Pinia instance
+- Added `createTracerRegistry()` to group matching trace events in the console
 - Added the `Tracer` class and registry methods `addTraceListener()`, `clearTraceListeners()` and `hasTraceListeners()`
 - Added metadata-based trace filter criteria with `equals`, `contains`, `startsWith` and `endsWith` comparators, combined with `every` or `some`
 - Added `createConsoleTraceListener()` as an opt-in console sink for trace events
@@ -22,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added unit tests covering the tracing system and the leak detection logic
 
 ### Changed
+- Moved the demo application from `src/demo/` to the repository-level `demo/` directory, separating example code from the library source and tracking the demo files in version control.
 - Clarified that SSR tracing registries and plugin instances must be created per request, and added coverage for listener isolation between registries
 - Replaced the `Debug` abstract class with composition: `Store` and `PluginSubscription` no longer extend it and now own a `Tracer`
 - `createPlugin()` accepts `PluginSubscriptionOptions`, including a `createTracer` factory to connect a tracer registry to plugin and store trace events
@@ -33,9 +43,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Error events are delivered to matching listeners and reported with `console.error` when none match
 - Store trace labels can include the store class name by default, and callers can override the event namespace
 - Excluded `scripts/**` from coverage thresholds, as build tooling is not shipped to consumers
+- `Store` and `PluginSubscription` now share the abstract `TraceEmitter` class for `trace()`, `traceError()` and class-name label formatting, removing duplicated code
+- `Tracer` listener matching no longer allocates intermediate arrays beyond the matched set, and duplicated unhandled-error reporting was factored out
+- The `pluginsubscription` namespace prefix is now a shared constant (`pluginSubscriptionNamespace`) instead of a hard-coded string
+
+### Fixed
+- `onAction`, `after` and `onError` subscription callbacks may now be asynchronous: rejections are traced instead of becoming unhandled, and their trace groups are closed once all async callbacks have settled
+- Group listener filters receive only trace metadata, redaction safely copies own `__proto__` keys, and registry group payload factories are skipped when no listeners are registered
+- Subscriber, subscription, action and rollback tracking keys now encode store IDs and names without delimiter collisions; disposing a store removes only its own tracking entries
+- Trace groups opened by `onAction`, `$subscribe` and `$reset` are now always closed (also when the action fails or a callback throws), so grouped events no longer stay buffered forever
+- Listener definitions passed to `addListener()` are no longer mutated when their `filter` is an array of criteria
+- `TracerHandler` and `TraceRegistry` types now match the implementation (`createTracer(source, options?)`, `void` group callbacks, `addListener()` with options, `tracerHandler`); `createTracerRegistry()` is explicitly typed as `TraceRegistry`
+- `CustomConsole.rebuildArgs()` no longer returns `undefined` for unsupported argument types
+- `clearTraceListeners()` now empties the shared listener list in place, so tracers created before the call stop delivering to cleared listeners and see listeners registered afterwards
 
 ### Removed
-- **Breaking:** removed `debugLog()` and `logError()` from `Store` and `PluginSubscription` — use `trace()` and `traceError()` instead (see the migration snippet in `README.md`)
+- Removed the internal `PluginConsole` singleton and the dead commented code of `system/log.ts`; `CustomConsole` stays exported from `helpers` for plugins not yet migrated to the tracer
+- **Breaking:** removed `debugLog()` and `logError()` from `Store` and `PluginSubscription` — use `trace()` and `traceError()` instead (see the migration snippet in `docs/tracing.md`)
 - **Breaking:** removed the obsolete `debug` and custom-console arguments from `createPlugin()`, `PluginSubscription`, `PluginSubscriber`, `Store`, and `Store.customizeStore()`
 - **Breaking:** removed the `debug` argument from subscriber `invoke()`, `hydrate()`, and `afterHydration()` hooks; tracing is now configured exclusively through listeners
 - **Breaking:** removed the legacy `debug` and `console` accessors from `Store` and `PluginSubscription`

package/README.md

@@ -34,7 +34,8 @@ The package serves two audiences:
 | You want to… | Guide |
 | --- | --- |
 | Use a compatible plugin (e.g. `pinia-plugin-extending-store`, `pinia-plugin-persist-state`) or this package's built-in store features (`defineAStore`, `$reset`, state rollback) in your app | [Using compatible plugins](docs/using-plugins.md) |
-| Build your own pinia plugin on top of `pinia-plugin-subscription` | [Plugin authoring guide](docs/authoring-plugins.md) |
+| Build your own pinia plugin on top of `pinia-plugin-subscription` (API reference, `Store` class, import subpaths, development and testing) | [Plugin authoring guide](docs/authoring-plugins.md) |
+| Debug stores and plugins with structured trace events | [Tracing](docs/tracing.md) |
 
 ## Installation
 
@@ -60,311 +61,29 @@ app.use(pinia)
 app.mount('#app')
 ```
 
-### Import subpaths
-
-## Usage — Examples
-
-**1) Subscriber using a `Store` subclass:**
-
-```typescript
-import PluginSubscriber from 'pinia-plugin-subscription'
-import { Store } from 'pinia-plugin-subscription'
-
-class MyPlugin extends Store {
-  protected override _className: string = 'MyPlugin'
-  protected static override _requiredKeys?: string[] | undefined = ['my-plugin-option']
-
-  constructor(store, options) {
-    super(store, options)
-    this.doSomething()
-  }
-}
-
-class MyPluginSubscriber extends PluginSubscriber<MyPlugin> {
-  constructor() {
-    super('my-plugin', MyPlugin.customizeStore.bind(MyPlugin))
-  }
-}
-
-export const myStoreSubscriber = new MyPluginSubscriber()
-```
-
-**2) Simple subscriber implementing `PluginSubscriberInterface`:**
-
-```typescript
-import type { PluginSubscriberInterface } from 'pinia-plugin-subscription'
-
-export const myStoreSubscriber: PluginSubscriberInterface = {
-  name: 'my-plugin',
-
-  invoke: (context) => {
-    // context contains `store`, `options`, `pinia`
-    console.log('store registered', context.store.$id)
-
-    return true
-  },
-
-  resetStoreCallback: (store) => {
-    console.log('store reset:', store.$id)
-  }
-}
-```
-
 ## Advanced Features
 
-- **Structured tracing:** Subscribe to typed trace events and filter them at runtime, per store or per namespace — see [Tracing](#tracing).
+- **Structured tracing:** Subscribe to typed trace events and filter them at runtime, per store or per namespace. Group filters receive metadata only, and the built-in registry avoids preparing group payloads when it has no listeners — see [Tracing](#tracing).
+- **Scope-based trace listeners:** Use `addScopesListener()` to group events from selected stores — see [Tracing](docs/tracing.md#filtering-events).
 - **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.
 - **Lifecycle safety:** Internal hydration ordering is now guarded so `hydrate()` completes before `afterHydration()` and disposed stores do not retain stale subscriber metadata.
 
-## API Reference
-
-### `createPlugin(subscribers: PluginSubscriber[], options?: PluginSubscriptionOptions): PiniaPlugin`
-
-Creates and returns a Pinia plugin from the provided `subscribers`. Each subscriber is invoked when a store is registered. The optional `options` configure execution, hydration and tracing.
-
-### `createHydrationPlugin(subscribers: PluginSubscriber[], options?: PluginSubscriptionOptions): PiniaPlugin`
-
-Deprecated. Use `createPlugin()` with hydration options instead. This helper remains available for compatibility.
-
-```typescript
-import { createPlugin } from 'pinia-plugin-subscription'
-
-pinia.use(createPlugin([
-  persistedStateSubscriber
-], {
-  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) => {
-    // ...
-    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 on a subscriber or through `createPlugin()` options to override execution timing when needed.
-
-### SSR / Nuxt best practices
-
-`pinia-plugin-subscription` is SSR-safe by design, but the runtime policy still needs to match the actual app lifecycle.
-
-For helper-only imports, the package exposes an additive subpath kept separate from the default library API:
-
-```ts
-import { PluginSubscriber, Store } from 'pinia-plugin-subscription/helpers'
-```
-
-For type-only imports, prefer the dedicated public types entry:
-
-```ts
-import type { PluginSubscriptionOptions } from 'pinia-plugin-subscription/types'
-```
-
-## Development
-
-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:
-
-- **Properties:** `options`, `state`, `store`.
-- **Useful methods:**
-  - `addToState(name, value?)` — adds a property to store state and exposes it as a `Ref` when appropriate.
-  - `addSubscription(pluginName, subscription)` — registers a plugin-specific subscription function.
-  - `getSubscriptions()` — returns registered subscriptions.
-  - `storeSubscribe` (getter/setter) — factory for `store.$subscribe` ({ store, callback }).
-  - `onAction` (getter/setter) — factory for `onAction` ({ store, callback }).
-  - `static customizeStore(store, options)` — recommended factory for class instantiation.
-  - `trace(label, payload?, scope?, namespace?)` — emits a structured trace event, scoped to the store by default.
-  - `traceError(label, error, payload?, scope?, namespace?)` — emits an error event, or reports it with `console.error` when no listener matches.
-  - Helpers: `stateHas()`, `storeHas()`, `getValue()`.
-
 ## Tracing
 
-Tracing is **opt-in**, scoped to an explicit registry, and **allocation free when unused**. Create one registry per application or Pinia instance, then pass its `createTracer` factory to `createPlugin()` so plugin and store events share its listeners. For SSR, create a fresh registry, Pinia instance, and plugin instance for every request; do not keep them in module-level state or clear a shared registry at request completion, since requests may overlap. See the [SSR guide](./docs/using-plugins.md#ssr--nuxt) for an example.
-
-### Production safety
-
-Tracing is **not automatically blocked in production**. Leave normal tracing disabled by default using your application's environment configuration; enable production diagnostics only deliberately and with limited scope and duration.
-
-Events are **not automatically redacted** and may include sensitive action arguments, store state, plugin options, or error details. Filters select events by metadata; they do not sanitize payloads. Before writing to a console or forwarding to a logging service, select an allowlist of fields and redact sensitive values rather than sending complete events.
-
-**Disabling normal tracing does not disable error reporting.** Errors can still be sent to `console.error` without a tracer or when no listener matches. See [Error reporting](#error-reporting) and the [security guidance](./SECURITY.md#tracing-and-production-logging) for precautions, including log access and retention.
-
-### Consuming events
+A built-in, opt-in debugging solution: plugins and stores emit structured trace events that you select with filters, optionally redact, and group in the console. It is disabled by default in production builds and costs nothing when unused.
 
 ```ts
 import { createPlugin } from 'pinia-plugin-subscription'
 import { createTracerRegistry } from 'pinia-plugin-subscription/helpers'
 
-const traceRegistry = createTracerRegistry()
-const remove = traceRegistry.addTraceListener({
-  filter: (event) => event.scope === 'cart'
-    && event.namespace.startsWith('pluginsubscription:subscription:'),
-  handler: (event) => console.log(event.namespace, event.scope, event.payload)
-})
-
-pinia.use(createPlugin(subscribers, {
-  createTracer: traceRegistry.createTracer
-}))
-
-remove() // unsubscribe
-```
-
-`filter` is evaluated against event metadata before the payload is resolved,
-so you can narrow tracing to a single store without building discarded
-payloads. Registries do not share listeners with one another.
-
-For simple metadata filters, provide comparison criteria instead of a
-callback. Supported comparators are `equals` (the default), `contains`,
-`startsWith` and `endsWith`; multiple criteria use `every` by default or
-`some` when requested:
-
-```ts
-traceRegistry.addTraceListener({
-  filter: [
-    { target: 'scope', value: 'cart' },
-    { target: 'namespace', comparator: 'startsWith', value: 'pluginsubscription:subscription:' }
-  ]
-}, 'every')
-```
-
-When no `handler` is provided for criteria-based registration, the registry
-uses its styled console listener.
-
-### Event shape
-
-| Field | Description |
-| --- | --- |
-| `namespace` | Structured identifier, derived from the label by default |
-| `label` | Human-readable event label |
-| `source` | Source passed to `createTracer`, usually `pinia-plugin-subscription` |
-| `scope` | Instance identifier, usually `store.$id` |
-| `payload` | Event data, resolved only when consumed |
-| `level` | `debug` or `error` |
-| `timestamp` | `Date.now()` at emission |
-| `error` | Present on `error` events |
-
-By default, `Store` prefixes its class name to labels and derived namespaces.
-Library events use `PluginSubscription` as their prefix (for example,
-`pluginsubscription:store:mutation` and
-`pluginsubscription:subscription:delivery`). Set
-`classNameAddedToTraceNamespace = false` on a `Store` subclass to omit its
-class prefix, or provide an explicit namespace as the fourth argument to
-`trace()` / `traceError()`.
-
-### Emitting your own events
-
-```ts
-class CartStore extends Store {
-  hydrate() {
-    this.trace('cart:hydrate', () => ({ items: this.state.items }))
-  }
-}
-```
-
-`Store.trace(label, payload?, scope?, namespace?)` and
-`Store.traceError(label, error, payload?, scope?, namespace?)` emit the events.
-The store class name is included in the label by default; set
-`classNameAddedToTraceNamespace = false` to omit it. Unless an explicit
-namespace is provided, the normalized label is used as the namespace.
-
-Always prefer the **function form** for `payload`: it is only invoked once a
-listener matches, so unobserved tracing costs nothing.
-
-### Console listener
-
-Normal trace events do not write to a console. Console output for those events is an opt-in listener:
+const registry = createTracerRegistry({ redact: true })
+registry.addListener([{ target: 'scope', value: 'cart' }])
 
-```ts
-import {
-  createConsoleTraceListener,
-  createTracerRegistry
-} from 'pinia-plugin-subscription/helpers'
-
-const traceRegistry = createTracerRegistry()
-const remove = traceRegistry.addTraceListener({
-  ...createConsoleTraceListener(),
-  filter: () => true
-})
-```
-
-By default, this listener uses the styled plugin console. Pass any object exposing `log` and `error` to use another target:
-
-Any object exposing `log` and `error` satisfies the `Console` interface, so external logging libraries can be connected without this plugin depending on them:
-
-```ts
-const remove = traceRegistry.addTraceListener({
-  ...createConsoleTraceListener(myLogger),
-  filter: () => true
-})
-```
-
-### Error reporting
-
-An error is delivered to every matching listener. If no listener matches — including when listeners exist but all filters reject the event — it is reported with `console.error`; it is not rethrown. Errors thrown by filters or handlers are also reported and isolated so they do not interrupt the traced process or remaining listeners.
-
-### Migrating from `debugLog()` / `logError()`
-
-These methods were removed in favour of structured events:
-
-```ts
-// before
-this.debugLog(`$subscribe ${store.$id}`, { mutation, store })
-this.logError('subscriptionDelivery()', error, store, options)
-
-// after
-this.trace('store:mutation', () => ({ mutation, store }))
-this.traceError('subscription:delivery', error, () => ({ store, options }))
-```
-
-The `namespace` replaces the formatted message, store trace events are scoped to `store.$id`, and the payload becomes a factory so it is only built when a listener consumes the event.
-
-## Testing
-
-- `npm run dev` — runs the dedicated demo app in [`demo/`](demo/). The library build remains `npm run build` and is intentionally kept separate from the demo entry.
-- `npm test` — runs the Vitest suite, including typecheck tests (`*.test-d.ts`) validating type-level contracts such as `StoreOptionsExtensions` merging. Coverage reports are available in `coverage/`.
-- `npm run bundle:check` — measures the emitted bundle size.
-
-### Dependency leak guard
-
-Published artifacts must only reference **peer dependencies** (`pinia`, `vue`) and Node builtins. A `devDependency` referenced from `src/` does not fail the local build, but it breaks consumers: Vite inlines runtime imports, while `tsc` keeps bare `import type` specifiers in the emitted `.d.ts`, which consumers cannot resolve.
-
-`npm run check:leaks` scans every built `.js` and `.d.ts` file and fails the build when a non-peer package appears:
-
-```bash
-npm run check:leaks
+pinia.use(createPlugin(subscribers, { tracerHandler: registry.tracerHandler }))
 ```
 
-It runs automatically as part of `npm run build` and in CI. If it reports a leak, either remove the import from `src/`, or duplicate the required type into `src/types/`.
+See the [Tracing documentation](docs/tracing.md) for filtering, redaction, production safety, event shape and error reporting.
 
 ## License
 

package/SECURITY.md

@@ -38,22 +38,22 @@ When using pinia-plugin-subscription:
 
 ### Tracing and Production Logging
 
-Normal trace events are opt-in: the plugin requires an explicitly configured `createTracer` factory and matching listeners to deliver them. The plugin does not automatically detect production environments or block tracing in production. Production tracing can be useful for incident diagnosis, but should only be enabled deliberately and with controlled access to its output.
+Normal trace events are opt-in: the plugin requires an explicitly configured `tracerHandler` and matching listeners to deliver them. `createTracerRegistry()` ignores `addListener()` in production builds (`process.env.NODE_ENV === 'production'`) unless `createTracerRegistry({ enabled: true })` is passed. This guard relies on the consuming bundler replacing `process.env.NODE_ENV`; without it, tracing is considered enabled. Production tracing can be useful for incident diagnosis, but should only be enabled deliberately and with controlled access to its output.
 
-Trace events are not automatically sanitized or redacted. Depending on the event, they may contain action arguments, store state, mutations, plugin options, subscriptions, or error details. These values can include application secrets or personal data. A listener can expose them through the browser console, server logs, or an external logging service. The absence of a production block is not, by itself, a vulnerability; the disclosure risk depends on the data emitted, the logging destination, and who can access it.
+Trace events are not redacted by default. Depending on the event, they may contain action arguments, store state, mutations, plugin options, subscriptions, or error details. These values can include application secrets or personal data. `createTracerRegistry({ redact: true })` masks values stored under sensitive keys (passwords, tokens, secrets, authorization, API keys, cookies...) before any listener receives them, but it inspects keys only: it does not detect secrets under innocuous keys, and it does not redact `event.error`. A listener can expose them through the browser console, server logs, or an external logging service. The absence of a production block is not, by itself, a vulnerability; the disclosure risk depends on the data emitted, the logging destination, and who can access it.
 
 When configuring tracing:
 
-1. **Disable Normal Tracing in Production by Default:** Use the application's environment configuration to omit `createTracer` or avoid registering normal trace listeners. Enable production diagnostics only when needed and limit their duration and scope.
-2. **Minimize Logged Data:** Select an explicit allowlist of fields and redact sensitive values before writing or forwarding events. Avoid logging complete stores, action arguments, plugin options, or raw error objects.
-3. **Do Not Treat Filters as Redaction:** Filters only select events using metadata; a matching handler receives the full event, including its resolved payload and error. Sanitize data in the handler before passing it to a logging destination.
+1. **Keep Normal Tracing Disabled in Production:** This is the default of `createTracerRegistry()`. Only pass `enabled: true` when diagnostics are needed, and limit their duration and scope.
+2. **Minimize Logged Data:** Enable `createTracerRegistry({ redact: true })` (extend it with your own `keys`) and select an explicit allowlist of fields before writing or forwarding events. Avoid logging complete stores, action arguments, plugin options, or raw error objects.
+3. **Do Not Treat Filters as Redaction:** Filters only select events using metadata; a matching handler receives the full event, including its resolved payload and error. Use the `redact` option, and sanitize `event.error` and any remaining data in the handler before passing it to a logging destination.
 4. **Protect Logging Destinations:** Review external logging services, restrict access to logs, and define appropriate retention periods. Do not assume browser console output or server logs are private.
 
 **Error reporting is separate from normal tracing.** Without a tracer, plugin and store error reporting falls back to `console.error`. With a tracer, error events also fall back to `console.error` when no listener matches, including when all filters reject the event. Exceptions thrown by listener filters or handlers are reported to `console.error` as well. Removing listeners, clearing a registry, or omitting `createTracer` therefore does not guarantee that no errors will be logged.
 
 For production, handle error events with a matching listener that reports only sanitized details, and ensure listener filters and handlers do not throw sensitive errors. Review the application's console and error logging policy as well; do not silently discard operational errors to prevent disclosure.
 
-See [Tracing](./README.md#tracing) for configuration and event details.
+See [Tracing](./docs/tracing.md) for configuration and event details.
 
 ## Dependencies Security