Docs for createType (#1931)

docs/.vuepress/config.js

@@ -43,6 +43,7 @@ module.exports = {
           ['start/api.tx.wrap.md', 'Complex transactions'],
           ['start/types.basics.md', 'Type basics'],
           ['start/types.extend.md', 'Extending types'],
+          ['start/types.create.md', 'Creating types'],
           ['start/extrinsic.extend.md', 'Extending extrinsics'],
           ['start/typescript.md', 'TypeScript interfaces'],
           ['start/typescript.user.md', 'TypeScript user generated'],

docs/start/types.create.md

@@ -0,0 +1,54 @@
+# Type creation
+
+Circling back to metadata. There are two important things to remember when using the API to make queries or send transactions.
+
+1. The functionality available, e.g. exposed on `api.query.*` is not hard-coded in the API, rather this is decorated from the chain metadata. So the metadata lets the API know which endpoints are available and what the type for those endpoints are.
+
+2. When you supply a value to the API, internally it will convert that value to the correct type as expected by the chain, i.e. as determined by the metadata. This means that a function such as `balances.transfer(address: Address, value: Balance)` can take at least the following inputs, which are all converted to the correct types -
+
+- `address` can be an `Address`, an `AccountId`, an `Uint8Array` publicKey, a hex publicKey or an ss58 formatted address;
+- `value` can be a `Balance`, a value encoded in hex, a `BN` object, a base-10 string, a JS `number`, a JS `BigInt` or even a SCALE-encoded `Uint8Array`
+
+In cases where a value is returned such as storage queries, the response from the chain is always encoded into the correct `Codec` type. This means that while the node may return an encoded block (with encoded extrinsics) via `api.rpc.chain.getBlock()`, this is decoded into a proper `SignedBlock` by the API. Outputting this value via `.toJSON()` will yield an encoding for RPC, so if you are not using TypeScript (which adds code helpers on decoded objects), a representation via `.toHuman()` will be more representative of the actual object fields, re-formatted for human consumption.
+
+## Why create types
+
+With the conversions done in the API, there are limited reasons to create types "manually". However, just because there are not thousands of reasons, does not mean it is not valid. For instance, you may retrieve an `Option` and for the sake of sanity would like to use `.unwrapOr()` on it, returning a `Codec` default value where the value `.isNone`.
+
+```js
+// type import for TypeScript
+import type { Balance } from '@polkadot/types/interfaces';
+
+...
+// unwrap out option into a zero Balance whn not found
+const balance: Balance = balanceOpt.unwrapOr(api.createType('Balance'));
+```
+
+In the example above, we introduced the `api.createType(<typeName>, [<value>])`. The same format is also exposed by the `TypeRegistry` (more on this in a short while) as well as `createType(...)` from the actual `@polkadot/types` package. All doing exactly the same.
+
+## Choosing how to create
+
+In most cases, you would always want to use the `api.createType` helper. What this does is call the underlying `@polkadot/types` `createType`, passing through the registry that is attached to the API. Registry? Yes, registry.
+
+The registry contains a listing of all internal types and their classes that have been registered. So upon creation of an API instance, a `registry` object  is attached to the API and this is passed through to all created types. This allows the type definitions to not pollute the global namespace, but rather be contained and able to reference one another.
+
+As mentioned, the `createType` functions all do exactly the same, and it 99.99% of the cases you would be recommended to just forget about everything and use `api.createType` if and when required. In some cases, you may just have a type object and from that want to create another type instance. For that you can access the `registry` on the type object and call `createType` on it. (If this type object was created from an API instance, the registry on the type and on the API will point to the same instance.)
+
+Basically, this means that we have equivalency in creation for all the items below, all creating on the same registry (containing all injected types), and all wrapping the same value -
+
+```js
+import { createType } from '@polkadot/types';
+
+// via API (recommended)
+api.createType('Balance', 123);
+
+// via registry (`.registry` is on all API and Codec objects)
+api.registry.createType('Balance', 123n);
+
+// via the low-level approach
+createType(api.registry, 'Balance', '123');
+```
+
+## Extending extrinsics
+
+On customized chains, it is possible to [extend the format of the extrinsics and extrinsic payload for the chain](extrinsic.extend.md), next up we will look at this advanced use-case.

docs/start/types.extend.md

@@ -137,6 +137,6 @@ const api = await ApiPromise.create({
 
 `Balance` would be defined as an `u128` at the end. Effectively based on the flow it is first registered as a `u32`, then overridden as a `u64` and finally overridden once more as a `u128` by the chain types.
 
-## Extending extrinsics
+## Type creation
 
-On customized chains, it is possible to [extend the format of the extrinsics and extrinsic payload as customized on the chain](extrinsic.extend.md), next up we will look at this advanced use-case.
+While the API always converts all the inputs into the underlying type required by the operation, in some cases you may want to [cret an instance of a type](types.create.md) yourself.