Skip to main content

3 posts tagged with "typescript"

View All Tags

· 9 min read


Markdown is a markup language that has gained immense popularity in recent years. Besides being used as a convenient way to create content that generates full-blown static websites (via engines such as Gatsby.js and MarkBind), I also started to see widespread usage of Markdown in knowledge management systems such as Obsidian and Dendron.

I write articles like this one using Markdown and I am also actively exploring the use of Markdown in the above-mentioned capacities this year. As a result, I decided to dive deep into how Markdown works and hence this article.

I realized that there are two extremes in software projects:

  • the most popular/battle-tested/enterprise-grade projects that define the "standard" for a particular domain
  • tutorial examples/toy projects for educational purposes

While the former is complex and production ready, the latter is simple and easy to understand. The problem is that there's a huge gap between creating something simple to something complex. Should you want to do it, there's less help and at times you are basically on your own to read the code and figure out how the complex implementation works. Nonetheless, there are values in the toy examples, which is what (and why) I will be going through in this article. A simple, starter-friendly implementation.

To understand how Markdown works, I intend to implement several Markdown parsers according to the tutorials/articles that I can find online and work from simple/naive implementations to (hopefully) a more realistic implementation that can be used in production. This is the first one in the "series" and hence the elaborated introduction.

What is Markdown

As Markdown was born without a well-defined set of rules or tests, it has evolved to have a few different flavors. The most well-known flavor of Markdown is CommonMark, which provides a standard set of rules for the language. Borrowing their Markdown reference as seen here, a common set of Markdown syntax looks like this:

*This text will be italic*
**This text will be bold**
# heading 1
## heading 2
* List
* List
* List
1. One
2. Two
3. Three
> and more!

The syntax available in Markdown allows you to style plain text using simple "decorators" such as * and #. It is easy to write and even reads well without the need for a rendered HTML preview.

How it works

The simplest idea for a working Markdown parser is probably using regular expressions. They help you match patterns in a string and you can thereafter replace them with the formatted version. For example, you can grab text surrounded by ** (e.g. **text**) and replace them with <b>text<b>. With this mechanism, we can establish a set of regular expressions and their string replacement strategy, and then just iteratively apply them to the input text. However, it is important to note that this approach has obvious limitations which will be discussed later.

With that, we will examine how a simple Markdown parser can be implemented.

(Note that the following sections will be brief in certain areas that are trivial. You can check the codebase for reference)


As the title suggests, we will be building our parser using TypeScript. Here are the steps to get started:

  1. Create a new project with npm init -y
  2. Install the dev dependencies with npm i -D typescript parcel jest ts-jest @types/jest
    • typescript is the TypeScript compiler
    • parcel is a bundler that we will use to bundle our code into a single HTML file
    • jest and the related packages are going to help during unit testing
  3. Initialize the TypeScript project with npx tsc --init
  4. Ensure that the tsconfig.json file generated is configured properly

With the setup done, we can start building just a few simple components.


The Pattern class in src/Pattern.ts is an abstraction that holds the regular expression and the string replacement strategy. It also provides the method to apply the regular expression.

export class Pattern {
regex: RegExp;
replacement: string;
constructor(regex: RegExp, replacement: string) {
this.regex = regex;
this.replacement = replacement;

apply(raw: string): string {
return raw.replace(this.regex, this.replacement);

As an aside, the above can be simplified by using the public modifier.

export class Pattern {
constructor(public regex: RegExp, public replacement: string) {}

apply(raw: string): string {
return raw.replace(this.regex, this.replacement);


From patterns, we create a higher-level abstraction which is the Rule. It is a collection of patterns that are applied in a sequence. The reason why we have a collection of patterns is that in Markdown, there can be more than one way to achieve the same formatting. For example, you can use * or _ to achieve italic text. The Rule class in src/Rule.ts is defined as follows:

import { Pattern } from './Pattern';

export class Rule {
name: string;
patterns: Pattern[];
constructor(name: string, patterns: Pattern[]) { = name;
this.patterns = patterns;

apply(raw: string): string {
return this.patterns.reduce(
(result, pattern) => pattern.apply(result),


With Pattern and Rule, we can now use them to create a RMark class that will be the Markdown parser. RMark is just a convenient name for "Regex Markdown" and it is defined in src/index.ts as follows:

import { Rule } from './Rule';
import { Pattern } from './Pattern';

const defaultRules: Rule[] = [
new Rule('header', [
new Pattern(/^#{6}\s?([^\n]+)/gm, '<h6>$1</h6>'),
new Pattern(/^#{5}\s?([^\n]+)/gm, '<h5>$1</h5>'),
new Pattern(/^#{4}\s?([^\n]+)/gm, '<h4>$1</h4>'),
new Pattern(/^#{3}\s?([^\n]+)/gm, '<h3>$1</h3>'),
new Pattern(/^#{2}\s?([^\n]+)/gm, '<h2>$1</h2>'),
new Pattern(/^#{1}\s?([^\n]+)/gm, '<h1>$1</h1>'),
new Rule('bold', [
new Pattern(/\*\*\s?([^\n]+)\*\*/g, '<b>$1</b>'),
new Pattern(/\_\_\s?([^\n]+)\_\_/g, '<b>$1</b>'),
new Rule('italic', [
new Pattern(/\*\s?([^\n]+)\*/g, '<i>$1</i>'),
new Pattern(/\_\s?([^\n]+)\_/g, '<i>$1</i>'),
new Rule('image', [
new Pattern(/\!\[([^\]]+)\]\((\S+)\)/g, '<img src="$2" alt="$1" />'),
new Rule('link', [
new Pattern(
'<a href="$2" target="_blank" rel="noopener">$1</a>'
new Rule('paragraph', [
new Pattern(/([^\n]+\n?)/g, '\n<p>$1</p>\n'),

export class RMark {
private rules: Rule[] = defaultRules;

public addRuleBefore(rule: Rule, before: string): RMark {
const index = this.rules.findIndex((r) => === before);
if (index !== -1) {
this.rules.splice(index, 0, rule);
return this;

public addRule(rule: Rule): RMark {
this.addRuleBefore(rule, 'paragraph');
return this;

public render(raw: string) {
let result = raw;
this.rules.forEach((rule) => {
result = rule.apply(result);
return result;

There are two parts in src/index.ts, one being the default rules and the other being the RMark class. The default rules are the Markdown syntax that we support. As for the RMark class, its render method simply iterates through the rules and applies them to the input text. It also has the addRuleBefore and addRule methods that allow us to add new rules to the parser.


Now, the parser is ready to be called via new RMark().render('input text').

A set of unit tests have been written to showcase the result:

  test('should render bold', () => {
expect(new RMark().render('**Bold**')).toBe('\n<p><b>Bold</b></p>\n');
expect(new RMark().render('__Bold__')).toBe('\n<p><b>Bold</b></p>\n');
expect(new RMark().render('This is **Bold**')).toBe(
'\n<p>This is <b>Bold</b></p>\n'

By using parcel, a simple HTML example is created to see the rendered result in the browser (by running npm run build and npm run serve in the rmark repository):

rendered page

The source code below for the screenshot above can be found in src/page.ts (index.html is also created for this example to work).

import { RMark } from '.';

const sampleText = `# Header 1
## Header 2
### Header 3
#### Header 4
##### Header 5
###### Header 6



This is **Bold** and this is *Italic*.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam ornare erat facilisis odio viverra gravida. Phasellus in finibus libero. Duis eget pellentesque arcu, ut lobortis mi. Praesent vitae nulla sed leo dignissim finibus eget hendrerit arcu. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vestibulum enim nibh, eu pellentesque tellus fermentum venenatis. Nam consectetur sem a magna mattis, sed luctus purus tincidunt. Nam faucibus tellus sed ligula molestie pulvinar. Mauris facilisis felis ex, eu tempor justo commodo et. Aenean lobortis dignissim diam eget tempor.

Sed pellentesque nulla sit amet tincidunt sagittis. Phasellus eget justo nulla. Cras nisi odio, lobortis nec ante eget, commodo euismod
turpis. Cras id orci dolor. Etiam auctor, nisl luctus volutpat lacinia, turpis orci euismod magna, pharetra eleifend massa metus aliquet

const page = document.getElementById('page');

if (page) {
page.innerHTML = new RMark().render(sampleText);


Besides offering only an incomplete set of Markdown features, there are other limitations to the simple rmark parser above.

  • The regular expression approach may not be the most efficient way to parse the text
  • The regular expression is difficult to write and understand for complex syntax
  • The current approach does not strictly obey the CommonMark spec in terms of the expected HTML output

The limitations are frustrating because while the HTML generated looks almost there/mostly identical, it is not the same as the one generated by the referenced implementation. You can compare the difference with this markdown-it playground (Click on source in the right pane to view the HTML code as well).

One reason is that in the above simple implementation, the paragraph tags are added even for those that do not need them. For example, the heading tags should not be wrapped. However, to tweak the implementation to be more compliant with the CommonMark spec, the regular expression turned out to be difficult to create. If it stops adding the extra paragraph tags, it starts breaking other specs, such as not adding paragraphs for the block of lines. Additionally, the parser is likely to fail when handling nested Markdown syntax.


And...this is where most tutorials on (regex-based) Markdown parsers end! We are left with a simple parser that can handle a few Markdown features. Hopefully, this time it is going to be different. I am interested to find out how the edge cases can be handled, and how the parser can be made more efficient. So, I will stop here for now but continue with a more advanced implementation in the next post of the series.


· 3 min read


const genericFn = <T>() => {
return "This is a poorly written example generic function"

Above is an example of a function with a generic parameter T that could potentially be used within the function body. However, if the above code is saved in a .tsx file (In my context, within a React application, while trying to create a generic custom hook), you will receive with the following error when hover over <T>:

JSX element 'T' has no corresponding closing tag.ts(17008)
Cannot find name 'T'.ts(2304)


Defining generic function in TypeScript

To resolve the issue, I started with researching on how to properly define a generic function in TypeScript. Perhaps I made a mistake somewhere in the above syntax. I landed on two articles here and here. Both of them talked about how to create a custom React hook that uses generics. However, the syntax used in the articles were similar to the above example but no errors were discussed.

While I did not find an answer after heading over to TypeScript-CheatSheets, I thought the note on avoiding type inference when declaring custom hook was an interesting point that I did not know about.

If you are returning an array in your Custom Hook, you will want to avoid type inference as TypeScript will infer a union type (when you actually want different types in each position of the array). Instead, use TS 3.4 const assertions:

export function useLoading() {
const [isLoading, setState] = React.useState(false);
const load = (aPromise: Promise<any>) => {
return aPromise.finally(() => setState(false));
return [isLoading, load] as const; // infers [boolean, typeof load] instead of (boolean | typeof load)[]

This way, when you destructure you actually get the right types based on destructure position.

Credit: TypeScript-CheatSheets

Google the error

Moving on with the second strategy: "Google & Stack overflow". Searching the above error landed me on the following issue in the Microsoft TypeScript repository. There were a few more interesting links here and here.

So according to the reported issue:

The usage of <T> prior to the function braces causes a JSX error within .tsx files: "JSX element has no corresponding closing tag.". Basic example works as expected in a .ts file.

The issue was claimed to be a limitation and there were a few workarounds mentioned (in the thread and also in the related stack overflow post):

  • change from .tsx to .ts
  • add a comma: const f = <T,>(arg: T): T => {...}
  • extend this way: const foo = <T extends unknown>(x: T) => x;
  • or extend this way: const foo = <T extends {}>(x: T): T => x;


Funny how issues like this one will continue to bite us even way into the future... simply because no one is going to do anything about it?

· 4 min read

With this series I intend to note down some of the confusion and quirky stuff that I encountered out in the wild. So, today I am going to start with this snippet in TypeScript.


interface CustomState {
value: {
[key:string]: any

const defaultState : CustomState = {
value: {}

const reducer = (state: CustomState, action: { type: string }): CustomState => {
if (action.type === 'reset') {
return {
value: []
} else {
return {

The CustomState declared at the start includes a property called value, which is an object with key-value pairs of the form string - any. The defaultState variable contains an (empty) object conforming to the interface declared above, which is perfectly normal.

The thing that caught me off-guard is in the reducer. The reducer function is supposed to reset the state by clearing out the value property. However, notice here that an array [] is used, instead of {}.

I thought the change from type object to type array is pretty drastic, especially if I compare it to Java (Changing from a HashMap to an ArrayList just like that? Is this even allowed?). The strangest part of this was that TypeScript had no qualms about this at all. No curly lines nor compiler warnings.


The first thing I did was to find out whether the interface was declared correctly, i.e. is it declaring that value contains an object or an array. This led me to review the definition of index signature.

Index Signature

Index signature is a way to describe the types of possible values. Borrowing the examples used in the official TypeScript docs:

interface StringArray {
[index: number]: string;

const myArray: StringArray = getStringArray();
const secondItem = myArray[1]; // secondItem is of type string

The syntax to declare the index signature might seem strange at first. It looks like declaring an object with {} but in the above example, it is used for declaring an interface for an array. For comparison, the way to declare an object interface looks like this:

interface PaintOptions {
xPos: number;
yPos: number;

In the TypeScript documentation example, index signature is used to describe an array. However, there is also a line below that says:

While string index signatures are a powerful way to describe the “dictionary” pattern, they also enforce that all properties match their return type.

Doing a bit more research would point me to other examples of how index signatures are also applicable to objects:

interface NumberDictionary {
[index: string]: number;
length: number;
width: number;

So in the case of CustomState, both the following usage are correct:

const arrayExample:CustomState = {
value: [{val: 1}]

const objectExample:CustomState = {
value: {val: 1}

Array VS Object

The second thing I checked was that since {} could be replaced with [], are arrays and objects, besides what we already know about the different use cases, the same thing in JavaScript/TypeScript? Without going too deep into this question, we can make an observation with console log :

console.log(typeof []) // "object"
console.log(typeof {}) // "object"

Stack Overflow?

The last bit of things of interest came up when I started to draft examples for this article and encountered this stack overflow question. Essentially, the person had an issue with Index signature of object type implicitly has an 'any' type. Scrolling further down, an proposed answer had something similar to my initial example:

type ISomeType = {[key: string]: any};

let someObject: ISomeType = {
firstKey: 'firstValue',
secondKey: 'secondValue',
thirdKey: 'thirdValue'

let key: string = 'secondKey';

let secondValue: string = someObject[key];

In fact to add on, the declaration of ISomeType allows for the following to work as well:

type ISomeType = {[key: string]: any};

// My additional example
let someArray: ISomeType = [
{firstKey: 'firstValue'},
{secondKey: 'secondValue'},
{thirdKey: 'thirdValue'}

let newkey: string = 'secondKey';

let newSecondValue: string = someArray[newkey];

But, if the use of any has been replaced, the whole thing would break:

// Note the change in the type and therefore the error!
type ISomeTypeA = {[key: string]: string};

let someObjectA: ISomeTypeA = {
firstKey: 'firstValue',
secondKey: 'secondValue',
thirdKey: 'thirdValue'

let keyA: string = 'secondKey';

let secondValueA: string = someObjectA[keyA];

// My additional example
let someArrayA: ISomeTypeA = [ // Error: Type '{ firstKey: string; }' is not
{firstKey: 'firstValue'}, // assignable to type 'string'.
{secondKey: 'secondValue'},
{thirdKey: 'thirdValue'}

let newkeyA: string = 'secondKey';

let newSecondValueA: string = someArrayA[newkeyA];

Potential moral of the story? Don't use any 😂


The code snippets used in this article is also available at this TypeScript playground.