{"id":24511721,"url":"https://github.com/devnax/react-rock","last_synced_at":"2025-04-14T08:22:30.921Z","repository":{"id":248300447,"uuid":"824155406","full_name":"devnax/react-rock","owner":"devnax","description":"A lightweight and powerful state management library for React applications. Simplify global state management with advanced querying, CRUD operations, and selective re-rendering.","archived":false,"fork":false,"pushed_at":"2025-03-03T09:49:24.000Z","size":610,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-27T22:01:39.217Z","etag":null,"topics":["react","react-app","react-global-state","react-state-management"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/react-rock","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devnax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-07-04T13:25:30.000Z","updated_at":"2025-03-03T09:49:28.000Z","dependencies_parsed_at":"2025-01-22T00:40:58.861Z","dependency_job_id":"dcb0e7a4-5acb-41f0-9ec6-3c13ee4cd2b4","html_url":"https://github.com/devnax/react-rock","commit_stats":null,"previous_names":["devnax/react-rock"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devnax%2Freact-rock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devnax%2Freact-rock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devnax%2Freact-rock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devnax%2Freact-rock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devnax","download_url":"https://codeload.github.com/devnax/react-rock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248830396,"owners_count":21168272,"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":["react","react-app","react-global-state","react-state-management"],"created_at":"2025-01-22T00:40:55.799Z","updated_at":"2025-04-14T08:22:30.888Z","avatar_url":"https://github.com/devnax.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"120\" src=\"https://raw.githubusercontent.com/devnax/react-rock/main/logo.png\" alt=\"React Rock logo\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eReact Rock\u003c/h1\u003e\n\nReact-Rock is a lightweight package for managing global state in React applications. It simplifies handling data by providing a store with rows and metadata, while offering methods to perform CRUD operations and more. It enables easy integration with React components, making it an ideal solution for managing complex state in large applications.\n\n\n## Installation\n\nTo install the React-Rock package, run the following command in your project:\n\n```bash\nnpm install react-rock\n```\n\n## Features\n\n- **Global Store Management**: Manage rows and meta data in a global store.\n- **CRUD Operations**: Perform create, read, update, and delete operations on rows.\n- **Meta Management**: Set, get, and delete meta data.\n- **Optimized Re-renders**: Control component re-renders with the `freeze` option.\n- **Class Component Support**: Use the `StoreComponent` for integrating store data into class components.\n\n## Basic Example: Creating a Store and Adding Records\n\nTo create a new store and add a record, use the `createStore` function. Here's an example:\n\n```typescript\nimport { createStore } from 'react-rock';\n\n// Define RowType and MetaType\ntype RowType = { name: string, age: number };\ntype MetaType = { anykey: any };\n\nconst default_rows = [{ name: '', age: 0 }]\n// Create a store\nconst users = createStore\u003cRowType, MetaType\u003e(default_rows, { anykey: '' });\n\n// Add a new row to the store\nusers.create({ name: 'John Doe', age: 30 });\n```\n\n### RowType Explained\n\nWhen a row is created, it will have the following properties:\n\n```typescript\ntype RowType\u003cRow\u003e = Row \u0026 {\n    _id: string;       // Unique identifier for the row\n    _index: number;    // Index of the row in the store\n    _observe: number;  // Internal property to track changes\n}\n```\n\nEach row will include the original data (`Row`) and some additional properties like `_id`, `_index`, and `_observe`.\n\n## Methods\n\nHere’s a table with all available methods and their descriptions:\n\n| Method                          | Description                                                                                  |\n| ------------------------------- | -------------------------------------------------------------------------------------------- |\n| `create(row, freeze?)`          | Adds a new record to the store. Optionally, prevents re-rendering if `freeze` is `true`.     |\n| `createMany(rows, freeze?)`     | Adds multiple records to the store. Optionally, prevents re-rendering if `freeze` is `true`. |\n| `update(row, where, freeze?)`   | Updates records based on the condition specified in `where`.                                 |\n| `updateAll(row, freeze?)`       | Updates all records in the store. Optionally, prevents re-rendering if `freeze` is `true`.   |\n| `delete(where, freeze?)`        | Deletes records based on the condition specified in `where`.                                 |\n| `move(oldIdx, newIdx, freeze?)` | Moves a record from one index to another.                                                    |\n| `clearAll(freeze?)`             | Clears all records from the store. Optionally, prevents re-rendering if `freeze` is `true`.  |\n| `getAll(args?)`                 | Retrieves all rows from the store.                                                           |\n| `find(where, args?)`            | Finds rows based on a condition specified in `where`.                                        |\n| `findFirst(where, freeze?)`     | Finds the first row that matches the condition in `where`.                                   |\n| `findById(_id, freeze?)`        | Finds a row by its `_id`.                                                                    |\n| `setMeta(key, value, freeze?)`  | Sets a value for a specific meta key.                                                        |\n| `getMeta(key, freeze?)`         | Retrieves the value of a specific meta key.                                                  |\n| `getAllMeta(freeze?)`           | Retrieves all meta data from the store.                                                      |\n| `deleteMeta(key, freeze?)`      | Deletes a specific meta key.                                                                 |\n| `clearMeta(freeze?)`            | Clears all meta data from the store.                                                         |\n\n### Example of the `find` Method\n\nThe `find` method allows you to search for rows in the store based on specific conditions:\n\n```typescript\nconst foundUsers = users.find({ name: 'John Doe' } );\nconsole.log(foundUsers);\n```\n\n\n### Re-rendering in React Components\n\nReact-Rock optimizes re-renders by offering a freeze mechanism. When a store update occurs and the `freeze` option is enabled, React components that access the store using methods like `find` or `findFirst` will not automatically re-render. This gives you control over when your components should re-render, improving performance in large applications.\n\n\n## WhereType\n\nThe `WhereType` is used to specify conditions when querying rows. It defines a query structure for filtering rows.\n\n### QueryValueType\n\nThe `QueryValueType` is used within `WhereType` to define possible conditions for querying:\n\n| Property       | Description                                                       |\n| -------------- | ----------------------------------------------------------------- |\n| `contain`      | Finds values containing the specified string, number, or boolean. |\n| `startWith`    | Finds values that start with the specified string or number.      |\n| `endWith`      | Finds values that end with the specified string or number.        |\n| `equalWith`    | Finds values that are exactly equal to the specified value.       |\n| `notEqualWith` | Finds values that are not equal to the specified value.           |\n| `gt`           | Finds values greater than the specified number.                   |\n| `lt`           | Finds values less than the specified number.                      |\n| `gte`          | Finds values greater than or equal to the specified number.       |\n| `lte`          | Finds values less than or equal to the specified number.          |\n\n### Example of WhereType\n\n```typescript\nconst usersOver30 = users.find({ age: { gt: 30 } });\nconsole.log(usersOver30);\n```\n\n## ArgsType\n\nThe `ArgsType` defines options for customizing query behavior, such as selecting specific rows or skipping rows.\n\n| Property | Description                                               |\n| -------- | --------------------------------------------------------- |\n| `getRow` | Custom function to process rows before returning them.    |\n| `skip`   | Number of rows to skip.                                   |\n| `take`   | Number of rows to return.                                 |\n| `freeze` | If `true`, prevents re-rendering when accessing the data. |\n\n## Example with Class Component\n\nTo use the store in a class component, extend the `StoreComponent` class:\n\n```typescript\nimport { StoreComponent } from 'react-rock';\n\nclass UserList extends StoreComponent {\n    render() {\n        const allUsers = users.getAll();\n        return (\n            \u003cdiv\u003e\n                {allUsers.map(user =\u003e \u003cdiv key={user._id}\u003e{user.name}\u003c/div\u003e)}\n            \u003c/div\u003e\n        );\n    }\n}\n```\n\n## CRUD Example\n\n```typescript\n// Create a new user\nusers.create({ name: 'Alice', age: 25 });\n\n// Update a user\nusers.update({ age: 26 }, { name: 'Alice' } );\n\n// Delete a user\nusers.delete({ name: 'Alice' } );\n```\n\n## Examples with `find` and Query\n\n```typescript\n// Find users over the age of 25\nconst usersOver25 = users.find({ age: { gt: 25 } });\nconsole.log(usersOver25);\n\n// Find the first user with the name 'Alice'\nconst alice = users.findFirst({ name: 'Alice' } );\nconsole.log(alice);\n```\n\n## Example of Using the Store in Multiple Components\n\nReact-Rock allows you to share the same store across multiple components, ensuring a consistent state throughout the app:\n\n```typescript\nimport { StoreComponent } from 'react-rock';\n\nclass UserList extends StoreComponent {\n    render() {\n        const users = users.getAll();\n        return (\n            \u003cdiv\u003e\n                {users.map(user =\u003e \u003cdiv key={user._id}\u003e{user.name}\u003c/div\u003e)}\n            \u003c/div\u003e\n        );\n    }\n}\n\nclass UserProfile extends StoreComponent {\n    render() {\n        const user = users.findFirst({ name: 'John Doe' });\n        return \u003cdiv\u003e{user ? user.name : 'User not found'}\u003c/div\u003e;\n    }\n}\n```\n\n\n\n## Explanation of Types\n\n- **RowType**: Represents a record with an `_id`, `_index`, and `_observe` along with user-defined data fields.\n- **ArgsType**: Defines the options for querying rows with flexibility like skipping, taking, and custom row processing.\n- **WhereType**: Represents the conditions for querying records, using fields like `contain`, `equalWith`, and range queries like `gt`, `lt`, etc.\n- **QueryValueType**: Specifies the allowed condition types for filtering rows based on field values.\n\n\n## License\n\nThis package is licensed under the MIT License.\n\n---\n\nThis documentation should provide a concise overview of how to use the `react-rock` package effectively.\n\n## 🤝 Contributing\n\nContributions are welcome! Please check out the [contribution guidelines](https://github.com/devnax/react-rock).\n\n---\n\n## 📄 License\n\nThis project is licensed under the [MIT License](https://opensource.org/licenses/MIT).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevnax%2Freact-rock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevnax%2Freact-rock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevnax%2Freact-rock/lists"}