{"id":15013179,"url":"https://github.com/bitecraft/rustato","last_synced_at":"2025-04-12T04:21:16.754Z","repository":{"id":252594936,"uuid":"840890278","full_name":"BiteCraft/rustato","owner":"BiteCraft","description":"Rustato: A powerful, thread-safe global state management library for Rust applications, offering type-safe, reactive state handling with an easy-to-use macro-based API.","archived":false,"fork":false,"pushed_at":"2024-08-12T05:31:28.000Z","size":593,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T11:19:54.787Z","etag":null,"topics":["application-state","cli-tools","desktop-apps","event-system","global-state","macros","multithreading","performance","reactive","rust","rust-library","state-management","tauri","thread-safe","type-safe","web-servers"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BiteCraft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["BiteCraft"],"patreon":"bitecraft","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"custom":null}},"created_at":"2024-08-11T02:17:23.000Z","updated_at":"2025-02-08T18:09:02.000Z","dependencies_parsed_at":"2024-09-24T19:58:34.371Z","dependency_job_id":"8501d2f9-b8f2-45f3-8f4e-6dfc61ddc2d4","html_url":"https://github.com/BiteCraft/rustato","commit_stats":{"total_commits":13,"total_committers":1,"mean_commits":13.0,"dds":0.0,"last_synced_commit":"29c1f1f19c80ad1ef00dd2f867b65a6d6aeb2740"},"previous_names":["bitecraft/rustato"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BiteCraft%2Frustato","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BiteCraft%2Frustato/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BiteCraft%2Frustato/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BiteCraft%2Frustato/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BiteCraft","download_url":"https://codeload.github.com/BiteCraft/rustato/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248514414,"owners_count":21116962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["application-state","cli-tools","desktop-apps","event-system","global-state","macros","multithreading","performance","reactive","rust","rust-library","state-management","tauri","thread-safe","type-safe","web-servers"],"created_at":"2024-09-24T19:43:51.840Z","updated_at":"2025-04-12T04:21:16.732Z","avatar_url":"https://github.com/BiteCraft.png","language":"Rust","readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cimg width=\"100%\" src=\"./rustato_logo.png\" alt=\"Coinbase Commerce Client\"\u003e\n  \u003cbr\u003e\n  Rustato State Manager\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003eA generical thread-safe global state manager for Rust\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg alt=\"Crates.io Version\" src=\"https://img.shields.io/crates/v/rustato\"\u003e\n    \u003cimg src=\"https://img.shields.io/crates/d/rustato\"  alt=\"Total Downloads\"\u003e\n    \u003cimg src=\"https://img.shields.io/crates/size/rustato\" alt=\"size\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/BiteCraft/rustato\" alt=\"License\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#introduction\"\u003eIntroduction\u003c/a\u003e •\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e •\n  \u003ca href=\"#advanced-usage\"\u003eAdvanced Usage\u003c/a\u003e •\n  \u003ca href=\"#api-reference\"\u003eApi Reference\u003c/a\u003e •\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\u003csub\u003eThis library is a global state management solution for Rust projects, inspired by state management concepts from various ecosystems. Our goal is to provide a robust and easy-to-use tool for Rust developers who need a centralized state management system in their applications.\u003c/sub\u003e\n\n## Table of Contents\n\n1. [Introduction](#introduction)\n2. [Features](#features)\n3. [Installation](#installation)\n4. [Usage](#usage)\n   - [Creating States](#creating-states)\n   - [Accessing States](#accessing-states)\n   - [Modifying States](#modifying-states)\n   - [Registering Callbacks](#registering-callbacks)\n5. [Advanced Usage](#advanced-usage)\n   - [Using with Tauri](#using-with-tauri)\n   - [Using in Multithreaded Applications](#using-in-multithreaded-applications)\n   - [Custom State Types](#custom-state-types)\n6. [API Reference](#api-reference)\n7. [Best Practices](#best-practices)\n8. [Contributing](#contributing)\n9. [License](#license)\n\n## Introduction\n\nThe Rustato Library is a powerful and flexible solution for managing application state in Rust projects. It provides a simple and intuitive API for creating, accessing, and modifying states, as well as registering callbacks for state changes. This library is particularly useful for applications that require a centralized state management system, such as desktop applications, web servers, or complex CLI tools.\n\n## Features\n\n- Global state management with a singleton pattern\n- Type-safe state creation and access\n- Automatic generation of getters and setters\n- Event system for state changes\n- Thread-safe state manipulation\n- Easy integration with existing Rust projects\n- Macro-based API for reduced boilerplate\n\n## Installation\n\nTo use the Rustato Library in your project, add the following to your `Cargo.toml`:\n\n```toml\n[dependencies]\nrustato = \"0.1.1\"\n```\n\nThen, add the following to your main Rust file:\n\n```rust\nuse rustato::*;\n```\n\n## Usage\n\n### Creating States\n\nTo create a new state, use the `create_state!` macro:\n\n```rust\nuse rustato::*;\n\ncreate_state!(struct AppState {\n    status: String,\n    window_visible: bool,\n    user_count: u32,\n});\n```\n\nThis macro creates a new struct `AppState` with the specified fields and registers it with the global state manager.\n\n### Accessing States\n\nTo access a state for read-only operations, use the `get_state!` macro and call the `read` mode:\n\n```rust\nlet app_state = get_state!(AppState).read();\n\nprintln!(\"Current status: {}\", app_state.status);\nprintln!(\"Window visible: {}\", app_state.window_visible);\nprintln!(\"User count: {}\", app_state.user_count);\n```\n\n\n### Modifying States\n\nTo modify a state, use the `get_state!` macro and call the `write` mode:\n\n```rust\nlet mut app_state = get_state!(AppState).write();\n\napp_state.status = \"Running\".to_string();\napp_state.window_visible = true;\napp_state.user_count = 42;\n```\n\n### Registering Callbacks\n\nTo register a callback that will be called when a state changes, use the `on_state_change!` macro:\n\n```rust\non_state_change!(CounterState, |field_changed: \u0026str, state: \u0026CounterState| {\n    println!(\"Field changed: {}\", field_changed);\n    println!(\"New counter value: {}\", state.counter);\n});\n```\n\n## Advanced Usage\n\n### Using with Tauri\n\nThe Rustato Library can be easily integrated with Tauri applications. Here's an example of how to use it in a Tauri app:\n\n```rust\nuse rustato::*;\nuse tauri::Manager;\n\n#[tauri::command]\nfn increment_counter() -\u003e i32 {\n    let mut app_state = get_state!(AppState).write();\n    let new_value = app_state.counter + 1;\n    app_state.counter = new_value;\n    new_value\n}\n\nfn main() {\n    create_state!(AppState {\n        counter: i32,\n    });\n\n    tauri::Builder::default()\n        .setup(|app| {\n            let app_handle = app.handle();\n            on_state_change!(AppState, |field_changed: \u0026str, state: \u0026CounterState| {\n                if field_changed == \"counter\" {\n                    app_handle.emit_all(\"counter-changed\", state.counter).unwrap();\n                }\n            });\n            Ok(())\n        })\n        .invoke_handler(tauri::generate_handler![increment_counter])\n        .run(tauri::generate_context!())\n        .expect(\"error while running tauri application\");\n}\n```\n\nIn this example, we create an `AppState` with a `counter` field. We register a callback that emits a Tauri event whenever the counter changes. The `increment_counter` function is exposed as a Tauri command that increments the counter and returns the new value.\n\n### Using in Multithreaded Applications\n\nThe Rustato Library is designed to be thread-safe. Here's an example of using it in a multithreaded application:\n\n```rust\nuse rustato::*;\nuse std::thread;\n\nfn main() {\n    create_state!(struct SharedState {\n        value: i32,\n    });\n\n    let handles: Vec\u003c_\u003e = (0..10).map(|i| {\n        thread::spawn(move || {\n            let mut state = get_state!(SharedState).write();\n            state.value += i;\n        })\n    }).collect();\n\n    for handle in handles {\n        handle.join().unwrap();\n    }\n\n    let final_state = get_state!(SharedState).read();\n    println!(\"Final value: {}\", final_state.value);\n}\n```\n\nIn this example, we create 10 threads that all modify the same shared state. The library ensures that these modifications are thread-safe.\n\n### Custom State Types\n\nYou can use custom types in your states as long as they implement the necessary traits. Here's an example:\n\n\n```rust\nuse rustato::*;\n\n#[derive(Clone, Default)]\nstruct User {\n    id: u64,\n    name: String,\n    email: String,\n}\n\ncreate_state!(struct UserState {\n    current_user: User,\n    logged_in: bool,\n});\n\nfn main() {\n    {\n        let mut state = get_state!(UserState).write();\n        state.current_user = User {\n            id: 1,\n            name: \"John Doe\".to_string(),\n            email: \"john@example.com\".to_string(),\n        };\n        state.logged_in = true;\n    }\n\n    let user_state = get_state!(UserState).read();\n    println!(\"Current user: {:?}\", user_state.current_user);\n    println!(\"Logged in: {}\", user_state.logged_in);\n}\n```\n\n## API Reference\n\n### Macros\n\n- `create_state!(struct_definition)`: Creates a new state with the given ID and struct definition.\n- `get_state!(struct_definition).read() -\u003e \u0026State`: Returns a reference to the state with the given struct definition.\n- `get_state!(struct_definition).write() -\u003e \u0026mut State`: Returns a mutable reference to the state with the given struct definition.\n- `on_state_change!(struct_definition, callback: Fn(\u0026str, \u0026State))`: Registers a callback to be called when the state with the given struct definition changes.\n\n### StateManager\n\n- `StateManager::new() -\u003e StateManager`: Creates a new StateManager instance.\n- `StateManager::register_state\u003cT: 'static + Clone + Send + Sync\u003e(\u0026self, id: \u0026str, state: T)`: Registers a new state with the given ID and initial value.\n- `StateManager::get_state\u003cT: 'static + Send + Sync\u003e(\u0026self, id: \u0026str) -\u003e Option\u003cState\u003cT\u003e\u003e`: Returns the state with the given ID, if it exists.\n- `StateManager::register_callback\u003cT: 'static + Send + Sync\u003e(\u0026self, id: \u0026str, callback: StateChangeCallback\u003cT\u003e)`: Registers a callback for the state with the given ID.\n- `StateManager::notify_state_change\u003cT: 'static + Send + Sync\u003e(\u0026self, id: \u0026str, field: \u0026str, state: \u0026T)`: Notifies registered callbacks about a state change.\n\n## Best Practices\n\n1. **State Granularity**: Create separate states for different parts of your application to improve performance and reduce unnecessary updates.\n\n2. **Immutable Access**: Use `get_state!(struct_definition).read()` when you only need to read state values to prevent accidental modifications.\n\n3. **Callback Efficiency**: Keep callbacks lightweight and avoid performing heavy computations or I/O operations directly in the callback. Instead, use the callback to trigger other parts of your application.\n\n4. **State Initialization**: Initialize your states as early as possible in your application lifecycle, preferably during the setup phase.\n\n5. **Error Handling**: Always handle potential errors when accessing states, especially when using `get_state!(struct_definition).read()` or `get_state!(struct_definition).write()` with an unknown struct definition.\n\n6. **Thread Safety**: While the library is designed to be thread-safe, be cautious when sharing state across threads and consider using appropriate synchronization primitives when necessary.\n\n7. **Testing**: Create unit tests for your state management logic to ensure that state changes and callbacks work as expected.\n\n## Contributing\n\nContributions to the Rustato Library are welcome! Please feel free to submit issues, fork the repository and send pull requests!\n\nWhen contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.\n\nPlease note we have a code of conduct, please follow it in all your interactions with the project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","funding_links":["https://github.com/sponsors/BiteCraft","https://patreon.com/bitecraft"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitecraft%2Frustato","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitecraft%2Frustato","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitecraft%2Frustato/lists"}