chore: reformat code globally

[kaljarv]

Harmonize code formatting globally:

1. Import statements and curly brace spacing
2. Import ordering
3. Convert string unions to Enums
4. Comments
   1. Remove non-paragraph line breaks from comments
   2. Remove @default statements from @component docstrings because they break the IDE layout
5. Naming conventions
6. Consider changing all explicit undefineds to nulls if this is the recommended approach. At least, null is compatible with JSON, which is a plus.
   1. This may require globally changing optional Svelte component properties to accept null and undefined, which ought to be checked as well.
   2. MISSING_ANSWER is now defined as undefined (pun not intended) in vaa-matching, but null might be a better option because of JSON compatibility.
7. Check all cases where setTimeout is used to wait for DOM updates and see if those can be converted to use tick.
8. Convert components events to use Svelte-5-style callback props instead of eventDispatcher.

[kaljarv]

A way to start is to look at the style guides of existing OS projects (with TS)

[norppaa]

Undefined vs null

It seems that the convention in TypeScript is that undefined values have not been defined yet, whereas null values indicate intentional absence of a value. Therefore, I would not just change all undefineds to null, because they have different meanings.

Some sources say that the use of undefined is recommended and null is discouraged (all these cite the coding guidelines for contributors of typescript but this does not necessarily mean that projects made with typescript should only use undefined). Many seem to prefer using only undefined.

Some also argue, that you should not assign undefined to any value, because it is easier to debug programs if you know that if you get undefined it was because the variable never got set. Null indicates a variable that is empty or contains nothing (but has type etc)

https://www.reddit.com/r/typescript/comments/11dpu05/undefined_vs_null/

I could not really find any repos or style guides that take a stand on what should be used. Google and ts.dev styling guide both say that many js apis use undefined and many dom and google apis use null, so the appropriate value depends on the context.

See also TS Style Guide.

Enums vs string unions Why is it not good to use enums comparison

Why use string literals:

• Numeric enums are not type safe
  • You can assing any nymber to numeric enums
• Declarations of string enums can be redundant
• Enums are compiled to js, thus increasing the bundle size
• No need to duplicate key and value with string unions. With enums this is probable atleast in some cases
• No import needed in string union
• String unions can be used directly
• The TS Style Guide linked below forbids Enums

Why use Enums:

• Quicker to refactor (F2 vs find and replace)
• Can be marked as deprecated
• Helpful when values are not self explanatory
• Work well for logical references

Different ways to use enums so that they safe typesafety

[norppaa]

Quite extensive type-script style guide

[kaljarv]

The style guide looks like something we could adopt, although these rules might need discussion:

• https://mkosir.github.io/typescript-style-guide/#type-definition
• https://mkosir.github.io/typescript-style-guide/#array-types
• https://mkosir.github.io/typescript-style-guide/#general
  • The no side effects rule might not be very easy to follow in component event and lifecycle handlers, although we should try to prefer reactive updates for these
• https://mkosir.github.io/typescript-style-guide/#args-as-discriminated-union
  • This seems to sometimes cause linter issues if used for component properties, but could be enforced for functions proper
• https://mkosir.github.io/typescript-style-guide/#naming-conventions
  • The boolean naming convention could otherwise be followed, but we often want to use HTML attribute names for the matching properties to use the Svelte <button {disabled}> shorthand.

We might need some automatic type generation for services and the like, e.g. Strapi types and translations. It'd be worthwhile to investigate how this can be best achieved.

[anolpe]

• https://mkosir.github.io/typescript-style-guide/#type-definition

Do we have lot of cases where we have to use interfaces?

• https://mkosir.github.io/typescript-style-guide/#array-types

I think I often use string[] but I don't have a strong preference.

• https://mkosir.github.io/typescript-style-guide/#args-as-discriminated-union
  • This seems to sometimes cause linter issues if used for component properties, but could be enforced for functions proper

What kind of linter issues?

• https://mkosir.github.io/typescript-style-guide/#naming-conventions
  • The boolean naming convention could otherwise be followed, but we often want to use HTML attribute names for the matching properties to use the Svelte <button {disabled}> shorthand.

Agree, and in those cases it's pretty clear that those are boolean.

[kaljarv]

• https://mkosir.github.io/typescript-style-guide/#type-definition Do we have lot of cases where we have to use interfaces?

Not necessarily that many, and most all can be converted into types. Possible contexts where interfaces are needed are:

• external api typing, e.g. for Strapi
• vaa-matching and vaa-data models where we want to only dictate the minimum requirements for the objects they accept, but maybe these could still be types…

• https://mkosir.github.io/typescript-style-guide/#array-types I think I often use string[] but I don't have a strong preference.

Me too :D, but I'm starting to think that Array<string> might be preferable because it's easier to distinguish from string. An added benefit is a less messy initialisation for empty typed arrays:

const foo = new Array<Bar>();
// vs.
const foo: Bar[] = [];

• https://mkosir.github.io/typescript-style-guide/#args-as-discriminated-union
  • This seems to sometimes cause linter issues if used for component properties, but could be enforced for functions proper What kind of linter issues?

I had such a discriminated construction for the ButtonProps type in $lib/compontents/icon, which only allowed for some values of iconPos for some variants. It was easy enough to describe in the interface, but then on some pages where the component is used with variables as the values for these properties, the linter would rightly complain it couldn't be sure the combination was correct. In theory, this could be worked around but that seemed a bit complicated, but it would ensure correct usage on the other hand 🤔 . E.g.

let foo: ButtonProps['variant'];
let bar: ButtonProps['iconPos'];

// Set values here

// This will still be bad, because we don't know if `foo` and `bar` are compatible
<Button variant={foo} iconPos={bar}/>

// Could be possibly worked around this way or so
let props: Partial<ButtonProps> = foobar
  ? { variant: 'iconAnywhere', iconPos: 'left' } 
  : { variant: 'iconOnlyRight', iconPos: 'right' };

<Button {...props}/>

[kaljarv]

• https://mkosir.github.io/typescript-style-guide/#type-definition .- Let's prefer types but use interfaces where it's the simpler option, such as in separate module's definitions of acceptable inputs
• https://mkosir.github.io/typescript-style-guide/#array-types
  • Let's adopt this rule.
• https://mkosir.github.io/typescript-style-guide/#general
  • The no side effects rule might not be very easy to follow in component event and lifecycle handlers, although we should try to prefer reactive updates for these
• https://mkosir.github.io/typescript-style-guide/#args-as-discriminated-union
  • Let's adopt this and try if we can also use it in complex components, such as<Button>, but if it gets too fraught, we can make exceptions for components
• https://mkosir.github.io/typescript-style-guide/#naming-conventions
  • The boolean naming convention could otherwise be followed, but we often want to use HTML attribute names for the matching properties to use the Svelte <button {disabled}> shorthand.