@atoapayments/pinia-store-lifecycle-manager 0.0.1

package/README.md

@@ -0,0 +1,320 @@
+# Pinia Store Lifecycle Manager
+
+A robust Pinia plugin designed to manage store lifecycles seamlessly, including state resets and refreshes. Enhance your Vue applications with streamlined state management tailored for dynamic development needs.
+
+## Table of Contents
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Setup](#basic-setup)
+  - [Advanced Configuration](#advanced-configuration)
+- [Features](#features)
+- [Use Cases](#use-cases)
+- [API Reference](#api-reference)
+- [Why Choose Pinia Store Lifecycle Manager](#why-choose-pinia-store-lifecycle-manager)
+- [License](#license)
+
+## Installation
+
+You can install the Pinia Store Lifecycle Manager using npm or Yarn:
+
+```bash
+npm install @atoapayments/pinia-store-lifecycle-manager
+# or
+yarn add @atoapayments/pinia-store-lifecycle-manager
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+//vue
+import { createPinia } from "pinia";
+import { PiniaStoreLifecycleManager } from "pinia-store-lifecycle-manager";
+
+const pinia = createPinia();
+pinia.use((context) => {
+  PiniaStoreLifecycleManager(context, (lifecycleEvents) => {
+    // Register your lifecycle event handlers here
+    // For example:
+    // lifecycleEvents.reset();
+    // lifecycleEvents.reconfigure();
+    // lifecycleEvents.refresh({ mode: 'full' });
+  });
+});
+```
+
+#### Nuxt
+
+```typescript
+// \plugin\pinia-store-lifecycle-manager.ts
+import type { Pinia } from "pinia";
+import { PiniaStoreLifecycleManager } from "pinia-store-lifecycle-manager";
+
+export default defineNuxtPlugin(({ $pinia }) => {
+  ($pinia as Pinia).use((pluginContext) => {
+    return PiniaStoreLifecycleManager(
+      pluginContext,
+      (lifecycleEvents) => {
+        // Use event listeners of your choice
+        const { $listen } = useNuxtApp();
+
+        // Register event listeners
+        $listen("user:logOut", () => {
+          lifecycleEvents.reset();
+        });
+        $listen("user:switchProfile", () => {
+          // Reset the store and perform a full refresh when switching profile
+          lifecycleEvents.reset();
+          lifecycleEvents.refresh({
+            mode: "full",
+            includeResetOnlyActions: true,
+          });
+        });
+        $listen("user:anyEvent", () => {
+          // Reconfigure the store and perform a partial refresh
+          lifecycleEvents.reconfigure();
+          lifecycleEvents.refresh({ mode: "partial" });
+        });
+      },
+      {
+        enableDebugLogs: __DEV__,
+      }
+    );
+  });
+});
+
+```
+
+### Advanced Configuration
+
+```typescript
+import { createPinia } from "pinia";
+import { PiniaStoreLifecycleManager } from "pinia-store-lifecycle-manager";
+
+const pinia = createPinia();
+pinia.use((context) => {
+  PiniaStoreLifecycleManager(
+    context,
+    (lifecycleEvents) => {
+      // Define custom lifecycle event handlers
+    },
+    {
+      enableDebugLogs: true,
+      enableSSR: false,
+      disableAutoRegister: false,
+    }
+  );
+});
+```
+
+## Features
+
+- **State Reset:** Easily reset the store to its initial state.
+- **Reconfiguration:** Update multiple store properties simultaneously.
+- **Data Refresh:** Refresh store data by invoking specified actions.
+- **Debug Logging:** Enable detailed logging for lifecycle events and actions.
+- **SSR Support:** Compatible with server-side rendering setups.
+
+## Use Cases
+
+- **User Authentication:** Reset store states upon user logout.
+- **Dynamic Configuration:** Reconfigure store settings based on different environments.
+- **Real-time Data Management:** Refresh store data in response to real-time events.
+- **State Management Optimization:** Streamline complex state transitions.
+
+## API Reference
+
+### Lifecycle Options
+
+```typescript
+interface DefineStoreOptionsBase<S extends StateTree, Store> {
+  lifecycleOptions?: {
+    clean?: CleanOptions<Store> | CleanFunction<Store> | (() => CleanOptions<Store> | void);
+    reConfigure?: ReconfigureOptions<Store> | ReconfigureFunction<Store> | (() => ReconfigureOptions<Store> | void);
+    refresh?: RefreshOptions<Store> | RefreshFunction<Store> | (() => RefreshOptions<Store> | void);
+    disableListener?: boolean;
+  };
+}
+```
+
+#### Clean and Reconfigure
+
+Both `clean` and `reConfigure` can be defined as an object, a function that takes the store as an argument, or a function that takes no arguments:
+
+```typescript
+// As an object
+clean: {
+  user: null,
+  token: '',
+  isAuthenticated: false
+}
+
+// As a function with store argument
+clean: (store) => ({
+  user: null,
+  token: '',
+  isAuthenticated: false
+})
+
+// As a function without arguments
+clean: () => ({
+  user: null,
+  token: '',
+  isAuthenticated: false
+})
+
+// Reconfigure examples (similar pattern)
+reConfigure: {
+  theme: 'dark',
+  language: 'en'
+}
+
+reConfigure: (store) => ({
+  theme: 'dark',
+  language: 'en'
+})
+
+reConfigure: () => ({
+  theme: 'dark',
+  language: 'en'
+})
+```
+
+#### Refresh
+
+The `refresh` option can be defined as an object, a function that takes the store as an argument, or a function that takes no arguments:
+
+```typescript
+// As an object
+refresh: {
+  fetchUserProfile: { params: [], resetOnly: false },
+  fetchUserSettings: { params: [], resetOnly: true }
+}
+
+// As a function with store argument
+refresh: (store) => ({
+  fetchUserProfile: { params: [] },
+  fetchUserSettings: { params: [], resetOnly: true }
+})
+
+// As a function without arguments
+refresh: () => ({
+  fetchUserProfile: { params: [] },
+  fetchUserSettings: { params: [], resetOnly: true }
+})
+```
+
+### Refresh Options
+
+When calling the `refresh` function, you can specify options:
+
+```typescript
+type PiniaStoreLifecycleManagerRefreshOptions = {
+  mode: "full" | "partial";
+  includeResetOnlyActions?: boolean;
+};
+
+ /**
+  * Use 'full' mode when you need to refresh all data, including reset-only actions.
+  * This is useful for major state changes, like switching user accounts.
+  *
+  * Use 'partial' mode for routine updates or when switching to a related context
+  * that doesn't require a full data refresh.
+  */
+ lifecycleEvents.refresh({ mode: 'full', includeResetOnlyActions: true });
+```
+
+#### Property Exclusions
+
+The `clean`, `reConfigure`, and `refresh` options automatically exclude certain properties to ensure safe state management:
+
+- Pinia's internal properties (starting with `$`)
+- Conventionally private properties (starting with `_`)
+- Non-writable computed properties
+- State properties defined in the store
+
+This ensures that only appropriate properties are modified during lifecycle operations.
+
+#### Clean and Reconfigure
+
+Both `clean` and `reConfigure` can be defined as either an object or a function:
+
+```typescript
+// As an object
+clean: {
+  user: null,
+  token: '',
+  isAuthenticated: false
+}
+
+// As a function
+clean: (store) => ({
+  previousUserId: store.user?.id,
+  user: null,
+  token: '',
+  isAuthenticated: false
+})
+
+// Reconfigure example
+reConfigure: () => ({
+  theme: 'dark',
+  language: 'en',
+})
+```
+
+#### Refresh
+
+The `refresh` option can be defined as either an object or a function:
+
+```typescript
+// As an object
+refresh: {
+  fetchUserProfile: { params: ['userId'] },
+  fetchUserSettings: { params: [], resetOnly: true }
+}
+
+// As a function
+refresh: (store) => ({
+  fetchUserProfile: { params: [store.userId] },
+  fetchUserSettings: { params: [], resetOnly: true }
+})
+```
+
+#### Property Inclusions and Exclusions
+
+The `clean` and `reConfigure` options include:
+- Data variables (including list types)
+- Writable computed properties
+
+They automatically exclude:
+- Pinia's internal properties (starting with `$`)
+- Conventionally private properties (starting with `_`)
+- Non-writable computed properties
+- Function properties
+
+This ensures that only appropriate properties are modified during lifecycle operations while including all relevant data types.
+
+#### Readonly Properties
+
+The `clean` and `reConfigure` operations automatically skip readonly properties to prevent errors:
+
+- If a property is readonly or a non-writable computed property, it will not be modified during reset or reconfigure operations.
+- When debug logs are enabled, a warning with a 🚫 emoji will be issued for each skipped non-writable property, reminding developers to avoid including such properties in clean or reConfigure options.
+
+This ensures that only modifiable properties are affected by lifecycle operations, maintaining the integrity of readonly state and computed properties.
+
+> **Open Issue / Upcoming Enhancement:** 
+> We are aware that non-writable properties can currently be included in `clean` and `reConfigure` options, which is not ideal. We plan to enhance the type system to prevent this in a future update. For now, we have a runtime safety check that skips these properties and issues a warning when encountered. Please avoid including non-writable properties in your `clean` and `reConfigure` options to ensure smooth operation and prepare for future updates.
+
+## Why Choose Pinia Store Lifecycle Manager
+
+- **Seamless Integration:** Easily integrates with existing Pinia stores.
+- **Highly Customizable:** Offers flexible configuration options.
+- **Performance Optimized:** Ensures minimal overhead in state management operations.
+- **Comprehensive Logging:** Facilitates debugging through optional debug logs.
+- **Active Maintenance:** Regular updates and community support.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,242 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  PiniaStoreLifecycleManager: () => PiniaStoreLifecycleManager
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/utils.ts
+function debugLog(storeId, message, data) {
+  console.log(`\u{1F504} [${storeId}] ${message}`, data ? data : "");
+}
+function devWarnNonWritable(storeId, propertyName) {
+  console.warn(
+    `\u{1F504} \u{1F6AB} [${storeId}] Skipped non-writable property '${propertyName}'. Avoid including non-writable computed properties in clean or reConfigure options.`
+  );
+}
+function devError(storeId, message, error) {
+  console.error(
+    `\u{1F504} [PiniaStoreLifecycleManager] (${storeId}) ${message}`,
+    error
+  );
+}
+
+// src/plugin.ts
+var import_vue = require("vue");
+var PiniaStoreLifecycleManager = ({ options, store }, lifecycleEventHandler, pluginOptions) => {
+  if ((typeof window === "undefined" || typeof document === "undefined") && !pluginOptions?.enableSSR) {
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(
+        store.$id,
+        "PiniaStoreLifecycleManager is not running on the client side."
+      );
+    }
+    return;
+  }
+  if (!store.$state.hasOwnProperty("hasStoreLifecycleManagerListener") && (!pluginOptions?.disableAutoRegister && options.lifecycleOptions?.disableListener !== true || pluginOptions?.disableAutoRegister && options.lifecycleOptions?.disableListener === false)) {
+    const _hasStoreLifecycleManagerListener = (0, import_vue.ref)(true);
+    store.$state._hasStoreLifecycleManagerListener = _hasStoreLifecycleManagerListener;
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(store.$id, "Attaching PiniaStoreLifecycleManager listener");
+    }
+    lifecycleEventHandler({
+      reset: resetState,
+      reconfigure: reconfigureState,
+      refresh: refreshState
+    });
+    store._hasStoreLifecycleManagerListener = (0, import_vue.toRef)(
+      store.$state,
+      "_hasStoreLifecycleManagerListener"
+    );
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(
+        store.$id,
+        "PiniaStoreLifecycleManager listener attached successfully"
+      );
+    }
+  } else {
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(
+        store.$id,
+        "Skipping PiniaStoreLifecycleManager listener attachment",
+        {
+          reason: store.$state.hasStoreLifecycleManagerListener ? "Already attached" : "Disabled by configuration"
+        }
+      );
+    }
+  }
+  function resetState() {
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(
+        store.$id,
+        "Initiating reset state operation",
+        options.lifecycleOptions?.clean
+      );
+    }
+    if (!options.lifecycleOptions?.clean) {
+      if (pluginOptions?.enableDebugLogs) {
+        debugLog(
+          store.$id,
+          "Reset state operation skipped: No clean options defined"
+        );
+      }
+      return;
+    }
+    const cleanOptions = typeof options.lifecycleOptions.clean === "function" ? options.lifecycleOptions.clean.length > 0 ? options.lifecycleOptions.clean(store) : options.lifecycleOptions.clean() : options.lifecycleOptions.clean;
+    if (cleanOptions) {
+      Object.keys(cleanOptions).forEach((key) => {
+        if ((0, import_vue.isReadonly)(store[key])) {
+          if (pluginOptions?.enableDebugLogs) {
+            devWarnNonWritable(store.$id, key);
+          }
+          return;
+        }
+        const oldValue = store[key];
+        try {
+          store[key] = cleanOptions[key];
+          if (pluginOptions?.enableDebugLogs) {
+            debugLog(store.$id, `Reset state: Updated '${key}'`, {
+              oldValue,
+              newValue: store[key]
+            });
+          }
+        } catch (error) {
+          devError(store.$id, `Failed to reset state for key '${key}'`, error);
+        }
+      });
+    }
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(store.$id, "Reset state operation completed");
+    }
+  }
+  function reconfigureState() {
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(
+        store.$id,
+        "Initiating reconfigure state operation",
+        options.lifecycleOptions?.reConfigure
+      );
+    }
+    if (!options.lifecycleOptions?.reConfigure) {
+      if (pluginOptions?.enableDebugLogs) {
+        debugLog(
+          store.$id,
+          "Reconfigure state operation skipped: No reconfigure options defined"
+        );
+      }
+      return;
+    }
+    const reconfigureOptions = typeof options.lifecycleOptions.reConfigure === "function" ? options.lifecycleOptions.reConfigure.length > 0 ? options.lifecycleOptions.reConfigure(store) : options.lifecycleOptions.reConfigure() : options.lifecycleOptions.reConfigure;
+    if (reconfigureOptions) {
+      Object.keys(reconfigureOptions).forEach((key) => {
+        if ((0, import_vue.isReadonly)(store[key])) {
+          if (pluginOptions?.enableDebugLogs) {
+            devWarnNonWritable(store.$id, key);
+          }
+          return;
+        }
+        const oldValue = store[key];
+        try {
+          store[key] = reconfigureOptions[key];
+          if (pluginOptions?.enableDebugLogs) {
+            debugLog(store.$id, `Reconfigure state: Updated '${key}'`, {
+              oldValue,
+              newValue: store[key]
+            });
+          }
+        } catch (error) {
+          devError(
+            store.$id,
+            `Failed to reconfigure state for key '${key}'`,
+            error
+          );
+        }
+      });
+    }
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(store.$id, "Reconfigure state operation completed");
+    }
+  }
+  function refreshState(refreshOptions) {
+    const { mode, includeResetOnlyActions = false } = refreshOptions;
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(store.$id, "Initiating refresh action", {
+        mode,
+        includeResetOnlyActions,
+        refreshOptions: options.lifecycleOptions?.refresh
+      });
+    }
+    if (!options.lifecycleOptions?.refresh) {
+      if (pluginOptions?.enableDebugLogs) {
+        debugLog(
+          store.$id,
+          "Refresh action skipped: No refresh options defined"
+        );
+      }
+      return;
+    }
+    const refreshResult = typeof options.lifecycleOptions.refresh === "function" ? options.lifecycleOptions.refresh.length > 0 ? options.lifecycleOptions.refresh(store) : options.lifecycleOptions.refresh() : options.lifecycleOptions.refresh;
+    if (refreshResult && typeof refreshResult === "object") {
+      const filteredResult = Object.fromEntries(
+        Object.entries(refreshResult).filter(([key, value]) => {
+          const actionResetOnly = value?.resetOnly ?? false;
+          const shouldInclude = mode === "full" ? !includeResetOnlyActions || includeResetOnlyActions && actionResetOnly : !actionResetOnly;
+          if (pluginOptions?.enableDebugLogs) {
+            debugLog(store.$id, `Filtering refresh action: ${key}`, {
+              shouldInclude,
+              mode,
+              includeResetOnlyActions,
+              actionResetOnly
+            });
+          }
+          return shouldInclude;
+        })
+      );
+      Object.entries(filteredResult).forEach(([key, value]) => {
+        const actionKey = key;
+        const action = store[actionKey];
+        if (action) {
+          const params = value?.params ?? [];
+          if (pluginOptions?.enableDebugLogs) {
+            debugLog(store.$id, `Executing refresh action: ${key}`, { params });
+          }
+          action(...params);
+        } else {
+          if (pluginOptions?.enableDebugLogs) {
+            debugLog(store.$id, `Skipped non-existent refresh action: ${key}`);
+          }
+        }
+      });
+    } else {
+      if (pluginOptions?.enableDebugLogs) {
+        debugLog(store.$id, "Refresh action skipped: Invalid refresh result");
+      }
+    }
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(store.$id, "Refresh action completed");
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PiniaStoreLifecycleManager
+});

package/dist/index.d.cts

@@ -0,0 +1,130 @@
+import { StoreState, StoreGetters, StoreActions, PiniaPluginContext } from 'pinia';
+import { Ref } from 'vue';
+
+/**
+ * Represents a map of action parameters for a store.
+ * Each key is an action name, and the value contains the action's parameters and a flag indicating if it's reset-only.
+ */
+type ActionParamsMap<T> = {
+    [K in keyof T]: {
+        params: T[K] extends (...args: infer P) => unknown ? P : [];
+        resetOnly?: boolean;
+    };
+};
+/**
+ * Options for refreshing a Pinia store using the lifecycle manager.
+ */
+type PiniaStoreLifecycleManagerRefreshOptions = {
+    /** The refresh mode: 'full' refreshes all actions, 'partial' skips reset-only actions */
+    mode: "full" | "partial";
+    /** Whether to include reset-only actions in 'full' mode */
+    includeResetOnlyActions?: boolean;
+};
+/**
+ * Represents the options for cleaning a store's state.
+ * Omits the internal '_hasStoreLifecycleManagerListener' property.
+ */
+type CleanOptions<Store> = Partial<Omit<StoreState<Store> & StoreGetters<Store>, "_hasStoreLifecycleManagerListener">>;
+/**
+ * Represents the options for reconfiguring a store's state.
+ * Omits the internal '_hasStoreLifecycleManagerListener' property.
+ */
+type ReconfigureOptions<Store> = Partial<Omit<StoreState<Store> & StoreGetters<Store>, "_hasStoreLifecycleManagerListener">>;
+/**
+ * A function that takes a store and returns clean options or void.
+ */
+type CleanFunction<Store> = (store: Omit<Store, `$${string}` | `_customProperties` | "_hasStoreLifecycleManagerListener">) => CleanOptions<Store> | void;
+/**
+ * A function that takes a store and returns reconfigure options or void.
+ */
+type ReconfigureFunction<Store> = (store: Omit<Store, `$${string}` | `_customProperties` | "_hasStoreLifecycleManagerListener">) => ReconfigureOptions<Store> | void;
+/**
+ * Represents the options for refreshing a store's actions.
+ */
+type RefreshOptions<Store> = Partial<ActionParamsMap<StoreActions<Store>>>;
+/**
+ * A function that takes a store and returns refresh options or void.
+ */
+type RefreshFunction<Store> = (store: Omit<Store, `$${string}` | `_customProperties` | "_hasStoreLifecycleManagerListener">) => RefreshOptions<Store> | void;
+declare module "pinia" {
+    interface PiniaCustomProperties {
+        _hasStoreLifecycleManagerListener?: Ref<boolean>;
+    }
+    interface DefineStoreOptionsBase<S extends StateTree, Store> {
+        lifecycleOptions?: {
+            /**
+             * Defines properties to be reset during a hard-reset operation.
+             */
+            clean?: CleanOptions<Store> | CleanFunction<Store> | (() => CleanOptions<Store> | void);
+            /**
+             * Defines properties to be reset during a soft-reset (reconfigure) operation.
+             */
+            reConfigure?: ReconfigureOptions<Store> | ReconfigureFunction<Store> | (() => ReconfigureOptions<Store> | void);
+            /**
+             * Defines actions to be called during a refresh operation.
+             * @param v - The store instance with certain properties omitted.
+             * @returns Partial map of action parameters.
+             */
+            refresh?: RefreshOptions<Store> | RefreshFunction<Store> | (() => RefreshOptions<Store> | void);
+            /**
+             * Controls the automatic registration of the listener.
+             * - For automatic registration: set to true to disable listener registration.
+             * - For manual registration: set to false to enable listener registration.
+             */
+            disableListener?: boolean;
+        };
+    }
+}
+
+/**
+ * PiniaStoreLifecycleManager: A Pinia plugin for managing store lifecycle, including state resets and refreshes.
+ *
+ * @param context - The Pinia plugin context.
+ * @param lifecycleEventHandler - The listener function to be called for various lifecycle events.
+ * @param pluginOptions - Configuration options for the plugin.
+ */
+declare const PiniaStoreLifecycleManager: ({ options, store }: PiniaPluginContext, lifecycleEventHandler: (events: {
+    /**
+     * Resets the store to its initial state.
+     * Use this when you need to completely clear the store, e.g., on user logout.
+     */
+    reset: () => void;
+    /**
+     * Reconfigures the store with new values.
+     * Use this when you need to update multiple store properties at once,
+     * e.g., when switching to a different configuration or context.
+     */
+    reconfigure: () => void;
+    /**
+     * Refreshes the store data by calling specified actions.
+     * @param options RefreshOptions to control the refresh behavior.
+     *
+     * Use 'full' mode when you need to refresh all data, including reset-only actions.
+     * This is useful for major state changes, like switching user accounts.
+     *
+     * Use 'partial' mode for routine updates or when switching to a related context
+     * that doesn't require a full data refresh.
+     */
+    refresh: (options: PiniaStoreLifecycleManagerRefreshOptions) => void;
+}) => void, pluginOptions?: {
+    /**
+     * Disables the automatic registration of lifecycle listeners.
+     * Set to true to manually manage lifecycle listener registration.
+     */
+    disableAutoRegister?: boolean;
+    /**
+     * Enables debug logging for the PiniaStoreLifecycleManager.
+     * Set to true to output debug information to the console.
+     */
+    enableDebugLogs?: boolean;
+    /**
+     * Enables server-side rendering support for the PiniaStoreLifecycleManager.
+     * Set to true if the application uses SSR to ensure proper lifecycle management.
+     *
+     * **Note:** Only enable if you are sure that your listener works perfectly in SSR,
+     * as this plugin only assigns the listener once either on the server or on the client.
+     */
+    enableSSR?: boolean;
+}) => void;
+
+export { type ActionParamsMap, type CleanFunction, type CleanOptions, PiniaStoreLifecycleManager, type PiniaStoreLifecycleManagerRefreshOptions, type ReconfigureFunction, type ReconfigureOptions, type RefreshFunction, type RefreshOptions };

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+import { StoreState, StoreGetters, StoreActions, PiniaPluginContext } from 'pinia';
+import { Ref } from 'vue';
+
+/**
+ * Represents a map of action parameters for a store.
+ * Each key is an action name, and the value contains the action's parameters and a flag indicating if it's reset-only.
+ */
+type ActionParamsMap<T> = {
+    [K in keyof T]: {
+        params: T[K] extends (...args: infer P) => unknown ? P : [];
+        resetOnly?: boolean;
+    };
+};
+/**
+ * Options for refreshing a Pinia store using the lifecycle manager.
+ */
+type PiniaStoreLifecycleManagerRefreshOptions = {
+    /** The refresh mode: 'full' refreshes all actions, 'partial' skips reset-only actions */
+    mode: "full" | "partial";
+    /** Whether to include reset-only actions in 'full' mode */
+    includeResetOnlyActions?: boolean;
+};
+/**
+ * Represents the options for cleaning a store's state.
+ * Omits the internal '_hasStoreLifecycleManagerListener' property.
+ */
+type CleanOptions<Store> = Partial<Omit<StoreState<Store> & StoreGetters<Store>, "_hasStoreLifecycleManagerListener">>;
+/**
+ * Represents the options for reconfiguring a store's state.
+ * Omits the internal '_hasStoreLifecycleManagerListener' property.
+ */
+type ReconfigureOptions<Store> = Partial<Omit<StoreState<Store> & StoreGetters<Store>, "_hasStoreLifecycleManagerListener">>;
+/**
+ * A function that takes a store and returns clean options or void.
+ */
+type CleanFunction<Store> = (store: Omit<Store, `$${string}` | `_customProperties` | "_hasStoreLifecycleManagerListener">) => CleanOptions<Store> | void;
+/**
+ * A function that takes a store and returns reconfigure options or void.
+ */
+type ReconfigureFunction<Store> = (store: Omit<Store, `$${string}` | `_customProperties` | "_hasStoreLifecycleManagerListener">) => ReconfigureOptions<Store> | void;
+/**
+ * Represents the options for refreshing a store's actions.
+ */
+type RefreshOptions<Store> = Partial<ActionParamsMap<StoreActions<Store>>>;
+/**
+ * A function that takes a store and returns refresh options or void.
+ */
+type RefreshFunction<Store> = (store: Omit<Store, `$${string}` | `_customProperties` | "_hasStoreLifecycleManagerListener">) => RefreshOptions<Store> | void;
+declare module "pinia" {
+    interface PiniaCustomProperties {
+        _hasStoreLifecycleManagerListener?: Ref<boolean>;
+    }
+    interface DefineStoreOptionsBase<S extends StateTree, Store> {
+        lifecycleOptions?: {
+            /**
+             * Defines properties to be reset during a hard-reset operation.
+             */
+            clean?: CleanOptions<Store> | CleanFunction<Store> | (() => CleanOptions<Store> | void);
+            /**
+             * Defines properties to be reset during a soft-reset (reconfigure) operation.
+             */
+            reConfigure?: ReconfigureOptions<Store> | ReconfigureFunction<Store> | (() => ReconfigureOptions<Store> | void);
+            /**
+             * Defines actions to be called during a refresh operation.
+             * @param v - The store instance with certain properties omitted.
+             * @returns Partial map of action parameters.
+             */
+            refresh?: RefreshOptions<Store> | RefreshFunction<Store> | (() => RefreshOptions<Store> | void);
+            /**
+             * Controls the automatic registration of the listener.
+             * - For automatic registration: set to true to disable listener registration.
+             * - For manual registration: set to false to enable listener registration.
+             */
+            disableListener?: boolean;
+        };
+    }
+}
+
+/**
+ * PiniaStoreLifecycleManager: A Pinia plugin for managing store lifecycle, including state resets and refreshes.
+ *
+ * @param context - The Pinia plugin context.
+ * @param lifecycleEventHandler - The listener function to be called for various lifecycle events.
+ * @param pluginOptions - Configuration options for the plugin.
+ */
+declare const PiniaStoreLifecycleManager: ({ options, store }: PiniaPluginContext, lifecycleEventHandler: (events: {
+    /**
+     * Resets the store to its initial state.
+     * Use this when you need to completely clear the store, e.g., on user logout.
+     */
+    reset: () => void;
+    /**
+     * Reconfigures the store with new values.
+     * Use this when you need to update multiple store properties at once,
+     * e.g., when switching to a different configuration or context.
+     */
+    reconfigure: () => void;
+    /**
+     * Refreshes the store data by calling specified actions.
+     * @param options RefreshOptions to control the refresh behavior.
+     *
+     * Use 'full' mode when you need to refresh all data, including reset-only actions.
+     * This is useful for major state changes, like switching user accounts.
+     *
+     * Use 'partial' mode for routine updates or when switching to a related context
+     * that doesn't require a full data refresh.
+     */
+    refresh: (options: PiniaStoreLifecycleManagerRefreshOptions) => void;
+}) => void, pluginOptions?: {
+    /**
+     * Disables the automatic registration of lifecycle listeners.
+     * Set to true to manually manage lifecycle listener registration.
+     */
+    disableAutoRegister?: boolean;
+    /**
+     * Enables debug logging for the PiniaStoreLifecycleManager.
+     * Set to true to output debug information to the console.
+     */
+    enableDebugLogs?: boolean;
+    /**
+     * Enables server-side rendering support for the PiniaStoreLifecycleManager.
+     * Set to true if the application uses SSR to ensure proper lifecycle management.
+     *
+     * **Note:** Only enable if you are sure that your listener works perfectly in SSR,
+     * as this plugin only assigns the listener once either on the server or on the client.
+     */
+    enableSSR?: boolean;
+}) => void;
+
+export { type ActionParamsMap, type CleanFunction, type CleanOptions, PiniaStoreLifecycleManager, type PiniaStoreLifecycleManagerRefreshOptions, type ReconfigureFunction, type ReconfigureOptions, type RefreshFunction, type RefreshOptions };

package/dist/index.js

@@ -0,0 +1,215 @@
+// src/utils.ts
+function debugLog(storeId, message, data) {
+  console.log(`\u{1F504} [${storeId}] ${message}`, data ? data : "");
+}
+function devWarnNonWritable(storeId, propertyName) {
+  console.warn(
+    `\u{1F504} \u{1F6AB} [${storeId}] Skipped non-writable property '${propertyName}'. Avoid including non-writable computed properties in clean or reConfigure options.`
+  );
+}
+function devError(storeId, message, error) {
+  console.error(
+    `\u{1F504} [PiniaStoreLifecycleManager] (${storeId}) ${message}`,
+    error
+  );
+}
+
+// src/plugin.ts
+import { ref, toRef, isReadonly } from "vue";
+var PiniaStoreLifecycleManager = ({ options, store }, lifecycleEventHandler, pluginOptions) => {
+  if ((typeof window === "undefined" || typeof document === "undefined") && !pluginOptions?.enableSSR) {
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(
+        store.$id,
+        "PiniaStoreLifecycleManager is not running on the client side."
+      );
+    }
+    return;
+  }
+  if (!store.$state.hasOwnProperty("hasStoreLifecycleManagerListener") && (!pluginOptions?.disableAutoRegister && options.lifecycleOptions?.disableListener !== true || pluginOptions?.disableAutoRegister && options.lifecycleOptions?.disableListener === false)) {
+    const _hasStoreLifecycleManagerListener = ref(true);
+    store.$state._hasStoreLifecycleManagerListener = _hasStoreLifecycleManagerListener;
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(store.$id, "Attaching PiniaStoreLifecycleManager listener");
+    }
+    lifecycleEventHandler({
+      reset: resetState,
+      reconfigure: reconfigureState,
+      refresh: refreshState
+    });
+    store._hasStoreLifecycleManagerListener = toRef(
+      store.$state,
+      "_hasStoreLifecycleManagerListener"
+    );
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(
+        store.$id,
+        "PiniaStoreLifecycleManager listener attached successfully"
+      );
+    }
+  } else {
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(
+        store.$id,
+        "Skipping PiniaStoreLifecycleManager listener attachment",
+        {
+          reason: store.$state.hasStoreLifecycleManagerListener ? "Already attached" : "Disabled by configuration"
+        }
+      );
+    }
+  }
+  function resetState() {
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(
+        store.$id,
+        "Initiating reset state operation",
+        options.lifecycleOptions?.clean
+      );
+    }
+    if (!options.lifecycleOptions?.clean) {
+      if (pluginOptions?.enableDebugLogs) {
+        debugLog(
+          store.$id,
+          "Reset state operation skipped: No clean options defined"
+        );
+      }
+      return;
+    }
+    const cleanOptions = typeof options.lifecycleOptions.clean === "function" ? options.lifecycleOptions.clean.length > 0 ? options.lifecycleOptions.clean(store) : options.lifecycleOptions.clean() : options.lifecycleOptions.clean;
+    if (cleanOptions) {
+      Object.keys(cleanOptions).forEach((key) => {
+        if (isReadonly(store[key])) {
+          if (pluginOptions?.enableDebugLogs) {
+            devWarnNonWritable(store.$id, key);
+          }
+          return;
+        }
+        const oldValue = store[key];
+        try {
+          store[key] = cleanOptions[key];
+          if (pluginOptions?.enableDebugLogs) {
+            debugLog(store.$id, `Reset state: Updated '${key}'`, {
+              oldValue,
+              newValue: store[key]
+            });
+          }
+        } catch (error) {
+          devError(store.$id, `Failed to reset state for key '${key}'`, error);
+        }
+      });
+    }
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(store.$id, "Reset state operation completed");
+    }
+  }
+  function reconfigureState() {
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(
+        store.$id,
+        "Initiating reconfigure state operation",
+        options.lifecycleOptions?.reConfigure
+      );
+    }
+    if (!options.lifecycleOptions?.reConfigure) {
+      if (pluginOptions?.enableDebugLogs) {
+        debugLog(
+          store.$id,
+          "Reconfigure state operation skipped: No reconfigure options defined"
+        );
+      }
+      return;
+    }
+    const reconfigureOptions = typeof options.lifecycleOptions.reConfigure === "function" ? options.lifecycleOptions.reConfigure.length > 0 ? options.lifecycleOptions.reConfigure(store) : options.lifecycleOptions.reConfigure() : options.lifecycleOptions.reConfigure;
+    if (reconfigureOptions) {
+      Object.keys(reconfigureOptions).forEach((key) => {
+        if (isReadonly(store[key])) {
+          if (pluginOptions?.enableDebugLogs) {
+            devWarnNonWritable(store.$id, key);
+          }
+          return;
+        }
+        const oldValue = store[key];
+        try {
+          store[key] = reconfigureOptions[key];
+          if (pluginOptions?.enableDebugLogs) {
+            debugLog(store.$id, `Reconfigure state: Updated '${key}'`, {
+              oldValue,
+              newValue: store[key]
+            });
+          }
+        } catch (error) {
+          devError(
+            store.$id,
+            `Failed to reconfigure state for key '${key}'`,
+            error
+          );
+        }
+      });
+    }
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(store.$id, "Reconfigure state operation completed");
+    }
+  }
+  function refreshState(refreshOptions) {
+    const { mode, includeResetOnlyActions = false } = refreshOptions;
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(store.$id, "Initiating refresh action", {
+        mode,
+        includeResetOnlyActions,
+        refreshOptions: options.lifecycleOptions?.refresh
+      });
+    }
+    if (!options.lifecycleOptions?.refresh) {
+      if (pluginOptions?.enableDebugLogs) {
+        debugLog(
+          store.$id,
+          "Refresh action skipped: No refresh options defined"
+        );
+      }
+      return;
+    }
+    const refreshResult = typeof options.lifecycleOptions.refresh === "function" ? options.lifecycleOptions.refresh.length > 0 ? options.lifecycleOptions.refresh(store) : options.lifecycleOptions.refresh() : options.lifecycleOptions.refresh;
+    if (refreshResult && typeof refreshResult === "object") {
+      const filteredResult = Object.fromEntries(
+        Object.entries(refreshResult).filter(([key, value]) => {
+          const actionResetOnly = value?.resetOnly ?? false;
+          const shouldInclude = mode === "full" ? !includeResetOnlyActions || includeResetOnlyActions && actionResetOnly : !actionResetOnly;
+          if (pluginOptions?.enableDebugLogs) {
+            debugLog(store.$id, `Filtering refresh action: ${key}`, {
+              shouldInclude,
+              mode,
+              includeResetOnlyActions,
+              actionResetOnly
+            });
+          }
+          return shouldInclude;
+        })
+      );
+      Object.entries(filteredResult).forEach(([key, value]) => {
+        const actionKey = key;
+        const action = store[actionKey];
+        if (action) {
+          const params = value?.params ?? [];
+          if (pluginOptions?.enableDebugLogs) {
+            debugLog(store.$id, `Executing refresh action: ${key}`, { params });
+          }
+          action(...params);
+        } else {
+          if (pluginOptions?.enableDebugLogs) {
+            debugLog(store.$id, `Skipped non-existent refresh action: ${key}`);
+          }
+        }
+      });
+    } else {
+      if (pluginOptions?.enableDebugLogs) {
+        debugLog(store.$id, "Refresh action skipped: Invalid refresh result");
+      }
+    }
+    if (pluginOptions?.enableDebugLogs) {
+      debugLog(store.$id, "Refresh action completed");
+    }
+  }
+};
+export {
+  PiniaStoreLifecycleManager
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@atoapayments/pinia-store-lifecycle-manager",
+  "version": "0.0.1",
+  "description": "A Pinia plugin for managing store lifecycle, including state resets and refreshes",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src/**/*.ts",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "pinia",
+    "vue",
+    "store",
+    "lifecycle",
+    "management"
+  ],
+  "author": "Tushar gupta",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "@typescript-eslint/eslint-plugin": "^8.7.0",
+    "@typescript-eslint/parser": "^8.7.0",
+    "eslint": "^9.11.1",
+    "pinia": "^2.2.2",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2",
+    "vue": "^3.5.9"
+  },
+  "peerDependencies": {
+    "pinia": "^2.0.0",
+    "vue": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pinia": {
+      "optional": false
+    },
+    "vue": {
+      "optional": false
+    }
+  }
+}