style.md

Style Preferences

Declare when needed

• Declaring variables close to where they're used limits their scope, reducing the cognitive load.

Use JSDoc for documentation

• Use JSDoc for documentation (description, @todo, @returns, @param).
• Use normal comments for implementation details.

Prefer function declarations for named functions

• Function declarations are clearer and hoistable.
• Prefer arrow functions for callbacks since they are simpler and bind this.

Avoid default exports

• Non-default exports add type-safety.
• Exception: If the filename matches the export name, default exports can be used since they stand out and the syntax is cleaner.

Use Readonly to ensure immutability

• Marking parameters and state variables as readonly ensures immutability.

Avoid positional parameters of the same type

• Positional parameters of the same type are easy to mix up.

Prefer a distinct type for failure

• Using a distinct type for failure makes the failure obvious.
• Prefer null over undefined to ensure the failure is handled even with optional parameters.

Make illegal states unrepresentable and prefer precise types or brands

• Making illegal states unrepresentable, precise types and brands increase confidence and type safety, and reduce implementation complexity.
• Note: Big unions might hurt performance.

Make argument types as generic as possible

• Using a more generic argument type, as long as it doesn't affect the implementation, is more convenient.