{"_id":"1cbyc-state-management","name":"1cbyc-state-management","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"1cbyc-state-management","version":"1.0.0","description":"A sophisticated state management library for complex web applications","main":"src/index.js","type":"module","scripts":{"test":"mocha test/**/*.js","test:watch":"mocha test/**/*.js --watch","test:coverage":"nyc mocha test/**/*.js","lint":"eslint src/**/*.js test/**/*.js","lint:fix":"eslint src/**/*.js test/**/*.js --fix","format":"prettier --write src/**/*.js test/**/*.js","format:check":"prettier --check src/**/*.js test/**/*.js","build":"echo 'No build step required for ES modules'","size-check":"echo 'Bundle size check - implement if needed'","prepublishOnly":"npm test && npm run lint && npm run format:check","prepare":"npm run lint && npm run format"},"keywords":["state-management","store","middleware","persistence","undo-redo","events","javascript","es6"],"author":{"name":"1cbyc","email":"github.com/1cbyc"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/1cbyc/1cbyc-state-management.git"},"bugs":{"url":"https://github.com/1cbyc/1cbyc-state-management/issues"},"homepage":"https://github.com/1cbyc/1cbyc-state-management#readme","devDependencies":{"chai":"^4.3.10","mocha":"^10.2.0","nyc":"^15.1.0","eslint":"^8.0.0","prettier":"^3.0.0"},"engines":{"node":">=14.0.0"},"_id":"1cbyc-state-management@1.0.0","gitHead":"0ee9aa9e0a6b3ea816294409b676676b01eec511","_nodeVersion":"22.17.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-y7nmKhWrhXNF3lMaM9fhVaxcKCsuuwPawbcZvohQBecbDdgFiyxcS6TIPSQ/K/0+JL5GtCojLwWTB1Ca1XrPPQ==","shasum":"fcb74cef978a20de02a5201ffbc75239f6255efb","tarball":"https://registry.npmjs.org/1cbyc-state-management/-/1cbyc-state-management-1.0.0.tgz","fileCount":6,"unpackedSize":31150,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHz5N9lmJO5qMl7Og5NJHR6/R3DBiJfcJMolJ+jkmhjYAiBSrsSoWJf5jtJx6LND0j8pEQSDeYgAfn095J5up6a22g=="}]},"_npmUser":{"name":"nsisong","email":"isaacnsisong@gmail.com"},"directories":{},"maintainers":[{"name":"nsisong","email":"isaacnsisong@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/1cbyc-state-management_1.0.0_1753313279219_0.9257160765766275"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-23T23:27:59.218Z","1.0.0":"2025-07-23T23:27:59.392Z","modified":"2025-07-23T23:27:59.643Z"},"maintainers":[{"name":"nsisong","email":"isaacnsisong@gmail.com"}],"description":"A sophisticated state management library for complex web applications","homepage":"https://github.com/1cbyc/1cbyc-state-management#readme","keywords":["state-management","store","middleware","persistence","undo-redo","events","javascript","es6"],"repository":{"type":"git","url":"git+https://github.com/1cbyc/1cbyc-state-management.git"},"author":{"name":"1cbyc","email":"github.com/1cbyc"},"bugs":{"url":"https://github.com/1cbyc/1cbyc-state-management/issues"},"license":"MIT","readme":"# 1cbyc State Management\n\nA sophisticated state management library for complex web applications with advanced features including middleware support, persistence, undo/redo functionality, and event-driven architecture.\n\n## Features\n\n- **Advanced State Management**: Robust state handling with deep cloning and comparison\n- **Middleware System**: Extensible middleware architecture for custom logic\n- **Event System**: Custom event handling and state change subscriptions\n- **Undo/Redo**: Complete state history management with undo/redo capabilities\n- **Persistence**: Local storage and file-based state persistence\n- **Performance Optimizations**: Debouncing, batch updates, and memory management\n- **Error Handling**: Comprehensive error handling with custom error handlers\n- **TypeScript Ready**: Full TypeScript support (coming soon)\n\n## Installation\n\n```bash\nnpm install 1cbyc-state-management\n```\n\n## Quick Start\n\n```javascript\nimport { StateManager, PersistenceMiddleware } from '1cbyc-state-management';\n\nconst store = new StateManager({ count: 0, user: null });\n\nstore.subscribe((state) => {\n  console.log('State updated:', state);\n});\n\nstore.setState({ count: 1, user: { name: 'John' } });\n```\n\n## Core Concepts\n\n### StateManager\n\nThe main state management class that handles all state operations.\n\n```javascript\nconst store = new StateManager(initialState);\n```\n\n#### Basic State Operations\n\n```javascript\n// Get current state\nconst state = store.getState();\n\n// Set new state\nstore.setState({ count: 1, name: 'test' });\n\n// Merge partial state\nstore.mergeState({ count: 2 });\n\n// Patch state with middleware processing\nstore.patchState({ name: 'updated' });\n```\n\n#### Subscription System\n\n```javascript\n// Subscribe to state changes\nconst unsubscribe = store.subscribe((state) => {\n  console.log('State changed:', state);\n});\n\n// Unsubscribe when done\nunsubscribe();\n```\n\n#### Event System\n\n```javascript\n// Listen for custom events\nconst unsubscribe = store.on('userLogin', (userData) => {\n  console.log('User logged in:', userData);\n});\n\n// Trigger custom events\nstore.triggerEvent('userLogin', { userId: 123, name: 'John' });\n\n// Unsubscribe from events\nunsubscribe();\n```\n\n#### Undo/Redo Functionality\n\n```javascript\n// Make state changes\nstore.setState({ count: 1 });\nstore.setState({ count: 2 });\nstore.setState({ count: 3 });\n\n// Undo last change\nstore.undo(); // count: 2\n\n// Redo change\nstore.redo(); // count: 3\n\n// Check stack sizes\nconsole.log('Undo stack size:', store.getUndoStackSize());\nconsole.log('Redo stack size:', store.getRedoStackSize());\n\n// Clear history\nstore.clearHistory();\n```\n\n#### Middleware System\n\n```javascript\n// Create middleware\nconst loggingMiddleware = (prevState, nextState) => {\n  console.log('State transition:', { prevState, nextState });\n};\n\nconst validationMiddleware = (prevState, nextState) => {\n  if (nextState.count < 0) {\n    throw new Error('Count cannot be negative');\n  }\n};\n\n// Apply middleware\nstore.applyMiddleware(loggingMiddleware);\nstore.applyMiddleware(validationMiddleware);\n\n// Async middleware\nconst asyncMiddleware = async (prevState, nextState) => {\n  await fetch('/api/log-state', {\n    method: 'POST',\n    body: JSON.stringify({ prevState, nextState })\n  });\n};\n\nstore.applyMiddleware(asyncMiddleware);\n```\n\n#### Performance Features\n\n```javascript\n// Debounced state updates\nstore.setDebounce(300);\nstore.setState({ count: 1 }, true, true); // Debounced update\n\n// Batch updates\nstore.startBatchUpdate();\nstore.queueBatchUpdate({ count: 1 });\nstore.queueBatchUpdate({ name: 'test' });\nstore.endBatchUpdate(); // Single notification\n\n// Deep state comparison\nstore.enableDeepStateComparison();\nstore.setState({ nested: { value: 1 } });\n```\n\n#### Error Handling\n\n```javascript\n// Set custom error handler\nstore.setErrorHandler((error) => {\n  console.error('Store error:', error);\n  // Send to error reporting service\n});\n\n// Handle errors gracefully\ntry {\n  store.setState(invalidState);\n} catch (error) {\n  // Error is handled by error handler\n}\n```\n\n#### Utility Methods\n\n```javascript\n// Get state snapshot\nconst snapshot = store.getStateSnapshot();\nconsole.log('Store info:', snapshot);\n\n// Remove all listeners\nstore.removeAllListeners();\n\n// Remove all event listeners\nstore.removeAllEventListeners('userLogin');\n\n// Remove all middleware\nstore.removeAllMiddlewares();\n\n// Enable/disable specific middleware\nstore.disableMiddleware(0);\nstore.enableMiddleware(0);\n```\n\n### PersistenceMiddleware\n\nA specialized middleware for file-based state persistence.\n\n```javascript\nconst persistenceMiddleware = new PersistenceMiddleware('state.json', {\n  spaces: 2,\n  fileType: 'json',\n  version: 1\n});\n```\n\n#### Basic Operations\n\n```javascript\n// Save state to file\nawait persistenceMiddleware.saveState({ count: 1, name: 'test' });\n\n// Load state from file\nconst state = await persistenceMiddleware.loadState();\n\n// Check if file exists\nconst exists = await persistenceMiddleware.fileExists();\n\n// Get file information\nconst fileInfo = await persistenceMiddleware.getFileInfo();\n```\n\n#### File Management\n\n```javascript\n// Rename file\nawait persistenceMiddleware.renameFile('new-state.json');\n\n// Delete file\nawait persistenceMiddleware.deleteFile();\n\n// Get file size\nconst size = await persistenceMiddleware.getFileSize();\n\n// Check if file is empty\nconst isEmpty = await persistenceMiddleware.isFileEmpty();\n```\n\n#### Backup Operations\n\n```javascript\n// Create backup\nawait persistenceMiddleware.backupState(currentState);\n\n// Restore from backup\nconst restoredState = await persistenceMiddleware.restoreFromBackup();\n```\n\n#### Validation\n\n```javascript\n// Validate state before saving\nconst isValid = await persistenceMiddleware.validateState(state);\n\n// Save with validation\nawait persistenceMiddleware.saveStateWithValidation(state);\n\n// Load with validation\nconst validState = await persistenceMiddleware.loadStateWithValidation();\n```\n\n#### Configuration\n\n```javascript\n// Update options\npersistenceMiddleware.setOptions({ spaces: 4 });\n\n// Set file type\npersistenceMiddleware.setFileType('json');\n\n// Set JSON formatting\npersistenceMiddleware.setJsonFormatting(4);\n\n// Version management\npersistenceMiddleware.incrementVersion();\nconst version = persistenceMiddleware.getVersion();\n```\n\n## Advanced Usage\n\n### Integration with React\n\n```javascript\nimport React, { useEffect, useState } from 'react';\nimport { StateManager } from '1cbyc-state-management';\n\nconst store = new StateManager({ count: 0 });\n\nfunction Counter() {\n  const [state, setState] = useState(store.getState());\n\n  useEffect(() => {\n    const unsubscribe = store.subscribe(setState);\n    return unsubscribe;\n  }, []);\n\n  return (\n    <div>\n      <p>Count: {state.count}</p>\n      <button onClick={() => store.setState({ count: state.count + 1 })}>\n        Increment\n      </button>\n      <button onClick={() => store.undo()}>Undo</button>\n      <button onClick={() => store.redo()}>Redo</button>\n    </div>\n  );\n}\n```\n\n### Integration with Vue\n\n```javascript\nimport { reactive } from 'vue';\nimport { StateManager } from '1cbyc-state-management';\n\nconst store = new StateManager({ count: 0 });\n\nexport default {\n  setup() {\n    const state = reactive(store.getState());\n\n    store.subscribe((newState) => {\n      Object.assign(state, newState);\n    });\n\n    return {\n      state,\n      increment: () => store.setState({ count: state.count + 1 }),\n      undo: () => store.undo(),\n      redo: () => store.redo()\n    };\n  }\n};\n```\n\n### Complex State Management\n\n```javascript\nconst store = new StateManager({\n  user: null,\n  posts: [],\n  loading: false,\n  errors: []\n});\n\n// User actions\nconst userActions = {\n  login: (userData) => store.setState({ user: userData }),\n  logout: () => store.setState({ user: null }),\n  updateProfile: (updates) => store.mergeState({ user: { ...store.getState().user, ...updates } })\n};\n\n// Post actions\nconst postActions = {\n  setPosts: (posts) => store.setState({ posts }),\n  addPost: (post) => store.mergeState({ posts: [...store.getState().posts, post] }),\n  updatePost: (id, updates) => {\n    const posts = store.getState().posts.map(post => \n      post.id === id ? { ...post, ...updates } : post\n    );\n    store.setState({ posts });\n  }\n};\n\n// UI actions\nconst uiActions = {\n  setLoading: (loading) => store.setState({ loading }),\n  addError: (error) => store.mergeState({ errors: [...store.getState().errors, error] }),\n  clearErrors: () => store.setState({ errors: [] })\n};\n```\n\n### Custom Middleware\n\n```javascript\n// Authentication middleware\nconst authMiddleware = (prevState, nextState) => {\n  if (nextState.user && !prevState.user) {\n    // User logged in\n    localStorage.setItem('authToken', nextState.user.token);\n  } else if (!nextState.user && prevState.user) {\n    // User logged out\n    localStorage.removeItem('authToken');\n  }\n};\n\n// Analytics middleware\nconst analyticsMiddleware = (prevState, nextState) => {\n  if (nextState.page !== prevState.page) {\n    // Track page change\n    analytics.track('page_view', { page: nextState.page });\n  }\n};\n\n// Validation middleware\nconst validationMiddleware = (prevState, nextState) => {\n  if (nextState.count < 0) {\n    throw new Error('Count cannot be negative');\n  }\n  \n  if (nextState.user && !nextState.user.email) {\n    throw new Error('User must have an email');\n  }\n};\n\nstore.applyMiddleware(authMiddleware);\nstore.applyMiddleware(analyticsMiddleware);\nstore.applyMiddleware(validationMiddleware);\n```\n\n## API Reference\n\n### StateManager\n\n#### Constructor\n- `new StateManager(initialState?: object)`\n\n#### State Methods\n- `getState(): object`\n- `setState(newState: object, addToUndoStack?: boolean, debounce?: boolean): void`\n- `mergeState(partialState: object): void`\n- `patchState(partialState: object): void`\n- `resetState(): void`\n\n#### Subscription Methods\n- `subscribe(listener: function): function`\n- `on(eventName: string, callback: function): function`\n- `triggerEvent(eventName: string, eventData: any): void`\n\n#### History Methods\n- `undo(): void`\n- `redo(): void`\n- `getUndoStackSize(): number`\n- `getRedoStackSize(): number`\n- `clearHistory(): void`\n\n#### Middleware Methods\n- `applyMiddleware(middleware: function, options?: object): void`\n- `getMiddlewareCount(): number`\n- `enableMiddleware(index: number): void`\n- `disableMiddleware(index: number): void`\n- `removeAllMiddlewares(): void`\n\n#### Performance Methods\n- `setDebounce(delay: number): void`\n- `startBatchUpdate(): void`\n- `endBatchUpdate(): void`\n- `queueBatchUpdate(partialState: object): void`\n\n#### Configuration Methods\n- `enableDeepStateComparison(): void`\n- `disableDeepStateComparison(): void`\n- `setLocalStorageKey(key: string): void`\n- `setErrorHandler(handler: function): void`\n\n#### Utility Methods\n- `getStateSnapshot(): object`\n- `getListenerCount(): number`\n- `getEventListenerCount(eventName: string): number`\n- `removeAllListeners(): void`\n- `removeAllEventListeners(eventName?: string): void`\n\n### PersistenceMiddleware\n\n#### Constructor\n- `new PersistenceMiddleware(filePath?: string, options?: object)`\n\n#### File Operations\n- `saveState(state: object): Promise<boolean>`\n- `loadState(): Promise<object|null>`\n- `fileExists(filePath?: string): Promise<boolean>`\n- `getFileInfo(): Promise<object|null>`\n- `getFileSize(): Promise<number>`\n- `isFileEmpty(): Promise<boolean>`\n\n#### File Management\n- `renameFile(newFilePath: string): Promise<boolean>`\n- `deleteFile(): Promise<boolean>`\n- `truncateFile(): Promise<boolean>`\n- `appendToFile(content: string): Promise<boolean>`\n\n#### Backup Operations\n- `backupState(state: object): Promise<boolean>`\n- `restoreFromBackup(): Promise<object|null>`\n\n#### Validation\n- `validateState(state: object): Promise<boolean>`\n- `saveStateWithValidation(state: object): Promise<boolean>`\n- `loadStateWithValidation(): Promise<object|null>`\n\n#### Configuration\n- `setOptions(options: object): void`\n- `getOptions(): object`\n- `setFileType(fileType: string): void`\n- `setJsonFormatting(spaces: number): void`\n- `incrementVersion(): void`\n- `getVersion(): number`\n- `setFilePath(filePath: string): void`\n- `getFilePath(): string`\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/1cbyc/1cbyc-state-management/issues)\n- **Documentation**: [GitHub Wiki](https://github.com/1cbyc/1cbyc-state-management/wiki)\n- **Discussions**: [GitHub Discussions](https://github.com/1cbyc/1cbyc-state-management/discussions)\n\n## Roadmap\n\nSee [docs/whats-next.md](docs/whats-next.md) for detailed roadmap and upcoming features.","readmeFilename":"README.md","_rev":"1-a8c2f155f11b5a39c5e0e72711039f78"}