FAQ Update 2024: The FAQ now attempts to only address content from people who end up filing GitHub issues.

This is not intended to be a representative FAQ for TypeScriptin general.

Listed here (with some synonyms) for easier Ctrl-F-ing

• Nominal types (tagged, branded):#202
• Negated types (not, exclusion, exclude, remove):#4196
• Exact types (sealed, final, closed, unopen):#12936

• Method and function signatures behave differently, specifically that narrower argument types are unsoundly allowed in subtypes of methods, but not functions. See "Why Method Bivariance?" on this page

Whilelib.d.ts has some built-in types such asPick,Omit,Exclude,ReturnType, etc., we are not accepting suggestions for adding new utility types.

Experience has taught us that defining utility types opens up a huge range of disagreement about very specific aspects of how these utility types should work, and once we ship a utility type, it's nearly always impossible to change it without causing many subtle breaks in user code.

Omits lack of key constraint is intentional. Many use cases for this type do not obey that constraint, e.g.:

typeMySpread<T1,T2>=T2&Omit<T1,keyofT2>;typeX=MySpread<{a:string,b:number},{b:string,c:boolean}>;letx:X={a:"",b:"",c:true};

You can write a user-spaceOmit type if you'd like to constrain the key.

We also recommend using these definitions of a user-sidePick andOmit if desired:

typePick_NewAndImproved<T,KextendskeyofT>={[PinkeyofTasK&P]:T[P];};// Optional: Add 'extends keyof T' constraint to KtypeOmit_NewAndImproved<T,K>={[PinkeyofTasExclude<P,K&keyofany>]:T[P];}}

It's explicitly out of scope for TypeScript to modify module specifiers as they appear in emitted JS, e.g. if you write

importxfrom"some/path";

the output specifierwill always be"some/path" regardless of your tsconfig settings.

This includes things like changing file extensions, changingpaths lookups to their resolutions, changing absolute paths to relative paths, changing relative paths to absolute paths, changing sub-module specifiers to something else, and so on. The string in the import path is the string in the emitted JavaScript, no exceptions.

Instead of trying to get TypeScript to change the path during emit, the correct approach is to write the specifier you want to be in the output, and adjust your configuration until that specifier resolves (in type-land) to the path you want it to.

See also:

• Module documentation
• This comment

noUncheckedIndexedAccess is intended to prevent all accidental out-of-bounds access on arrays.

Because array mutationcould occur at any time, it doesn't make any exceptions for things likelength checks.

In order to ensure that the flag doesn't have any "gaps", requests to change the logic to produceT instead ofT | undefined will not be accepted.

See this comment

Note: Section titles here state thetrue version of the fact.

When TypeScript emits JavaScript, it does not guarantee that 100% of source comments will be present in the output.Not storing or computing comment ranges on emit is important for performance, and reasonable people can and do disagree about which comment blocks "belong" to either type (thus omitted) or expression (thus retained) constructs, so in general you should not take a hard dependency on comments being preserved or removed in arbitrary positions.

You cangenerally expect comments to be preserved in cases where the comment immediately precedes a value declaration

// This comment will be in the outputconstn=5;

Comments willgenerally not be emitted when they occur inside types:

interfaceFoo{// This comment won't be in the outputs:string;}

If you need 100% comment preservation according to some definition of what should/shouldn't be emitted, we recommend using a different emit tool.Edge cases or "inconsistencies"will not be considered as defects, and we don't accept PRs to tinker with comment emit.

The type{ } refers to any (non-null/undefined) value with zero or more properties.

Primitive values, like strings, do have properties. For example,"hello world".length is a valid property access, because strings have alength property. Therefore, astring is a valid{ }: it is not null or undefined, and has zero or more properties.

The type that refers to values which haveObject in their prototype chain isobject.{ } is not a synonym forobject.

Because TypeScript doesn't have sealed/closed types, there's no type which refers to values with zero properties.

Certainlint rules ban using{}; we do not recommend this rule and we don't design the language around misguided lint rules. The correct value to use for "any non-null non-undefined value" is{ }, other suggested types likeRecord<string, never> are not particularly coherent and shouldn't be used instead. We recommend disabling any lint rule that tries to prevent you from using{ }, because (unlikeString orNumber) it's a valid type that does occur in normal usage of TypeScript.

Evolvinglet and evolving arrays are intentional (see PR #11263) and shouldn't be errors undernoImplicitAny. They do not act likeany.

These features exist to ensure that these programs have equivalent behavior:

letx;if(cond){x=y;}else{x=z;}doSomethingWith(x);// <- first read

and the identical program:

letx=cond ?y :z;doSomethingWith(x);

Even those these appear asany in tooltips (see #54414), these don't have any of the problems associated withany. Allowing an assignment prior to the first read is no different from initialization and should be treated the same as initialization (and is).

Object types in TypeScript aren't "sealed" / "closed" / "final". In other words, if you have a variable oftype{ a: string }, it's possible that the variable points to avalue like{ a: "hello", b: 42 }.

When you're directly creating an object literal, TypeScript uses "excess property checks" to detect likely problems:

interfaceDimensions{width:number;height:number;depth?:number;}constp:Dimensions={width:32,height:14,depht:11// <-- typo!!}

However, this code is still legal:

constp={width:32,height:14,depht:11// <-- fine};console.log(p.depht);// yep, it's thereconstq:Dimensions=p;// also fine

This also means thatObject.keys should (and does) returnstring[], not(keyof T)[]. See alsothis StackOverflow post

See also suggestion #12936

A dangerous thing that can happen in JavaScript is implicit coercion:

functionquadruple(x){console.log((x+x)*2);}quadruple("1");// Prints 22, not 4

This happens because the value"1" adds to itself as string concat to produce"11", which is then coerced to a number (11) before being multipled by2.

You might try to use the global functionisFinite to prevent this bug:

functionquadruple(x){if(isFinite(x)){console.log((x+x)*2);}}quadruple("1");// Still prints 22

This is becauseisFinite coerces its argument to a numeric valuebefore evaluating if it's finite or not.This is dangerous, because it can lead to unexpected results like the one above.

The functionNumber.isFinite doesn't have this problem; it only returnstrue if its argument is actually anumber:

functionquadruple(x){if(Number.isFinite(x)){// Not reachedconsole.log((x+x)*2);}}quadruple("1");// Safely does nothing

isNaN andNumber.isNaN behave in a similar way; we know one property of theNaN value is that

NaN!==NaN

However, this property isn't true of values which passisNaN:

constobj={};if(isNaN(obj)){// prints trueconsole.log(obj===obj);}

The TypeScript types for these functionscorrectly model the fact that you never want a dangerous coercion to occur:

• It's only safe to pass pre-coercednumbers to the globalisFinite. It always returns predictable, non-dangerous resultsas long as its input is anumber
• Conversely,Number.isFinite will always give reliable results, because it does not perform coercion. It can safely accept any input as a result

Let's say you write an interface

interfaceCanCheck{checkThing:(x:string)=>boolean;}

and implement it with an object:

constobj={checkThing:(sn:string|number)=>{returntrue;}}objsatisfiesCanCheck;// OK

A common confusion is to say that sincestring | number is a bigger type thanstring, this program should be rejected, since it means a number might appear where a string is expected. This reasoning is incorrect; even though a number can be passed toobj.checkThing, that cannot create the situation where anumber is present somewhere whereonly astring is expected.

Another common confusion is to claim that the opposite program should be accepted:

interfaceCanCheck{checkThing:(x:string|number)=>boolean;}constobj={checkThing:(s:string)=>{returntrue;}}objsatisfiesCanCheck;// Alleged: should be OK

This is wrong. Ifobj is aCanCheck, thenobj.checkThing(42) is legal, and42 would appear ins, which is only allowed to be astring.

Another common confusion is, in response, to say something like

But a function that takes a stringis a function that takes a string or number!

This is very, very easy to get backwards. After all, in common parlance, a "carnivore" is someone who eats meat. A person who eats beef would seem to qualify. Yet nearly every carnivore human doesnot eat human meat -- the predicate is not universal over all inputs.

The correct way to phrase this is to insert the necessary qualifiers to the proposition

A function that can takeany string is(?) a function that can takeany string or number

In this phrasing, the flaw is more apparent: Because the functiondoesn't take numbers, it doesn't match the criteria.

This logic also applies equally to methods of classes that implement interfaces; no different behavior is required or justified here.

I wrote some code like this and expected an error:

functionhandler(arg:string){// ....}functiondoSomething(callback:(arg1:string,arg2:number)=>void){callback('hello',42);}// Expected error because 'doSomething' wants a callback of// 2 parameters, but 'handler' only accepts 1doSomething(handler);

This is the expected and desired behavior.

Let's consider another program first:

letitems=[1,2,3];items.forEach(arg=>console.log(arg));

This is isomorphic to the example that "wanted" an error.At runtime,forEach invokes the given callback with three arguments (value, index, array), but most of the time the callback only uses one or two of the arguments.This is a very common JavaScript pattern and it would be burdensome to have to explicitly declare unused parameters.

If thiswere an error, it's not even clear how you would fix it! Adding the extra parameters is likely to run afoul of your linter:

letitems=[1,2,3];// Error: Unused variables 'i', 'arr'items.forEach((arg,i,arr)=>console.log(arg));

JavaScript doesn't have a "discard" binding method, so you'd either end up with lint suppressions, or ugly and useless parameters:

// No one wants to write this sad code:items.forEach((arg,_1,_2)=>console.log(arg));

ButforEach should just mark its parameters as optional!e.g.forEach(callback: (element?: T, index?: number, array?: T[]))

This isnot what an optional callback parameter means.Function signatures are always read from thecaller's perspective.IfforEach declared that its callback parameters were optional, the meaning of that is "forEachmight call the callback with 0 arguments".

The meaning of an optional callback parameter isthis:

// Invoke the provided function with 0 or 1 argumentfunctionmaybeCallWithArg(callback:(x?:number)=>void){if(Math.random()>0.5){callback();}else{callback(42);}}

forEachalways provides all three arguments to its callback.You don't have to check for theindex argument to beundefined - it's always there; it's not optional.

There is currently not a way in TypeScript to indicate that a callback parametermust be present.Note that this sort of enforcement wouldn't ever directly fix a bug.In other words, in a hypothetical world whereforEach callbacks were required to accept a minimum of one argument, you'd have this code:

[1,2,3].forEach(()=>console.log("just counting"));//   ~~ Error, not enough arguments?

which would be "fixed", butnot made any more correct, by adding a parameter:

[1,2,3].forEach(x=>console.log("just counting"));// OK, but doesn't do anything different at all

void is not an alias forundefined.

Seethis StackOverflow answer

See also #42709

Exclude<T, U> isn't the same asT & not U. TypeScript does not yet have the notion of a negated type; see #4196.

As mentioned in the documentation,Exclude is a type alias whoseonly effect is to filter unions. This behavior comes from itsdistributivity. It isn't a true "built-in" type that performs type negation.

This means that if the input type isn't a union, nothing will happen. This includes types that you might think of as being "infinite unions", likestring ornumber - they are not union types.

For example,Exclude<string, "hello"> just meansstring. It doesn't mean "anystring except"hello"", becausestring is not a union, and thus no filtering occurs.

The same is true for numbers;Exclude<number, 0> isnumber becausenumber is not a union.

Theas operator (and its other syntax,<T>expr) is in the languagefor the purpose of downcasting, e.g. telling TypeScript that anAnimal is actually aCat. It's very easy to introduce runtime errors in your program via silencing a type error with a downcast, so care should be taken when using it.

For convenience, this operator also works for upcasting, which is a much less frequently needed operation (usuallysatisfies is better).

The ECMAScript spec defines the behavior of JavaScript runtime semantics. This means that evenclearly buggy code, e.g.:

constoutput="hello, world".substr("world");

hasa defined behavior.

The purpose of TypeScript isn't to tell you when you've somehow managed to reach outside the bounds of the ES Spec (a nearly impossible feat), nor to only tell you when you've done something that will raise a runtime exception (something that most people agree doesn't happen nearly often enough in JS). TypeScript defines anormative set of behaviors that we think are generally "good" JS - fewer (but not necessarily zero) implicit coercions, fewer property accesses that result inundefined, fewer exceptions, fewerNaNs, and so on. This does mean that some behavior is on the borderline of "good" vs "not so good", and there are judgement calls involved when it comes to what TypeScript thinks is OK or not.

See alsothis Stackoverflow Post

As mentioned in the docs, theexclude tsconfig optiononly filters the list of files thatinclude picks up. It does not do anything else. Its only purpose is to change which filesinclude produces, and doesn't change the behavior of any other processes. The only thing you can useexclude for is to haveinclude not process a file; if the file is part of your program for a different reason, it will still be there.

exclude has no effect on other ways a file might be included:

• Module resolution
• Thefiles list
• /// <reference directives
• Anything else that isn'tinclude

You can runtsc --explainFiles to see why a file was included.

The "lib" in "skipLibCheck" refers to any.d.ts file.

In other words, there is no distinction made between.d.ts files which are "yours" (say, in yourfiles list) and "not yours" (say, innode_modules/@types).

In general it's not correct to have a.d.ts file be a user-authored input to your program - even if a file only contains types, it should still be.ts so that itproduces a.d.ts in the output for downstream consumers to use.

During the depth-first process of typechecking, TypeScript may encounter an apparent circularity in logic, e.g. it determines thatX should be assignable toY ifX is assignable toY. When this happens, you'll see an error:

'foo' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer

Due to the complexity of the checking process and caching, it's sometimes possible for a circularity error to occur in some situations but not others. If a codebase has a circularity in checking, that errormay be issued, but it's also possible that you may be able to cause the error to go away by pre-doing part of the cycle elsewhere.

In the interests of not arbitrarily breaking people, we're not accepting PRs toadd more circularity errors.

If you have a working PR thatremoves circularity errors without adverse side effects, we can review them.

A very instructive deeper discussion can be read at#45213.

As a trade-off to make parsing more efficient, TypeScript's emittermay not emit every comment in the original source.

If your scenario requires every comment, or some particular form of comment, to be preserved, please use an alternate TS-to-JS transpiler.

Consider a function call where TypeScript must perform type inference:

typeBox<T>={value:T};declarefunctionunbox<T>(arg:Box<T>):T;functionfoo(x:Box<string>){consta=unbox(x);// What is T?}

There are two different approaches for inferringT you can use here:

• Option 1 (structural): Determine the structure ofBox<string>, see that it has a{ value: string } property, look at each property inBox<T> seeing if it usesT in some position, notice that there's avalue: string coming fromx that corresponds tovalue: T inBox<T>, thereforeT = string
• Option 2 (instantiation-based): Notice thatBox<string> is an instantiation ofBox<T>, soT = string

As one might expect, Option 2 ismuch faster, and is also equally correct. As such, TypeScript generally prefers this instantiation-based inference whenever possible.

However, there are cases where instantiation and structural inference can produce different results.

For example ifBox<T> doesn't actuallyuseT, then a structurally-based inference will find no occurrences ofT and inferT = never.But since there's never really a good reason to write a generic type this way, it's not considered to be problematic to do this.

Which inference algorithm is chosen is implementation-dependent and may change for necessary correctness or performance reasons; you should not take a dependency on one or the other occurring.

Many bug reports simply require certain flags to be turned on to get the desired behavior.

Auto-import is the feature that automatically suggests identifiers from other files that you may be able toimport into the current file. It operates under a few key assumptions:

1. Your existingimports were written that way on purpose
2. It's a bad idea toimport things that won't work
3. You don't want your laptop to start on fire

Per the first point, when auto-import is choosing a way to refer to a module (there can often be more than one valid way), generally auto-import will try to use a module format that matches existing imports in the program. If this isn't available for whatever reason, the preferencestypescript.preferences.importModuleSpecifier andtypescript.preferences.importModuleSpecifierEndingare consulted. You can change these settings to change how auto-import chooses how to refer to a module.

On the second point, auto-importintentionally will not offer imports from packages that aren't listed as explicit dependencies inpackage.json, unless those packages have already been imported elsewhere in your code. This includes bothtransitive dependencies anddevDependencies, since neither of those kind of dependencies are guaranteed to be present when your code is installed elsewhere. There isn't an option to configure this, since this only affects the very first time you import a module.

Performance is also important. In situations where auto-import would traverse an impractically large amount of code from yourdependencies list, it instead switches to only offering identifiers from already-imported modules. The current threshold for this is 25 packages. If you want to scan the entire dependencies list, change thetypescript.preferences.includePackageJsonAutoImports setting fromauto (the default) toon, or if you want to disable dependencies scanning altogether, change it tooff.

You can turn onnoUncheckedIndexedAccess to change the behavior such that arrays and object maps presume possibly-out-of-bounds access.

This flag is a "big hammer", so to speak, and does not have any mechanisms for detecting provably in-bounds access. Because it's nearly impossible to soundly prove that an access is in-bounds (on account of mutation, etc.), such exceptions won't be considered.

You can turn onexactOptionalPropertyTypes to change the behavior such that an optional property can't be explicitly provided with the valueundefined.This has important effects on things like object spread:

typeFoo={bar:number};constbase:Foo={bar:42};// Somewhat-suspect initialization of Partial<Foo>constpartial:Partial<Foo>={bar:undefined};// If using spread, the 'undefined' value can be present// at Foo.barconstpossiblyBad:Foo={ ...base, ...partial};

This flag affectsall optional properties and there is no mechanism for doing this on a per-type basis.

Enable--enforceReadonly (not yet released; see#58296)

We greatly appreciate constructive and actionable feedback on all issues. Constructive and actionable means that we can read your comment and gain new information from it.

Good examples of constructive and actionable feedback:

• Code examples demonstrating how you would have used or been helped by the feature
• Examples of third-party libraries that already use patterns like this
• Describing where existing workarounds fall short of the desired behavior

A good litmus test to see if feedback is useful is to consider the scenario where we have an idea for some featureother than exactly the one being proposed, and think it might solve the problem you're having when asking for a particular feature. If you just say "I need this feature", we can't look at your comment and evaluate if the other proposed feature would solve your problem.

Similarly, the same feature request might have many different interpretations. If you just say "I need this", we don't know whichthis you're talking about, and can't figure out which interpretation of the feature is the correct one to implement.

Comments noting how long an suggestion has been open, what year it is, etc., are not considered constructive or helpful. We ask that you not bother posting them.

Most programming languages in common use have been in development for decades at this point, and most common feature ideas can be noticed within the first couple years of use, so the only notable thing that we can deduce from a suggestion being longstanding is that the underlying language has withstood the test of time and is still in usedespite lacking that feature - if anything, evidence against its priority.

Similarly, in successful languages, most ideas that are easy and good get implemented quickly, so if you're looking at a longstanding issue, it's like either much more difficult or much less good than you might be thinking it is. Engaging with the problem, or providing useful context on why you think the change would be helpful, are constructive ways that you can comment on these threads.

Extending long threads with unconstructive comments like this has many downsides:

• Doesn't do anything to clarify why any particular change is more important than the thousands of other open suggestions (evolving a language is not a first-in first-out queue)
• Makes it harder to find useful content in the thread itself
• Adds noise to search results
• Increases the number of times someone has to click "Show More" once we reach the pagination limit

If this is in theBacklog milestone, yes! See alsohttps://github.com/microsoft/TypeScript/blob/main/CONTRIBUTING.md#issue-claiming. Issues may also be marked with "Help Wanted" but this label is not necessary; the milestone field is authoritative.

If an issue isn't in theBacklog milestone, please be advised that PRs may not be reviewed and may not be accepted.

There are generally no nonpublic updates that can be retrieved by asking "Any updates?".

Ouriteration plans,meeting notes, and other plans are available for perusal.

If you'd like to see a particular bug fixed, feel free to raise it in the active milestone's iteration plan. We do our best to prioritize issues that people are encountering.

If there are features you'd like to see added:

• If it's in theBacklog milestone, PRs are welcomed!
• If it's not in theBacklog milestone, see "What Kind of Feedback Are You Looking For?"

Every project on GitHub uses slightly different definitions of "Open" and "Closed".

For us, "Open" means "There is known work left to do". An unfixed bug, for example, should be left open. A suggestion we're still working out the details on, or assessing the need for, is also likely to be Open.

"Closed" means "There is not known work left to do". A fixed bug, for example, is always closed; there is nothing left to do. A suggestion which is clearly out-of-scope for the project, either by going against its core design principles, or being simply unrelated to its core goals, would also be closed.

Not every example is clear-cut. As with all things in life, when there are grey areas to be found, and it'shard to find definitions that everyone agrees with.

These are the edge case rules that we've decided on for clarity:

• Abug (i.e. known defect) that is so trivial as to not ever be bothersome (for example, a benign crash that only occurs in a file specifically crafted to overflow the parser stack) may be considered a "Won't Fix". In this case, it isClosed because there is not "work left to do"
• Asuggestion (feature idea) that seems quite unlikely to provide a good return on investment in the foreseeable future would be Closed, because we've done the work (gathered feedback, considered the pros and cons, and made a decision)
  • Sometimes the decision will be "Not right now, but definitely possibly later?" - in this case, Open is the correct state, because the work is "Keep collecting feedback to see how priorities change". A suggestion may be Open for a very long time as a result. We do not Close suggestionssimply because they were brought up a long time ago, and don't Close issues simply because they haven't been done fast enough for someone's liking.
• Adesign limitation (acknowledged problem, but one where we have no idea how to fix it, or how to fix it without unacceptable downsides) is Closed. These are difficult cases where we've agreed that the issue is a problemper se, but can't see any solution that would be acceptable. There is no "work to be done" here because "Make a breakthrough" is not work that can be concretely pursued.
  • If you think you have a solution to a problem marked "design limitation", feel free to send a PR, we will evaluate it.

All decisions are "only for now". The JS ecosystem is ever-changing, developer priorities are ever-changing, and the project itself will always be evolving over time. This doesn't mean we need to leaveevery issue Open just to leave open a slight chance of a future possibility -- the "Re-open" button is always there, and we're always capable of changing our minds in the face of new evidence or new circumstances. Open/Closed in these gray areas representsour best guess at the long-term state of all of these decisions.

It's worth noting that the Open/Close state flowsfrom the maintainers' point of viewto the issue, not vice versa. Reopening a Suggestion for a feature that we actively don't want to be part of the language won't make us start wanting it. Similarly, reopening a Design Limitation that we have no idea how to fix won't make us able to address it.

Open/Closed definition is a project-wide decision and we don't make per-issue deviations from this definition. Complaining about open/closed state isn't constructive, and please remember that insistence in engaging in nonconstructive discussion is against thecode of conduct.

On a related note, this project does not use the "Closed as Completed" / "Closed as Not Planned" distinction, please do not consult this information. The "close reason" field was added in 2022 so all closed issues prior to that are marked as "Completed" even if nothing was done as a result. Additionally, for a long time thereafter, it wasn't possible to set this field when closing via automation, so auto-closed issues also have an incorrect "close reason". Please don't consult this field, draw any conclusions from it, or ask maintainers to change it -- we don't consult it, and we consider labels / discussion comments to be the correct source of truth as to why an issue was closed (setting aside the philosophical paradox of whether one can be said to have "completed" something involving zero planned work).

It seems like it should be really easy to add a--strictMethodTypes flag that works just like--strictFunctionTypes does today. What's the problem?

In short, even though this seems like it should be straightforward, there are a large number of common patterns today that depend on using method bivariance to cause types to subtype other types in ways that are idiomatic due to prior knowledge of ownership, conventions around who's allowed to raise event-like callbacks, and others. A cursory check in a small project shows hundreds of errors in longstanding code where there aren't any existing complaints of unsoundness due to bivariance. Without a way to fix these errors, there's not a tractable path forward to adding those errors in other places where bivariance definitelyis a possible source of error.

Out of the gate, this breaks array covariance, and not even in a way that has an apparent fix. Let's reduceArray<T> andReadonlyArray<T> to their smallest representations relevant to the problem at hand:

// The smallest possible read-only array that still has// a useful method for getting a mutable copy, like you// would expect to be able to get from Array#sliceinterfaceMiniatureReadonlyArray<T>{getMutableCopy():MiniatureMutableArray<T>;readonly[i:number]:T;}// Mutable array just adds one contravariant methodinterfaceMiniatureMutableArray<T>extendsMiniatureReadonlyArray<T>{push(arg:T):void;}// A read-only array of strings and numbersdeclareconstsn_mini:MiniatureReadonlyArray<string|number>;// A should-be-legal covariant aliasing of that arrayletsnb_mini:MiniatureReadonlyArray<string|number|boolean>=sn_mini;

UnderstrictMethodTypes, this assignment actually fails. Why?

It appears that an illegal call is possible when you do this:

// Invalid: snb_mini is possibly an alias to sn_mini,// whose getMutablyCopy's return type is MiniatureMutableArray<string | number>,// whose `push` method cannot accept booleanssnb_mini.getMutableCopy().push(true);

This logic is sound given the definitions of types that we have.

However, we (as humans) know from reading the prose that when we callgetMutableCopy, thecopy we get is something we're free to mutate however we like.

Possible solutions to this problem are themselves quite difficult:

• One option would be to have some kind of per-site annotation so that we could say thatgetMutableCopy doesn't return aMiniatureMutableArray<T>; instead it returns... well, something else.MiniatureMutableArray< out T> ? What are the semantics of this? When exactly is the covariant aliasing allowed? Can I get a reference to anout string if I start with aMiniatureReadonlyArray<string>? When does that modifier go away? It's not clear. If I knew what to write here I'd be proposing it.
• Allow "forced" variance annotation, e.g. allow you to write something likeinterface ReadonlyArray<out! T> { that forces a covariant measurement ofT. This isn't great either, because it means that structural and instantiation-based inferences and relational checks onReadonlyArray would behave differently (see the FAQ entry on this). Since there's no guarantee which of those two checks you get, this just opens the door for a huge amount of fundamentally-unfixable inconsistencies whenever this type gets mentioned, which is going to be very common.Worse, sinceinterface Array<T> andinterface ReadonlyArray<T>are different interfaces, any time you bridge the mutability gap, you'll see the invariant behavior instead of the covariant behavior (since a variance annotation can't apply to a structural operation), so this problem would not actually go awayat all.
• Some kind of more-explicit "ownership" model like Rust's that gives more prescriptive rules around when something is allowed to be covariantly aliased and when it isn't. Again, I don't know what that looks like in TypeScript.

This also breaks function intersection with the built-inFunction, again with no clear fix:

typeSomeFunc=(s:string)=>void;declareconstsf:SomeFunc;// Illegalconstp:Function&SomeFunc=sf;

With the observed error - again, technically sound - that you can't callp'sapply method obtained fromFunction

error TS2322: Type 'SomeFunc' is not assignable to type 'Function & SomeFunc'.  Type 'SomeFunc' is not assignable to type 'Function'.    Types of property 'apply' are incompatible.      Type '{ <T, R>(this: (this: T) => R, thisArg: T): R; <T, A extends any[], R>(this: (this: T, ...args: A) => R, thisArg: T, args: A): R; }' is not assignable to type '(this: Function, thisArg: any, argArray?: any) => any'.

Basic assignment toreadonly unknown[] doesn't work, due toconcat:

error TS2322: Type 'readonly string[]' is not assignable to type 'readonly unknown[]'.  Types of property 'concat' are incompatible.    Type '{ (...items: ConcatArray<string>[]): string[]; (...items: (string | ConcatArray<string>)[]): string[]; }' is not assignable to type '{ (...items: ConcatArray<unknown>[]): unknown[]; (...items: unknown[]): unknown[]; }'.      Types of parameters 'items' and 'items' are incompatible.        Type 'ConcatArray<unknown>' is not assignable to type 'ConcatArray<string>'.          The types returned by 'slice(...).pop()' are incompatible between these types.            Type 'unknown' is not assignable to type 'string | undefined'.

There's also a problem with the DOM, because the DOM types are constructed in a way that implicitly disallows some operations via a supertype alias, e.g.addEventListener

@types/node also produces hundreds of errors due to the eventing pattern, e.g.

node_modules/@types/node/child_process.d.ts:73:15 - error TS2430: Interface 'ChildProcess' incorrectly extends interface 'EventEmitter'.  Types of property 'addListener' are incompatible.    Type '{ (event: string, listener: (...args: any[]) => void): this; (event: "close", listener: (code: number | null, signal: Signals | null) => void): this; (event: "disconnect", listener: () => void): this; (event: "error", listener: (err: Error) => void): this; (event: "exit", listener: (code: number | null, signal: Sign...' is not assignable to type '(eventName: string | symbol, listener: (...args: any[]) => void) => this'.      Types of parameters 'event' and 'eventName' are incompatible.        Type 'string | symbol' is not assignable to type 'string'.          Type 'symbol' is not assignable to type 'string'.73     interface ChildProcess extends EventEmitter {                 ~~~~~~~~~~~~

Search Terms: "A top-level 'export' modifier cannot be used on value declarations in a CommonJS module when 'verbatimModuleSyntax' is enabled.";TypeScript 5.9: "A CommonJS module cannot use ESM syntax when 'verbatimModuleSyntax' is enabled. Consider adding "type": "module" to package.json"

TL;DR

• If you're writing an ESM NodeJS app, add"type": "module" topackage.json
  • If you're not sure what to do, start by trying this
• If you're writing a CommonJS NodeJS app, either writeimport fs = require("fs"); or disableverbatimModuleSyntax
• If you're using a bundler, changemodule topreserve intsconfig.json
• If you're writing ESM directly for web, changemodule toesnext intsconfig.json

TheverbatimModuleSyntax flag enforces that CommonJS (CJS) modules use CJS syntax (import fs = require('fs');), and ES Modules (ESM) use ESM syntax (import * as fs from 'fs';).This is generally a good flag to enable, because some packages expose different API to CJS and ESM.By enablingverbatimModuleSyntax, you can be sure that when you see CJS syntax you're getting the CJS version of the module, and likewise for ESM.

However, two things interact in a way that can be surprising.

The first fact is that most people tend to write ESM syntax these days.

The second is that NodeJS has a complex set of rules for determining when a file with a .js extension is CJS or ESM:

• If package.json doesn't exist, files are CJS unless they have a top-level import or export statement, in which case they're silently re-interpreted as ESM
• If package.json exists but has notype field, the same rule applies, except you'll see a warning on stdout
  • Note that older versions ofnpm init do not set atype field
• If package.json exists and settype, the file is always of that type
  • Newer versions ofnpm init set thetype field to"commonjs" by default

This means that unless you've explicitly taken some step to opt into ESM modules (either by setting"type": "module" or naming your file.mts`), Node.js will treat your files as CommonJS modules.

Let's say you use a package manager with strict dependencies:

|-/my_package_1|-- /node_modules|---- /other_package <- direct dependency|------ index.d.ts|------ /node_modules|--------- /sub_dep <- symlink!|----------- index.d.ts|-- /src|---- tsconfig.json  <- project root|---- foo.ts         <- a source file that imports the above file

Wherefoo.ts looks like this:

import{getMakeSubDep}from"other_package";// The inferred type of p refers to a type defined// inside node_modules/other_package/node_modules/sub_dep/index.d.tsexportconstp=getMakeSubDep();

When TypeScript needs to emitfoo.d.ts, it needs to write out a type forp:

exportconstp: ???

What should go in the??? ?

One option would be to use a relative path:

import{subdep}from"../node_modules/other_package/node_modules/sub_dep";exportconstp:subdep

This isobviously wrong: It's implausible that a consumer offoo.d.ts would have a folder layout that matches what we happened to have here.

Another option would be to use a subpath:

import{subdep}from"other_package/node_modules/sub_dep";exportconstp:subdep

This isalso obviously wrong: The semantics ofother_package are not that it exposesnode_modules/sub_dep as as sub-path. This probably won't work at runtime, and even if it did, it's not what you want

Another option would be to use a module name:

import{subdep}from"sub_dep";exportconstp:subdep

Isthis correct?

Ifother_package has a dependency onsub_dep@2.0.0 andyour package has a dependency onsub_dep@3.0.0, then these aren't the same type, and it's wrong.

If you don't have a declared dependency onsub_dep at all, then this code would also fail to loadsub_dep when ingested in a downstream project.

These situations - the non-working ones - are the "non-portable identifiers" that TypeScript is complaining about. TS was put into a position where it had to reference the name of a module, but it couldn't find a name for that module that appeared to work. This is why this error occurs.

Now, if youdo have a declared dependency onsub_dep, and it resolves to the "same" target as the oneother_package did, then this is fine. The way this works (roughly) is that TS keeps a reverse map of the files it has loaded and what module specifiers it used to find them. So if you haveimport { subdep } from "sub_dep", and it resolved to a correct .d.ts file, then TS will have it in the lookup table and can usesub_dep to refer to the same file thatother_package did even though these two module specifiersmay have referred to different files (but they didn't).

But! If you never referred tosub_dep in your compilation, then TypeScript has never "seen"sub_dep be referred to from the module resolution context thatfoo.d.ts will have, so it doesn't know whether or not"sub_dep" is a legal way to refer toother_package/node_modules/sub_dep, and ends up issuing this error.

The correct way to address this is generally to import the type that the.d.ts needs to refer to:

// in foo.tsimport{subdep}from"sub_dep";import{getMakeSubDep}from"other_package";// No additional type annotation neededexportconstp=getMakeSubDep();

Ifyou can't do this, then TypeScript can't either, and the only real alternative is to use a broader type annotation so that TS doesn't need to refer to types which are impossible to name:

// in foo.tsimport{getMakeSubDep}from"other_package";// Annotate to anonymous version of whatever subdep isexportconstp:{isSubDep:boolean}=getMakeSubDep();

Or restructure the input file in such a way that the referenced type is not exposed in the.d.ts.

As of TypeScript 5.5 (see #58176), this error should never occur if the required dependency is in your project'spackage.json.

I've found a long-overlooked bug in TypeScript!

Here are some behaviors that may look like bugs, but aren't.

• These two empty classes can be used in place of each other
  • See theFAQ Entry on this page
• I can use a non-void-returning function where one returningvoid is expected
  • See theFAQ Entry on this page
  • Prior discussion at #4544
• I'm allowed to use a shorter parameter list where a longer one is expected
  • See theFAQ Entry on this page
  • Prior discussion at #370, #9300, #9765, #9825, #13043, #16871, #13529, #13977, #17868, #20274, #20541, #21868, #26324, #30876
• private class members are actually visible at runtime
  • See theFAQ Entry on this page for a commonly suggested "fix"
  • Prior discussion at #564, #1537, #2967, #3151, #6748, #8847, #9733, #11033
• This conditional type returnsnever when it should return the true branch.
  • See thisissue for discussion aboutdistributive conditional types.
• This mapped type returns a primitive type, not an object type.
  • Mapped types declared as{ [ K in keyof T ]: U } where T is a type parameter are known ashomomorphic mapped types, which means that the mapped type is a structure preserving function ofT. When type parameterT is instantiated with a primitive type the mapped type evaluates to the same primitive.
• A method and a function property of the same type behave differently.
  • Methods are always bivariant in their argument, while function properties are contravariant in their argument understrictFunctionTypes. More discussionhere.
• Export maps aren't respected.
  • TypeScript's support for export maps is recent, and requiresmoduleResolution be set tonode16,nodenext orbundler to be respected.
• A default import of a commonjs module with a default in a esm file doesn't seem to be the default export of that module whenmodule isnode16 ornodenext.
  • TypeScript is exposingnode's behavior here - when a esm module default imports a commonjs module, that whole commonjs module is made available as the default import. If you then want the actual default member of that module, you'll need to access thedefault member of that import. Refer to thenode documentation for more information.

I want to request one of the following features...

Here's a list of common feature requests and their corresponding issue.Please leave comments in these rather than logging new issues.

• Safe navigation operator, AKA CoffeeScript's null conditional/propagating/propagation operator, AKA C#'s'?. operator#16
• Minification#8
• Extension methods#9
• Partial classes#563
• Something to do withthis#513
• Strong typing ofFunction memberscall/bind/apply#212
• Runtime function overloading#3442

TypeScript usesstructural typing.This system is different than the type system employed by some other popular languages you may have used (e.g. Java, C#, etc.)

The idea behind structural typing is that two types are compatible if theirmembers are compatible.For example, in C# or Java, two classes namedMyPoint andYourPoint, both with publicint propertiesx andy, are not interchangeable, even though they are identical.But in a structural type system, the fact that these types have different names is immaterial.Because they have the same members with the same types, they are identical.

This applies to subtype relationships as well.In C++, for example, you could only use aDog in place of anAnimal ifAnimal was explicitly inDog's class heritage.In TypeScript, this is not the case - aDog with at least as many members (with appropriate types) asAnimal is a subtype ofAnimal regardless of explicit heritage.

This can have some surprising consequences for programmers accustomed to working in a nominally-typed language.Many questions in this FAQ trace their roots to structural typing and its implications.Once you grasp the basics of it, however, it's very easy to reason about.

TypeScriptremoves type annotations, interfaces, type aliases, and other type system constructs during compilation.

Input:

varx:SomeInterface;

Output:

varx;

This means that at run-time, there is no information present that says that some variablex was declared as being of typeSomeInterface.

The lack of run-time type information can be surprising for programmers who are used to extensively using reflection or other metadata systems.Many questions in this FAQ boil down to "because types are erased".

I wrote some code like this and expected an error:\

functiontrainDog(d:Dog){ ...}functioncloneAnimal(source:Animal,done:(result:Animal)=>void):void{ ...}letc=newCat();// Runtime error here occurs because we end up invoking 'trainDog' with a 'Cat'cloneAnimal(c,trainDog);

This is an unsoundness resulting from the lack of explicit covariant/contravariant annotations in the type system.Because of this omission, TypeScript must be more permissive when asked whether(x: Dog) => void is assignable to(x: Animal) => void.

To understand why, consider two questions: IsDog[] a subtype ofAnimal[]?ShouldDog[] be a subtype ofAnimal[] in TypeScript?

The second question (shouldDog[] be a subtype ofAnimal[]?) is easier to analyze.What if the answer was "no"?

functioncheckIfAnimalsAreAwake(arr:Animal[]){ ...}letmyPets:Dog[]=[spot,fido];// Error? Can't substitute Dog[] for Animal[]?checkIfAnimalsAreAwake(myPets);

This would beincredibly annoying.The code here is 100% correct provided thatcheckIfAnimalsAreAwake doesn't modify the array.There's not a good reason to reject this program on the basis thatDog[] can't be used in place ofAnimal[] - clearly a group ofDogs is a group ofAnimals here.

Back to the first question.When the type system decides whether or notDog[] is a subtype ofAnimal[], it does the following computation (written here as if the compiler took no optimizations), among many others:

• IsDog[] assignable toAnimal[]?
• Is each member ofDog[] assignable toAnimal[]?
  • IsDog[].push assignable toAnimal[].push?
    • Is the type(x: Dog) => number assignable to(x: Animal) => number?
      • Is the first parameter type in(x: Dog) => number assignable to or from first parameter type in(x: Animal) => number?
        • IsDog assignable to or fromAnimal?
          • Yes.

As you can see here, the type system must ask "Is the type(x: Dog) => number assignable to(x: Animal) => number?",which is the same question the type system needed to ask for the original question.If TypeScript forced contravariance on parameters (requiringAnimal being assignable toDog), thenDog[] would not be assignable toAnimal[].

In summary, in the TypeScript type system, the question of whether a more-specific-type-accepting function should be assignable to a function accepting a less-specific type provides a prerequisite answer to whether anarray of that more specific type should be assignable to an array of a less specific type.Having the latternot be the case would not be an acceptable type system in the vast majority of cases,so we have to take a correctness trade-off for the specific case of function argument types.

I wrote some code like this and expected an error:

functionhandler(arg:string){// ....}functiondoSomething(callback:(arg1:string,arg2:number)=>void){callback('hello',42);}// Expected error because 'doSomething' wants a callback of// 2 parameters, but 'handler' only accepts 1doSomething(handler);

This is the expected and desired behavior.First, refer to the "substitutability" primer at the top of the FAQ --handler is a valid argument forcallback because it can safely ignore extra parameters.

Second, let's consider another case:

letitems=[1,2,3];items.forEach(arg=>console.log(arg));

This is isomorphic to the example that "wanted" an error.At runtime,forEach invokes the given callback with three arguments (value, index, array), but most of the time the callback only uses one or two of the arguments.This is a very common JavaScript pattern and it would be burdensome to have to explicitly declare unused parameters.

ButforEach should just mark its parameters as optional!e.g.forEach(callback: (element?: T, index?: number, array?: T[]))

This isnot what an optional callback parameter means.Function signatures are always read from thecaller's perspective.IfforEach declared that its callback parameters were optional, the meaning of that is "forEachmight call the callback with 0 arguments".

The meaning of an optional callback parameter isthis:

// Invoke the provided function with 0 or 1 argumentfunctionmaybeCallWithArg(callback:(x?:number)=>void){if(Math.random()>0.5){callback();}else{callback(42);}}

forEachalways provides all three arguments to its callback.You don't have to check for theindex argument to beundefined - it's always there; it's not optional.

There is currently not a way in TypeScript to indicate that a callback parametermust be present.Note that this sort of enforcement wouldn't ever directly fix a bug.In other words, in a hypothetical world whereforEach callbacks were required to accept a minimum of one argument, you'd have this code:

[1,2,3].forEach(()=>console.log("just counting"));//   ~~ Error, not enough arguments?

which would be "fixed", butnot made any more correct, by adding a parameter:

[1,2,3].forEach(x=>console.log("just counting"));// OK, but doesn't do anything different at all

I wrote some code like this and expected an error:

functiondoSomething():number{return42;}functioncallMeMaybe(callback:()=>void){callback();}// Expected an error because 'doSomething' returns number, but 'callMeMaybe'// expects void-returning functioncallMeMaybe(doSomething);

This is the expected and desired behavior.First, refer to the "substitutability" primer -- the fact thatdoSomething returns "more" information thancallMeMaybe is a valid substitution.

Second, let's consider another case:

letitems=[1,2];callMeMaybe(()=>items.push(3));

This is isomorphic to the example that "wanted" an error.Array#push returns a number (the new length of the array), but it's a safe substitute to use for avoid-returning function.

Another way to think of this is that avoid-returning callback type says "I'm not going to look at your return value, if one exists".

I wrote some code like this and expected an error:

interfaceThing{/* nothing here */}functiondoSomething(a:Thing){// mysterious implementation here}// Expected some or all of these to be errorsdoSomething(window);doSomething(42);doSomething('huh?');

Types with no members can be substituted byany type.In this example,window,42, and'huh?' all have the required members of aThing (there are none).

In general, you shouldnever find yourself declaring aninterface with no properties.

I wrote the following code and expected an error:

typeSomeUrl=string;typeFirstName=string;letx:SomeUrl="http://www.typescriptlang.org/";lety:FirstName="Bob";x=y;// Expected error

Type aliases are simplyaliases -- they are indistinguishable from the types they refer to.

A workaround involving intersection types to make "branded primitives" is possible:

// Strings here are arbitrary, but must be distincttypeSomeUrl=string&{'this is a url':{}};typeFirstName=string&{'person name':{}};// Add type assertionsletx=<SomeUrl>'';lety=<FirstName>'bob';x=y;// Error// OKletxs:string=x;letys:string=y;xs=ys;

You'll need to add a type assertion wherever a value of this type is created.These can still be aliased bystring and lose type safety.

I would like the following code to produce an error:

interfaceScreenCoordinate{x:number;y:number;}interfacePrintCoordinate{x:number;y:number;}functionsendToPrinter(pt:PrintCoordinate){// ...}functiongetCursorPos():ScreenCoordinate{// Not a real implementationreturn{x:0,y:0};}// This should be an errorsendToPrinter(getCursorPos());

A possible fix if you really want two types to be incompatible is to add a 'brand' member:

interfaceScreenCoordinate{_screenCoordBrand:any;x:number;y:number;}interfacePrintCoordinate{_printCoordBrand:any;x:number;y:number;}// ErrorsendToPrinter(getCursorPos());

Note that this will require a type assertion wherever 'branded' objects are created:

functiongetCursorPos():ScreenCoordinate{// Not a real implementationreturn<ScreenCoordinate>{x:0,y:0};}

See also#202 for a suggestion tracking making this more intuitive.

I want to write some code like this:

interfaceSomeInterface{name:string;length:number;}interfaceSomeOtherInterface{questions:string[];}functionf(x:SomeInterface|SomeOtherInterface){// Can't use instanceof on interface, help?if(xinstanceofSomeInterface){// ...}}

TypeScript types are erased (https://en.wikipedia.org/wiki/Type_erasure) during compilation.This means there is no built-in mechanism for performing runtime type checks.It's up to you to decide how you want to distinguish objects.A popular method is to check for properties on an object.You can use user-defined type guards to accomplish this:

functionisSomeInterface(x:any):x isSomeInterface{returntypeofx.name==='string'&&typeofx.length==='number';functionf(x:SomeInterface|SomeOtherInterface){if(isSomeInterface(x)){console.log(x.name);// Cool!}}

I wrote some code like this:

letx:any=true;lety=<string>x;// Expected: runtime error (can't convert boolean to string)

or this

leta:any='hmm';letb=aasHTMLElement;// expected b === null

TypeScript hastype assertions, nottype casts.The intent of<T>x is to say "TypeScript, please treatx as aT", not to perform a type-safe run-time conversion.Because types are erased, there is no direct equivalent of C#'sexpr as type or(type)expr syntax.

I wrote some code like this and expected an error:

letmyFunc:(number)=>string=(n)=>'The number in hex is '+n.toString(16);// Expected error because boolean is not numberconsole.log(myFunc(true));

Parameter names in function types are required.The code as written describes a function taking one parameter namednumber of typeany.In other words, this declaration

letmyFunc:(number)=>string;

is equivalent to this one

letmyFunc:(number:any)=>string;

You should instead write:

letmyFunc:(myArgName:number)=>string;

To avoid this problem, turn on thenoImplicitAny flag, which will issue a warning about the implicitany parameter type.

These three functions seem to do the same thing, but the last one is an error. Why is this the case?

interfaceStringMap{[key:string]:string;}functiona():StringMap{return{a:"1"};// OK}functionb():StringMap{varresult:StringMap={a:"1"};returnresult;// OK}functionc():StringMap{varresult={a:"1"};returnresult;// Error - result lacks index signature, why?}

This isn't now an error in TypeScript 1.8 and later. As for earlier versions:

Contextual typing occurs when the context of an expression gives a hint about what its type might be. For example, in this initialization:

varx:number=y;

The expressiony gets a contextual type ofnumber because it's initializing a value of that type. In this case, nothing special happens, but in other cases more interesting things will occur.

One of the most useful cases is functions:

// Error: string does not contain a function called 'ToUpper'varx:(n:string)=>void=(s)=>console.log(s.ToUpper());

How did the compiler know thats was astring? If you wrote that function expression by itself,s would be of typeany and there wouldn't be any error issued. But because the function was contextually typed by the type ofx, the parameters acquired the typestring. Very useful!

At the same time, an index signature specifies the type when an object is indexed by astring or anumber. Naturally, these signatures are part of type checking:

varx:{[n:string]:Car;};vary:{[n:string]:Animal;};x=y;// Error: Cars are not Animals, this is invalid

The lack of an index signature is also important:

varx:{[n:string]:Car;};vary:{name:Car;};x=y;// Error: y doesn't have an index signature that returns a Car

The problem with assuming that objects don't have index signatures is that you then have no way to initialize an object with an index signature:

varc:Car;// Error, or not?varx:{[n:string]:Car}={'mine':c};

The solution is that when an object literal is contextually typed by a type with an index signature, that index signature is added to the type of the object literal if it matches. For example:

varc:Car;vara:Animal;// OKvarx:{[n:string]:Car}={'mine':c};// Not OK: Animal is not Carvary:{[n:string]:Car}={'mine':a};

Let's look at the original function:

functionc():StringMap{varresult={a:"1"};returnresult;// Error - result lacks index signature, why?}

Becauseresult's type does not have an index signature, the compiler throws an error.

A function or a method implementation signature is not part of the overloads.

functioncreateLog(message:string):number;functioncreateLog(source:string,message?:string):number{return0;}createLog("message");// OKcreateLog("source","message");// ERROR: Supplied parameters do not match any signature

When having at least one overload signature declaration, only the overloads are visible. The last signature declaration, also known as the implementation signature, does not contribute to the shape of your signature. So to get the desired behavior you will need to add an additional overload:

functioncreateLog(message:string):number;functioncreateLog(source:string,message:string):numberfunctioncreateLog(source:string,message?:string):number{return0;}

The rationale here is that since JavaScript does not have function overloading, you will be doing parameter checking in your function, and this your function implementation might be more permissive than what you would want your users to call you through.

For instance you can require your users to call you using matching pairs of arguments, and implement this correctly without having to allow mixed argument types:

functioncompare(a:string,b:string):void;functioncompare(a:number,b:number):void;functioncompare(a:string|number,b:string|number):void{// Just an implementation and not visible to callers}compare(1,2)// OKcompare("s","l")// OKcompare(1,"l")// Error.

I wrote some code like this and expected an error:

classEmpty{/* empty */}vare2:Empty=window;

See the question"Why are all types assignable to empty interfaces?" in this FAQ.It's worth re-iterating the advice from that answer: in general, you shouldnever declare aclass with no properties.This is true even for subclasses:

classBase{important:number;properties:number;}classAlphaextendsBase{}classBravoextendsBase{}

Alpha andBravo are structurally identical to each other, and toBase.This has a lot of surprising effects, so don't do it!If you wantAlpha andBravo to be different, add a private property to each.

What explains the difference between these two lines of code?

classAlpha{x:number}classBravo{x:number}classCharlie{privatex:number}classDelta{privatex:number}leta=newAlpha(),b=newBravo(),c=newCharlie(),d=newDelta();a=b;// OKc=d;// Error

In TypeScript, classes are compared structurally.The one exception to this isprivate andprotected members.When a member is private or protected, it mustoriginate in the same declaration to be considered the same as another private or protected member.

I wrote some code like this:

classMyClass{x=10;someCallback(){console.log(this.x);// Prints 'undefined', not 10this.someMethod();// Throws error "this.method is not a function"}someMethod(){}}letobj=newMyClass();window.setTimeout(obj.someCallback,10);

Synonyms and alternate symptoms:

• Why are my class propertiesundefined in my callback?
• Why doesthis point towindow in my callback?
• Why doesthis point toundefined in my callback?
• Why am I getting an errorthis.someMethod is not a function?
• Why am I getting an errorCannot read property 'someMethod' of undefined?

In JavaScript, the value ofthis inside a function is determined as follows:

1. Was the function the result of calling.bind? If so,this is the first argument passed tobind
2. Was the functiondirectly invoked via a property access expressionexpr.method()? If so,this isexpr
3. Otherwise,this isundefined (in "strict" mode), orwindow in non-strict mode

The offending problem is this line of code:

window.setTimeout(obj.someCallback,10);

Here, we provided a function reference toobj.someCallback tosetTimeout.The function was then invoked on something that wasn't the result ofbind and wasn'tdirectly invoked as a method.Thus,this in the body ofsomeCallback referred towindow (orundefined in strict mode).

Solutions to this are outlined here:http://stackoverflow.com/a/20627988/1704166

I wrote some code like this and don't understand the error I'm getting:

classMyClass{someMethod(){}}varx:MyClass;// Cannot assign 'typeof MyClass' to MyClass? Huh?x=MyClass;

It's important to remember that in JavaScript, classes are just functions.We refer to the class object itself -- thevalueMyClass -- as aconstructor function.When a constructor function is invoked withnew, we get back an object that is aninstance of the class.

So when we define a class, we actually define two differenttypes.

The first is the one referred to by the class' name; in this case,MyClass.This is theinstance type of the class.It defines the properties and methods that aninstance of the class has.It's the type returned by invoking the class' constructor.

The second type is anonymous.It is the type that the constructor function has.It contains aconstruct signature (the ability to be invoked withnew) that returns aninstance of the class.It also contains anystatic properties and methods the class might have.This type is typically referred to as the "static side" of the class because it contains those static members (as well as being theconstructor for the class).We can refer to this type with the type query operatortypeof.

Thetypeof operator (when used in atype position) expresses thetype of anexpression.Thus,typeof MyClass refers to the type of the expressionMyClass - theconstructor function that produces instances ofMyClass.

See#1617 for this and other initialization order questions

TODO: Write up common symptoms ofdeclare class /interface confusion.

Seehttp://stackoverflow.com/a/14348084/1704166

What does this code mean?

classFoo{/* ... */}interfaceBarextendsFoo{}

This makes a type calledBar that has the same members as the instance shape ofFoo.However, ifFoo has private members, their corresponding properties inBar must be implementedby a class which hasFoo in its heritage.In general, this pattern is best avoided, especially ifFoo has private members.

I wrote some code like this:

/** file1.ts **/classAlpha{/* ... */}/** file2.ts **/classBravoextendsAlpha{/* ... */}

I'm seeing a runtime error in__extends:

Uncaught TypeError: Alpha is not defined

The most common cause of this is that your HTML page includes a<script> tag for file2.ts, but not file1.ts.Add a script tag for the base class' outputbefore the script tag for the derived class.

I wrote some code:

/** file1.ts **/classAlpha{/* ... */}/** file2.ts **/classBravoextendsAlpha{/* ... */}

I'm seeing a runtime error in__extends:

Uncaught TypeError: Cannot read property 'prototype' of undefined

This can happen for a few reasons.

The first is that, within a single file, you defined the derived classbefore the base class.Re-order the file so that base classes are declared before the derived classes.

If you're using--out, the compiler may be confused about what order you intended the files to be in.See the section "How do I control file ordering..." in the FAQ.

If you're not using--out, your script tags in the HTML file may be the wrong order.Re-order your script tags so that files defining base classes are included before the files defining the derived classes.

Finally, if you're using a third-party bundler of some sort, that bundler may be ordering files incorrectly.Refer to that tool's documentation to understand how to properly order the input files in the resulting output.

In ES2015, constructors which return an object implicitly substitute the value ofthis for any callers ofsuper(...).It is necessary for generated constructor code to capture any potential return value ofsuper(...) and replace it withthis.

As a result, subclassingError,Array, and others may no longer work as expected.This is due to the fact that constructor functions forError,Array, and the like use ECMAScript 6'snew.target to adjust the prototype chain;however, there is no way to ensure a value fornew.target when invoking a constructor in ECMAScript 5.Other downlevel compilers generally have the same limitation by default.

Example

For a subclass like the following:

classFooErrorextendsError{constructor(m:string){super(m);}sayHello(){return"hello "+this.message;}}

you may find that:

• methods may beundefined on objects returned by constructing these subclasses, so callingsayHello will result in an error.
• instanceof will be broken between instances of the subclass and their instances, so(new FooError()) instanceof FooError will returnfalse.

Recommendation

As a recommendation, you can manually adjust the prototype immediately after anysuper(...) calls.

classFooErrorextendsError{constructor(m:string){super(m);// Set the prototype explicitly.Object.setPrototypeOf(this,FooError.prototype);}sayHello(){return"hello "+this.message;}}

However, any subclass ofFooError will have to manually set the prototype as well.For runtimes that don't supportObject.setPrototypeOf, you may instead be able to use__proto__.

Unfortunately,these workarounds will not work on Internet Explorer 10 and prior.One can manually copy methods from the prototype onto the instance itself (i.e.FooError.prototype ontothis), but the prototype chain itself cannot be fixed.

I wrote some code and expected an error:

interfaceSomething<T>{name:string;}letx:Something<number>;lety:Something<string>;// Expected error: Can't convert Something<number> to Something<string>!x=y;

TypeScript uses a structural type system.When determining compatibility betweenSomething<number> andSomething<string>, we examine eachmember of each type.If all of the members are compatible, then the types themselves are compatible.But becauseSomething<T> doesn'tuseT in any member, it doesn't matter what typeT is - it has no bearing on whether the types are compatible.

In general, you shouldnever have type parameters which are unused.The type will have unexpected compatibility (as shown here) and will also fail to have proper generic type inference in function calls.

I wrote some code like this:

interfaceNamed<T>{name:string;}classMyNamed<T>implementsNamed<T>{name:'mine';}functionfindByName<T>(x:Named<T>):T{// TODO: Implementreturnundefined;}varx:MyNamed<string>;vary=findByName(x);// expected y: string, got y: {}

TypeScript uses a structural type system.This structural-ness also applies during generic type inference.When inferring the type ofT in the function call, we try to findmembers of typeT on thex argument to figure out whatT should be.Because there are no members which useT, there is nothing to infer from, so we return{}.

Note that if you useT, you get correct inference:

interfaceNamed<T>{name:string;value:T;// <-- added}classMyNamed<T>implementsNamed<T>{name:'mine';value:T;// <-- added}functionfindByName<T>(x:Named<T>):T{// TODO: Implementreturnundefined;}varx:MyNamed<string>;vary=findByName(x);// got y: string;

Remember: You shouldnever have unused type parameters!See the previous question for more reasons why this is bad.

I want to write some code like this:

functiondoSomething<T>(x:T){// Can't find name T?letxType=typeofT;lety=newxType();// Same here?if(someVarinstanceoftypeofT){}// How do I instantiate?letz=newT();}

Generics are erased during compilation.This means that there is novalueT at runtime insidedoSomething.The normal pattern that people try to express here is to use the constructor function for a class either as a factory or as a runtime type check.In both cases, using aconstruct signature and providing it as a parameter will do the right thing:

functioncreate<T>(ctor:{new():T}){returnnewctor();}varc=create(MyClass);// c: MyClassfunctionisReallyInstanceOf<T>(ctor:{new(...args:any[]):T},obj:T){returnobjinstanceofctor;}

I wrote a program:

/* myApp.ts */functiondoSomething(){console.log('Hello, world!');}doSomething();

I compiled it withtsc --module commonjs myApp.ts --out app.js and rannode app.js and got the expected output.

Then I added animport to it:

importfs= require('fs');functiondoSomething(){console.log('Hello, world!');}doSomething();

Or added anexport to it:

exportfunctiondoSomething(){console.log('Hello, world!');}doSomething();

And now nothing happens when I runapp.js!

Modules -- those files containing top-levelexport orimport statements -- are always compiled 1:1 with their corresponding js files.The--out option only controls wherescript (non-module) code is emitted.In this case, you should be runningnode myApp.js, because themodulemyApp.ts is always emitted to the filemyApp.js.

This behavior has been fixed as of TypeScript 1.8; combining--out and--module is now an error for CommonJS module output.

This error occurs when you use the--declaration flag because the compiler is trying to produce a declaration file thatexactly matches the module you defined.

Let's say you have this code:

/// MyFile.tsclassTest{// ... other members ....constructor(publicparent:Test){}}exportlett=newTest("some thing");

To produce a declaration file, the compiler has to write out a type fort:

/// MyFile.d.ts, auto-generatedexportlett:___fillintheblank___;

The membert has the typeTest. The typeTest is not visible because it's not exported, so we can't writet: Test.

In thevery simplest cases, we could rewriteTest's shape as an object type literal. But for the vast majority of cases, this doesn't work. As written,Test's shape is self-referential and can't be written as an anonymous type. This also doesn't work ifTest has any private or protected members. So rather than let you get 65% of the way through writing a realistic class and then start erroring then, we just issue the error (you're almost certainly going to hit later anyway) right away and save you the trouble.

To avoid this error:

1. Export the declarations used in the type in question
2. Specify an explicit type annotation for the compiler to use when writing declarations.

There is no way now to indicate an"include" to a file outside the current folder in thetsconfig.json (tracked by#1927). You can achieve the same result by either:

1. Using a"files" list, or ;
2. Adding a/// <reference path="..." /> directive in one of the files in your directory.

For a TypeScript file, the TypeScript compiler by default emits the generated JavaScript files in the same directory with the same base file name.Because the TypeScript files and emitted JavaScript files always have different file extensions, it is safe to do so.However, if you have set theallowJs compiler option totrue and didn't set any emit output options (outFile andoutDir), the compiler will try to emit JavaScript source files by the same rule, which will result in the emitted JavaScript file having the same file name with the source file. To avoid accidentally overwriting your source file, the compiler will issue this warning and skip writing the output files.

There are multiple ways to solve this issue, though all of them involve configuring compiler options, therefore it is recommended that you have atsconfig.json file in the project root to enable this.If you don't want JavaScript files included in your project at all, simply set theallowJs option tofalse;If you do want to include and compile these JavaScript files, set theoutDir option oroutFile option to direct the emitted files elsewhere, so they won't conflict with your source files;If you just want to include the JavaScript files for editing and don't need to compile, set thenoEmit compiler option totrue to skip the emitting check.

For some code examples, we'll use a hypothetical type hierarchy:

Animal/      \DogCat

That is, allDogs areAnimals, allCats areAnimals, but e.g. a function expecting aDog cannot accept an argument of typeCat.If you want to try these examples in the TypeScript Playground, start with this template:

interfaceAnimal{move():void;}interfaceDogextendsAnimal{woof:string;}interfaceCatextendsAnimal{meow:string;}

Other examples will use DOM types likeHTMLElement andHTMLDivElement to highlight concrete real-world implications of certain behaviors.

Many answers relating to the type system make reference toSubstitutability.This is a principle that says that if an objectX can be used in place of some objectY, thenX is asubtype ofY.We also commonly say thatX isassignable toY (these terms have slightly different meanings in TypeScript, but the difference is not important here).

In other words, if I ask for afork, aspork is an acceptablesubstitute because it has the same functions and properties of afork (three prongs and a handle).

TypeScript classifies comments into three different types:

• Leading comment : a comment before a node followed by newline.
• Trailing comment : a comment after a node and in the same line as the node.
• Detached comment : a comment that is not part of any node such as copyright comment.

/*! Top-of-file copyright comment is a detached comment *//* Leading comments of the function AST node */functionfoo/* trailing comments of the function name, "foo", AST node */(){/* Detached comment */letx=10;}