lock.extend not well documented

[raijinsetsu]

We discovered today that code we have had in production for almost a year was faulty. This was because the lack of documentation on the extend method did not make it clear that it returns a brand new Lock instance.

Our code looked like this:

await someLongishProcess();
await lock.extend(5000);
await anotherLongishProcess();
await lock.extend(5000);

This works, most of the time, but not all the time. While diagnosing, I started reviewing the Redlock code and found that extend returns a new instance of a Lock. We are making a change to our code but would appreciate updating the documentation (ie. in the README.md and on the Typescript side) to indicate that the Promise returned by extend resolves with a NEW lock which takes the place of the old lock.

If you agree, I can certainly open a PR myself.

[raijinsetsu]

Just some more details.
https://github.com/mike-marcacci/node-redlock/blob/main/src/index.ts#L399

This indicates that it is a new Lock instance when we extend. The current doc in the README indicates it references the same lock, which is mostly true. What is different is the expiration. So, if you continue to use the original instance of the Lock to attempt to extend, you will likely see our issue which is the error indicating that the lock has already expired.

[mike-marcacci]

This is a really great point, and definitely something that we should clarify in the docs.