@motiadev/adapter-redis-state 0.8.2-beta.140-709523

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.1.0] - 2025-10-22
+
+### Added
+- Initial release of Redis state adapter for Motia
+- Support for distributed state management across multiple instances
+- TTL support for automatic state cleanup
+- Atomic operations for data consistency
+- Efficient SCAN operations for large datasets
+- Type preservation for state values
+- Support for filtering and querying state items
+- Automatic reconnection handling
+- Configurable key prefixes for namespacing
+- Full TypeScript support with type definitions
+- Comprehensive documentation and examples
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Motia
+
+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,142 @@
+# @motiadev/adapter-redis-state
+
+Redis state adapter for Motia framework, enabling distributed state management across multiple instances.
+
+## Installation
+
+```bash
+npm install @motiadev/adapter-redis-state
+```
+
+## Usage
+
+Configure the Redis state adapter in your `motia.config.ts`:
+
+```typescript
+import { config } from '@motiadev/core'
+import { RedisStateAdapter } from '@motiadev/adapter-redis-state'
+
+export default config({
+  adapters: {
+    state: new RedisStateAdapter({
+      host: process.env.REDIS_HOST || 'localhost',
+      port: parseInt(process.env.REDIS_PORT || '6379'),
+      password: process.env.REDIS_PASSWORD,
+      keyPrefix: 'motia:state:',
+      ttl: 3600,
+    }),
+  },
+})
+```
+
+## Configuration Options
+
+### RedisStateAdapterConfig
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | `string` | `'localhost'` | Redis server host |
+| `port` | `number` | `6379` | Redis server port |
+| `password` | `string` | `undefined` | Redis authentication password |
+| `username` | `string` | `undefined` | Redis authentication username |
+| `database` | `number` | `0` | Redis database number |
+| `keyPrefix` | `string` | `'motia:state:'` | Prefix for all state keys |
+| `ttl` | `number` | `undefined` | Time-to-live in seconds for state entries |
+| `socket.reconnectStrategy` | `function` | Auto-retry | Custom reconnection strategy |
+| `socket.connectTimeout` | `number` | `10000` | Connection timeout in milliseconds |
+
+## Features
+
+- **Distributed State**: Share state across multiple Motia instances
+- **Automatic TTL**: Optional automatic cleanup of expired state
+- **Connection Pooling**: Efficient Redis connection management
+- **Automatic Reconnection**: Handles connection failures gracefully
+- **Atomic Operations**: Ensures data consistency
+- **Efficient Scanning**: Uses SCAN for large datasets to avoid blocking
+- **Type Preservation**: Maintains type information for state values
+
+## Key Namespacing
+
+The adapter uses the following key pattern:
+```
+{keyPrefix}{traceId}:{key}
+```
+
+For example:
+```
+motia:state:trace-123:userData
+motia:state:trace-456:orderDetails
+```
+
+## Example
+
+```typescript
+import { RedisStateAdapter } from '@motiadev/adapter-redis-state'
+
+const adapter = new RedisStateAdapter({
+  host: 'redis.example.com',
+  port: 6379,
+  password: 'your-secure-password',
+  keyPrefix: 'myapp:motia:state:',
+  ttl: 7200,
+  socket: {
+    connectTimeout: 5000,
+    reconnectStrategy: (retries) => {
+      if (retries > 20) {
+        return new Error('Too many retries')
+      }
+      return Math.min(retries * 50, 2000)
+    },
+  },
+})
+```
+
+## Environment Variables
+
+```bash
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=your-password
+REDIS_DATABASE=0
+STATE_KEY_PREFIX=motia:state:
+STATE_TTL=3600
+```
+
+## Performance Considerations
+
+- **TTL Settings**: Set appropriate TTL values to prevent memory bloat
+- **Key Prefix**: Use descriptive prefixes to organize keys
+- **Connection Pooling**: Redis client handles connection pooling automatically
+- **Batch Operations**: The adapter uses batch operations where possible
+- **Scan Operations**: Uses SCAN instead of KEYS to avoid blocking
+
+## Troubleshooting
+
+### Connection Issues
+
+If you experience connection problems:
+1. Verify Redis is running and accessible
+2. Check your host, port, and credentials
+3. Ensure firewall rules allow connections on the Redis port
+4. Review Redis logs for errors
+
+### Memory Issues
+
+If Redis runs out of memory:
+1. Configure appropriate TTL values
+2. Implement state cleanup strategies
+3. Monitor Redis memory usage
+4. Consider using Redis eviction policies
+
+### Performance Issues
+
+If you experience slow operations:
+1. Monitor Redis server performance
+2. Check network latency between app and Redis
+3. Review key patterns and optimize queries
+4. Consider Redis clustering for large datasets
+
+## License
+
+MIT
+

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { RedisStateAdapter } from './redis-state-adapter';
+export type { RedisStateAdapterConfig } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisStateAdapter = void 0;
+var redis_state_adapter_1 = require("./redis-state-adapter");
+Object.defineProperty(exports, "RedisStateAdapter", { enumerable: true, get: function () { return redis_state_adapter_1.RedisStateAdapter; } });

package/dist/redis-state-adapter.d.ts

@@ -0,0 +1,28 @@
+import type { StateAdapter, StateItem, StateItemsInput } from '@motiadev/core';
+import type { RedisStateAdapterConfig } from './types';
+export declare class RedisStateAdapter implements StateAdapter {
+    private client;
+    private keyPrefix;
+    private ttl?;
+    private connected;
+    constructor(config: RedisStateAdapterConfig);
+    private connect;
+    private ensureConnected;
+    private makeKey;
+    private makeTracePrefix;
+    private extractKey;
+    private determineType;
+    get<T>(traceId: string, key: string): Promise<T | null>;
+    set<T>(traceId: string, key: string, value: T): Promise<T>;
+    delete<T>(traceId: string, key: string): Promise<T | null>;
+    getGroup<T>(traceId: string): Promise<T[]>;
+    clear(traceId: string): Promise<void>;
+    cleanup(): Promise<void>;
+    keys(traceId: string): Promise<string[]>;
+    traceIds(): Promise<string[]>;
+    items(input: StateItemsInput): Promise<StateItem[]>;
+    private scanKeys;
+    private applyFilters;
+    private matchesFilter;
+}
+//# sourceMappingURL=redis-state-adapter.d.ts.map

package/dist/redis-state-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-state-adapter.d.ts","sourceRoot":"","sources":["../src/redis-state-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAe,SAAS,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAE3F,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAA;AAEtD,qBAAa,iBAAkB,YAAW,YAAY;IACpD,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,GAAG,CAAC,CAAQ;IACpB,OAAO,CAAC,SAAS,CAAQ;gBAEb,MAAM,EAAE,uBAAuB;YA2C7B,OAAO;YAWP,eAAe;IAM7B,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,aAAa;IAQf,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAOvD,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAc1D,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAQ1D,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAW1C,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAMxB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAOxC,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAiB7B,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;YAkD3C,QAAQ;IAgBtB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,aAAa;CAmCtB"}

package/dist/redis-state-adapter.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisStateAdapter = void 0;
+const redis_1 = require("redis");
+class RedisStateAdapter {
+    constructor(config) {
+        this.connected = false;
+        this.keyPrefix = config.keyPrefix || 'motia:state:';
+        this.ttl = config.ttl;
+        this.client = (0, redis_1.createClient)({
+            socket: {
+                host: config.host || 'localhost',
+                port: config.port || 6379,
+                reconnectStrategy: config.socket?.reconnectStrategy ||
+                    ((retries) => {
+                        if (retries > 10) {
+                            return new Error('Redis connection retry limit exceeded');
+                        }
+                        return Math.min(retries * 100, 3000);
+                    }),
+                connectTimeout: config.socket?.connectTimeout || 10000,
+            },
+            password: config.password,
+            username: config.username,
+            database: config.database || 0,
+        });
+        this.client.on('error', (err) => {
+            console.error('[Redis State] Client error:', err);
+        });
+        this.client.on('connect', () => {
+            this.connected = true;
+        });
+        this.client.on('disconnect', () => {
+            console.warn('[Redis State] Disconnected');
+            this.connected = false;
+        });
+        this.client.on('reconnecting', () => {
+            console.log('[Redis State] Reconnecting...');
+        });
+        this.connect();
+    }
+    async connect() {
+        if (!this.connected && !this.client.isOpen) {
+            try {
+                await this.client.connect();
+            }
+            catch (error) {
+                console.error('[Redis State] Failed to connect:', error);
+                throw error;
+            }
+        }
+    }
+    async ensureConnected() {
+        if (!this.client.isOpen) {
+            await this.connect();
+        }
+    }
+    makeKey(traceId, key) {
+        return `${this.keyPrefix}${traceId}:${key}`;
+    }
+    makeTracePrefix(traceId) {
+        return `${this.keyPrefix}${traceId}:`;
+    }
+    extractKey(fullKey, traceId) {
+        const prefix = this.makeTracePrefix(traceId);
+        return fullKey.slice(prefix.length);
+    }
+    determineType(value) {
+        if (value === null)
+            return 'null';
+        if (Array.isArray(value))
+            return 'array';
+        return (['string', 'number', 'boolean', 'object'].find((type) => typeof value === type) || 'object');
+    }
+    async get(traceId, key) {
+        await this.ensureConnected();
+        const fullKey = this.makeKey(traceId, key);
+        const value = await this.client.get(fullKey);
+        return value ? JSON.parse(value) : null;
+    }
+    async set(traceId, key, value) {
+        await this.ensureConnected();
+        const fullKey = this.makeKey(traceId, key);
+        const serialized = JSON.stringify(value);
+        if (this.ttl) {
+            await this.client.setEx(fullKey, this.ttl, serialized);
+        }
+        else {
+            await this.client.set(fullKey, serialized);
+        }
+        return value;
+    }
+    async delete(traceId, key) {
+        await this.ensureConnected();
+        const fullKey = this.makeKey(traceId, key);
+        const value = await this.get(traceId, key);
+        await this.client.del(fullKey);
+        return value;
+    }
+    async getGroup(traceId) {
+        await this.ensureConnected();
+        const pattern = `${this.makeTracePrefix(traceId)}*`;
+        const keys = await this.scanKeys(pattern);
+        if (keys.length === 0)
+            return [];
+        const values = await this.client.mGet(keys);
+        return values.filter((v) => v !== null).map((v) => JSON.parse(v));
+    }
+    async clear(traceId) {
+        await this.ensureConnected();
+        const pattern = `${this.makeTracePrefix(traceId)}*`;
+        const keys = await this.scanKeys(pattern);
+        if (keys.length > 0) {
+            await this.client.del(keys);
+        }
+    }
+    async cleanup() {
+        if (this.client.isOpen) {
+            await this.client.quit();
+        }
+    }
+    async keys(traceId) {
+        await this.ensureConnected();
+        const pattern = `${this.makeTracePrefix(traceId)}*`;
+        const keys = await this.scanKeys(pattern);
+        return keys.map((key) => this.extractKey(key, traceId));
+    }
+    async traceIds() {
+        await this.ensureConnected();
+        const pattern = `${this.keyPrefix}*`;
+        const keys = await this.scanKeys(pattern);
+        const traceIdSet = new Set();
+        for (const key of keys) {
+            const withoutPrefix = key.slice(this.keyPrefix.length);
+            const traceId = withoutPrefix.split(':')[0];
+            if (traceId) {
+                traceIdSet.add(traceId);
+            }
+        }
+        return Array.from(traceIdSet);
+    }
+    async items(input) {
+        await this.ensureConnected();
+        const items = [];
+        if (input.groupId) {
+            const pattern = `${this.makeTracePrefix(input.groupId)}*`;
+            const keys = await this.scanKeys(pattern);
+            for (const fullKey of keys) {
+                const value = await this.client.get(fullKey);
+                if (value !== null) {
+                    const key = this.extractKey(fullKey, input.groupId);
+                    const parsedValue = JSON.parse(value);
+                    items.push({
+                        groupId: input.groupId,
+                        key,
+                        type: this.determineType(parsedValue),
+                        value: parsedValue,
+                    });
+                }
+            }
+        }
+        else {
+            const traceIds = await this.traceIds();
+            for (const traceId of traceIds) {
+                const pattern = `${this.makeTracePrefix(traceId)}*`;
+                const keys = await this.scanKeys(pattern);
+                for (const fullKey of keys) {
+                    const value = await this.client.get(fullKey);
+                    if (value !== null) {
+                        const key = this.extractKey(fullKey, traceId);
+                        const parsedValue = JSON.parse(value);
+                        items.push({
+                            groupId: traceId,
+                            key,
+                            type: this.determineType(parsedValue),
+                            value: parsedValue,
+                        });
+                    }
+                }
+            }
+        }
+        if (input.filter && input.filter.length > 0) {
+            return this.applyFilters(items, input.filter);
+        }
+        return items;
+    }
+    async scanKeys(pattern) {
+        const keys = [];
+        let cursor = 0;
+        do {
+            const result = await this.client.scan(cursor, {
+                MATCH: pattern,
+                COUNT: 100,
+            });
+            cursor = result.cursor;
+            keys.push(...result.keys);
+        } while (cursor !== 0);
+        return keys;
+    }
+    applyFilters(items, filters) {
+        return items.filter((item) => {
+            return filters.every((filter) => this.matchesFilter(item, filter));
+        });
+    }
+    matchesFilter(item, filter) {
+        const value = typeof item.value === 'object' && item.value !== null ? item.value[filter.valueKey] : item.value;
+        const filterValue = filter.value;
+        switch (filter.operation) {
+            case 'eq':
+                return value === filterValue;
+            case 'neq':
+                return value !== filterValue;
+            case 'gt':
+                return value > filterValue;
+            case 'gte':
+                return value >= filterValue;
+            case 'lt':
+                return value < filterValue;
+            case 'lte':
+                return value <= filterValue;
+            case 'contains':
+                return typeof value === 'string' && value.includes(filterValue);
+            case 'notContains':
+                return typeof value === 'string' && !value.includes(filterValue);
+            case 'startsWith':
+                return typeof value === 'string' && value.startsWith(filterValue);
+            case 'endsWith':
+                return typeof value === 'string' && value.endsWith(filterValue);
+            case 'isNotNull':
+                return value !== null && value !== undefined;
+            case 'isNull':
+                return value === null || value === undefined;
+            default:
+                return false;
+        }
+    }
+}
+exports.RedisStateAdapter = RedisStateAdapter;

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+export interface RedisStateAdapterConfig {
+    host?: string;
+    port?: number;
+    password?: string;
+    username?: string;
+    database?: number;
+    keyPrefix?: string;
+    ttl?: number;
+    socket?: {
+        reconnectStrategy?: (retries: number) => number | Error;
+        connectTimeout?: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE;QACP,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,KAAK,CAAA;QACvD,cAAc,CAAC,EAAE,MAAM,CAAA;KACxB,CAAA;CACF"}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@motiadev/adapter-redis-state",
+  "description": "Redis state adapter for Motia framework, enabling distributed state management across multiple instances.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "version": "0.8.2-beta.140-709523",
+  "dependencies": {
+    "redis": "^4.7.0",
+    "@motiadev/core": "0.8.2-beta.140-709523"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "@motiadev/core": "^0.8.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "lint": "biome check .",
+    "watch": "tsc --watch"
+  }
+}