DEV Community: Danny Kim

Sync Cursor Settings the Dotfiles Way

Danny Kim — Fri, 22 Aug 2025 04:20:30 +0000

If you migrated from VS Code to Cursor, you might have noticed that Cursor doesn't support settings sync.

https://forum.cursor.com/t/sync-of-keybindings-and-settings/31

In this post, I'd like to share how to sync your Cursor settings & extensions the traditional way, similar to how you sync .zshrc and .vimrc files.

You put the settings file in a git repo.

Settings

Syncing your settings is simpler than syncing extensions, so let's start there.

What you need to do is:

Save the settings.json file in a git repo.
Clone the repo on your machine.
Create a symlink to that settings.json file.

Git Repo Structure

Your repo should be structured like this if you're on Linux.

repo
└── cursor
    └── .config
        └── Cursor
            └── User
                └── settings.json

And like this if you're on Mac.

repo
└── cursor
    └── Library
        └── Application Support
            └── Cursor
                └── User
                    └── settings.json

Stow

You can use stow to create settings.json symlink in your home directory.
https://www.gnu.org/software/stow/

Install stow, and run this command from your repo root.

stow --no-folding -t ~ *

Technically, --no-folding flag is optional, but I recommend you use it.

Once you run this command, your Cursor settings file is symlinked to the git repo. You can commit changes and push/pull.

Extensions

Syncing Cursor extensions is a little more complicated than syncing settings. Unlike settings.json, Cursor extensions are not saved as a text file. The extensions are saved as packages under ~/.cursor/extensions/.

What we have access to:

cursor --list-extensions command prints out the extension IDs that are currently installed.
cursor --install-extension <extension-id> command can install the extension.
cursor --uninstall-extension <extension-id> can do the opposite. Note: there's a bug that prevents you from uninstalling multiple extensions in one command.

From these ingredients, we can whip up a script that syncs extensions across machines.

Compare the mtime (last modified time) of the ~/.cursor/extensions/extensions.json file and the list file (more on the list file later).
- (case 1) If the extensions.json file is newer, we generate a new list file. Dump the output of cursor --list-extensions command to [repo]/.cursor/extensions/list.txt.
- (case 2) If the extensions.json file is older, then it means the extensions are outdated.
  - Get which extensions are currently installed by running cursor --list-extensions.
  - Install extensions that are not currently installed but exist in the list file.
  - Uninstall extensions that are currently installed but do not exist in the list file.

You can run this script manually or as a git post-merge hook.

Working Example

If you'd like to see how the extension syncing script is written, please check out my dotfiles repo.

https://github.com/0916dhkim/dotfiles/blob/b5f8558328ffe668750f94e2ab0afbc52eb3f6e7/post-merge.js (latest commit at the time of writing)

About Reverse Proxy

Danny Kim — Mon, 09 Oct 2023 05:50:28 +0000

Being able to stitch together a website with multiple services is a powerful technique. With this technique, teams don't need to use one single tool to build every page on their websites. Designers can iterate on the landing page using Webflow without affecting the dev team, the customer success team can edit the helpdesk items independently, and all those pages look cohesive to the main app from users' perspective!

This is done through a thing called reverse proxy.

What is Reverse Proxy?

Reverse proxy is a server that sits in front of all other servers so that users can't tell which server is serving each content. A reverse proxy makes it feel like everything comes from the same domain. Please see the following diagram.

Here's how it works:

Client sends requests to the proxy server.
The proxy server decides which server should handle the request.
The proxy server sends the request to the actual server and get the response.
The proxy server sends the response to the client.

Then why do we call this reverse proxy? It's because forward proxy is a middleman for clients. Reverse proxy is reverse because it is a middleman for servers.

Of course, we can have more than 2 servers behind the proxy!
If we run multiple servers of the same type behind a proxy, that's called load-balancer. We can stitch together multiple types of servers with a proxy too.

Example: Webflow + React

Shall we take a look at a more concrete example? In this post, I will present a use-case of combining two websites under the same domain. One built with Webflow, and the other built with React.

Webflow is a no-code website builder that allows designers to directly implement their designs into pages. React is all-code (?) tool that allows us to build sophisticated features on web.

I'll use Vercel, React, and Webpack in this post, but you can setup reverse proxy with many different technologies. You can use any of the below:

Apache HTTP server
Nginx
Vercel
Firebase
Netlify
Cloudflare (this article is a good read about reverse proxy if you want to dig deeper into the concept.)

Vercel

When you bundle a React app with Webpack, the result is a HTML file, a JS file, and static assets. Vercel is (among other things) a platform to host these files + some capabilities for proxy.

We deploy a site on Vercel by uploading static files (e.g. js bundle, html, css, images) and a config file named vercel.json. By default, Vercel will only serve the static files we uploaded. We can tell it to proxy some requests by defining rewrites in the config file.

{
    "$schema": "https://openapi.vercel.sh/vercel.json",
    "scope": "our-site",
    ...
    "rewrites": [
        { "source": "/", "destination": "https://example.webflow.io/" },
        { "source": "/blog", "destination": "https://example.webflow.io/blog" },
        { "source": "/api/:path(.*)", "destination": "https://example.fly.dev/api/:path" },
        { "source": "/(.*)", "destination": "/_index.html" }
    ]
}

Let's look into each rewrite rule more closely:

{ "source": "/", "destination": "https://example.webflow.io/" } Assuming we deploy this site to example.com, Vercel will serve https://example.webflow.io/ when a client requests https://example.com/.
{ "source": "/blog", "destination": "https://example.webflow.io/blog" } Similar to above. It proxies https://example.com/blog to https://example.webflow.io/blog.
{ "source": "/api/:path(.*)", "destination": "https://example.fly.dev/api/:path" } Now this is Vercel's syntax for defining wildcard proxy. https://example.com/api/user will be proxied to https://example.fly.dev/api/user, https://example.com/api/user/1234 to https://example.fly.dev/api/user/1234, etc.
{ "source": "/(.*)", "destination": "/_index.html" } A couple things to mention here.
- This catch-all proxy rule is required for serving a single-page-application. You can read more about what is required when configuring servers for client-side-routing: https://create-react-app.dev/docs/deployment/#serving-apps-with-client-side-routing
- Static files takes precedence over rewrite rules on Vercel. So if there is /index.html file, it will take precedence over a rewrite rule for the / route. That's why we name our index page _index.html for the SPA here. We want to make sure the / route to be proxied to the webflow page.

That's all that's needed for configuring proxy for our Vercel deployment!

Webpack

One problem: our local dev environment doesn't make use of Vercel proxy. Webpack dev server has a separate way of configuring reverse proxy for local environment.

Here's an example webpack.config.js. Explanation is below the code snippet.

const path = require("path");
const HtmlWebpackPlugin = require("html-webpack-plugin");
const vercel = require("../vercel.json");

/** @type {import("webpack").Configuration} */
const config = {
    mode: "development",
    devtool: "inline-source-map",
    devServer: {
        port: 3000,
        open: false,
        hot: true,
        historyApiFallback: {
            index: "/_index.html",
        },
        proxy: buildProxyFromVercelJson(vercel.rewrites),
        devMiddleware: {
            index: false, // for root proxy
        },
    },
    entry: "./src/index.tsx",
    module: {
        rules: [
            {
                test: /\.(js|jsx)$/,
                use: "babel-loader",
                exclude: /node_modules/,
            },
            {
                test: /\.(ts|tsx)$/,
                use: "ts-loader",
                exclude: /node_modules/,
            },
        ],
    },
    resolve: {
        extensions: ["*", ".js", ".jsx", ".ts", ".tsx"],
    },
    plugins: [
        new HtmlWebpackPlugin({
            // Usually HtmlWebpackPlugin will generate an index.html file,
            // but we need to use a different filename so that we can reverse proxy the root route on Vercel.
            // Vercel will serve the index.html file if it exists instead of proxying to the landing page.
            template: "./public/_index.html",
            favicon: "./public/favicon.svg",
            filename: "_index.html",
        }),
    ],
    output: {
        path: path.resolve(__dirname, "dist"),
        filename: "bundle.js",
        publicPath: "/",
    },
};

/**
 * Transforms the Vercel rewrite config into a webpack dev server proxy config.
 * @param  {{source: string, destination: string}[]} rewriteConfig Vercel rewrite config
 * @returns Equivalent webpack dev server proxy config
 */
function buildProxyFromVercelJson(rewriteConfig) {
    const proxyConfig = [];
    for (const rule of rewriteConfig) {
        if (rule.source === "/(.*)") {
            // skip the default rewrite
            continue;
        }
        const SOURCE_WILD_CARD_REGEX = /\/:path\(\.\*\)$/;
        const DESTINATION_WILD_CARD_REGEX = /\/:path$/;
        const isWildCard = SOURCE_WILD_CARD_REGEX.test(rule.source);
        if (isWildCard) {
            proxyConfig.push({
                context: rule.source.replace(SOURCE_WILD_CARD_REGEX, "/"),
                target: rule.destination.replace(DESTINATION_WILD_CARD_REGEX, ""),
                pathRewrite: (path) => {
                    const re = `^${rule.source.replace(SOURCE_WILD_CARD_REGEX, "(.*)")}$`; // example: /api/:path(.*) -> ^/api/(.*)$
                    return path.match(re)[1];
                },
                changeOrigin: true,
            });
        } else {
            proxyConfig.push({
                context: (path) => path === rule.source,
                target: rule.destination,
                pathRewrite: () => "",
                changeOrigin: true,
            });
        }
    }
    return proxyConfig;
}

module.exports = config;

HtmlWebpackPlugin is responsible for generating a bundled HTML file. We configure it to output to _index.html instead of the default filename index.html because Vercel needs it for / route proxy as mentioned in the previous section.

config.devServer.historyApiFallback.index should be set to /_index.html. This configuration is essentially doing the same thing as Vercel's { "source": "/(.*)", "destination": "/_index.html" } rule. It enables our SPA to work on multiple paths.

Also, config.devServer.devMiddleware should be set to false in order for the root route proxy to take effect. The dev server returns the SPA's HTML if the option is set to true.

Finally, we convert rewrite rules from vercel.json config file into config.devServer.proxy using an utility function called buildProxyFromVercelJson.

buildProxyFromVercelJson

Let's dissect what's going on within this utility function.
The function is a big for-loop that iterates over each rewrite rules from Vercel config. It translates each rule to what webpack-dev-server can parse and return the resulting array.

The first thing we do in the for-loop is skipping the rule for /(.*) because that part is handled by config.devServer.historyApiFallback option.

Then we translate each rule. webpack-dev-server uses http-proxy-middleware under the hood, and here's how to translate each field.

context: This function determines whether the rule applies to the given path or not.
- For wildcard paths, match all paths that begins with the source route.
- For non-wildcard paths, check if the path is exactly equal to the source route.
target: Proxied location. It corresponds to Vercel's destination option.
pathRewrite: This function determines how to translate the source route's path to the destination path.
- For wildcard paths, imitate how Vercel handles wildcard substitution. Detect the :path(.*) part of the source path and append it at the end of the destination route.
- For non-wildcard paths, use the destination route exactly as-is.
changeOrigin: Always true.

With this webpack config, npx webpack serve will spin up a dev server with reverse proxy. Opening http://localhost:3000/ on a browser will show the webflow page!

Conclusion: The Chimera Website

In this example, we stitched together Webflow and a React app together. The same technique can be applied to add many more things behind the proxy. Like a blog, documentation, online store, CDN for large files (images, video, software packages).

The key point is to keep the experience consistent between the deployed website & the local dev environment. Vercel + Webpack is just an example, and you should be able to apply this pattern to other platforms & tools as well!

Notes
buildProxyFromVercelJson utility function doesn't support all Vercel rewrite wildcard syntax. It only matches when the wildcard is :path(.*) at the end of the route.

Simple TypeScript Mutex Implementation

Danny Kim — Wed, 22 Mar 2023 02:50:06 +0000

JavaScript on browser is single-threaded, but JS developers still need to worry about interleaving timelines because the language has the concept of re-entrancy. An async function can stop in the middle of execution, yield its way to another function, then resume later.

There can be unexpected outcomes when timeline of multiple functions get intertwined, and we call that "race conditions".

One way to deal with this complexity is to lock the critical section so that only one piece of code can access it at a time. That prevents any race conditions caused by two functions simultaneously accessing the same resource.

The lock is called mutex because the locked resource becomes mutually exclusive. Here is an example implementation with annotation:

/**
 * A lock for synchronizing async operations.
 * Use this to protect a critical section
 * from getting modified by multiple async operations
 * at the same time.
 */
export class Mutex {
    /**
     * When multiple operations attempt to acquire the lock,
     * this queue remembers the order of operations.
     */
    private _queue: {
        resolve: (release: ReleaseFunction) => void;
    }[] = [];

    private _isLocked = false;

    /**
     * Wait until the lock is acquired.
     * @returns A function that releases the acquired lock.
     */
    acquire() {
        return new Promise<ReleaseFunction>((resolve) => {
            this._queue.push({resolve});
            this._dispatch();
        });
    }

    /**
     * Enqueue a function to be run serially.
     * 
     * This ensures no other functions will start running
     * until `callback` finishes running.
     * @param callback Function to be run exclusively.
     * @returns The return value of `callback`.
     */
    async runExclusive<T>(callback: () => Promise<T>) {
        const release = await this.acquire();
        try {
            return await callback();
        } finally {
            release();
        }
    }

    /**
     * Check the availability of the resource
     * and provide access to the next operation in the queue.
     *
     * _dispatch is called whenever availability changes,
     * such as after lock acquire request or lock release.
     */
    private _dispatch() {
        if (this._isLocked) {
            // The resource is still locked.
            // Wait until next time.
            return;
        }
        const nextEntry = this._queue.shift();
        if (!nextEntry) {
            // There is nothing in the queue.
            // Do nothing until next dispatch.
            return;
        }
        // The resource is available.
        this._isLocked = true; // Lock it.
        // and give access to the next operation
        // in the queue.
        nextEntry.resolve(this._buildRelease());
    }

    /**
     * Build a release function for each operation
     * so that it can release the lock after
     * the operation is complete.
     */
    private _buildRelease(): ReleaseFunction {
        return () => {
            // Each release function make
            // the resource available again
            this._isLocked = false;
            // and call dispatch.
            this._dispatch();
        };
    }
}

type ReleaseFunction = () => void;

Example Usage

Let's say we want to add some items to a shopping cart and apply coupons at the same time. In order to prevent a race condition from producing incorrect total, we can use our mutex to run one operation at a time.

const shoppingCartMutex = new Mutex();

shoppingCartMutex.runExclusive(async () => {
  cart.add(items);
  total = await cart.calculateTotal();
});

shoppingCartMutex.runExclusive(async () => {
  await cart.applyCoupons();
  total = await cart.calculateTotal();
});

References

Simplify Business Logic with Reactive Architecture

Danny Kim — Mon, 13 Feb 2023 04:41:42 +0000

Expressing a complex business logic as a readable code is not an easy task. Also, refactoring can feel like shifting the complexity around rather than making it simpler. I'd like to show you a technique that can simplify your code: using Reactive Architecture.

Please take a look at this example:

class Feedback {
  create(user, message) {
    // Save the feedback on db.
    dbService.create("Feedback", message);
    if (user.isVip) {
      // Send notification on slack on VIP feedback.
      slackService.notify(message);
    } else {
      // Non-VIP feedbacks get deleted later.
      taskQueue.enqueue(
        "/tasks/delete-feedback",
        {id: message.id},
      );
    }
  }
}

As you can see, it is really common for a business logic to include side-effects like logging, messaging, analytics, and scheduling. The example code wraps the ugly part behind services methods (like slackService.notify), but you can see the function is clearly doing more than one thing. Basic extraction like below won't really improve anything here.

function enqueueDeleteTask(messageId) {
  taskQueue.enqueue(
    "/tasks/delete-feedback",
    {id: messageId},
  );
}

But we can simplify the code by splitting them into cause & effect. Also known as Reactive Architecture or event handlers.

class Feedback {
  constructor(options) {
    this.onVipFeedback = options.onVipFeedback;
    this.onNonVipFeedback = options.onNonVipFeedback;
  }
  create(user, message) {
    dbService.create("Feedback", message);
    if (user.isVip) {
      onVipFeedback();
    } else {
      onNonVipFeedback();
    }
  }
}

// usage
const feedbackService = new Feedback({
  onVipFeedback: (message) => {
    slackService.notify(message);
  },
  onNonVipFeedback: (message) => {
    taskQueue.enqueue(
      "/tasks/delete-feedback",
      {id: message.id},
    );
  },
});

This structure is much better than the original code because

Feedback.create method will not change when business logic changes for VIP feedback handling. It will stay short and readable.
Feedback.create method doesn’t depend on “slackService” or “taskQueue” anymore. This makes testing much easier.

The benefits of Reactive Architecture get amplified as your business logic gets more complicated. Try this technique next time you’re writing a complex code. The technique is pretty versatile so you can use it as easily in backend controllers as in React component functions.

Deep Mocking for Jest

Danny Kim — Thu, 09 Feb 2023 05:35:01 +0000

TLDR (deepMock implementation & example test code)

Most JavaScript test frameworks provide a way to "mock" a dependency. This is great because it lets you write better test code, but it can quickly get verbose if the module to mock is coupled tightly with the code under test.

Here's an example from Jest documentation:

jest.mock('../foo-bar-baz', () => {
  const originalModule = jest.requireActual('../foo-bar-baz');
  return {
    __esModule: true,
    ...originalModule,
    default: jest.fn(() => 'mocked baz'),
    foo: 'mocked foo',
  };
});

That's a piece of code to replace just 2 properties of a module. You can see the jest.mock call will get longer if

There are more properties to mock.
Each fake values are more complex.

This is a hassle because oftentimes, we don't care what the fake object does. We just want to avoid calling the actual dependency (like payment module, db access, etc) while not breaking the code under test.

Wouldn't it be nice if we could do this instead?

jest.mock('../foo-bar-baz', () => mockEverything());

Requirements

Let's think about what's required to build this magic. First of all, mockEverything needs to replace each child property with a mock.

// Requirement 1
const myMock = mockEverything();
myMock.a // <- this should be a mock too.

That means a child of a child should also be a mock. In fact, all nested properties should be a mock.

// Requirement 1 - corollary
const myMock = mockEverything();
myMock.a.b.c // <- this should be a mock.

Secondly, return value of a mock method should be a mock. If a mock method returns any other concrete value, there's a possibility of breaking the code under test.

// Requirement 2
const myMock = mockEverything();
const value = myMock(); // <- this should be a mock.

That looks like a good starting point. Let's attempt to implement this magical thing!

Building Deep Mock

JavaScript's built-in Proxy is perfect for this use-case because Proxy lets us redefine fundamental object operations like getting a property or calling a function.

Iteration 1

To satisfy Requirement 1, we can do something like this:

function deepMock() {
  return new Proxy(
    ["MOCK"], // object to "wrap". can be anything.
    {
      get() {
        // Redefine property getter.
        // Regardless of which key is requested,
        // always return another mock.
        return deepMock();
      },
    },
  );
}

Let's check.

const myMock = deepMock();
console.log(myMock.a); // MOCK
console.log(myMock.a.b.c); // MOCK

Ok it works as expected! Now onto Requirement 2:

function deepMock() {
  return new Proxy(
    ["MOCK"],
    {
      get() {
        return deepMock();
      },
      apply() {
        // Redefine function call.
        // Always return another mock.
        return deepMock();
      },
    },
  );
}

const myMock = deepMock();
console.log(myMock()); // MOCK

Great, are we done?

Problem: Because our proxy returns a new object every time, it can do funky things like this.

const myMock = deepMock();
myMock.a === myMock.a // false

Iteration 2

Let's fix that by adding a little cache in the closure.

// Use Symbol to avoid name collision with other properties.
const ReturnSymbol = Symbol("proxy return");
function deepMock() {
  const cache = {}; // cache in closure
  return new Proxy(
    ["MOCK"],
    {
      get(target, prop) {
        // Use the cached value if it exists.
        if (prop in cache) {
          return cache[prop];
        }
        // Otherwise, save a new mock to the cache and return.
        return (cache[prop] = deepMock());
      },
      apply() {
        // Similar to "get" above.
        if (ReturnSymbol in cache) {
          return cache[ReturnSymbol];
        }
        return (cache[ReturnSymbol] = deepMock());
      },
    },
  );
}

Cool, now property comparison works normally.

const myMock = deepMock();
myMock.a === myMock.a // true

Problem: there is still a problem when mocking a promise. JS engine calls .then method recursively to await a value. Take a look at this example.

const myMock = deepMock();
await myMock; // never ends

It falls into an infinite recursion of myMock.then(x => x.then(y => y.then(....

Iteration 3

We can fix the infinite recursion by limiting the number of consecutive .then calls.

const ReturnSymbol = Symbol("proxy return");
const ResolveSymbol = Symbol("proxy resolve");
// Set the limit to something practical.
const DEFAULT_PROMISE_DEPTH = 20;
function deepMock(promiseDepth = DEFAULT_PROMISE_DEPTH) {
  const cache = {}; // cache in closure
  return new Proxy(
    ["MOCK"],
    {
      get(target, prop) {
        if (prop in cache) {
          return cache[prop];
        }
        if (prop === "then" && promiseDepth === 0) {
          // break the loop when it hits the limit.
          return undefined;
        }
        return (cache[prop] =
          prop === "then"
            // recursively resolve as another mock with 1 less depth limit.
            ? (resolve) =>
                resolve((cache[ResolveSymbol] ??= deepMock(promiseDepth - 1)))
            : deepMock());
      },
      apply() {
        if (ReturnSymbol in cache) {
          return cache[ReturnSymbol];
        }
        return (cache[ReturnSymbol] = deepMock());
      },
    },
  );
}

Awesome! Our implementation is getting longer, but await does not hang anymore.

Problem: there is a problem when mocking a class.

const myMock = deepMock();
new myMock(); // TypeError: myMock is not a constructor

Iteration 4

We can support class mocking by changing the proxy target to a class and redefining construct operation.

const ReturnSymbol = Symbol("proxy return");
const ResolveSymbol = Symbol("proxy resolve");
const DEFAULT_PROMISE_DEPTH = 20;
function deepMock(promiseDepth = DEFAULT_PROMISE_DEPTH) {
  const cache = {};
  return new Proxy(
    // anonymous class as the proxy target.
    class {},
    {
      get(target, prop) {
        if (prop in cache) {
          return cache[prop];
        }
        if (prop === "then" && promiseDepth === 0) {
          return undefined;
        }
        return (cache[prop] =
          prop === "then"
            ? (resolve) =>
                resolve((cache[ResolveSymbol] ??= deepMock(promiseDepth - 1)))
            : deepMock());
      },
      apply() {
        if (ReturnSymbol in cache) {
          return cache[ReturnSymbol];
        }
        return (cache[ReturnSymbol] = deepMock());
      },
      // Redefine construct operation.
      construct() {
        return deepMock();
      },
    },
  );
}

It's great that we can mock classes, but we have a new problem.
Problem: now it throws an error when we try to convert a mock into a string.

const myMock = deepMock();
`${myMock}` // TypeError: Cannot convert object to primitive value
String(myMock) // TypeError: Cannot convert object to primitive value

Iteration 5

We can handle this edge case by adding Symbol.toPrimitive and toString methods to our proxy.

const ReturnSymbol = Symbol("proxy return");
const ResolveSymbol = Symbol("proxy resolve");
const DEFAULT_PROMISE_DEPTH = 20;
function deepMock(promiseDepth = DEFAULT_PROMISE_DEPTH) {
  const cache = {};
  return new Proxy(
    class {},
    {
      get(target, prop) {
        if (prop in cache) {
          return cache[prop];
        }
        if (prop === "then" && promiseDepth === 0) {
          return undefined;
        }
        // Provide string conversion methods.
        if (prop === Symbol.toPrimitive || prop === "toString") {
          return () => "<mock>"; // return any string here.
        }
        return (cache[prop] =
          prop === "then"
            ? (resolve) =>
                resolve((cache[ResolveSymbol] ??= deepMock(promiseDepth - 1)))
            : deepMock());
      },
      apply() {
        if (ReturnSymbol in cache) {
          return cache[ReturnSymbol];
        }
        return (cache[ReturnSymbol] = deepMock());
      },
      construct() {
        return deepMock();
      },
    },
  );
}

We're almost there.
One last thing: Jest mock provides features like altering the return value, inspecting call history, etc. We'd like to expose those features to deepMock users.

Iteration 6

Instead of making apply operation return a mock right away, we can wrap it once with jest.fn.

const ReturnSymbol = Symbol("proxy return");
const ResolveSymbol = Symbol("proxy resolve");
// Symbol for caching `jest.fn`
const MockSymbol = Symbol("mock");
const DEFAULT_PROMISE_DEPTH = 20;
function deepMock(promiseDepth = DEFAULT_PROMISE_DEPTH) {
  const cache = {
    // This Jest mock gets called inside the proxy apply operation.
    [MockSymbol]: jest.fn(() =>
      ReturnSymbol in cache
        ? cache[ReturnSymbol]
        : (cache[ReturnSymbol] = deepMock())
    ),
  };
  return new Proxy(
    class {},
    {
      get(target, prop) {
        if (prop in cache) {
          return cache[prop];
        }
        if (prop === "then" && promiseDepth === 0) {
          return undefined;
        }
        // Provide string conversion methods.
        if (prop === Symbol.toPrimitive || prop === "toString") {
          return () => "<mock>"; // return any string here.
        }
        return (cache[prop] =
          prop === "then"
            ? (resolve) =>
                resolve((cache[ResolveSymbol] ??= deepMock(promiseDepth - 1)))
            : deepMock());
      },
      // forward args to the Jest mock.
      apply(target, thisArg, args) {
        return cache[MockSymbol](...args)
      },
      construct() {
        return deepMock();
      },
    },
  );
}

/**
 * Access the Jest mock function that's wrapping the given deeply mocked function.
 * @param func the target function. It needs to be deeply mocked.
 */
export const mocked = (func) => func[MockSymbol];

Fantastic, this allows us to control deeply mocked methods through Jest.

const myMock = deepMock();
mocked(myMock.a.b.c.d).mockReturnValueOnce(42);
myMock.a.b.c.d(); // 42

Conclusion

Here's how our deepMock function can be used!

// foo.js
export const DatabaseAdapter {
  // ...
  doSomethingCrazy() {...}
}

// bar.js
import {DatabaseAdapter} from "./foo";
export function legacyFunction() {
   // imagine lots of code here...
   DatabaseAdapter.doSomethingCrazy();
   // ...
}

// bar.test.js
import {DatabaseAdapter} from "./foo";
import {legacyFunction} from "./bar";
import {mocked} from "./deepMock";

// Deeply mock foo.
jest.mock(
  "./foo",
  () => jest.requireActual("./deepMock").deepMock(),
);

test("legacy", () => {
  // We can call legacyFunction without worrying about
  // affecting database because foo is deeply mocked.
  legacyFunction();

  // But we can still test whether the database adapter
  // is used properly.
  expect(mocked(DatabaseAdapter.doSomethingCrazy)).toHaveBeenCalled();
});

And that's a wrap! Is this something you would use in your test code? What do you think about the deepMock implementation? Could I do it better?

Notes

If your dependency is too tightly coupled with your application code, the better way to deal with the problem is to reduce the coupling with techniques like inversion of control. Deep mocking is just a convenient workaround until a proper fix is available.
The meaning of "mock", "stub", "fake", and "spy" can be different depending on which language/framework/library you use, but they are all some variant of test double.

Reference

서비스 패턴으로 조립하기 쉬운 백엔드 만들기

Danny Kim — Thu, 17 Nov 2022 05:13:35 +0000

조립하기 쉬운 시스템이란

잘 설계된 백엔드를 작업할 때는 마치 레고를 가지고 노는 기분이 듭니다. 많은 백엔드 개발자들이 (스프링, 루비온레일즈, 네스트 같은) 강한 컨벤션의 프레임워크를 선호하는 이유는 바로 코드를 간단한 컴포넌트로 분리하는게 쉽기 때문입니다.

이 포스트를 통해 조립하기 쉬운 시스템의 본질을 알아보고, (약한 컨벤션의) ExpressJS 프로젝트에도 적용하는 법을 보여드리겠습니다.

조립하기 쉬운 시스템을 구축하기 위해서는 각 컴포넌트가 간단하고 명확한 경계면을 가져야 합니다. 조립을 힘들게 하는 요소는 크게 두가지가 있는데요:

글로벌 & 탑레벨 변수

글로벌 변수나 모듈 레벨에 선언된 변수는 컴포넌트 간의 경계를 흐립니다. 환경변수가 좋은 예인데요, process.env는 어디서나 쓰기 쉽기 때문에 별 생각없이 남용하기 마련입니다. 하지만 이런 패턴은 어떤 함수가 어떤 환경변수에 의존하는지 확인하기 힘들게 만듭니다. 다시말해 함수의 의존성이 모호해진다는 뜻입니다.

큰 인터페이스

간혹 인터페이스가 명확하긴 하지만 너무 커다란 경우가 있습니다. 이 경우도 모호한 의존성만큼이나 나쁩니다. 큰 인터페이스를 가진 컴포넌트는 다른 컴포넌트로 바꿔 끼우는게 불편하기 때문이죠. ORM과 (object-relational mapping) 데이터베이스 어댑터가 이런 문제의 대표적인 예입니다.

개발자들은 ORM을 사용함으로써 명료한 인터페이스로 데이터베이스에 접근할 수 있지만, 대부분의 ORM들은 인터페이스 크기가 어마어마합니다. 따라서 한 ORM을 다른 컴포넌트로 바꿔 끼우는건 거의 불가능합니다.

간단한 코드 구조를 위한 리팩터링

이제 주요 문제점을 파악했으니 개선 방안을 찾을 차례입니다. 각 문제점 별 코드 예시와 리팩터링 기법을 살펴봅시다.

글로벌 & 탑레벨 변수

예시

환경변수는 흔히 아래와 같이 사용됩니다:

// env.ts
import dotenv from "dotenv";
dotenv.configure();
export const SESSION_SECRET = process.env.SESSION_SECRET;
export const DATABASE_URI = process.env.DATABASE_URI;

import { DATABASE_URI } from "./env";
mongoose.connect(DATABASE_URI);

이와 같은 탑레벨 변수는 앞서 언급했듯이 컴포넌트 간의 경계면을 흐립니다.

리팩터링

DATABASE_URI를 탑레벨 변수로 노출하는 대신 함수 스코프에 집어넣을 수 있습니다. 감싸는 함수의 이름은 EnvService라고 합시다.

// env.ts
import dotenv from "dotenv";
export const EnvService = () => {
  dotenv.configure();
  return {
    SESSION_SECRET: process.env.SESSION_SECRET,
    DATABASE_URI: process.env.DATABASE_URI,
  };
};
export type EnvService = ReturnType<typeof EnvService>;

데이터베이스가 환경변수에 의존한다는걸 표현하기 위해서 데이터베이스 관련 코드도 함수로 감싸줄 수 있습니다.

import { EnvService } from "./env";
export const DatabaseService = (env: EnvService) => {
  mongoose.connect(env.DATABASE_URI);
  ...
};

이렇게 하면 데이터베이스 코드가 환경변수에 의존한다는게 아주 명확하게 보입니다. 글로벌 변수를 사용하지 않아도 말이죠.

큰 인터페이스

그렇다면 큰 인터페이스는 어떻게 처리하면 될까요?

예시

Express 핸들러 안에서 흔히들 ORM 클래스를 직접 사용합니다.

app.get("/user/:id", async (req, res, next) => {
  try {
    const user = await UserModel.findById(req.params.id);
    //                 ^ 이렇게 말이죠
    res.send({ user });
  } catch (err) {
    next(err);
  }
});

이 구현에는 두가지 문제점이 있습니다.

UserModel이 탑레벨 클래스입니다. "/user/:id" 핸들러는 UserModel에 의존적이지만, 이 의존성이 명시적이지가 않습니다.
UserModel의 인터페이스가 너무 큽니다. 대부분의 ORM 라이브러리들이 거대한 인터페이스를 가지죠. 데이터베이스의 다양한 기능들과 설정들을 전부 다루는 만큼, ORM이 피할수 없는 운명이라고 할 수 있습니다.

한마디로 핸들러와 UserModel 사이의 결합도가 지나치게 높습니다. 이런 구현에서는 두 컴포넌트를 깔끔하게 분리하기 쉽지 않습니다.

리팩터링

앞서 사용한 리팩터링 기법을 활용해서 의존성을 명시적으로 표현할 수 있습니다. ORM쪽부터 시작합시다.

// user.ts
export const UserService = () => {
  return {
    getById: (userId: string) => UserModel.findById(userId),
  };
};
export type UserService = ReturnType<typeof UserService>;
// type: { getById: (userId: string) => Promise<User> }

복잡한 탑레벨 UserModel을 UserService 함수로 감싸주었습니다. UserService 함수는 UserModel에 비해 인터페이스가 훨씬 작다는걸 볼 수 있습니다.

이제 UserService와 핸들러 사이의 의존성을 표현해주면 됩니다.

먼저 인라인으로 선언된 핸들러를 밖으로 추출하는 작업을 해줍니다.

const userHandler: RequestHandler = async (
  req, res, next
) => {
  try {
    const user = await UserModel.findById(req.params.id);
    res.send({ user });
  } catch (err) {
    next(err);
  }
};
app.get("/user/:id", userHandler);

그리고 핸들러를 함수로 감싸서 의존성을 표현해줍니다.

const UserHandler = (
  userService: UserService
): RequestHandler => async (req, res, next) => {
  try {
    const user = await userService.getById(req.params.id);
    res.send({ user });
  } catch (err) {
    next(err);
  }
};
app.get("/user/:id", UserHandler(userService));

핸들러와 서비스 사이에 아주 깔끔한 인터페이스가 생긴걸 확인할 수 있습니다!

마무리 작업

탑레벨 변수를 함수로 감싸고 의존성을 파라미터로 표현함으로써 컴포넌트 간의 경계면을 단순화 할 수 있었습니다. 이 기법을 "inversion of control" (제어의 반전)이라고 부릅니다.

In software engineering, inversion of control (IoC) is a design principle in which custom-written portions of a computer program receive the flow of control from an external source. The term "inversion" is historical: a software architecture with this design "inverts" control as compared to procedural programming. In procedural programming, a program's custom code calls reusable libraries to take care of generic tasks, but with inversion of control, it is the external source or framework that calls the custom code.

View on Wikipedia>

눈치채셨을지도 모르겠지만, 아직 구현에 한가지 빠진 부분이 있습니다. 핸들러가 파라미터로 서비스를 전달받아야 하는데, 이걸 제공하는 코드가 없습니다.

app.get("/user/:id", UserHandler(userService));
// `userService`는 어디서 와야 할까요?

이걸 위해 "메타 서비스"를 만들어 봅시다. 서비스를 제공하는 서비스 말이죠.

import { EnvService } from "./env";
import { SessionService } from "./session";
import { UserService } from "./user";

type ServiceMap = {
  user: UserService;
  env: EnvService;
  session: SessionService;
};

// Meta service
export const ServiceProvider = () => {
  // 서비스들을 선언.
  const env = EnvService();
  // 각 서비스는 다른 서비스에 의존할 수 있습니다.
  const user = UserService(env);
  // 물론 여러 서비스에 의존하는것도 가능합니다.
  const session = SessionService(env, user);

  const serviceMap: ServiceMap = {
    user,
    env,
    session,
  };

  /**
   * Get service by service name.
   */
  const getService = <TServiceName extends keyof ServiceMap>(
    serviceName: TServiceName
  ) => serviceMap[serviceName];

  return getService;
};

export type ServiceProvider = ReturnType<typeof ServiceProvider>;

이 메타 서비스는 아래와 같이 사용 가능합니다:

const service = ServiceProvider();
const env = service("env"); // EnvService

App이 ServiceProvider에 의존한다는걸 표현해줍니다.

// app.ts
import express from "express";
import { ServiceProvider } from "./service";
import { UserHandler } from "./handlers";

export const App = (service: ServiceProvider) => {
  const app = express();
  app.get("/user/:id", UserHandler(
    // 필요한 서비스는 `ServiceProvider`를 통해 제공.
    service("user"),
  ));
  return app;
};

마지막으로, ServiceProvider를 생성해서 App에 넘겨줍니다!

// index.ts
import { App } from "./app";
import { ServiceProvider } from "./service";

const service = ServiceProvider();
const app = App(service);
app.listen(service("env").PORT);

그래서 이게 왜 좋은가요?

필요한 기능들을 서비스의 형태로 묶어줌으로써 아주 이해하기 쉬운 프로젝트 구조를 갖게 됩니다.

인터페이스가 작고 명시적이라면, 서비스의 구현을 수정하는 작업이 쉬워집니다. Firestore를 MongoDB로 교체하고 싶으시다고요? 해당 작업은 데이터베이스와 직접 상호작용하는 서비스에만 영향을 끼칩니다. 나머지 코드베이스는 거의 건드릴 필요가 없습니다. 만약 핸들러에서 ORM 클래스를 직접 사용하고 있었다면 이야기가 다르겠죠. 물론 데이터베이스를 갈아끼우는게 자주있는 일은 아니지만, 요점은 코드 수정이 쉬워진다는 것입니다.
테스팅도 훨씬 쉬위집니다. 첫번째 논점과 연결되는 부분인데요, 테스트를 하기 위해서는 서비스를 mock으로 교체해야 할 일이 많기 때문입니다. 인터페이스가 작고 명시적이면 (mock, fake, stub 같은) test double을 만드는게 쉽습니다. 또한 어떤 컴포넌트를 mocking 해줘야하는지도 확인하기 간편합니다. 제어 반전을 사용했다면 의존성은 그냥 파라미터 목록으로 다 보이니까요.

요약

아래는 이 포스트에서 사용한 리팩터링 기법에 대한 요약입니다.

탑레벨 변수/함수를 서비스 함수로 감싸기. 서비스 함수의 인터페이스는 작아야 함.
핸들러를 외부 함수로 추출하기.
의존성을 파라미터로 표현하기 (제어 반전).
메타 서비스 구현하기 (ServiceProvider).
ServiceProvider를 통해 핸들러들에게 서비스 제공하기.

이 패턴이 실제 프로젝트에서 어떻게 사용되는지 보고 싶으시다면 제 개인 프로젝트에서 확인하실 수 있습니다:

Building Backend with Composable Services

Danny Kim — Wed, 16 Nov 2022 22:12:47 +0000

About Composable Systems

Working inside a well-structured backend code feels like playing with Lego blocks. Many backend developers love opinionated frameworks (like Spring, Ruby on Rails, NestJS) because these frameworks make it easier to split their code into simple components.

In this post, we'll explore the essence of composable systems, and apply it to an (unopinionated) ExpressJS project.

To build a composable system, each component should have a simple & clear boundary. There are two main offenders that hurt composability of a component:

Global & Top-level Variable

Global variables or module-level variables smudge the boundary between components. Environment variables are a good example of this pattern. It is so easy to access process.env from anywhere, so we tend to use them without thinking too much about it. This makes it harder to check which function depends on which environment variable. In other words, the function's dependency gets blurry.

Big Interface

Sometimes, interfaces are very clear but too big. This is as bad as blurry dependencies because it is difficult to swap out a component with big interface. ORMs (object-relational mapping) and database adapters are good examples of this pattern.

By using an ORM, developers can access database with a clean interface; however, most ORMs have extremely big interfaces. It is near impossible to swap out an ORM with another component.

Refactoring for Simpler Structure

Ok, so we have identified the problem, but how do we fix it? Let's look at some examples and refactoring techniques.

Global & Top-level Variable

Example

Environment variables are often used like this:

// env.ts
import dotenv from "dotenv";
dotenv.configure();
export const SESSION_SECRET = process.env.SESSION_SECRET;
export const DATABASE_URI = process.env.DATABASE_URI;

import { DATABASE_URI } from "./env";
mongoose.connect(DATABASE_URI);

Top-level variables in this example blur the boundary between components as mentioned above.

Refactoring

Instead of exposing DATABASE_URI as top-level variable, we can put it in a function scope. Let's call the wrapper function EnvService.

// env.ts
import dotenv from "dotenv";
export const EnvService = () => {
  dotenv.configure();
  return {
    SESSION_SECRET: process.env.SESSION_SECRET,
    DATABASE_URI: process.env.DATABASE_URI,
  };
};
export type EnvService = ReturnType<typeof EnvService>;

To express that our database depends on environment variables, we can write a wrapper function for database as well.

import { EnvService } from "./env";
export const DatabaseService = (env: EnvService) => {
  mongoose.connect(env.DATABASE_URI);
  ...
};

Now it is super clear that our database depends on environment variables. We don't need global variables anymore.

Big Interface

Then what about big interfaces?

Example

It is common to use ORM classes directly inside request handlers.

app.get("/user/:id", async (req, res, next) => {
  try {
    const user = await UserModel.findById(req.params.id);
    //                 ^ like this one
    res.send({ user });
  } catch (err) {
    next(err);
  }
});

There are two problems with this implementation.

UserModel is a top-level class. The "/user/:id" handler depends on UserModel, but this dependency is not explicit.
UserModel has big interface. Most ORM libraries expose huge interfaces. It is unavoidable because an ORM needs to support a lot of database features & configurations.

In short, the request handler is tightly coupled with UserModel. There is no simple way to slice them apart cleanly.

Refactoring

We can attempt the same approach to make dependencies explicit. Let's start from the ORM.

// user.ts
export const UserService = () => {
  return {
    getById: (userId: string) => UserModel.findById(userId),
  };
};
export type UserService = ReturnType<typeof UserService>;
// type: { getById: (userId: string) => Promise<User> }

We have wrapped the complex top-level UserModel in a UserService function. UserService has much smaller interface compared to UserModel.

It's time to express the dependency between UserService & the request handler.

First, extract the handler into a separate function.

const userHandler: RequestHandler = async (
  req, res, next
) => {
  try {
    const user = await UserModel.findById(req.params.id);
    res.send({ user });
  } catch (err) {
    next(err);
  }
};
app.get("/user/:id", userHandler);

Then, express the dependency by wrapping the request handler with a function.

const UserHandler = (
  userService: UserService
): RequestHandler => async (req, res, next) => {
  try {
    const user = await userService.getById(req.params.id);
    res.send({ user });
  } catch (err) {
    next(err);
  }
};
app.get("/user/:id", UserHandler(userService));

Nice, now we have a clean interface between the request handler and the service!

Final Touch

Wrapping top-level variables & expressing dependencies as parameters are excellent ways to simplify boundaries between components. (This technique is called "inversion of control")

View on Wikipedia>

But you may have noticed that we still don't have a way to provide required services to request handlers.

app.get("/user/:id", UserHandler(userService));
// Where does `userService` come from?

We can create a meta service for this purpose. A service that provides other services.

import { EnvService } from "./env";
import { SessionService } from "./session";
import { UserService } from "./user";

type ServiceMap = {
  user: UserService;
  env: EnvService;
  session: SessionService;
};

// Meta service
export const ServiceProvider = () => {
  // Initialize services.
  const env = EnvService();
  // A service can depend on another service,
  const user = UserService(env);
  // or multiple services.
  const session = SessionService(env, user);

  const serviceMap: ServiceMap = {
    user,
    env,
    session,
  };

  /**
   * Get service by service name.
   */
  const getService = <TServiceName extends keyof ServiceMap>(
    serviceName: TServiceName
  ) => serviceMap[serviceName];

  return getService;
};

export type ServiceProvider = ReturnType<typeof ServiceProvider>;

This meta service can be used like this:

const service = ServiceProvider();
const env = service("env"); // EnvService

Let's express that our app depends on ServiceProvider:

// app.ts
import express from "express";
import { ServiceProvider } from "./service";
import { UserHandler } from "./handlers";

export const App = (service: ServiceProvider) => {
  const app = express();
  app.get("/user/:id", UserHandler(
    // Provide required service with `ServiceProvider`.
    service("user"),
  ));
  return app;
};

Finally, initialize ServiceProvider and pass it to App!

// index.ts
import { App } from "./app";
import { ServiceProvider } from "./service";

const service = ServiceProvider();
const app = App(service);
app.listen(service("env").PORT);

What's Good About This Pattern?

By organizing functionalities into services, we get very straightforward project structure to reason about.

Modifying service implementation is easier when the interface is small & explicit. Swapping out Firestore with MongoDB? That only affects the service that directly interacts with the database. The rest of the codebase is largely unaffected. The same can't be said if our request handlers are using ORM classes directly. Of course we don't change database every week, but the point is that changes are easier to make.
Testing gets much easier. This is related to the first point, because we replace services with mocks during testing. Creating a test double (a.k.a. mock, fake, stub) is easier when the component has small & explicit interface. Also, checking which component to mock is effortless with inversion of control. All dependencies are expressed as parameters, so we just need to check those parameters.

Summary

Here's a summary of the refactoring technique we used.

Wrap top-level variables/functions into a service function. The service function's interface should be small.
Extract request handlers as separate functions.
Express dependencies as parameters (inversion of control).
Create a meta service (ServiceProvider).
Provide services to request handlers via ServiceProvider.

If you want to take a look at this pattern in action, please check out my personal project:

How to Make Your Firebase Application Open Source Friendly

Danny Kim — Tue, 18 Oct 2022 04:49:41 +0000

Serverless Technologies & Open Source

Serverless technologies like Firebase are great options for hobbyist developers because they are very affordable for small projects; however, you might have experienced some difficulties sharing your lovely projects with the open source community because of the nature of serverless: a big chunk of your app is managed by the platform provider (GCP, AWS, etc.).

The first and most obvious way to share your project is to invite your contributors to your Firebase project. This is a big hurdle for contributors because they can't even run the app until they reach out to the maintainer and gain the maintainer's trust.

Another approach is to make your project configurable, so that the contributors can set up their own Firebase project and wire it into your project. This is better than the first approach, but it is still a nuisance for contributors.

Strike a Balance

So here's my suggestion: accept that your repository is tied to your Firebase project, but make use of the local emulator to get rid of the contribution hurdle.

This approach doesn't require inviting everyone to your Firebase project, because emulator can be run without credentials.

A drawback of this approach is that it becomes harder to use your code in another Firebase project. I think this is a reasonable compromise to make because contributors will have easier time by skipping the configuration step.

Tips

Here are some Firebase-specific tips to make your project more contribution-friendly.

Make your local app zero-config

Make sure the contributors can run your app locally without setting any environment variables, or at least try to minimize the configuration process.

Provide valid default values for Firebase API key, auth domain, project ID, app ID, etc., so that contributors don't need to provide them manually.

Ideally, a contributor should be able to get started by running yarn && yarn firebase emulator:start.

Commit your `.firebaserc`

Check in your .firebaserc to the repo with your Firebase project name.

{
  "projects": {
    "default": <your-project-name>
  }
}

There are many advice against this practice because this will tie your repository to your Firebase project; however, Firebase local emulator asks the developer to log in with Firebase credentials when .firebaserc file is missing. Therefore, this is a crucial step to minimize the configuration hassle for your contributors.

If you're using external services

It is common for an application to make use of external services like Stripe, Mailchimp, etc.. If you need secrets to access these services, use Google Cloud Secret Manager. Since contributors cannot access your secrets, I suggest using something like MSW to mock these services.

If you're using Firebase Hosting

If you're using Firebase Hosting service, make sure your proxies are configured correctly. Here's an example of hosting configuration (firebase.json):

{
  "hosting": {
    "public": "app/dist",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "rewrites": [
      {
        "source": "/api/**",
        "function": "api"
      },
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

If you use a dev server for local development, you would need to set up another reverse proxy like this:

Conclusion

It takes extra effort to build an open source application with serverless technologies, but it is certainly doable. Although I only covered Firebase in this post, there are other tools that provide local emulation (e.g. LocalStack). If you're considering which platform to use, pick one with local emulation support or a Docker image.

Going serverless means you have less control over infrastructure details. But that doesn't mean you need to compromise the contributor experience. You'll see that you can streamline the setup process to a pleasant level.

Generating CMS from Prisma Schema

Danny Kim — Fri, 05 Aug 2022 20:41:00 +0000

One of Prisma's best features is its TypeScript client generated from Prisma schema. For me, it is a killer feature that differentiates Prisma from other JavaScript ORMs. By using the generated TypeScript client, I don't need to worry about writing custom types no matter how complex my queries are. Even better, Prisma's code generator system is designed to be extensible, so we can make it generate more than just TS client.

Motivated by this flexibility of Prisma generator, I tried to generate a content management system (CMS) from a Prisma schema. This project is still in proof-of-concept stage, but I think it has a potential to be used for building internal admin dashboards.

Existing Projects

There are already content management systems out there that are built on top of Prisma, so let's take a look at some major ones first:

KeystoneJS

KeystoneJS is a headless CMS with a built-in ORM. If you design a database schema using Keystone schema API, this tool generates everything from a GraphQL server to admin UIs. It is an amazing productivity booster. It started to support Prisma as a database adapter from 2021 therefore widened the gap between other headless CMS tools and itself.

Although Keystone is a one of the superior frameworks, it is limited in a sense that it cannot be easily attached to exiting projects because Keystone needs to manage the database itself.

PalJS

PalJS is a GraphQL API + admin UI generation tool built by a solo developer. It covers e2e just like KeystoneJS, but it is much more flexible because PalJS is a Prisma generator! As long as you have a Prisma schema (either prisma db pulled or written yourself), you can attach PalJS to any project.

It is a bit difficult to customize the generated UI because everything is wrapped in components.

prisma-generator-proto

So I built a proof-of-concept project called prisma-generator-proto to overcome the limitations of existing projects.

Making use of Prisma generator interface

Even though some content management systems are standalone services (e.g. Wordpress), others use a CMS for managing data for existing services. Something like Keystone can be good for greenfield projects, but it is challenging to adopt in existing projects. So I wanted prisma-generator-proto to be a CMS generated from a Prisma schema for ease of adoption.

Providing UI as React hooks

It is definitely convenient to have the entire UI/pages generated like PalJS, most teams need to customize their admin UI as they grow. If you have ever tried to customize components from UI libraries like Material UI, you would know how tricky it is to change behavior of packaged components. So prisma-generator-proto only exposes data & operations as React hooks without any styling. Developers can build admin UI by mixing these generated hooks with an UI component library.

Prisma generator under the hood

All Prisma generators have a similar mechanism.

Prisma schema

It all starts from a file called schema.prisma:



datasource db {
  url      = env("DATABASE_URL")
  provider = "postgresql"
}

generator client {
  provider = "prisma-client-js"
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  posts     Post[]
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String   @db.VarChar(255)
  author    User?    @relation(fields: [authorId], references: [id])
  authorId  Int?
}

As you can see above, there are three main directives in schema.prisma:

datasource : Defines how to connect to the database
model : Defines each data model
generator : Configures a generator that consumes this schema file. By default, we generate TypeScript client with prisma-client-js generator, and we can declare additional generators using generator directive again.

schema.prisma file can either be hand-written or be pulled from existing database with prisma db pull CLI.

prisma generate

prisma generate command sequentially runs each generators declared in schema.prisma. Prisma takes care of parsing the schema, and each generator receives a parsed result called "DMMF". Each DMMF contains the following information as JS objects:

A list of all models
A list of fields within each model
Type, default value, nullability of each field
Model associations

Also, Prisma lets each generator where to output the generated files, so a generator's job is just to create some files from DMMF and writing them in the designated output directory.

Progress

Here's what prisma-generator-proto can do now:

REST API generation

It generates an Express router containing CRUD routes for all models. It does not generate the Express application itself.

Usage:



import express from "express";
import { router } from "../__generated__";

const app = express();
app.use(express.json());

// Use the generated CRUD routes!
app.use("/api", router);

app.listen(3001, () => {
  console.log("Listening...");
});

Client code generation

It generates React hooks that calls the generated REST API routes.

Usage:



import Form from "../components/Form";

import React from "react";

import Table from "../components/Table";

import styles from "../styles/DataScreen.module.css";

import { useCountry } from "../generated/hooks";

const Countries = () => {

  // Do CRUD operations with the generated hooks

  const [countries, addHandler, formState, setFormState] = useCountry();

  return (

    <div className={styles.screen}>

      <Form

        name="Country"

        keys={["name", "population", "continentId", "isUnMember"]}

        onSubmit={addHandler}

        state={formState}

        setState={setFormState}

      />

      <Table

        name="Country"

        list={countries}

        keys={["id", "name", "population", "continentId", "isUnMember"]}

      />

    </div>

  );

};

export default Countries;

Try it yourself

prisma-generator-proto is available on NPM.

You can find the source code in this GitHub repository.

Type-Safe Usage of React Router

Danny Kim — Mon, 07 Dec 2020 15:32:56 +0000

This is my approach to implement strongly typed routing using React Router and TypeScript. So that if I try to create a <Link> to an unknown path, tsc can warn me appropriately. Of course there are other benefits of typed routes, but let's go over what's wrong with the current implementation first.

Problem

react-router takes any plain string as a path. This makes it difficult to refactor routes when it is required to rename/delete/add routes. Also typos are hard to detect.
Developers need to provide types for useParams hook (i.e. useParams<{ id: string }>). It has the same issue with refactoring. Developers need to update useParams hooks whenever there's a change in URL parameter names.

Solution (Walkthrough)

I ended up implementing something I am happy with. Example source code is available on a GitHub repo. I hope this can help others who desire typed routes. This post is mostly annotation of my implementation, so if you prefer reading source code directly, check out the GitHub repo.

`src/hooks/paths.tsx`

The single source of truth for available paths is defined in this module. If a route needs to be modified, this PATH_SPECS can be fixed, then TypeScript compiler will raise errors where type incompatibilities are found.

const PATHS = [
  '/',
  '/signup',
  '/login',
  '/post/:id',
  '/calendar/:year/:month',
] as const;

Utility types can be derived from this readonly array of paths.

type ExtractRouteParams<T> = string extends T
    ? Record<string, string>
    : T extends `${infer _Start}:${infer Param}/${infer Rest}`
    ? { [k in Param | keyof ExtractRouteParams<Rest>]: string }
    : T extends `${infer _Start}:${infer Param}`
    ? { [k in Param]: string }
    : {};

export type Path = (typeof PATHS)[number];

// Object which has matching parameter keys for a path.
export type PathParams<P extends Path> = ExtractRouteParams<P>;

Small amount of TypeScript magic is applied here, but the end result is quite simple. Note how PathParams type behaves.

PathParams<'/post/:id'> is { id: string }
PathParams<'/calendar/:year/:month'> is { year: string, month: string }
PathParams<'/'> is {}

From here, a type-safe utility function is written for building URL strings.

/**
 * Build an url with a path and its parameters.
 * @example
 * buildUrl(
 *   '/a/:first/:last',
 *   { first: 'p', last: 'q' },
 * ) // returns '/a/p/q'
 * @param path target path.
 * @param params parameters.
 */
export const buildUrl = <P extends Path>(
  path: P,
  params: PathParams<P>,
): string => {
  let ret: string = path;

  // Upcast `params` to be used in string replacement.
  const paramObj: { [i: string]: string } = params;

  for (const key of Object.keys(paramObj)) {
    ret = ret.replace(`:${key}`, paramObj[key]);
  }

  return ret;
};

buildUrl function can be used like this:

buildUrl(
  '/post/:id',
  { id: 'abcd123' },
); // returns '/post/abcd123'

buildUrl only takes a known path (from PATHS) as the first argument, therefore typo-proof. Sweet!

`src/components/TypedLink`

Now, let's look at TypedLink a type-safe alternative to Link.

import { Path, PathParams, buildUrl } from '../hooks/paths';
import React, { ComponentType, ReactNode } from 'react';

import { Link } from 'react-router-dom';

type TypedLinkProps<P extends Path> = {
  to: P,
  params: PathParams<P>,
  replace?: boolean,
  component?: ComponentType,
  children?: ReactNode,
};

/**
 * Type-safe version of `react-router-dom/Link`.
 */
export const TypedLink = <P extends Path>({
   to,
   params,
   replace,
   component,
   children,
}: TypedLinkProps<P>) => {
  return (
    <Link
      to={buildUrl(to, params)}
      replace={replace}
      component={component}
    >
      {children}
    </Link>
  );
}

TypedLink can be used like this:

<TypedLink to='/post/:id' params={{ id: 'abcd123' }} />

The to props of TypedLink only takes a known path, just like buildUrl.

`src/components/TypedRedirect.tsx`

TypedRedirect is implemented in same fashion as TypedLink.

import { Path, PathParams, buildUrl } from '../hooks/paths';

import React from 'react';
import { Redirect } from 'react-router-dom';

type TypedRedirectProps<P extends Path, Q extends Path> = {
  to: P,
  params: PathParams<P>,
  push?: boolean,
  from?: Q,
};

/**
 * Type-safe version of `react-router-dom/Redirect`.
 */
export const TypedRedirect = <P extends Path, Q extends Path>({
  to,
  params,
  push,
  from,
}: TypedRedirectProps<P, Q>) => {
  return (
    <Redirect
      to={buildUrl(to, params)}
      push={push}
      from={from}
    />
  );
};

`src/hooks/index.tsx`

Instead of useParams which cannot infer the shape of params object, useTypedParams hook can be used. It can infer the type of params from path parameter.

/**
 * Type-safe version of `react-router-dom/useParams`.
 * @param path Path to match route.
 * @returns parameter object if route matches. `null` otherwise.
 */
export const useTypedParams = <P extends Path>(
  path: P
): PathParams<P> | null => {
  // `exact`, `sensitive` and `strict` options are set to true
  // to ensure type safety.
  const match = useRouteMatch({
    path,
    exact: true,
    sensitive: true,
    strict: true,
  });

  if (!match || !isParams(path, match.params)) {
    return null;
  }
  return match.params;
}

Finally, useTypedSwitch allows type-safe <Switch> tree.

/**
 * A hook for defining route switch.
 * @param routes 
 * @param fallbackComponent 
 */
export const useTypedSwitch = (
  routes: ReadonlyArray<{ path: Path, component: ComponentType }>,
  fallbackComponent?: ComponentType,
): ComponentType => {
  const Fallback = fallbackComponent;
  return () => (
    <Switch>
      {routes.map(({ path, component: RouteComponent }, i) => (
        <Route exact strict sensitive path={path}>
          <RouteComponent />
        </Route>
      ))}
      {Fallback && <Fallback />}
    </Switch>
  );
}

Here's how <Switch> is usually used:

// Traditional approach.
const App = () => (
  <BrowserRouter>
    <Switch>
      <Route exact path='/' component={Home} />
      <Route exact path='/user/:id' component={User} />
    </Switch>
  </BrowserRouter>
);

The code above can be replaced with the following code.

const App = () => {
  const TypedSwitch = useTypedSwitch([
    { path: '/', component: Home },
    { path: '/user/:id', component: User },
  ]);

  return (
    <BrowserRouter>
      <TypedSwitch />
    </BrowserRouter>
  );
}

Conclusion

Original	Replaced
`<Link to='/user/123' />`	`<TypedLink to='/user/:id' params={ id: '123' } />`
`<Redirect to='/user/123'>`	`<TypedRedirect to='/user/:id' params={ id: '123' } />`
`useParams()`	`useTypedParams('/user/:id')`
`<Switch>`	`useTypedSwitch`

Type-safe alternatives are slightly more verbose than the original syntax, but I believe this is better for overall integrity of a project.

Developers can make changes in routes without worrying about broken links (at least they don't break silently).
Nice autocompletion while editing code.

DEV Community: Danny Kim

Sync Cursor Settings the Dotfiles Way

Settings

Git Repo Structure

Stow

Extensions

Working Example

About Reverse Proxy

What is Reverse Proxy?

Example: Webflow + React

Vercel

Webpack

buildProxyFromVercelJson

Conclusion: The Chimera Website

Simple TypeScript Mutex Implementation

Example Usage

References

Simplify Business Logic with Reactive Architecture

Deep Mocking for Jest

Requirements

Building Deep Mock

Iteration 1

Iteration 2

Iteration 3

Iteration 4

Iteration 5

Iteration 6

Conclusion

Notes

Reference

서비스 패턴으로 조립하기 쉬운 백엔드 만들기

조립하기 쉬운 시스템이란

글로벌 & 탑레벨 변수

큰 인터페이스

간단한 코드 구조를 위한 리팩터링

글로벌 & 탑레벨 변수

예시

리팩터링

큰 인터페이스

예시

리팩터링

마무리 작업

그래서 이게 왜 좋은가요?

요약

Building Backend with Composable Services

About Composable Systems

Global & Top-level Variable

Big Interface

Refactoring for Simpler Structure

Global & Top-level Variable

Example

Refactoring

Big Interface

Example

Refactoring

Final Touch

What's Good About This Pattern?

Summary

How to Make Your Firebase Application Open Source Friendly

Serverless Technologies & Open Source

Strike a Balance

Tips

Make your local app zero-config

Commit your .firebaserc

If you're using external services

If you're using Firebase Hosting

Conclusion

Generating CMS from Prisma Schema

Existing Projects

KeystoneJS

PalJS

prisma-generator-proto

Making use of Prisma generator interface

Providing UI as React hooks

Prisma generator under the hood

Prisma schema

prisma generate

Progress

Try it yourself

Read more & dig deeper

Commit your `.firebaserc`

`src/hooks/paths.tsx`

`src/components/TypedLink`

`src/components/TypedRedirect.tsx`

`src/hooks/index.tsx`