The client API is callback- and event-based. This page summarizes the core operations verified against ldapjs-community@2.4.0; consult the upstream client reference for exhaustive option and event details.
Link to Create a clientCreate a client
const ldap = require('ldapjs')
const client = ldap.createClient({
url: process.env.LDAP_URL,
connectTimeout: 5000,
timeout: 10000,
reconnect: false
})
client.on('error', (err) => {
console.error('LDAP client error:', err)
})
The source-backed options include url, socketPath, log, timeout, connectTimeout, tlsOptions, idleTimeout, strictDN, and reconnect. Register an error listener because the client is an EventEmitter.
url accepts one URL or an array of URLs. Array entries are tried in order. reconnect accepts true or an object with initialDelay, maxDelay, and failAfter; after a reconnect, the application may need to bind again before making authenticated requests.
Client lifecycle events include connect, connectError, connectRefused, connectTimeout, setupError, socketTimeout, resultError, timeout, idle, end, close, and destroy. Use the events your application can act on rather than treating every event as interchangeable.
Link to Controls and callbacksControls and callbacks
The optional controls argument accepts one Control instance or an array of controls. Most operation callbacks receive (error, response). compare additionally reports whether the value matched, while exop reports the returned value before the response object. See the upstream reference for exact overloads.
Link to Core operationsCore operations
| Operation | Signature | Purpose |
|---|---|---|
| Bind | bind(dn, password, controls?, callback) | Perform a simple bind. |
| Add | add(dn, entry, controls?, callback) | Add a directory entry. |
| Compare | compare(dn, attribute, value, controls?, callback) | Compare one attribute value. |
| Delete | del(dn, controls?, callback) | Delete an entry. |
| Extended operation | exop(name, value?, controls?, callback) | Send an LDAP extended operation. |
| Modify | modify(dn, changes, controls?, callback) | Apply one or more Change objects. |
| Modify DN | modifyDN(dn, newDN, controls?, callback) | Rename or move an entry. |
| Search | search(base, options, controls?, callback) | Start an event-driven search. |
| Abandon | abandon(messageId, controls?, callback) | Ask the server to abandon an outstanding request. |
| StartTLS | starttls(options, controls?, callback) | Upgrade the current connection to TLS. |
| Unbind | unbind(callback?) | Send unbind and disconnect. |
| Destroy | destroy(error?) | Disconnect and prevent future reconnection. |
Link to BindBind
client.bind(process.env.LDAP_BIND_DN, process.env.LDAP_PASSWORD, (err) => {
if (err) throw err
console.log('Bound')
})
The client reference documents simple binds. Protect credentials with LDAPS or StartTLS.
Link to SearchSearch
search returns a response emitter through its callback. Listen for entries, referrals, errors, and completion:
client.search(process.env.LDAP_BASE_DN, {
scope: 'sub',
filter: '(objectClass=person)',
attributes: ['dn', 'cn', 'mail']
}, (err, response) => {
if (err) throw err
response.on('searchEntry', (entry) => console.log(entry.object))
response.on('searchReference', (referral) => console.log(referral.uris))
response.on('error', (searchError) => console.error(searchError))
response.on('end', (result) => {
console.log('LDAP status:', result.status)
client.unbind()
})
})
Search options include scope, filter, attributes, attrsOnly, sizeLimit, timeLimit, and paged. See the complete search example for a runnable flow.
The response also emits searchRequest after a request is sent. Its messageID can be passed to client.abandon(). Search error events cover client or transport failures; LDAP result status is reported by end, so check result.status before treating the search as successful.
Link to PagingPaging
Set paged: true for automatic paging, or pass { pageSize, pagePause }. A paged response emits page after each page. With pagePause: true, the event receives a callback; call it when the application is ready for the next page.
Link to ModifyModify
const change = new ldap.Change({
operation: 'replace',
modification: { displayName: ['Ada Lovelace'] }
})
client.modify(process.env.LDAP_ENTRY_DN, change, (err) => {
if (err) throw err
client.unbind()
})
Change.operation accepts the operations documented upstream: add, delete, or replace.
Link to Disconnect and cleanupDisconnect and cleanup
unbind() sends the LDAP unbind operation and disconnects; it is not the inverse of bind, and its callback is optional because LDAP sends no unbind response. Use destroy() when the connection has failed or the client must not reconnect.