📝 Add docstrings to user/marko/add-redis-pub-sub

Docstrings generation was requested by @markovejnovic.

* https://github.com/oven-sh/bun/pull/21728#issuecomment-3240935695

The following files were modified:

* `src/bun.js/bindings/bindings.cpp`
* `test/js/valkey/test-utils.ts`

src/bun.js/bindings/bindings.cpp

@@ -6411,11 +6411,41 @@ CPP_DECL [[ZIG_EXPORT(nothrow)]] bool JSC__JSMap__remove(JSC::JSMap* map, JSC::J
     JSC::JSValue value = JSC::JSValue::decode(JSValue2);
     return map->remove(arg1, value);
 }
+/**
+ * @brief Set a key/value pair on a JavaScript Map.
+ *
+ * Stores the given key/value pair into the provided JSC::JSMap. The key and value are passed as
+ * encoded JS values and will be associated in the map (overwriting any existing entry for the key).
+ *
+ * @param map The JSMap to modify.
+ * @param JSValue2 EncodedJSValue representing the key.
+ * @param JSValue3 EncodedJSValue representing the value to associate with the key.
+ */
 CPP_DECL [[ZIG_EXPORT(nothrow)]] void JSC__JSMap__set(JSC::JSMap* map, JSC::JSGlobalObject* arg1, JSC::EncodedJSValue JSValue2, JSC::EncodedJSValue JSValue3)
 {
     map->set(arg1, JSC::JSValue::decode(JSValue2), JSC::JSValue::decode(JSValue3));
 }
 
+/**
+ * @brief Return the number of entries in a JavaScript Map.
+ *
+ * @param map Pointer to the JSMap to query.
+ * @param arg1 Global object (unused by this function).
+ * @return uint32_t The map's size (number of key/value entries).
+ */
+CPP_DECL [[ZIG_EXPORT(nothrow)]] uint32_t JSC__JSMap__size(JSC::JSMap* map, JSC::JSGlobalObject* arg1)
+{
+    return map->size();
+}
+
+/**
+ * @brief Enable or disable the VM's control-flow profiler.
+ *
+ * Toggles the JSC::VM control-flow profiler on or off. When enabled, the VM
+ * collects control-flow profiling data; when disabled, profiling is stopped.
+ *
+ * @param isEnabled True to enable the control-flow profiler, false to disable it.
+ */
 CPP_DECL void JSC__VM__setControlFlowProfiler(JSC::VM* vm, bool isEnabled)
 {
     if (isEnabled) {

test/js/valkey/test-utils.ts

@@ -454,55 +454,49 @@ import { tmpdir } from "os";
 /**
  * Create a new client with specific connection type
  */
-export function createClient(
-    connectionType: ConnectionType = ConnectionType.TCP,
-    customOptions = {},
-    dbId: number | undefined = undefined,
-) {
+export function createClient(connectionType: ConnectionType = ConnectionType.TCP, customOptions = {}) {
   let url: string;
-  const mkUrl = (baseUrl: string) => dbId ? `${baseUrl}/${dbId}`: baseUrl;
-
   let options: any = {};
   context.id++;
 
   switch (connectionType) {
     case ConnectionType.TCP:
-      url = mkUrl(DEFAULT_REDIS_URL);
+      url = DEFAULT_REDIS_URL;
       options = {
         ...DEFAULT_REDIS_OPTIONS,
         ...customOptions,
       };
       break;
     case ConnectionType.TLS:
-      url = mkUrl(TLS_REDIS_URL);
+      url = TLS_REDIS_URL;
       options = {
         ...TLS_REDIS_OPTIONS,
         ...customOptions,
       };
       break;
     case ConnectionType.UNIX:
-      url = mkUrl(UNIX_REDIS_URL);
+      url = UNIX_REDIS_URL;
       options = {
         ...UNIX_REDIS_OPTIONS,
         ...customOptions,
       };
       break;
     case ConnectionType.AUTH:
-      url = mkUrl(AUTH_REDIS_URL);
+      url = AUTH_REDIS_URL;
       options = {
         ...AUTH_REDIS_OPTIONS,
         ...customOptions,
       };
       break;
     case ConnectionType.READONLY:
-      url = mkUrl(READONLY_REDIS_URL);
+      url = READONLY_REDIS_URL;
       options = {
         ...READONLY_REDIS_OPTIONS,
         ...customOptions,
       };
       break;
     case ConnectionType.WRITEONLY:
-      url = mkUrl(WRITEONLY_REDIS_URL);
+      url = WRITEONLY_REDIS_URL;
       options = {
         ...WRITEONLY_REDIS_OPTIONS,
         ...customOptions,
@@ -764,7 +758,15 @@ async function getRedisContainerName(): Promise<string> {
 }
 
 /**
- * Restart the Redis container to simulate connection drop
+ * Restart the Redis Docker container used by the tests.
+ *
+ * Restarts the container identified by the test harness and waits briefly for it
+ * to come back online (approximately 2 seconds). Use this to simulate a server
+ * restart or connection drop during tests.
+ *
+ * @returns A promise that resolves when the restart and short wait complete.
+ * @throws If the Docker restart command exits with a non-zero code; the error
+ *         message includes the container's stderr output.
  */
 export async function restartRedisContainer(): Promise<void> {
   const containerName = await getRedisContainerName();
@@ -789,3 +791,14 @@ export async function restartRedisContainer(): Promise<void> {
 
   console.log(`Redis container restarted: ${containerName}`);
 }
+
+/**
+ * Returns a random boolean (a 50/50 coin flip).
+ *
+ * Useful for tests that need a nondeterministic boolean. Uses Math.random and is not suitable for cryptographic purposes.
+ *
+ * @returns true or false with approximately equal probability
+ */
+export function randomCoinFlip(): boolean {
+  return Math.floor(Math.random() * 2) == 0;
+}