@mhmo91/schmancy 0.2.140 → 0.2.142

package/types/src/store/context-object.d.ts

@@ -1,41 +1,18 @@
-import { BehaviorSubject } from 'rxjs';
-import { IStore, StorageType, StoreError } from './types';
+import { BaseStore } from './store.class';
+import { IStore, StorageType } from './types';
 /**
- * Enhanced store object with better TypeScript support
+ * Enhanced store object with better TypeScript support and immutability
+ * Now extends BaseStore for common functionality and uses Immer
  */
-export declare class SchmancyStoreObject<T extends Record<string, any>> implements IStore<T> {
-    private storageType;
-    private key;
+export declare class SchmancyStoreObject<T extends Record<string, any>> extends BaseStore<T> implements IStore<T> {
     static type: string;
     private static instances;
-    private _ready;
-    private _destroy$;
-    $: BehaviorSubject<T>;
-    error$: BehaviorSubject<StoreError<unknown>>;
-    readonly defaultValue: T;
-    private storage;
-    /**
-     * Get store ready state
-     */
-    get ready(): boolean;
-    /**
-     * Set store ready state
-     */
-    set ready(value: boolean);
-    /**
-     * Private constructor to enforce singleton pattern
-     */
-    private constructor();
     /**
      * Static method to get or create an instance with strong typing
      */
     static getInstance<T extends Record<string, any>>(storage: StorageType, key: string, defaultValue: T): SchmancyStoreObject<T>;
     /**
-     * Get the current value from the store
-     */
-    get value(): T;
-    /**
-     * Set state with proper typing
+     * Set state with proper typing and immutability using Immer
      */
     set(value: Partial<T>, merge?: boolean): void;
     /**
@@ -43,27 +20,21 @@ export declare class SchmancyStoreObject<T extends Record<string, any>> implemen
      */
     clear(): void;
     /**
-     * Replace the store with a new value
-     */
-    replace(newValue: T): void;
-    /**
-     * Delete a specific key from the store with type checking
+     * Delete a specific key from the store with type checking and immutability
      */
     delete<K extends keyof T>(key: K): void;
     /**
-     * Update the state with proper error handling
+     * Update a nested property at a specific path
+     * @param path Dot-separated path to the property (e.g., 'user.profile.name')
+     * @param value New value to set
      */
-    private updateState;
+    setPath(path: string, value: any): void;
     /**
-     * Initialize the store from persistent storage
+     * Process stored value by merging with default value
      */
-    private initializeFromStorage;
+    protected processStoredValue(storedValue: T): T;
     /**
      * Setup development tools for debugging
      */
-    private setupDevTools;
-    /**
-     * Clean up resources
-     */
-    destroy(): void;
+    protected setupDevTools(): void;
 }

package/types/src/store/filter-directive.d.ts

@@ -29,11 +29,6 @@ export interface ScoredItem<T> {
  * Checks explicitly for null/undefined so falsy values like 0 or false are preserved.
  */
 export declare const getFieldValue: <T = any>(item: Record<string, any>, path: string) => T;
-/**
- * Compare two values based on a comparison operator.
- * For non-fuzzy operators, this returns a boolean.
- */
-export declare function compareValues(op: ComparisonOperator, actual: unknown, expected: unknown): boolean;
 /**
  * Filter a Map of items given an array of query conditions.
  * For each query condition:
@@ -55,5 +50,67 @@ export declare function filterMapItems<T extends Record<string, any>>(items: Map
  * Filter an array of items using query conditions
  */
 export declare function filterArrayItems<T extends Record<string, any>>(items: T[], queries?: QueryCondition[], fuzzyThreshold?: number): T[];
+/**
+ * Type guard for checking if a value is an array with better type inference
+ * @param value Value to check
+ * @returns True if the value is an array
+ */
+export declare function isArray<T = unknown>(value: unknown): value is Array<T>;
+/**
+ * Type guard for checking if a value is a string
+ * @param value Value to check
+ * @returns True if the value is a string
+ */
+export declare function isString(value: unknown): value is string;
+/**
+ * Type guard for checking if a value is a number
+ * @param value Value to check
+ * @returns True if the value is a number and not NaN
+ */
+export declare function isNumber(value: unknown): value is number;
+/**
+ * Type guard for checking if a value is a date
+ * @param value Value to check
+ * @returns True if the value is a valid Date object
+ */
+export declare function isDate(value: unknown): value is Date;
+/**
+ * Type guard for checking if a value is an iterable collection
+ * @param value Value to check
+ * @returns True if the value implements the iterable protocol
+ */
+export declare function isIterable<T = unknown>(value: unknown): value is Iterable<T>;
+/**
+ * Type guard for checking if a value is a Map
+ * @param value Value to check
+ * @returns True if the value is a Map
+ */
+export declare function isMap<K = unknown, V = unknown>(value: unknown): value is Map<K, V>;
+/**
+ * Type guard for checking if a value is a Set
+ * @param value Value to check
+ * @returns True if the value is a Set
+ */
+export declare function isSet<T = unknown>(value: unknown): value is Set<T>;
+/**
+ * Type guard for checking if a value is a plain object (not an array, Map, etc.)
+ * @param value Value to check
+ * @returns True if the value is a plain object
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard for checking if a value is undefined or null
+ * @param value Value to check
+ * @returns True if the value is undefined or null
+ */
+export declare function isNil(value: unknown): value is undefined | null;
+/**
+ * Improved type-safe comparison function that uses appropriate type guards
+ * @param op Comparison operator
+ * @param actual Actual value
+ * @param expected Expected value
+ * @returns Result of the comparison
+ */
+export declare function compareValues(op: ComparisonOperator, actual: unknown, expected: unknown): boolean;
 export declare const filterMap: typeof filterMapItems;
 export declare const filterArray: typeof filterArrayItems;

package/types/src/store/immer-integration.d.ts

@@ -0,0 +1,60 @@
+import { Draft, castDraft, castImmutable, Immutable } from 'immer';
+/**
+ * Type-safe wrapper functions for immutable operations with Immer
+ *
+ * Re-export useful Immer types and utilities
+ */
+export { Draft, castDraft, castImmutable, Immutable };
+/**
+ * Create an immutable update for Maps
+ * @param map Original Map to update
+ * @param updater Function that can make "mutable" changes to the draft
+ * @returns A new Map with the changes applied
+ */
+export declare function updateMap<K, V>(map: Immutable<Map<K, V>>, updater: (draft: Draft<Map<K, V>>) => void): Map<K, V>;
+/**
+ * Create an immutable update for a specific item in a Map
+ * @param map Original Map to update
+ * @param key Key of the item to update
+ * @param updater Function that can make "mutable" changes to the item
+ * @returns A new Map with the item updated
+ */
+export declare function updateItem<K, V>(map: Immutable<Map<K, V>>, key: K, updater: (item: Draft<V>) => void): Map<K, V>;
+/**
+ * Immutably filter a Map
+ * @param map Original Map to filter
+ * @param predicate Function that returns true for items to keep
+ * @returns A new Map with only the matching items
+ */
+export declare function filterMap<K, V>(map: Immutable<Map<K, V>>, predicate: (value: Immutable<V>, key: Immutable<K>) => boolean): Map<K, V>;
+/**
+ * Create an immutable update for an object
+ * @param obj Original object to update
+ * @param updater Function that can make "mutable" changes to the draft
+ * @returns A new object with the changes applied
+ */
+export declare function updateObject<T extends Record<string, any>>(obj: Immutable<T>, updater: (draft: Draft<T>) => void): T;
+/**
+ * Merge objects immutably
+ * @param target Original object
+ * @param source Source object to merge in
+ * @returns A new object with properties merged
+ */
+export declare function mergeObjects<T extends Record<string, any>>(target: Immutable<T>, source: Partial<T>): T;
+/**
+ * Type guard to check if an object is a Map
+ */
+export declare function isMap<K = unknown, V = unknown>(value: unknown): value is Map<K, V>;
+/**
+ * Creates a readonly version of a type
+ * This is a utility that uses Immer's Immutable type to make a type readonly
+ * @param value The value to cast as immutable
+ * @returns The same value but typed as immutable
+ */
+export declare function asReadonly<T>(value: T): Immutable<T>;
+/**
+ * Makes an object or Map deeply immutable at runtime by freezing
+ * @param value The value to freeze
+ * @returns The frozen value
+ */
+export declare function freeze<T>(value: T): Immutable<T>;

package/types/src/store/selector-hook.d.ts

@@ -22,9 +22,12 @@ interface SelectOptions {
     deepClone?: boolean;
     /** Custom equality function to determine when to update */
     equals?: (a: any, b: any) => boolean;
+    /** Debug mode - logs selector activity */
+    debug?: boolean;
 }
 /**
  * Selector decorator that connects a component property to a store selector
+ * with improved memory management
  *
  * @param store The store to select from
  * @param selectorFn Optional function to transform the store state
@@ -33,6 +36,7 @@ interface SelectOptions {
 export declare function select<T, R>(store: IStore<T> | ICollectionStore<T>, selectorFn?: (state: any) => R, options?: SelectOptions): (proto: Record<string, any>, propName: string, _descriptor?: PropertyDescriptor<R>) => void;
 /**
  * Creates a selector decorator that selects a specific item from a collection store
+ * with improved memory management
  *
  * @param store The collection store
  * @param keyGetter Function that returns the key to select

package/types/src/store/selectors.d.ts

@@ -23,14 +23,6 @@ export declare function createCollectionSelector<T, R>(store: ICollectionStore<T
  * @returns An observable of all items as an array
  */
 export declare function createItemsSelector<T>(store: ICollectionStore<T>): Observable<T[]>;
-/**
- * Creates a selector that filters items from a collection
- *
- * @param store The collection store
- * @param filterFn Function that returns true for items to include
- * @returns An observable of filtered items as an array
- */
-export declare function createFilterSelector<T>(store: ICollectionStore<T>, filterFn: (item: T, key: string) => boolean): Observable<T[]>;
 /**
  * Creates a selector that retrieves a single item from a collection
  *
@@ -39,14 +31,6 @@ export declare function createFilterSelector<T>(store: ICollectionStore<T>, filt
  * @returns An observable of the selected item that emits when the item changes
  */
 export declare function createItemSelector<T>(store: ICollectionStore<T>, itemKey: string): Observable<T | undefined>;
-/**
- * Creates a selector that counts items in a collection, optionally filtered
- *
- * @param store The collection store
- * @param filterFn Optional function to filter which items to count
- * @returns An observable of the count
- */
-export declare function createCountSelector<T>(store: ICollectionStore<T>, filterFn?: (item: T, key: string) => boolean): Observable<number>;
 /**
  * Creates a compound selector that depends on multiple other selectors
  *
@@ -65,10 +49,6 @@ export declare function createKeysSelector<T>(store: ICollectionStore<T>): Obser
  * Creates a selector that returns entries (key-value pairs) from a collection
  */
 export declare function createEntriesSelector<T>(store: ICollectionStore<T>): Observable<[string, T][]>;
-/**
- * Creates a selector that maps collection values through a transform function
- */
-export declare function createMapSelector<T, R>(store: ICollectionStore<T>, mapFn: (item: T, key: string) => R): Observable<R[]>;
 /**
  * Creates a selector that sorts collection items
  */
@@ -77,3 +57,32 @@ export declare function createSortSelector<T>(store: ICollectionStore<T>, compar
  * Creates a selector that finds the first item matching a predicate
  */
 export declare function createFindSelector<T>(store: ICollectionStore<T>, predicate: (item: T, key: string) => boolean): Observable<T | undefined>;
+/**
+ * Creates a selector that filters items from a collection - OPTIMIZED
+ *
+ * @param store The collection store
+ * @param filterFn Function that returns true for items to include
+ * @returns An observable of filtered items as an array
+ */
+export declare function createFilterSelector<T>(store: ICollectionStore<T>, filterFn: (item: T, key: string) => boolean): Observable<T[]>;
+/**
+ * Creates a selector that maps collection values through a transform function - OPTIMIZED
+ */
+export declare function createMapSelector<T, R>(store: ICollectionStore<T>, mapFn: (item: T, key: string) => R): Observable<R[]>;
+/**
+ * Creates a selector that counts items in a collection, optionally filtered - OPTIMIZED
+ *
+ * @param store The collection store
+ * @param filterFn Optional function to filter which items to count
+ * @returns An observable of the count
+ */
+export declare function createCountSelector<T>(store: ICollectionStore<T>, filterFn?: (item: T, key: string) => boolean): Observable<number>;
+/**
+ * Optimized RxJS Pipeline - use share with reset on refCount zero for better memory management
+ * in scenarios where selector subscriptions come and go
+ *
+ * @param store The store to observe
+ * @param selectorFn Function that transforms the state
+ * @returns An observable of the selected state with improved memory management
+ */
+export declare function createOptimizedSelector<T, R>(store: IStore<T>, selectorFn: (state: T) => R): Observable<R>;

package/types/src/store/store.class.d.ts

@@ -0,0 +1,67 @@
+import { BehaviorSubject, Subject } from 'rxjs';
+import { IStorageManager, StorageType, StoreError } from './types';
+/**
+ * Base store class to handle common functionality between store types
+ * Now with Immer integration for immutability
+ */
+export declare abstract class BaseStore<T> {
+    protected storageType: StorageType;
+    protected key: string;
+    protected _ready: boolean;
+    protected _destroy$: Subject<void>;
+    $: BehaviorSubject<T>;
+    error$: BehaviorSubject<StoreError<unknown>>;
+    readonly defaultValue: T;
+    protected storage: IStorageManager<T>;
+    /**
+     * Get store ready state
+     */
+    get ready(): boolean;
+    /**
+     * Set store ready state
+     */
+    set ready(value: boolean);
+    /**
+     * Get the current value
+     */
+    get value(): T;
+    /**
+     * Initialize the base store
+     * @param storageType Storage type to use
+     * @param key Unique key for the store
+     * @param defaultValue Default/initial value
+     */
+    constructor(storageType: StorageType, key: string, defaultValue: T);
+    /**
+     * Cleanup method for all store types
+     */
+    destroy(): void;
+    /**
+     * Replace the entire store state immutably
+     */
+    replace(newValue: T): void;
+    /**
+     * Reset to default value - to be implemented by subclasses
+     */
+    abstract clear(): void;
+    /**
+     * Update the state with proper error handling and immutability
+     */
+    protected updateState(newValue: T): void;
+    /**
+     * Initialize the store from persistent storage
+     */
+    protected initializeFromStorage(): Promise<void>;
+    /**
+     * Process stored value (can be overridden by subclasses)
+     */
+    protected processStoredValue(storedValue: T): T;
+    /**
+     * Persist state to storage
+     */
+    protected persistToStorage(state: T): Promise<void>;
+    /**
+     * Setup development tools
+     */
+    protected abstract setupDevTools(): void;
+}

package/types/src/store/types.d.ts

@@ -1,3 +1,4 @@
+import { Draft } from 'immer';
 import { BehaviorSubject, Observable } from 'rxjs';
 /**
  * Storage types supported by the store
@@ -137,3 +138,104 @@ export type StoreFactory = <T extends Record<string, any>>(initialData: T, stora
  * Factory function type for creating collection stores
  */
 export type CollectionStoreFactory = <T>(initialData: Map<string, T>, storage: StorageType, key: string) => ICollectionStore<T>;
+/**
+ * Interface for array stores with improved typing
+ */
+export interface IArrayStore<T> {
+    /** Get the current array value */
+    readonly value: T[];
+    /** Observable stream of array values */
+    readonly $: BehaviorSubject<T[]>;
+    /** The default/initial value of the array */
+    readonly defaultValue: T[];
+    /** Whether the store is ready (loaded from storage) */
+    ready: boolean;
+    /** Observable stream of store errors */
+    readonly error$: Observable<StoreError | null>;
+    /**
+     * Add item(s) to the end of the array
+     * @param items Items to add
+     */
+    push(...items: T[]): void;
+    /**
+     * Remove and return the last item from the array
+     * @returns The removed item or undefined if the array was empty
+     */
+    pop(): T | undefined;
+    /**
+     * Add item(s) to the beginning of the array
+     * @param items Items to add
+     */
+    unshift(...items: T[]): void;
+    /**
+     * Remove and return the first item from the array
+     * @returns The removed item or undefined if the array was empty
+     */
+    shift(): T | undefined;
+    /**
+     * Update an item at a specific index
+     * @param index The index to update
+     * @param value The new value
+     */
+    set(index: number, value: T): void;
+    /**
+     * Get the item at a specific index
+     * @param index The index to get
+     * @returns The item or undefined if index is out of bounds
+     */
+    get(index: number): T | undefined;
+    /**
+     * Remove items from the array and optionally insert new ones
+     * @param start The start index
+     * @param deleteCount The number of items to delete
+     * @param items Items to insert
+     * @returns The removed items
+     */
+    splice(start: number, deleteCount?: number, ...items: T[]): T[];
+    /**
+     * Remove an item by value (first occurrence)
+     * @param item The item to remove
+     * @param compareFn Optional function to compare items
+     * @returns True if the item was found and removed
+     */
+    remove(item: T, compareFn?: (a: T, b: T) => boolean): boolean;
+    /**
+     * Replace the entire array
+     * @param newArray The new array
+     */
+    replace(newArray: T[]): void;
+    /**
+     * Filter items in the array
+     * @param predicate Function to test each item
+     */
+    filter(predicate: (value: T, index: number, array: T[]) => boolean): void;
+    /**
+     * Map over the array and transform items
+     * @param mapper Function to transform each item
+     * @returns Array of transformed items
+     */
+    map<U>(mapper: (value: T, index: number, array: T[]) => U): U[];
+    /**
+     * Sort the array in place
+     * @param compareFn Optional function to determine sort order
+     */
+    sort(compareFn?: (a: T, b: T) => number): void;
+    /**
+     * Update a specific item using a callback function
+     * @param index The index to update
+     * @param updater Function that can modify the item
+     */
+    update(index: number, updater: (item: Draft<T>) => void): void;
+    /**
+     * Clear all items from the array
+     */
+    clear(): void;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+/**
+ * Factory function type for creating array stores
+ */
+export type ArrayStoreFactory = <T>(initialData: T[], storage: StorageType, key: string) => IArrayStore<T>;