infinispan 0.13.0 → 0.15.0

package/lib/utils.js

@@ -15,9 +15,9 @@
   exports.context = function(size) {
     return {buf: Buffer.alloc(size), offset: 0, id: parseInt(_.uniqueId()), triedAddrs: []};
   };
-  exports.showAddress = function(addr) { return addr.host + ':' + addr.port; };
+  exports.showAddress = function(addr) { return `${addr.host  }:${  addr.port}`; };
   exports.showArrayAddress = function(addrs) {
-    return ["[", _.map(addrs, function(a) { return exports.showAddress(a); }).join(","), "]"].join('');
+    return ['[', _.map(addrs, function(a) { return exports.showAddress(a); }).join(','), ']'].join('');
   };
 
   exports.parse = function (chal) {
@@ -89,7 +89,7 @@
           logger.trace.apply(logger, fun());
       },
       error: function() { logger.error.apply(logger, arguments); }
-    }
+    };
   };
 
   var ReplayableBuffer = function() {
@@ -129,42 +129,69 @@
         buf.copy(b);
         return b;
       }
-    }
+    };
   };
 
   var polyToString = f.dispatch(
-      function(s) { return !f.existy(s) ? 'undefined' : undefined },
-      function(s) { return _.isString(s) ? (s.length > 1024 ? s.substring(0, 1024) + '...' : s) : undefined},
-      function(s) { return _.isArray(s) ? stringifyArray(s) : undefined },
-      function(s) { return _.isObject(s) ? JSON.stringify(s) : undefined },
-      function(s) { return s.toString() });
-
+      function(s) { return !f.existy(s) ? 'undefined' : undefined; },
+      function(s) { return _.isString(s) ? (s.length > 1024 ? `${s.substring(0, 1024)  }...` : s) : undefined;},
+      function(s) { return _.isArray(s) ? stringifyArray(s) : undefined; },
+      function(s) { return _.isObject(s) ? JSON.stringify(s) : undefined; },
+      function(s) { return s.toString(); });
+
+  /**
+   * Converts a value to its string representation using polymorphic dispatch.
+   * @param {*} o Value to convert to string.
+   * @returns {string} String representation of the value.
+   */
   function str(o) {
     return polyToString(o);
   }
 
+  /**
+   * Converts an array to a bracketed, comma-separated string.
+   * @param {Array} ary Array to stringify.
+   * @returns {string} String representation of the array.
+   */
   function stringifyArray(ary) {
-    return ["[", _.map(ary, polyToString).join(","), "]"].join('');
+    return ['[', _.map(ary, polyToString).join(','), ']'].join('');
   }
 
+  /**
+   * Normalizes server address arguments into a uniform array of address objects.
+   * @param {Object|Object[]|undefined} args Address object, array of addresses, or undefined.
+   * @returns {Object[]} Array of address objects with host and port properties.
+   */
   function normalizeAddresses(args) {
     var normalizer = f.dispatch(
-        function(xs) { return _.isArray(xs) ? xs : undefined },
-        function(x) { return _.isObject(x) ? [x] : undefined },
+        function(xs) { return _.isArray(xs) ? xs : undefined; },
+        function(x) { return _.isObject(x) ? [x] : undefined; },
         function(x) {
-          if (f.existy(x)) throw new Error('Unknown server addresses: ' + x);
-          return [{port: 11222, host: '127.0.0.1'}]
+          if (f.existy(x)) throw new Error(`Unknown server addresses: ${  x}`);
+          return [{port: 11222, host: '127.0.0.1'}];
         });
     return normalizer(args);
   }
 
   var MurmurHash3 = function() {
+    /**
+     * XORs two 64-bit integers represented as two-element 32-bit int arrays.
+     * @param {number[]} m First 64-bit integer as [high, low].
+     * @param {number[]} n Second 64-bit integer as [high, low].
+     * @returns {number[]} XOR result as [high, low].
+     */
     function x64Xor(m, n) {
       // Given two 64bit ints (as an array of two 32bit ints) returns the two
       // xored together as a 64bit int (as an array of two 32bit ints).
       return [m[0] ^ n[0], m[1] ^ n[1]];
     }
 
+    /**
+     * Multiplies two 64-bit integers represented as two-element 32-bit int arrays.
+     * @param {number[]} m First 64-bit integer as [high, low].
+     * @param {number[]} n Second 64-bit integer as [high, low].
+     * @returns {number[]} Product as [high, low].
+     */
     function x64Multiply(m, n) {
       // Given two 64bit ints (as an array of two 32bit ints) returns the two
       // multiplied together as a 64bit int (as an array of two 32bit ints).
@@ -202,6 +229,12 @@
       return [(o[0] << 16) | o[1], (o[2] << 16) | o[3]];
     }
 
+    /**
+     * Rotates a 64-bit integer left by the given number of bit positions.
+     * @param {number[]} m 64-bit integer as [high, low].
+     * @param {number} n Number of bit positions to rotate.
+     * @returns {number[]} Rotated result as [high, low].
+     */
     function x64Rotl(m, n) {
       // Given a 64bit int (as an array of two 32bit ints) and an int
       // representing a number of bit positions, returns the 64bit int (as an
@@ -218,6 +251,12 @@
       }
     }
 
+    /**
+     * Adds two 64-bit integers represented as two-element 32-bit int arrays.
+     * @param {number[]} m First 64-bit integer as [high, low].
+     * @param {number[]} n Second 64-bit integer as [high, low].
+     * @returns {number[]} Sum as [high, low].
+     */
     function x64Add(m, n) {
       // Given two 64bit ints (as an array of two 32bit ints) returns the two
       // added together as a 64bit int (as an array of two 32bit ints).
@@ -243,6 +282,12 @@
       return [(o[0] << 16) | o[1], (o[2] << 16) | o[3]];
     }
 
+    /**
+     * Shifts a 64-bit integer left by the given number of bit positions.
+     * @param {number[]} m 64-bit integer as [high, low].
+     * @param {number} n Number of bit positions to shift.
+     * @returns {number[]} Shifted result as [high, low].
+     */
     function x64LeftShift(m, n) {
       // Given a 64bit int (as an array of two 32bit ints) and an int
       // representing a number of bit positions, returns the 64bit int (as an
@@ -257,6 +302,12 @@
         return [m[1] << (n - 32), 0];
     }
 
+    /**
+     * Reads a 64-bit block from the key buffer at the given byte index.
+     * @param {Buffer} key Key buffer to read from.
+     * @param {number} i Byte offset into the key buffer.
+     * @returns {number[]} 64-bit block as [high, low].
+     */
     function getblock(key, i) {
       return [
         ((key[i + 4] & 0xff))
@@ -270,6 +321,11 @@
       ];
     }
 
+    /**
+     * Performs the MurmurHash3 block mix operation on the hash state.
+     * @param {Object} state Mutable hash state with h1, h2, k1, k2, c1, c2 fields.
+     * @returns {void}
+     */
     function bmix(state) {
       state.k1 = x64Multiply(state.k1, state.c1);
       state.k1 = x64Rotl(state.k1, 23);
@@ -293,6 +349,11 @@
       state.c2 = x64Add(x64Multiply(state.c2, [0, 5]), [0, 0x6bce6396]);
     }
 
+    /**
+     * Applies the MurmurHash3 final mix (fmix) to a 64-bit block.
+     * @param {number[]} h 64-bit block as [high, low].
+     * @returns {number[]} Mixed result as [high, low].
+     */
     function x64Fmix(h) {
       // Given a block, returns murmurHash3's final x64 mix of that block.
       // (`[0, h[0] >>> 1]` is a 33 bit unsigned right shift. This is the
@@ -305,17 +366,21 @@
       return h;
     }
 
-    // Used for debugging hashing
-    function toHex(bignum) {
-      var tmp0 = bignum[0] < 0 ? (bignum[0]>>>0) : bignum[0];
-      var tmp1 = bignum[1] < 0 ? (bignum[1]>>>0) : bignum[1];
-      return tmp0.toString(16) + tmp1.toString(16);
-    }
-
+    /**
+     * Converts a 32-bit integer to a 64-bit representation as a two-element array.
+     * @param {number} num 32-bit integer.
+     * @returns {number[]} 64-bit representation as [high, low].
+     */
     function _x32tox64(num) {
       return num < 0 ? [0xffffffff, num] : [0, num];
     }
 
+    /**
+     * Computes the MurmurHash3 x64 128-bit hash and returns the first 64 bits.
+     * @param {Buffer} key Key buffer to hash.
+     * @param {number[]} seed 64-bit seed as [high, low].
+     * @returns {number[]} First 64-bit hash value as [high, low].
+     */
     function murmurHash3_x64_64(key, seed) {
       var state = {};
 
@@ -389,7 +454,7 @@
         var h = murmurHash3_x64_64(key, [0, 9001]);
         return h[0] >>> 32;
       }
-    }
-  }
+    };
+  };
 
 }.call(this));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinispan",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Infinispan Javascript client",
   "main": "index",
   "typings": "./types",
@@ -8,8 +8,14 @@
     "test": "test"
   },
   "scripts": {
-    "lint": "eslint --ignore-path .gitignore .",
-    "test": "jasmine"
+    "lint": "eslint --ignore-path .gitignore lib spec index.js",
+    "test": "jasmine",
+    "test:docker": "node scripts/docker-test.js",
+    "docker:up": "docker compose -p ispn-test up -d --wait && docker compose -p ispn-test --profile failover create server-failover-one server-failover-two server-failover-three",
+    "docker:down": "docker compose -p ispn-test --profile failover down --remove-orphans",
+    "ssl:generate": "node scripts/make-ssl.js",
+    "docs:api": "jsdoc lib/*.js",
+    "docs:user": "node scripts/gen-asciidoc.js"
   },
   "author": "Infinispan Community",
   "license": "Apache-2.0",
@@ -28,7 +34,6 @@
   },
   "dependencies": {
     "buffer-xor": "^2.0.2",
-    "jsdoc": "^4.0.2",
     "log4js": "^6.4.6",
     "protobufjs": "^7.0.0",
     "underscore": "^1.13.3",
@@ -37,6 +42,7 @@
   "devDependencies": {
     "eslint": "^8.26.0",
     "jasmine": "^6.1.0",
+    "jsdoc": "^4.0.2",
     "long": "^5.2.3"
   }
 }

package/types/index.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Connect to an Infinispan Server using a Hot Rod URI.
+ *
+ * URI format: hotrod://[user:pass@]host1[:port1][,host2[:port2]][?params]
+ * Use hotrods:// to enable TLS.
+ *
+ * Supported query parameters:
+ *   sasl_mechanism, trust_store_file_name (alias trust_ca),
+ *   key_store_file_name (alias client_cert), key_store_password (alias client_key),
+ *   sni_host_name (alias sni_host), max_retries, cache_name.
+ *
+ * @param uri Hot Rod URI string.
+ * @param options Optional overrides (take precedence over URI values).
+ */
+export function client(uri: string, options?: Record<string, any>): Promise<any>;
+
 export function client(args: {
     /**
      * - Server host name.
@@ -20,7 +36,7 @@ export function client(args: {
     /**
      * - Version of client/server protocol.
      */
-    version?: (2.9 | 2.5 | 2.2) | null;
+    version?: ('auto' | '4.1' | '4.0' | '3.1' | '3.0' | '2.9' | '2.5' | '2.2') | null;
     /**
      * - Optional cache name.
      */
@@ -131,6 +147,15 @@ export function client(args: {
             port: number;
         }[];
     }[];
+    /**
+     * - Near cache configuration. When set, enables client-side caching with server-side invalidation.
+     */
+    nearCache?: {
+        /**
+         * - Maximum number of entries to store in the near cache.
+         */
+        maxEntries: number;
+    } | null;
 }): Promise<ReturnType<{
     (addrs: any, clientOpts: any): {
         connect: () => any;
@@ -144,6 +169,14 @@ export function client(args: {
          * @since 0.3
          */
         disconnect: () => Promise<void>;
+        /**
+         * Returns the active protocol version string (e.g. '3.1', '4.1').
+         * When using auto-negotiation, this reflects the negotiated version.
+         *
+         * @returns {string} Protocol version string.
+         * @memberof Client#
+         */
+        getProtocolVersion: () => string;
         /**
          * Get the value associated with the given key parameter.
          *
@@ -651,6 +684,134 @@ export function client(args: {
          * @since 0.3
          */
         removeListener: (listenerId: string) => Promise<any>;
+        /**
+         * Register a continuous query that watches for cache changes
+         * matching the given Ickle query.
+         *
+         * @param queryString Ickle query string.
+         * @param opts Optional CQ options.
+         * @returns A promise completed with a ContinuousQuery handle.
+         * @memberof Client#
+         * @since 0.16
+         */
+        addContinuousQuery: (queryString: string, opts?: {
+            /** Named parameter bindings for the Ickle query. */
+            params?: { [name: string]: string | number | boolean };
+        }) => Promise<{
+            /** Register a callback for continuous query events. */
+            on(event: 'joining' | 'leaving' | 'updated', callback: (key: Buffer, value: Buffer, projection?: any[]) => void): any;
+            /** Get the listener ID for this continuous query. */
+            getListenerId(): string;
+        }>;
+        /**
+         * Remove a continuous query.
+         *
+         * @param cq ContinuousQuery handle returned by addContinuousQuery.
+         * @returns A promise completed when the continuous query has been removed.
+         * @memberof Client#
+         * @since 0.16
+         */
+        removeContinuousQuery: (cq: { getListenerId(): string }) => Promise<any>;
+        /**
+         * Create a distributed counter.
+         *
+         * @param {String} name Counter name.
+         * @param {CounterConfig} config Counter configuration.
+         * @returns {Promise.<Boolean>}
+         * @memberof Client#
+         * @since 0.14
+         */
+        counterCreate: (name: string, config: {
+            type: 'strong' | 'weak';
+            storage?: 'persistent' | 'volatile';
+            initialValue?: number;
+            lowerBound?: number;
+            upperBound?: number;
+            concurrencyLevel?: number;
+        }) => Promise<boolean>;
+        /**
+         * Get the current value of a counter.
+         *
+         * @param {String} name Counter name.
+         * @returns {Promise.<?Number>}
+         * @memberof Client#
+         * @since 0.14
+         */
+        counterGet: (name: string) => Promise<number | undefined>;
+        /**
+         * Add a value to the counter and return the new value.
+         *
+         * @param {String} name Counter name.
+         * @param {Number} value Value to add.
+         * @returns {Promise.<?Number>}
+         * @memberof Client#
+         * @since 0.14
+         */
+        counterAddAndGet: (name: string, value: number) => Promise<number | undefined>;
+        /**
+         * Reset the counter to its initial value.
+         *
+         * @param {String} name Counter name.
+         * @returns {Promise.<Boolean>}
+         * @memberof Client#
+         * @since 0.14
+         */
+        counterReset: (name: string) => Promise<boolean>;
+        /**
+         * Compare and swap the counter value.
+         *
+         * @param {String} name Counter name.
+         * @param {Number} expect Expected current value.
+         * @param {Number} update New value to set.
+         * @returns {Promise.<?Number>}
+         * @memberof Client#
+         * @since 0.14
+         */
+        counterCompareAndSwap: (name: string, expect: number, update: number) => Promise<number | undefined>;
+        /**
+         * Check if a counter is defined.
+         *
+         * @param {String} name Counter name.
+         * @returns {Promise.<Boolean>}
+         * @memberof Client#
+         * @since 0.14
+         */
+        counterIsDefined: (name: string) => Promise<boolean>;
+        /**
+         * Get the configuration of a counter.
+         *
+         * @param {String} name Counter name.
+         * @returns {Promise.<?Object>}
+         * @memberof Client#
+         * @since 0.14
+         */
+        counterGetConfiguration: (name: string) => Promise<{
+            type: 'strong' | 'weak';
+            storage: 'persistent' | 'volatile';
+            initialValue: number;
+            lowerBound?: number;
+            upperBound?: number;
+            concurrencyLevel?: number;
+        } | undefined>;
+        /**
+         * Remove a counter from the cluster.
+         *
+         * @param {String} name Counter name.
+         * @returns {Promise.<Boolean>}
+         * @memberof Client#
+         * @since 0.14
+         */
+        counterRemove: (name: string) => Promise<boolean>;
+        /**
+         * Set a value to the counter and return the previous value.
+         *
+         * @param {String} name Counter name.
+         * @param {Number} value Value to set.
+         * @returns {Promise.<?Number>}
+         * @memberof Client#
+         * @since 0.14
+         */
+        counterGetAndSet: (name: string, value: number) => Promise<number | undefined>;
         /**
          * Add script to server(s).
          *
@@ -784,6 +945,80 @@ export function client(args: {
         toString: () => string;
         registerProtostreamType: (typeName: any, descriptorId: any) => any;
         registerProtostreamRoot: (root: any) => any;
+        /**
+         * Get the number of entries in the near cache.
+         *
+         * @returns {Number} Number of entries in the near cache, or 0 if near caching is not enabled.
+         * @memberof Client#
+         * @since 0.14
+         */
+        nearCacheSize: () => number;
+        /**
+         * Admin operations for cache lifecycle, schema management, and indexing.
+         * @since 0.15
+         */
+        admin: {
+            /**
+             * Create a cache with the given configuration.
+             * @param name Cache name.
+             * @param config Cache configuration (XML or JSON).
+             * @param opts Optional settings.
+             * @since 0.15
+             */
+            createCache: (name: string, config?: string, opts?: { template?: string; flags?: string }) => Promise<any>;
+            /**
+             * Get an existing cache or create it with the given configuration.
+             * @param name Cache name.
+             * @param config Cache configuration (XML or JSON).
+             * @param opts Optional settings.
+             * @since 0.15
+             */
+            getOrCreateCache: (name: string, config?: string, opts?: { template?: string; flags?: string }) => Promise<any>;
+            /**
+             * Remove a cache.
+             * @param name Cache name.
+             * @since 0.15
+             */
+            removeCache: (name: string) => Promise<any>;
+            /**
+             * List all cache names.
+             * @since 0.15
+             */
+            cacheNames: () => Promise<string[]>;
+            /**
+             * Update a mutable configuration attribute on a cache.
+             * @param name Cache name.
+             * @param attribute Attribute path (e.g. 'memory.max-count').
+             * @param value New attribute value.
+             * @since 0.15
+             */
+            updateConfigurationAttribute: (name: string, attribute: string, value: string) => Promise<any>;
+            /**
+             * Rebuild indexes for a cache.
+             * @param name Cache name.
+             * @since 0.15
+             */
+            reindex: (name: string) => Promise<any>;
+            /**
+             * Update the index schema for a cache.
+             * @param name Cache name.
+             * @since 0.15
+             */
+            updateIndexSchema: (name: string) => Promise<any>;
+            /**
+             * Register (create or update) a Protobuf schema on the server.
+             * @param name Schema name (e.g. 'person.proto').
+             * @param schema Protobuf schema content.
+             * @since 0.15
+             */
+            registerSchema: (name: string, schema: string) => Promise<any>;
+            /**
+             * Remove a registered Protobuf schema.
+             * @param name Schema name.
+             * @since 0.15
+             */
+            removeSchema: (name: string) => Promise<any>;
+        };
     };
     /**
      * Cluster information.