infinispan 0.12.0 → 0.14.0

package/lib/infinispan.js

@@ -16,24 +16,28 @@
   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 +45,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 +134,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 +156,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 +166,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 +177,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 +251,7 @@
           return futurePinned(
               ctx, 0x35, p.encodeIterId(iterId), p.complete(p.hasSuccess), conn);
         }
-      }
+      };
     }
 
     return {
@@ -188,6 +259,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 +302,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 +326,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 +366,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 +393,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 +404,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 +443,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 +454,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 +474,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 +485,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 +496,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 +508,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 +519,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 +531,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 +542,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 +561,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 +572,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 +590,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 +608,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 +636,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 +645,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 +666,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 +705,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 +771,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 +786,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 +794,7 @@
             }
         } else {
             return Promise.reject(
-                new Error('The event \'' + event + '\' is not supported'));
+                new Error(`The event '${  event  }' is not supported`));
         }
       },
       /**
@@ -674,7 +813,7 @@
         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) {
@@ -734,6 +873,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 +1034,7 @@
       },
       /**
        * Get client information represented as a string.
+       * @returns {String} String representation of the client.
        * @memberof Client#
        * @since 0.4
        */
@@ -761,13 +1048,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 +1258,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 +1281,7 @@
       switchToDefaultCluster: function() {
         return transport.switchToDefaultCluster();
       }
-    }
+    };
   };
 
   /**
@@ -861,13 +1310,13 @@
    * client([{port: 11522, host: 'myhost'}, {port: 11622, host: 'myhost'}],
    *        {version: '2.2', cacheName: 'myCache'})
    *
-   * @param args {(ServerAddress|ServerAddress[])}
+   * @param {(ServerAddress|ServerAddress[])} args
    * 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}
+   * @param {ClientOptions=} options
    * Optional configuration settings.
    * @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) {
@@ -891,7 +1340,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 +1367,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: {