infinispan 0.13.0 → 0.15.0

package/lib/infinispan.js

@@ -13,27 +13,32 @@
   var f = require('./functional');
   var codec = require('./codec');
   var u = require('./utils');
+  var uri = require('./uri');
   var protocols = require('./protocols');
   var io = require('./io');
   var listeners = require('./listeners');
+  var nearCacheFactory = require('./near-cache');
 
   var Client = function(addrs, clientOpts) {
     var logger = u.logger('client');
 
+    /**
+     * Resolves the protocol implementation for a given version string.
+     * @param {string} version Protocol version (e.g. '2.9', '3.0').
+     * @returns {Object} Protocol instance for the specified version.
+     */
     function protocolResolver(version) {
-      logger.debugf('Using protocol version: %s', version);
-
-      switch (version) {
-        case '3.0': return protocols.version30(clientOpts);
-        case '2.9': return protocols.version29(clientOpts);
-        case '2.5': return protocols.version25(clientOpts);
-        case '2.2': return protocols.version22(clientOpts);
-        default : throw new Error('Unknown protocol version: ' + version);
+      if (version === 'auto') {
+        logger.debugf('Using protocol auto-negotiation (starting with %s)', protocols.VERSION_ORDER[0]);
+        return protocols.resolve(protocols.VERSION_ORDER[0], clientOpts);
       }
+      logger.debugf('Using protocol version: %s', version);
+      return protocols.resolve(version, clientOpts);
     }
 
     var p = protocolResolver(clientOpts['version']);
     var listen = listeners(p);
+    var nc = clientOpts.nearCache ? nearCacheFactory(clientOpts.nearCache.maxEntries) : null;
 
     var TINY = 16, SMALL = 32, MEDIUM = 64, BIG = 128;
 
@@ -41,31 +46,82 @@
     var events = ['create', 'modify', 'remove', 'expiry'];
     Object.freeze(events);
 
+    /**
+     * Sends a request with header and body, returning a promise for the decoded response.
+     * @param {Object} ctx Request context with buffer and id.
+     * @param {number} op Operation code.
+     * @param {Function} body Body encoder function.
+     * @param {Function} decoder Response decoder function.
+     * @param {Object} [opts] Optional operation options.
+     * @returns {Promise} Promise resolved with the decoded response.
+     */
     function future(ctx, op, body, decoder, opts) {
       f.actions(p.stepsHeaderBody(ctx, op, body, opts), codec.bytesEncoded)(ctx);
       return transport.writeCommand(ctx, decoder);
     }
 
+    /**
+     * Sends a header-only request and decodes the response.
+     * @param {Object} ctx Request context with buffer and id.
+     * @param {number} op Operation code.
+     * @param {Function} decoder Response decoder function.
+     * @param {Object} [opts] Optional operation options.
+     * @returns {Promise} Promise resolved with the decoded response.
+     */
     function futureDecodeOnly(ctx, op, decoder, opts) {
       f.actions(p.stepsHeader(ctx, op, opts), codec.bytesEncoded)(ctx);
       return transport.writeCommand(ctx, decoder);
     }
 
+    /**
+     * Sends a header-only request with no decoder.
+     * @param {Object} ctx Request context with buffer and id.
+     * @param {number} op Operation code.
+     * @returns {Promise} Promise resolved when the operation completes.
+     */
     function futureEmpty(ctx, op) {
       f.actions(p.stepsHeader(ctx, op), codec.bytesEncoded)(ctx);
       return transport.writeCommand(ctx);
     }
 
+    /**
+     * Sends a key-routed request with body, using consistent hashing for server selection.
+     * @param {Object} ctx Request context with buffer and id.
+     * @param {number} op Operation code.
+     * @param {string|Object} key Key used for routing.
+     * @param {Function} body Body encoder function.
+     * @param {Function} decoder Response decoder function.
+     * @param {Object} [opts] Optional operation options.
+     * @returns {Promise} Promise resolved with the decoded response.
+     */
     function futureKey(ctx, op, key, body, decoder, opts) {
       f.actions(p.stepsHeaderBody(ctx, op, body, opts), codec.bytesEncoded)(ctx);
       return transport.writeKeyCommand(ctx, key, decoder);
     }
 
+    /**
+     * Sends a request pinned to a specific connection.
+     * @param {Object} ctx Request context with buffer and id.
+     * @param {number} op Operation code.
+     * @param {Function} body Body encoder function.
+     * @param {Function} decoder Response decoder function.
+     * @param {Object} conn Connection to pin the request to.
+     * @returns {Promise} Promise resolved with the decoded response.
+     */
     function futurePinned(ctx, op, body, decoder, conn) {
       f.actions(p.stepsHeaderBody(ctx, op, body), codec.bytesEncoded)(ctx);
       return transport.writeCommandPinned(ctx, decoder, conn);
     }
 
+    /**
+     * Sends a script execution request and post-processes nulls in the response.
+     * @param {Object} ctx Request context with buffer and id.
+     * @param {number} op Operation code.
+     * @param {Function} body Body encoder function.
+     * @param {Function} decoder Response decoder function.
+     * @param {Object} [opts] Optional operation options.
+     * @returns {Promise<string>} Promise resolved with the execution result.
+     */
     function futureExec(ctx, op, body, decoder, opts) {
       f.actions(p.stepsHeaderBody(ctx, op, body, opts), codec.bytesEncoded)(ctx);
       var resultPromise = transport.writeCommand(ctx, decoder);
@@ -79,6 +135,11 @@
       });
     }
 
+    /**
+     * Checks whether the given event name is a supported listener event.
+     * @param {string} event Event name to check.
+     * @returns {boolean} True if the event is supported.
+     */
     function isEventDefined(event) {
       var exists = false;
       var eventLowerCase = event.toLowerCase();
@@ -96,6 +157,9 @@
     /**
      * Iterator instance returned by completed promise from Client.iterator() calls.
      *
+     * @param {String} iterId Iterator identifier.
+     * @param {Object} conn Connection instance.
+     * @returns {Object} Iterator instance with close and next methods.
      * @constructs Iterator
      * @since 0.3
      */
@@ -103,6 +167,10 @@
       var nextElems = [];
       var done = false;
 
+      /**
+       * Returns a promise fulfilled with the next cached entry.
+       * @returns {Promise<Object>} Promise with the next entry and done status.
+       */
       function nextPromise() {
         var kv = nextElems.pop();
         return new Promise(function (fulfill, reject) {
@@ -110,6 +178,10 @@
         });
       }
 
+      /**
+       * Returns a promise indicating iteration is complete.
+       * @returns {Promise<Object>} Promise with done set to true.
+       */
       function donePromise() {
         return new Promise(function (fulfill, reject) {
           fulfill({done: done});
@@ -180,7 +252,7 @@
           return futurePinned(
               ctx, 0x35, p.encodeIterId(iterId), p.complete(p.hasSuccess), conn);
         }
-      }
+      };
     }
 
     return {
@@ -188,6 +260,29 @@
         // TODO: Avoid user calling connect by checking if connected
         var client = this;
         return transport.connect()
+            .then(function() {
+              if (clientOpts.version === 'auto') {
+                var negotiatedProtocol = transport.getProtocol();
+                p = negotiatedProtocol;
+                listen.setProtocol(negotiatedProtocol);
+                logger.debugf('Negotiated protocol version: %s', p.getVersionString());
+              }
+            })
+            .then(function() {
+              if (nc) {
+                var invalidate = function(key) { nc.remove(key); };
+                return client.addListener('create', invalidate)
+                    .then(function(listenerId) {
+                      return client.addListener('modify', invalidate, {listenerId: listenerId});
+                    })
+                    .then(function(listenerId) {
+                      return client.addListener('remove', invalidate, {listenerId: listenerId});
+                    })
+                    .then(function(listenerId) {
+                      return client.addListener('expiry', invalidate, {listenerId: listenerId});
+                    });
+              }
+            })
             .then(function() {
               logger.debugf('Started Infinispan %s', client);
               return client; // return client
@@ -208,12 +303,23 @@
        * @since 0.3
        */
       disconnect: function() {
+        if (nc) nc.clear();
         return transport.disconnect();
       },
+      /**
+       * 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: function() {
+        return p.getVersionString();
+      },
       /**
        * Get the value associated with the given key parameter.
        *
-       * @param k {(String|Object)} Key to retrieve.
+       * @param {(String|Object)} k Key to retrieve.
        * @returns {Promise.<?String>}
        * A promise that will be completed with the value associated with
        * the key, or undefined if the value is not present.
@@ -221,18 +327,33 @@
        * @since 0.3
        */
       get: function(k) {
+        if (nc) {
+          var cached = nc.get(k);
+          if (cached !== undefined) {
+            return Promise.resolve(cached);
+          }
+        }
         var ctx = transport.context(SMALL);
         logger.debugf('Invoke get(msgId=%d,key=%s)', ctx.id, u.str(k));
         var decoder = p.decodeValue();
-        return futureKey(ctx, 0x03, k, p.encodeKey(k), decoder);
+        var result = futureKey(ctx, 0x03, k, p.encodeKey(k), decoder);
+        if (nc) {
+          return result.then(function(value) {
+            if (value !== undefined) {
+              nc.put(k, value);
+            }
+            return value;
+          });
+        }
+        return result;
       },
       /**
        * Query the server with the given queryString.
        *
-       * @param q {(Object)} query to retrieve.
-       * @returns {Promise.<?Object[]>}
+       * @param {Object} q Query to retrieve.
+       * @returns {Promise.<Object[]>}
        * A promise that will be completed with the array of values associated with
-       * the query, or empty array if the no values matches the query.
+       * the query, or empty array if no values match the query.
        * @memberof Client#
        * @since 1.3
        */
@@ -246,7 +367,7 @@
       /**
        * Check whether the given key is present.
        *
-       * @param k {(String|Object)} Key to check for presence.
+       * @param {(String|Object)} k Key to check for presence.
        * @returns {Promise.<boolean>}
        * A promise that will be completed with true if there is a value
        * associated with the key, or false otherwise.
@@ -273,7 +394,7 @@
       /**
        * Get the value and metadata associated with the given key parameter.
        *
-       * @param k {(String|Object)} Key to retrieve.
+       * @param {(String|Object)} k Key to retrieve.
        * @returns {Promise.<?MetadataValue>}
        * A promise that will be completed with the value and metadata
        * associated with the key, or undefined if the value is not present.
@@ -284,7 +405,16 @@
         var ctx = transport.context(SMALL);
         logger.debugf('Invoke getWithMetadata(msgId=%d,key=%s)', ctx.id, u.str(k));
         var decoder = p.decodeWithMeta();
-        return futureKey(ctx, 0x1B, k, p.encodeKey(k), decoder);
+        var result = futureKey(ctx, 0x1B, k, p.encodeKey(k), decoder);
+        if (nc) {
+          return result.then(function(meta) {
+            if (meta !== undefined) {
+              nc.put(k, meta.value);
+            }
+            return meta;
+          });
+        }
+        return result;
       },
       /**
        * A String formatted to specify duration unit information.
@@ -314,9 +444,9 @@
       /**
        * Associates the specified value with the given key.
        *
-       * @param k {(String|Object)} Key with which the specified value is to be associated.
-       * @param v {(String|Object)} Value to be associated with the specified key.
-       * @param opts {StoreOptions=} Optional store options.
+       * @param {(String|Object)} k Key with which the specified value is to be associated.
+       * @param {(String|Object)} v Value to be associated with the specified key.
+       * @param {StoreOptions=} opts Optional store options.
        * @returns {Promise.<?(String|Object)>}
        * A promise that will be completed with undefined unless 'previous'
        * option has been enabled and a previous value exists, in which case it
@@ -325,6 +455,7 @@
        * @since 0.3
        */
       put: function(k, v, opts) {
+        if (nc) nc.remove(k);
         var ctx = transport.context(MEDIUM);
         logger.debugl(function() { return ['Invoke put(msgId=%d,key=%s,value=%s,opts=%s)',
                                            ctx.id, u.str(k), u.str(v), u.str(opts)]; });
@@ -344,8 +475,8 @@
       /**
        * Removes the mapping for a key if it is present.
        *
-       * @param k {(String|Object)} Key whose mapping is to be removed.
-       * @param opts {RemoveOptions=} Optional remove options.
+       * @param {(String|Object)} k Key whose mapping is to be removed.
+       * @param {RemoveOptions=} opts Optional remove options.
        * @returns {Promise.<(Boolean|String|Object)>}
        * A promise that will be completed with true if the mapping was removed,
        * or false if the key did not exist.
@@ -355,6 +486,7 @@
        * @since 0.3
        */
       remove: function(k, opts) {
+        if (nc) nc.remove(k);
         var ctx = transport.context(SMALL);
         logger.debugl(function() {return ['Invoke remove(msgId=%d,key=%s,opts=%s)',
                                           ctx.id, u.str(k), JSON.stringify(opts)]; });
@@ -365,9 +497,9 @@
        * Conditional store operation that associates the key with the given
        * value if the specified key is not already associated with a value.
        *
-       * @param k {(String|Object)} Key with which the specified value is to be associated.
-       * @param v {(String|Object)} Value to be associated with the specified key.
-       * @param opts {StoreOptions=} Optional store options.
+       * @param {(String|Object)} k Key with which the specified value is to be associated.
+       * @param {(String|Object)} v Value to be associated with the specified key.
+       * @param {StoreOptions=} opts Optional store options.
        * @returns {Promise.<(Boolean|String|Object)>}
        * A promise that will be completed with true if the mapping was stored,
        * or false if the key is already present.
@@ -377,6 +509,7 @@
        * @since 0.3
        */
       putIfAbsent: function(k, v, opts) {
+        if (nc) nc.remove(k);
         var ctx = transport.context(MEDIUM);
         logger.debugl(function() {return ['Invoke putIfAbsent(msgId=%d,key=%s,value=%s,opts=%s)',
                                           ctx.id, u.str(k), u.str(v), JSON.stringify(opts)]; });
@@ -387,9 +520,9 @@
        * Conditional store operation that replaces the entry for a key only
        * if currently mapped to a given value.
        *
-       * @param k {(String|Object)} Key with which the specified value is associated.
-       * @param v {(String|Object)} Value expected to be associated with the specified key.
-       * @param opts {StoreOptions=} Optional store options.
+       * @param {(String|Object)} k Key with which the specified value is associated.
+       * @param {(String|Object)} v Value expected to be associated with the specified key.
+       * @param {StoreOptions=} opts Optional store options.
        * @returns {Promise.<(Boolean|String|Object)>}
        * A promise that will be completed with true if the mapping was replaced,
        * or false if the key does not exist.
@@ -399,6 +532,7 @@
        * @since 0.3
        */
       replace: function(k, v, opts) {
+        if (nc) nc.remove(k);
         var ctx = transport.context(MEDIUM);
         logger.debugl(function() { return ['Invoke replace(msgId=%d,key=%s,value=%s,opts=%s)',
                                            ctx.id, u.str(k), u.str(v), JSON.stringify(opts)]; });
@@ -409,12 +543,12 @@
        * Replaces the given value only if its version matches the supplied
        * version.
        *
-       * @param k {(String|Object)} Key with which the specified value is associated.
-       * @param v {(String|Object)} Value expected to be associated with the specified key.
-       * @param version {Buffer} binary buffer version that should match the
+       * @param {(String|Object)} k Key with which the specified value is associated.
+       * @param {(String|Object)} v Value expected to be associated with the specified key.
+       * @param {Buffer} version binary buffer version that should match the
        * one in the server for the operation to succeed. Version information
        * can be retrieved with getWithMetadata method.
-       * @param opts {StoreOptions=} Optional store options.
+       * @param {StoreOptions=} opts Optional store options.
        * @returns {Promise.<(Boolean|String|Object)>}
        * A promise that will be completed with true if the version matches
        * and the mapping was replaced, otherwise it returns false if not
@@ -428,6 +562,7 @@
        * @since 0.3
        */
       replaceWithVersion: function(k, v, version, opts) {
+        if (nc) nc.remove(k);
         var ctx = transport.context(MEDIUM);
         logger.debugl(function() { return ['Invoke replaceWithVersion(msgId=%d,key=%s,value=%s,version=0x%s,opts=%s)',
                                            ctx.id, u.str(k), u.str(v), version.toString('hex'), JSON.stringify(opts)]; });
@@ -438,11 +573,11 @@
        * Removes the given entry only if its version matches the
        * supplied version.
        *
-       * @param k {(String|Object)} Key whose mapping is to be removed.
-       * @param version {Buffer} binary buffer version that should match the
+       * @param {(String|Object)} k Key whose mapping is to be removed.
+       * @param {Buffer} version binary buffer version that should match the
        * one in the server for the operation to succeed. Version information
        * can be retrieved with getWithMetadata method.
-       * @param opts {RemoveOptions=} Optional remove options.
+       * @param {RemoveOptions=} opts Optional remove options.
        * @returns {Promise.<(Boolean|String|Object)>}
        * A promise that will be completed with true if the version matches
        * and the mapping was removed, otherwise it returns false if not
@@ -456,6 +591,7 @@
        * @since 0.3
        */
       removeWithVersion: function(k, version, opts) {
+        if (nc) nc.remove(k);
         var ctx = transport.context(SMALL);
         logger.debugl(function() { return ['Invoke removeWithVersion(msgId=%d,key=%s,version=0x%s,opts=%s)',
                                            ctx.id, u.str(k), version.toString('hex'), JSON.stringify(opts)]; });
@@ -473,7 +609,7 @@
       /**
        * Retrieves all of the entries for the provided keys.
        *
-       * @param keys {(String[]|Object[])} Keys to find values for.
+       * @param {(String[]|Object[])} keys Keys to find values for.
        * @returns {Promise.<Entry[]>}
        * A promise that will be completed with an array of entries for all
        * keys found. If a key does not exist, there won't be an entry for that
@@ -501,8 +637,8 @@
       /**
        * Stores all of the mappings from the specified entry array.
        *
-       * @param pairs {Entry[]} key/value pair mappings to be stored
-       * @param opts {MultiStoreOptions=}
+       * @param {Entry[]} pairs key/value pair mappings to be stored
+       * @param {MultiStoreOptions=} opts
        * Optional storage options to apply to all entries.
        * @returns {Promise}
        * A promise that will be completed when all entries have been stored.
@@ -510,6 +646,9 @@
        * @since 0.3
        */
       putAll: function(pairs, opts) {
+        if (nc) {
+          _.each(pairs, function(pair) { nc.remove(pair.key); });
+        }
         var ctx = transport.context(BIG);
         logger.debugl(function() { return ['Invoke putAll(msgId=%d,pairs=%s,opts=%s)',
                                            ctx.id, JSON.stringify(pairs), JSON.stringify(opts)]; });
@@ -528,9 +667,9 @@
       /**
        * Iterate over the entries stored in server(s).
        *
-       * @param batchSize {Number}
+       * @param {Number} batchSize
        * The number of entries transferred from the server at a time.
-       * @param opts {IteratorOptions=} Optional iteration settings.
+       * @param {IteratorOptions=} opts Optional iteration settings.
        * @return {Promise.<Iterator>}
        * A promise that will be completed with an iterator that can be used
        * to retrieve stored elements.
@@ -567,6 +706,7 @@
        * @since 0.3
        */
       clear: function() {
+        if (nc) nc.clear();
         var ctx = transport.context(TINY);
         logger.debugf('Invoke clear(msgId=%d)', ctx.id);
         return futureEmpty(ctx, 0x13);
@@ -632,7 +772,7 @@
        * entry version and listener id.
        * 'remove' and 'expiry' events callback the function with key
        * and listener id.
-       * @param opts {ListenOptions=} Options for adding listener.
+       * @param {ListenOptions=} opts Options for adding listener.
        * @returns {Promise<String>}
        * A promise that will be completed with the identifier of the listener.
        * This identifier can be used to register multiple callbacks with the
@@ -647,7 +787,7 @@
                 var conn = listen.findConnectionListener(opts.listenerId);
                 if (!f.existy(conn))
                     return Promise.reject(
-                        new Error('No server connection for listener (listenerId=' + opts.listenerId + ')'));
+                        new Error(`No server connection for listener (listenerId=${  opts.listenerId  })`));
 
                 return listen.addLocalListener(ctx, event, listener, opts);
             } else {
@@ -655,7 +795,7 @@
             }
         } else {
             return Promise.reject(
-                new Error('The event \'' + event + '\' is not supported'));
+                new Error(`The event '${  event  }' is not supported`));
         }
       },
       /**
@@ -674,7 +814,59 @@
         var conn = listen.findConnectionListener(listenerId);
         if (!f.existy(conn))
           return Promise.reject(
-            new Error('No server connection for listener (listenerId=' + listenerId + ')'));
+            new Error(`No server connection for listener (listenerId=${  listenerId  })`));
+
+        var remote = futurePinned(ctx, 0x27, p.encodeListenerId(listenerId), p.complete(p.hasSuccess), conn);
+        return remote.then(function (success) {
+          if (success) {
+            listen.removeListeners(listenerId);
+            return true;
+          }
+          return false;
+        });
+      },
+      /**
+       * Continuous query options.
+       *
+       * @typedef {Object} ContinuousQueryOptions
+       * @property {Object} [params] - Named parameter bindings for the Ickle query.
+       * @since 0.16
+       */
+      /**
+       * Register a continuous query that watches for cache changes
+       * matching the given Ickle query.
+       *
+       * @param {String} queryString Ickle query string.
+       * @param {ContinuousQueryOptions=} opts Optional CQ options.
+       * @returns {Promise<Object>}
+       * A promise completed with a ContinuousQuery handle.
+       * Use cq.on('joining', fn), cq.on('leaving', fn), cq.on('updated', fn)
+       * to receive events.
+       * @memberof Client#
+       * @since 0.16
+       */
+      addContinuousQuery: function(queryString, opts) {
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke addContinuousQuery(msgId=%d,query=%s)', ctx.id, queryString);
+        return listen.addContinuousQueryListener(transport, ctx, queryString, opts);
+      },
+      /**
+       * Remove a continuous query.
+       *
+       * @param {Object} cq ContinuousQuery handle returned by addContinuousQuery.
+       * @returns {Promise}
+       * A promise completed when the continuous query has been removed.
+       * @memberof Client#
+       * @since 0.16
+       */
+      removeContinuousQuery: function(cq) {
+        var listenerId = cq.getListenerId();
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke removeContinuousQuery(msgId=%d,listenerId=%s)', ctx.id, listenerId);
+        var conn = listen.findConnectionListener(listenerId);
+        if (!f.existy(conn))
+          return Promise.reject(
+            new Error(`No server connection for CQ listener (listenerId=${  listenerId  })`));
 
         var remote = futurePinned(ctx, 0x27, p.encodeListenerId(listenerId), p.complete(p.hasSuccess), conn);
         return remote.then(function (success) {
@@ -734,6 +926,153 @@
         // TODO update jsdoc, value does not need to be String, can be JSON too
         return futureExec(ctx, 0x2B, p.encodeNameParams(scriptName, params), p.decodeValue());
       },
+      /**
+       * Counter configuration options.
+       *
+       * @typedef {Object} CounterConfig
+       * @property {('strong'|'weak')} type - Counter type.
+       * @property {('persistent'|'volatile')} [storage='volatile'] - Storage mode.
+       * @property {Number} [initialValue=0] - Initial counter value.
+       * @property {Number} [lowerBound] - Lower bound (strong bounded counters only).
+       * @property {Number} [upperBound] - Upper bound (strong bounded counters only).
+       * @property {Number} [concurrencyLevel=16] - Concurrency level (weak counters only).
+       * @since 0.14
+       */
+      /**
+       * Create a distributed counter.
+       *
+       * @param {String} name Counter name.
+       * @param {CounterConfig} config Counter configuration.
+       * @returns {Promise.<Boolean>}
+       * A promise that will be completed with true if the counter was created,
+       * or false if it already exists.
+       * @memberof Client#
+       * @since 0.14
+       */
+      counterCreate: function(name, config) {
+        var ctx = transport.context(MEDIUM);
+        logger.debugf('Invoke counterCreate(msgId=%d,name=%s)', ctx.id, name);
+        return future(ctx, 0x4B, p.encodeCounterCreate(name, config), p.decodeCounterStatus);
+      },
+      /**
+       * Get the current value of a counter.
+       *
+       * @param {String} name Counter name.
+       * @returns {Promise.<?Number>}
+       * A promise that will be completed with the counter value,
+       * or undefined if the counter is not defined.
+       * @memberof Client#
+       * @since 0.14
+       */
+      counterGet: function(name) {
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke counterGet(msgId=%d,name=%s)', ctx.id, name);
+        return future(ctx, 0x56, p.encodeCounterName(name), p.decodeCounterValue);
+      },
+      /**
+       * Add a value to the counter and return the new value.
+       *
+       * @param {String} name Counter name.
+       * @param {Number} value Value to add (can be negative).
+       * @returns {Promise.<?Number>}
+       * A promise that will be completed with the new counter value.
+       * @memberof Client#
+       * @since 0.14
+       */
+      counterAddAndGet: function(name, value) {
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke counterAddAndGet(msgId=%d,name=%s,value=%d)', ctx.id, name, value);
+        return future(ctx, 0x52, p.encodeCounterNameValue(name, value), p.decodeCounterValue);
+      },
+      /**
+       * Reset the counter to its initial value.
+       *
+       * @param {String} name Counter name.
+       * @returns {Promise.<Boolean>}
+       * A promise that will be completed with true if the counter was reset.
+       * @memberof Client#
+       * @since 0.14
+       */
+      counterReset: function(name) {
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke counterReset(msgId=%d,name=%s)', ctx.id, name);
+        return future(ctx, 0x54, p.encodeCounterName(name), p.decodeCounterStatus);
+      },
+      /**
+       * Compare and swap the counter value.
+       *
+       * @param {String} name Counter name.
+       * @param {Number} expect Expected current value.
+       * @param {Number} update New value to set if current matches expected.
+       * @returns {Promise.<?Number>}
+       * A promise that will be completed with the counter value
+       * (the old value if successful, or current value if not).
+       * @memberof Client#
+       * @since 0.14
+       */
+      counterCompareAndSwap: function(name, expect, update) {
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke counterCompareAndSwap(msgId=%d,name=%s,expect=%d,update=%d)', ctx.id, name, expect, update);
+        return future(ctx, 0x58, p.encodeCounterNameTwoLongs(name, expect, update), p.decodeCounterValue);
+      },
+      /**
+       * Check if a counter is defined.
+       *
+       * @param {String} name Counter name.
+       * @returns {Promise.<Boolean>}
+       * A promise that will be completed with true if the counter is defined.
+       * @memberof Client#
+       * @since 0.14
+       */
+      counterIsDefined: function(name) {
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke counterIsDefined(msgId=%d,name=%s)', ctx.id, name);
+        return future(ctx, 0x4F, p.encodeCounterName(name), p.decodeCounterStatus);
+      },
+      /**
+       * Get the configuration of a counter.
+       *
+       * @param {String} name Counter name.
+       * @returns {Promise.<?CounterConfig>}
+       * A promise that will be completed with the counter configuration,
+       * or undefined if the counter is not defined.
+       * @memberof Client#
+       * @since 0.14
+       */
+      counterGetConfiguration: function(name) {
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke counterGetConfiguration(msgId=%d,name=%s)', ctx.id, name);
+        return future(ctx, 0x4D, p.encodeCounterName(name), p.decodeCounterConfig);
+      },
+      /**
+       * Remove a counter from the cluster.
+       *
+       * @param {String} name Counter name.
+       * @returns {Promise.<Boolean>}
+       * A promise that will be completed with true if the counter was removed.
+       * @memberof Client#
+       * @since 0.14
+       */
+      counterRemove: function(name) {
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke counterRemove(msgId=%d,name=%s)', ctx.id, name);
+        return future(ctx, 0x5E, p.encodeCounterName(name), p.decodeCounterStatus);
+      },
+      /**
+       * 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>}
+       * A promise that will be completed with the previous counter value.
+       * @memberof Client#
+       * @since 0.14
+       */
+      counterGetAndSet: function(name, value) {
+        var ctx = transport.context(SMALL);
+        logger.debugf('Invoke counterGetAndSet(msgId=%d,name=%s,value=%d)', ctx.id, name, value);
+        return future(ctx, 0x7F, p.encodeCounterNameValue(name, value), p.decodeCounterValue);
+      },
       /**
        * Get server topology related information.
        *
@@ -748,6 +1087,7 @@
       },
       /**
        * Get client information represented as a string.
+       * @returns {String} String representation of the client.
        * @memberof Client#
        * @since 0.4
        */
@@ -761,13 +1101,175 @@
 
       registerProtostreamRoot: function(root){
         return p.registerProtostreamRoot(root);
+      },
+      /**
+       * 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: function() {
+        return nc ? nc.size() : 0;
+      },
+
+      /**
+       * Admin operations for cache lifecycle, schema management, and indexing.
+       * These operations use Hot Rod server tasks (exec opcode 0x2B) with
+       * predefined @@-prefixed task names.
+       * @memberof Client#
+       * @since 0.15
+       */
+      admin: {
+        /**
+         * Create a cache with the given configuration.
+         *
+         * @param {String} name Cache name.
+         * @param {String} config Cache configuration (XML or JSON).
+         * @param {Object} [opts] Optional settings.
+         * @param {String} [opts.template] Template name to use instead of config.
+         * @param {String} [opts.flags] Admin flags (e.g. 'VOLATILE' for non-persistent caches).
+         * @returns {Promise} A promise that completes when the cache is created.
+         * @memberof Client.admin#
+         * @since 0.15
+         */
+        createCache: function(name, config, opts) {
+          var params = {name: name};
+          if (f.existy(config)) params.configuration = config;
+          if (f.existy(opts) && f.existy(opts.template)) params.template = opts.template;
+          if (f.existy(opts) && f.existy(opts.flags)) params.flags = opts.flags;
+          var ctx = transport.context(MEDIUM);
+          logger.debugf('Invoke admin.createCache(msgId=%d,name=%s)', ctx.id, name);
+          return future(ctx, 0x2B, p.encodeNameParams('@@cache@create', params), p.decodeValue());
+        },
+        /**
+         * Get an existing cache or create it with the given configuration.
+         *
+         * @param {String} name Cache name.
+         * @param {String} config Cache configuration (XML or JSON).
+         * @param {Object} [opts] Optional settings.
+         * @param {String} [opts.template] Template name to use instead of config.
+         * @param {String} [opts.flags] Admin flags (e.g. 'VOLATILE').
+         * @returns {Promise} A promise that completes when the cache is available.
+         * @memberof Client.admin#
+         * @since 0.15
+         */
+        getOrCreateCache: function(name, config, opts) {
+          var params = {name: name};
+          if (f.existy(config)) params.configuration = config;
+          if (f.existy(opts) && f.existy(opts.template)) params.template = opts.template;
+          if (f.existy(opts) && f.existy(opts.flags)) params.flags = opts.flags;
+          var ctx = transport.context(MEDIUM);
+          logger.debugf('Invoke admin.getOrCreateCache(msgId=%d,name=%s)', ctx.id, name);
+          return future(ctx, 0x2B, p.encodeNameParams('@@cache@getorcreate', params), p.decodeValue());
+        },
+        /**
+         * Remove a cache.
+         *
+         * @param {String} name Cache name.
+         * @returns {Promise} A promise that completes when the cache is removed.
+         * @memberof Client.admin#
+         * @since 0.15
+         */
+        removeCache: function(name) {
+          var ctx = transport.context(SMALL);
+          logger.debugf('Invoke admin.removeCache(msgId=%d,name=%s)', ctx.id, name);
+          return future(ctx, 0x2B, p.encodeNameParams('@@cache@remove', {name: name}), p.decodeValue());
+        },
+        /**
+         * List all cache names.
+         *
+         * @returns {Promise<String[]>} A promise that completes with the list of cache names.
+         * @memberof Client.admin#
+         * @since 0.15
+         */
+        cacheNames: function() {
+          var ctx = transport.context(SMALL);
+          logger.debugf('Invoke admin.cacheNames(msgId=%d)', ctx.id);
+          return future(ctx, 0x2B, p.encodeNameParams('@@cache@names', {}), p.decodeValue())
+            .then(function(result) { return JSON.parse(result); });
+        },
+        /**
+         * Update a mutable configuration attribute on a cache.
+         *
+         * @param {String} name Cache name.
+         * @param {String} attribute Attribute path (e.g. 'memory.max-count').
+         * @param {String} value New attribute value.
+         * @returns {Promise} A promise that completes when the attribute is updated.
+         * @memberof Client.admin#
+         * @since 0.15
+         */
+        updateConfigurationAttribute: function(name, attribute, value) {
+          var ctx = transport.context(SMALL);
+          logger.debugf('Invoke admin.updateConfigurationAttribute(msgId=%d,name=%s,attr=%s)', ctx.id, name, attribute);
+          return future(ctx, 0x2B, p.encodeNameParams('@@cache@updateConfigurationAttribute', {
+            name: name, attribute: attribute, value: value
+          }), p.decodeValue());
+        },
+        /**
+         * Rebuild indexes for a cache.
+         *
+         * @param {String} name Cache name.
+         * @returns {Promise} A promise that completes when reindexing starts.
+         * @memberof Client.admin#
+         * @since 0.15
+         */
+        reindex: function(name) {
+          var ctx = transport.context(SMALL);
+          logger.debugf('Invoke admin.reindex(msgId=%d,name=%s)', ctx.id, name);
+          return future(ctx, 0x2B, p.encodeNameParams('@@cache@reindex', {name: name}), p.decodeValue());
+        },
+        /**
+         * Update the index schema for a cache.
+         *
+         * @param {String} name Cache name.
+         * @returns {Promise} A promise that completes when the index schema is updated.
+         * @memberof Client.admin#
+         * @since 0.15
+         */
+        updateIndexSchema: function(name) {
+          var ctx = transport.context(SMALL);
+          logger.debugf('Invoke admin.updateIndexSchema(msgId=%d,name=%s)', ctx.id, name);
+          return future(ctx, 0x2B, p.encodeNameParams('@@cache@updateindexschema', {name: name}), p.decodeValue());
+        },
+        /**
+         * Register (create or update) a Protobuf schema on the server.
+         *
+         * @param {String} name Schema name (e.g. 'person.proto').
+         * @param {String} schema Protobuf schema content.
+         * @returns {Promise} A promise that completes when the schema is registered.
+         * @memberof Client.admin#
+         * @since 0.15
+         */
+        registerSchema: function(name, schema) {
+          var ctx = transport.context(MEDIUM);
+          logger.debugf('Invoke admin.registerSchema(msgId=%d,name=%s)', ctx.id, name);
+          return future(ctx, 0x2B, p.encodeNameParams('@@schemas@createOrUpdate', {
+            name: name, content: schema, op: 's'
+          }), p.decodeValue());
+        },
+        /**
+         * Remove a registered Protobuf schema.
+         *
+         * @param {String} name Schema name.
+         * @returns {Promise} A promise that completes when the schema is removed.
+         * @memberof Client.admin#
+         * @since 0.15
+         */
+        removeSchema: function(name) {
+          var ctx = transport.context(SMALL);
+          logger.debugf('Invoke admin.removeSchema(msgId=%d,name=%s)', ctx.id, name);
+          return future(ctx, 0x2B, p.encodeNameParams('@@schemas@delete', {name: name}), p.decodeValue());
+        }
       }
-    }
+    };
   };
 
   /**
    * Server topology information.
    *
+   * @param {Object} transport Transport instance.
+   * @returns {Object} Topology info object.
    * @constructs Topology
    * @since 0.3
    */
@@ -809,7 +1311,7 @@
        * Switch remote cache manager to a different cluster,
        * previously declared via configuration.
        *
-       * @param clusterName name of the cluster to which to switch to
+       * @param {String} clusterName Name of the cluster to which to switch to.
        * @return {Promise<Boolean>}
        * A promise encapsulating a Boolean that indicates {@code true} if the
        * switch happened, or {@code false} otherwise.
@@ -832,7 +1334,7 @@
       switchToDefaultCluster: function() {
         return transport.switchToDefaultCluster();
       }
-    }
+    };
   };
 
   /**
@@ -845,8 +1347,24 @@
    */
   /**
    * Infinispan client constructor taking an optional initial address,
-   * or multiple addresses, to which the client will try to connect to,
-   * as well as optional configuration settings.
+   * multiple addresses, or a Hot Rod URI string to which the client
+   * will try to connect, as well as optional configuration settings.
+   *
+   * @example
+   * // Connect with a Hot Rod URI
+   * client('hotrod://admin:password@localhost:11222')
+   *
+   * @example
+   * // URI with TLS and query parameters
+   * client('hotrods://admin:password@localhost:11222?trust_ca=/ca.pem')
+   *
+   * @example
+   * // URI with programmatic overrides
+   * client('hotrod://admin:password@localhost:11222', {authentication: {saslMechanism: 'SCRAM-SHA-256'}})
+   *
+   * @example
+   * // URI with multiple servers
+   * client('hotrod://admin:password@node1:11222,node2:11322')
    *
    * @example
    * client({port: 11222, host: 'localhost'})
@@ -861,18 +1379,29 @@
    * client([{port: 11522, host: 'myhost'}, {port: 11622, host: 'myhost'}],
    *        {version: '2.2', cacheName: 'myCache'})
    *
-   * @param args {(ServerAddress|ServerAddress[])}
-   * Optional single or multiple addresses to which to connect. If none
-   * provided, the client will connect to localhost:11222 address by default.
-   * @param [options] {ClientOptions}
-   * Optional configuration settings.
+   * @param {(String|ServerAddress|ServerAddress[])} args
+   * A Hot Rod URI string (hotrod:// or hotrods://), a single server address,
+   * or an array of server addresses. If none provided, the client connects
+   * to localhost:11222 by default.
+   * @param {ClientOptions=} options
+   * Optional configuration settings. When a URI is provided, these settings
+   * override URI values.
    * @constructs Client
-   * @returns {Promise<ReturnType<Client>>}
+   * @returns {Promise<ReturnType<Client>>} A promise that resolves to a connected client.
    * @since 0.3
    */
   exports.client = function client(args, options) {
-    var merged = f.merge(Client.config, options);
-    var c = new Client(u.normalizeAddresses(args), merged);
+    var addrs, uriOpts;
+    if (uri.isHotrodURI(args)) {
+      var parsed = uri.parseHotrodURI(args);
+      addrs = parsed.servers;
+      uriOpts = parsed.options;
+    } else {
+      addrs = u.normalizeAddresses(args);
+      uriOpts = {};
+    }
+    var merged = f.deepMerge(Client.config, uriOpts, options || {});
+    var c = new Client(addrs, merged);
 
     return c.connect();
   };
@@ -891,7 +1420,7 @@
    *
    * @static
    * @typedef {Object} ClientOptions
-   * @property {?(2.9|2.5|2.2)} [version=2.9] - Version of client/server protocol.
+   * @property {?('auto'|'4.1'|'4.0'|'3.1'|'3.0'|'2.9'|'2.5'|'2.2')} [version='auto'] - Version of client/server protocol. Use 'auto' to negotiate the highest supported version.
    * @property {?String} [cacheName] - Optional cache name.
    * @property {?Number} [maxRetries=3] - Optional number of retries for operation.
    * @property {?Object} [ssl] - TLS/SSL properties.
@@ -918,10 +1447,12 @@
    * @property {?boolean} [topologyUpdates=true] - Optional flag to controls whether the client deals with topology updates or not.
    * @property {?("text/plain"|"application/json")} [mediaType="text/plain"] - Media type of the cache contents.
    * @property {?Cluster[]} [clusters] - Optional additional clusters for cross-site failovers.
+   * @property {?Object} [nearCache] - Near cache configuration. When set, enables client-side caching with server-side invalidation.
+   * @property {?Number} [nearCache.maxEntries] - Maximum number of entries to store in the near cache.
    * @since 0.3
    */
   Client.config = {
-    version: '2.9',         // Hot Rod protocol version
+    version: 'auto',        // Hot Rod protocol version (auto-negotiate)
     cacheName: undefined,   // Cache name
     maxRetries: 3,           // Maximum number of retries
     authentication: {
@@ -938,16 +1469,7 @@
       enabled: false,
       secureProtocol: 'TLS_client_method',
       trustCerts: [],
-      clientAuth: {
-        key: undefined,
-        passphrase: undefined,
-        cert: undefined
-      },
-      sniHostName: undefined,
-      cryptoStore: {
-        path: undefined,
-        passphrase: undefined
-      }
+      sniHostName: undefined
     },
     dataFormat : {
       keyType: 'text/plain',