Cascade - Simple State Management for Roblox-TS

Cascade is a lightweight state management library for Roblox-TS, designed to make handling state in your Roblox games simple and efficient. By focusing on the concept of "truth" and states that depend on it, Cascade ensures your game's state is always synchronized and easy to manage.

Features

• Simple API: Easy to understand and use, even for beginners.
• Lightweight: Does not burden your game with unnecessary complexity.
• Efficient State Management: Keeps your game's state synchronized effortlessly.

Installation

1. Install the package via npm:

npm install @rbxts/cascade

2. Include it in your Roblox-TS project:

import { Cascade } from "@rbxts/cascade";

Quick Start

Defining the truth and state

interface PlayerTruth {
	health: number;
	experience: number;
}

interface PlayerState extends PlayerTruth {
	isAlive: boolean;
	level: number;
}

Creating a Cascade store

const initialTruth: PlayerTruth = {
	health: 100,
	experience: 0,
}

const reducer = (state: PlayerTruth): PlayerState => {
	return {
		...state,
		isAlive: state.health > 0,
		level: math.floor(state.experience / 100),
	};
};

const actions = {
    heal(state: PlayerTruth, amount: number) {
        state.health += amount;
    }
	takeDamage(state: PlayerTruth, amount: number) {
		state.health -= amount;
	},
	addExp(state: PlayerTruth, amount: number) {
		state.experience += amount;
	},
    levelUp(state: PlayerTruth) {
        state.experience += 100;
        state.health = 100;
    }
};

const store = new Cascade(initialTruth, reducer, actions);

Accessing state

const state = store.getState();
print(state.isAlive);
print(state.level);

Modifying state through actions

store.takeDamage(20);
store.addExp(50);

Observing state changes

const aliveSelector = createSelector((state: PlayerState) => state.isAlive);
const levelUpSelector = createSelector((state: PlayerState) => (state), (previous, current) => previous.level !== current.level);

store.observe(aliveSelector, (isAlive) => {
    if (!isAlive) {
        print("Player died!");
    }
});
store.observe(levelUpSelector, (state) => {
    print(`Player reached level ${state.level}!`);
});

Subscribing to all state changes

store.subscribe((state) => {
    print(`Player health: ${state.health}`);
    print(`Player level: ${state.level}`);
});

One-time observations and subscriptions

store.observeOnce(aliveSelector, (isAlive) => {
    if (!isAlive) {
        print("Player died for the first time!");
    }
});

store.subscribeOnce((state) => {
    print(`Player reached level ${state.level} for the first time!`);
});

Cleanup

store.destroy();

API Reference

Cascade<T, S, A>

• constructor(truth: T, reducer: (state: T) => S, actions: A)
• getState(): S - Returns the current state.
• getTruth(): T - Returns the current truth.
• observe<U>(selector: Selector<U>, callback: (value: U) => void): RBXScriptConnection - Observes changes to a specific part of the state.
• subscribe(callback: (state: S) => void): RBXScriptConnection - Subscribes to all state changes.
• observeOnce<U>(selector: Selector<U>, callback: (value: U) => void): RBXScriptConnection - Observes changes to a specific part of the state once.
• subscribeOnce(callback: (state: S) => void): RBXScriptConnection - Subscribes to all state changes once.
• destroy(): void - Destroys the store and cleans up all subscriptions.

createSelector<State, U>(selector: (state: State) => U, didChange?: (previous: U, current: U, lastState: State, newState: State) => boolean): Selector<U>

Creates a selector for observing a specific part of the state.

License

Cascade is released under the MIT License. See LICENSE for more information.