diff --git a/docs/errors/common-errors.md b/docs/errors/common-errors.md index afc380b40..ad2934583 100644 --- a/docs/errors/common-errors.md +++ b/docs/errors/common-errors.md @@ -1,5 +1,5 @@ # Common Errors -In this section we explain a number of common error codes that users experience in the real world. +In this section, we explain several common error codes that users experience in the real world. ## TS2304 Samples: @@ -7,19 +7,19 @@ Samples: > `Cannot find name $` > `Cannot find module jquery` -You are probably using a third party library (e.g. google analytics) and don't have it `declare`d. TypeScript tries to save you from *spelling mistakes* and *using variables without declaring them* so you need to be explicit on anything that is *available at runtime* because of you including some external library ([more on how to fix it][ambient]). +You are probably using a third-party library (e.g. Google Analytics) and don't have it `declare`d. TypeScript tries to save you from *spelling mistakes* and *using variables without declaring them* so you need to be explicit about anything that is *available at runtime* because you include some external library ([more on how to fix it][ambient]). ## TS2307 Samples: > `Cannot find module 'underscore'` -You are probably using a third party library (e.g. underscore) as a *module* ([more on modules][modules]) and don't have the ambient declaration file for it ([more on ambient declarations][ambient]). +You are probably using a third-party library (e.g. underscore) as a *module* ([more on modules][modules]) and don't have the ambient declaration file for it ([more on ambient declarations][ambient]). ## TS1148 Sample: > Cannot compile modules unless the '--module' flag is provided -Checkout the [section on modules][modules]. +Check out the [section on modules][modules]. ## Catch clause variable cannot have a type annotation Sample: @@ -34,7 +34,7 @@ try { something(); } catch (e) { if (e instanceof Error){ // Here you go. - } + } } ``` diff --git a/docs/errors/interpreting-errors.md b/docs/errors/interpreting-errors.md index b05bfeb52..f01f5e3e8 100644 --- a/docs/errors/interpreting-errors.md +++ b/docs/errors/interpreting-errors.md @@ -1,7 +1,7 @@ # Interpreting Errors -Since TypeScript is a heavily focused *Developer Help* oriented programming language, its errors messages try to be super helpful when something goes wrong. This can lead to a slight information overload for unsuspecting users of compilers that aren't so helpful. +Since TypeScript is a heavily focused *Developer Help* oriented programming language, its error messages try to be super helpful when something goes wrong. This can lead to a slight information overload for unsuspecting users of compilers that aren't so helpful. -Lets look at an example in an IDE to break apart the process of reading an error message. +Let's look at an example in an IDE to break apart the process of reading an error message. ```ts type SomethingComplex = { @@ -25,29 +25,29 @@ const fail = { takeSomethingComplex(fail); // TS ERROR HAPPENS HERE ``` -This example demonstrates a common programmer error where they *fail* to call a function (`bar: getBar` should be `bar: getBar()`). Fortunately this mistake is caught by TypeScript as soon as it doesn't meet the type requirements. +This example demonstrates a common programmer error where they *fail* to call a function (`bar: getBar` should be `bar: getBar()`). Fortunately, this mistake is caught by TypeScript as soon as it doesn't meet the type requirements. ## Error Categories There are two categories of TypeScript Error messages (succinct and detailed). ### Succinct -The objective of the succinct error message is to provide an example *conventional compiler* description of the error number and message. For this example the succinct message looks like: +The objective of the succinct error message is to provide an example *conventional compiler* description of the error number and message. For this example, the succinct message looks like: ``` TS2345: Argument of type '{ foo: number; bar: () => string; }' is not assignable to parameter of type 'SomethingComplex'. ``` -It is fairly self explanatory. However, it doesn't provide a deeper breakdown of *why* the error is happening. That is what the *detailed* error message is for. +It is fairly self-explanatory. However, it doesn't provide a deeper breakdown of *why* the error is happening. That is what the *detailed* error message is for. ### Detailed -For this example the detailed version looks like: +For this example, the detailed version looks like: ``` [ts] Argument of type '{ foo: number; bar: () => string; }' is not assignable to parameter of type 'SomethingComplex'. - Types of property 'bar' are incompatible. - Type '() => string' is not assignable to type 'string'. + Types of property 'bar' are incompatible. + Type '() => string' is not assignable to type 'string'. ``` -The objective of the detailed error message is to *guide* the user to the reason why some error (type incompatibility in this case) is happening. The first line is same as the succinct, followed by a chain. You should read this chain as a series of responses to the developer question `WHY?` between lines i.e +The objective of the detailed error message is to *guide* the user to the reason why some error (type incompatibility in this case) is happening. The first line is the same as the succinct, followed by a chain. You should read this chain as a series of responses to the developer's question `WHY?` between lines i.e ``` ERROR: Argument of type '{ foo: number; bar: () => string; }' is not assignable to parameter of type 'SomethingComplex'. diff --git a/docs/errors/main.md b/docs/errors/main.md index 790387cbb..0191deaee 100644 --- a/docs/errors/main.md +++ b/docs/errors/main.md @@ -1,2 +1,2 @@ # Errors -In this section we discuss how to read and understand TypeScript errors. We follow this with common errors and their solutions. +In this section, we discuss how to read and understand TypeScript errors. We follow this with common errors and their solutions. diff --git a/docs/javascript/closure.md b/docs/javascript/closure.md index db7eaa28b..8ceabecd7 100644 --- a/docs/javascript/closure.md +++ b/docs/javascript/closure.md @@ -8,7 +8,7 @@ function outerFunction(arg) { function bar() { console.log(variableInOuterFunction); // Access a variable from the outer scope - } + } // Call the local function to demonstrate that it has access to arg bar(); @@ -19,14 +19,14 @@ outerFunction("hello closure"); // logs hello closure! You can see that the inner function has access to a variable (variableInOuterFunction) from the outer scope. The variables in the outer function have been closed by (or bound in) the inner function. Hence the term **closure**. The concept in itself is simple enough and pretty intuitive. -Now the awesome part: The inner function can access the variables from the outer scope *even after the outer function has returned*. This is because the variables are still bound in the inner function and not dependent on the outer function. Again let's look at an example: +Now the awesome part: The inner function can access the variables from the outer scope *even after the outer function has returned*. This is because the variables are still bound to the inner function and not dependent on the outer function. Again let's look at an example: ```ts function outerFunction(arg) { var variableInOuterFunction = arg; return function() { console.log(variableInOuterFunction); - } + } } var innerFunction = outerFunction("hello closure!"); @@ -44,7 +44,7 @@ function createCounter() { return { increment() { val++ }, getVal() { return val } - } + } } let counter = createCounter(); @@ -54,7 +54,7 @@ counter.increment(); console.log(counter.getVal()); // 2 ``` -At a high level it is also what makes something like Node.js possible (don't worry if it doesn't click in your brain right now. It will eventually 🌹): +At a high level, it is also what makes something like Node.js possible (don't worry if it doesn't click in your brain right now. It will eventually 🌹): ```ts // Pseudo code to explain the concept @@ -62,6 +62,6 @@ server.on(function handler(req, res) { loadData(req.id).then(function(data) { // the `res` has been closed over and is available res.send(data); - }) + }) }); ``` diff --git a/docs/javascript/equality.md b/docs/javascript/equality.md index 79916c01c..6436d6480 100644 --- a/docs/javascript/equality.md +++ b/docs/javascript/equality.md @@ -9,7 +9,7 @@ console.log(5 == "5"); // true , TS Error console.log(5 === "5"); // false , TS Error ``` -However, the choices JavaScript makes are not always ideal. For example, in the below example the first statement is false +However, the choices JavaScript makes are not always ideal. For example, in the example below, the first statement is false because `""` and `"0"` are both strings and are clearly not equal. However, in the second case both `0` and the empty string (`""`) are falsy (i.e. behave like `false`) and are therefore equal with respect to `==`. Both statements are false when you use `===`. @@ -51,14 +51,14 @@ type IdDisplay = { display: string } const list: IdDisplay[] = [ - { + { id: 'foo', display: 'Foo Select' - }, - { + }, + { id: 'bar', display: 'Bar Select' - }, + }, ] const fooIndex = list.map(i => i.id).indexOf('foo'); diff --git a/docs/javascript/null-undefined.md b/docs/javascript/null-undefined.md index 4564797c3..f40b7ac4f 100644 --- a/docs/javascript/null-undefined.md +++ b/docs/javascript/null-undefined.md @@ -2,15 +2,15 @@ > [Free youtube video on the subject](https://www.youtube.com/watch?v=kaUfBNzuUAI) -JavaScript (and by extension TypeScript) has two bottom types : `null` and `undefined`. They are *intended* to mean different things: +JavaScript (and by extension TypeScript) has two bottom types: `null` and `undefined`. They are *intended* to mean different things: -* Something hasn't been initialized : `undefined`. +* Something hasn't been initialized: `undefined`. * Something is currently unavailable: `null`. ### Checking for either -Fact is you will need to deal with both. Interestingly in JavaScript with `==`, `null` and `undefined` are only equal to each other: +The fact is you will need to deal with both. Interestingly in JavaScript with `==`, `null` and `undefined` are only equal to each other: ```ts // Both null and undefined are only `==` to themselves and each other: @@ -30,19 +30,19 @@ Recommend `== null` to check for both `undefined` or `null`. You generally don't function foo(arg: string | null | undefined) { if (arg != null) { // arg must be a string as `!=` rules out both null and undefined. - } + } } ``` > You could also do `== undefined`, but `== null` is more conventional/shorter. -One exception, root level `undefined` values which we discuss next. +One exception is root level `undefined` values which we discuss next. ### Checking for root level undefined -Remember how I said you should use `== null`? Of course you do (cause I just said it ^). Don't use it for root level things. In strict mode if you use `foo` and `foo` is undefined you get a `ReferenceError` **exception** and the whole call stack unwinds. +Remember how I said you should use `== null`? Of course, you do (cause I just said it ^). Don't use it for root level things. In strict mode if you use `foo` and `foo` is undefined you get a `ReferenceError` **exception** and the whole call stack unwinds. -> You should use strict mode ... and in fact the TS compiler will insert it for you if you use modules ... more on those later in the book so you don't have to be explicit about it :) +> You should use strict mode ... and in fact, the TS compiler will insert it for you if you use modules ... more on those later in the book so you don't have to be explicit about it :) So to check if a variable is defined or not at a *global* level you normally use `typeof`: @@ -54,7 +54,7 @@ if (typeof someglobal !== 'undefined') { ``` ### Limit explicit use of `undefined` -Because TypeScript gives you the opportunity to *document* your structures separately from values instead of stuff like: +Because TypeScript allows you to *document* your structures separately from values instead of stuff like: ```ts function foo(){ // if Something @@ -62,6 +62,7 @@ function foo(){ // else return {a:1,b:undefined}; } + ``` you should use a type annotation: ```ts @@ -74,7 +75,7 @@ function foo():{a:number,b?:number}{ ``` ### Node style callbacks -Node style callback functions (e.g. `(err,somethingElse)=>{ /* something */ }`) are generally called with `err` set to `null` if there isn't an error. You generally just use a truthy check for this anyways: +Node style callback functions (e.g. `(err,somethingElse)=>{ /* something */ }`) are generally called with `err` set to `null` if there isn't an error. You generally just use a truthy check for this anyway: ```ts fs.readFile('someFile', 'utf8', (err,data) => { @@ -85,7 +86,7 @@ fs.readFile('someFile', 'utf8', (err,data) => { } }); ``` -When creating your own APIs it's *okay* to use `null` in this case for consistency. In all sincerity for your own APIs you should look at promises, in that case you actually don't need to bother with absent error values (you handle them with `.then` vs. `.catch`). +When creating your own APIs it's *okay* to use `null` in this case for consistency. In all sincerity for your own APIs you should look at promises, in that case, you actually don't need to bother with absent error values (you handle them with `.then` vs. `.catch`). ### Don't use `undefined` as a means of denoting *validity* @@ -124,4 +125,4 @@ Setting attribute values to undefined can save on storage and transmission costs ### Final thoughts TypeScript team doesn't use `null` : [TypeScript coding guidelines](https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines#null-and-undefined) and it hasn't caused any problems. Douglas Crockford thinks [`null` is a bad idea](https://www.youtube.com/watch?v=PSGEjv3Tqo0&feature=youtu.be&t=9m21s) and we should all just use `undefined`. -However, NodeJS style code bases uses `null` for Error arguments as standard as it denotes `Something is currently unavailable`. I personally don't care to distinguish between the two as most projects use libraries with differing opinions and just rule out both with `== null`. +However, NodeJS style code bases use `null` for Error arguments as standard as it denotes `Something is currently unavailable`. I personally don't care to distinguish between the two as most projects use libraries with differing opinions and just rule out both with `== null`. diff --git a/docs/javascript/number.md b/docs/javascript/number.md index f452de2ef..1ad11cf4f 100644 --- a/docs/javascript/number.md +++ b/docs/javascript/number.md @@ -5,7 +5,7 @@ Whenever you are handling numbers in any programming language you need to be awa JavaScript has only one number type. It is a double-precision 64-bit `Number`. Below we discuss its limitations along with a recommended solution. ### Decimal -For those familiar with doubles / float in other languages, you would know that binary floating point numbers *do not* map correctly to Decimal numbers. A trivial (and famous) example with JavaScript's built in numbers is shown below: +For those familiar with doubles/float in other languages, you would know that binary floating point numbers *do not* map correctly to Decimal numbers. A trivial (and famous) example with JavaScript's built-in numbers is shown below: ```js console.log(.1 + .2); // 0.30000000000000004 @@ -14,7 +14,7 @@ console.log(.1 + .2); // 0.30000000000000004 > For true decimal math use `big.js` mentioned below. ### Integer -The integer limits represented by the built in number type are `Number.MAX_SAFE_INTEGER` and `Number.MIN_SAFE_INTEGER`. +The integer limits represented by the built-in number type are `Number.MAX_SAFE_INTEGER` and `Number.MIN_SAFE_INTEGER`. ```js console.log({max: Number.MAX_SAFE_INTEGER, min: Number.MIN_SAFE_INTEGER}); @@ -23,7 +23,7 @@ console.log({max: Number.MAX_SAFE_INTEGER, min: Number.MIN_SAFE_INTEGER}); **Safe** in this context refers to the fact that the value *cannot be the result of a rounding error*. -The unsafe values are `+1 / -1` away from these safe values and any amount of addition / subtraction will *round* the result. +The unsafe values are `+1 / -1` away from these safe values and any amount of addition/subtraction will *round* the result. ```js console.log(Number.MAX_SAFE_INTEGER + 1 === Number.MAX_SAFE_INTEGER + 2); // true! @@ -52,7 +52,7 @@ console.log(Number.isSafeInteger(Number.MAX_SAFE_INTEGER + 10)); // false > JavaScript will eventually get [BigInt](https://developers.google.com/web/updates/2018/05/bigint) support. For now, if you want arbitrary precision integer math use `big.js` mentioned below. ### big.js -Whenever you use math for financial calculations (e.g. GST calculation, money with cents, addition etc) use a library like [big.js](https://github.com/MikeMcl/big.js/) which is designed for +Whenever you use math for financial calculations (e.g. GST calculation, money with cents, addition, etc) use a library like [big.js](https://github.com/MikeMcl/big.js/) which is designed for * Perfect decimal math * Safe out of bound integer values @@ -73,7 +73,7 @@ export const bar = foo.plus(new Big('0.00000000000000000001')); const x: number = Number(bar.toString()); // Loses the precision ``` -> Do not use this library for math used for UI / performance intensive purposes e.g charts, canvas drawing etc. +> Do not use this library for math used for UI / performance-intensive purposes e.g. charts, canvas drawing, etc. ### NaN When some number calculation is not representable by a valid number, JavaScript returns a special `NaN` value. A classic example is imaginary numbers: @@ -114,7 +114,7 @@ console.log(Number.MAX_VALUE + 1e292); // Infinity console.log(-Number.MAX_VALUE - 1e292); // -Infinity ``` -Of-course, these special infinity values also show up with arithmetic that requires it e.g. +Of course, these special infinity values also show up with arithmetic that requires it e.g. ```js console.log( 1 / 0); // Infinity @@ -128,7 +128,7 @@ console.log(Number.POSITIVE_INFINITY === Infinity); // true console.log(Number.NEGATIVE_INFINITY === -Infinity); // true ``` -Fortunately comparison operators (`<` / `>`) work reliably on infinity values: +Fortunately, comparison operators (`<` / `>`) work reliably on infinity values: ```js console.log( Infinity > 1); // true diff --git a/docs/javascript/recap.md b/docs/javascript/recap.md index 28aa764d4..525c244b0 100644 --- a/docs/javascript/recap.md +++ b/docs/javascript/recap.md @@ -6,8 +6,8 @@ There were (and will continue to be) a lot of competitors in *Some syntax* to *J However, it does mean that *you need to learn JavaScript* (the good news is *you **only** need to learn JavaScript*). TypeScript is just standardizing all the ways you provide *good documentation* on JavaScript. -* Just giving you a new syntax doesn't help catch bugs - but might help you write cleaner / less bugs (e.g. CoffeeScript). -* Creating a new language abstracts you too far from your runtimes and communities - but might help on-board you easier if its an already familiar flavour (e.g. Dart - closer for Java / C# devs). +* Just giving you a new syntax doesn't help catch bugs - but might help you write cleaner / fewer bugs (e.g. CoffeeScript). +* Creating a new language abstracts you too far from your runtimes and communities - but might help onboard you easier if it's an already familiar flavour (e.g. Dart - closer for Java / C# devs). TypeScript is just JavaScript with docs. @@ -36,7 +36,7 @@ function add(a,b) { } ``` -Essentially TypeScript is linting JavaScript. Just doing a better job at it than other linters that don't have *type information*. +Essentially TypeScript is linting JavaScript, doing a better job at it than other linters that don't have *type information*. ## You still need to learn JavaScript diff --git a/docs/javascript/references.md b/docs/javascript/references.md index f0c6f2cb6..42ad9a192 100644 --- a/docs/javascript/references.md +++ b/docs/javascript/references.md @@ -1,6 +1,6 @@ ## References -Beyond literals, any Object in JavaScript (including functions, arrays, regexp etc) are references. This means the following +Beyond literals, any Objects in JavaScript (including functions, arrays, regexp, etc) are references. This means the following: ### Mutations are across all references diff --git a/docs/javascript/this.md b/docs/javascript/this.md index 6c5f26782..8d0894a22 100644 --- a/docs/javascript/this.md +++ b/docs/javascript/this.md @@ -1,6 +1,6 @@ ## this -Any access to `this` keyword within a function is controlled by how the function is actually called. It is commonly referred to as the β€œcalling context.” +Any access to `this` keyword within a function is controlled by how the function is called. It is commonly referred to as the β€œcalling context.” Here is an example: diff --git a/docs/javascript/truthy.md b/docs/javascript/truthy.md index 84c2db4e9..1da19ab63 100644 --- a/docs/javascript/truthy.md +++ b/docs/javascript/truthy.md @@ -26,7 +26,7 @@ Here's a handy table for your reference. > The `!!` pattern -Quite commonly it helps to be explicit that the intent is to treat the value as a `boolean` and convert it into a *true boolean* (one of `true`|`false`). You can easily convert values to a true boolean by prefixing it with `!!` e.g. `!!foo`. Its just `!` used *twice*. The first `!` converts the variable (in this case `foo`) to a boolean but inverts the logic (*truthy* -`!`> `false`, *falsy* -`!`> `true`). The second one toggles it again to match the nature of the original object (e.g. *truthy* -`!`> `false` -`!`> `true`). +Quite commonly it helps to be explicit that the intent is to treat the value as a `boolean` and convert it into a *true boolean* (one of `true`|`false`). You can easily convert values to a true boolean by prefixing it with `!!` e.g. `!!foo`. It's just `!` used *twice*. The first `!` converts the variable (in this case `foo`) to a boolean but inverts the logic (*truthy* -`!`> `false`, *falsy* -`!`> `true`). The second one toggles it again to match the nature of the original object (e.g. *truthy* -`!`> `false` -`!`> `true`). It is common to use this pattern in lots of places e.g. diff --git a/docs/jsx/others.md b/docs/jsx/others.md index f3664a10c..5bd26ff65 100644 --- a/docs/jsx/others.md +++ b/docs/jsx/others.md @@ -1,12 +1,12 @@ -# Non React JSX +# Non-React JSX [![DesignTSX](https://raw.githubusercontent.com/basarat/typescript-book/master/images/designtsx-banner.png)](https://designtsx.com) -TypeScript provides you with the ability to use something other than React with JSX in a type safe manner. The following lists the customizability points, but note that this is for advanced UI framework authors: +TypeScript provides you with the ability to use something other than React with JSX in a type-safe manner. The following lists the customizability points, but note that this is for advanced UI framework authors: * You can disable `react` style emit by using `"jsx" : "preserve"` option. This means that JSX is emitted *as is* and then you can use your own custom transpiler to transpile the JSX portions. * Using the `JSX` global module: - * You can control what HTML tags are available and how they are type checked by customizing the `JSX.IntrinsicElements` interface members. + * You can control what HTML tags are available and how they are type-checked by customizing the `JSX.IntrinsicElements` interface members. * When using components: * You can control which `class` must be inherited by components by customizing the default `interface ElementClass extends React.Component { }` declaration. * You can control which property is used to type check the attributes (the default is `props`) by customizing the `declare module JSX { interface ElementAttributesProperty { props: {}; } }` declaration. @@ -51,7 +51,7 @@ import {jsxFactory} from "jsxFactory"; var div =
Hello JSX!
``` -With `--jsx react` this file will emit to use the factory specfied in the jsx pragma: +With `--jsx react` this file will emit to use the factory specified in the jsx pragma: ```js "use strict"; var jsxFactory_1 = require("jsxFactory"); diff --git a/docs/jsx/react.md b/docs/jsx/react.md index 6c4233115..93cc7a993 100644 --- a/docs/jsx/react.md +++ b/docs/jsx/react.md @@ -1,6 +1,6 @@ # React JSX -> [Free series of youtube videos on React / TypeScript best practices](https://www.youtube.com/watch?v=7EW67MqgJvs&list=PLYvdvJlnTOjHNayH7MukKbSJ6PueUNkkG) +> [Free series of YouTube videos on React / TypeScript best practices](https://www.youtube.com/watch?v=7EW67MqgJvs&list=PLYvdvJlnTOjHNayH7MukKbSJ6PueUNkkG) > [PRO Egghead course on TypeScript and React](https://egghead.io/courses/use-typescript-to-develop-react-applications) @@ -23,7 +23,7 @@ React can either render HTML tags (strings) or React components. The JavaScript ### HTML Tags -An HTML Tag `foo` is to be of the type `JSX.IntrinsicElements.foo`. These types are already defined for all the major tags in a file `react-jsx.d.ts` which we had you install as a part of the setup. Here is a sample of the the contents of the file: +An HTML Tag `foo` is to be of the type `JSX.IntrinsicElements.foo`. These types are already defined for all the major tags in a file `react-jsx.d.ts` which we had you install as a part of the setup. Here is a sample of the contents of the file: ```ts declare module JSX { @@ -61,7 +61,7 @@ As of [@types/react PR #46643](https://github.com/DefinitelyTyped/DefinitelyType type Props = { foo: string } -// OK now, in future, error +// OK now, in the future, error const FunctionComponent: React.FunctionComponent = ({ foo, children }: Props) => { return
{foo} {children}
; // OK }; @@ -73,7 +73,7 @@ const VoidFunctionComponent: React.VoidFunctionComponent = ({ foo, childr ### Class Components -Components are type checked based on the `props` property of the component. This is modeled after how JSX is transformed i.e. the attributes become the `props` of the component. +Components are type-checked based on the `props` property of the component. This is modeled after how JSX is transformed i.e. the attributes become the `props` of the component. The `react.d.ts` file defines the `React.Component` class which you should extend in your own class providing your own `Props` and `State` interfaces. This is demonstrated below: @@ -194,7 +194,7 @@ class Use { } ``` -And the same with ref's for native elements e.g. +and the same with ref's for native elements e.g. ```ts class FocusingInput extends React.Component<{ value: string, onChange: (value: string) => any }, {}>{ diff --git a/docs/jsx/tsx.md b/docs/jsx/tsx.md index 6aa62fbb7..cca31d832 100644 --- a/docs/jsx/tsx.md +++ b/docs/jsx/tsx.md @@ -6,10 +6,10 @@ TypeScript supports JSX transpilation and code analysis. If you are unfamiliar w > JSX is an XML-like syntax extension to ECMAScript without any defined semantics. It's NOT intended to be implemented by engines or browsers. It's NOT a proposal to incorporate JSX into the ECMAScript spec itself. It's intended to be used by various preprocessors (transpilers) to transform these tokens into standard ECMAScript. -The motivation behind JSX is to allow users to write HTML like views *in JavaScript* so that you can: +The motivation behind JSX is to allow users to write HTML-like views *in JavaScript* so that you can: * Have the view Type Checked by the same code that is going to check your JavaScript * Have the view be aware of the context it is going to operate under (i.e. strengthen the *controller-view* connection in traditional MVC). * Reuse JavaScript patterns for HTML maintenance e.g. `Array.prototype.map`, `?:`, `switch` etc instead of creating new (and probably poorly typed) alternatives. -This decreases the chances of errors and increases the maintainability of your user interfaces. The main consumer of JSX at this point is [ReactJS from facebook](http://facebook.github.io/react/). This is the usage of JSX that we will discuss here. +This decreases the chances of errors and increases the maintainability of your user interfaces. The main consumer of JSX at this point is [ReactJS from Facebook](http://facebook.github.io/react/). This is the usage of JSX that we will discuss here. diff --git a/docs/npm/index.md b/docs/npm/index.md index 5f844da98..44084dafa 100644 --- a/docs/npm/index.md +++ b/docs/npm/index.md @@ -2,7 +2,7 @@ > Fun fact `npm` is [not an acronym](https://twitter.com/npmjs/status/347057301401763840) so it doesn't expand to anything, but among friends it is commonly called `node package manager`. -`npm` is a binary that comes with default `node` installations used to manage community shared JavaScript / TypeScript packages. +`npm` is a binary that comes with default `node` installations used to manage community-shared JavaScript / TypeScript packages. * NPM packages are hosted at (and installed from) https://www.npmjs.com/ (the ☁️). @@ -14,7 +14,7 @@ > Even though you might be building an application, having a `package.json` essentially makes your project a package as well. So the terms your `project | package` can be used interchangeably. -When you checkout someone's (your team's) package, it will have a `package.json` that will list the dependencies you need to run the project. You simply run `npm install` and npm will bring them down from the cloud ☁️. +When you check out someone's (your team's) package, it will have a `package.json` that will list the dependencies you need to run the project. You simply run `npm install` and npm will bring them down from the cloud ☁️. ## Installing a package You can run `npm install `. Most people will use the shorthand `npm i ` e.g. @@ -27,17 +27,17 @@ npm i react > This will also automatically add `react` into your `package.json`'s `dependencies`. ## Installing a devDependency -`devDependencies` are dependencies that are only required during *development* if your project and not required after deployment. +`devDependencies` are dependencies that are only required during *development* of your project and not required after deployment. -`typescript` is common in `devDependencies` as its only required to build `.ts -> .js`. You normally deploy the built `.js` files: +`typescript` is common in `devDependencies` as it is only required to build `.ts -> .js`. You normally deploy the built `.js` files: * into production -* OR for consumption by other other npm packages +* OR for consumption by other npm packages ## Security -The public `npm` packages are scanned by security team worldwide and issues get reported to npm team. They then release security advisories detailing the issue and potential fixes. Commonly the fix is simply updating the package. +The public `npm` packages are scanned by the security team worldwide and issues get reported to the npm team. They then release security advisories detailing the issue and potential fixes. Commonly the fix is simply updating the package. -You can run an audit on your node project by simply running `npm audit`. This will highlight any vulnerabilities that might exist in the package / dependencies of the package. e.g. +You can run an audit on your node project by simply running `npm audit`. This will highlight any vulnerabilities that might exist in the package/dependencies of the package. e.g. ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” @@ -53,9 +53,9 @@ You can run an audit on your node project by simply running `npm audit`. This wi β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` -Note that commonly the issues are found in *development* dependencies (e.g. jest in this case). Since these aren't are a part of your production deployments, most likely your production application is not vulnerable. But still good practice to keep vulnerabilities to `0`. +Note that commonly the issues are found in *development* dependencies (e.g. jest in this case). Since these aren't a part of your production deployments, most likely your production application is not vulnerable. But still good practice to keep vulnerabilities to `0`. -Simply add `npm audit` (the command exist with error code `1` in case of error) as a part of your deployment to ensure the projects stay up to date. +Simply add `npm audit` (the command exists with error code `1` in case of error) as a part of your deployment to ensure the projects stay up to date. ## NPM Scripts @@ -92,7 +92,7 @@ You can pass in as many flags as you want after `--` e.g. in the following examp ``` ## Public vs. Private packages -You don't need this when *using* any of the common public npm packages. Just know its there for enterprise / commercial customers. +You don't need this when *using* any of the common public npm packages. Just know it's there for enterprise / commercial customers. ### Public packages * Packages are public by default. @@ -101,11 +101,11 @@ You don't need this when *using* any of the common public npm packages. Just kno No one needs an account to download a public package. -This free sharing of packages is one of the key reasons of success for npm 🌹. +This free sharing of packages is one of the key reasons for the success of npm 🌹. ### Private packages -If you want a private package for your company / team / enterprise you need to sign up to a paid plan, details here : https://www.npmjs.com/pricing +If you want a private package for your company/team/enterprise you need to sign up for a paid plan, details here: https://www.npmjs.com/pricing -Of-course you need an account with the right permissions to download a private package. +Of course, you need an account with the right permissions to download a private package. \ No newline at end of file diff --git a/docs/options/noImplicitAny.md b/docs/options/noImplicitAny.md index 668b9213a..bc58c81e7 100644 --- a/docs/options/noImplicitAny.md +++ b/docs/options/noImplicitAny.md @@ -1,6 +1,6 @@ # noImplicitAny -There are some things that cannot be inferred or inferring them might result in unexpected errors. A fine example is function arguments. If you don't annotate them, its unclear what should and shouldn't be valid e.g. +There are some things that cannot be inferred or inferring them might result in unexpected errors. A fine example is function arguments. If you don't annotate them, it is unclear what should and shouldn't be valid e.g. ```ts function log(someArg) { @@ -12,7 +12,7 @@ log(123); log('hello world'); ``` -So if you don't annotate some function argument, TypeScript assumes `any` and moves on. This essentially turns off type checking for such cases, which is what a JavaScript dev would expect. But this can catch people that want high safety off guard. Hence there is an option, `noImplicitAny`, that when switched on will flag the cases where the type cannot be inferred e.g. +So if you don't annotate some function argument, TypeScript assumes `any` and moves on. This essentially turns off type checking for such cases, which is what a JavaScript dev would expect. But this can catch people who want high safety off guard. Hence there is an option, `noImplicitAny`, that when switched on will flag the cases where the type cannot be inferred e.g. ```ts function log(someArg) { // Error : someArg has an implicit `any` type @@ -20,7 +20,7 @@ function log(someArg) { // Error : someArg has an implicit `any` type } ``` -Of course you can then go ahead and annotate: +Of course, you can then go ahead and annotate: ```ts function log(someArg: number) { diff --git a/docs/options/strictNullChecks.md b/docs/options/strictNullChecks.md index 23d315d60..cb8abc5a2 100644 --- a/docs/options/strictNullChecks.md +++ b/docs/options/strictNullChecks.md @@ -8,7 +8,7 @@ foo = null; // Okay foo = undefined; // Okay ``` -This is modelled after how a lot of people write JavaScript. However, like all things, TypeScript allows you to be *explicit* about what *can and cannot be* assigned a `null` or `undefined`. +This is modeled after how a lot of people write JavaScript. However, like all things, TypeScript allows you to be *explicit* about what *can and cannot be* assigned a `null` or `undefined`. In strict null checking mode, `null` and `undefined` are different: