docs updated for 0.5

docs/client.md

@@ -27,32 +27,34 @@ client is:
 
 ||url|| a valid LDAP url.||
 ||socketPath|| If you're running an LDAP server over a Unix Domain Socket, use this.||
-||log4js|| You can optionally pass in a log4js instance the client will use to acquire a logger.  The client logs all messages at the `Trace` level.||
+||log|| You can optionally pass in a bunyan instance the client will use to acquire a logger.  The client logs all messages at the `trace` level.||
 ||timeout||How long the client should let operations live for before timing out. Default is Infinity.||
 ||connectTimeout||How long the client should wait before timing out on TCP connections. Default is up to the OS.||
-||reconnect||Whether or not to automatically reconnect (and rebind) on socket errors. Takes amount of time in millliseconds. Default is 1000. 0/false will disable altogether.||
+||maxConnections||Whether or not to enable connection pooling, and if so, how many to maintain.||
+
+If using connection pooling, you can additionally pass in:
+
+||bindDN||The DN all connections should be bound as.||
+||bindCredentials||The credentials to use with bindDN.||
+||checkInterval||How often to schedule health checks.||
+||maxIdleTime||How long a client can sit idle before initiating a health check (subject to the frequency set by checkInterval).||
 
 ## Connection management
 
 As LDAP is a stateful protocol (as opposed to HTTP), having connections torn
-down from underneath you is difficult to deal with. As such, the ldapjs client
+down from underneath you is difficult to deal with.  That said, the "raw"
-will automatically reconnect when the underlying socket has errors.  You can
+client, which is what you get when maxConnections is either unset or <= 1, does
-disable this behavior by passing `reconnect=false` in the options at construct
+not do anything for you here; you can handle that however you want.
-time, or just setting the reconnect property to false at any time.
 
-On reconnect, the client will additionally automatically rebind (assuming you
+More commonly, you probably want to use connection pooling, which performs
-ever successfully called bind).  Only after the rebind succeeds will other
+health checks, and while you will see occasional errors from a client, those
-operations be allowed back through; in the meantime all callbacks will receive
+will be highly transient, as the pooling logic will purge them and create new
-a `DisconnectedError`. If you never called `bind`, the client will allow
+ones for you.
-operations when the socket is connected.
 
-Also, note that the client will emit a `timeout` event if an operation
+It is highly recommended you just provide bindCredentials initially, as all
-times out, and you'll be passed in the request object that was offending. You
+clients used will be authenticated, but you can call `bind` at any given time.
-probably don't _need_ to listen on it, as the client will also return an error
+This is expensive though, as the pool must first drain, be destroyed, and then
-in the callback of that request.  However, it is useful if you want to have a
+recreated.  So try not to do that.
-catch-all.  An event of `connectTimout` will be emitted when the client fails to
-get a socket in time; there are no arguments.  Note that this event will be
-emitted (potentially) in reconnect scenarios as well.
 
 ## Common patterns
 

docs/server.md

@@ -19,7 +19,7 @@ The code to create a new server looks like:
 
 The full list of options is:
 
-||log4js||You can optionally pass in a log4js instance the client will use to acquire a logger.  You'll need to set the level to `TRACE` to get any output from the client.||
+||log||You can optionally pass in a bunyan instance the client will use to acquire a logger.||
 ||certificate||A PEM-encoded X.509 certificate; will cause this server to run in TLS mode.||
 ||key||A PEM-encoded private key that corresponds to _certificate_ for SSL.||