cyberia 3.1.3 → 3.2.9

package/src/server/shape-generator.js

@@ -155,6 +155,26 @@ registerShape('parabola', (t, params) => {
   return { x, y: a * x * x };
 });
 
+registerShape('thick-parabola', (t, params) => {
+  // Closed parabolic band — traces the outer curve forward then the inner
+  // curve backward, producing a thick filled crescent when rasterized.
+  // `a` controls curvature, `rangeX` controls horizontal span, and
+  // `thickness` controls band width (vertical gap between outer/inner).
+  const a = params.a ?? 0.6;
+  const rangeX = params.rangeX ?? 1.3;
+  const thickness = params.thickness ?? 0.35;
+  if (t <= 0.5) {
+    // Outer parabola (forward: left → right)
+    const u = t * 2;
+    const xNorm = -rangeX + 2 * rangeX * u;
+    return { x: xNorm, y: a * xNorm * xNorm };
+  }
+  // Inner parabola (reverse: right → left, shifted up by thickness)
+  const u = 1 - (t - 0.5) * 2;
+  const xNorm = -rangeX + 2 * rangeX * u;
+  return { x: xNorm, y: a * xNorm * xNorm + thickness };
+});
+
 registerShape('heart', (t) => {
   const angle = t * Math.PI * 2;
   const x = 16 * Math.pow(Math.sin(angle), 3);
@@ -408,6 +428,42 @@ registerShape('bezier-path', (t, params) => {
   return { x, y };
 });
 
+registerShape('regular-polygon', (t, params) => {
+  // Regular convex polygon with `sides` edges.
+  // Traces straight vertex-to-vertex segments for perfect geometric figures.
+  const sides = Math.max(3, params.sides ?? 4);
+  const r = params.r ?? 1;
+  const segAngle = (2 * Math.PI) / sides;
+  const angle = t * Math.PI * 2;
+  // Which segment are we in?
+  const seg = Math.floor(angle / segAngle);
+  const frac = (angle - seg * segAngle) / segAngle;
+  // Offset: -π/2 puts first vertex at top (flat bottom for odd-sided).
+  // For even-sided polygons, shift by half a segment so edges are axis-aligned.
+  const offset = -Math.PI / 2 + (sides % 2 === 0 ? Math.PI / sides : 0);
+  const a0 = seg * segAngle + offset;
+  const a1 = (seg + 1) * segAngle + offset;
+  const x = r * ((1 - frac) * Math.cos(a0) + frac * Math.cos(a1));
+  const y = r * ((1 - frac) * Math.sin(a0) + frac * Math.sin(a1));
+  return { x, y };
+});
+
+registerShape('rectangle', (t, params) => {
+  // Axis-aligned rectangle with configurable aspect ratio.
+  // `width` and `height` control proportions (default: 1.4 × 1.0).
+  const w = params.width ?? 1.4;
+  const h = params.height ?? 1.0;
+  const hw = w / 2,
+    hh = h / 2;
+  const perim = 2 * (w + h);
+  const d = t * perim;
+  // Traverse: bottom-left → bottom-right → top-right → top-left
+  if (d < w) return { x: -hw + d, y: hh };
+  if (d < w + h) return { x: hw, y: hh - (d - w) };
+  if (d < 2 * w + h) return { x: hw - (d - w - h), y: -hh };
+  return { x: -hw, y: -hh + (d - 2 * w - h) };
+});
+
 /* ═══════════════════════════════════════════════════════════════════════════
  *  GEOMETRY HELPERS
  * ═══════════════════════════════════════════════════════════════════════════ */
@@ -677,6 +733,49 @@ function rasterizeContour(normalizedPoints, gridW, gridH, closed) {
   return unique;
 }
 
+/**
+ * Scanline-fills the interior of a closed contour on an integer grid.
+ * Takes the contour points produced by `rasterizeContour` and returns a
+ * new array containing both the contour AND all interior cells.
+ *
+ * Uses the standard even-odd scanline algorithm: for each row, find the
+ * leftmost and rightmost contour cell then fill everything in between.
+ *
+ * @param {ShapePoint[]} contourPoints - Contour cells from rasterizeContour.
+ * @param {number} gridW - Grid width.
+ * @param {number} gridH - Grid height.
+ * @returns {ShapePoint[]} All unique filled cells (contour + interior).
+ * @memberof ShapeGenerator
+ */
+function scanlineFill(contourPoints, gridW, gridH) {
+  // Build per-row min/max from contour
+  const rowBounds = new Map();
+  for (const p of contourPoints) {
+    const b = rowBounds.get(p.y);
+    if (b) {
+      if (p.x < b.min) b.min = p.x;
+      if (p.x > b.max) b.max = p.x;
+    } else {
+      rowBounds.set(p.y, { min: p.x, max: p.x });
+    }
+  }
+
+  const seen = new Set();
+  const filled = [];
+
+  for (const [y, { min, max }] of rowBounds) {
+    for (let x = min; x <= max; x++) {
+      const k = x * 100000 + y;
+      if (!seen.has(k)) {
+        seen.add(k);
+        filled.push({ x, y });
+      }
+    }
+  }
+
+  return filled;
+}
+
 /**
  * Renders an integer-coordinate ShapeResult as an ASCII grid string.
  * Useful for quick visual verification of pixel-art shapes.
@@ -738,6 +837,9 @@ export function renderGrid(shapeResult, opts = {}) {
  *   with Bresenham rasterization so that even on a 16×16 grid the full contour
  *   is visible as a connected set of cells. `count` is ignored in this mode;
  *   the number of output points equals the number of unique rasterized cells.
+ * @property {boolean} [fill=false] - When true (and intCoords is enabled),
+ *   scanline-fills the interior of the closed contour, producing a solid
+ *   silhouette instead of an outline-only shape.
  * @memberof ShapeGenerator
  */
 
@@ -810,6 +912,7 @@ export function generateShape(key, options = {}) {
     closed = true,
     normalize = true,
     intCoords = false,
+    fill = false,
     color,
     ...extraParams
   } = options;
@@ -896,6 +999,11 @@ export function generateShape(key, options = {}) {
   if (useIntCoords) {
     points = rasterizeContour(points, gridW, gridH, closed);
 
+    // ---- Scanline fill (solid silhouette) -----------------------------------
+    if (fill && closed) {
+      points = scanlineFill(points, gridW, gridH);
+    }
+
     // Build metadata for integer grid mode
     const bbox = computeBbox(points);
     /** @type {ShapeMetadata} */

package/src/server/start.js

@@ -131,11 +131,21 @@ class UnderpostStartUp {
      * @param {boolean} options.build - Whether to build the deployment.
      * @param {boolean} options.run - Whether to run the deployment.
      * @param {boolean} options.underpostQuicklyInstall - Whether to use underpost quickly install.
+     * @param {boolean} options.skipPullBase - Whether to skip pulling the base code.
+     * @param {boolean} options.skipFullBuild - Whether to skip building the full client bundle.
+     * @param {boolean} options.pullBundle - When true, download pre-built client bundle from Cloudinary via pull-bundle before starting.
      */
     async callback(
       deployId = 'dd-default',
       env = 'development',
-      options = { build: false, run: false, underpostQuicklyInstall: false },
+      options = {
+        build: false,
+        run: false,
+        underpostQuicklyInstall: false,
+        skipPullBase: false,
+        skipFullBuild: false,
+        pullBundle: false,
+      },
     ) {
       Underpost.env.set('container-status', `${deployId}-${env}-build-deployment`);
       if (options.build === true) await Underpost.start.build(deployId, env, options);
@@ -149,12 +159,15 @@ class UnderpostStartUp {
      * @param {Object} options - Options for the build.
      * @param {boolean} options.skipPullBase - Whether to skip pulling the base code and use the current workspace code directly.
      * @param {boolean} options.underpostQuicklyInstall - Whether to use underpost quickly install.
+     * @param {boolean} options.skipFullBuild - Whether to skip building the full client bundle.
+     * @param {boolean} options.pullBundle - When true, download pre-built client bundle from Cloudinary via pull-bundle (must be pushed first with push-bundle).
+     *   This flag is independent of skipFullBuild: it can be combined with skipFullBuild or used alone.
      * @memberof UnderpostStartUp
      */
     async build(
       deployId = 'dd-default',
       env = 'development',
-      options = { underpostQuicklyInstall: false, skipPullBase: false },
+      options = { underpostQuicklyInstall: false, skipPullBase: false, skipFullBuild: false, pullBundle: false },
     ) {
       const buildBasePath = `/home/dd`;
       const repoName = `engine-${deployId.split('-')[1]}`;
@@ -163,10 +176,9 @@ class UnderpostStartUp {
         shellExec(`mkdir -p ${buildBasePath}/engine`);
         shellExec(`cd ${buildBasePath} && sudo cp -a ./${repoName}/. ./engine`);
         shellExec(`cd ${buildBasePath} && sudo rm -rf ./${repoName}`);
-        shellExec(`cd ${buildBasePath}/engine && underpost clone ${process.env.GITHUB_USERNAME}/${repoName}-private`);
-        shellExec(`cd ${buildBasePath}/engine && sudo mv ./${repoName}-private ./engine-private`);
       }
       shellCd(`${buildBasePath}/engine`);
+      Underpost.repo.privateEngineRepoFactory(deployId);
       shellExec(options?.underpostQuicklyInstall ? `underpost install` : `npm install`);
       shellExec(`node bin env ${deployId} ${env}`);
       if (fs.existsSync('./engine-private/itc-scripts')) {
@@ -174,7 +186,8 @@ class UnderpostStartUp {
         for (const itcScript of itcScripts)
           if (itcScript.match(deployId)) shellExec(`node ./engine-private/itc-scripts/${itcScript}`);
       }
-      shellExec(`node bin client ${deployId}`);
+      if (options.pullBundle === true) shellExec(`node bin run pull-bundle --deploy-id ${deployId}`);
+      else if (!options.skipFullBuild) shellExec(`node bin client ${deployId}`);
     },
     /**
      * Runs a deployment.
@@ -197,6 +210,7 @@ class UnderpostStartUp {
       shellExec(`node bin env ${deployId} ${env}`);
       shellExec(`npm ${runCmd} ${deployId}`, { async: true });
       await awaitDeployMonitor(true);
+      if (env === 'production' && Underpost.env.isInsideContainer()) Underpost.secret.globalSecretClean();
       Underpost.env.set('container-status', `${deployId}-${env}-running-deployment`);
     },
   };

package/src/server/valkey.js

@@ -1,293 +1,199 @@
 /**
- * Module for managing Valkey
+ * Valkey connection and key-value store module.
+ *
+ * Responsibilities:
+ *  - Manage per-instance Valkey connections keyed by `${host}${path}`.
+ *  - Provide a thin, typed CRUD surface: get / set / del / update.
+ *  - Expose connection status helpers.
+ *
+ * Out of scope: domain model factories, DTO projection — those belong in
+ * their respective service modules (e.g. guest.service.js).
+ *
  * @module src/server/valkey.js
  * @namespace ValkeyService
  */
-
 import Valkey from 'iovalkey';
-import mongoose from 'mongoose';
-import { hashPassword } from './auth.js';
 import { loggerFactory } from './logger.js';
 
 const logger = loggerFactory(import.meta);
 
-// Per-instance registries keyed by `${host}${path}`
+// ─── Instance registry ────────────────────────────────────────────────────────
+
+/** @type {Record<string, import('iovalkey').default>} */
 const ValkeyInstances = {};
-const DummyStores = {}; // in-memory Maps per instance
-const ValkeyStatus = {}; // 'connected' | 'dummy' | 'error' | undefined
+
+/** @type {Record<string, 'connected' | 'reconnecting' | 'error'>} */
+const ValkeyStatus = {};
 
 /**
- * Checks if any Valkey instance is connected.
- * This is a backward-compatible overall flag.
- * @returns {boolean} True if any instance has a 'connected' status.
- * @memberof ValkeyService
+ * Derives the registry key from an instance descriptor.
+ * @param {{ host?: string, path?: string }} opts
+ * @returns {string}
  */
-const isValkeyEnable = () => Object.values(ValkeyStatus).some((s) => s === 'connected');
+const _instanceKey = (opts = {}) => `${opts.host || ''}${opts.path || ''}`;
+
+// ─── Connection ───────────────────────────────────────────────────────────────
 
 /**
- * Generates a unique key for a Valkey instance based on its host and path.
- * @param {object} [opts={ host: '', path: '' }] - The instance options.
- * @param {string} [opts.host=''] - The host of the instance.
- * @param {string} [opts.path=''] - The path of the instance.
- * @returns {string} The instance key.
- * @private
+ * Returns true when at least one Valkey instance is connected.
+ * @returns {boolean}
  * @memberof ValkeyService
  */
-const _instanceKey = (opts = { host: '', path: '' }) => `${opts.host || ''}${opts.path || ''}`;
+const isValkeyEnable = () => Object.values(ValkeyStatus).some((s) => s === 'connected');
 
 /**
- * Creates and manages a connection to a Valkey server for a given instance.
- * It sets up a client, attaches event listeners for connection status, and implements a fallback to an in-memory dummy store if the connection fails.
- * @param {object} [instance={ host: '', path: '' }] - The instance identifier.
- * @param {string} [instance.host=''] - The host of the instance.
- * @param {string} [instance.path=''] - The path of the instance.
- * @param {object} [valkeyServerConnectionOptions={ host: '', path: '' }] - Connection options for the iovalkey client.
- * @returns {Promise<Valkey|undefined>} A promise that resolves to the Valkey client instance, or undefined if creation fails.
+ * Creates a Valkey client for the given instance and waits for connectivity.
+ * Throws on connection failure — callers decide whether to abort or continue
+ * without Valkey.
+ *
+ * @param {{ host?: string, path?: string }} instance - Registry key descriptor.
+ * @param {{ host?: string, port?: number }} connectionOptions - iovalkey connection options.
+ * @returns {Promise<import('iovalkey').default>}
  * @memberof ValkeyService
  */
-const createValkeyConnection = async (
-  instance = { host: '', path: '' },
-  valkeyServerConnectionOptions = { host: '', path: '' },
-) => {
+const createValkeyConnection = async (instance = {}, connectionOptions = {}) => {
   const key = _instanceKey(instance);
-  // Initialize dummy store for the instance
-  if (!DummyStores[key]) DummyStores[key] = new Map();
 
-  try {
-    const client = await ValkeyAPI.valkeyClientFactory(valkeyServerConnectionOptions);
-
-    // Attach listeners for visibility
-    client.on?.('ready', () => {
-      ValkeyStatus[key] = 'connected';
-      logger.info('Valkey connected', { instance, status: ValkeyStatus[key] });
-    });
-    client.on?.('error', (err) => {
-      // Switch to dummy if not yet connected
-      if (ValkeyStatus[key] !== 'connected') {
-        ValkeyStatus[key] = 'dummy';
-      } else {
-        ValkeyStatus[key] = 'error';
-      }
-      logger.warn('Valkey error', { err: err?.message, instance, status: ValkeyStatus[key] });
-    });
-    client.on?.('end', () => {
-      if (ValkeyStatus[key] !== 'dummy') ValkeyStatus[key] = 'error';
-      logger.warn('Valkey connection ended', { instance, status: ValkeyStatus[key] });
-    });
-
-    // Probe connectivity with a short timeout
-    const probe = async () => {
+  const client = new Valkey({
+    port: connectionOptions.port ?? undefined,
+    host: connectionOptions.host ?? undefined,
+    // Retry indefinitely with capped exponential backoff (1 s → 30 s)
+    retryStrategy: (attempt) => Math.min(attempt * 1000, 30000),
+    // Fail commands immediately when not connected; do NOT queue them
+    maxRetriesPerRequest: 0,
+  });
+
+  client.on('ready', () => {
+    ValkeyStatus[key] = 'connected';
+    logger.info('Valkey connected', { instance });
+  });
+  client.on('error', (err) => {
+    ValkeyStatus[key] = 'error';
+    logger.error('Valkey error', { err: err?.message, instance });
+  });
+  client.on('reconnecting', () => {
+    ValkeyStatus[key] = 'reconnecting';
+    logger.warn('Valkey reconnecting...', { instance });
+  });
+  client.on('end', () => {
+    ValkeyStatus[key] = 'error';
+    logger.warn('Valkey connection ended', { instance });
+  });
+
+  // Verify connectivity with a probe before marking ready
+  await Promise.race([
+    (async () => {
       try {
-        // basic ping via SET/GET roundtrip
-        const probeKey = `__vk_probe_${Date.now()}`;
-        await client.set(probeKey, '1');
-        await client.get(probeKey);
+        const probe = `__vk_probe_${Date.now()}`;
+        await client.set(probe, '1');
+        await client.get(probe);
+        await client.del(probe);
         ValkeyStatus[key] = 'connected';
-      } catch (e) {
-        ValkeyStatus[key] = 'dummy';
-        logger.warn('Valkey probe failed, falling back to dummy', { instance, error: e?.message });
+      } catch {
+        ValkeyStatus[key] = 'error';
       }
-    };
-
-    // Race with timeout to avoid hanging
-    await Promise.race([probe(), new Promise((resolve) => setTimeout(resolve, 1000))]);
+    })(),
+    new Promise((resolve) => setTimeout(resolve, 1500)),
+  ]);
 
-    ValkeyInstances[key] = client;
-    if (!ValkeyStatus[key]) ValkeyStatus[key] = 'dummy';
-  } catch (err) {
-    ValkeyStatus[key] = 'dummy';
-    logger.warn('Valkey client creation failed, using dummy', { instance, error: err?.message });
-  }
-
-  return ValkeyInstances[key];
+  ValkeyInstances[key] = client;
+  logger.info('Valkey instance registered', { key, status: ValkeyStatus[key] });
+  return client;
 };
 
+// ─── Internal client resolver ─────────────────────────────────────────────────
+
 /**
- * Factory function to create a Data Transfer Object (DTO) from a payload.
- * It filters the payload to include only the keys specified in the `select` object.
- * @param {object} payload - The source object.
- * @param {object} select - An object where keys are field names and values are 1 to include them.
- * @returns {object} A new object containing only the selected fields from the payload.
- * @memberof ValkeyService
+ * Resolves the connected client for an instance or throws.
+ * @param {{ host?: string, path?: string }} options
+ * @returns {import('iovalkey').default}
  */
-const selectDtoFactory = (payload, select) => {
-  const result = {};
-  for (const key of Object.keys(select)) {
-    if (select[key] === 1 && key in payload) result[key] = payload[key];
+const _client = (options) => {
+  const k = _instanceKey(options);
+  const client = ValkeyInstances[k];
+  if (!client || ValkeyStatus[k] !== 'connected') {
+    throw new Error(`Valkey instance not connected: ${k}`);
   }
-  return result;
+  return client;
 };
 
-/**
- * Factory function to create a new Valkey client instance.
- * @param {object} options - Connection options for the iovalkey client.
- * @returns {Promise<Valkey>} A promise that resolves to a new Valkey client.
- * @memberof ValkeyService
- */
-const valkeyClientFactory = async (options) => {
-  const valkey = new Valkey({
-    port: options?.port ? options.port : undefined,
-    host: options?.host ? options.host : undefined,
-    // Keep retry strategy minimal; state handled in createValkeyConnection
-    retryStrategy: (attempt) => {
-      if (attempt === 1) return undefined; // stop aggressive retries early
-      return 1000; // retry interval if library continues
-    },
-  }); // Connect to 127.0.0.1:6379
-  // new Valkey(6380); // 127.0.0.1:6380
-  // new Valkey(6379, '192.168.1.1'); // 192.168.1.1:6379
-  // new Valkey('/tmp/redis.sock');
-  // new Valkey({
-  //   port: 6379, // Valkey port
-  //   host: '127.0.0.1', // Valkey host
-  //   username: 'default', // needs Valkey >= 6
-  //   password: 'my-top-secret',
-  //   db: 0, // Defaults to 0
-  // });
-  return valkey;
-};
+// ─── CRUD ─────────────────────────────────────────────────────────────────────
 
 /**
- * Retrieves an object from Valkey by key for a specific instance.
- * If the Valkey client is not connected or an error occurs, it falls back to the dummy in-memory store.
- * It automatically parses JSON strings.
- * @param {object} [options={ host: '', path: '' }] - The instance identifier.
- * @param {string} [key=''] - The key of the object to retrieve.
- * @returns {Promise<object|string|null>} A promise that resolves to the retrieved object, string, or null if not found.
+ * Retrieves and JSON-parses a value by key.
+ * Returns null when the key does not exist.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @returns {Promise<object | string | null>}
  * @memberof ValkeyService
  */
-const getValkeyObject = async (options = { host: '', path: '' }, key = '') => {
-  const k = _instanceKey(options);
-  const status = ValkeyStatus[k];
+const get = async (options, key) => {
+  const raw = await _client(options).get(key);
+  if (raw == null) return null;
   try {
-    if (status === 'connected' && ValkeyInstances[k]) {
-      const value = await ValkeyInstances[k].get(key);
-      if (value == null) return null;
-      try {
-        return JSON.parse(value);
-      } catch {
-        // not JSON, return raw string
-        return value;
-      }
-    }
-  } catch (err) {
-    logger.warn('Valkey get failed, using dummy', { key, err: err?.message });
+    return JSON.parse(raw);
+  } catch {
+    return raw;
   }
-  // Dummy fallback returns stored value as-is (string or object)
-  return DummyStores[k]?.get(key) ?? null;
 };
 
 /**
- * Sets an object or string in Valkey for a specific instance.
- * If the Valkey client is not connected, it writes to the in-memory dummy store instead.
- * Objects are automatically stringified.
- * @param {object} [options={ host: '', path: '' }] - The instance identifier.
- * @param {string} [key=''] - The key under which to store the payload.
- * @param {object|string} [payload={}] - The data to store.
- * @returns {Promise<string>} A promise that resolves to 'OK' on success.
+ * Serialises and stores a value by key.
+ * Pass `ttlMs` to set an expiry in milliseconds.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @param {object | string} payload
+ * @param {number} [ttlMs]
+ * @returns {Promise<string>} Resolves to 'OK'.
  * @memberof ValkeyService
  */
-const setValkeyObject = async (options = { host: '', path: '' }, key = '', payload = {}) => {
-  const k = _instanceKey(options);
-  const isString = typeof payload === 'string';
-  const value = isString ? payload : JSON.stringify(payload);
-  try {
-    if (ValkeyStatus[k] === 'connected' && ValkeyInstances[k]) {
-      return await ValkeyInstances[k].set(key, value);
-    }
-  } catch (err) {
-    logger.warn('Valkey set failed, writing to dummy', { key, err: err?.message });
-  }
-  if (!DummyStores[k]) DummyStores[k] = new Map();
-  // Store raw string or object accordingly
-  DummyStores[k].set(key, isString ? payload : payload);
-  return 'OK';
+const set = async (options, key, payload, ttlMs) => {
+  const value = typeof payload === 'string' ? payload : JSON.stringify(payload);
+  if (ttlMs) return _client(options).set(key, value, 'PX', ttlMs);
+  return _client(options).set(key, value);
 };
 
 /**
- * Updates an existing object in Valkey by merging it with a new payload.
- * It retrieves the current object, merges it with the new payload, and sets the updated object back.
- * It also updates the `updatedAt` timestamp.
- * @param {object} [options={ host: '', path: '' }] - The instance identifier.
- * @param {string} [key=''] - The key of the object to update.
- * @param {object} [payload={}] - The new data to merge into the object.
- * @returns {Promise<string>} A promise that resolves to the result of the set operation.
+ * Deletes a key.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @returns {Promise<number>}
  * @memberof ValkeyService
  */
-const updateValkeyObject = async (options = { host: '', path: '' }, key = '', payload = {}) => {
-  let base = await getValkeyObject(options, key);
-  if (typeof base !== 'object' || base === null) base = {};
-  base.updatedAt = new Date().toISOString();
-  return await setValkeyObject(options, key, { ...base, ...payload });
-};
+const del = async (options, key) => _client(options).del(key);
 
 /**
- * Factory function to create a new object based on a model schema.
- * It generates a new object with default properties like `_id`, `createdAt`, and `updatedAt`,
- * and model-specific properties.
- * @param {object} [options={ host: 'localhost', path: '', object: {} }] - Options for object creation.
- * @param {string} [options.host='localhost'] - The host context for the object.
- * @param {object} [options.object={}] - An initial object to extend.
- * @param {string} [model=''] - The name of the model schema to use (e.g., 'user').
- * @returns {Promise<object>} A promise that resolves to the newly created object.
+ * Shallow-merges `payload` into the existing object stored at `key`
+ * and persists the result.  The `updatedAt` timestamp is refreshed automatically.
+ *
+ * @param {{ host?: string, path?: string }} options
+ * @param {string} key
+ * @param {object} payload
+ * @returns {Promise<string>} Resolves to 'OK'.
  * @memberof ValkeyService
  */
-const valkeyObjectFactory = async (options = { host: 'localhost', path: '', object: {} }, model = '') => {
-  const idoDate = new Date().toISOString();
-  options.object = options.object || {};
-  const { object } = options;
-  const _id = new mongoose.Types.ObjectId().toString();
-  object._id = _id;
-  object.createdAt = idoDate;
-  object.updatedAt = idoDate;
-  switch (model) {
-    case 'user': {
-      const role = 'guest';
-      object._id = `${role}${_id}`;
-      return {
-        ...object,
-        username: `${role}${_id.slice(-5)}`,
-        email: `${_id}@${options.host}`,
-        password: hashPassword(process.env.JWT_SECRET),
-        role,
-        failedLoginAttempts: 0,
-        phoneNumbers: [],
-        publicKey: [],
-        profileImageId: null,
-        emailConfirmed: false,
-        recoverTimeOut: null,
-        lastLoginDate: null,
-        activeSessions: [],
-      };
-    }
-    default:
-      throw new Error(`model schema not found: ${model}`);
-  }
+const update = async (options, key, payload) => {
+  const base = (await get(options, key)) ?? {};
+  return set(options, key, { ...base, ...payload, updatedAt: new Date().toISOString() });
 };
 
+// ─── Public API class ─────────────────────────────────────────────────────────
+
 /**
- * A collection of Valkey-related API functions.
- * @type {object}
- * @memberof ValkeyServiceService
+ * Namespace grouping all Valkey operations.
+ * @memberof ValkeyService
  */
-const ValkeyAPI = {
-  valkeyClientFactory,
-  selectDtoFactory,
-  getValkeyObject,
-  setValkeyObject,
-  valkeyObjectFactory,
-  updateValkeyObject,
-  createValkeyConnection,
-};
-
-export {
-  valkeyClientFactory,
-  selectDtoFactory,
-  getValkeyObject,
-  setValkeyObject,
-  valkeyObjectFactory,
-  updateValkeyObject,
-  isValkeyEnable,
-  createValkeyConnection,
-  ValkeyAPI,
-};
+class ValkeyAPI {
+  /** @param {{ host?: string, path?: string }} options */
+  static isConnected = (options) => ValkeyStatus[_instanceKey(options)] === 'connected';
+  static get = get;
+  static set = set;
+  static del = del;
+  static update = update;
+  static createValkeyConnection = createValkeyConnection;
+}
+
+export { isValkeyEnable, createValkeyConnection, get, set, del, update, ValkeyAPI };