@jr200-labs/xstate-nats 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jayshan Raghunandan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# @jr200-labs/xstate-nats
+
+A 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.
+
+## Features
+
+- **State Machine Management**: Built on XState for predictable state transitions and side effects
+- **NATS Integration**: Full support for NATS Core, JetStream, and Key-Value operations
+- **Authentication Support**: Multiple auth types (decentralised, userpass, token)
+- **Connection Management**: Automatic connection handling with retry logic and error recovery
+- **Subject Management**: Subscribe, publish, and request-reply operations with state tracking
+- **Key-Value Store**: KV bucket and key management with real-time subscriptions
+
+## Installation
+
+```bash
+pnpm add @jr200-labs/xstate-nats
+```
+
+## Quick Start
+
+### Basic Setup
+
+```typescript
+import { natsMachine } from '@jr200-labs/xstate-nats'
+import { useActor } from '@xstate/react'
+
+function MyComponent() {
+  const [state, send] = useActor(natsMachine)
+
+  const connect = () => {
+    send({
+      type: 'CONFIGURE',
+      config: {
+        opts: {
+          servers: ['nats://localhost:4222'],
+        },
+        auth: {
+          type: 'userpass',
+          user: 'myuser',
+          pass: 'mypass',
+        },
+        maxRetries: 3,
+      },
+    })
+
+    send({ type: 'CONNECT' })
+  }
+
+  return (
+    <div>
+      <p>Status: {state.value}</p>
+      <button onClick={connect}>Connect</button>
+    </div>
+  )
+}
+```
+
+### Subject Operations
+
+```typescript
+// Subscribe to a subject
+send({
+  type: 'SUBJECT.SUBSCRIBE',
+  config: {
+    subject: 'user.events',
+    callback: (data) => {
+      console.log('Received:', data)
+    },
+  },
+})
+
+// Publish to a subject
+send({
+  type: 'SUBJECT.PUBLISH',
+  subject: 'user.events',
+  payload: { userId: 123, action: 'login' },
+})
+
+// Request-reply pattern
+send({
+  type: 'SUBJECT.REQUEST',
+  subject: 'user.get',
+  payload: { userId: 123 },
+  callback: (reply) => {
+    console.log('Reply:', reply)
+  },
+})
+```
+
+### Key-Value Operations
+
+```typescript
+// Create a KV bucket
+send({
+  type: 'KV.BUCKET_CREATE',
+  bucket: 'user-sessions',
+  onResult: (result) => {
+    if (result.ok) {
+      console.log('Bucket created successfully')
+    }
+  },
+})
+
+// Put a value
+send({
+  type: 'KV.PUT',
+  bucket: 'user-sessions',
+  key: 'user-123',
+  value: { sessionId: 'abc123', expiresAt: Date.now() },
+  onResult: (result) => {
+    if (result.ok) {
+      console.log('Value stored successfully')
+    }
+  },
+})
+
+// Get a value
+send({
+  type: 'KV.GET',
+  bucket: 'user-sessions',
+  key: 'user-123',
+  onResult: (result) => {
+    if ('error' in result) {
+      console.error('Error:', result.error)
+    } else {
+      console.log('Value:', result)
+    }
+  },
+})
+
+// Subscribe to KV changes
+send({
+  type: 'KV.SUBSCRIBE',
+  config: {
+    bucket: 'user-sessions',
+    key: 'user-123',
+    callback: (entry) => {
+      console.log('KV Update:', entry)
+    },
+  },
+})
+```
+
+## State Machine States
+
+The NATS machine operates in the following states:
+
+- **`not_configured`**: Initial state, waiting for configuration
+- **`configured`**: Configuration received, ready to connect
+- **`connecting`**: Attempting to establish NATS connection
+- **`initialise_managers`**: Setting up subject and KV managers
+- **`connected`**: Fully connected and operational
+- **`closing`**: Gracefully disconnecting
+- **`closed`**: Connection closed, can reconnect
+- **`error`**: Error state, can reset and retry
+
+## API Reference
+
+### Main Exports
+
+- `natsMachine`: The main XState machine for NATS operations
+- `KvSubscriptionKey`: Type for KV subscription keys
+- `parseNatsResult`: Utility for parsing NATS operation results
+- `AuthConfig`: Type for authentication configuration
+
+### Authentication
+
+```typescript
+// Decentralised auth
+auth: {
+  type: 'decentralised',
+  sentinelB64: 'base64-encoded-sentinel',
+  user: 'username',
+  pass: 'password'
+}
+
+// User/password auth
+auth: {
+  type: 'userpass',
+  user: 'username',
+  pass: 'password'
+}
+
+// Token auth
+auth: {
+  type: 'token',
+  token: 'your-token'
+}
+```
+
+### Events
+
+#### Connection Events
+
+- `CONFIGURE`: Set connection configuration
+- `CONNECT`: Establish connection
+- `DISCONNECT`: Close connection
+- `RESET`: Reset to initial state
+
+#### Subject Events
+
+- `SUBJECT.SUBSCRIBE`: Subscribe to a subject
+- `SUBJECT.UNSUBSCRIBE`: Unsubscribe from a subject
+- `SUBJECT.PUBLISH`: Publish to a subject
+- `SUBJECT.REQUEST`: Send request-reply
+- `SUBJECT.UNSUBSCRIBE_ALL`: Clear all subscriptions
+
+#### KV Events
+
+- `KV.BUCKET_CREATE`: Create a KV bucket
+- `KV.BUCKET_DELETE`: Delete a KV bucket
+- `KV.BUCKET_LIST`: List KV buckets
+- `KV.PUT`: Store a value
+- `KV.GET`: Retrieve a value
+- `KV.DELETE`: Delete a value
+- `KV.SUBSCRIBE`: Subscribe to KV changes
+- `KV.UNSUBSCRIBE`: Unsubscribe from KV changes
+- `KV.UNSUBSCRIBE_ALL`: Unsubscribe from all KV changes
+
+## Examples
+
+Check out the [React example](./examples/react-test/) for a complete working implementation.
+
+## Development
+
+### Prerequisites
+
+- Node.js 22+
+- pnpm
+
+### Setup
+
+```bash
+make install
+```
+
+### Commands
+
+```bash
+make check          # Run prettier + lint (tsc --noEmit)
+make test           # Run tests
+make build          # Build the library
+make bump PART=patch  # Bump version (major|minor|patch)
+make release        # Tag, push, and create GitHub release
+make publish        # Build, test, and publish to npm
+```
+
+## License
+
+MIT

package/dist/actions/connection.d.ts

@@ -0,0 +1,28 @@
+import { ConnectionOptions, Msg, NatsConnection, Status } from '@nats-io/nats-core';
+import { KvEntry } from '@nats-io/kv';
+import { type AuthConfig } from './types';
+export type InternalStatusEvents = {
+    type: 'NATS_CONNECTION.DISCONNECTED';
+    status: Status;
+} | {
+    type: 'NATS_CONNECTION.RECONNECT';
+    status: Status;
+} | {
+    type: 'NATS_CONNECTION.ERROR';
+    status: Status;
+} | {
+    type: 'NATS_CONNECTION.CLOSE';
+    status: Status;
+} | {
+    type: 'NATS_CONNECTION.RECONNECTING';
+    status: Status;
+};
+export declare const connectToNats: import("xstate").PromiseActorLogic<NatsConnection, {
+    opts: ConnectionOptions;
+    auth?: AuthConfig;
+}, import("xstate").EventObject>;
+export declare const disconnectNats: import("xstate").PromiseActorLogic<void, {
+    connection: NatsConnection | null;
+}, import("xstate").EventObject>;
+export declare const parseNatsResult: (msg: Msg | KvEntry | null | Error) => unknown;
+//# sourceMappingURL=connection.d.ts.map

package/dist/actions/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/actions/connection.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EAEjB,GAAG,EACH,cAAc,EACd,MAAM,EAEP,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAA;AA6BzC,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,8BAA8B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,2BAA2B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,8BAA8B,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5D,eAAO,MAAM,aAAa;UAIP,iBAAiB;WAAS,UAAU;gCAwDtD,CAAA;AAED,eAAO,MAAM,cAAc;gBACgB,cAAc,GAAG,IAAI;gCAM/D,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,KAAK,GAAG,GAAG,OAAO,GAAG,IAAI,GAAG,KAAK,YAiBhE,CAAA"}

package/dist/actions/connection.js

@@ -0,0 +1,102 @@
+import { fromPromise } from 'xstate';
+import { credsAuthenticator, wsconnect, } from '@nats-io/nats-core';
+import { sendParent } from 'xstate';
+const makeAuthConfig = (auth) => {
+    if (!auth) {
+        return {};
+    }
+    if (auth.type === 'decentralised') {
+        const decodedSentinel = atob(auth.sentinelB64);
+        return {
+            authenticator: credsAuthenticator(new TextEncoder().encode(decodedSentinel)),
+            user: auth.user,
+            pass: auth.pass,
+        };
+    }
+    else if (auth.type === 'userpass') {
+        return {
+            user: auth.user,
+            pass: auth.pass,
+        };
+    }
+    else if (auth.type === 'token') {
+        return {
+            token: auth.token,
+        };
+    }
+    throw new Error(`Unsupported auth config type ${auth.type}`);
+};
+export const connectToNats = fromPromise(async ({ input, }) => {
+    const mergedOpts = {
+        ...input.opts,
+        ...makeAuthConfig(input.auth),
+    };
+    const nc = await wsconnect(mergedOpts);
+    (async () => {
+        for await (const status of nc.status()) {
+            console.log('Status loop received status', status);
+            const { type } = status;
+            switch (type) {
+                case 'disconnect':
+                    sendParent({ type: 'NATS_CONNECTION.DISCONNECTED', status });
+                    break;
+                case 'reconnect':
+                    sendParent({ type: 'NATS_CONNECTION.RECONNECT', status });
+                    break;
+                case 'error':
+                    sendParent({ type: 'NATS_CONNECTION.ERROR', status });
+                    break;
+                case 'close':
+                    sendParent({ type: 'NATS_CONNECTION.CLOSE', status });
+                    break;
+                case 'ldm':
+                    console.debug('LDM', status);
+                    break;
+                case 'ping':
+                    // console.debug('Received ping, pong sent automatically')
+                    break;
+                case 'forceReconnect':
+                    sendParent({ type: 'NATS_CONNECTION.RECONNECT', status });
+                    break;
+                case 'reconnecting':
+                    sendParent({ type: 'NATS_CONNECTION.RECONNECTING', status });
+                    break;
+                case 'slowConsumer':
+                    console.debug('SLOW_CONSUMER', status);
+                    break;
+                case 'staleConnection':
+                    console.debug('STALE_CONNECTION', status);
+                    break;
+                case 'update':
+                    console.debug('NATS_CONNECTION.UPDATE', status);
+                    break;
+            }
+        }
+        console.log('Exiting nats status loop');
+    })();
+    return nc;
+});
+export const disconnectNats = fromPromise(async ({ input }) => {
+    if (input.connection) {
+        await input.connection.drain();
+        await input.connection.close();
+    }
+});
+export const parseNatsResult = (msg) => {
+    if (!msg) {
+        return null;
+    }
+    if (msg instanceof Error) {
+        return msg;
+    }
+    let data;
+    try {
+        data = msg.json();
+    }
+    catch (jsonError) {
+        // If JSON parsing fails, use the raw string
+        data = msg.string();
+    }
+    return data;
+};
+//# sourceMappingURL=connection.js.map

package/dist/actions/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/actions/connection.ts"],"names":[],"mappings":"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"}

package/dist/actions/kv.d.ts

@@ -0,0 +1,21 @@
+import { NatsConnection, QueuedIterator } from '@nats-io/nats-core';
+import { Kvm, KvWatchEntry, KvWatchOptions } from '@nats-io/kv';
+import { Pair } from '../utils';
+export declare class KvSubscriptionKey extends Pair<string, string> {
+}
+export type KvSubscriptionConfig = {
+    bucket: string;
+    key: string;
+    callback: (data: any) => void;
+    opts?: KvWatchOptions;
+    replayOnReconnect?: boolean;
+};
+export declare const kvConsolidateState: import("xstate").PromiseActorLogic<{
+    subscriptions: Map<string, QueuedIterator<KvWatchEntry>>;
+}, {
+    kvm: Kvm | null;
+    connection: NatsConnection | null;
+    currentState: Map<string, QueuedIterator<KvWatchEntry>>;
+    targetState: Map<string, KvSubscriptionConfig>;
+}, import("xstate").EventObject>;
+//# sourceMappingURL=kv.d.ts.map

package/dist/actions/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../../src/actions/kv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAG/B,qBAAa,iBAAkB,SAAQ,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;CAAG;AAE9D,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7B,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,eAAO,MAAM,kBAAkB;mBAWZ,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;;SANjD,GAAG,GAAG,IAAI;gBACH,cAAc,GAAG,IAAI;kBACnB,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;iBAC1C,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC;gCAoEnD,CAAA"}

package/dist/actions/kv.js

@@ -0,0 +1,66 @@
+import { Pair } from '../utils';
+import { fromPromise } from 'xstate';
+export class KvSubscriptionKey extends Pair {
+}
+export const kvConsolidateState = fromPromise(async ({ input, }) => {
+    if (!input.connection || !input.kvm) {
+        throw new Error('NATS connection or KVM is not available');
+    }
+    const { currentState, targetState } = input;
+    const syncedState = new Map(currentState);
+    // Unsubscribe from items that are in currentState but not in targetState
+    for (const [kvKey, subscription] of currentState) {
+        if (!targetState.has(kvKey)) {
+            try {
+                syncedState.delete(kvKey);
+                subscription.stop();
+            }
+            catch (error) {
+                console.error(`Error unsubscribing from subject "${kvKey}"`, error);
+            }
+        }
+    }
+    // Subscribe to new subjects that are in targetState but not in currentState
+    for (const [kvKey, config] of targetState) {
+        if (!currentState.has(kvKey)) {
+            // the problem is kv key is triggered on successive calls to consolidateState
+            // the match is not working?
+            try {
+                const kv = await input.kvm.open(config.bucket);
+                const watchOptions = config;
+                const watcher = await kv.watch(watchOptions);
+                syncedState.set(kvKey, watcher);
+                (async () => {
+                    try {
+                        for await (const e of watcher) {
+                            if (e.operation !== 'DEL') {
+                                let parsedValue;
+                                try {
+                                    parsedValue = JSON.parse(e.string());
+                                }
+                                catch {
+                                    parsedValue = e.string();
+                                }
+                                config.callback({
+                                    bucket: config.bucket,
+                                    key: config.key,
+                                    value: parsedValue,
+                                });
+                            }
+                        }
+                    }
+                    catch (error) {
+                        console.error(`KV_SUBSCRIBE (connected): Watcher loop error for ${kvKey}:`, error);
+                    }
+                })();
+            }
+            catch (error) {
+                console.error(`Error subscribing to subject "${kvKey}"`, error);
+            }
+        }
+    }
+    return {
+        subscriptions: syncedState,
+    };
+});
+//# sourceMappingURL=kv.js.map

package/dist/actions/kv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.js","sourceRoot":"","sources":["../../src/actions/kv.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA;AAEpC,MAAM,OAAO,iBAAkB,SAAQ,IAAoB;CAAG;AAU9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,WAAW,CAC3C,KAAK,EAAE,EACL,KAAK,GAQN,EAEE,EAAE;IACH,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;IAC5D,CAAC;IAED,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,KAAK,CAAA;IAC3C,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAA;IAEzC,yEAAyE;IACzE,KAAK,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,YAAY,EAAE,CAAC;QACjD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACzB,YAAY,CAAC,IAAI,EAAE,CAAA;YACrB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,qCAAqC,KAAK,GAAG,EAAE,KAAK,CAAC,CAAA;YACrE,CAAC;QACH,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC1C,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,6EAA6E;YAC7E,4BAA4B;YAC5B,IAAI,CAAC;gBACH,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBAE9C,MAAM,YAAY,GAAG,MAAwB,CAAA;gBAC7C,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;gBAE5C,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAC9B;gBAAA,CAAC,KAAK,IAAI,EAAE;oBACX,IAAI,CAAC;wBACH,IAAI,KAAK,EAAE,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;4BAC9B,IAAI,CAAC,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;gCAC1B,IAAI,WAAW,CAAA;gCACf,IAAI,CAAC;oCACH,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;gCACtC,CAAC;gCAAC,MAAM,CAAC;oCACP,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAA;gCAC1B,CAAC;gCAED,MAAM,CAAC,QAAQ,CAAC;oCACd,MAAM,EAAE,MAAM,CAAC,MAAM;oCACrB,GAAG,EAAE,MAAM,CAAC,GAAG;oCACf,KAAK,EAAE,WAAW;iCACnB,CAAC,CAAA;4BACJ,CAAC;wBACH,CAAC;oBACH,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,OAAO,CAAC,KAAK,CAAC,oDAAoD,KAAK,GAAG,EAAE,KAAK,CAAC,CAAA;oBACpF,CAAC;gBACH,CAAC,CAAC,EAAE,CAAA;YACN,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,iCAAiC,KAAK,GAAG,EAAE,KAAK,CAAC,CAAA;YACjE,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,aAAa,EAAE,WAAW;KAC3B,CAAA;AACH,CAAC,CACF,CAAA"}

package/dist/actions/subject.d.ts

@@ -0,0 +1,39 @@
+import { NatsConnection, PublishOptions, RequestOptions, Subscription, SubscriptionOptions } from '@nats-io/nats-core';
+export type SubjectSubscriptionConfig = {
+    subject: string;
+    callback: (data: any) => void;
+    opts?: SubscriptionOptions;
+};
+export declare const subjectConsolidateState: ({ input, }: {
+    input: {
+        connection: NatsConnection | null;
+        currentSubscriptions: Map<string, Subscription>;
+        targetSubscriptions: Map<string, SubjectSubscriptionConfig>;
+    };
+}) => {
+    subscriptions: Map<string, Subscription>;
+};
+export declare const subjectRequest: ({ input, }: {
+    input: {
+        connection: NatsConnection | null;
+        subject: string;
+        payload: any;
+        opts?: RequestOptions;
+        callback: (data: any) => void;
+    };
+}) => void;
+export declare const subjectPublish: ({ input, }: {
+    input: {
+        connection: NatsConnection | null;
+        subject: string;
+        payload: any;
+        options?: PublishOptions;
+        onPublishResult?: (result: {
+            ok: true;
+        } | {
+            ok: false;
+            error: Error;
+        }) => void;
+    };
+}) => void;
+//# sourceMappingURL=subject.d.ts.map

package/dist/actions/subject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../src/actions/subject.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACd,cAAc,EACd,cAAc,EACd,YAAY,EACZ,mBAAmB,EACpB,MAAM,oBAAoB,CAAA;AAG3B,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAA;IAC7B,IAAI,CAAC,EAAE,mBAAmB,CAAA;CAC3B,CAAA;AAED,eAAO,MAAM,uBAAuB,GAAI,YAErC;IACD,KAAK,EAAE;QACL,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;QACjC,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;QAC/C,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAA;KAC5D,CAAA;CACF;;CAmDA,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,YAE5B;IACD,KAAK,EAAE;QACL,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;QACjC,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,GAAG,CAAA;QACZ,IAAI,CAAC,EAAE,cAAc,CAAA;QACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAA;KAC9B,CAAA;CACF,SAcA,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,YAE5B;IACD,KAAK,EAAE;QACL,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;QACjC,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,GAAG,CAAA;QACZ,OAAO,CAAC,EAAE,cAAc,CAAA;QACxB,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE;YAAE,EAAE,EAAE,IAAI,CAAA;SAAE,GAAG;YAAE,EAAE,EAAE,KAAK,CAAC;YAAC,KAAK,EAAE,KAAK,CAAA;SAAE,KAAK,IAAI,CAAA;KAC/E,CAAA;CACF,SAaA,CAAA"}

package/dist/actions/subject.js

@@ -0,0 +1,79 @@
+import { parseNatsResult } from './connection';
+export const subjectConsolidateState = ({ input, }) => {
+    const { connection, currentSubscriptions, targetSubscriptions } = input;
+    if (!connection) {
+        throw new Error('NATS connection is not available');
+    }
+    const syncedSubscriptions = new Map(currentSubscriptions);
+    // Unsubscribe from subjects that are in currentSubscriptions but not in targetSubscriptions
+    for (const [subject, subscription] of currentSubscriptions) {
+        if (!targetSubscriptions.has(subject)) {
+            try {
+                syncedSubscriptions.delete(subject);
+                subscription.unsubscribe();
+            }
+            catch (error) {
+                console.error(`Error unsubscribing from subject "${subject}"`, error);
+            }
+        }
+    }
+    // Subscribe to new subjects that are in targetSubscriptions but not in currentSubscriptions
+    for (const [subject, subscriptionConfig] of targetSubscriptions) {
+        if (!currentSubscriptions.has(subject)) {
+            try {
+                const sub = connection.subscribe(subject, subscriptionConfig.opts);
+                (async () => {
+                    try {
+                        for await (const msg of sub) {
+                            try {
+                                subscriptionConfig?.callback(parseNatsResult(msg));
+                            }
+                            catch (callbackError) {
+                                console.error(`Callback error for subject "${subject}"`, callbackError);
+                            }
+                        }
+                    }
+                    catch (iteratorError) {
+                        console.error(`Iterator error for subject "${subject}"`, iteratorError);
+                    }
+                })();
+                syncedSubscriptions.set(subject, sub);
+            }
+            catch (error) {
+                console.error(`Error subscribing to subject "${subject}"`, error);
+            }
+        }
+    }
+    return {
+        subscriptions: syncedSubscriptions,
+    };
+};
+export const subjectRequest = ({ input, }) => {
+    const { connection, subject, payload, opts, callback } = input;
+    if (!connection) {
+        throw new Error('NATS connection is not available');
+    }
+    connection
+        .request(subject, payload, opts)
+        .then((msg) => {
+        callback(parseNatsResult(msg));
+    })
+        .catch((err) => {
+        console.error(`RequestReply error for subject "${subject}"`, err);
+    });
+};
+export const subjectPublish = ({ input, }) => {
+    const { connection, subject, payload, options, onPublishResult } = input;
+    if (!connection) {
+        throw new Error('NATS connection is not available');
+    }
+    try {
+        connection.publish(subject, payload, options);
+        onPublishResult?.({ ok: true });
+    }
+    catch (callbackError) {
+        console.error(`Publish callback error for subject "${subject}"`, callbackError);
+        onPublishResult?.({ ok: false, error: callbackError });
+    }
+};
+//# sourceMappingURL=subject.js.map

package/dist/actions/subject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject.js","sourceRoot":"","sources":["../../src/actions/subject.ts"],"names":[],"mappings":"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"}

package/dist/actions/types.d.ts

@@ -0,0 +1,8 @@
+export interface AuthConfig {
+    type: 'decentralised' | 'userpass' | 'token';
+    sentinelB64?: string;
+    user?: string;
+    pass?: string;
+    token?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/actions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/actions/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,CAAA;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}

package/dist/actions/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/actions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/actions/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { natsMachine } from './machines/root';
+export { subjectManagerLogic, type Context as SubjectContext, type ExternalEvents as SubjectEvent, } from './machines/subject';
+export { kvManagerLogic, type Context as KvContext, type ExternalEvents as KvEvent, } from './machines/kv';
+export { KvSubscriptionKey, type KvSubscriptionConfig } from './actions/kv';
+export { parseNatsResult } from './actions/connection';
+export { type AuthConfig } from './actions/types';
+export { type NatsConnectionConfig, type Context as NatsContext, type ExternalEvents as NatsEvent, } from './machines/root';
+//# sourceMappingURL=index.d.ts.map