[@zeit/title_v3.4.x] Add definitions

[pascalduez]

• Links to documentation: https://github.com/zeit/title
• Link to GitHub or NPM: https://github.com/zeit/title
• Type of contribution: new definition

[villesau]

No any blockers, just suggestions. Would perhaps be good to encourage some "best practices" regarding immutability, exactness etc.

[pascalduez]

Would perhaps be good to encourage some "best practices" regarding immutability, exactness etc.

I'm all for this.

Just wondering in this particular case whether it's that useful. Let's say one wants to reuse and mutate on options object.

let options = { specials: [''] };

title('', options);

options.specials.push(''); // Error

title('', options);

So we enforce immutability here, which is a good thing I guess.

let options = { specials: [''] };

title('', options);

let newOptions = { specials: [...options.specials, ''] };

title('', newOptions);

[villesau]

It actually will not error, see: https://flow.org/try/#0PTAEAEDMBsHsHcBQiAmBTAxtAhgJzaJAK4B2GALgJawmjloDO5AFJSQA5HkBcoAJACU02FAHkS0AJ4BBXLmySAPCSIBbAEZpcAPgCUvAG6xKKANzIMNJqDy5QAXlABtALrnbAOk4MAFswCMAEwAzLrm9EzMtmFAA

Taking in immutable types ensures that the value is not mutated inside the function. If you take in mutable types, you can't pass immutable values to it: https://flow.org/try/#0PTAEAEDMBsHsHcBQiAmBTAxtAhgJzaJAK4B2GALgJawmjloDO5AFJSQA5HkBcoAgrlzYAngB4SRALYAjNLgB8ASl4A3WJRQBuZBhpNCtALyhmeXLwAkAJTTYUAeRLRhAoWIky5S0IfmgA3ogAkPRMpoKK2gC+iEA

So the benefit of defining immutable types is that the function can take in immutable types (as well as mutable types, it just guarantees that they are not mutated).

Added mention of immutability and exactness: #3100

[pascalduez]

My test was like: https://flow.org/try/#0PQKgBAAgZgNg9gdzCYAoVAXAngBwKZgDyOGAlnAHYDOYAvGACQCiAHgIYDGGAPAN6pgwAair4OpNjCoAuRgCU8bACaEKMLAEEATlrZZuVDFtIUA5gD4ANKgC+5gNzoleDjDZaCUAK4Uu5CmBkGDB4ABSGWrIRJqaWYHAk-lQA-LLEZJRUAJRRRjGOqCEY8YmZdGC8YKIuElKyANoA5I0AumA2BUEhoc1xCRnUWQX9SQB01eKSVKM4XlQAFj2NQ+hAA

But in the libdef test I couldn't make it fail add to explicitly type it: let options: Options. 🤷‍♂️

[villesau]

I guess that's because Flow refines the type if no explicit type defined. If the type is explicitly defined, it does not error: https://flow.org/try/#0PQKgBAAgZgNg9gdzCYAoVAXAngBwKZgDyOGAlnAHYDOYAvGACQCiAHgIYDGGAPAN6pgwAair4OpNjCoAuRgCU8bACaEKMLAEEATlrZZuVDFtIUA5gD4ANKgC+5gNzoleDjDZaCUAK4Uu5CmBkGDB4ABSGWrIRJqaWYHAk-lQA-LLEZJRUAJRRRjGO2PhEiZkATHSMrJw8-IKiLhJSstq6+tFmVrYO6ByZGGBQAfShCRnUaSXUpVl05mC1gaTBYQDkK3GjSVmOgpuZAHT14pJU+zheVAAWoWvbtugPQA