effectable 0.1.0

package/build/store/selector.js

@@ -0,0 +1,226 @@
+"use strict";
+/* eslint-disable no-redeclare */
+/**
+ * Selector System with Memoization
+ *
+ * Implements a memoized selector system similar to the reselect library.
+ * Selectors recompute only when dependencies change,
+ * which optimizes performance of reactive subscriptions.
+ *
+ * @module Effectable/store/selector
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSelector = createSelector;
+exports.createStructuredSelector = createStructuredSelector;
+/**
+ * Simple memoization for a single argument (state)
+ *
+ * Caches the function result based on a shallow equality check of the argument.
+ * If the argument has not changed (shallow equal), returns the cached result.
+ *
+ * @template F - Type of the function to memoize
+ * @param func - Function to memoize
+ * @returns Memoized function with extra methods
+ *
+ * @example
+ * const expensive = (state) => state.items.map(x => x * 2);
+ * const memoized = defaultMemoize(expensive);
+ *
+ * memoized(state1); // Computed
+ * memoized(state1); // Returns cache
+ * memoized(state2); // Recomputed
+ */
+function defaultMemoize(func) {
+    let lastArg = null;
+    let lastResult = null;
+    let called = false;
+    let recomputationCount = 0;
+    const memoized = (arg) => {
+        // If never called or the argument changed — recompute
+        if (!called || !shallowEqual(arg, lastArg)) {
+            lastArg = arg;
+            lastResult = func(arg);
+            called = true;
+            recomputationCount++;
+        }
+        return lastResult;
+    };
+    // Cache reset method
+    memoized.resetMemoization = () => {
+        lastArg = null;
+        lastResult = null;
+        called = false;
+        recomputationCount = 0;
+    };
+    // Method returning recomputation count (for debugging)
+    memoized.recomputations = () => recomputationCount;
+    return memoized;
+}
+/**
+ * Shallow equality for primitives and objects
+ *
+ * Compares two values:
+ * - For primitives uses ===
+ * - For objects compares all top-level fields
+ * - For arrays compares length and elements
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @returns true if values are equal (shallow)
+ */
+function shallowEqual(a, b) {
+    // Strict equality (for primitives and references)
+    if (a === b) {
+        return true;
+    }
+    // Different types or null/undefined
+    if (typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    if (a === null || b === null) {
+        return false;
+    }
+    // For arrays
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    // For objects
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) {
+        return false;
+    }
+    for (const key of keysA) {
+        if (a[key] !== b[key]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Creates a memoized selector
+ *
+ * Takes input selectors and a combiner function.
+ * Input selectors extract dependencies from state.
+ * Combiner combines input selector results into the final result.
+ *
+ * The selector recomputes only when:
+ * - At least one input selector result changed (shallow equality)
+ *
+ * @template S - State type
+ * @template T - Result type
+ *
+ * @param args - Input selectors + combiner function at the end
+ * @returns Memoized selector
+ *
+ * @example
+ * // Simple selector
+ * const selectCount = createSelector(
+ *   [(state) => state.count],
+ *   (count) => count * 2
+ * );
+ *
+ * @example
+ * // Selector composition
+ * const selectUsers = (state) => state.users;
+ * const selectFilter = (state) => state.filter;
+ *
+ * const selectFilteredUsers = createSelector(
+ *   [selectUsers, selectFilter],
+ *   (users, filter) => users.filter(u => u.name.includes(filter))
+ * );
+ *
+ * @example
+ * // Usage with store.select()
+ * store.select(selectFilteredUsers).subscribe(users => {
+ *   console.log('Filtered users:', users);
+ * });
+ */
+function createSelector(...args) {
+    // Last argument is the combiner function
+    const combiner = args[args.length - 1];
+    // Remaining arguments are input selectors
+    // Two formats are supported:
+    // 1. createSelector(sel1, sel2, combiner) - selectors as separate arguments
+    // 2. createSelector([sel1, sel2], combiner) - selectors as an array
+    let inputSelectors;
+    if (Array.isArray(args[0])) {
+        // Format: createSelector([sel1, sel2], combiner)
+        inputSelectors = args[0];
+    }
+    else {
+        // Format: createSelector(sel1, sel2, combiner)
+        inputSelectors = args.slice(0, -1);
+    }
+    // Memoize the combiner function.
+    // IMPORTANT: defaultMemoize memoizes on a SINGLE argument only, so
+    // we pass the dependency array as one argument and then
+    // "spread" it into the combiner (as in reselect).
+    const memoizedCombiner = defaultMemoize((params) => combiner(...params));
+    /**
+     * Resulting selector
+     *
+     * Calls all input selectors, collects results into an array,
+     * and passes them to the memoized combiner.
+     */
+    const selector = (state) => {
+        // Get results of all input selectors
+        const params = inputSelectors.map((inputSelector) => inputSelector(state));
+        // Apply the memoized combiner
+        // Memoization is based on shallow equality of the params array
+        return memoizedCombiner(params);
+    };
+    // Add methods for debugging and cache control
+    const memoizedSelector = selector;
+    memoizedSelector.resetMemoization = () => {
+        memoizedCombiner.resetMemoization();
+    };
+    memoizedSelector.recomputations = () => {
+        return memoizedCombiner.recomputations();
+    };
+    return memoizedSelector;
+}
+/**
+ * Creates a structured selector from an object of selectors
+ *
+ * Convenient utility for creating a selector that returns an object
+ * with results of several selectors.
+ *
+ * @template S - State type
+ * @template T - Result type (object with selectors)
+ *
+ * @param selectorsObj - Object where keys are field names and values are selectors
+ * @returns Memoized selector returning an object of results
+ *
+ * @example
+ * const selectNavigation = createStructuredSelector({
+ *   currentPath: (state) => state.navigation.currentPath,
+ *   breadcrumb: (state) => state.navigation.breadcrumb,
+ *   canGoBack: (state) => state.navigation.history.backStack.length > 0,
+ * });
+ *
+ * // Result: { currentPath: '...', breadcrumb: [...], canGoBack: true }
+ * store.select(selectNavigation).subscribe(nav => {
+ *   console.log('Navigation:', nav);
+ * });
+ */
+function createStructuredSelector(selectorsObj) {
+    const keys = Object.keys(selectorsObj);
+    const selectors = keys.map((key) => selectorsObj[key]);
+    return createSelector(selectors, (...values) => {
+        const result = {};
+        keys.forEach((key, index) => {
+            result[key] = values[index];
+        });
+        return result;
+    });
+}
+//# sourceMappingURL=selector.js.map

package/build/store/selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.js","sourceRoot":"","sources":["../../src/store/selector.ts"],"names":[],"mappings":"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"}

package/build/store/semanticStateTree.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Builds a semantic JSON tree from a store state snapshot / reducer map.
+ *
+ * Reducers at runtime do not describe data shape without initial state, so
+ * the walk is performed over the provided `initialState` (or `store.getState()`),
+ * and the `{ slice: reducer }` map is used to align slice keys with the root state.
+ *
+ * @module Effectable/store/semanticStateTree
+ */
+import type { Action, Reducer, Store } from './types';
+/**
+ * Primitive kind in the semantic tree.
+ */
+export type SemanticJsonPrimitiveKind = 'null' | 'undefined' | 'boolean' | 'number' | 'string' | 'bigint' | 'symbol';
+/**
+ * Semantic tree node suitable for `JSON.stringify`.
+ */
+export type SemanticJsonNode = {
+    kind: 'primitive';
+    valueType: SemanticJsonPrimitiveKind;
+} | {
+    kind: 'date';
+    iso: string;
+} | {
+    kind: 'array';
+    length: number;
+    item: SemanticJsonNode | null;
+} | {
+    kind: 'object';
+    keys: Record<string, SemanticJsonNode>;
+} | {
+    kind: 'reference';
+    reused: true;
+} | {
+    kind: 'truncated';
+    maxDepthExceeded: true;
+} | {
+    kind: 'nonSerializable';
+    description: string;
+};
+/**
+ * Options for building the tree.
+ */
+export interface BuildSemanticStateTreeOptions {
+    /**
+     * Maximum nesting depth (root counts as depth 0).
+     */
+    maxDepth?: number;
+    /**
+     * Maximum keys on a single object (the rest are listed as `__overflow`).
+     */
+    maxKeysPerObject?: number;
+}
+/**
+ * Build a semantic tree from an arbitrary state snapshot (root is a single node).
+ *
+ * @param {unknown} state - root state or any fragment
+ * @param {BuildSemanticStateTreeOptions} [options] - depth and key-count limits
+ * @returns {SemanticJsonNode} tree serializable to JSON
+ */
+export declare function buildSemanticStateTree(state: unknown, options?: BuildSemanticStateTreeOptions): SemanticJsonNode;
+/**
+ * Build a semantic tree from the store's current state.
+ *
+ * @template S - store state type
+ * @template A - store action type
+ * @param {Store<S, A>} store - store instance from `createStore`
+ * @param {BuildSemanticStateTreeOptions} [options] - depth and key-count limits
+ * @returns {SemanticJsonNode} state tree
+ */
+export declare function buildSemanticStateTreeFromStore<S, A extends Action = Action>(store: Store<S, A>, options?: BuildSemanticStateTreeOptions): SemanticJsonNode;
+/**
+ * Build a semantic tree from a reducer map and a matching initial state.
+ * Keys of `reducerMap` and `initialState` must match as sets (otherwise an error is thrown).
+ *
+ * @param {Record<string, Reducer<unknown, Action>>} reducerMap - map of slice names to reducers
+ * @param {Record<string, unknown>} initialState - initial state with the same keys
+ * @param {BuildSemanticStateTreeOptions} [options] - depth and key-count limits
+ * @returns {SemanticJsonNode} state tree
+ */
+export declare function buildSemanticStateTreeFromReducerMap(reducerMap: Record<string, Reducer<unknown, Action>>, initialState: Record<string, unknown>, options?: BuildSemanticStateTreeOptions): SemanticJsonNode;
+/**
+ * Serialize a semantic tree to a JSON string (with indentation by default).
+ *
+ * @param {unknown} state - root state
+ * @param {BuildSemanticStateTreeOptions} [options] - tree options
+ * @param {number | string} [space] - indent for `JSON.stringify` (default 2)
+ * @returns {string} JSON string
+ */
+export declare function semanticStateTreeToJsonString(state: unknown, options?: BuildSemanticStateTreeOptions, space?: number | string): string;
+//# sourceMappingURL=semanticStateTree.d.ts.map

package/build/store/semanticStateTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticStateTree.d.ts","sourceRoot":"","sources":["../../src/store/semanticStateTree.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,yBAAyB,GACjC,MAAM,GACN,WAAW,GACX,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,yBAAyB,CAAC;CACtC,GACC;IACA,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb,GACC;IACA,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC/B,GACC;IACA,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACxC,GACC;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,IAAI,CAAC;CACd,GACC;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,gBAAgB,EAAE,IAAI,CAAC;CACxB,GACC;IACA,IAAI,EAAE,iBAAiB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEJ;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAwND;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,6BAA6B,GAAG,gBAAgB,CAIjH;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EAC1E,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB,CAElB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oCAAoC,CAClD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,EACpD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,OAAO,CAAC,EAAE,6BAA6B,GACtC,gBAAgB,CAwBlB;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,6BAA6B,EACvC,KAAK,GAAE,MAAM,GAAG,MAAU,GACzB,MAAM,CAGR"}

package/build/store/semanticStateTree.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Builds a semantic JSON tree from a store state snapshot / reducer map.
+ *
+ * Reducers at runtime do not describe data shape without initial state, so
+ * the walk is performed over the provided `initialState` (or `store.getState()`),
+ * and the `{ slice: reducer }` map is used to align slice keys with the root state.
+ *
+ * @module Effectable/store/semanticStateTree
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSemanticStateTree = buildSemanticStateTree;
+exports.buildSemanticStateTreeFromStore = buildSemanticStateTreeFromStore;
+exports.buildSemanticStateTreeFromReducerMap = buildSemanticStateTreeFromReducerMap;
+exports.semanticStateTreeToJsonString = semanticStateTreeToJsonString;
+const DEFAULT_MAX_DEPTH = 32;
+const DEFAULT_MAX_KEYS = 500;
+/**
+ * Resolve tree-building options.
+ *
+ * @param {BuildSemanticStateTreeOptions | undefined} options - user options
+ * @returns {ResolvedBuildSemanticStateTreeOptions} values with defaults
+ */
+function resolveOptions(options) {
+    const maxDepth = typeof options?.maxDepth === 'number' && Number.isFinite(options.maxDepth) && options.maxDepth >= 0
+        ? Math.floor(options.maxDepth)
+        : DEFAULT_MAX_DEPTH;
+    const maxKeysPerObject = typeof options?.maxKeysPerObject === 'number' &&
+        Number.isFinite(options.maxKeysPerObject) &&
+        options.maxKeysPerObject >= 1
+        ? Math.floor(options.maxKeysPerObject)
+        : DEFAULT_MAX_KEYS;
+    return {
+        maxDepth,
+        maxKeysPerObject,
+    };
+}
+/**
+ * Check for a “plain” object (not an array and not null).
+ *
+ * @param {unknown} value - value to check
+ * @returns {boolean} true if it is a plain object
+ */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto === null) {
+        return true;
+    }
+    if (proto === Object.prototype) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Build a tree node for an arbitrary value.
+ *
+ * @param {unknown} value - value from state
+ * @param {number} depth - current depth
+ * @param {WeakSet<object>} visited - already visited objects (for references)
+ * @param {ResolvedBuildSemanticStateTreeOptions} options - resolved options
+ * @returns {SemanticJsonNode} tree node
+ */
+function buildNode(value, depth, visited, options) {
+    if (depth > options.maxDepth) {
+        return {
+            kind: 'truncated',
+            maxDepthExceeded: true,
+        };
+    }
+    if (value === null) {
+        return {
+            kind: 'primitive',
+            valueType: 'null',
+        };
+    }
+    if (value === undefined) {
+        return {
+            kind: 'primitive',
+            valueType: 'undefined',
+        };
+    }
+    const typeofValue = typeof value;
+    if (typeofValue === 'boolean') {
+        return {
+            kind: 'primitive',
+            valueType: 'boolean',
+        };
+    }
+    if (typeofValue === 'number') {
+        return {
+            kind: 'primitive',
+            valueType: 'number',
+        };
+    }
+    if (typeofValue === 'string') {
+        return {
+            kind: 'primitive',
+            valueType: 'string',
+        };
+    }
+    if (typeofValue === 'bigint') {
+        return {
+            kind: 'primitive',
+            valueType: 'bigint',
+        };
+    }
+    if (typeofValue === 'symbol') {
+        return {
+            kind: 'primitive',
+            valueType: 'symbol',
+        };
+    }
+    if (typeofValue === 'function') {
+        return {
+            kind: 'nonSerializable',
+            description: 'function',
+        };
+    }
+    if (typeof value === 'object') {
+        if (value instanceof Date) {
+            return {
+                kind: 'date',
+                iso: value.toISOString(),
+            };
+        }
+        if (visited.has(value)) {
+            return {
+                kind: 'reference',
+                reused: true,
+            };
+        }
+        visited.add(value);
+        if (Array.isArray(value)) {
+            const length = value.length;
+            let item = null;
+            if (length > 0) {
+                item = buildNode(value[0], depth + 1, visited, options);
+            }
+            return {
+                kind: 'array',
+                length,
+                item,
+            };
+        }
+        if (isPlainObject(value)) {
+            const keys = Object.keys(value);
+            const keysOut = {};
+            const limit = options.maxKeysPerObject;
+            let processed = 0;
+            for (let i = 0; i < keys.length; i++) {
+                if (processed >= limit) {
+                    break;
+                }
+                const key = keys[i];
+                if (key === undefined) {
+                    continue;
+                }
+                if (!Object.hasOwn(value, key)) {
+                    continue;
+                }
+                const child = Reflect.get(value, key);
+                keysOut[key] = buildNode(child, depth + 1, visited, options);
+                processed = processed + 1;
+            }
+            const omitted = keys.length - processed;
+            if (omitted > 0) {
+                keysOut['__semanticOverflow'] = {
+                    kind: 'nonSerializable',
+                    description: `omitted keys: ${String(omitted)}`,
+                };
+            }
+            return {
+                kind: 'object',
+                keys: keysOut,
+            };
+        }
+        const ctor = value.constructor;
+        const name = ctor !== undefined && ctor !== null && typeof ctor.name === 'string' ? ctor.name : 'Object';
+        return {
+            kind: 'nonSerializable',
+            description: `instance:${name}`,
+        };
+    }
+    return {
+        kind: 'nonSerializable',
+        description: 'unknown',
+    };
+}
+/**
+ * Build a semantic tree from an arbitrary state snapshot (root is a single node).
+ *
+ * @param {unknown} state - root state or any fragment
+ * @param {BuildSemanticStateTreeOptions} [options] - depth and key-count limits
+ * @returns {SemanticJsonNode} tree serializable to JSON
+ */
+function buildSemanticStateTree(state, options) {
+    const resolved = resolveOptions(options);
+    const visited = new WeakSet();
+    return buildNode(state, 0, visited, resolved);
+}
+/**
+ * Build a semantic tree from the store's current state.
+ *
+ * @template S - store state type
+ * @template A - store action type
+ * @param {Store<S, A>} store - store instance from `createStore`
+ * @param {BuildSemanticStateTreeOptions} [options] - depth and key-count limits
+ * @returns {SemanticJsonNode} state tree
+ */
+function buildSemanticStateTreeFromStore(store, options) {
+    return buildSemanticStateTree(store.getState(), options);
+}
+/**
+ * Build a semantic tree from a reducer map and a matching initial state.
+ * Keys of `reducerMap` and `initialState` must match as sets (otherwise an error is thrown).
+ *
+ * @param {Record<string, Reducer<unknown, Action>>} reducerMap - map of slice names to reducers
+ * @param {Record<string, unknown>} initialState - initial state with the same keys
+ * @param {BuildSemanticStateTreeOptions} [options] - depth and key-count limits
+ * @returns {SemanticJsonNode} state tree
+ */
+function buildSemanticStateTreeFromReducerMap(reducerMap, initialState, options) {
+    const reducerKeys = Object.keys(reducerMap);
+    for (let i = 0; i < reducerKeys.length; i++) {
+        const key = reducerKeys[i];
+        if (key === undefined) {
+            continue;
+        }
+        if (!Object.hasOwn(initialState, key)) {
+            throw new Error(`buildSemanticStateTreeFromReducerMap: initialState does not contain key "${key}" from reducerMap`);
+        }
+    }
+    const stateKeys = Object.keys(initialState);
+    for (let i = 0; i < stateKeys.length; i++) {
+        const key = stateKeys[i];
+        if (key === undefined) {
+            continue;
+        }
+        if (!Object.hasOwn(reducerMap, key)) {
+            throw new Error(`buildSemanticStateTreeFromReducerMap: reducerMap does not contain key "${key}" from initialState`);
+        }
+    }
+    return buildSemanticStateTree(initialState, options);
+}
+/**
+ * Serialize a semantic tree to a JSON string (with indentation by default).
+ *
+ * @param {unknown} state - root state
+ * @param {BuildSemanticStateTreeOptions} [options] - tree options
+ * @param {number | string} [space] - indent for `JSON.stringify` (default 2)
+ * @returns {string} JSON string
+ */
+function semanticStateTreeToJsonString(state, options, space = 2) {
+    const tree = buildSemanticStateTree(state, options);
+    return JSON.stringify(tree, null, space);
+}
+//# sourceMappingURL=semanticStateTree.js.map

package/build/store/semanticStateTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semanticStateTree.js","sourceRoot":"","sources":["../../src/store/semanticStateTree.ts"],"names":[],"mappings":"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"}