{"id":30383551,"url":"https://github.com/jr200/xstate-nats","last_synced_at":"2026-03-09T19:38:25.271Z","repository":{"id":307782926,"uuid":"1029131223","full_name":"jr200/xstate-nats","owner":"jr200","description":"XState machine for NATS","archived":false,"fork":false,"pushed_at":"2025-08-08T08:16:35.000Z","size":171,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-21T00:47:58.226Z","etag":null,"topics":["nats","nats-streaming","xstate","xstate-react"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/jr200.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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,"zenodo":null}},"created_at":"2025-07-30T15:10:13.000Z","updated_at":"2025-08-03T11:23:45.000Z","dependencies_parsed_at":"2025-08-03T07:15:17.668Z","dependency_job_id":null,"html_url":"https://github.com/jr200/xstate-nats","commit_stats":null,"previous_names":["jr200/xstate-nats"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/jr200/xstate-nats","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jr200%2Fxstate-nats","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jr200%2Fxstate-nats/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jr200%2Fxstate-nats/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jr200%2Fxstate-nats/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jr200","download_url":"https://codeload.github.com/jr200/xstate-nats/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jr200%2Fxstate-nats/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273699716,"owners_count":25152284,"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","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["nats","nats-streaming","xstate","xstate-react"],"created_at":"2025-08-21T00:36:19.303Z","updated_at":"2026-03-09T19:38:25.266Z","avatar_url":"https://github.com/jr200.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @jr200/xstate-nats\n\nA state machine library that integrates [XState v5](https://xstate.js.org/) with [NATS](https://nats.io/) messaging system, providing a type-safe way to manage NATS connections, subscriptions, and Key-Value operations.\n\n## Features\n\n- **State Machine Management**: Built on XState for predictable state transitions and side effects\n- **NATS Integration**: Full support for NATS Core, JetStream (TODO), and Key-Value operations\n- **Connection Management**: Automatic connection handling with retry logic and error recovery\n- **Subject Management**: Subscribe, publish, and request-reply operations with state tracking\n- **Key-Value Store**: KV bucket and key management with real-time subscriptions\n\n## Installation\n\n```bash\nnpm install @jr200/xstate-nats\n# or\npnpm add @jr200/xstate-nats\n# or\nyarn add @jr200/xstate-nats\n```\n\n## Quick Start\n\n### Basic Setup\n\n```typescript\nimport { natsMachine } from '@jr200/xstate-nats'\nimport { useActor } from '@xstate/react'\n\nfunction MyComponent() {\n  const [state, send] = useActor(natsMachine)\n\n  const connect = () =\u003e {\n    send({\n      type: 'CONFIGURE',\n      config: {\n        opts: {\n          servers: ['nats://localhost:4222']\n        },\n        maxRetries: 3\n      }\n    })\n    \n    send({ type: 'CONNECT' })\n  }\n\n  return (\n    \u003cdiv\u003e\n      \u003cp\u003eStatus: {state.value}\u003c/p\u003e\n      \u003cbutton onClick={connect}\u003eConnect\u003c/button\u003e\n    \u003c/div\u003e\n  )\n}\n```\n\n### Subject Operations\n\n```typescript\n// Subscribe to a subject\nsend({\n  type: 'SUBJECT.SUBSCRIBE',\n  subjectConfig: {\n    subject: 'user.events',\n    callback: (data) =\u003e {\n      console.log('Received:', data)\n    }\n  }\n})\n\n// Publish to a subject\nsend({\n  type: 'SUBJECT.PUBLISH',\n  subject: 'user.events',\n  payload: { userId: 123, action: 'login' }\n})\n\n// Request-reply pattern\nsend({\n  type: 'SUBJECT.REQUEST',\n  subject: 'user.get',\n  payload: { userId: 123 },\n  callback: (reply) =\u003e {\n    console.log('Reply:', reply)\n  }\n})\n```\n\n### Key-Value Operations\n\n```typescript\n// Create a KV bucket\nsend({\n  type: 'KV.BUCKET_CREATE',\n  bucket: 'user-sessions',\n  onResult: (result) =\u003e {\n    if (result.ok) {\n      console.log('Bucket created successfully')\n    }\n  }\n})\n\n// Put a value\nsend({\n  type: 'KV.PUT',\n  bucket: 'user-sessions',\n  key: 'user-123',\n  value: { sessionId: 'abc123', expiresAt: Date.now() },\n  onResult: (result) =\u003e {\n    if (result.ok) {\n      console.log('Value stored successfully')\n    }\n  }\n})\n\n// Get a value\nsend({\n  type: 'KV.GET',\n  bucket: 'user-sessions',\n  key: 'user-123',\n  onResult: (result) =\u003e {\n    if ('error' in result) {\n      console.error('Error:', result.error)\n    } else {\n      console.log('Value:', result)\n    }\n  }\n})\n\n// Subscribe to KV changes\nsend({\n  type: 'KV.SUBSCRIBE',\n  config: {\n    bucket: 'user-sessions',\n    key: 'user-123',\n    callback: (entry) =\u003e {\n      console.log('KV Update:', entry)\n    }\n  }\n})\n```\n\n## State Machine States\n\nThe NATS machine operates in the following states:\n\n- **`not_configured`**: Initial state, waiting for configuration\n- **`configured`**: Configuration received, ready to connect\n- **`connecting`**: Attempting to establish NATS connection\n- **`initialise_managers`**: Setting up subject and KV managers\n- **`connected`**: Fully connected and operational\n- **`closing`**: Gracefully disconnecting\n- **`closed`**: Connection closed, can reconnect\n- **`error`**: Error state, can reset and retry\n\n## API Reference\n\n### Main Exports\n\n- `natsMachine`: The main XState machine for NATS operations\n- `KvSubscriptionKey`: Type for KV subscription keys\n- `parseNatsResult`: Utility for parsing NATS operation results\n\n### Events\n\n#### Connection Events\n- `CONFIGURE`: Set connection configuration\n- `CONNECT`: Establish connection\n- `DISCONNECT`: Close connection\n- `RESET`: Reset to initial state\n\n#### Subject Events\n- `SUBJECT.SUBSCRIBE`: Subscribe to a subject\n- `SUBJECT.UNSUBSCRIBE`: Unsubscribe from a subject\n- `SUBJECT.PUBLISH`: Publish to a subject\n- `SUBJECT.REQUEST`: Send request-reply\n- `SUBJECT.UNSUBSCRIBE_ALL`: Clear all subscriptions\n\n#### KV Events\n- `KV.BUCKET_CREATE`: Create a KV bucket\n- `KV.BUCKET_DELETE`: Delete a KV bucket\n- `KV.BUCKET_LIST`: List KV buckets\n- `KV.PUT`: Store a value\n- `KV.GET`: Retrieve a value\n- `KV.DELETE`: Delete a value\n- `KV.SUBSCRIBE`: Subscribe to KV changes\n- `KV.UNSUBSCRIBE`: Unsubscribe from KV changes\n- `KV.UNSUBSCRIBE_ALL`: Unsubscribe from all KV changes\n\n## Examples\n\nCheck out the [React example](./examples/react-test/) for a complete working implementation that demonstrates:\n\n- Connection management\n- Subject subscriptions and publishing\n- Request-reply patterns\n- Key-Value operations\n- Real-time state updates\n\n## Development\n\n### Prerequisites\n\n- Node.js 18+\n- pnpm (recommended) or npm\n- NATS server running locally\n\n### Setup\n\n```bash\n# Install dependencies\npnpm install\n\n# Start NATS server (if not already running)\nnats-server -c nats-server.conf\n\n# Run the React example\ncd examples/react-test\npnpm dev\n```\n\n### Scripts\n\n- `pnpm build`: Build the library\n- `pnpm test`: Run tests\n- `pnpm lint`: Run ESLint\n- `pnpm format`: Format code with Prettier\n\n## Contributing\n\nContributions welcome!\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nMIT\n\n## Dependencies\n\n- [XState](https://xstate.js.org/) - State machine library\n- [@nats-io/nats-core](https://github.com/nats-io/nats.js) - NATS client\n- [@nats-io/jetstream](https://github.com/nats-io/nats.js) - JetStream support\n- [@nats-io/kv](https://github.com/nats-io/nats.js) - Key-Value store\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjr200%2Fxstate-nats","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjr200%2Fxstate-nats","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjr200%2Fxstate-nats/lists"}