docs: consistently quote props for editing

[nickmccurdy]

Depends on #725

When using ArkType, users will frequently add characters like ? that need to be quoted, so we should quote props consistently when they are used.

[ssalbdivad]

Thanks for the suggestion! I agree there is some benefit to being able to make a prop optional by adding a single character, but I'm still not necessarily sure that's what we'd want by default everywhere in the codebase yet.

It also seems like adding consistent key quotes wouldn't help in a situation where someone defines a definition with no optional keys and then wants to make something optional, which would be a pretty common case.

I'm also considering allowing alternate optional key syntax in our upcoming release to help mitigate this problem (would be either key: "?string|number" or key: "string|number?" but still pondering that since it violates the 1:1 with TS and might give people bad intuitions about where "?" can be used and whether it belongs to the prop value or its key.

I will ponder this, any feedback would be welcome!

[nickmccurdy]

Thanks for the suggestion! I agree there is some benefit to being able to make a prop optional by adding a single character, but I'm still not necessarily sure that's what we'd want by default everywhere in the codebase yet.

It also seems like adding consistent key quotes wouldn't help in a situation where someone defines a definition with no optional keys and then wants to make something optional, which would be a pretty common case.

I understand these assumptions aren't perfect, but I think they'd generally be helpful, especially for end users. I originally planned to just make this change in the docs. Would you be more comfortable with that?

I'm also considering allowing alternate optional key syntax in our upcoming release to help mitigate this problem (would be either key: "?string|number" or key: "string|number?" but still pondering that since it violates the 1:1 with TS and might give people bad intuitions about where "?" can be used and whether it belongs to the prop value or its key.

Good points here. Maybe it would be better to just have users explicitly add | undefined to types, especially since this already a common pattern in some TypeScript codebases (such as DefinitelyTyped which uses exactOptionalPropertyTypes). Alternatively the whole object could be put into a string template, but I'm not sure how to implement that and if it would be worth it in terms of architecture, performance, and type safety.

[ssalbdivad]

@nickmccurdy Right now the behavior mirrors TS, because adding "?" to a key just makes the key optional. During validation, it assumes exactOptionalPropertyTypes are enabled, and would still fail if you didn't include |undefined in the type.

Conversely, if you add |undefined to the type but don't make the key optional and it is not present, it would fail.

I'm sure it could be parsed but I think the DX would be much worse, and yes, probably a lot less efficient for TS.

I've thought a lot about the optional key syntax and keep coming back to just including it in the key as the best option, even though it's obnoxious. My fallbacks if I constantly get the feedback that it's frustrating would be one of the two alternatives I mentioned.

I don't think I want to quote all key strings by default, but this could perhaps be a setting we mention as an option for users frustrated with the setup as is.