@rcrsr/rill-ext-kv-redis 0.8.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andre Bremer
+
+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,32 @@
+# @rcrsr/rill-ext-kv-redis
+
+Redis kv backend implementation for rill scripting language.
+
+## Installation
+
+```bash
+npm install @rcrsr/rill-ext-kv-redis
+```
+
+## Usage
+
+```typescript
+import { createRedisKvExtension } from '@rcrsr/rill-ext-kv-redis';
+
+const extension = createRedisKvExtension({
+  url: 'redis://localhost:6379',
+  mounts: {
+    // Mount configurations
+  },
+  maxStoreSize: 1000000,
+  writePolicy: 'dispose',
+});
+```
+
+## Documentation
+
+Full documentation available at [rill.run/docs/extensions/kv-redis/](https://rill.run/docs/extensions/kv-redis/)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,195 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import { ExtensionResult, SchemaEntry } from '@rcrsr/rill';
+
+/**
+ * Configuration for a single Redis kv mount.
+ *
+ * Extends common kv mount configuration with Redis-specific fields.
+ * Each mount represents a key prefix in Redis.
+ *
+ * @example
+ * ```typescript
+ * const mountConfig: RedisKvMountConfig = {
+ *   mode: 'read-write',
+ *   prefix: 'app:user:',
+ *   schema: {
+ *     name: { type: 'string', default: '' },
+ *     count: { type: 'number', default: 0 }
+ *   },
+ *   maxEntries: 5000,
+ *   maxValueSize: 50000,
+ *   ttl: 3600
+ * };
+ * ```
+ */
+export interface RedisKvMountConfig {
+	/**
+	 * Access mode for this mount.
+	 *
+	 * - 'read': Read-only access (set/delete/clear operations throw errors)
+	 * - 'write': Write-only access (get operations throw errors)
+	 * - 'read-write': Full access to all operations
+	 */
+	readonly mode: "read" | "write" | "read-write";
+	/**
+	 * Key prefix for this mount.
+	 *
+	 * All keys in this mount are prefixed with this string to namespace them.
+	 * Different mounts can use different prefixes to organize keys.
+	 *
+	 * @example 'app:user:'
+	 */
+	readonly prefix: string;
+	/**
+	 * Schema definitions (optional).
+	 *
+	 * When provided, enables declared mode:
+	 * - Only declared keys can be accessed
+	 * - Type validation enforced on set operations
+	 * - Missing keys return schema defaults
+	 *
+	 * When undefined, enables open mode:
+	 * - Any key can be accessed
+	 * - No type validation
+	 * - Missing keys return empty string
+	 */
+	readonly schema?: Record<string, SchemaEntry> | undefined;
+	/**
+	 * Maximum number of entries allowed in this mount.
+	 *
+	 * Defaults to 10000.
+	 * Set operations throw when limit exceeded.
+	 */
+	readonly maxEntries?: number | undefined;
+	/**
+	 * Maximum value size in bytes (JSON-encoded).
+	 *
+	 * Defaults to 102400 bytes (100 KB).
+	 * Set operations throw when value exceeds limit.
+	 */
+	readonly maxValueSize?: number | undefined;
+	/**
+	 * Time-to-live in seconds for keys in this mount.
+	 *
+	 * Optional - when undefined, keys do not expire.
+	 * When set, keys are automatically deleted after TTL expires.
+	 *
+	 * @example 3600 // 1 hour
+	 */
+	readonly ttl?: number | undefined;
+}
+/**
+ * Configuration options for Redis kv extension.
+ *
+ * Defines Redis connection URL, mount configurations, size limits,
+ * and write policies for Redis-backed key-value storage.
+ *
+ * @example
+ * ```typescript
+ * // Multi-mount configuration
+ * const config: RedisKvConfig = {
+ *   url: 'redis://localhost:6379',
+ *   mounts: {
+ *     user: {
+ *       mode: 'read-write',
+ *       prefix: 'app:user:',
+ *       schema: { name: { type: 'string', default: '' } },
+ *       ttl: 3600
+ *     },
+ *     cache: {
+ *       mode: 'read-write',
+ *       prefix: 'app:cache:',
+ *       ttl: 300
+ *     }
+ *   },
+ *   maxStoreSize: 5242880,
+ *   writePolicy: 'immediate'
+ * };
+ * ```
+ */
+export interface RedisKvConfig {
+	/**
+	 * Redis connection URL.
+	 *
+	 * Required - specifies the Redis server connection string.
+	 * Supports standard Redis URL format.
+	 *
+	 * @example 'redis://localhost:6379'
+	 * @example 'redis://user:pass@host:port/db'
+	 */
+	readonly url: string;
+	/**
+	 * Mount definitions keyed by mount name.
+	 *
+	 * Each mount corresponds to a key prefix in Redis.
+	 * Mount names are used in kv function calls (e.g., `kv::get('user', 'name')`).
+	 *
+	 * Required field - at least one mount must be defined.
+	 */
+	readonly mounts: Record<string, RedisKvMountConfig>;
+	/**
+	 * Maximum total store size in bytes across all mounts.
+	 *
+	 * Defaults to 10485760 bytes (10 MB).
+	 * This limit applies to the sum of all values in all mounts.
+	 * Set operations throw when total size exceeds limit.
+	 */
+	readonly maxStoreSize?: number | undefined;
+	/**
+	 * Write policy for Redis operations.
+	 *
+	 * - 'dispose': Changes buffered in memory, flushed on extension dispose (default)
+	 * - 'immediate': Each set operation writes to Redis immediately
+	 *
+	 * Immediate mode trades performance for durability.
+	 * Dispose mode is faster but risks data loss if process crashes.
+	 */
+	readonly writePolicy?: "dispose" | "immediate" | undefined;
+}
+/**
+ * Configuration for Redis kv extension factory.
+ */
+export interface RedisKvExtensionConfig {
+	/** Redis connection URL (e.g., "redis://localhost:6379") */
+	readonly url: string;
+	/** Mount point configurations */
+	readonly mounts: Record<string, RedisKvMountConfig>;
+	/** Maximum store size in bytes (optional) */
+	readonly maxStoreSize?: number | undefined;
+	/** Write policy: 'dispose' (write on dispose) or 'immediate' (write immediately) */
+	readonly writePolicy?: "dispose" | "immediate" | undefined;
+}
+/**
+ * Creates a Redis kv backend extension for rill.
+ *
+ * Connects to Redis server and validates configuration.
+ * Throws error for invalid connection string or unreachable server.
+ *
+ * @param config - Extension configuration
+ * @returns Extension result with kv functions and dispose
+ * @throws Error for invalid configuration (AC-10)
+ *
+ * @example
+ * ```typescript
+ * const ext = createRedisKvExtension({
+ *   url: 'redis://localhost:6379',
+ *   mounts: {
+ *     user: {
+ *       mode: 'read-write',
+ *       prefix: 'app:user:',
+ *       schema: { name: { type: 'string', default: '' } }
+ *     }
+ *   }
+ * });
+ * // Use with rill runtime...
+ * await ext.dispose();
+ * ```
+ */
+export declare function createRedisKvExtension(config: RedisKvExtensionConfig): ExtensionResult;
+
+export {
+	SchemaEntry,
+};
+
+export {};

package/dist/index.js

@@ -0,0 +1,425 @@
+// src/factory.ts
+import { Redis } from "ioredis";
+function createRedisKvExtension(config) {
+  if (!config.mounts || Object.keys(config.mounts).length === 0) {
+    throw new Error(
+      "Redis kv extension requires at least one mount in configuration"
+    );
+  }
+  if (!config.url || typeof config.url !== "string") {
+    throw new Error("Redis kv extension requires a valid connection URL");
+  }
+  if (!config.url.startsWith("redis://") && !config.url.startsWith("rediss://")) {
+    throw new Error(
+      `Invalid Redis connection URL: must start with redis:// or rediss:// (got: ${config.url})`
+    );
+  }
+  const prefixes = Object.entries(config.mounts).map(([name, cfg]) => ({
+    name,
+    prefix: cfg.prefix
+  }));
+  for (let i = 0; i < prefixes.length; i++) {
+    for (let j = i + 1; j < prefixes.length; j++) {
+      const a = prefixes[i];
+      const b = prefixes[j];
+      if (a.prefix.startsWith(b.prefix) || b.prefix.startsWith(a.prefix)) {
+        throw new Error(
+          `Mount prefix overlap detected: "${a.name}" (${a.prefix}) and "${b.name}" (${b.prefix})`
+        );
+      }
+    }
+  }
+  let client;
+  try {
+    client = new Redis(config.url);
+  } catch (error) {
+    throw new Error(
+      `Failed to create Redis client: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  client.on("error", (err) => {
+    console.error("Redis connection error:", err);
+  });
+  function getMountConfig(mountName) {
+    const mountConfig = config.mounts[mountName];
+    if (!mountConfig) {
+      throw new Error(
+        `Mount '${mountName}' not found. Available mounts: ${Object.keys(config.mounts).join(", ")}`
+      );
+    }
+    return mountConfig;
+  }
+  function buildKey(prefix, key) {
+    return `${prefix}${key}`;
+  }
+  function checkWritePermission(mountName, mode) {
+    if (mode === "read") {
+      throw new Error(`Mount '${mountName}' is read-only (mode: ${mode})`);
+    }
+  }
+  function calculateValueSize(value) {
+    return Buffer.byteLength(JSON.stringify(value), "utf-8");
+  }
+  function validateType(key, value, expectedType) {
+    let actualType;
+    if (typeof value === "string") {
+      actualType = "string";
+    } else if (typeof value === "number") {
+      actualType = "number";
+    } else if (typeof value === "boolean") {
+      actualType = "bool";
+    } else if (Array.isArray(value)) {
+      actualType = "list";
+    } else if (typeof value === "object" && value !== null) {
+      actualType = "dict";
+    } else {
+      actualType = typeof value;
+    }
+    if (actualType !== expectedType) {
+      throw new Error(
+        `key "${key}" expects ${expectedType}, got ${actualType}`
+      );
+    }
+  }
+  function isDict(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+  const get = async (args) => {
+    const mountName = args[0];
+    const key = args[1];
+    const mountConfig = getMountConfig(mountName);
+    if (mountConfig.schema && !(key in mountConfig.schema)) {
+      throw new Error(`key "${key}" not declared in schema`);
+    }
+    const redisKey = buildKey(mountConfig.prefix, key);
+    const value = await client.get(redisKey);
+    if (value !== null) {
+      return JSON.parse(value);
+    }
+    if (mountConfig.schema && key in mountConfig.schema) {
+      return mountConfig.schema[key].default;
+    }
+    return "";
+  };
+  const get_or = async (args) => {
+    const mountName = args[0];
+    const key = args[1];
+    const fallback = args[2];
+    const mountConfig = getMountConfig(mountName);
+    const redisKey = buildKey(mountConfig.prefix, key);
+    const value = await client.get(redisKey);
+    if (value !== null) {
+      return JSON.parse(value);
+    }
+    return fallback;
+  };
+  const set = async (args) => {
+    const mountName = args[0];
+    const key = args[1];
+    const value = args[2];
+    const mountConfig = getMountConfig(mountName);
+    checkWritePermission(mountName, mountConfig.mode);
+    if (mountConfig.schema && !(key in mountConfig.schema)) {
+      throw new Error(`key "${key}" not declared in schema`);
+    }
+    if (mountConfig.schema && key in mountConfig.schema) {
+      validateType(key, value, mountConfig.schema[key].type);
+    }
+    const maxValueSize = mountConfig.maxValueSize ?? 102400;
+    const valueSize = calculateValueSize(value);
+    if (valueSize > maxValueSize) {
+      throw new Error(
+        `value for "${key}" exceeds size limit (${valueSize} > ${maxValueSize})`
+      );
+    }
+    const maxEntries = mountConfig.maxEntries ?? 1e4;
+    const redisKey = buildKey(mountConfig.prefix, key);
+    const exists = await client.exists(redisKey) === 1;
+    if (!exists) {
+      const pattern = `${mountConfig.prefix}*`;
+      const keys2 = await scanKeys(pattern);
+      if (keys2.length >= maxEntries) {
+        throw new Error(
+          `store exceeds entry limit (${keys2.length + 1} > ${maxEntries})`
+        );
+      }
+    }
+    const serialized = JSON.stringify(value);
+    if (mountConfig.ttl) {
+      await client.setex(redisKey, mountConfig.ttl, serialized);
+    } else {
+      await client.set(redisKey, serialized);
+    }
+    return true;
+  };
+  const merge = async (args) => {
+    const mountName = args[0];
+    const key = args[1];
+    const partial = args[2];
+    const mountConfig = getMountConfig(mountName);
+    checkWritePermission(mountName, mountConfig.mode);
+    const redisKey = buildKey(mountConfig.prefix, key);
+    let retries = 0;
+    const MAX_RETRIES = 10;
+    while (retries < MAX_RETRIES) {
+      await client.watch(redisKey);
+      try {
+        const currentValueStr = await client.get(redisKey);
+        let currentValue;
+        if (currentValueStr !== null) {
+          currentValue = JSON.parse(currentValueStr);
+          if (!isDict(currentValue)) {
+            await client.unwatch();
+            throw new Error(`Cannot merge into non-dict value at key "${key}"`);
+          }
+        }
+        const mergedValue = {
+          ...currentValue,
+          ...partial
+        };
+        if (mountConfig.schema && key in mountConfig.schema) {
+          validateType(key, mergedValue, mountConfig.schema[key].type);
+        }
+        const maxValueSize = mountConfig.maxValueSize ?? 102400;
+        const valueSize = calculateValueSize(mergedValue);
+        if (valueSize > maxValueSize) {
+          await client.unwatch();
+          throw new Error(
+            `merged value for "${key}" exceeds size limit (${valueSize} > ${maxValueSize})`
+          );
+        }
+        const serialized = JSON.stringify(mergedValue);
+        const result2 = await client.multi().set(redisKey, serialized).exec();
+        if (result2 !== null) {
+          if (mountConfig.ttl) {
+            await client.expire(redisKey, mountConfig.ttl);
+          }
+          return true;
+        }
+        retries++;
+      } catch (error) {
+        await client.unwatch();
+        throw error;
+      }
+    }
+    throw new Error(
+      `Failed to merge after ${MAX_RETRIES} retries due to concurrent modifications`
+    );
+  };
+  const deleteKey = async (args) => {
+    const mountName = args[0];
+    const key = args[1];
+    const mountConfig = getMountConfig(mountName);
+    checkWritePermission(mountName, mountConfig.mode);
+    const redisKey = buildKey(mountConfig.prefix, key);
+    const result2 = await client.del(redisKey);
+    return result2 > 0;
+  };
+  async function scanKeys(pattern) {
+    const keys2 = [];
+    let cursor = "0";
+    do {
+      const [nextCursor, foundKeys] = await client.scan(
+        cursor,
+        "MATCH",
+        pattern,
+        "COUNT",
+        100
+      );
+      cursor = nextCursor;
+      keys2.push(...foundKeys);
+    } while (cursor !== "0");
+    return keys2;
+  }
+  const keys = async (args) => {
+    const mountName = args[0];
+    const mountConfig = getMountConfig(mountName);
+    const pattern = `${mountConfig.prefix}*`;
+    const redisKeys = await scanKeys(pattern);
+    const prefixLen = mountConfig.prefix.length;
+    return redisKeys.map((k) => k.substring(prefixLen));
+  };
+  const has = async (args) => {
+    const mountName = args[0];
+    const key = args[1];
+    const mountConfig = getMountConfig(mountName);
+    const redisKey = buildKey(mountConfig.prefix, key);
+    const exists = await client.exists(redisKey);
+    return exists === 1;
+  };
+  const clear = async (args) => {
+    const mountName = args[0];
+    const mountConfig = getMountConfig(mountName);
+    checkWritePermission(mountName, mountConfig.mode);
+    const pattern = `${mountConfig.prefix}*`;
+    const redisKeys = await scanKeys(pattern);
+    if (redisKeys.length > 0) {
+      await client.del(...redisKeys);
+    }
+    if (mountConfig.schema) {
+      const pipeline = client.pipeline();
+      for (const [key, entry] of Object.entries(mountConfig.schema)) {
+        const redisKey = buildKey(mountConfig.prefix, key);
+        const serialized = JSON.stringify(entry.default);
+        if (mountConfig.ttl) {
+          pipeline.setex(redisKey, mountConfig.ttl, serialized);
+        } else {
+          pipeline.set(redisKey, serialized);
+        }
+      }
+      await pipeline.exec();
+    }
+    return true;
+  };
+  const getAll = async (args) => {
+    const mountName = args[0];
+    const mountConfig = getMountConfig(mountName);
+    const pattern = `${mountConfig.prefix}*`;
+    const redisKeys = await scanKeys(pattern);
+    if (redisKeys.length === 0) {
+      return {};
+    }
+    const values = await client.mget(...redisKeys);
+    const result2 = {};
+    const prefixLen = mountConfig.prefix.length;
+    for (let i = 0; i < redisKeys.length; i++) {
+      const key = redisKeys[i].substring(prefixLen);
+      const value = values[i];
+      if (value !== null && value !== void 0) {
+        result2[key] = JSON.parse(value);
+      }
+    }
+    return result2;
+  };
+  const schema = (args) => {
+    const mountName = args[0];
+    const mountConfig = getMountConfig(mountName);
+    if (!mountConfig.schema) {
+      return [];
+    }
+    const result2 = [];
+    for (const [key, entry] of Object.entries(mountConfig.schema)) {
+      result2.push({
+        key,
+        type: entry.type,
+        description: entry.description ?? ""
+      });
+    }
+    return result2;
+  };
+  const mountsList = () => {
+    const result2 = [];
+    for (const [name, mountConfig] of Object.entries(config.mounts)) {
+      result2.push({
+        name,
+        mode: mountConfig.mode,
+        schema: mountConfig.schema ? "declared" : "open",
+        maxEntries: mountConfig.maxEntries ?? 1e4,
+        maxValueSize: mountConfig.maxValueSize ?? 102400,
+        prefix: mountConfig.prefix,
+        ttl: mountConfig.ttl ?? 0
+      });
+    }
+    return result2;
+  };
+  const result = {
+    get: {
+      params: [
+        { name: "mount", type: "string", description: "Mount name" },
+        { name: "key", type: "string", description: "Key to retrieve" }
+      ],
+      fn: get,
+      description: "Get value or schema default",
+      returnType: "any"
+    },
+    get_or: {
+      params: [
+        { name: "mount", type: "string", description: "Mount name" },
+        { name: "key", type: "string", description: "Key to retrieve" },
+        {
+          name: "fallback",
+          type: "dict",
+          description: "Fallback value if key missing"
+        }
+      ],
+      fn: get_or,
+      description: "Get value or return fallback if key missing",
+      returnType: "any"
+    },
+    set: {
+      params: [
+        { name: "mount", type: "string", description: "Mount name" },
+        { name: "key", type: "string", description: "Key to set" },
+        { name: "value", type: "string", description: "Value to store" }
+      ],
+      fn: set,
+      description: "Set value with validation",
+      returnType: "bool"
+    },
+    merge: {
+      params: [
+        { name: "mount", type: "string", description: "Mount name" },
+        { name: "key", type: "string", description: "Key to merge into" },
+        { name: "partial", type: "dict", description: "Partial dict to merge" }
+      ],
+      fn: merge,
+      description: "Merge partial dict into existing dict value",
+      returnType: "bool"
+    },
+    delete: {
+      params: [
+        { name: "mount", type: "string", description: "Mount name" },
+        { name: "key", type: "string", description: "Key to delete" }
+      ],
+      fn: deleteKey,
+      description: "Delete key",
+      returnType: "bool"
+    },
+    keys: {
+      params: [{ name: "mount", type: "string", description: "Mount name" }],
+      fn: keys,
+      description: "Get all keys in mount",
+      returnType: "list"
+    },
+    has: {
+      params: [
+        { name: "mount", type: "string", description: "Mount name" },
+        { name: "key", type: "string", description: "Key to check" }
+      ],
+      fn: has,
+      description: "Check key existence",
+      returnType: "bool"
+    },
+    clear: {
+      params: [{ name: "mount", type: "string", description: "Mount name" }],
+      fn: clear,
+      description: "Clear all keys in mount",
+      returnType: "bool"
+    },
+    getAll: {
+      params: [{ name: "mount", type: "string", description: "Mount name" }],
+      fn: getAll,
+      description: "Get all entries as dict",
+      returnType: "dict"
+    },
+    schema: {
+      params: [{ name: "mount", type: "string", description: "Mount name" }],
+      fn: schema,
+      description: "Get schema information",
+      returnType: "list"
+    },
+    mounts: {
+      params: [],
+      fn: mountsList,
+      description: "Get list of mount metadata",
+      returnType: "list"
+    }
+  };
+  result.dispose = async () => {
+    await client.quit();
+  };
+  return result;
+}
+export {
+  createRedisKvExtension
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@rcrsr/rill-ext-kv-redis",
+  "version": "0.8.5",
+  "description": "rill extension for Redis kv backend implementation",
+  "license": "MIT",
+  "author": "Andre Bremer",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "rill",
+    "redis",
+    "kv",
+    "key-value",
+    "storage",
+    "extension",
+    "scripting"
+  ],
+  "peerDependencies": {
+    "@rcrsr/rill": "^0.8.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "dts-bundle-generator": "^9.5.1",
+    "tsup": "^8.5.0",
+    "undici-types": "^7.21.0",
+    "@rcrsr/rill": "^0.8.5"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rcrsr/rill.git",
+    "directory": "packages/ext/kv-redis"
+  },
+  "homepage": "https://rill.run/docs/extensions/kv-redis/",
+  "bugs": {
+    "url": "https://github.com/rcrsr/rill/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ioredis": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsup && dts-bundle-generator --config dts-bundle-generator.config.cjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint --config ../../../eslint.config.js src/",
+    "check": "pnpm run build && pnpm run test && pnpm run lint"
+  }
+}