eleva 1.0.1 → 1.1.0

package/dist/plugins/store.d.ts

@@ -0,0 +1,266 @@
+import * as eleva from 'eleva';
+
+declare namespace StorePlugin {
+    let name: string;
+    let version: string;
+    let description: string;
+    /**
+     * Installs the plugin into the Eleva instance.
+     *
+     * @public
+     * @param {Eleva} eleva - The Eleva instance.
+     * @param {StoreOptions} options - Plugin configuration options.
+     * @param {Record<string, unknown>} [options.state={}] - Initial state object.
+     * @param {Record<string, ActionFunction>} [options.actions={}] - Action functions for state mutations.
+     * @param {Record<string, StoreModule>} [options.namespaces={}] - Namespaced modules for organizing store.
+     * @param {StorePersistenceOptions} [options.persistence] - Persistence configuration.
+     * @param {boolean} [options.persistence.enabled=false] - Enable state persistence.
+     * @param {string} [options.persistence.key="eleva-store"] - Storage key.
+     * @param {'localStorage' | 'sessionStorage'} [options.persistence.storage="localStorage"] - Storage type.
+     * @param {string[]} [options.persistence.include] - Dot-path prefixes to persist (e.g., "auth.user")
+     * @param {string[]} [options.persistence.exclude] - Dot-path prefixes to exclude (applies when include is empty).
+     * @param {boolean} [options.devTools=false] - Enable development tools integration.
+     * @param {(error: Error, context: string) => void} [options.onError=null] - Error handler function.
+     * @returns {void}
+     * @description
+     * Installs the store and injects `store` into component setup context by wrapping
+     * `eleva.mount` and `eleva._mountComponents`. Also exposes `eleva.store` and
+     * helper methods (`eleva.dispatch`, `eleva.getState`, `eleva.subscribe`, `eleva.createAction`).
+     * Uninstall restores the originals.
+     *
+     * @example
+     * // Basic installation
+     * app.use(StorePlugin, {
+     *   state: { count: 0, user: null },
+     *   actions: {
+     *     increment: (state) => state.count.value++,
+     *     setUser: (state, user) => state.user.value = user
+     *   }
+     * });
+     *
+     * // Advanced installation with persistence and namespaces
+     * app.use(StorePlugin, {
+     *   state: { theme: "light" },
+     *   namespaces: {
+     *     auth: {
+     *       state: { user: null, token: null },
+     *       actions: {
+     *         login: (state, { user, token }) => {
+     *           state.auth.user.value = user;
+     *           state.auth.token.value = token;
+     *         },
+     *         logout: (state) => {
+     *           state.auth.user.value = null;
+     *           state.auth.token.value = null;
+     *         }
+     *       }
+     *     }
+     *   },
+     *   persistence: {
+     *     enabled: true,
+     *     include: ["theme", "auth.user"]
+     *   }
+     * });
+     */
+    function install(eleva: Eleva, options?: StoreOptions): void;
+    /**
+     * Uninstalls the plugin from the Eleva instance.
+     *
+     * @public
+     * @param {Eleva} eleva - The Eleva instance.
+     * @returns {void}
+     * @description
+     * Restores the original Eleva methods and removes all plugin-specific
+     * functionality. This method should be called when the plugin is no
+     * longer needed.
+     * Also removes `eleva.store` and top-level helpers (`eleva.dispatch`,
+     * `eleva.getState`, `eleva.subscribe`, `eleva.createAction`).
+     *
+     * @example
+     * // Uninstall the plugin
+     * StorePlugin.uninstall(app);
+     */
+    function uninstall(eleva: Eleva): void;
+}
+
+/**
+ * Type imports from the Eleva core library.
+ */
+type Eleva = eleva.Eleva;
+/**
+ * Type imports from the Eleva core library.
+ */
+type ComponentDefinition = eleva.ComponentDefinition;
+/**
+ * Type imports from the Eleva core library.
+ */
+type ComponentContext = eleva.ComponentContext;
+/**
+ * Type imports from the Eleva core library.
+ */
+type SetupResult = eleva.SetupResult;
+/**
+ * Type imports from the Eleva core library.
+ */
+type ComponentProps = eleva.ComponentProps;
+/**
+ * Type imports from the Eleva core library.
+ */
+type ChildrenMap = eleva.ChildrenMap;
+/**
+ * Type imports from the Eleva core library.
+ */
+type MountResult = eleva.MountResult;
+/**
+ * Generic type import.
+ */
+type Signal<T> = eleva.Signal<T>;
+/**
+ * Mutation record emitted to subscribers.
+ */
+type StoreMutation = {
+    /**
+     *           The action name that was dispatched.
+     */
+    type: string;
+    /**
+     *           The payload passed to the action.
+     */
+    payload: unknown;
+    /**
+     *           Unix timestamp of when the mutation occurred.
+     */
+    timestamp: number;
+};
+/**
+ * Store configuration options.
+ */
+type StoreOptions = {
+    /**
+     * Initial state object.
+     */
+    state?: Record<string, unknown> | undefined;
+    /**
+     * Action functions for state mutations.
+     */
+    actions?: Record<string, ActionFunction> | undefined;
+    /**
+     * Namespaced modules for organizing store.
+     */
+    namespaces?: Record<string, StoreModule> | undefined;
+    /**
+     * Persistence configuration.
+     */
+    persistence?: StorePersistenceOptions | undefined;
+    /**
+     * Enable development tools integration.
+     */
+    devTools?: boolean | undefined;
+    /**
+     * Error handler function.
+     */
+    onError?: StoreErrorHandler | undefined;
+};
+/**
+ * Namespaced store module definition.
+ */
+type StoreModule = {
+    /**
+     *           Module state.
+     */
+    state: Record<string, unknown>;
+    /**
+     * Module actions.
+     */
+    actions?: Record<string, ActionFunction> | undefined;
+};
+/**
+ * Store persistence configuration.
+ */
+type StorePersistenceOptions = {
+    /**
+     * Enable state persistence.
+     */
+    enabled?: boolean | undefined;
+    /**
+     * Storage key (default: "eleva-store").
+     */
+    key?: string | undefined;
+    /**
+     * Storage type.
+     */
+    storage?: "localStorage" | "sessionStorage" | undefined;
+    /**
+     * Dot-path prefixes to persist (e.g., "auth.user").
+     */
+    include?: string[] | undefined;
+    /**
+     * Dot-path prefixes to exclude.
+     */
+    exclude?: string[] | undefined;
+};
+/**
+ * Store error handler callback.
+ */
+type StoreErrorHandler = (error: Error, context: string) => void;
+/**
+ * Reactive state tree containing signals and nested namespaces.
+ */
+type StoreState = Record<string, Signal<unknown> | Record<string, unknown>>;
+/**
+ * Action function signature for store actions.
+ */
+type ActionFunction = (state: StoreState, payload?: unknown) => unknown;
+/**
+ * Dispatch function signature for triggering actions.
+ */
+type DispatchFunction = (actionName: string, payload?: unknown) => Promise<unknown>;
+/**
+ * Subscribe callback signature for mutation listeners.
+ */
+type SubscribeCallback = (mutation: StoreMutation, state: StoreState) => void;
+/**
+ * Store API exposed to components via ctx.store.
+ */
+type StoreApi = {
+    /**
+     *           Reactive state signals (supports nested modules).
+     */
+    state: StoreState;
+    /**
+     *           Dispatch an action by name with optional payload.
+     */
+    dispatch: DispatchFunction;
+    /**
+     *           Subscribe to state mutations. Returns unsubscribe function.
+     */
+    subscribe: (callback: SubscribeCallback) => () => void;
+    /**
+     *           Get a snapshot of current state values.
+     */
+    getState: () => Record<string, unknown>;
+    /**
+     *           Register a namespaced module dynamically.
+     */
+    registerModule: (namespace: string, module: StoreModule) => void;
+    /**
+     *           Unregister a namespaced module.
+     */
+    unregisterModule: (namespace: string) => void;
+    /**
+     *           Create a new state signal dynamically.
+     */
+    createState: (key: string, initialValue: unknown) => Signal<unknown>;
+    /**
+     *           Register a new action dynamically.
+     */
+    createAction: (name: string, actionFn: ActionFunction) => void;
+    /**
+     *           Signal class constructor for manual state creation.
+     */
+    signal: new <T>(value: T) => Signal<T>;
+};
+
+export { StorePlugin as Store, StorePlugin };
+export type { ActionFunction, ChildrenMap, ComponentContext, ComponentDefinition, ComponentProps, DispatchFunction, Eleva, MountResult, SetupResult, Signal, StoreApi, StoreErrorHandler, StoreModule, StoreMutation, StoreOptions, StorePersistenceOptions, StoreState, SubscribeCallback };
+//# sourceMappingURL=store.d.ts.map

package/dist/plugins/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sources":["../../types/plugins/Store.d.ts"],"sourcesContent":["export namespace StorePlugin {\n    let name: string;\n    let version: string;\n    let description: string;\n    /**\n     * Installs the plugin into the Eleva instance.\n     *\n     * @public\n     * @param {Eleva} eleva - The Eleva instance.\n     * @param {StoreOptions} options - Plugin configuration options.\n     * @param {Record<string, unknown>} [options.state={}] - Initial state object.\n     * @param {Record<string, ActionFunction>} [options.actions={}] - Action functions for state mutations.\n     * @param {Record<string, StoreModule>} [options.namespaces={}] - Namespaced modules for organizing store.\n     * @param {StorePersistenceOptions} [options.persistence] - Persistence configuration.\n     * @param {boolean} [options.persistence.enabled=false] - Enable state persistence.\n     * @param {string} [options.persistence.key=\"eleva-store\"] - Storage key.\n     * @param {'localStorage' | 'sessionStorage'} [options.persistence.storage=\"localStorage\"] - Storage type.\n     * @param {string[]} [options.persistence.include] - Dot-path prefixes to persist (e.g., \"auth.user\")\n     * @param {string[]} [options.persistence.exclude] - Dot-path prefixes to exclude (applies when include is empty).\n     * @param {boolean} [options.devTools=false] - Enable development tools integration.\n     * @param {(error: Error, context: string) => void} [options.onError=null] - Error handler function.\n     * @returns {void}\n     * @description\n     * Installs the store and injects `store` into component setup context by wrapping\n     * `eleva.mount` and `eleva._mountComponents`. Also exposes `eleva.store` and\n     * helper methods (`eleva.dispatch`, `eleva.getState`, `eleva.subscribe`, `eleva.createAction`).\n     * Uninstall restores the originals.\n     *\n     * @example\n     * // Basic installation\n     * app.use(StorePlugin, {\n     *   state: { count: 0, user: null },\n     *   actions: {\n     *     increment: (state) => state.count.value++,\n     *     setUser: (state, user) => state.user.value = user\n     *   }\n     * });\n     *\n     * // Advanced installation with persistence and namespaces\n     * app.use(StorePlugin, {\n     *   state: { theme: \"light\" },\n     *   namespaces: {\n     *     auth: {\n     *       state: { user: null, token: null },\n     *       actions: {\n     *         login: (state, { user, token }) => {\n     *           state.auth.user.value = user;\n     *           state.auth.token.value = token;\n     *         },\n     *         logout: (state) => {\n     *           state.auth.user.value = null;\n     *           state.auth.token.value = null;\n     *         }\n     *       }\n     *     }\n     *   },\n     *   persistence: {\n     *     enabled: true,\n     *     include: [\"theme\", \"auth.user\"]\n     *   }\n     * });\n     */\n    function install(eleva: Eleva, options?: StoreOptions): void;\n    /**\n     * Uninstalls the plugin from the Eleva instance.\n     *\n     * @public\n     * @param {Eleva} eleva - The Eleva instance.\n     * @returns {void}\n     * @description\n     * Restores the original Eleva methods and removes all plugin-specific\n     * functionality. This method should be called when the plugin is no\n     * longer needed.\n     * Also removes `eleva.store` and top-level helpers (`eleva.dispatch`,\n     * `eleva.getState`, `eleva.subscribe`, `eleva.createAction`).\n     *\n     * @example\n     * // Uninstall the plugin\n     * StorePlugin.uninstall(app);\n     */\n    function uninstall(eleva: Eleva): void;\n}\nexport { StorePlugin as Store };\n/**\n * Type imports from the Eleva core library.\n */\nexport type Eleva = import(\"eleva\").Eleva;\n/**\n * Type imports from the Eleva core library.\n */\nexport type ComponentDefinition = import(\"eleva\").ComponentDefinition;\n/**\n * Type imports from the Eleva core library.\n */\nexport type ComponentContext = import(\"eleva\").ComponentContext;\n/**\n * Type imports from the Eleva core library.\n */\nexport type SetupResult = import(\"eleva\").SetupResult;\n/**\n * Type imports from the Eleva core library.\n */\nexport type ComponentProps = import(\"eleva\").ComponentProps;\n/**\n * Type imports from the Eleva core library.\n */\nexport type ChildrenMap = import(\"eleva\").ChildrenMap;\n/**\n * Type imports from the Eleva core library.\n */\nexport type MountResult = import(\"eleva\").MountResult;\n/**\n * Generic type import.\n */\nexport type Signal<T> = import(\"eleva\").Signal<T>;\n/**\n * Mutation record emitted to subscribers.\n */\nexport type StoreMutation = {\n    /**\n     *           The action name that was dispatched.\n     */\n    type: string;\n    /**\n     *           The payload passed to the action.\n     */\n    payload: unknown;\n    /**\n     *           Unix timestamp of when the mutation occurred.\n     */\n    timestamp: number;\n};\n/**\n * Store configuration options.\n */\nexport type StoreOptions = {\n    /**\n     * Initial state object.\n     */\n    state?: Record<string, unknown> | undefined;\n    /**\n     * Action functions for state mutations.\n     */\n    actions?: Record<string, ActionFunction> | undefined;\n    /**\n     * Namespaced modules for organizing store.\n     */\n    namespaces?: Record<string, StoreModule> | undefined;\n    /**\n     * Persistence configuration.\n     */\n    persistence?: StorePersistenceOptions | undefined;\n    /**\n     * Enable development tools integration.\n     */\n    devTools?: boolean | undefined;\n    /**\n     * Error handler function.\n     */\n    onError?: StoreErrorHandler | undefined;\n};\n/**\n * Namespaced store module definition.\n */\nexport type StoreModule = {\n    /**\n     *           Module state.\n     */\n    state: Record<string, unknown>;\n    /**\n     * Module actions.\n     */\n    actions?: Record<string, ActionFunction> | undefined;\n};\n/**\n * Store persistence configuration.\n */\nexport type StorePersistenceOptions = {\n    /**\n     * Enable state persistence.\n     */\n    enabled?: boolean | undefined;\n    /**\n     * Storage key (default: \"eleva-store\").\n     */\n    key?: string | undefined;\n    /**\n     * Storage type.\n     */\n    storage?: \"localStorage\" | \"sessionStorage\" | undefined;\n    /**\n     * Dot-path prefixes to persist (e.g., \"auth.user\").\n     */\n    include?: string[] | undefined;\n    /**\n     * Dot-path prefixes to exclude.\n     */\n    exclude?: string[] | undefined;\n};\n/**\n * Store error handler callback.\n */\nexport type StoreErrorHandler = (error: Error, context: string) => void;\n/**\n * Reactive state tree containing signals and nested namespaces.\n */\nexport type StoreState = Record<string, Signal<unknown> | Record<string, unknown>>;\n/**\n * Action function signature for store actions.\n */\nexport type ActionFunction = (state: StoreState, payload?: unknown) => unknown;\n/**\n * Dispatch function signature for triggering actions.\n */\nexport type DispatchFunction = (actionName: string, payload?: unknown) => Promise<unknown>;\n/**\n * Subscribe callback signature for mutation listeners.\n */\nexport type SubscribeCallback = (mutation: StoreMutation, state: StoreState) => void;\n/**\n * Store API exposed to components via ctx.store.\n */\nexport type StoreApi = {\n    /**\n     *           Reactive state signals (supports nested modules).\n     */\n    state: StoreState;\n    /**\n     *           Dispatch an action by name with optional payload.\n     */\n    dispatch: DispatchFunction;\n    /**\n     *           Subscribe to state mutations. Returns unsubscribe function.\n     */\n    subscribe: (callback: SubscribeCallback) => () => void;\n    /**\n     *           Get a snapshot of current state values.\n     */\n    getState: () => Record<string, unknown>;\n    /**\n     *           Register a namespaced module dynamically.\n     */\n    registerModule: (namespace: string, module: StoreModule) => void;\n    /**\n     *           Unregister a namespaced module.\n     */\n    unregisterModule: (namespace: string) => void;\n    /**\n     *           Create a new state signal dynamically.\n     */\n    createState: (key: string, initialValue: unknown) => Signal<unknown>;\n    /**\n     *           Register a new action dynamically.\n     */\n    createAction: (name: string, actionFn: ActionFunction) => void;\n    /**\n     *           Signal class constructor for manual state creation.\n     */\n    signal: new <T>(value: T) => Signal<T>;\n};\n//# sourceMappingURL=Store.d.ts.map"],"names":[],"mappings":";;AAAO,kBAAA,WAAA;AACP;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,4BAAA,KAAA,YAAA,YAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,8BAAA,KAAA;AACA;;AAEA;AACA;AACA;AACO,KAAA,KAAA,GAAa,KAAe,CAAA,KAAA;AACnC;AACA;AACA;AACO,KAAA,mBAAA,GAA2B,KAAe,CAAA,mBAAA;AACjD;AACA;AACA;AACO,KAAA,gBAAA,GAAwB,KAAe,CAAA,gBAAA;AAC9C;AACA;AACA;AACO,KAAA,WAAA,GAAmB,KAAe,CAAA,WAAA;AACzC;AACA;AACA;AACO,KAAA,cAAA,GAAsB,KAAe,CAAA,cAAA;AAC5C;AACA;AACA;AACO,KAAA,WAAA,GAAmB,KAAe,CAAA,WAAA;AACzC;AACA;AACA;AACO,KAAA,WAAA,GAAmB,KAAe,CAAA,WAAA;AACzC;AACA;AACA;AACO,KAAA,MAAA,MAAiB,KAAe,CAAA,MAAA;AACvC;AACA;AACA;AACO,KAAA,aAAA;AACP;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,KAAA,YAAA;AACP;AACA;AACA;AACA,YAAA,MAAA;AACA;AACA;AACA;AACA,cAAA,MAAA,SAAA,cAAA;AACA;AACA;AACA;AACA,iBAAA,MAAA,SAAA,WAAA;AACA;AACA;AACA;AACA,kBAAA,uBAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,cAAA,iBAAA;AACA;AACA;AACA;AACA;AACO,KAAA,WAAA;AACP;AACA;AACA;AACA,WAAA,MAAA;AACA;AACA;AACA;AACA,cAAA,MAAA,SAAA,cAAA;AACA;AACA;AACA;AACA;AACO,KAAA,uBAAA;AACP;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,KAAA,iBAAA,WAAA,KAAA;AACP;AACA;AACA;AACO,KAAA,UAAA,GAAA,MAAA,SAAA,MAAA,YAAA,MAAA;AACP;AACA;AACA;AACO,KAAA,cAAA,WAAA,UAAA;AACP;AACA;AACA;AACO,KAAA,gBAAA,8CAAA,OAAA;AACP;AACA;AACA;AACO,KAAA,iBAAA,cAAA,aAAA,SAAA,UAAA;AACP;AACA;AACA;AACO,KAAA,QAAA;AACP;AACA;AACA;AACA,WAAA,UAAA;AACA;AACA;AACA;AACA,cAAA,gBAAA;AACA;AACA;AACA;AACA,0BAAA,iBAAA;AACA;AACA;AACA;AACA,oBAAA,MAAA;AACA;AACA;AACA;AACA,gDAAA,WAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,yDAAA,MAAA;AACA;AACA;AACA;AACA,2CAAA,cAAA;AACA;AACA;AACA;AACA,iCAAA,MAAA;AACA;;;;"}