Provide searchSync and loadSync functions, instead of the sync option

I was reviewing the documentation, then poking around in the code a little bit, wondering if things could be simplified —— and I’m thinking that the challenges we have in documenting and Flow-typing functions, because they can be sync or async based on an option, indicates a flaw that we should refactor out.

Instead of the sync option, we could have explorer.searchSync and explorer.loadSync functions. Internally, we’d do the same thing with our utility functions. I believe that the standard practice across Node is to provide separate functions for sync and async versions of the same behavior — instead of overloading a single function. This results in each function having a cleaner signature, which is easier to document, type check, unit test.

Does anybody object? If not, I will work on this refactoring and the new functions before our v5 release.

[davidtheclark]

But should it be searchSync or search.sync?

I believe that the reason libraries go with fn (async) and fn.sync is because of how CommonJS works: that way the module can have one main export, the default function that people should use most of the time, instead of exporting an object. So you get fn and fn.sync instead of SomeModule.fn and SomeModule.fnSync.

That situation doesn’t apply to us, so I favor the searchSync convention.

[davidtheclark]

Documented now in the v5 branch.