Lazy-Loading Module#

Modules are eagerly loaded by default.

Teasim loads all modules then registers and indexes all of them before starting the server. This enforces that all the modules have loaded before it starts accepting requests.

While this is fine for most applications, it may become a bottleneck for a server running in a serverless environment or an edge function, in which the startup time is important.

Lazy-loading can help decrease startup time by deferring modules to be gradually indexed after the server start.

Lazy-loading modules are a good option when some modules are heavy and importing startup time is crucial.

By default, any async plugin without await is treated as a deferred module and the import statement as a lazy-loading module.

Both will be registered after the server is started.

Deferred Module#

The deferred module is an async plugin that can be registered after the server is started.

// plugin.ts
export const loadStatic = async (app: Teasim) => {
  const files = await loadAllFiles();

  files.forEach(file => app.get(file, () => Bun.file(file)));

  return app;
};

// index.ts
import { loadStatic } from "./plugin";

const app = new Teasim().use(loadStatic);

Teasim static plugin is also a deferred module, as it loads files and registers files path asynchronously.

To ensure module registration before the server starts, you can use await on the deferred module.

// index.ts
import { loadStatic } from "./plugin";

const app = new Teasim().use(await loadStatic);

Lazy Load Module#

Same as the async plugin, the lazy-load module will be registered after the server is started.

A lazy-load module can be both sync or async function, as long as the module is used with import the module will be lazy-loaded.

import { Teasim } from "teasim";

const app = new Teasim().use(import("./plugin"));

Using module lazy-loading is recommended when the module is computationally heavy and/or blocking.

Testing#

In a test environment, you can use await app.modules to wait for deferred and lazy-loading modules.

import { Teasim } from 'teasim'

import { describe, expect, it } from 'bun:test'

describe('Modules', () => {
    it('inline async', async () => {
        const app = new Teasim()
              .use(async (app) =>
                  app.get('/async', () => 'async')
              )

        await app.modules

        const res = await app.handle(req('/async')).then((r) => r.text())

        expect(res).toBe('async')
    })