chore: redis cache type implemented

Author: cemjotform

README.md

@@ -13,7 +13,7 @@ Create a `zenith.json` in your project root including `projects` and `buildConfi
 
 ## Features
 
--   **Local & Remote Caching:** Deploy faster using less bandwidth.
+-   **Local & Remote Caching:** Deploy faster using less bandwidth. Supports local disk, S3-compatible remote storage, and Redis.
 -   **No .git Required:** Ideal for team-based monorepo development.
 -   **Versatile Commands:** Supports `build`, `test`, and more.
 
@@ -26,6 +26,7 @@ Create a `zenith.json` in your project root including `projects` and `buildConfi
 - [zenith.json: What is it and why is it required?](#zenithjson-what-is-it-and-why-is-it-required)
 - [Required Parameters](#required-parameters)
   - [Environment Variables](#environment-variables)
+  - [Cache types (usage)](#cache-types-usage)
   - [Params](#params)
 - [Optional Parameters](#optional-parameters)
 - [Debugging](#debugging)
@@ -46,11 +47,52 @@ pnpm add @jotforminc/zenith
 
 From the terminal, run:
 
-
 ```
 pnpm zenith --target=("build" | "test") --project=("all" | <project_name>)
 ```
+
 Target and project arguments are required for now. Without them, the tool will not work.
+
+### Usage examples
+
+Local cache (default — artifacts stored under `.cache` on disk):
+
+```
+CACHE_TYPE=local pnpm zenith --target=build --project=all
+```
+
+Remote S3 cache (requires S3 credentials; see [Local S3 with MinIO](#local-s3-with-minio) for a local setup):
+
+```
+CACHE_TYPE=remote \
+S3_ACCESS_KEY=... \
+S3_SECRET_KEY=... \
+S3_BUCKET_NAME=... \
+S3_REGION=us-east-1 \
+pnpm zenith --target=build --project=all
+```
+
+Redis cache (requires a running Redis server; see [Redis cache](#redis-cache)):
+
+```
+CACHE_TYPE=redis \
+REDIS_URL=redis://127.0.0.1:6379 \
+pnpm zenith --target=build --project=all
+```
+
+Hybrid modes (write to both backends; read from the first that hits):
+
+```
+CACHE_TYPE=local-first pnpm zenith --target=build --project=all   # local, then remote S3
+CACHE_TYPE=remote-first pnpm zenith --target=build --project=all  # remote S3, then local
+```
+
+Optional flags used often in CI or debugging:
+
+```
+pnpm zenith --target=build --project=all --logLevel=3 --cache-format=zip
+```
+
 ## zenith.json: What is it and why is it required?
 Zenith looks for a file named "zenith.json" in the same folder where your root package.json file is. This file is used to determine the behavior of Zenith. It MUST include 'projects' and 'buildConfig' keys, and MAY include 'ignore' and 'appDirectories' keys. An example of usage is as follows.
 ```json
@@ -116,7 +158,9 @@ Zenith looks for a file named "zenith.json" in the same folder where your root p
 The project uses several required environment variables and params. Without them, the tool will not work as intended.
 ### Environment Variables
 ```
-- CACHE_TYPE (string): One of ['local', 'remote', 'local-first', 'remote-first'], 'local' by default. If 'remote', S3 environment variables are required.
+- CACHE_TYPE (string): One of ['local', 'remote', 'redis', 'local-first', 'remote-first'], 'local' by default. If 'remote' or hybrid modes that include remote, S3 environment variables are required. If 'redis', REDIS_URL is required (defaults to redis://127.0.0.1:6379).
+- REDIS_URL (string): Redis connection URL when CACHE_TYPE=redis. Default: redis://127.0.0.1:6379.
+- REDIS_KEY_PREFIX (string): Prefix for all Redis cache keys when CACHE_TYPE=redis. Default: zenith:.
 - S3_ACCESS_KEY (string): Access key to be used to get objects from and write objects to the buckets.
 - S3_SECRET_KEY (string): Secret key to be used to get objects from and write objects to the buckets.
 - S3_BUCKET_NAME (string): Bucket name to be written and read from.
@@ -145,6 +189,36 @@ export S3_REGION=us-east-1
 ```
 Stop MinIO: `yarn minio:down`.
 
+### Redis cache
+
+1. Install Redis if needed: `brew install redis`
+2. Start a local server: `yarn redis:up` (uses the `redis-server` binary on `127.0.0.1:6379`).
+   - If you prefer Docker, use `docker run -d --name zenith-redis -p 6379:6379 redis:7-alpine` (requires Docker Desktop to be running).
+3. Point Zenith at Redis:
+
+```
+export CACHE_TYPE=redis
+export REDIS_URL=redis://127.0.0.1:6379
+export REDIS_KEY_PREFIX=zenith:
+pnpm zenith --target=build --project=all
+```
+
+Stop Redis: `yarn redis:down`.
+
+Redis stores cache blobs as binary values keyed by the same paths used for S3/local storage (`zenith:` + `target/layoutHash/projectRoot/...`). Use a dedicated Redis instance or database index in shared environments.
+
+### Cache types (usage)
+
+| CACHE_TYPE | Where artifacts go | When to use |
+|------------|-------------------|-------------|
+| `local` | `.cache/` on disk (or `LOCAL_CACHE_PATH`) | Solo development, no shared cache needed |
+| `remote` | S3-compatible bucket | CI/CD teams sharing cache across machines |
+| `redis` | Redis server | Fast shared cache when you already run Redis; good for smaller/medium artifacts |
+| `local-first` | Local disk + S3 (read local first) | Dev machines with optional remote fallback |
+| `remote-first` | S3 + local disk (read remote first) | CI agents that also keep a local copy |
+
+For `remote`, `local-first`, and `remote-first`, set the S3 variables listed above. For `redis`, set `REDIS_URL` (and optionally `REDIS_KEY_PREFIX`).
+
 ### Cache format benchmark (local MinIO)
 
 After `yarn build` and `yarn minio:up`, with remote S3 env vars set:

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jotforminc/zenith",
   "packageManager": "yarn@1.22.21",
-  "version": "3.2.3",
+  "version": "3.3.0",
   "description": "",
   "main": "./build/index.js",
   "files": [
@@ -36,6 +36,8 @@
     "tsc:w": "tsc -w",
     "minio:up": "node scripts/minio-up.cjs",
     "minio:down": "node scripts/minio-down.cjs",
+    "redis:up": "node scripts/redis-up.cjs",
+    "redis:down": "node scripts/redis-down.cjs",
     "bench:cache-formats": "node scripts/benchmark-cache-formats.cjs"
   },
   "keywords": [],
@@ -47,6 +49,7 @@
     "commander": "10.0.1",
     "extract-zip": "2.0.1",
     "jszip": "3.10.1",
+    "redis": "^4.7.0",
     "tar": "7.5.11",
     "typescript": "^5.0.4",
     "voici.js": "^2.1.0",

scripts/redis-down.cjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+const fs = require('fs/promises');
+const path = require('path');
+
+const PID_PATH = path.join('/tmp', 'zenith-redis.pid');
+
+const stopRedis = async () => {
+  let pid = 0;
+  try {
+    pid = Number.parseInt((await fs.readFile(PID_PATH, 'utf8')).trim(), 10);
+  } catch {
+    process.stdout.write('Redis is not running (pid file missing).\n');
+    return;
+  }
+
+  if (Number.isInteger(pid) && pid > 0) {
+    try {
+      process.kill(pid, 'SIGTERM');
+      process.stdout.write(`Stopped Redis process ${pid}.\n`);
+    } catch {
+      process.stdout.write(`Redis process ${pid} was not running.\n`);
+    }
+  }
+
+  await fs.rm(PID_PATH, { force: true });
+};
+
+stopRedis().catch((error) => {
+  process.stderr.write(`${error?.message || error}\n`);
+  process.exit(1);
+});

scripts/redis-up.cjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+const { spawn, spawnSync } = require('child_process');
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+
+const REDIS_HOST = '127.0.0.1';
+const REDIS_PORT = 6379;
+
+const DATA_DIR = path.join('/tmp', 'zenith-redis-data');
+const LOG_PATH = path.join('/tmp', 'zenith-redis.log');
+const PID_PATH = path.join('/tmp', 'zenith-redis.pid');
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const isProcessRunning = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const pingRedis = () => {
+  const result = spawnSync(
+    'redis-cli',
+    ['-h', REDIS_HOST, '-p', `${REDIS_PORT}`, 'ping'],
+    { encoding: 'utf8' },
+  );
+  return result.stdout?.trim() === 'PONG';
+};
+
+const waitForRedisReady = async () => {
+  for (let i = 0; i < 60; i += 1) {
+    if (pingRedis()) return;
+    await sleep(500);
+  }
+  throw new Error('Redis did not become ready in time');
+};
+
+const ensureRedisInstalled = () => {
+  const server = spawnSync('redis-server', ['--version'], { stdio: 'ignore' });
+  const cli = spawnSync('redis-cli', ['--version'], { stdio: 'ignore' });
+  if (server.status !== 0 || cli.status !== 0) {
+    throw new Error('Redis is not available in PATH. Install via `brew install redis`.');
+  }
+};
+
+const startRedis = async () => {
+  ensureRedisInstalled();
+  await fsp.mkdir(DATA_DIR, { recursive: true });
+
+  if (pingRedis()) {
+    process.stdout.write(`Redis already running at redis://${REDIS_HOST}:${REDIS_PORT}\n`);
+    return;
+  }
+
+  let existingPid = 0;
+  try {
+    existingPid = Number.parseInt((await fsp.readFile(PID_PATH, 'utf8')).trim(), 10);
+  } catch {
+    existingPid = 0;
+  }
+
+  if (!isProcessRunning(existingPid)) {
+    const logFd = fs.openSync(LOG_PATH, 'a');
+    const child = spawn(
+      'redis-server',
+      [
+        '--port',
+        `${REDIS_PORT}`,
+        '--bind',
+        REDIS_HOST,
+        '--dir',
+        DATA_DIR,
+        '--save',
+        '',
+      ],
+      {
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+      },
+    );
+    child.unref();
+    await fsp.writeFile(PID_PATH, `${child.pid}\n`, 'utf8');
+  }
+
+  await waitForRedisReady();
+
+  process.stdout.write(`Redis ready at redis://${REDIS_HOST}:${REDIS_PORT}\n`);
+};
+
+startRedis().catch((error) => {
+  process.stderr.write(`${error?.message || error}\n`);
+  process.exit(1);
+});

src/classes/Cache/CacheFactory.ts

@@ -1,6 +1,7 @@
 import Cacher from './Cacher';
 import LocalCacher from './LocalCacher';
 import RemoteCacher from './RemoteCacher';
+import RedisCacher from './RedisCacher';
 import HybridCacher from './HybridCacher';
 import { configManagerInstance } from '../../config';
 
@@ -12,6 +13,8 @@ export default class CacherFactory {
         return new LocalCacher();
       case 'remote':
         return new RemoteCacher();
+      case 'redis':
+        return new RedisCacher();
       case 'local-first':
       case 'remote-first':
         return new HybridCacher(cache) as Cacher;