Make Borgs mutable #39
Description
The immutability of Borgs has considerable performance implications - especially considering a copy is created on every method call in the chain.
The original rationale was to allow Borg reusability. If a .required() Borg is desired in one place, and the same Borg is mutated somewhere else to be .optional(), the first case might then allow undefined values if that parse occurs after the mutation.
While immutable Borgs are certainly ergonomic, an escape hatch should exist allowing users to configure the Borg's mutability. I've considered two options (better names are needed, especially for the latter option):
Make Borg's mutable by default and provide a .lock() method. - This would be a breaking change, and make performance optimization opt-out. The idiomatic approach to re-use would be to call .copy() before any other methods when reusing a Borg, to insure the original is not mutated, or to call .lock() on a Borg if it should never be mutated. When .lock() is called, the next method call in the chain returns a copy. This copy is mutable, and subsequent calls mutate the copy until .lock() is called again and a new copy is returned. This introduces more boilerplate - one would need to call .lock() and .copy() quite often. On the upside, it decreases complexity in the tooltip by eliminating the need to denote the Borg's mutability state. An explanation would be provided in the docs and in the tooltip explaining these semantics.
Keep Borgs immutable by default and introduce .unsafe() - This would make performance optimization opt-in. The current behavior would remain, and a new method would be introduced which causes all subsequent calls to mutate the Borg until the inverse method is called (.safe(), .lock(), or something like that). This introduces more boilerplate in cases where performance optimization is desired, and it would require a new hint in the tooltip to denote the Borg's mutability. If the performance of the library is poor even for regular consumers, and optimization is desired in the majority of cases, the former option may be a better candidate. Docs and tooltips would document the meaning of unsafe, and a section would be added to the docs titled "performance optimization".
This is probably a post-1.0 issue.