Forem: AkaraChen

How to make a modern npm package

AkaraChen — Sun, 11 Sep 2022 12:59:30 +0000

I've been working on an npm package for a while now, in an age of ESM and CJS going hand in hand, it is not enough that you add just one of these supports to your npm package.

Now, I will show you my work today, how to initialize an npm package elegantly.

Set up

At first, create package.json

pnpm init

pnpm will automatically generate the necessary information.

Then, add some code:

// src/math.js
export const increment = value => ++value;

// src/index.js
import {increment} from "./math";
export default increment(0);

Now we have a simple ESM package. As a flag for the npm package, we need to specify what we are exporting. So I add the following line to package.json:

"exports": {
  "import": "./src/index.js",
}

Bundler

As I mentioned before, it is not enough to provide only ESM or CJS support for the package, but you don't want to write two sets of code by hand that do the same thing, so you need a bundler that can transform TypeScript to ESM and CJS, I choose esbuild, because vite also choose it.

It is easy to install:

pnpm install esbuild -D

Esbuild has a very easy-to-use CLI, we just need to add some package script in your package.json:

"scripts": {
  "build": "npm run build:esm && npm run build:cjs",
  "build:esm": "esbuild --bundle src/index.js --format=esm --outfile=dist/esm.js",
  "build:cjs": "esbuild --bundle src/index.js --format=cjs --outfile=dist/cjs.js",
}

Try to run pnpm run build, you can see esm.js and cjs.js in dist folder, so you can change the package.json:

"exports": {
  "import": "./dist/esm.js",
  "require": "./dist/cjs.js"
}

Esbuild has TypeScript support out of the box, so we do not need to configure TypeScript, just rename your .js file to .ts, and change the package script:

"scripts": {
  "build": "npm run build:esm && npm run build:cjs",
  "build:esm": "esbuild --bundle src/index.ts --format=esm --outfile=dist/esm.js",
  "build:cjs": "esbuild --bundle src/index.ts --format=cjs --outfile=dist/cjs.js",
}

Types

Adding a type definition to a package makes the package easier to use, although esbuild does not have built-in support for type definitions, we can implement them via plugins:

pnpm add esbuild-plugin-d.ts -D

Esbuild cli does not support using plugins, so we should use esbuild's JavaScript API to build our package.

create build.js:

// build.js

const esbuild = require("esbuild");
const { dtsPlugin } = require("esbuild-plugin-d.ts");

const option = {
    bundle: true,
    color: true,
    logLevel: "info",
    sourcemap: true,
    entryPoints: ["./src/index.ts"],
    minify: true,
}

async function run() {
    await esbuild
        .build({
            format: "esm",
            outdir: "dist",
            splitting: true,
            plugins: [dtsPlugin()],
            ...option
        })
        .catch(() => process.exit(1))

    await esbuild
        .build({
            format: "cjs",
            outfile: "./dist/cjs.js",
            ...option
        })
        .catch(() => process.exit(1))
}

run()

Then edit package.json

"scripts": {
  "build": "node build",
},

Run pnpm run build again and you will see that index.d.ts has been successfully generated.

Now, we add the location of d.ts to package.json, and the type definition is done:

"types": "./dist/index.d.ts"

By now, you have a fully featured project, it is enough for building a simple package, but for a big package, we need unit test and lint.

Unit test

I choose jest for unit test library, it is powerful and easy to use.

We need to install some dev dependency:

pnpm add -D @jest/global jest ts-jest typescript

Then, create a jest.config.js:

// jest.config.js
module.exports = {
    preset: 'ts-jest',
    transform: {
        '^.+\\.ts?$': 'ts-jest',
    },
};

Jest is ready to go, let's write a unit test:

import {increment} from "../src/math";
import {describe, expect, test} from "@jest/globals";

describe("math module", () => {
  test("0 increment equal 1", () => {
    expect(increment(0)).toBe(1);
  });
});

Add a package script:

"scripts": {
  "test": "jest"
},

Run pnpm test to launch jest.

Lint

It seems we have no choice but to use eslint:

pnpm create @eslint/config

Manually select your feature, then add a script to your package.json:

"scripts": {
  "lint": "eslint --ext .js,.jsx,.ts,.tsx --fix -c .eslintrc.js",
},

At last

Congratulations, we have learned how to initialize an npm package elegantly. If you have a comment, drop them anyway.

If you don't want to build from scratch, you can simply use my template.

Optimize the use of if-else, you need a better selective structure!

AkaraChen — Tue, 07 Jun 2022 02:59:17 +0000

I don't know if you've ever encountered an if-else nesting like a pyramid placed horizontally:

if (true) {
}

if (true) {
}

if (true) {
  if (true) {
    if (true) {
    }
  } else {
  }
} else {
}

If there are too many if-else in a piece of code, the readability of the code will drop rapidly, it becomes very difficult to maintain the code later on.Next I will talk about how to remove them.

Conditional operator

For the simpler if-else statements, they can easily be rewritten as conditional operators:

// Bad 😥
if (true) {
  console.log("Congratutions!")
} else {
  console.warn("Oops, something went wrong!")
}

// Great 🥰
true 
  ? console.log("Congratutions")
  : console.warn("Oops, something went wrong!")

Of course, at this point the difference between the two is not that great.

Logical AND operator

If you just want to execute a function when a certain condition is met, then you can use logical AND operator:

if (true) {
  alert(1)
}

// is equals to:

true && alert(1)

It has very strict conditions of use, only functions can be executed and no statements can be used, including "return". This doesn't make the code look more logical though, but it can be useful in certain cases.

Early returns

Metioned by @Edenn Touitou and @Infinite Table.

Just sort the conditions by their complexities and return each time:

function handleRequest(req) {
  if (req.code >= 500) {
    return "Server error";
  }
  if (req.code >= 404) {
    return "Cilent error";
  }
  return "Suceess";
}

Table driven method

For code like the following, most of the time we will use switch instead. But it's not the best solution, and if we forget to add "break;", the code may run beyond expectations, and switch is not very elegant.

// Bad 😥
const weekday = (num) => {
  if (num === 1) {
    return "Monday"
  } else if (num === 2) {
    return "Tuesday"
  } else if (num === 3) {
    return "Wednesday"
  } else if (num === 4) {
    return "Thursday"
  } else if (num === 5) {
    return "Friday"
  } else if (num === 6) {
    return "Saturday"
  } else if (num === 7) {
    return "Sunday"
  } else {
    return "Unknown"
  }
}

console.log(weekday(1)) // Monday

This is the time to use the table driven method:

// Great 🥰
const weekday = (option) => {
    let obj = {
        1: "Monday",
        2: "Tuesday",
        3: "Wednesday",
        4: "Thursday",
        5: "Friday",
        6: "Saturday",
        0: "Sunday"
    }
    return obj[option] ?? "Unknown"
}

console.log(weekday(1)) // Monday

Or you can use ES6's Map:

// Great 🥰
const weekday = (num) => {
  const map = new Map()
    .set(1, "Monday")
    .set(2, "Tuesday")
    .set(3, "Wednesday")
    .set(4, "Thursday")
    .set(5, "Friday")
    .set(6, "Saturday")
    .set(7, "Sunday");
  return map.has(num) ? map.get(num) : "Unknown";
};

console.log(weekday(1));

Array's include method

In the previous section, we discussed how to optimize one-to-one selection structures, and here we discuss how to elegantly implement one-to-many selection structures.

For example, the following script:

const getContinent = (option) => {
  if (option === "China" || option === "Japan") {
    return "Asia";
  }
  if (option === "Germany" || option === "France") {
    return "Europe";
  }
};

console.log(getContinent("China"));

It doesn't look that bad now because I haven't added all the countries in yet. This is certainly optimizable and can be easily avoided by using Array's include method:

const getContinent = (option) => {
  const Asia = ["China", "Japan"];
  const Europe = ["Germany", "Franch"];
  if (Asia.includes(option)) return "Asia";
  if (Europe.includes(option)) return "Europe";
  return "Unknown";
};

console.log(getContinent("China")); // Asia

After this optimization, the code will not become cluttered even if more countries are added. But it can get even better:

const getContinent = (option) => {
  let [result, setResult] = ["unknown", (str) => (result = str)];
  const Asia = ["China", "Japan"];
  const Europe = ["Germany", "Franch"];
  Asia.includes(option) && setResult("Asia");
  Europe.includes(option) && setResult("Europe");
  return result;
};

console.log(getContinent("China"));

Conclusion

From this article, we have learned how to reduce if-else in your code. If you think this post is helpful, please share it with your network, if you have comment, drop them anyway🙂.