fysics

An Open Source Universe Project

Contents

• fysics
  • Contents
  • Features ✨
  • Install 🛠
  • Usage 🔭
  • Documentation 🛰
    • subject
    • subjectAll
    • subscribe
    • subscribeAll
    • get
    • getAll
    • dispatch
    • undo
    • redo
    • rebase
  • Contributing 🌎
  • License ⚖️

Features ✨

• Define a State Store
• Add Reducers & Actions to your State Store
• Define Async Side Effects via Saga Functions
• Create Bulk Actions by calling other Actions
• Subscribe to the State Object
• Subscribe to Deltas of the State Object
• Typescript Support

Install 🛠

npm install fysics

Usage 🔭

Read more about the Design behind fysics here.

import { createStore } from 'fysics';
// Create the store
const STORE = createStore({
 initialState: { count: 0 },
 actions: {
  INCREMENT: {
    reducer(state, { amount }) {
      state.count += amount ?? 1;
    }
  },
  DECREMENT: {
    reducer(state, { amount }) {
      state.count -= amount ?? 1;
    }
  },
  INCREMENT_SAGA: {
    async saga(state, { url }) {
      const response = await fetch(url);
      const { amount } = await response.data.json()
      return amount;
    },
    reducer(state, payload, { amount }) {
      state.count += amount ?? 1;
    }
  },
  DECREMENT_BULK: {
    reducer(state, { listOfAmounts }) {
      for (let amount of listOfAmounts) {
        this.DECREMENT.reducer(state, amount);
      }
    }
  }
 }
});
// And Use It :)
STORE.dispatch({ name: 'INCREMENT', payload: { amount: 5 } });
// { count: 5 }
STORE.dispatch({ name: 'DECREMENT_BULK', payload: { listOfAmounts: [2, 3] } });
// { count: 0 }
STORE.undo();
// { count: 5 }
const unsubscribe = STORE.subscribe((stateObject) => {
  console.log(stateObject);
});

Documentation 🛰

The Store returned by the createStore function is contains methods to interface with two internal components: the store's present state (of type State), and the store's full state, which is defined as

FullState<State, Payload>;

where

type FullState<State, Payload> = {
  past: Array<TimelineEvent<PayloadType>>;
  present: State;
  future: Array<TimelineEvent<PayloadType>>;
};

type TimelineEvent<Payload> = {
  action: DispatchAction<Payload>;
  patches: Array<Patch>;
  inversePatches: Array<Patch>;
};

type DispatchAction<Payload> = {
  name: string;
  payload?: Payload;
};

are the relevant type definitions. See here to understand the Patch type imported from immer.

subject

subject: () => Subject<State>;

Gets the subject for the store's present state.

subjectAll

subject: () => Subject<FullState<State, Payload>>;

Gets the subject for the store's full state.

subscribe

subscribe: (observer?: Partial<Observer<State>> | ((value: State) => void)) =>
  Subscription;

Creates a subscription to the store's present state with the specified observer or function to run when the store's present state subject pushes a new value (i.e. when the store's present state changes).

subscribeAll

subscribe: (observer?: Partial<Observer<State>> | ((value: State) => void)) =>
  Subscription;

Creates a subscription to the store's full state with the specified observer or function to run when the store's full state subject pushes a new value (i.e. when the store's full state changes).

get

get: () => State;

Returns a deep copy of the store's present state.

getAll

getAll: () => FullState<State, Payload>;

Returns a deep copy of the store's full state.

dispatch

dispatch: (action: DispatchAction<Payload>) => void

Dispatches an Action (see the Usage section) by name, with the provided payload.

undo

undo: () => void

Undoes actions in the store's past until an action with skipUndo: false is undone, or does nothing if all the actions in the store's past have skipUndo: true.

redo

redo: () => void

Redoes actions in the store's future until the second most recent action with skipUndo: false is on top of the stack, or redoes everything if there is no such action.

rebase

rebase: () => void

Clears the past and future of the store's full state.

Contributing 🌎

We would love for you to contribute your ideas, code, & fixes to fysics.

We encourage everyone to read our Design Document to learn more about the thought process behind fysics.

Also check out the rewards offered for contributing to the Open Source Universe.

License ⚖️

MIT