Lack of TypeScript null safety

[lionel-rowe]

Article URL

https://github.com/OfficeDev/office-scripts-docs-reference/blob/main/generate-docs/script-inputs/excel.d.ts

Issue

Office Scripts TypeScript types provide no null safety — mostly not clear where nulls are/aren't allowed or occur:

• Many return values might be null, but not typed as such. Often this is documented in JSDoc, but not reflected in the types. For example, DataValidation#getValid is typed () => boolean, whereas it's really () => boolean | null.
• Many parameters are nullable, but not typed as such. For example, the extremely useful Table#setPredefinedTableStyle(null) to remove all table styles is completely undocumented (parameter is typed as string).

• The inline Code Editor in Excel also provides no null safety. For example:

  const nullable = Math.random() > 0.5 ? 1 : null
  nullable.toString()

  Here, nullable is typed as 1, and nullable.toString() will throw a runtime error 50% of the time.

  Presumably this is a tsconfig issue, so maybe outside the scope of documentation, but seems the issues are related.

[AlexJerabek]

Hi @lionel-rowe,

Thanks for reporting this. This appears to be a widespread issue here and with the Office JS APIs that sit underneath the Office Scripts API. @gergzk and I will start investigating a fix for both the type definitions and the documentation, though it will likely take some time.

[AlexJerabek]

While we acknowledge this issue, there is no timeline for a complete fix. We will be updating individual APIs to indicate null and undefined behavior as we are able. I'm closing this issue to reflect this level of investment.