Support for Filter.toString()? about node-ldapjs

[jsumners]

Don't these statements contradict each other? 🤔

No, the docs reside in docs/. We control those. They should be updated to resolve #909.

At some point we need to get in contact with Joyent to determine what can be done about the website. But right now, I just don't have the money or time to do so.

[jsumners]

The undocumented Filter.toString()

It is documented, albeit sparsely (really not much to say about it): https://github.com/ldapjs/filter/blob/e70a7cba6c17310956e87a9b28e6bea61db48d93/lib/filter-string.js#L87-L94

"sub" prefix because it's not officially part of the api.

What do you mean? While the accessors do not have explicit documentation (https://github.com/ldapjs/filter/blob/e70a7cba6c17310956e87a9b28e6bea61db48d93/lib/filters/substring.js#L60-L70) they are transitively documented at https://github.com/ldapjs/filter/blob/e70a7cba6c17310956e87a9b28e6bea61db48d93/lib/filters/substring.js#L19-L30.

Should I not mess with Filter.toString() or is this something that ldapjs could support?

All methods on the various objects that do not start with an _, or are otherwise documented as private, should be considered part of the public API.

From a quick look at the other filters it seems that .toString() already works just fine for the rest of them.

Correct. All subclasses of FilterString support .toString(), as the objects are meant to represent strings 😄, with customizations as appropriate for the specific filter type.

[simon-lorenz]

Hm, that's weird. If I check the type definitions, I get the following:

declare class Filter {
    matches(obj: any): boolean;
    type: string;
}

// [...]

export class SubstringFilter extends Filter {
    constructor(options: {
        attribute: string;
        initial: string;
        any?: string[] | undefined;
        final?: string | undefined;
    });
}

No mention of .toString() nor the "sub" prefixes. The latter are also not mentioned in the example. That's why I considered them sortof private. :-)

I'm a bit confused about the "sub" prefix in general. Why is it there? And why does the example on the website omits the prefix if this breaks .toString()? Is this a bug? It also seems that .matches() always returns true when the prefix is omitted:

import ldapjs from 'ldapjs'

const { SubstringFilter } = ldapjs

const f = new SubstringFilter({
	attribute: 'cn',
	initial: 'foo',
	any: ['bar', 'cat'],
	final: 'dog'
})

console.log(f.matches({ cn: 'foobarcatdog' })) // -> true
console.log(f.matches({ cn: 'thisshouldprobablynotmatch' })) // -> true
console.log(f.matches({ cn: '' })) // -> true
console.log(f.matches({ cn: '123' })) // -> true

const f2 = new SubstringFilter({
	attribute: 'cn',
	subInitial: 'foo',
	subAny: ['bar', 'cat'],
	subFinal: 'dog'
})

console.log(f2.matches({ cn: 'foobarcatdog' })) // -> true
console.log(f2.matches({ cn: 'thisshouldprobablynotmatch' })) // -> false
console.log(f2.matches({ cn: '' })) // -> false
console.log(f2.matches({ cn: '123' })) // -> false

[jsumners]

If I check the type definitions

We don't supply any such things.

The latter are also not mentioned in the example.

The documentation should be updated.

I'm a bit confused about the "sub" prefix in general. Why is it there?

🤔 I don't have a good answer for this one. My best guess is that I read https://ldap.com/ldapv3-wire-protocol-reference-search/#search-request in which the following is stated:

The substrings filter (also called a substring filter) can be used to match an that has a specified attribute with at least one value that matches a provided substring assertion. The substring assertion can contain one or more of the following components:

An initial component (sometimes called subInitial), which will match a value that starts with a specified string.
An any component (sometimes called subAny), which will match a value that contains a specified string.
A final component (sometimes called subFinal), which will match a value that ends with a specified string.

I believe this happened early in the v3 development cycle (June of 2022) ldapjs/filter@d8eb54a. I may not have been following the spec so closely at that time, and that was a mistake. I'd say we should update @ldapjs/filter to deprecate the subX fields in favor of the spec defined fields:

https://www.rfc-editor.org/rfc/rfc4515#section-2

SubstringFilter ::= SEQUENCE {
type AttributeDescription,
-- initial and final can occur at most once
substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE {
initial [0] AssertionValue,
any [1] AssertionValue,
final [2] AssertionValue } }

And why does the example on the website

The website is not under our control.

It also seems that .matches() always returns true when the prefix is omitted:

Because the current implementation works as described above.

[simon-lorenz]

We don't supply any such things.

Oh, I see! I was wondering where that index.d.ts file comes from. Took a bit of googling to understand that it originates from DefinitlyTyped. That clears a lot of my confusion.

I'm still wondering why these types exist on my system, since I didn't install @types/ldapjs and they seem to override the correct jsdoc annotations in intellisense (EDIT: TIL about Automatic Type Aquisition)... But that's my problem 😃

The documentation should be updated.
[...]
The website is not under our control.

Don't these statements contradict each other? 🤔

Deprecating the subX fields in favor of the more spec compliant fields seems like a good idea.

[jsumners]

Closing because I believe this is resolved. If not, please reopen.