{"id":50944305,"url":"https://github.com/codecaine-zz/bun_redis_tool","last_synced_at":"2026-06-17T18:07:37.390Z","repository":{"id":358367480,"uuid":"1241126602","full_name":"codecaine-zz/bun_redis_tool","owner":"codecaine-zz","description":"A lightweight, high-performance CLI utility for reading, writing, deleting, and listing keys in Redis using namespaces. Built with Bun's native Redis client.","archived":false,"fork":false,"pushed_at":"2026-06-13T23:44:31.000Z","size":13,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T01:19:29.278Z","etag":null,"topics":["bun","console","console-application","crud","crud-application","execuable","javascript","neutralinojs","neutralinojs-client","python","pywebview","rad","redis","subprocess","subprocess-run","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codecaine-zz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-17T01:46:59.000Z","updated_at":"2026-06-13T23:44:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codecaine-zz/bun_redis_tool","commit_stats":null,"previous_names":["codecaine-zz/bun_redis_tool"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/codecaine-zz/bun_redis_tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codecaine-zz%2Fbun_redis_tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codecaine-zz%2Fbun_redis_tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codecaine-zz%2Fbun_redis_tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codecaine-zz%2Fbun_redis_tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codecaine-zz","download_url":"https://codeload.github.com/codecaine-zz/bun_redis_tool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codecaine-zz%2Fbun_redis_tool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34459783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","console","console-application","crud","crud-application","execuable","javascript","neutralinojs","neutralinojs-client","python","pywebview","rad","redis","subprocess","subprocess-run","typescript"],"created_at":"2026-06-17T18:07:36.803Z","updated_at":"2026-06-17T18:07:37.384Z","avatar_url":"https://github.com/codecaine-zz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Redis Tool\n\nA lightweight, high-performance utility for reading, writing, deleting, and listing keys in Redis using namespaces. Built with [Bun's native Redis client](https://bun.sh/docs/runtime/redis#redis).\n\nThis tool is designed to be multi-purpose:\n1. **Console App:** Provides clean, human-readable output in your terminal when run directly.\n2. **Subprocess:** Outputs exact raw strings (without extra newlines or formatting) when spawned by another application, making it perfectly suited for inter-process communication.\n3. **Importable Module:** Can be compiled to a single file and imported directly into other Bun runtime files.\n\n## Prerequisites\n\n- [Bun](https://bun.sh/) installed on your machine.\n- A running Redis server.\n\n## Configuration\n\nBy default, Bun's Redis client will attempt to connect to `redis://localhost:6379`. You can override this by setting the `REDIS_URL` environment variable:\n\n```bash\nexport REDIS_URL=\"redis://username:password@your-redis-host:6379\"\n```\n\n## Installation\n\nInstall the package in your project using Bun:\n\n```bash\nbun add bun-redis-tool\n```\n\nOr with npm:\n\n```bash\nnpm install bun-redis-tool\n```\n\n## Compilation \u0026 Bundling\n\nYou can compile and bundle the tool in two different formats:\n\n### 1. Bundled Single JS File (For importing in other Bun files)\nTo bundle the tool into a single module file that you can import in other Bun projects:\n\n```bash\nbun run build\n```\nThis outputs a single-file bundle to `dist/redis_tool.js`.\n\n### 2. Standalone Executable (CLI)\nTo compile the script into a single, standalone binary:\n\n```bash\nbun run compile\n```\nThis compiles the tool into the standalone executable `redis-tool`.\n\n## Usage as an Importable Module\n\nYou can import `RedisTool` from `bun-redis-tool` in any other Bun runtime file. Below are comprehensive examples covering everything the module can do.\n\n### 1. Initialization and Connection Modes\n\nThe `RedisTool` class is highly flexible. It accepts the namespace as the first argument, and optionally a Redis client configuration or existing instance as the second argument:\n\n```typescript\nimport { RedisTool } from \"bun-redis-tool\";\nimport { RedisClient } from \"bun\";\n\n// Mode A: Connect using default configuration (uses REDIS_URL environment variable or localhost:6379)\nconst cache = new RedisTool(\"cache\");\n\n// Mode B: Connect to a custom Redis URL string\nconst db = new RedisTool(\"users\", \"redis://:my-secret-password@redis-host:6379\");\n\n// Mode C: Reuse an existing client connection (ideal for multiple namespaces to avoid opening extra socket connections)\nconst sharedClient = new RedisClient();\nconst sessions = new RedisTool(\"session\", sharedClient);\nconst metrics = new RedisTool(\"metric\", sharedClient);\n```\n\n### 2. Reading and Writing Data\n\nThe tool automatically prefixes keys with the namespace (e.g. `namespace:key`).\n\n```typescript\n// A. Write a persistent value (string)\nawait cache.write(\"theme\", \"dark\");\n\n// B. Read a value (returns string or null if key does not exist)\nconst theme = await cache.read(\"theme\"); // \"dark\"\nconst missing = await cache.read(\"nonexistent\"); // null\n\n// C. Storing and retrieving JSON objects\nconst userObj = { id: 42, name: \"Alice\", roles: [\"admin\"] };\nawait cache.write(\"user_42\", JSON.stringify(userObj));\n\nconst rawUser = await cache.read(\"user_42\");\nif (rawUser) {\n  const user = JSON.parse(rawUser);\n  console.log(user.name); // \"Alice\"\n}\n```\n\n### 3. Expiration and TTL (Time-To-Live)\n\nYou can specify a TTL in seconds when writing a key.\n\n```typescript\n// Write a key that automatically expires after 10 minutes (600 seconds)\nawait cache.write(\"temp_token\", \"abc123xyz\", 600);\n```\n\n### 4. Listing Keys\n\nYou can query all keys belonging to the current namespace.\n\n```typescript\n// Set some keys\nawait cache.write(\"key_a\", \"val_a\");\nawait cache.write(\"key_b\", \"val_b\");\n\n// List all keys (returns string[] of matching keys, including namespace prefix)\nconst allKeys = await cache.list();\nconsole.log(allKeys); // [\"cache:key_a\", \"cache:key_b\"]\n```\n\n### 5. Deleting Data\n\n```typescript\n// A. Delete a single key (returns number of keys deleted: 1 if deleted, 0 if it didn't exist)\nconst deletedCount = await cache.delete(\"key_a\"); // 1\nconst deleteNonexistent = await cache.delete(\"key_a\"); // 0\n\n// B. Delete ALL keys within the namespace (Clear)\n// This finds all keys matching \"namespace:*\" and deletes them at once\nconst clearedCount = await cache.clear();\nconsole.log(`Cleared ${clearedCount} namespace keys`);\n```\n\n### 6. Closing Connections\n\nAlways clean up connections once you are done using the client:\n\n```typescript\ncache.close();\n// Note: If you passed an existing RedisClient to the constructor,\n// calling close() on RedisTool will also close that shared client.\n```\n\n## CLI Usage\n\nThe tool accepts up to five positional arguments depending on the action:\n`[action] [namespace] [key] [value] [ttl_in_seconds]`\n\n*(Notes: The `key` is optional for `list` and `clear`. The `value` is required for `write`. The `ttl_in_seconds` is optional for `write`.)*\n\n### Running directly with Bun\n\n**Write a persistent value:**\n\n```bash\nbun run redis_tool.ts write myapp session_id \"xyz_12345\"\n```\n\n**Write a value that expires (e.g., 3600 seconds / 1 hour):**\n\n```bash\nbun run redis_tool.ts write myapp temp_session \"abc_987\" 3600\n```\n\n**Read a value:**\n\n```bash\nbun run redis_tool.ts read myapp session_id\n```\n\n**Delete a value:**\n\n```bash\nbun run redis_tool.ts delete myapp session_id\n```\n\n**List all keys in a namespace:**\n\n```bash\nbun run redis_tool.ts list myapp\n```\n\n**Delete all keys in a namespace (Clear):**\n\n```bash\nbun run redis_tool.ts clear myapp\n```\n\n### Running the Standalone Executable\n\nOnce compiled, you can run the binary directly:\n\n```bash\n./redis-tool write myapp test \"hello world\"\n./redis-tool read myapp test\n```\n\nIf you move the compiled binary to your `/usr/local/bin` folder, you can run it from any directory:\n\n```bash\nsudo mv redis-tool /usr/local/bin/\nredis-tool list myapp\n```\n\n## Usage as a Subprocess\n\nBecause `redis_tool.ts` automatically detects when it is not running in a TTY terminal, it strips conversational formatting and trailing newlines from output operations. This makes it incredibly easy to consume the stdout stream from another script.\n\n**Example: Reading a single value**\n\n```typescript\nasync function readValue() {\n  const readProc = Bun.spawn([\"redis-tool\", \"read\", \"myapp\", \"test\"]);\n  const output = await new Response(readProc.stdout).text();\n  console.log(\"Read from subprocess:\", output); \n}\n```\n\n**Example: Parsing a list of keys**\n\n```typescript\nasync function listKeys() {\n  const listProc = Bun.spawn([\"redis-tool\", \"list\", \"myapp\"]);\n  const output = await new Response(listProc.stdout).text();\n  \n  // Split the raw string into a clean array of keys\n  const keysArray = output.split(\"\\n\").filter(Boolean); \n  console.log(\"Keys found:\", keysArray);\n}\n```\n\n## How it Works (Namespaces)\n\nWhen you provide a namespace and a key, the tool automatically joins them with a colon (`:`).\nFor example, running `redis-tool write cache user_1 \"Alice\"` will execute `SET cache:user_1 \"Alice\"` under the hood. If you provide a TTL of 60, it will follow up with an `EXPIRE cache:user_1 60` command. Similarly, `redis-tool list cache` executes a `KEYS cache:*` pattern match to find all relevant records.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodecaine-zz%2Fbun_redis_tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodecaine-zz%2Fbun_redis_tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodecaine-zz%2Fbun_redis_tool/lists"}