@rx-ted/packages-honest-plugins 1.0.1

package/cache/node_modules/.bin/yaml

@@ -0,0 +1,22 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/Users/ben/projects/app/node_modules/.pnpm/yaml@2.9.0/node_modules/yaml/node_modules:/Users/ben/projects/app/node_modules/.pnpm/yaml@2.9.0/node_modules:/Users/ben/projects/app/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/Users/ben/projects/app/node_modules/.pnpm/yaml@2.9.0/node_modules/yaml/node_modules:/Users/ben/projects/app/node_modules/.pnpm/yaml@2.9.0/node_modules:/Users/ben/projects/app/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../../node_modules/.pnpm/yaml@2.9.0/node_modules/yaml/bin.mjs" "$@"
+else
+  exec node  "$basedir/../../../../../node_modules/.pnpm/yaml@2.9.0/node_modules/yaml/bin.mjs" "$@"
+fi
+# cmd-shim-target=/Users/ben/projects/app/node_modules/.pnpm/yaml@2.9.0/node_modules/yaml/bin.mjs

package/cache/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"4.1.8","results":[[":src/cacheable.test.ts",{"duration":5.22483299999999,"failed":false}],[":src/redis/driver.test.ts",{"duration":5.951208999999977,"failed":false}],[":src/resolve.test.ts",{"duration":8.927333000000004,"failed":false}],[":src/index.test.ts",{"duration":1.8274999999999864,"failed":false}],[":src/cloudflare/driver.test.ts",{"duration":4.579999999999984,"failed":false}],[":src/cache-service.test.ts",{"duration":1.563874999999996,"failed":false}]]}

package/cache/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@rx-ted/packages-honest-plugins-cache",
+  "version": "1.0.1",
+  "private": true,
+  "description": "Cache plugin for @rx-ted/packages-honest",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "vitest": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": [
+    "./dist/index.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rx-ted/honest.git"
+  },
+  "author": "rx-ted",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "redis": "^4.7.1",
+    "@rx-ted/packages-core": "workspace:^"
+  },
+  "peerDependencies": {
+    "@rx-ted/packages-honest": "workspace:^",
+    "hono": "^4.12.18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "vitest": "^4.1.7"
+  }
+}

package/cache/src/cache-service.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+import { CacheService, CACHE_GLOBAL_KEY } from './cache-service';
+
+describe('CacheService', () => {
+  it('exports CACHE_GLOBAL_KEY as "app:cache"', () => {
+    expect(CACHE_GLOBAL_KEY).toBe('app:cache');
+  });
+
+  it('is a class', () => {
+    expect(typeof CacheService).toBe('function');
+  });
+
+  it('throws when instantiated without ComponentManager registration', () => {
+    expect(() => new CacheService()).toThrow();
+  });
+});

package/cache/src/cache-service.ts

@@ -0,0 +1,15 @@
+import { Service, ComponentManager } from '@rx-ted/packages-honest';
+import type { CacheDriver } from './types';
+
+export const CACHE_GLOBAL_KEY = 'app:cache';
+
+@Service()
+class CacheService {
+  constructor() {
+    return ComponentManager.getPlugin<CacheDriver>(CACHE_GLOBAL_KEY);
+  }
+}
+
+interface CacheService extends CacheDriver {}
+
+export { CacheService };

package/cache/src/cacheable.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi } from 'vitest';
+import { cacheable } from './cacheable';
+import type { CacheDriver } from './types';
+
+function createMockDriver(): CacheDriver {
+  return {
+    get: vi.fn(),
+    set: vi.fn(),
+    delete: vi.fn(),
+    exists: vi.fn(),
+    mget: vi.fn(),
+    mset: vi.fn(),
+    deleteByPattern: vi.fn(),
+    incr: vi.fn(),
+    decr: vi.fn(),
+    expire: vi.fn(),
+    close: vi.fn(),
+    healthCheck: vi.fn(),
+  };
+}
+
+describe('cacheable', () => {
+  it('returns cached value when cache hits', async () => {
+    const cache = createMockDriver();
+    cache.get = vi.fn().mockResolvedValue('cached-value');
+
+    const result = await cacheable(cache, 'my-key', 60, async () => 'fresh-value');
+
+    expect(result).toBe('cached-value');
+    expect(cache.get).toHaveBeenCalledWith('my-key');
+  });
+
+  it('calls fetch and caches result when cache misses', async () => {
+    const cache = createMockDriver();
+    cache.get = vi.fn().mockResolvedValue(null);
+    cache.set = vi.fn().mockResolvedValue(true);
+
+    const fetch = vi.fn().mockResolvedValue('fresh-value');
+    const result = await cacheable(cache, 'my-key', 60, fetch);
+
+    expect(result).toBe('fresh-value');
+    expect(cache.get).toHaveBeenCalledWith('my-key');
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(cache.set).toHaveBeenCalledWith('my-key', 'fresh-value', 60);
+  });
+
+  it('does not cache when fetch returns null', async () => {
+    const cache = createMockDriver();
+    cache.get = vi.fn().mockResolvedValue(null);
+    cache.set = vi.fn();
+
+    const result = await cacheable(cache, 'my-key', 60, async () => null);
+
+    expect(result).toBeNull();
+    expect(cache.set).not.toHaveBeenCalled();
+  });
+
+  it('uses the provided ttl', async () => {
+    const cache = createMockDriver();
+    cache.get = vi.fn().mockResolvedValue(null);
+    cache.set = vi.fn().mockResolvedValue(true);
+
+    await cacheable(cache, 'key-ttl', 300, async () => ({ data: true }));
+
+    expect(cache.set).toHaveBeenCalledWith('key-ttl', { data: true }, 300);
+  });
+
+  it('forwards exception from fetch', async () => {
+    const cache = createMockDriver();
+    cache.get = vi.fn().mockResolvedValue(null);
+
+    await expect(
+      cacheable(cache, 'error-key', 60, async () => {
+        throw new Error('fetch-failed');
+      }),
+    ).rejects.toThrow('fetch-failed');
+  });
+});

package/cache/src/cacheable.ts

@@ -0,0 +1,16 @@
+import type { CacheDriver } from './types';
+
+export async function cacheable<T>(
+  cache: CacheDriver,
+  key: string,
+  ttl: number,
+  fetch: () => Promise<T>,
+): Promise<T> {
+  const cached = await cache.get<T>(key);
+  if (cached !== null) return cached;
+  const data = await fetch();
+  if (data !== null) {
+    await cache.set(key, data, ttl);
+  }
+  return data;
+}

package/cache/src/cloudflare/driver.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createCloudflareKvDriver } from './driver';
+import type { CacheDriver } from '../types';
+
+function mockKvNamespace() {
+  const store = new Map<string, string>();
+  return {
+    get: vi.fn(async (key: string, _options?: { cacheTtl?: number }) => store.get(key) ?? null),
+    put: vi.fn(async (key: string, value: string) => {
+      store.set(key, value);
+    }),
+    delete: vi.fn(async (key: string) => {
+      store.delete(key);
+    }),
+    list: vi.fn(async (opts?: { prefix?: string }) => {
+      const prefix = opts?.prefix ?? '';
+      const keys = [...store.keys()].filter((k) => k.startsWith(prefix)).map((name) => ({ name }));
+      return { keys, list_complete: true, cacheStatus: null };
+    }),
+  };
+}
+
+describe('CloudflareKvDriver', () => {
+  let driver: CacheDriver;
+
+  beforeEach(() => {
+    driver = createCloudflareKvDriver(mockKvNamespace());
+  });
+
+  describe('get/set', () => {
+    it('returns null for missing key', async () => {
+      const result = await driver.get('missing');
+      expect(result).toBeNull();
+    });
+
+    it('stores and retrieves a value', async () => {
+      await driver.set('foo', { hello: 'world' });
+      const result = await driver.get('foo');
+      expect(result).toEqual({ hello: 'world' });
+    });
+
+    it('stores with ttl', async () => {
+      const result = await driver.set('bar', 'value', 60);
+      expect(result).toBe(true);
+    });
+
+    it('retrieves string values', async () => {
+      await driver.set('str', 'plain-string');
+      const result = await driver.get<string>('str');
+      expect(result).toBe('plain-string');
+    });
+
+    it('retrieves numeric values', async () => {
+      await driver.set('num', 42);
+      const result = await driver.get<number>('num');
+      expect(result).toBe(42);
+    });
+  });
+
+  describe('delete', () => {
+    it('deletes an existing key', async () => {
+      await driver.set('tmp', 'value');
+      const result = await driver.delete('tmp');
+      expect(result).toBe(true);
+      const got = await driver.get('tmp');
+      expect(got).toBeNull();
+    });
+
+    it('returns true even when key does not exist', async () => {
+      const result = await driver.delete('nonexistent');
+      expect(result).toBe(true);
+    });
+  });
+
+  describe('exists', () => {
+    it('returns true for existing key', async () => {
+      await driver.set('present', 'yes');
+      const result = await driver.exists('present');
+      expect(result).toBe(true);
+    });
+
+    it('returns false for missing key', async () => {
+      const result = await driver.exists('absent');
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('mget', () => {
+    it('returns values for multiple keys', async () => {
+      await driver.set('a', 1);
+      await driver.set('b', 2);
+      const result = await driver.mget(['a', 'b', 'c']);
+      expect(result).toEqual([1, 2, null]);
+    });
+  });
+
+  describe('mset', () => {
+    it('sets multiple items', async () => {
+      const result = await driver.mset([
+        { key: 'x', value: 10 },
+        { key: 'y', value: 20, ttl: 60 },
+      ]);
+      expect(result).toBe(true);
+      expect(await driver.get('x')).toBe(10);
+      expect(await driver.get('y')).toBe(20);
+    });
+  });
+
+  describe('deleteByPattern', () => {
+    it('deletes keys matching prefix pattern', async () => {
+      await driver.set('session:abc', 1);
+      await driver.set('session:def', 2);
+      await driver.set('other:xyz', 3);
+
+      const deleted = await driver.deleteByPattern('session:*');
+      expect(deleted).toBe(2);
+      expect(await driver.get('session:abc')).toBeNull();
+      expect(await driver.get('session:def')).toBeNull();
+      expect(await driver.get('other:xyz')).toBe(3);
+    });
+
+    it('returns 0 when no keys match', async () => {
+      await driver.set('a', 1);
+      const deleted = await driver.deleteByPattern('z:*');
+      expect(deleted).toBe(0);
+    });
+  });
+
+  describe('incr/decr', () => {
+    it('incr increments from 0 for missing key', async () => {
+      const result = await driver.incr('counter');
+      expect(result).toBe(1);
+      expect(await driver.get<number>('counter')).toBe(1);
+    });
+
+    it('incr increments existing value', async () => {
+      await driver.set('counter', 5);
+      const result = await driver.incr('counter');
+      expect(result).toBe(6);
+      expect(await driver.get<number>('counter')).toBe(6);
+    });
+
+    it('decr decrements from 0 for missing key', async () => {
+      const result = await driver.decr('counter');
+      expect(result).toBe(-1);
+    });
+
+    it('decr decrements existing value', async () => {
+      await driver.set('counter', 5);
+      const result = await driver.decr('counter');
+      expect(result).toBe(4);
+    });
+
+    it('multiple incr calls accumulate', async () => {
+      await driver.incr('c');
+      await driver.incr('c');
+      const result = await driver.incr('c');
+      expect(result).toBe(3);
+    });
+  });
+
+  describe('expire', () => {
+    it('sets ttl on existing key', async () => {
+      await driver.set('tmp', 'value');
+      const result = await driver.expire('tmp', 60);
+      expect(result).toBe(true);
+      expect(await driver.get('tmp')).toBe('value');
+    });
+
+    it('returns false for missing key', async () => {
+      const result = await driver.expire('missing', 60);
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('close', () => {
+    it('does not throw', async () => {
+      await expect(driver.close()).resolves.toBeUndefined();
+    });
+  });
+
+  describe('healthCheck', () => {
+    it('returns true when namespace responds', async () => {
+      const result = await driver.healthCheck();
+      expect(result).toBe(true);
+    });
+  });
+});

package/cache/src/cloudflare/driver.ts

@@ -0,0 +1,118 @@
+import type { CacheDriver } from '../types';
+
+export interface KvNamespace {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(options?: { prefix?: string; cursor?: string }): Promise<{
+    keys: { name: string }[];
+    list_complete: boolean;
+    cursor?: string;
+    cacheStatus: string | null;
+  }>;
+}
+
+export interface CloudflareKvOptions {
+  namespace: KvNamespace;
+}
+
+class CloudflareKvDriver implements CacheDriver {
+  constructor(private namespace: KvNamespace) {}
+
+  async get<T = unknown>(key: string): Promise<T | null> {
+    if (!this.namespace) return null;
+    const value = await this.namespace.get(key);
+    if (value === null) return null;
+    return JSON.parse(value) as T;
+  }
+
+  async set(key: string, value: unknown, ttl?: number): Promise<boolean> {
+    if (!this.namespace) return false;
+    const serialized = JSON.stringify(value);
+    const options: { expirationTtl?: number } = {};
+    if (ttl) {
+      options.expirationTtl = Math.max(ttl, 60);
+    }
+    await this.namespace.put(key, serialized, options);
+    return true;
+  }
+
+  async delete(key: string): Promise<boolean> {
+    if (!this.namespace) return false;
+    await this.namespace.delete(key);
+    return true;
+  }
+
+  async exists(key: string): Promise<boolean> {
+    if (!this.namespace) return false;
+    const value = await this.namespace.get(key);
+    return value !== null;
+  }
+
+  async mget<T = unknown>(keys: string[]): Promise<(T | null)[]> {
+    return Promise.all(keys.map((key) => this.get<T>(key)));
+  }
+
+  async mset(items: Array<{ key: string; value: unknown; ttl?: number }>): Promise<boolean> {
+    await Promise.all(items.map((item) => this.set(item.key, item.value, item.ttl)));
+    return true;
+  }
+
+  async deleteByPattern(pattern: string): Promise<number> {
+    if (!this.namespace) return 0;
+    const prefix = pattern.replace(/\*.*$/, '');
+    let cursor: string | undefined;
+    let total = 0;
+    do {
+      const result = await this.namespace.list({ prefix, cursor });
+      if (result.keys.length > 0) {
+        await Promise.all(result.keys.map((k) => this.namespace.delete(k.name)));
+        total += result.keys.length;
+      }
+      cursor = result.list_complete ? undefined : result.cursor;
+    } while (cursor);
+    return total;
+  }
+
+  async incr(key: string): Promise<number> {
+    if (!this.namespace) return 0;
+    const raw = await this.namespace.get(key);
+    const current = raw !== null ? Number(JSON.parse(raw)) : 0;
+    const next = current + 1;
+    await this.namespace.put(key, JSON.stringify(next));
+    return next;
+  }
+
+  async decr(key: string): Promise<number> {
+    if (!this.namespace) return 0;
+    const raw = await this.namespace.get(key);
+    const current = raw !== null ? Number(JSON.parse(raw)) : 0;
+    const next = current - 1;
+    await this.namespace.put(key, JSON.stringify(next));
+    return next;
+  }
+
+  async expire(key: string, ttl: number): Promise<boolean> {
+    if (!this.namespace) return false;
+    const value = await this.namespace.get(key);
+    if (value === null) return false;
+    await this.namespace.put(key, value, { expirationTtl: ttl });
+    return true;
+  }
+
+  async close(): Promise<void> {}
+
+  async healthCheck(): Promise<boolean> {
+    if (!this.namespace) return false;
+    try {
+      await this.namespace.get('__health_check__');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+export function createCloudflareKvDriver(namespace: KvNamespace): CacheDriver {
+  return new CloudflareKvDriver(namespace);
+}

package/cache/src/cloudflare/index.ts

@@ -0,0 +1,3 @@
+export { CloudflareKvPlugin, CLOUDFLARE_KV_CONTEXT_KEY } from './plugin';
+export type { CloudflareKvPluginOptions } from './plugin';
+export { createCloudflareKvDriver } from './driver';

package/cache/src/cloudflare/plugin.ts

@@ -0,0 +1,71 @@
+import { ENV_SYMBOL, type Env, type ILogger, resolveBinding } from '@rx-ted/packages-core';
+import { ComponentManager, resolvePluginLogger } from '@rx-ted/packages-honest';
+import type { Application, IPlugin } from '@rx-ted/packages-honest';
+import { createCloudflareKvDriver } from './driver';
+import type { KvNamespace } from './driver';
+import type { CacheDriver } from '../types';
+import { CACHE_GLOBAL_KEY } from '../cache-service';
+
+export const CLOUDFLARE_KV_CONTEXT_KEY = 'honest:cloudflare-kv';
+
+export interface CloudflareKvPluginOptions {
+  namespace?: KvNamespace;
+  binding?: string;
+}
+
+export class CloudflareKvPlugin implements IPlugin {
+  static readonly globalKey = 'cloudflare-kv';
+  readonly name = 'cloudflare-kv-plugin';
+  readonly version = '1.0.0';
+
+  logger?: ILogger;
+  private driver?: CacheDriver;
+
+  constructor(private options: CloudflareKvPluginOptions) {}
+
+  async beforeModulesRegistered(app: Application): Promise<void> {
+    this.logger ??= resolvePluginLogger(this.name);
+    this.logger.info('Cloudflare KV: connecting...');
+
+    const appEnv = ComponentManager.hasPlugin(ENV_SYMBOL)
+      ? ComponentManager.getPlugin<Env>(ENV_SYMBOL)
+      : undefined;
+    const ns = this.options.namespace ?? resolveBinding(this.options.binding ?? '', appEnv);
+
+    if (ns) {
+      this.driver = createCloudflareKvDriver(ns);
+    } else if (this.options.binding) {
+      this.driver = createLazyDriver(() => resolveBinding(this.options.binding!, appEnv));
+      this.logger.info(`Cloudflare KV: binding "${this.options.binding}" deferred`);
+    } else {
+      throw new Error('Cloudflare KV: namespace or binding option required');
+    }
+
+    app.getContext().set(CLOUDFLARE_KV_CONTEXT_KEY, this.driver);
+    ComponentManager.registerPlugin(CACHE_GLOBAL_KEY, this.driver);
+    this.logger.info('Cloudflare KV: connected');
+  }
+
+  async close(): Promise<void> {
+    await this.driver?.close();
+  }
+}
+
+function createLazyDriver(resolve: () => any): CacheDriver {
+  let cached: CacheDriver | null = null;
+  const noop = () => Promise.resolve(null);
+
+  return new Proxy({} as CacheDriver, {
+    get(_, prop) {
+      if (!cached) {
+        const ns = resolve();
+        if (ns) cached = createCloudflareKvDriver(ns);
+      }
+      if (cached) {
+        const val = (cached as any)[prop];
+        return typeof val === 'function' ? val.bind(cached) : val;
+      }
+      return noop;
+    },
+  });
+}

package/cache/src/index.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import * as plugin from './index';
+
+describe('plugin barrel exports', () => {
+  it('exports CACHE_GLOBAL_KEY', () => {
+    expect(plugin.CACHE_GLOBAL_KEY).toBe('app:cache');
+  });
+
+  it('exports CacheService (class)', () => {
+    expect(plugin.CacheService).toBeDefined();
+    expect(typeof plugin.CacheService).toBe('function');
+  });
+
+  it('exports types through namespaces', () => {
+    expect(typeof plugin.redis.createRedisDriver).toBe('function');
+    expect(typeof plugin.cloudflare.createCloudflareKvDriver).toBe('function');
+  });
+
+  it('exports cacheable (function)', () => {
+    expect(plugin.cacheable).toBeDefined();
+    expect(typeof plugin.cacheable).toBe('function');
+  });
+
+  describe('redis exports', () => {
+    it('exports RedisPlugin', () => {
+      expect(plugin.RedisPlugin).toBeDefined();
+      expect(typeof plugin.RedisPlugin).toBe('function');
+    });
+
+    it('exports redis namespace', () => {
+      expect(plugin.redis).toBeDefined();
+      expect(plugin.redis.RedisPlugin).toBeDefined();
+      expect(plugin.redis.createRedisDriver).toBeDefined();
+    });
+
+    it('exports REDIS_CONTEXT_KEY and REDIS_GLOBAL_KEY', () => {
+      expect(plugin.REDIS_CONTEXT_KEY).toBe('honest:redis');
+      expect(plugin.REDIS_GLOBAL_KEY).toBe('redis');
+    });
+
+    it('exports createRedisDriver (async function)', () => {
+      expect(plugin.createRedisDriver).toBeDefined();
+      expect(typeof plugin.createRedisDriver).toBe('function');
+    });
+  });
+
+  describe('cloudflare exports', () => {
+    it('exports CloudflareKvPlugin', () => {
+      expect(plugin.CloudflareKvPlugin).toBeDefined();
+      expect(typeof plugin.CloudflareKvPlugin).toBe('function');
+    });
+
+    it('exports cloudflare namespace', () => {
+      expect(plugin.cloudflare).toBeDefined();
+      expect(plugin.cloudflare.CloudflareKvPlugin).toBeDefined();
+      expect(plugin.cloudflare.createCloudflareKvDriver).toBeDefined();
+    });
+
+    it('exports CLOUDFLARE_KV_CONTEXT_KEY', () => {
+      expect(plugin.CLOUDFLARE_KV_CONTEXT_KEY).toBe('honest:cloudflare-kv');
+    });
+
+    it('exports createCloudflareKvDriver (function)', () => {
+      expect(plugin.createCloudflareKvDriver).toBeDefined();
+      expect(typeof plugin.createCloudflareKvDriver).toBe('function');
+    });
+  });
+});

package/cache/src/index.ts

@@ -0,0 +1,20 @@
+// Shared
+export { CACHE_GLOBAL_KEY, CacheService } from './cache-service';
+export type { CacheDriver } from './types';
+export { cacheable } from './cacheable';
+
+// Auto-detect cache plugin (recommended)
+export { CachePlugin, findKvBinding, resolveBinding } from './resolve';
+export type { CachePluginOptions } from './resolve';
+
+// Redis driver
+export * from './redis';
+export * as redis from './redis';
+
+// Cloudflare KV driver
+export * from './cloudflare';
+export * as cloudflare from './cloudflare';
+
+// Local in-memory driver (dev)
+export * from './local';
+export * as local from './local';