DEV Community: ByungJoon Lee

jin-frame: Declarative, Type-Safe HTTP Requests in TypeScript

ByungJoon Lee — Mon, 25 Aug 2025 17:00:00 +0000

A Common Story

One day, a teammate reaches out:

“We’ve rolled out a new version of the API server. But the host has changed, so please update your client.”

Suddenly, your mind goes blank. You’ve hardcoded https://old-api.example.com all over the place.

Now you’ll have to track down and replace every instance.

Another day, a data architect says:

“For APIs a, b, and c, we need logging whenever they fail. Right now we have no logs, and it’s impossible to trace errors.”

The problem? These APIs are called in dozens of places.

Adding error logging to every call would be a painful refactor.

Sound familiar?

This is exactly why I built jin-frame.

Why jin-frame?

jin-frame isn’t just another Axios wrapper.

It lets you define HTTP requests declaratively and type-safely using classes and decorators.

🎩 Declarative API definitions with decorators (@Param, @Query, @Header, @Body, @ObjectBody)
⛑️ Type safety enforced at compile-time
🎢 Production-ready features: retry, timeout, hooks, file upload, mocking
🏭 Axios ecosystem compatibility
🎪 Extensible via inheritance, so you can centralize config like host, timeout, or hooks

Example: Inheritance for Clean API Structure

With jin-frame, inheritance solves the exact problems we saw earlier:

“Host changed everywhere” or “Add common logging logic” becomes a one-line fix.

Base Class with Common Config

import { randomUUID } from 'crypto';

@Get({
  host: 'https://pokeapi.co',
  timeout: 3_000,
})
class PokemonAPI extends JinFrame<PokeRes> {
  @Query()
  declare readonly tid: string;

  protected static override getDefaultValues() {
    return { tid: randomUUID() };
  }

  override async $_postHook(req, reply, debugInfo) {
    if (reply.status >= 400) {
      console.error(`[Error] ${req.url}`, reply.status);
      // add your logging ...
    }
  }
}

Every Pokémon API request shares the same host/timeout
A tid field is automatically added for request tracing
A common postHook handles error logging

Child Class: Pokémon by Name

@Get({ path: '/api/v2/pokemon/:name' })
class PokemonByName extends PokemonAPI<IPokemonData> {
  @Param()
  declare readonly name: string;
}

Inherits host, timeout, and hooks from the parent
Child only needs to define its own path and name param

Usage

const frame = PokemonByName.of(b => b.from({ name: 'pikachu' }));
const reply = await frame.execute();

Now when the API host changes, you only update the parent class.

When common logging is required, update the parent hook—all children inherit it.

And if needed, child classes can override hooks for special cases.

Why This Matters

Centralized config: Manage host, timeout, and hooks in one place
Extensibility: Override only what you need in child classes
Traceability: Automatic fields (e.g. tid) for request tracking
Consistency: Every API request looks and behaves the same

Instead of scattering functions across your codebase, inheritance keeps things clean.

As projects grow, this structure dramatically reduces maintenance overhead.

Conclusion

jin-frame is built for developers who:

Are tired of repetitive, scattered HTTP request code
Need easy-to-apply features like retry, logging, and timeout
Want a request layer reusable across Next.js RSC and CSR

👉 Check out jin-frame

With jin-frame, you’ll never again panic over “The host changed, now what?”

AsyncContext, easily managing shared data

ByungJoon Lee — Mon, 25 Mar 2024 18:00:00 +0000

Background

This document introduces the AsyncContext feature. AsyncContext is a feature in TC39 Stage2. I introduce it because it has been included in the Node.js environment since v12 and continues to be improved in versions like v16, v18, v20, etc.

When running a synchronous function, creating a context before running the function allows the function to maintain and utilize the context while it runs. Synchronous functions can utilize the context because no other functions are executed while it is executed, so the value of the context can be guaranteed if the executing function does not change it, but asynchronous functions cannot guarantee the value of the context because other functions may be executed. Therefore, it is inconvenient to keep passing values such as tracking id, request id, etc. for tracking or settings such as language, cache life cycle, etc. as arguments to the function.

const Polyglot = require('node-polyglot');

const polyglot = {
  ko: new Polyglot({
    phrases: {
      hello_name: '안녕하세요! %{name}님',
    },
  }),
  en: new Polyglot({
    phrases: {
      hello_name: 'Hola %{name}',
    },
  }),
};

function child01(lang: string) {
  return polyglot[lang].t('hello_name', { name: 'hello' });
}

function child02(lang: string) {
    return { message: child01(lang) };
}
function child03(lang: string) {
    return child02(lang);
}
function child04(lang: string) {
    return child03();
}
function child05(lang: string) {
    return child04(lang);
}

function parent(req: FastifyRequest) {
  const lang = req.headers['accpet-language'];
    const message = child05(lang);
    return { ...message, id: 1 };
}

In the example above, the parent function uses the child05 function to get the message value, but the child05 function actually runs several other functions to get the message.

In the example code above, you can see that child02, child03, child04, and child05 don't use the language argument value, but the lang value is still passed as an argument to the child01 function to pass the language value. However, we can easily change this structure by utilizing context.

const { AsyncLocalStorage, AsyncResource } = require('async_hooks');
const store = new AsyncLocalStorage();
const Polyglot = require('node-polyglot');

const polyglot = {
  ko: new Polyglot({
    phrases: {
      hello_name: '안녕하세요! %{name}님',
    },
  }),
  en: new Polyglot({
    phrases: {
      hello_name: 'Hola %{name}',
    },
  }),
};

async function child01() {
  const currentStore = store.getStore();
  console.log('language: ', currentStore.lang);
  return polyglot[currentStore.lang].t('hello_name', { name: 'hello' });
}

async function child02() {
  return { message: await child01() };
}
async function child03() {
  return child02();
}
async function child04() {
  return child03();
}
async function child05() {
  return child04();
}

async function parent(req) {
  const lang = req.headers['accpet-language'];

  const result = store.run({ lang }, async () => {
    const resource = new AsyncResource('fastify-async-context');
    return resource.runInAsyncScope(async () => {
      const message = await child05(lang);
      return { ...message, id: 1 };
    });
  });

  return result;
}

In this example, unlike before, you can see that the lang value is not passed as an argument to the child01, child02, child03, child04, and child05 functions. Even though it is not passed as an argument, you can see that the child01 function uses AsyncContext to read the language value.

You can expect to be more productive and better able to utilize a variety of data because you won't have to keep passing AsyncContext the information it needs as function arguments.

Case study of AsyncContext

I'm going to describe in more detail my experience using AsyncContext in a useful way. However, browsers don't support AsyncContext yet, so we have to use alternatives like zone.js. So let's take a look at how we can utilize AsyncContext in a Node.js environment.

Request ID & Tracking ID

Giving every request a unique ID is useful for analyzing problems in case of failures, bugs, etc. fastify.js provides the ability to generate Request IDs.

const tidSymbol = Symbol('tid')
const fastify = require('fastify');
const server = fastify({ 
  genReqId: (req) => {
    const tid = randomUUID();
    req[tidSymbol] = tid;
    return tid;
} });

The request is now given a unique UUID, and once we have this UUID, we can track the request. Let's make it a little more useful. Store the UUID in the AsyncContext.

const fastify = require('fastify');
const { AsyncResource, executionAsyncId } = require('async_hooks');
const  { fastifyRequestContext } = require('@fastify/request-context');
const crypto = require('crypto');

const tidSymbol = Symbol('fastify-request-context-tracking-id')
const resourceType = 'fastify-request-context';

// Create fastify server with request ID generator
const server = fastify({ 
  genReqId: (req) => {
    const tid = crypto.randomUUID();
    req[tidSymbol] = tid;
    return tid;
  } 
});

server.register(fastifyRequestContext, {
  defaultStoreValues: (req) => ({
    tid: req.id,
    lang: req.headers['accept-language'],
    type: resourceType,
    triggerAsyncId: executionAsyncId(),
  }),
  createAsyncResource: () => new AsyncResource(resourceType),
});

Now we can access req.id from every fastify request handlers, and use AsyncContext in other functions to extract the request ID.

TypeORM with AsyncContext

TypeORM is a library that allows various databases to be used in the Node.js environment. ORM libraries provide the ability to log the queries they execute. TypeORM also provides the feature to log all queries, slow queries, query errors, and more. Combining the logging features with the Request ID mentioned earlier makes for a useful log.

import { AbstractLogger } from "typeorm"

export class MyCustomLogger extends AbstractLogger {
  /**
   * Write log to specific output.
  */
  protected writeLog(
        level: LogLevel,
        logMessage: LogMessage | LogMessage[],
        queryRunner?: QueryRunner,
    ) {
        // implementation of writeLog ...
    }

    /**
   * Logs query that is slow.
   */
  logQuerySlow(time: number, query: string, parameters?: unknown[], _queryRunner?: QueryRunner) {
    if (isFalse(this.isLogEnabledFor('query-slow'))) {
      return;
    }

      const store = getAsyncStore();
      console.log(`[${store.tid ?? randomUUID()}][${time}]show query: `, query, parameters);
  }
}

The example above logs the slow query with a tid, where tid is the request.id you stored in AsyncLocalStorage before. This allows you to quickly track which APIs are causing the slow queries, and is useful for planning fixes by knowing how often your APIs are being called.

translate with AsyncContext

I use the i18n library to create multilingual messages. I use node-polyglot, which requires me to decide which language to use before using the translate function. To determine the language, I have to keep passing the language to different functions, as mentioned in the background, and this is where AsyncContext can be used to simplify the process.

getAsyncStore function

We've seen situations where it's useful to use AsyncContext, so let's see how we can get AsyncLocalStorage. There are two ways you can get AsyncLocalStorage. The first way is to use Hooks to create a copy of the AsyncResource when it is created and destroyed. This approach is explained in Getting per-request context in NodeJS with async_hooks
. The second method is to use executionAsyncResource.

import { executionAsyncResource } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';

export function getAsyncStore(): { [key: string]: unknown } {
  const acquiredExecutionAsyncResource = executionAsyncResource() as {
    [key: string | symbol]: unknown;
  };
  const keys = Object.getOwnPropertySymbols(acquiredExecutionAsyncResource);
  const store = keys
    .map((key) => acquiredExecutionAsyncResource[key])
    .find((element): element is { tid: string } => typeof element === 'object' && element != null);

  if (store?.tid == null) {
    return `unde${randomUUID().substring(4)}`;
  }

  return store.tid;
}

You can use the Object.getOwnPropertySymbols function to extract the key of the AsyncResource, and that way you can get the AsyncLocalStorage. It doesn't matter which method you choose, but in my personal experience, the first method sometimes doesn't retrieve the AsyncLocalStorage, so if you want it to work every time, I recommend using the second method.

Conclusion

AsyncContext is still in Stage 2, and if you look at the official Node.js reference documentation, each version has a slightly different implementation, so it may be difficult to use if you are using Node.js v16 or lower. Also, the specification may change because it is in Stage 2. Nevertheless, AsyncContext is attractive. It's very useful to be able to get a common value from somewhere without having to add all the arguments to a function, so if you're building a new environment or using Node.js v16 or later, you should definitely take a look at it. Thank you for reading the documentation so far!

ctix - barrel file generator using TypeScript Compiler API

ByungJoon Lee — Tue, 14 Nov 2023 10:00:00 +0000

Background

In the past, I've written barrel files for various open source projects and work-related libraries. Barrel files are often used to simplify import statements, or to allow libraries to be exported to other projects. I've seen them in action recently, especially in the Next.js project, where they've been utilized to improve performance.

Problems when developers write their own barrel files

At first, you'll probably write most of your barrel files by hand, but since it's a fairly repetitive task, you'll probably want to find a tool to automate it. There are a couple of tools to automatically write barrel files.

CLI
IDE
- VSCODE - TypeScript Barrel Generator
- WebStorm - Barrels

These tools are awesome, but they mostly work based on directory traversal and filenames. While this works well in many cases, it has limitations in some situations. For example, eslint-config-airbnb recommends writing a class or function in a single file, and thus prefers to use default export. In the case of default export, the filename and the name of the default export statement may not match, but directory traversal and filename-based approaches cannot separate filenames from variable names.

These tools also have the limitation of not being recognized for empty files or test cases. Test cases can be filtered out through the glob pattern, but recognizing empty files is a challenge. Furthermore, barrel files are a collection of multiple export statements in one file, which can cause compilation errors if there are duplicate names. It is difficult to reliably filter out these duplicates with filename-based processing.

Considering these points, I came to the conclusion that while directory traversal and filename-based approaches are quick and easy, they may not be useful in complex projects. I recognized the need for a different approach.

Automate barrel file writing with the TypeScript Compiler API

At first, I tried to solve the problem with a directory traversal and filename-based approach. I developed and used create-ts-index for this purpose, but after experiencing the previously mentioned issues, I recognized the limitations of this approach. I decided that it needed to be improved, so I developed and used ctix. ctix utilizes the Typescript Compiler API to write barrel files. This approach solved most of the problems I mentioned earlier.

The default export statement can handle different filenames and variable names

// button.component.ts

const Button = () => {
  return <button>test</button>;
};

Button.getInitialProps = () => { /* ... */ };

export default Button;

The file is named button.component.ts, but in the export statement it is named Button. Since ctix uses the Typescript compiler API to get variable names, the above can be added to the barrel file without error.

When there are multiple export statements in a file, it is possible to exclude only some of them from the barrel file.

export function dog() {
  // ...
}

// @ctix-exclude-next
export function peach() {
  // ...
}

export function cat() {
  // ...
}

If you look at the code above, you'll see that I've excluded peach, which has a different personality, from the barrel file. In this case, the barrel file is written as shown below.

export { dog, cat } from './animal';

In addition, ctix can write barrel files with filenames using module mode since version 2.1. Front-end component projects such as Vue and Svelte have a different syntax and cannot be parsed using the TypeScript compiler API, so typically Vue and Svelte components use filenames as names and are registered as modules in TypeScript as type files.

declare module '*.vue' {
  import Vue from 'vue';
  export default Vue;
}

The above code is a type file written to make files with the .vue extension recognized as modules by Typescript. With this setup, Typescript cannot directly parse the contents of a .vue file, but it will recognize it as a module. ctix takes advantage of this, first writing barrel files for Vue components based on filenames and directory traversal.

/// <reference path="../types/vue.d.ts" />

import Button from './Button.vue';
import Accordion from './Accordion.vue';

export { Button, Accordion };

Unfortunately, the reference setting with the triple slash in the first line must be handled by the developer. It can be passed using the directive option. This will automatically add the TypeScript compiler API to the barrel file and affect the next barrel file writing operation, meaning that both actual TypeScript files and Vue components will be able to write barrel files. I've uploaded a working example to example/type10 and a configuration file.

Duplicate export statements can also be better detected.

marvel.ts

export const ironman = 'ironman is awesome!'

avengers.ts

export const ironman = 'avengers assemble!'

Because of the different file names, duplicate detection is difficult to do with filename and directory traversal, but it can be achieved using the Typescript compiler API. To prevent errors in situations like this, ctix excludes duplicate statements and outputs warning messages to help developers recognize errors.

By using the TypeScript compiler API, it can correctly handle most of the export syntax used by TypeScript, and it can write barrel files using actual code, as compared to the filename and directory traversal approach.

Conclusion

ctix is a tool that writes barrel files correctly in a variety of situations. It's designed to free developers from having to care about barrel files themselves, and offers a number of features including duplicate detection, exclusion of particular statements, and support for Vue and Svelte components. However, because it uses the TypeScript compiler API, it is slower than barrel file writing based on filenames and directory traversal. It also requires a tsconfig.json file to be provided for it to work correctly. To solve these problems, I've added the ability to generate a configuration file via an interactive prompt with the init command, and improved performance by minimizing the scope of the TypeScript compiler API's project analysis.

With ctix, you can automate the hassle of writing barrel files. Give it a try and let us know what you think so for us to make ctix even better!

In-Depth guide for TypeScript Library

ByungJoon Lee — Mon, 13 Nov 2023 12:12:45 +0000

Background

It's a common approach in development projects to separate common business logic into functions or classes within the same project for reuse. As a project grows in size, some logic may be more efficiently isolated into separate packages and used in other projects. In my experience, functions like login, logout, and logging are easier to maintain and adapt in the long run if they are separated into separate library packages. I've reviewed several articles on writing library packages, but here I'm going to summarize some of the more specialized topics that aren't covered in those articles.

What's the problem?

Barrel file, edit over and over again

To simplify the import syntax, the file that holds the export syntax is called a barrel file.

barrel file

export { Button } from './button/index.ts'
export { Accordion } from './accordion/index.ts'
export { Notification } from './notification/index.ts'

other file

import { Button } from '../../src'

Barrel files are commonly found in component library projects. For example, you can find a Barrel file in the Mantine project. Since there are often no dependencies between each component or feature in a library project, it often happens that the bundler does not include all the files even when using a dependency graph. This is where the barrel file comes into handy. By specifying the barrel file in the main and module fields of the package.json file, it also serves as a point of execution for the Node.js interpreter or the browser's script tag. Barrel files are often written by developers themselves because they fulfill an important function.

However, it is a big challenge for developers to write barrel files themselves. In projects like Mantine and date-fns, which are already very large, it is not easy to write a barrel file every time there is a change, and if it is included in a VCS(e.g. git), it increases the probability of conflicts when multiple developers collaborate. Therefore, I thought there is a need for a way to automatically generate barrel files based on certain rules and not include them in a VCS.

Can I use Paths Re-Maps ?

To import classes, functions, constants, etc. from another script in TypeScript and JavaScript, you need to enter the relative path to the script you want to call from the current script.

import chunkArray from '../../tools/array/chunkArray';

async function getBulkInsertFruit(fruits: string[]) {
  await Promise.all(chunkArray(fruits, 5).map(async (chunk) => insert(chunk)));
}

In the example code above, you can see that we imported the function with a relative path. Using relative paths is inconvenient because the import statement is always different. Using a barrel file doesn't improve things much, and it's a difficult problem to solve without the help of an IDE. That's why TypeScript provides the Paths Re-Map feature.

import chunkArray from '#/tools/array/chunkArray';

async function getBulkInsertFruit(fruits: string[]) {
  await Promise.all(chunkArray(fruits, 5).map(async (chunk) => insert(chunk)));
}

If you look at the example code above, you can see that we've imported the chunkArray function as if we were using an absolute path. This feature allows you to use the same import statement for all your files and reduces the amount of work when refactoring to change paths or filenames. However, since this feature is not provided by ECMA Script, it creates a number of problems: not only do you have to tell your test frameworks like jest and vitest to set up Paths Re-Map, but you also have to tell your bundlers about it. It also affects the bundling of .d.ts files, which we will discuss in the next chapter. Since this issue is the same for library packages and applications alike, we also need a way to work around it.

bundling for `.d.ts`

In order for a TypeScript-based library package to be used by other TypeScript projects, it is necessary to provide the type files (.d.ts) along with the JavaScript files. To do this, the types field in the package.json file sets the entry point for the type files. However, there is no official way to effectively bundle type files. There was a discussion about this, but the issue was closed without a clear solution to the problem.

Using TypeScript's Paths Re-Map feature further complicates matters. TypeScript has defined module renaming for Paths Re-Mapped modules as the role of the bundler, which means that when using Paths Re-Map, providing a type file requires you to do two things: convert the Paths Re-Map of that type file to a relative path and bundle it. This can make it difficult for library package developers to efficiently manage and ship type files.

How can we solve it?

If you don't use bundlers and Paths Re-Map, you can avoid the issues involved. However, you'll still need to manually write your barrel files, and as your library package grows in size, it can be inefficient to use only the basic functionality. So, let's take a look at how you can solve the problem.

Automatically generate a barrel file

I've been working on automating barrel files for a long time, and in the process have developed ctix. The 1.x version had some inconveniences, but with the 2.x version, I've improved these issues and made it more user-friendly. ctix uses the TypeScript Compiler API to automatically generate barrel files by extracting statements containing the export keyword. The advantage of ctix is that barrel files are automatically generated, so you don't have to manage them separately in your version control system (VCS), e.g. git. It also has the advantage of always generating compilable barrel files because it uses the TypeScript Compiler API to extract only export statements.

`.d.ts` bundling

This is a really hard problem. For now, there are discussions going on within the TypeScript community to resolve this issue, but they are inconclusive, and have been for a long time. So we need to use external tools to solve this problem. Currently, the popular .d.ts bundling tools are as follows

There are many more tools than those listed above. You can check out discussion and comparison of bundling tools. Unfortunately, choosing the right tool among them is a process that you'll have to experiment with and decide for your own project needs. For example, dts-bundle-generator, API Extractor, and rollup-plugin-dts do not support .d.ts.map files. Also, API Extractor and dts-bundle-generator do not have chunking capabilities, rollup-plugin-dts is currently in maintenance mode, and the default export and export statements differ in the way different bundlers generate output. Therefore, you should carefully select and use the most appropriate tool based on your project's configuration.

The dts-bundle-generator is a lightweight and easy tool. If you pass a barrel file generated using ctix to dts-bundle-generator and just specify the path to the output file, it will work fine in most cases without any additional setup. However, if you are using the latest version of Fastify.js in your backend development, you may encounter an issue where bundling fails because Symbol.asyncDispose is not found. This is due to the way the dts-bundle-generator loads only necessary modules for performance optimization, which prevents it from loading some .d.ts files. There is a workaround being discussed for this, but it didn't work in my case. Nevertheless, the tool generally works well and is easy to use with a few simple option settings, and I recommend testing in a live environment if you are considering adopting it.

The rollup-plugin-dts is a plugin that is currently in maintenance mode, but still works well. However, this plugin only performs bundling correctly for .d.ts files that do not use Paths Re-Map. By the way, even if you create a .d.ts file using @rollup/plugin-typescript, this does not fully resolve Paths Re-Map. For this, you need to use tsc-alias to resolve Paths Re-Map issues. After resolving Paths Re-Map, bundling with rollup-plugin-ts works well to generate a .d.ts file. However, even with this method, the ability to generate .map files and the chunking feature is not available. Given that library projects are often bundled as part of JavaScript projects, I think these limitations are acceptable.

I use ctix for barrel file generation and rollup-plugin-dts and tsc-alias for bundling. However, this method may not be suitable for monorepos consisting of multiple packages or if the composite option is set in tsconfig. Before introducing ctix or .d.ts bundling tools to your ongoing library packages, it is important to test them and make sure they are suitable before applying them.

default export, export

There has been some discussion about the use of default export vs export, but it's hard to conclude unequivocally that one is better. For example, eslint-config-airbnb recommends using default export. However, when developing ctix and using the TypeScript Compiler API, I noticed that all of the default exports were named default. Since all of the import statements in a barrel file are collected in one place, duplicate names can cause problems. The default export is similar to an anonymous export because it has the same name. If the original statement has a name, you can use the alias keyword to give it the original name, but since different .d.ts bundlers handle aliases differently, the result may not be what you intended.

Thus, default export can cause complicated syntax issues in library packages that need to be used by other projects. Because different bundling tools work differently, and because developers have different preferences on how to handle them, I believe that default export should only be used in components that cannot be handled by TypeScript, such as Vue and Svelte. In other cases, using export minimizes the chance of problems.

Conclusion

Library package projects are useful when developing. With npm, there are tons of library packages available. I've been creating and using libraries out of necessity, and in doing so, I've felt the need to organize how I go about scaffolding my library package projects. There's a lot of good material out there about setting up bundlers and overall scaffolding, but topics like Paths Re-Map and .d.ts bundling are relatively uninformed, so I've put together some thoughts on that. The following is by no means a definitive answer, but it's the way I apply it when working on library projects.

Automatically generate an barrel file using ctix
Bundling .d.ts files using rollup-plugin-dts and tsc-alias
Bundling with esbuild
use vitest or jest as a test runner
1. use vite-tsconfig-paths to pass Paths Re-Map
2. use ts-jest and set up Paths Re-Map

I've uploaded the typescript-lib-boilerplate repo.for your reference. How do you guys work when developing library projects? If you have any good tips, please let me know, thanks!

ERDIA: TypeORM entity specification documentation tool

ByungJoon Lee — Mon, 28 Aug 2023 17:00:00 +0000

Introduction

I am a developer using Node.js, TypeScript. Entity Specification documents and ER diagrams are important for backend development. GUI tools automatically generate Entity Specification documents and ER diagrams, but they are difficult to include in CI. So, I developed ERDIA, that generates Entity Specification documents and ER diagrams using CLI interface.

In this article, I will introduce how to use ERDIA and the results of using it.

ERDIA

ERDIA is a tool for generating Entity Specification documents and ER diagrams with a CLI interface. It supports formats like HTML, Markdown, PDF, SVG, PNG. and can be integrated into CI. In particular, if you set the output format to HTML documents, it till generate documents per version base on package.json version field or specific version file. I integrate it into my CI and deploy it to AWS S3. This increases productivity because it ensures each documents freshness.

TypeORM

TypeORM is one of the popular ORM tools.

The image above is a chart comparing three popular ORM tools from the npmtrends.com. ERDIA only supports TypeORM for now, but the roadmap is to support Sequelize and Prisma as well.

Getting Started

If you have a project that uses TypeORM, you can apply ERDIA now.



npm i erdia --save-dev

And then, I recommend running the initialization command.



npx erdia init

The initialization command asks a few questions about what is needed to run ERDIA and then creates the .erdiarc file. Now It's time to create your first document.



npx erdia build

If you are using TypeScript, please refer to the TypeScript section.

Format

ERDIA generates documents in HTML, Markdown, PDF and Image formats. Each document has the following characteristics.

	HTML	Markdown	PDF	Image
Entity Specification	O	O	O	X
ER diagram	O	O	O	O
ETA Template	O	O	O	X
Entity Version Management	O	X	X	X
SVG or PNG	O	X	X	O

Markdown, PDF, Image generate document single version. But HTML document contain multiple version.

Template

ERDIA uses the ETA template engine to generate documentation. The reason for using a template engine is that it allows you to customize the documentation the way you want it. If you want to customize documentation that ERDIA generates run the following command.



npx erdia eject

You can find the default template in template directory. Customize you want it. When run it, you'll need to pass the template path as follows to generate a modified document.



npx erdia build --template-path ./template

TypeScript

If your TypeORM entity is written in TypeScript, you have to run ERDIA using ts-node or tsx as follows.



TS_NODE_PROJECT="./tsconfig.json" node \
  -r ts-node/register \
  ./node_modules/erdia/dist/cli.js build -d [your dataSourcePath] --format html -o ./dist/html

If you've use a re-map path in your project, you have to pass it up to tsconfig-paths like this,



TS_NODE_PROJECT="./tsconfig.json" node </span>

  -r ts-node/register </span>

  -r tsconfig-paths/register </span>

  ./node_modules/erdia/dist/cli.js build -d [your dataSourcePath] --format html -o ./dist/html

Conclusion

I generate ERDIA HTML documents during Jenkins build process and deploy them to AWS S3(CDN). This task, I always have an up-to-date Entity specification, ER diagram and can share it with my co-workers.

Good documentation, well managed documentation, improves project productivity. If you're using TypeORM now, I strong recommend adopt ERDIA!

DEV Community: ByungJoon Lee

jin-frame: Declarative, Type-Safe HTTP Requests in TypeScript

A Common Story

Why jin-frame?

Example: Inheritance for Clean API Structure

Base Class with Common Config

Child Class: Pokémon by Name

Usage

Why This Matters

Conclusion

AsyncContext, easily managing shared data

Background

Case study of AsyncContext

Request ID & Tracking ID

TypeORM with AsyncContext

translate with AsyncContext

getAsyncStore function

Conclusion

ctix - barrel file generator using TypeScript Compiler API

Background

Problems when developers write their own barrel files

Automate barrel file writing with the TypeScript Compiler API

Conclusion

In-Depth guide for TypeScript Library

Background

What's the problem?

Barrel file, edit over and over again

Can I use Paths Re-Maps ?

bundling for .d.ts

How can we solve it?

Automatically generate a barrel file

.d.ts bundling

default export, export

Conclusion

ERDIA: TypeORM entity specification documentation tool

Introduction

ERDIA

TypeORM

Getting Started

Format

Template

TypeScript

Conclusion

bundling for `.d.ts`

`.d.ts` bundling