@jordanalec/dtk 1.0.6 → 1.1.0

package/README.md

@@ -286,6 +286,57 @@ AWS credentials are resolved from the environment via the SDK default provider c
 
 ---
 
+### redis
+
+Reads and writes data in a Redis cache.
+
+```bash
+dtk add redis
+```
+
+Env vars appended to `.env.template`:
+
+```
+REDIS_URL=redis://localhost:6379
+```
+
+Usage:
+
+```ts
+await suite()
+  .redis({ url: process.env.REDIS_URL! })
+  .step("write", async (ctx) => {
+    await ctx.services.redis.set("key", "value", 3600);
+  })
+  .step("read", async (ctx) => {
+    const value = await ctx.services.redis.get("key");
+    console.log("value:", value);
+    return value;
+  })
+  .step("disconnect", async (ctx) => {
+    await ctx.services.redis.quit();
+  })
+  .run("stopOnError");
+```
+
+> **The `disconnect` step is required.** The Redis client holds an open TCP connection. Without calling `quit()`, the Node.js process will hang indefinitely after the runbook finishes. Always use `stopOnError` (not `throwOnError`) so that the `disconnect` step is guaranteed to run even when an earlier step fails.
+
+Available methods on `ctx.services.redis`:
+
+| Method | Description |
+|---|---|
+| `get(key)` | Returns the string value or `null` if the key does not exist |
+| `set(key, value, ttlSeconds?)` | Sets a key, with an optional TTL in seconds |
+| `del(key)` | Deletes a key, returns the number of keys removed |
+| `exists(key)` | Returns `true` if the key exists |
+| `expire(key, ttlSeconds)` | Sets a TTL on an existing key, returns `true` if applied |
+| `hset(key, field, value)` | Sets a field on a hash, returns the number of new fields added |
+| `hget(key, field)` | Returns a hash field value or `null` |
+| `keys(pattern)` | Returns all keys matching a glob pattern (e.g. `user:*`) |
+| `quit()` | Closes the connection -- must be called at the end of every runbook |
+
+---
+
 ### open-ai
 
 Lists models and sends responses via the OpenAI API.
@@ -728,4 +779,5 @@ templates/
     aws-dynamo/
     aws-s3/
     open-ai/
+    redis/
 ```

package/dist/add.js

@@ -12,6 +12,7 @@ const PLUGIN_MAP = {
     'aws-dynamo': 'aws-dynamo',
     'aws-s3': 'aws-s3',
     'open-ai': 'open-ai',
+    'redis': 'redis',
 };
 export const addCommand = new Command('add')
     .description('Add a service plugin to the project')

package/dist/cli.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { createRequire } from 'module';
 import { initCommand } from './init.js';
 import { addCommand } from './add.js';
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
 const program = new Command();
 program
     .name('dtk')
     .description('Developer toolkit scaffolder')
-    .version('0.0.1');
+    .version(version);
 program.addCommand(initCommand);
 program.addCommand(addCommand);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jordanalec/dtk",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "CLI scaffolding tool for generating self-contained TypeScript runbook projects",
   "keywords": [
     "cli",
@@ -45,6 +45,7 @@
     "axios": "^1.6.0",
     "dotenv": "^16.4.0",
     "jest": "^30.3.0",
+    "redis": "^4.7.1",
     "ts-jest": "^29.4.9",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"

package/templates/init/GUIDE.md

@@ -382,6 +382,57 @@ AWS credentials are picked up automatically from `AWS_ACCESS_KEY_ID` and `AWS_SE
 
 ---
 
+### redis
+
+Reads and writes data in a Redis cache.
+
+```bash
+dtk add redis
+```
+
+Required env vars:
+
+```
+REDIS_URL=redis://localhost:6379
+```
+
+Usage:
+
+```ts
+await suite()
+  .redis({ url: process.env.REDIS_URL! })
+  .step("write", async (ctx) => {
+    await ctx.services.redis.set("key", "value", 3600);
+  })
+  .step("read", async (ctx) => {
+    const value = await ctx.services.redis.get("key");
+    console.log("value:", value);
+    return value;
+  })
+  .step("disconnect", async (ctx) => {
+    await ctx.services.redis.quit();
+  })
+  .run("stopOnError");
+```
+
+> **The `disconnect` step is required.** The Redis client holds an open TCP connection. Without calling `quit()`, the Node.js process will hang indefinitely after the runbook finishes. Always use `stopOnError` (not `throwOnError`) so that the `disconnect` step is guaranteed to run even when an earlier step fails.
+
+Available methods on `ctx.services.redis`:
+
+| Method | Description |
+|---|---|
+| `get(key)` | Returns the string value or `null` if the key does not exist |
+| `set(key, value, ttlSeconds?)` | Sets a key, with an optional TTL in seconds |
+| `del(key)` | Deletes a key, returns the number of keys removed |
+| `exists(key)` | Returns `true` if the key exists |
+| `expire(key, ttlSeconds)` | Sets a TTL on an existing key, returns `true` if applied |
+| `hset(key, field, value)` | Sets a field on a hash, returns the number of new fields added |
+| `hget(key, field)` | Returns a hash field value or `null` |
+| `keys(pattern)` | Returns all keys matching a glob pattern (e.g. `user:*`) |
+| `quit()` | Closes the connection -- must be called at the end of every runbook |
+
+---
+
 ### open-ai
 
 Lists models and sends responses via the OpenAI API.

package/templates/plugins/redis/env.txt

@@ -0,0 +1 @@
+REDIS_URL=

package/templates/plugins/redis/example.ts

@@ -0,0 +1,37 @@
+import "../load-env.js";
+import { suite } from "../suite.js";
+
+await suite()
+  .redis({
+    url: process.env.REDIS_URL!,
+  })
+  .step("write-session", async (ctx) => {
+    await ctx.services.redis.set("session:abc123", JSON.stringify({ userId: 42, role: "admin" }), 3600);
+    console.log("session written with 1h TTL");
+  })
+  .step("read-session", async (ctx) => {
+    const raw = await ctx.services.redis.get("session:abc123");
+    const session = raw ? JSON.parse(raw) : null;
+    console.log("session:", session);
+    return session;
+  })
+  .step("check-existence", async (ctx) => {
+    const exists = await ctx.services.redis.exists("session:abc123");
+    console.log("session exists:", exists);
+    return exists;
+  })
+  .step("hash-metadata", async (ctx) => {
+    await ctx.services.redis.hset("user:42", "lastSeen", new Date().toISOString());
+    const lastSeen = await ctx.services.redis.hget("user:42", "lastSeen");
+    console.log("user:42 lastSeen:", lastSeen);
+    return lastSeen;
+  })
+  .step("list-session-keys", async (ctx) => {
+    const keys = await ctx.services.redis.keys("session:*");
+    console.log("active sessions:", keys);
+    return keys;
+  })
+  .step("disconnect", async (ctx) => {
+    await ctx.services.redis.quit();
+  })
+  .run("stopOnError");

package/templates/plugins/redis/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "redis",
+  "description": "Redis -- get, set, del, exists, expire, hset, hget, keys",
+  "dependencies": {
+    "redis": "^4.7.0"
+  },
+  "files": [
+    { "src": "service.ts", "dest": "src/services/redis.ts" },
+    { "src": "types.ts", "dest": "src/types/redis.ts" },
+    { "src": "service.test.ts", "dest": "src/services/redis.test.ts" }
+  ],
+  "env": "env.txt",
+  "example": "example.ts",
+  "transforms": {
+    "service.ts": [
+      { "from": "./types.js", "to": "../types/redis.js" }
+    ],
+    "service.test.ts": [
+      { "from": "./service.js", "to": "./redis.js" }
+    ]
+  },
+  "patches": {
+    "src/suite.ts": {
+      "imports": [
+        "import { createRedisService } from \"./services/redis.js\";",
+        "import type { RedisConfig } from \"./types/redis.js\";"
+      ],
+      "configs": "  private redisConfig?: RedisConfig;",
+      "methods": "  redis(config: RedisConfig): this { this.redisConfig = config; return this; }",
+      "services": "        redis: createRedisService(this.redisConfig),"
+    },
+    "src/types/suite.ts": {
+      "service-types": "    redis: { get(key: string): Promise<string | null>; set(key: string, value: string, ttlSeconds?: number): Promise<void>; del(key: string): Promise<number>; exists(key: string): Promise<boolean>; expire(key: string, ttlSeconds: number): Promise<boolean>; hset(key: string, field: string, value: string): Promise<number>; hget(key: string, field: string): Promise<string | null>; keys(pattern: string): Promise<string[]>; quit(): Promise<void>; };"
+    }
+  }
+}

package/templates/plugins/redis/service.test.ts

@@ -0,0 +1,149 @@
+import { createRedisService } from './service.js';
+
+jest.mock('redis');
+import { createClient } from 'redis';
+
+const mockClient = {
+  connect: jest.fn().mockResolvedValue(undefined),
+  get: jest.fn(),
+  set: jest.fn().mockResolvedValue('OK'),
+  del: jest.fn(),
+  exists: jest.fn(),
+  expire: jest.fn(),
+  hSet: jest.fn(),
+  hGet: jest.fn(),
+  keys: jest.fn(),
+  quit: jest.fn().mockResolvedValue(undefined),
+};
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  (createClient as jest.Mock).mockReturnValue(mockClient);
+  mockClient.connect.mockResolvedValue(undefined);
+});
+
+describe('createRedisService', () => {
+  const config = { url: 'redis://localhost:6379' };
+
+  it('connects to redis using the provided url', async () => {
+    mockClient.get.mockResolvedValue('value');
+    const redis = createRedisService(config);
+    await redis.get('key');
+    expect(createClient).toHaveBeenCalledWith({ url: config.url });
+    expect(mockClient.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it('reuses the same client across multiple calls', async () => {
+    mockClient.get.mockResolvedValue('value');
+    const redis = createRedisService(config);
+    await redis.get('key1');
+    await redis.get('key2');
+    expect(mockClient.connect).toHaveBeenCalledTimes(1);
+  });
+
+  it('get returns the value for an existing key', async () => {
+    mockClient.get.mockResolvedValue('hello');
+    const redis = createRedisService(config);
+    const result = await redis.get('greeting');
+    expect(result).toBe('hello');
+    expect(mockClient.get).toHaveBeenCalledWith('greeting');
+  });
+
+  it('get returns null for a missing key', async () => {
+    mockClient.get.mockResolvedValue(null);
+    const redis = createRedisService(config);
+    const result = await redis.get('missing');
+    expect(result).toBeNull();
+  });
+
+  it('set calls client.set without EX when no ttl is given', async () => {
+    const redis = createRedisService(config);
+    await redis.set('key', 'value');
+    expect(mockClient.set).toHaveBeenCalledWith('key', 'value');
+  });
+
+  it('set calls client.set with EX option when ttl is given', async () => {
+    const redis = createRedisService(config);
+    await redis.set('key', 'value', 60);
+    expect(mockClient.set).toHaveBeenCalledWith('key', 'value', { EX: 60 });
+  });
+
+  it('del returns the number of deleted keys', async () => {
+    mockClient.del.mockResolvedValue(1);
+    const redis = createRedisService(config);
+    const result = await redis.del('key');
+    expect(result).toBe(1);
+    expect(mockClient.del).toHaveBeenCalledWith('key');
+  });
+
+  it('exists returns true when key is present', async () => {
+    mockClient.exists.mockResolvedValue(1);
+    const redis = createRedisService(config);
+    const result = await redis.exists('key');
+    expect(result).toBe(true);
+  });
+
+  it('exists returns false when key is absent', async () => {
+    mockClient.exists.mockResolvedValue(0);
+    const redis = createRedisService(config);
+    const result = await redis.exists('missing');
+    expect(result).toBe(false);
+  });
+
+  it('expire returns true when the timeout was set', async () => {
+    mockClient.expire.mockResolvedValue(true);
+    const redis = createRedisService(config);
+    const result = await redis.expire('key', 300);
+    expect(result).toBe(true);
+    expect(mockClient.expire).toHaveBeenCalledWith('key', 300);
+  });
+
+  it('hset returns the number of new fields added', async () => {
+    mockClient.hSet.mockResolvedValue(1);
+    const redis = createRedisService(config);
+    const result = await redis.hset('hash', 'field', 'value');
+    expect(result).toBe(1);
+    expect(mockClient.hSet).toHaveBeenCalledWith('hash', 'field', 'value');
+  });
+
+  it('hget returns the field value', async () => {
+    mockClient.hGet.mockResolvedValue('stored');
+    const redis = createRedisService(config);
+    const result = await redis.hget('hash', 'field');
+    expect(result).toBe('stored');
+  });
+
+  it('hget returns null when field is undefined', async () => {
+    mockClient.hGet.mockResolvedValue(undefined);
+    const redis = createRedisService(config);
+    const result = await redis.hget('hash', 'missing');
+    expect(result).toBeNull();
+  });
+
+  it('keys returns matching key names', async () => {
+    mockClient.keys.mockResolvedValue(['user:1', 'user:2']);
+    const redis = createRedisService(config);
+    const result = await redis.keys('user:*');
+    expect(result).toEqual(['user:1', 'user:2']);
+    expect(mockClient.keys).toHaveBeenCalledWith('user:*');
+  });
+
+  it('quit disconnects the client and clears it', async () => {
+    mockClient.get.mockResolvedValue('value');
+    mockClient.quit = jest.fn().mockResolvedValue(undefined);
+    const redis = createRedisService(config);
+    await redis.get('key');
+    await redis.quit();
+    expect(mockClient.quit).toHaveBeenCalledTimes(1);
+  });
+
+  it('quit is a no-op when client was never connected', async () => {
+    const redis = createRedisService(config);
+    await expect(redis.quit()).resolves.toBeUndefined();
+  });
+
+  it('throws when any method is called without config', async () => {
+    const redis = createRedisService();
+    await expect(redis.get('key')).rejects.toThrow('redis service is not configured');
+  });
+});

package/templates/plugins/redis/service.ts

@@ -0,0 +1,66 @@
+import { createClient } from "redis";
+import type { RedisConfig } from "./types.js";
+
+export function createRedisService(config?: RedisConfig) {
+  const ensureConfig = () => {
+    if (!config) throw new Error("redis service is not configured -- call .redis(config) on the suite");
+  };
+
+  let client: ReturnType<typeof createClient> | null = null;
+
+  const getClient = async () => {
+    ensureConfig();
+    if (!client) {
+      client = createClient({ url: config!.url });
+      await client.connect();
+    }
+    return client;
+  };
+
+  return {
+    get: async (key: string): Promise<string | null> => {
+      const c = await getClient();
+      return c.get(key);
+    },
+    set: async (key: string, value: string, ttlSeconds?: number): Promise<void> => {
+      const c = await getClient();
+      if (ttlSeconds !== undefined) {
+        await c.set(key, value, { EX: ttlSeconds });
+      } else {
+        await c.set(key, value);
+      }
+    },
+    del: async (key: string): Promise<number> => {
+      const c = await getClient();
+      return c.del(key);
+    },
+    exists: async (key: string): Promise<boolean> => {
+      const c = await getClient();
+      const count = await c.exists(key);
+      return count > 0;
+    },
+    expire: async (key: string, ttlSeconds: number): Promise<boolean> => {
+      const c = await getClient();
+      return c.expire(key, ttlSeconds);
+    },
+    hset: async (key: string, field: string, value: string): Promise<number> => {
+      const c = await getClient();
+      return c.hSet(key, field, value);
+    },
+    hget: async (key: string, field: string): Promise<string | null> => {
+      const c = await getClient();
+      const result = await c.hGet(key, field);
+      return result ?? null;
+    },
+    keys: async (pattern: string): Promise<string[]> => {
+      const c = await getClient();
+      return c.keys(pattern);
+    },
+    quit: async (): Promise<void> => {
+      if (client) {
+        await client.quit();
+        client = null;
+      }
+    },
+  };
+}

package/templates/plugins/redis/types.ts

@@ -0,0 +1,3 @@
+export interface RedisConfig {
+  url: string;
+}