Repository navigation
Proposal: optionally declared variables #23602
Description
Scenario
When writing code that will run in both Node.js and browser environments (e.g. a React component compatible with SSR), it's sometimes necessary that part of the code only executes in one environment and not the other.
A few browser-only examples:
document.querySelector()to find an element in the DOM.document.title = "new title"to update the page title.
To avoid executing these in Node.js, the following pattern is used:
if (typeof document !== "undefined") {
// Safely use `document`.
document.title = "new title";
}Now the developer needs to configure TypeScript to include the types for document. It basically boils down to them deciding whether or not to include dom in the lib compiler option.
(dom.d.ts is distributed with TypeScript and includes:)
declare var document: Document;Unfortunately both options have compromises:
- don't include it and
documentwon't be declared, and TypeScript will warnCannot find name 'document'. - do include it and
documentwill be declared as aDocument, but not asDocument | undefined, sostrict-type-predicateswill complain that the check is unnecessary
A motivated developer may choose to fork dom.d.ts and add | undefined to all of the global variable declarations, and satisfy strict-type-predicates.
However one final piece of safety is still missing: ensuring typeof document !== "undefined" is used, rather than document !== undefined. At runtime if document (or any name) isn't declared, and is used outside typeof, a ReferenceError is thrown. For this reason it's necessary to always choose typeof when performing environment "sniffing".
TypeScript currently cannot model "optionally declared variables", where a variable "might" be declared. Without this, TypeScript doesn't have enough information to warn about code that may throw ReferenceError.
Proposal
Introduce new syntax and type system concepts to allow the "optional declaration" of variables. Emit would be unaffected.
Proposed syntax:
declare? var window: Window;This is distinct from:
declare var window: Window | undefined;In the first case, it's describing that window may not be declared, and referencing window may throw a ReferenceError. In the second case, window is always declared, but might have the value undefined.
Implementation:
- The grammar would need to be extended to match
?followingdeclare. - The AST would need a representation (e.g. a flag for
DeclareKeywordor a newOptionalDeclareKeyword). - The type system would need to track if a variable is optionally-declared, and support type-narrowing to a standard variable via
typeofguards. - For this to actually be useful, the type checker should warn if "optionally declared" variables are referenced.
- If a variable is "optionally declared", that information should be included in the string representation (e.g.
declare? var document: Document), e.g. when hovering a name in VS Code.
Shortcomings:
- It would be convenient if a single
typeof window !== "undefined"guard could safely grant access to other browser globals (e.g.document,performance, etc). This current proposal would require separatetypeofchecks for each global.
Activity
mhegazy commentedon Apr 21, 2018
So the expectation here is that lib.d.ts would have
windowdeclared conditionally; this means that every app written for web has to check for the existence ofwindow. I do not think this is reasonable.that said, the proposal itself has merit. I would just say the
?should be after the var name and not thedeclaremodifier.estaub commentedon Apr 22, 2018
Mohamed Hegazy (@mhegazy) I'm not sure, but I believe the semantics need to be different from e.g.
window?. In the proposal's case, the variable may not exist as a reference at all. In thewindow?case, the variable is guaranteed to exist as a reference (whose value may be undefined). Of course, the guarantee is false (sometimes) when used withwindow, hence the proposal for a language element with different semantics.Having said that... while I think the proposal is good within its scope, I don't think it's very important, relative to https://github.com/Microsoft/TypeScript/issues.
bradleyayers commentedon Apr 23, 2018
I agree. I would expect this proposal would be used to create a derivative versions of
dom.d.tsor@types/nodedeclaration files that could be used by projects with these target environments.The derivative versions could be created by a script that rewrites
.d.tsfiles to use optional declarations.Putting it after the name would be more consistent with existing syntax, so I can see the benefit of that. I'm curious if the semantic differences with optional interface fields would be undesirable.
declare var window?: Windowwould mean either:Window(i.e. neverundefined)Compared to an optional interface field
barin `interface IFoo { bar?: Bar } which is:undefined, orBarPerhaps because since a
ReferenceErrorwould never be thrown in the interface scenario, the difference is inconsequential.estaub commentedon Apr 23, 2018
Consider the difference in meaning for optional function parameters as well.
mhegazy commentedon Apr 23, 2018
Possibly another use case of
missingfrom #13195ganeshkbhat commentedon Jul 11, 2018
You could have or add something like this as well:
declare? var Worker: Worker || var PseudoWorker: any;Reference:
#25570
bradleyayers commentedon Feb 3, 2019
I believe I'm going to be satisfied with #29332 and a lint rule to ban global access for things like
window(so that bothtypeof windowandwindow !== undefinedwould be banned). I expect instead I'll write code as: