fix: use Record for properties field in Schema Object

[vaibhavrajsingh2001]

Using mapped types like { [propertyName: string]: SchemaObject | ReferenceObject } doesn't ensure the key to be of type string. Instead, TypeScript interprets the key as string | number.

This behaviour can be verified in the following playground

Due to this issue, if you iterate over the properties of a schema, TypeScript can't be sure that the key is of type string. Instead the key will be interpreted as of type string | number.

Using a Record allows to strictly type the key to only be of type string, which can be verified here

It's a known TypeScript issue microsoft/TypeScript#48269

[vaibhavrajsingh2001]

Hey @pjmolina, came across this issue while I was trying to iterate over the properties field of a SchemaObject.
Would appreciate a review here 🙏.

[remidewitte]

I would suggest : Record<string, SchemaObject | ReferenceObject | undefined>

[vaibhavrajsingh2001]

I don't think the value of any field in properties can ever be undefined.

In YAML spec files, If no value is assigned to a field in properties, Swagger automatically treats the field as of type any.

However, in JSON format, it's not allowed to assign an undefined value to a filed in properties

[vaibhavrajsingh2001]

In the worst case, it'll be an empty object, which again is a valid SchemaObject

[vaibhavrajsingh2001]

@remidewitte do you think undefined would be needed here?

[RobinTail]

Properties assigned with undefined are not exported to YAML and JSON at all.

console.log(
  yaml.stringify({
    property: undefined,
  }),
);

console.log(
  JSON.stringify({
    property: undefined,
  }),
);

{}

{}

Therefore, the only benefit for adding undefined is for conditional properties:

yaml.stringify({
  property: isIncluded() ? "something" : undefined
});

But that condition can be implemented differently, without involving undefined at all:

yaml.stringify({
  ...(isIncluded() ? {property: "something"} : {})
});

[RobinTail]

with noUncheckedIndexedAccess enabled, @remidewitte

https://www.typescriptlang.org/play/?noUncheckedIndexedAccess=true#code/MYewdgzgLgBCBGArAXDASgU1AJwCYB5psBLMAcwBoYBvbDAM1SNLIF8A+GAXhtYG4AUANCRYUDNG5wkAOnHQZdeoIHF6MABQAieVC0xS0xAEoaAmBZgjJuqQkRyJURQ0GsgA

without it:

https://www.typescriptlang.org/play/?#code/MYewdgzgLgBCBGArAXDASgU1AJwCYB5psBLMAcwBoYBvbDAM1SNLIF8A+GAXhtYG4AUANCRYUDNG5wkAOnHQZdenyA

[remidewitte]

OK excellent.

[vaibhavrajsingh2001]

So, should I update the types to Partial<Record<string, SchemaObject | ReferenceObject>>?

[RobinTail]

@vaibhavrajsingh2001 , Taking into account the concept and the goal of this package:

TypeScript library to help building OpenAPI 3.x compliant API contracts.

I'd say: there are more benefits in Partial<> than any harm.

Under the hood Partial<> makes all properties optional ?:, while does not explicitly welcome undefined,
which can be assigned, but still there is no harm of that — it will not go further (JSON and YAML stringifiers remove it). It's helpful both for conditional writing and for avoiding runtime errors while reading, like in the @remidewitte 's case

[vaibhavrajsingh2001]

Updated the PR @RobinTail @remidewitte

[pjmolina]

I have contradicting feelings here:

• We cannot fix TS or JS here (clearly out of scope)
• Having a string key in dictionary does not prevent for accessing the keys by index (JS semantics) nor we should forbid it.
• If we fix this one, we should be coherent and fix all dictionary-like access we use.

To be honest, not sure if it is makes worthy. And if we are breaking uses cases for anyone else.