rx-tiny-flux 1.0.0

package/examples/counter.js

@@ -0,0 +1,132 @@
+import {
+  Store,
+  createAction,
+  createReducer,
+  createEffect,
+  on,
+  anyAction,
+  createFeatureSelector,
+  createSelector,
+  ofType,
+  concatMap,
+  from,
+  map,
+} from '../dist/rx-tiny-flux.esm.js'; // Pointing to the built file for a realistic test
+
+// 1. ESTADO INICIAL
+// The Store can start with an empty state.
+const initialState = {};
+
+// 2. AÇÕES
+// We create "messages" that describe events in the application.
+const increment = createAction('[Counter] Increment');
+const decrement = createAction('[Counter] Decrement');
+const incrementAsync = createAction('[Counter] Increment Async');
+const incrementSuccess = createAction('[Counter] Increment Success');
+
+// 3. REDUTORES
+// Pure functions that calculate the new state based on the previous state and an action.
+
+// This reducer manages the 'counter' slice of the state.
+const counterReducer = createReducer(
+  'counter',
+  { value: 0, lastUpdate: null }, // 1. Initial state for this slice.
+  on(increment, incrementSuccess, (state) => ({
+    ...state,
+    value: state.value + 1,
+    lastUpdate: new Date().toISOString(),
+  })),
+  on(decrement, (state) => ({
+    ...state,
+    value: state.value - 1,
+    lastUpdate: new Date().toISOString(),
+  }))
+);
+
+// This reducer manages the 'log' slice. It reacts to ANY action.
+const logReducer = createReducer(
+  'log',
+  [], // Initial state for this slice
+  // Using the `anyAction` token to create a handler that catches all actions.
+  on(anyAction, (state, action) => [...state, `Action: ${action.type} at ${new Date().toISOString()}`])
+);
+
+// 4. EFEITOS
+// Handle side effects, such as asynchronous calls.
+
+// Let's create a function that simulates an API call returning a Promise.
+const fakeApiCall = () => {
+  console.log('-> [Effect] Starting fake API call...');
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      console.log('<- [Effect] Fake API call finished.');
+      resolve({ success: true }); // The API returns a success object
+    }, 1000);
+  });
+};
+
+const incrementAsyncEffect = createEffect((actions$) =>
+  actions$.pipe(
+    ofType(incrementAsync), // Listens only for the 'incrementAsync' action
+    // Use concatMap to handle the async operation. It waits for the inner Observable to complete.
+    concatMap(() => from(fakeApiCall()).pipe( // `from` converts the Promise into an Observable
+      map(() => incrementSuccess()) // On success, map the result to a new action
+    ))
+  )
+);
+
+// 5. SELETORES
+// Functions to extract specific pieces of state.
+
+// 5.1. We use `createFeatureSelector` to get a top-level slice of the state.
+const selectCounterSlice = createFeatureSelector('counter');
+
+// 5.2. We use `createSelector` to compose and extract more granular data from the slice.
+const selectCounterValue = createSelector(
+  selectCounterSlice,
+  (counter) => counter?.value // Added 'optional chaining' for safety
+);
+
+const selectLastUpdate = createSelector(
+  selectCounterSlice,
+  (counter) => counter?.lastUpdate
+);
+
+// 6. STORE SETUP
+const store = new Store(initialState);
+store.registerReducers(counterReducer, logReducer);
+store.registerEffects(incrementAsyncEffect);
+
+// 7. USING THE STORE
+// We subscribe to the selector to observe changes in the counter's value.
+// It's crucial to capture the subscription object so we can unsubscribe later.
+const counterSubscription = store.select(selectCounterValue).subscribe((value) => {
+  console.log(`Counter value is now: ${value}`);
+});
+
+// Let's also subscribe to the log to see all actions
+const logSubscription = store.select((state) => state.log).subscribe((log) => {
+  console.log('--- Action Log ---');
+  console.log(log.join('\n'));
+});
+
+// 8. DISPATCHING ACTIONS
+console.log('Dispatching actions...');
+store.dispatch(increment());
+store.dispatch(increment());
+store.dispatch(incrementAsync()); // Will trigger the effect and update the counter after 1s.
+
+// 9. CLEANUP (Unsubscribing)
+// In a real application (like a component in a UI framework or a long-running service),
+// you must unsubscribe from subscriptions to prevent memory leaks when they are no longer needed.
+// In this simple script, the process would exit anyway, but we demonstrate the practice here
+// by unsubscribing after a few seconds.
+setTimeout(() => {
+  console.log('\n--- Cleaning up subscriptions ---');
+  counterSubscription.unsubscribe();
+  logSubscription.unsubscribe();
+  console.log('Subscriptions cleaned up. Further state changes will not be logged to the console.');
+
+  // This action will still be processed by the store, but our subscriptions won't react to it.
+  store.dispatch(increment());
+}, 2000);

package/jsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es6",
+    "checkJs": true
+  },
+  "exclude": ["node_modules", "**/node_modules/*"]
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "rx-tiny-flux",
+  "version": "1.0.0",
+  "description": "A lightweight, minimalist state management library for pure JavaScript projects, inspired by NgRx and Redux, and built with RxJS.",
+  "author": "Bernardo Baumblatt <baumblatt@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baumblatt/rx-tiny-flux.git"
+  },
+  "keywords": [
+    "rxjs",
+    "state-management",
+    "redux",
+    "ngrx",
+    "flux",
+    "zeppos",
+    "tiny",
+    "lightweight"
+  ],
+  "type": "module",
+  "main": "dist/rx-tiny-flux.esm.js",
+  "zeppos": true,
+  "exports": {
+    ".": "./dist/rx-tiny-flux.esm.js",
+    "./zeppos": "./dist/zeppos.esm.js"
+  },
+  "scripts": {
+    "start": "node examples/counter.js",
+    "build": "rollup -c"
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "rollup": "^4.9.6",
+    "rxjs": "^7.8.2"
+  }
+}

package/rollup.config.js

@@ -0,0 +1,43 @@
+import { nodeResolve } from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import terser from '@rollup/plugin-terser';
+import json from '@rollup/plugin-json';
+
+export default [
+  // Main library bundle
+  {
+    input: 'src/index.js',
+    output: [
+      {
+        file: 'dist/rx-tiny-flux.esm.js',
+        format: 'es',
+        sourcemap: false,
+      },
+      {
+        file: 'dist/rx-tiny-flux.esm.min.js',
+        format: 'es',
+        sourcemap: false,
+        plugins: [terser()],
+      },
+    ],
+    plugins: [json(), nodeResolve(), commonjs()],
+  },
+  // Third entry point for ZeppOS plugin
+  {
+    input: 'src/zeppos.js',
+    output: [
+      {
+        file: 'dist/zeppos.esm.js',
+        format: 'es',
+        sourcemap: false,
+      },
+      {
+        file: 'dist/zeppos.esm.min.js',
+        format: 'es',
+        sourcemap: false,
+        plugins: [terser()],
+      },
+    ],
+    plugins: [json(), nodeResolve(), commonjs()],
+  },
+];

package/src/actions.js

@@ -0,0 +1,16 @@
+/**
+ * @typedef {Object} Action
+ * @property {string} type - The action type, a unique string describing it.
+ * @property {any} [payload] - The data associated with the action.
+ */
+
+/**
+ * Factory function to create an action.
+ * @param {string} type - The action type.
+ * @returns {function(any=): Action} A function that creates the action with an optional payload.
+ */
+export function createAction(type) {
+  const actionCreator = (payload) => ({ type, payload });
+  actionCreator.type = type; // Attaches the type directly to the function for easy access
+  return actionCreator;
+}

package/src/effects.js

@@ -0,0 +1,33 @@
+import { filter } from 'rxjs';
+
+/**
+ * @typedef {import('./actions').Action} Action
+ * @typedef {import('rxjs').Observable<Action>} ActionStream
+ */
+
+/**
+ * Custom RxJS operator to filter actions by type.
+ * @param {...(function(any=): Action)} actionCreators - The action creators whose types will be used for filtering.
+ * @returns {import('rxjs').OperatorFunction<Action, Action>}
+ */
+export function ofType(...actionCreators) {
+  // Extracts the 'type' string from each action creator passed as an argument.
+  const allowedTypes = actionCreators.map(creator => creator.type);
+
+  return filter(action => allowedTypes.includes(action.type));
+}
+
+/**
+ * Factory function to create an effect.
+ * An effect is a function that receives the stream of all actions
+ * and returns a new stream of actions to be dispatched.
+ *
+ * @param {function(ActionStream): ActionStream} effectFn
+ * @returns {function(ActionStream): ActionStream} The effect function.
+ */
+export function createEffect(effectFn) {
+  if (typeof effectFn !== 'function') {
+    throw new Error('Effect must be a function.');
+  }
+  return effectFn;
+}

package/src/index.js

@@ -0,0 +1,8 @@
+export { Store } from './store.js';
+export { createAction } from './actions.js';
+export { createReducer, on, anyAction } from './reducers.js';
+export { createEffect, ofType } from './effects.js';
+export { createSelector, createFeatureSelector } from './selectors.js';
+
+// Re-export RxJS operators from the main entry point
+export * from './rxjs.js';

package/src/reducers.js

@@ -0,0 +1,67 @@
+/**
+ * @typedef {import('./actions').Action} Action
+ */
+
+/**
+ * A token to be used with `on` to catch any action.
+ */
+export function anyAction() {}
+
+/**
+ * Associates one or more action creators with a reducer function.
+ * @param {...(function|function(any, Action): any)} args - A list of action creators, followed by the reducer function.
+ * @returns {{ types: string[], reducerFn: function(any, Action): any }}
+ */
+export function on(...args) {
+  // The last argument is the reducer function.
+  const reducerFn = args.pop();
+  // All previous arguments are the action creators.
+  const actionCreators = args;
+
+  // Checks if the `anyAction` token was used.
+  const isCatchAll = actionCreators.includes(anyAction);
+  if (isCatchAll && actionCreators.length > 1) {
+    throw new Error('The `anyAction` token cannot be mixed with other action creators in a single `on` handler.');
+  }
+
+  const types = actionCreators.map(creator => creator.type);
+  return { types, reducerFn, isCatchAll };
+}
+
+/**
+ * Factory function to create a reducer.
+ * A reducer is associated with a key that defines which top-level property of the state it manages.
+ *
+ * @param {string} featureKey - The key for the state slice this reducer manages.
+ * @param {any} initialState - The initial state for this state slice.
+ * @param  {...{ types: string[], reducerFn: function(any, Action): any }} ons - A list of handlers created with the `on` function.
+ * @returns {{path: string, initialState: any, reducerFn: function(any, Action): any}} The reducer object.
+ */
+export function createReducer(featureKey, initialState, ...ons) {
+  if (!featureKey || typeof featureKey !== 'string') {
+    throw new Error('Reducer featureKey must be a non-empty string.');
+  }
+
+  // Separates specific handlers from generic (catch-all) ones.
+  const specificHandlers = ons.filter(o => !o.isCatchAll);
+  const catchAllHandler = ons.find(o => o.isCatchAll);
+
+  const reducerFn = (state = initialState, action) => {
+    // First, try to find a specific 'on' handler for the action.
+    for (const handler of specificHandlers) {
+      if (handler.types.includes(action.type)) {
+        return handler.reducerFn(state, action);
+      }
+    }
+
+    // If no specific handler matches, execute the 'any' handler, if it exists.
+    if (catchAllHandler) {
+      return catchAllHandler.reducerFn(state, action);
+    }
+
+    // If nothing matches, return the state unchanged.
+    return state;
+  };
+
+  return { path: featureKey, initialState, reducerFn };
+}

package/src/rxjs.js

@@ -0,0 +1,20 @@
+// This file acts as a secondary entry point for re-exporting
+// a curated set of RxJS functionalities. This allows consumers
+// of the library to import them via `rx-tiny-flux/rxjs`.
+
+export {
+	// Operators
+	map,
+	concatMap,
+	switchMap,
+	exhaustMap,
+	mergeMap,
+	delay,
+	filter,
+	tap,
+	catchError,
+	// Creation Functions
+	defer,
+	from,
+	of,
+} from 'rxjs';

package/src/selectors.js

@@ -0,0 +1,39 @@
+/**
+ * Creates a selector function that extracts a top-level state slice (feature) using a key.
+ * It is analogous to NgRx's `createFeatureSelector`.
+ *
+ * @param {string} featureKey - The key for the top-level feature in the state object.
+ * @param {function(any): any} [projectionFn] - An optional function to transform the selected value.
+ * @returns {function(object): any} A function that receives the complete state and returns the selected part.
+ */
+export function createFeatureSelector(featureKey, projectionFn) {
+  return (state) => {
+    const selectedValue = state[featureKey];
+    // If a projection function was provided, apply it to the value. Otherwise, return the value directly.
+    return projectionFn ? projectionFn(selectedValue) : selectedValue;
+  };
+}
+
+/**
+ * Creates a selector function that can compose multiple selectors, whose results
+ * are passed as arguments to a final projection function.
+ * It is analogous to NgRx's `createSelector`.
+ *
+ * @param {...Function} args - A list of input selector functions, followed by a projection function.
+ * @returns {function(object): any} The final composed selector function.
+ */
+export function createSelector(...args) {
+  // The last argument is always the projection function.
+  const projectionFn = args.pop();
+  // All previous arguments are the input selectors.
+  const inputSelectors = args;
+
+  if (typeof projectionFn !== 'function') {
+    throw new Error('The last argument to createSelector must be a projection function.');
+  }
+
+  return (state) => {
+    const inputs = inputSelectors.map(selector => selector(state));
+    return projectionFn(...inputs);
+  }
+}

package/src/store.js

@@ -0,0 +1,125 @@
+import { BehaviorSubject, Subject, merge } from 'rxjs';
+import { scan, shareReplay, startWith, tap, distinctUntilChanged, map } from 'rxjs/operators';
+
+/**
+ * @typedef {import('./actions').Action} Action
+ */
+
+export class Store {
+  /**
+   * @private
+   * @type {BehaviorSubject<object>}
+   */
+  _state$;
+
+  /**
+   * @private
+   * @type {Subject<Action>}
+   */
+  _actions$ = new Subject();
+
+  /**
+   * @private
+   * @type {Array<{path: string, initialState: any, reducerFn: function(any, Action): any}>}
+   */
+  _reducers = [];
+
+  /**
+   * @param {object} initialState - The initial state of the application.
+   */
+  constructor(initialState = {}) {
+    // The initial state is now deep-cloned to prevent external mutations.
+    // `structuredClone` is modern and ideal, but `JSON.parse` is a safe fallback.
+    const initialStoreState = typeof structuredClone === 'function' ? structuredClone(initialState) : JSON.parse(JSON.stringify(initialState));
+    this._state$ = new BehaviorSubject(initialStoreState);
+
+    const dispatcher$ = this._actions$.pipe(
+      // Optional: log for debugging
+      tap((action) => console.log('Action Dispatched:', action))
+    );
+
+    const state$ = dispatcher$.pipe(
+      scan((currentState, action) => {
+        // Clones the state to ensure immutability.
+        // For larger apps, a library like `lodash.cloneDeep` would be more robust.
+        const nextState = JSON.parse(JSON.stringify(currentState));
+
+        this._reducers.forEach(({ path: featureKey, reducerFn }) => {
+          // Gets the current state slice.
+          const stateSlice = nextState[featureKey];
+
+          // Executes the reducer to get the new slice.
+          const nextStateSlice = reducerFn(stateSlice, action);
+
+          // If the reducer returned a new value (not undefined) and it's different from the previous one,
+          // apply the change to the state object.
+          if (nextStateSlice !== undefined && stateSlice !== nextStateSlice) {
+            // Directly assign the new slice to the corresponding key in the state.
+            nextState[featureKey] = nextStateSlice;
+          }
+        });
+
+        return nextState;
+      }, initialStoreState),
+      startWith(initialState),
+      // Ensures new subscribers receive the last emitted state and shares the execution.
+      shareReplay(1)
+    );
+
+    // Connects the calculated state stream back to our main BehaviorSubject.
+    state$.subscribe(this._state$);
+  }
+
+  /**
+   * Registers reducers in the store.
+   * @param {...{path: string, initialState: any, reducerFn: function(any, Action): any}} reducers
+   */
+  registerReducers(...reducers) {
+    this._reducers.push(...reducers);
+
+    // Builds the initial state from the registered reducers
+    const currentState = this._state$.getValue();
+    const nextState = JSON.parse(JSON.stringify(currentState));
+
+    reducers.forEach(({ path: featureKey, initialState }) => {
+      // If the state slice has not been defined yet, apply the reducer's initial state.
+      if (nextState[featureKey] === undefined) {
+        nextState[featureKey] = initialState;
+      }
+    });
+
+    // Emits the new constructed state
+    this._state$.next(nextState);
+  }
+
+  /**
+   * Registers effects in the store.
+   * @param {...function(import('rxjs').Observable<Action>): import('rxjs').Observable<Action>} effects
+   */
+  registerEffects(...effects) {
+    const effectStreams = effects.map((effect) => effect(this._actions$));
+    // Merges all action streams returned by the effects and dispatches them back into the store.
+    merge(...effectStreams).subscribe((action) => this.dispatch(action));
+  }
+
+  /**
+   * Dispatches an action to the store, initiating the state update cycle.
+   * @param {Action} action
+   */
+  dispatch(action) {
+    this._actions$.next(action);
+  }
+
+  /**
+   * Selects a slice of the state and returns it as an Observable.
+   * @param {function(object): any} selectorFn - The selector function.
+   * @returns {import('rxjs').Observable<any>}
+   */
+  select(selectorFn) {
+    return this._state$.pipe(
+      map(state => selectorFn(state)),
+      // Emits only when the selected value has actually changed.
+      distinctUntilChanged()
+    );
+  }
+}

package/src/utils.js

@@ -0,0 +1,25 @@
+import jsonpath from 'jsonpath';
+
+/**
+ * Sets a value in an object using a jsonpath expression,
+ * creating the nested path if it doesn't exist.
+ * This function modifies the input object.
+ *
+ * @param {object} obj The object to be modified.
+ * @param {string} path The jsonpath expression.
+ * @param {any} value The value to be set.
+ */
+export function setValueByPath(obj, path, value) {
+    // Tries to set the value. If the path doesn't exist, the `value` function with 3 arguments returns undefined.
+    if (jsonpath.value(obj, path, value) === undefined) {
+        const pathComponents = jsonpath.parse(path);
+        // Removes the last component to get the "parent" path.
+        pathComponents.pop();
+        const parentPath = jsonpath.stringify(pathComponents);
+
+        // Recursively calls the function to ensure the parent path exists,
+        // setting it as an empty object before trying to set the final value.
+        setValueByPath(obj, parentPath, {});
+        jsonpath.value(obj, path, value);
+    }
+}

package/src/zeppos.js

@@ -0,0 +1,62 @@
+/**
+ * @file zeppos.js
+ * @description A smart plugin factory for integrating rx-tiny-flux with ZeppOS (via ZML).
+ * It exposes `dispatch` and a lifecycle-aware `subscribe` method,
+ * automatically handling unsubscriptions during the `onDestroy` lifecycle hook
+ * to prevent memory leaks.
+ */
+
+/**
+ * Factory function that creates the store plugin for ZML's BaseApp/BasePage.
+ * @param {object} instance - The App or Page instance (injected by ZML's plugin service).
+ * @param {object} store - The store instance from `rx-tiny-flux` passed via `.use(plugin, store)`.
+ * @returns {object} A mixin object with methods and lifecycle hooks to be merged.
+ */
+function storePlugin(instance, store) {
+  if (!store) {
+    console.error('[rx-tiny-flux] StorePlugin Error: Store instance was not provided on .use()');
+    return {};
+  }
+
+  return {
+    /**
+     * A proxy to the store's dispatch method.
+     * @param {object} action - The action to be dispatched to the store.
+     */
+    dispatch: store.dispatch.bind(store),
+
+    /**
+     * Subscribes to a selector and automatically manages the subscription's lifecycle.
+     * @param {Function} selector - A function that selects a slice of the state.
+     * @param {Function} callback - The function to execute when the selected state changes.
+     * @returns {object} The subscription object, allowing for manual unsubscription if needed.
+     */
+    subscribe(selector, callback) {
+      // 'this' refers to the App/Page instance.
+      // Initialize an internal array to hold subscriptions if it doesn't exist.
+      if (!this._subscriptions) {
+        this._subscriptions = [];
+      }
+
+      const subscription = store.select(selector).subscribe(callback);
+      this._subscriptions.push(subscription);
+
+      // Return the subscription object in case the developer needs to unsubscribe manually.
+      return subscription;
+    },
+    /**
+     * Lifecycle hook that will be merged and called during the instance's destruction.
+     * This is the core of the automatic memory management feature.
+     */
+    onDestroy() {
+      // 'this' refers to the App/Page instance.
+      if (this._subscriptions && this._subscriptions.length > 0) {
+        // console.log(`[rx-tiny-flux] Unsubscribing from ${this._subscriptions.length} subscriptions.`);
+        this._subscriptions.forEach((sub) => sub.unsubscribe());
+        this._subscriptions = []; // Clear the array.
+      }
+    },
+  };
+}
+
+export { storePlugin };