{"_id":"@bundle-of-tubes/state-promulgator","name":"@bundle-of-tubes/state-promulgator","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@bundle-of-tubes/state-promulgator","version":"0.0.1","private":false,"description":"A state object with a registry of callbacks to execute when state attributes are changed","keywords":["javascript","typescript","component","state","register","registry"],"homepage":"https://github.com/bundle-of-tubes/state-promulgator","license":"MIT","main":"./dist/state-promulgator.js","types":"./dist/state-promulgator.d.ts","type":"module","repository":{"type":"git","url":"git+https://github.com/bundle-of-tubes/state-promulgator.git"},"scripts":{"prepack":"tsc --project tsconfig.json"},"devDependencies":{"typescript":"^7.0.2"},"gitHead":"be7bf51dfbce88bc23131571bde25459b3fc052f","_id":"@bundle-of-tubes/state-promulgator@0.0.1","bugs":{"url":"https://github.com/bundle-of-tubes/state-promulgator/issues"},"_nodeVersion":"26.7.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-xcOv23w0M8rQp6cL62Q4g+0tc1geebyyCdOwJcY8oT6sJsr42weyxLNmq1h1tgmIlzK/pxScqJM1cRiN0xDN8A==","shasum":"c9dc380ebc0a89dca4d986f2231850702c65be6e","tarball":"https://registry.npmjs.org/@bundle-of-tubes/state-promulgator/-/state-promulgator-0.0.1.tgz","fileCount":5,"unpackedSize":13419,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIACVgahn2R6oh1mCKA39X3z8PZwH0BMXkHshCOrQUHvpAiEA+7SKLVOxtBl/BDwZIyG6ZPKAboPzmVzsfHnqv5w+8D4="}]},"_npmUser":{"name":"bundle-of-tubes","email":"jasonnmorrow@gmail.com"},"directories":{},"maintainers":[{"name":"bundle-of-tubes","email":"jasonnmorrow@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/state-promulgator_0.0.1_1788567295821_0.7566330784796422"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-05T00:14:55.615Z","0.0.1":"2026-09-05T00:14:55.972Z","modified":"2026-09-05T00:14:56.234Z"},"maintainers":[{"name":"bundle-of-tubes","email":"jasonnmorrow@gmail.com"}],"description":"A state object with a registry of callbacks to execute when state attributes are changed","homepage":"https://github.com/bundle-of-tubes/state-promulgator","keywords":["javascript","typescript","component","state","register","registry"],"repository":{"type":"git","url":"git+https://github.com/bundle-of-tubes/state-promulgator.git"},"bugs":{"url":"https://github.com/bundle-of-tubes/state-promulgator/issues"},"license":"MIT","readme":"# state-promulgator\nA state object with a registry of callbacks to execute when state attributes are changed\n\nThe motivating use case is creation of [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) with states like React Components. Except unlike [React](https://react.dev) and [Lit](https://lit.dev), `StatePromulgator` allows components to minimally interact with the DOM instead of completely re-rendering.\n\n## Usage\nThis module exports two classes: `StatePromulgatorError` and `StatePromulgator`. It works for both typescript and javascript.\n\nEach instance of `StatePromulgator` has a state which is an object with string keys. It also has a registry of callbacks configured to execute when the state is updated.\n\nUsage examples can be found at https://github.com/bundle-of-tubes/promulgator-examples\n\n### StatePromulgator Constructor\n#### Parameters\n* initialState: The initial value of the state object\n\n#### Examples\n```javascript\nimport {StatePromulgator} from '@bundle-of-tubes/state-promulgator';\nconst stateMachine = new StatePromulgator({message: 'message', value: 0});\n```\n\n```typescript\nimport {StatePromulgator} from '@bundle-of-tubes/state-promulgator';\ninterface PaginatorState {\n  skip: number;\n  take: number;\n  pageSize: number;\n  totalRows: number;\n}\nconst stateMachine = new StatePromulgator<PaginatorState>({skip: 0, take: 0, pageSize: 20, totalRows: 0});\n```\n\n### StatePromulgator.prototype.state\nThe current state value\n\n### StatePromulgator.prototype.registerCallback()\nDeclare a callback to be executed when certain properties of the state are updated\n#### Parameters\n* callback: The function to be executed in state transitions.\n    * The first parameter of callback is the new value of the state\n    * The second parameter of the callback is the previous value of the state\n    * The third parameter of the callback is a Map where the keys are the return values of previously declared intermediates and the values are the return values of associated callbacks\n    * The return value of callback will be accessible to other callbacks via the third parameter\n* triggeringStateProperties: An Iterable representing the set of attributes of the state which when changed cause this callback to run\n* intermediateDependencies: An Iterable representing the set of keys of other intermediates that need to be computed before this\n#### Return Value\nA Symbol representing the key of the registered callback\n#### Examples\n```javascript\nconst k = stateMachine.registerCallback((newState, oldState, dependencies)=>{\n  return newState.value + oldState.value;\n}, new Set(), new Set());\nstateMachine.registerCallback((newState, oldState, dependencies)=>{\n  console.log('message changed from ', oldState.message, 'to ', newState.message);\n  console.log('callback1 returned: ', dependencies.get(k));\n}, ['value'], [k]);\n```\n\n```typescript\nconst pageNumberKey: symbol = stateMachine.registerCallback((newState: PaginatorState, oldState: PaginatorState, dependencies: Map<symbol,any>)=>{\n  const skip = newState.skip as number;\n  const pageSize = newState.pageSize as number;\n  return Math.floor(skip/pageSize)+1;\n}, new Set(), new Set());\nstateMachine.registerCallback((newState: PaginatorState, oldState: PaginatorState, dependencies: Map<symbol, any>)=>{\n  const pageNumber = dependencies.get(pageNumberKey) as number;\n  console.log('current page is', pageNumber);\n}, ['skip', 'take'], [pageNumberKey]);\n```\n\n### StatePromulgator.prototype.updateState()\nMerge the new state with the existing state and execute the callbacks that are triggered by updated state attributes\n#### Parameters\n* newState: An object whose properties represent attributes of the state to be updated\n* promulgateUnchangedProperties: If true, callbacks will trigger for all properties of newState, even if they are identical to those of the old state\n#### Examples\n```javascript\nstateMachine.updateState({message: 'unwatched'}); //no callbacks are triggered because value is omitted, and value will be unchanged\nstateMachine.updateState({message: 'identical', value: 0}); //no callbacks are triggered because value is unchanged\nstateMachine.updateState({message: 'identical', value: 0}, true); //callbacks are triggered because of the promulgateUnchangedProperties flag\nstateMachine.updateState({message: 'fibonacci', value: 1}); //callbacks are triggered because value is changed\n```\n\n```typescript\nstateMachine.updateState({totalRows: 32});\nstateMachine.updateState({skip: 20, take: 12});\nstateMachine.updateState({pageSize: 10, take: 10});\n```\n\n### StatePromulgatorError\nAn Error subclass\n","readmeFilename":"README.md","_rev":"1-fcb63d696bdf84e9ec66c12067dca469"}