Adding a types folder to inform decisions about generated/incoming data

[tkshill]

Is there an existing issue for this?

• I have searched the existing issues

Issue Context

While working on issue #693 and putting up the subsequent #720 I noticed that we ended up in a particular pattern:

• We have a _generatedData/ folder where we put .json files with necessary runtime data for the application.
• Typescript will attempt to infer the data type from the imported json. It may be wrong, because the current state of the file does not cover the full domain of the data
  For example, in the case of buildUrls.json, the data frequently has the shape

type BuildUrls = {"URL":"http://localhost:9000"}

Typescript will determine that the type of buildUrls to be

{ URL: string }

But we know in the actual usage it's shape should be more like

type BuildUrls = {
	URL: string;
	NETLIFY?: string;
	CONTEXT?: string;
	DEPLOY_PRIME_URL?: string;
};

• This isn't discoverable when the json type is imported as a module, developers would need to add this type (and have this context) whenever they use the data if they want correct type info.

Proposed solution

• We can put type info in the file consuming the data which is fine but it'd be nice when folks import the data the correct type come attached.
• It could be worth making a dedicated types file for this and other externally sourced json data so developers have the correct type data when they import the json file as a module?
• We would a typings.ts or typings.d.ts file in the src/ folder containing the necessary type info.

declare module 'app/_generatedData/buildUrl.json' {
	URL: string;
	NETLIFY?: string;
	CONTEXT?: string;
	DEPLOY_PRIME_URL?: string;
};

As long as that file in included in our .tsconfig folder, we would get the correct info whenever someone does

import * as buildUrl from 'app/_generatedData/buildUrl.json';

• There could be a general use for using this file wherever we find ourselves casting types from json files.
• It moves the type information for external json to a fixed location rather than scattered throughout the project.

Alternatives Considered

We could also just not do this; a downside is type information consequently leaves the space where it's used. Arguably, this has less benefit if a piece of data is only used in one place, and most of ours still is, currently. It may be me wanting to do a neat thing, but not a needed thing.

Additional Resources

Stackoverflow that describes the idea/solution a bit more

Code of Conduct

• I've read the Code of Conduct and understand my responsibilities as a member of the Virtual Coffee community