pinia-plugin-subscription 0.1.6 → 0.1.7-beta.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.7]
+
+### Changed
+- Hardened SSR hydration sequencing so `hydrate()` always runs before `afterHydration()` and lifecycle errors are caught without breaking store registration.
+- Improved reset-state cloning to avoid JSON-only pitfalls during `$reset`, including structured values such as `Map` and `Set`.
+- Ensured tracking metadata is cleared when a store is disposed to prevent stale subscriber state.
+- Tightened internal store checks to avoid `hasOwnProperty` collisions.
+- Reduced library bundle overhead by stripping the Vue plugin from the library build and treeshaking the published bundle more aggressively.
+- Added additive sub-exports for helper-only imports and a strict type-only public surface to keep the core API stable while improving bundle clarity.
+- Added a real bundle-size check command to measure the emitted output before deciding whether a heavier split is justified.
+- Documented Nuxt / SSR best practices for `hydration: 'defer'`, `runtimeEnvironment`, and browser-only access in hydrated stores.
+
 ## [0.1.6]
 
 ### Added

package/README.md

@@ -14,6 +14,26 @@
 
 Ensure Pinia is installed, then register the plugin in your `main.ts`:
 
+For local development and runtime demos, use the dedicated demo app with `npm run dev`. The library build remains `npm run build` and is intentionally kept separate from the demo entry.
+
+For helper-only imports, the package also exposes an additive subpath that is kept separate from the default library API:
+
+```typescript
+import { PluginSubscriber, Store } from 'pinia-plugin-subscription/helpers'
+```
+
+For type-only imports, prefer the dedicated public types entry:
+
+```typescript
+import type { PluginSubscriptionOptions } from 'pinia-plugin-subscription/types'
+```
+
+The project also includes a bundle check command to measure the real output size before introducing a heavier split strategy:
+
+```bash
+npm run bundle:check
+```
+
 ```typescript
 import { createApp } from 'vue'
 import { createPinia } from 'pinia'
@@ -84,6 +104,7 @@ export const myStoreSubscriber: PluginSubscriberInterface = {
 - **Debug mode:** Specifies the name of the plugin(s) to debug as the second argument to `createPlugin` to enable detailed logging.
 - **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
 
@@ -135,6 +156,61 @@ Available execution options:
 - `hydration: 'immediate' | 'defer'` — on the client, `defer` schedules execution after hydration.
 - `hydrationScheduler` can be provided either on a subscriber or via `createHydrationPlugin()` to override the 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.
+
+Use `hydration: 'defer'` when the subscriber depends on browser-only APIs, client-side cookies, localStorage, DOM access, or a hydrated app state that must exist only after the app is mounted.
+
+```ts
+const persistedStateSubscriber: PluginSubscriberInterface = {
+  name: 'persisted-state',
+  execution: {
+    environment: 'client',
+    hydration: 'defer',
+  },
+  hydrationScheduler: (run) => nextTick(() => run()),
+  invoke: () => true,
+}
+```
+
+Use `runtimeEnvironment: 'server'` or `execution.environment: 'server'` when a subscriber is only valid during server-side rendering or when it should not touch browser-only objects.
+
+```ts
+pinia.use(createHydrationPlugin([serverOnlySubscriber], {
+  runtimeEnvironment: 'server'
+}))
+```
+
+Avoid browser-only code in stores during build-time SSR. In practice, that means:
+
+- do not access `window`, `document`, `localStorage`, or `matchMedia` at module scope or during store setup when the code may run on the server,
+- keep browser-specific bootstrap in `hydrate()` or `afterHydration()`,
+- prefer environment-aware guards such as `typeof window !== 'undefined'`,
+- avoid doing network access or hydration reads before the client is ready unless the code is explicitly intended to run on both environments.
+
+A safe pattern is:
+
+```ts
+const mySubscriber: PluginSubscriberInterface = {
+  name: 'safe-browser-access',
+  execution: {
+    environment: 'client',
+    hydration: 'defer',
+  },
+  hydrate: (context) => {
+    // safe browser access here after hydration is allowed
+    const saved = localStorage.getItem('demo')
+    if (saved) {
+      context.store.$patch({ value: JSON.parse(saved) })
+    }
+  },
+  invoke: () => true,
+}
+```
+
+This keeps the server render deterministic and prevents browser-only initialization from crashing Nuxt or SSR builds.
+
 ### `defineAStoreCtx(id, setup, options?)`
 
 Use actions or access the state, added by one or more plugins, when defining the store.

package/dist/chunks/index-ByASkYCc.js

@@ -0,0 +1,338 @@
+var f = Object.defineProperty;
+var b = (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) => b(s, typeof t != "symbol" ? t + "" : t, e);
+import { ref as S, toRef as y } 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;
+  }
+  hydrate(t, e) {
+  }
+  afterHydration(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 C {
+  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(), A = 50;
+function O(s) {
+  return s?.storeOptions?.debug === !0;
+}
+function h(s, t, e) {
+  if (!O(t))
+    return;
+  const r = c.size;
+  console.debug(`[defineAStoreSetup] ${s} - ${e} (contextsById=${r})`), r >= A && console.warn(`[defineAStoreSetup] contextsById reached ${r} entries`);
+}
+function x(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 R(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"), x(a, s, e)), a;
+  }), i);
+}
+function m(s, t, e) {
+  return e && (t = { ...t, ...e ?? {} }), g(s, t);
+}
+const $ = /* @__PURE__ */ new Set(["_", "$"]);
+function I(s) {
+  return $.has(s[0]);
+}
+function w(s) {
+  return p.get(s) ?? (typeof s?.$id == "string" ? c.get(s.$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 T(s) {
+  return k(s);
+}
+function E(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 P extends C {
+  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 = w(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;
+  }
+  hydrate() {
+  }
+  afterHydration() {
+  }
+  get storeSubscribe() {
+    if (this._storeSubscribe)
+      return () => ({
+        store: this.store,
+        callback: this._storeSubscribe
+      });
+  }
+  set storeSubscribe(e) {
+    this._storeSubscribe = e;
+  }
+  /**
+   * Add property to state
+   * @param name 
+   * @param value 
+   */
+  addToState(e, r) {
+    this.isOptionApi() || r?.value || (r = S(r)), this.state[e] = r, this.store[e] = y(this.state, e);
+  }
+  addSubscription(e, r, o) {
+    this._subscriptions[e] = { subscription: r, ...o ?? {} };
+  }
+  /**
+   * Create and return a class instance
+   * @param store 
+   * @param options 
+   * @param debug 
+   * @returns 
+   */
+  static customizeStore(e, r, o = !1, i) {
+    if (r.storeOptions && this.hasRequiredKeys(r.storeOptions))
+      return new this(e, r, o, i);
+  }
+  hasDeniedFirstChar(e) {
+    return I(e[0]);
+  }
+  static hasRequiredKeys(e) {
+    return this._requiredKeys !== void 0 && this._requiredKeys?.every((r) => !!e[r]);
+  }
+  getOption(e) {
+    return this.options && this.options[e];
+  }
+  getStatePropertyValue(e) {
+    return this.getValue(this.state[e]);
+  }
+  getSubscriptions() {
+    if (!E(this._subscriptions))
+      return this._subscriptions;
+  }
+  getValue(e) {
+    return e?.__v_isRef ? e.value : e;
+  }
+  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(P, "_requiredKeys");
+const _ = "pinia-plugin-subscription", q = (s, t = "white") => `background-color: ${s}; color: ${t}; padding: 1px; margin-right: 5px; font-size: 12px`;
+function B(s, t) {
+  if (!s)
+    throw new Error("Style instructions are required");
+  console.log(
+    "%c%s",
+    s,
+    t.shift(),
+    ...t
+  );
+}
+class D {
+  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 q(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) {
+    B(
+      this.generateStyle(t),
+      this.rebuildArgs(e, t.icon)
+    );
+  }
+}
+class j extends D {
+  constructor() {
+    super(...arguments);
+    n(this, "_pluginName", _);
+  }
+}
+const W = new j();
+export {
+  D as C,
+  C as D,
+  W as P,
+  P as S,
+  L as a,
+  R as b,
+  k as c,
+  N as d,
+  T as e,
+  w as g,
+  E as i,
+  _ as p,
+  M as s
+};

package/dist/core/Store.d.ts

@@ -0,0 +1,53 @@
+import Debug from "../system/Debug";
+import type { PluginSubscriptions, StoreMutationSubscription, StoreMutationSubscriptionCallback, StoreOnActionSubscription, StoreOnActionSubscriptionCallback } from "../types/plugin";
+import type { Store as PiniaStore, StateTree } from "pinia";
+import type { Console } from "../types/log";
+import type { AnyObject, PluginSubscriberInterface } from "../types";
+import type { StoreOptions, StatePropertyValue } from "../types/store";
+export default class Store extends Debug {
+    protected _className: string;
+    private _onAction?;
+    private _options;
+    private _store;
+    private _subscriptions;
+    private _storeSubscribe?;
+    protected static _requiredKeys?: string[];
+    get onAction(): StoreOnActionSubscription | undefined;
+    set onAction(onAction: StoreOnActionSubscriptionCallback);
+    get options(): StoreOptions;
+    get state(): StateTree;
+    set state(state: StateTree);
+    get store(): AnyObject;
+    hydrate(): void | Promise<void>;
+    afterHydration(): void | Promise<void>;
+    get storeSubscribe(): StoreMutationSubscription | undefined;
+    set storeSubscribe(storeSubscribe: StoreMutationSubscriptionCallback);
+    constructor(store: PiniaStore, options: AnyObject, debug?: boolean, customConsole?: Console);
+    /**
+     * Add property to state
+     * @param name
+     * @param value
+     */
+    addToState(name: string, value?: StatePropertyValue): void;
+    addSubscription(pluginName: string, subscription: PluginSubscriberInterface, options?: {
+        subscriptionOptions?: StoreOptions;
+        stores?: PiniaStore[];
+    }): void;
+    /**
+     * Create and return a class instance
+     * @param store
+     * @param options
+     * @param debug
+     * @returns
+     */
+    static customizeStore<Instance extends Store>(store: PiniaStore, options: AnyObject, debug?: boolean, customConsole?: Console): Instance | undefined;
+    hasDeniedFirstChar(property: string): boolean;
+    protected static hasRequiredKeys(options: AnyObject): boolean;
+    getOption(optionName: keyof StoreOptions): import("../types").StoreOptionsPropertyValue;
+    getStatePropertyValue(propertyName: string): any;
+    getSubscriptions(): PluginSubscriptions | undefined;
+    getValue(value: any): any;
+    isOptionApi(): boolean;
+    stateHas(property: string): boolean;
+    storeHas(property: string): boolean;
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,4 @@
+export { default as PluginSubscriber } from '../plugins/pluginSubscriber';
+export { default as Store } from '../core/Store';
+export { CustomConsole } from '../system/log';
+export { isEmpty } from '../utils/validation';

package/dist/helpers.js

@@ -0,0 +1,7 @@
+import { C as a, a as r, S as e, i } from "./chunks/index-ByASkYCc.js";
+export {
+  a as CustomConsole,
+  r as PluginSubscriber,
+  e as Store,
+  i as isEmpty
+};

package/dist/lib/main.d.ts

@@ -0,0 +1,14 @@
+import PluginSubscriber from '../plugins/pluginSubscriber';
+import PluginSubscription from '../plugins/pluginSubscription';
+import Store from '../core/Store';
+export { createPlugin } from "../plugins/createPlugin";
+export { createHydrationPlugin } from "../plugins/createHydrationPlugin";
+export type { AnyObject, Console, CustomStore, DefineAStoreSetupContext, DefineAStoreSetupExtensions, EmptyExtensions, PluginExecutionEnvironment, PluginExecutionOptions, PluginHydrationScheduler, PluginHydrationTiming, PluginRuntimeEnvironment, PluginStoreOptions, PluginSubscriptionOptions, PluginSubscriberInterface, PluginSubscriptionDefinition, PluginSubscriptions, StatePropertyValue, StoreOptions, StoreOptionsPropertyValue, StoreMutationSubscription, StoreMutationSubscriptionCallback, StoreOnActionCallbackParameters, StoreOnActionSubscription, StoreOnActionSubscriptionCallback, NativePiniaSubscription, NativePiniaSubscriptionReturn, SearchCollectionCriteria, LogType, StyleDefinition, StyleDefinitionKeys, StyleDefinitions, ConsoleStyleDefinition, ConsoleStyleDefinitionKeys, ConsoleStyleDefinitions, PartialList, ListTypes, ListTypesMap, List } from "../types";
+export type { StoreMutationSubscriptionReturn, StoreOnActionSubscriptionReturn } from "../types/plugin";
+export { defineAStore, defineAStoreCtx, getDefineAStoreSetupContext, getEnhancedStore, getExtendingStore, setEnhancedStore } from "../utils/store";
+export { CustomConsole } from "../system/log";
+export { isEmpty } from "../utils/validation";
+export { pluginName as PLUGIN_NAME } from "../utils/constantes";
+export { PluginSubscriber };
+export { PluginSubscription };
+export { Store };