# Documentation and guides

## Usage

```javascript
const LDAP = require('openldapjs').Client;
```
After installing it in your project, and assuming that you have access to a functioning LDAP server, the library can be used as following:

```javascript

/* creates a new ldap client instance with the host address your_ldap_host_address */
/* There is an optional parameter timeLimit for setting the maximum amount of time the server should take in responding for a operations */
/* The default value is 10 */
const ldapClient = new LDAP('your_ldap_host_address'); // E.g: ldap://192.168.0.1:389 or ldaps://example.com


/* in order for the client to be usable, it has to be initialized and bound with a user DN and a password */
/* The anonymous users(unbound) can only use  the ldap extended operation */
ldapClient.initialize()
    .then(() => {
       return ldapClient.bind('validDn','password')
    })
    .then(() => {
        //after the client is initialized and bound, you can add,search,etc.
    })
    .catch((customError) => {
        //custom errors have a description and a code field that you can inspect
    })

```


## Functions and  tools

Most functions that interact with the LDAP server are mapped using [Nan](https://github.com/nodejs/nan) from corresponding [Openldap](https://github.com/openldap/openldap) Asynchronous C functions. The javascript bindings to those functions return [Bluebird Promises](https://github.com/petkaantonov/bluebird).

The Async C functions are processed using [AsyncProgressWorkers](https://github.com/nodejs/nan/blob/master/doc/asyncworker.md). This prevents the event loop from blocking, delegating the heavy-lifting to the worker thread(Execute method) . Upon finishing, the result gets passed to node in the HandleOkCallback method.


* [LDAP Initialize ](./ldap_functions/initialize.MD)
* [LDAP Bind](./ldap_functions/bind.MD)
* [LDAP StartTls](./ldap_functions/startTls.MD)
* [LDAP Regular search](./ldap_functions/search.MD)
* [LDAP Paged Search](./ldap_functions/pagedSearch.MD)
* [LDAP Add](./ldap_functions/add.MD)
* [LDAP Delete](./ldap_functions/delete.MD)
* [LDAP Modify](./ldap_functions/modify.MD)
* [LDAP Rename](./ldap_functions/rename.MD)
* [LDAP Change Password](./ldap_functions/changePassword.MD)
* [LDAP Extended Operation](./ldap_functions/extendedOperation.MD)
* [LDAP Unbind](./ldap_functions/unbind.MD)

State Machine illustrating library usage:

![state machine](https://user-images.githubusercontent.com/22966207/35210587-81626eaa-ff5b-11e7-8ef2-ff0d932fe328.png)

## Error Handling

 All errors are handled using custom errors mapped from [LDAP error codes](http://wiki.servicenow.com/index.php?title=LDAP_Error_Codes#gsc.tab=0) ranging from 1-80. For more info, check [Errors](./errors.MD).



## FAQ

List of commonly asked questions


## References 

* [LDAP](https://www.ldap.com/getting-started-with-ldap)
* [OpenLdap documentation](https://www.openldap.org/doc)
* [OpenLdap library](https://github.com/openldap/openldap)
* [BlueBird](https://github.com/petkaantonov/bluebird)
* [LDAP Error Codes](http://wiki.servicenow.com/index.php?title=LDAP_Error_Codes#gsc.tab=0)
* [Nan](https://github.com/nodejs/nan)
* [RFC](https://tools.ietf.org/html/rfc4510)