Merge pull request #121 from bknd-io/release/0.11

Release 0.11

.github/workflows/test.yml

@@ -15,12 +15,20 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v1
         with:
-          bun-version: latest
+          bun-version: "1.2.5"
 
       - name: Install dependencies
         working-directory: ./app
         run: bun install
 
-      - name: Run tests
+      - name: Build
         working-directory: ./app
-        run: bun run test
+        run: bun run build:ci
+
+      - name: Run Bun tests
+        working-directory: ./app
+        run: bun run test:bun
+
+      - name: Run Node tests
+        working-directory: ./app
+        run: npm run test:node

app/.gitignore

@@ -0,0 +1,4 @@
+playwright-report
+test-results
+bknd.config.*
+__test__/helper.d.ts

app/__test__/adapter/adapter.test.ts

@@ -0,0 +1,62 @@
+import { expect, describe, it, beforeAll, afterAll } from "bun:test";
+import * as adapter from "adapter";
+import { disableConsoleLog, enableConsoleLog } from "core/utils";
+import { adapterTestSuite } from "adapter/adapter-test-suite";
+import { bunTestRunner } from "adapter/bun/test";
+
+beforeAll(disableConsoleLog);
+afterAll(enableConsoleLog);
+
+describe("adapter", () => {
+   it("makes config", () => {
+      expect(adapter.makeConfig({})).toEqual({});
+      expect(adapter.makeConfig({}, { env: { TEST: "test" } })).toEqual({});
+
+      // merges everything returned from `app` with the config
+      expect(adapter.makeConfig({ app: (a) => a as any }, { env: { TEST: "test" } })).toEqual({
+         env: { TEST: "test" },
+      } as any);
+   });
+
+   it("reuses apps correctly", async () => {
+      const id = crypto.randomUUID();
+
+      const first = await adapter.createAdapterApp(
+         {
+            initialConfig: { server: { cors: { origin: "random" } } },
+         },
+         undefined,
+         { id },
+      );
+      const second = await adapter.createAdapterApp();
+      const third = await adapter.createAdapterApp(undefined, undefined, { id });
+
+      await first.build();
+      await second.build();
+      await third.build();
+
+      expect(first.toJSON().server.cors.origin).toEqual("random");
+      expect(first).toBe(third);
+      expect(first).not.toBe(second);
+      expect(second).not.toBe(third);
+      expect(second.toJSON().server.cors.origin).toEqual("*");
+
+      // recreate the first one
+      const first2 = await adapter.createAdapterApp(undefined, undefined, { id, force: true });
+      await first2.build();
+      expect(first2).not.toBe(first);
+      expect(first2).not.toBe(third);
+      expect(first2).not.toBe(second);
+      expect(first2.toJSON().server.cors.origin).toEqual("*");
+   });
+
+   adapterTestSuite(bunTestRunner, {
+      makeApp: adapter.createFrameworkApp,
+      label: "framework app",
+   });
+
+   adapterTestSuite(bunTestRunner, {
+      makeApp: adapter.createRuntimeApp,
+      label: "runtime app",
+   });
+});

app/__test__/api/DataApi.spec.ts

@@ -5,7 +5,8 @@ import { DataApi } from "../../src/data/api/DataApi";
 import { DataController } from "../../src/data/api/DataController";
 import { dataConfigSchema } from "../../src/data/data-schema";
 import * as proto from "../../src/data/prototype";
-import { disableConsoleLog, enableConsoleLog, schemaToEm } from "../helper";
+import { schemaToEm } from "../helper";
+import { disableConsoleLog, enableConsoleLog } from "core/utils/test";
 
 beforeAll(disableConsoleLog);
 afterAll(enableConsoleLog);
@@ -64,6 +65,15 @@ describe("DataApi", () => {
          const res = await req;
          expect(res.data).toEqual(payload as any);
       }
+
+      {
+         // make sure sort is working
+         const req = await api.readMany("posts", {
+            select: ["title"],
+            sort: "-id",
+         });
+         expect(req.data).toEqual(payload.reverse() as any);
+      }
    });
 
    it("updates many", async () => {

app/__test__/app/App.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, mock, test } from "bun:test";
 import type { ModuleBuildContext } from "../../src";
-import { type App, createApp } from "../../src/App";
+import { App, createApp } from "../../src/App";
 import * as proto from "../../src/data/prototype";
 
 describe("App", () => {
@@ -51,4 +51,87 @@ describe("App", () => {
       expect(todos[0]?.title).toBe("ctx");
       expect(todos[1]?.title).toBe("api");
    });
+
+   test("lifecycle events are triggered", async () => {
+      const firstBoot = mock(() => null);
+      const configUpdate = mock(() => null);
+      const appBuilt = mock(() => null);
+      const appRequest = mock(() => null);
+      const beforeResponse = mock(() => null);
+
+      const app = createApp();
+
+      app.emgr.onEvent(
+         App.Events.AppFirstBoot,
+         (event) => {
+            expect(event).toBeInstanceOf(App.Events.AppFirstBoot);
+            expect(event.params.app.version()).toBe(app.version());
+            firstBoot();
+         },
+         "sync",
+      );
+      app.emgr.onEvent(
+         App.Events.AppBuiltEvent,
+         (event) => {
+            expect(event).toBeInstanceOf(App.Events.AppBuiltEvent);
+            expect(event.params.app.version()).toBe(app.version());
+            appBuilt();
+         },
+         "sync",
+      );
+      app.emgr.onEvent(
+         App.Events.AppConfigUpdatedEvent,
+         () => {
+            configUpdate();
+         },
+         "sync",
+      );
+      app.emgr.onEvent(
+         App.Events.AppRequest,
+         (event) => {
+            expect(event).toBeInstanceOf(App.Events.AppRequest);
+            expect(event.params.app.version()).toBe(app.version());
+            expect(event.params.request).toBeInstanceOf(Request);
+            appRequest();
+         },
+         "sync",
+      );
+      app.emgr.onEvent(
+         App.Events.AppBeforeResponse,
+         (event) => {
+            expect(event).toBeInstanceOf(App.Events.AppBeforeResponse);
+            expect(event.params.app.version()).toBe(app.version());
+            expect(event.params.response).toBeInstanceOf(Response);
+            beforeResponse();
+         },
+         "sync",
+      );
+
+      await app.build();
+      expect(firstBoot).toHaveBeenCalled();
+      expect(appBuilt).toHaveBeenCalled();
+      //expect(configUpdate).toHaveBeenCalled();
+      expect(appRequest).not.toHaveBeenCalled();
+      expect(beforeResponse).not.toHaveBeenCalled();
+   });
+
+   test("emgr exec modes", async () => {
+      const called = mock(() => null);
+      const app = createApp({
+         options: {
+            asyncEventsMode: "sync",
+         },
+      });
+
+      // register async listener
+      app.emgr.onEvent(App.Events.AppFirstBoot, async () => {
+         called();
+      });
+
+      await app.build();
+      await app.server.request(new Request("http://localhost"));
+
+      // expect async listeners to be executed sync after request
+      expect(called).toHaveBeenCalled();
+   });
 });

app/__test__/app/repro.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { createApp, registries } from "../../src";
 import * as proto from "../../src/data/prototype";
-import { StorageLocalAdapter } from "../../src/media/storage/adapters/StorageLocalAdapter";
+import { StorageLocalAdapter } from "adapter/node/storage/StorageLocalAdapter";
 
 describe("repros", async () => {
    /**

app/__test__/auth/strategies/OAuthStrategy.spec.ts

@@ -3,8 +3,10 @@ import { OAuthStrategy } from "../../../src/auth/authenticate/strategies";
 
 const ALL_TESTS = !!process.env.ALL_TESTS;
 
+// @todo: add mock response
 describe("OAuthStrategy", async () => {
-   const strategy = new OAuthStrategy({
+   return;
+   /*const strategy = new OAuthStrategy({
       type: "oidc",
       client: {
          client_id: process.env.OAUTH_CLIENT_ID!,
@@ -21,6 +23,7 @@ describe("OAuthStrategy", async () => {
 
       const server = Bun.serve({
          fetch: async (req) => {
+            console.log("req", req.method, req.url);
             const url = new URL(req.url);
             if (url.pathname === "/auth/google/callback") {
                console.log("req", req);
@@ -42,5 +45,5 @@ describe("OAuthStrategy", async () => {
       console.log("request", request);
 
       await new Promise((resolve) => setTimeout(resolve, 100000));
-   });
+   });*/
 });

app/__test__/core/EventManager.spec.ts

@@ -70,6 +70,9 @@ describe("EventManager", async () => {
       new SpecialEvent({ foo: "bar" });
       new InformationalEvent();
 
+      // execute asyncs
+      await emgr.executeAsyncs();
+
       expect(call).toHaveBeenCalledTimes(2);
       expect(delayed).toHaveBeenCalled();
    });
@@ -80,15 +83,11 @@ describe("EventManager", async () => {
          call();
          return Promise.all(p);
       };
-      const emgr = new EventManager(
+      const emgr = new EventManager({ InformationalEvent });
-         { InformationalEvent },
-         {
-            asyncExecutor,
-         },
-      );
 
       emgr.onEvent(InformationalEvent, async () => {});
       await emgr.emit(new InformationalEvent());
+      await emgr.executeAsyncs(asyncExecutor);
       expect(call).toHaveBeenCalled();
    });
 
@@ -125,6 +124,9 @@ describe("EventManager", async () => {
       const e2 = await emgr.emit(new ReturnEvent({ foo: "bar" }));
       expect(e2.returned).toBe(true);
       expect(e2.params.foo).toBe("bar-1-0");
+
+      await emgr.executeAsyncs();
+
       expect(onInvalidReturn).toHaveBeenCalled();
       expect(asyncEventCallback).toHaveBeenCalled();
    });

app/__test__/core/cache/CloudflareKvCache.native-spec.ts

@@ -1,57 +0,0 @@
-import * as assert from "node:assert/strict";
-import { createWriteStream } from "node:fs";
-import { after, beforeEach, describe, test } from "node:test";
-import { Miniflare } from "miniflare";
-import {
-   CloudflareKVCacheItem,
-   CloudflareKVCachePool,
-} from "../../../src/core/cache/adapters/CloudflareKvCache";
-import { runTests } from "./cache-test-suite";
-
-// https://github.com/nodejs/node/issues/44372#issuecomment-1736530480
-console.log = async (message: any) => {
-   const tty = createWriteStream("/dev/tty");
-   const msg = typeof message === "string" ? message : JSON.stringify(message, null, 2);
-   return tty.write(`${msg}\n`);
-};
-
-describe("CloudflareKv", async () => {
-   let mf: Miniflare;
-   runTests({
-      createCache: async () => {
-         if (mf) {
-            await mf.dispose();
-         }
-
-         mf = new Miniflare({
-            modules: true,
-            script: "export default { async fetch() { return new Response(null); } }",
-            kvNamespaces: ["TEST"],
-         });
-         const kv = await mf.getKVNamespace("TEST");
-         return new CloudflareKVCachePool(kv as any);
-      },
-      createItem: (key, value) => new CloudflareKVCacheItem(key, value),
-      tester: {
-         test,
-         beforeEach,
-         expect: (actual?: any) => {
-            return {
-               toBe(expected: any) {
-                  assert.equal(actual, expected);
-               },
-               toEqual(expected: any) {
-                  assert.deepEqual(actual, expected);
-               },
-               toBeUndefined() {
-                  assert.equal(actual, undefined);
-               },
-            };
-         },
-      },
-   });
-
-   after(async () => {
-      await mf?.dispose();
-   });
-});

app/__test__/core/cache/MemoryCache.spec.ts

@@ -1,15 +0,0 @@
-import { beforeEach, describe, expect, test } from "bun:test";
-import { MemoryCache, MemoryCacheItem } from "../../../src/core/cache/adapters/MemoryCache";
-import { runTests } from "./cache-test-suite";
-
-describe("MemoryCache", () => {
-   runTests({
-      createCache: async () => new MemoryCache(),
-      createItem: (key, value) => new MemoryCacheItem(key, value),
-      tester: {
-         test,
-         beforeEach,
-         expect,
-      },
-   });
-});

app/__test__/core/cache/cache-test-suite.ts

@@ -1,84 +0,0 @@
-//import { beforeEach as bunBeforeEach, expect as bunExpect, test as bunTest } from "bun:test";
-import type { ICacheItem, ICachePool } from "../../../src/core/cache/cache-interface";
-
-export type TestOptions = {
-   createCache: () => Promise<ICachePool>;
-   createItem: (key: string, value: any) => ICacheItem;
-   tester: {
-      test: (name: string, fn: () => Promise<void>) => void;
-      beforeEach: (fn: () => Promise<void>) => void;
-      expect: (actual?: any) => {
-         toBe(expected: any): void;
-         toEqual(expected: any): void;
-         toBeUndefined(): void;
-      };
-   };
-};
-
-export function runTests({ createCache, createItem, tester }: TestOptions) {
-   let cache: ICachePool<string>;
-   const { test, beforeEach, expect } = tester;
-
-   beforeEach(async () => {
-      cache = await createCache();
-   });
-
-   test("getItem returns correct item", async () => {
-      const item = createItem("key1", "value1");
-      await cache.save(item);
-      const retrievedItem = await cache.get("key1");
-      expect(retrievedItem.value()).toEqual(item.value());
-   });
-
-   test("getItem returns new item when key does not exist", async () => {
-      const retrievedItem = await cache.get("key1");
-      expect(retrievedItem.key()).toEqual("key1");
-      expect(retrievedItem.value()).toBeUndefined();
-   });
-
-   test("getItems returns correct items", async () => {
-      const item1 = createItem("key1", "value1");
-      const item2 = createItem("key2", "value2");
-      await cache.save(item1);
-      await cache.save(item2);
-      const retrievedItems = await cache.getMany(["key1", "key2"]);
-      expect(retrievedItems.get("key1")?.value()).toEqual(item1.value());
-      expect(retrievedItems.get("key2")?.value()).toEqual(item2.value());
-   });
-
-   test("hasItem returns true when item exists and is a hit", async () => {
-      const item = createItem("key1", "value1");
-      await cache.save(item);
-      expect(await cache.has("key1")).toBe(true);
-   });
-
-   test("clear and deleteItem correctly clear the cache and delete items", async () => {
-      const item = createItem("key1", "value1");
-      await cache.save(item);
-
-      if (cache.supports().clear) {
-         await cache.clear();
-      } else {
-         await cache.delete("key1");
-      }
-
-      expect(await cache.has("key1")).toBe(false);
-   });
-
-   test("save correctly saves items to the cache", async () => {
-      const item = createItem("key1", "value1");
-      await cache.save(item);
-      expect(await cache.has("key1")).toBe(true);
-   });
-
-   test("putItem correctly puts items in the cache ", async () => {
-      await cache.put("key1", "value1", { ttl: 60 });
-      const item = await cache.get("key1");
-      expect(item.value()).toEqual("value1");
-      expect(item.hit()).toBe(true);
-   });
-
-   /*test("commit returns true", async () => {
-      expect(await cache.commit()).toBe(true);
-   });*/
-}

app/__test__/core/utils.spec.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
-import { Perf, datetimeStringUTC, isBlob, ucFirst } from "../../src/core/utils";
+import { Perf, ucFirst } from "../../src/core/utils";
 import * as utils from "../../src/core/utils";
+import { assetsPath } from "../helper";
 
 async function wait(ms: number) {
    return new Promise((resolve) => {
@@ -75,57 +76,6 @@ describe("Core Utils", async () => {
          const result3 = utils.encodeSearch(obj3, { encode: true });
          expect(result3).toBe("id=123&name=%7B%22test%22%3A%22test%22%7D");
       });
-
-      describe("guards", () => {
-         const types = {
-            blob: new Blob(),
-            file: new File([""], "file.txt"),
-            stream: new ReadableStream(),
-            arrayBuffer: new ArrayBuffer(10),
-            arrayBufferView: new Uint8Array(new ArrayBuffer(10)),
-         };
-
-         const fns = [
-            [utils.isReadableStream, "stream"],
-            [utils.isBlob, "blob", ["stream", "arrayBuffer", "arrayBufferView"]],
-            [utils.isFile, "file", ["stream", "arrayBuffer", "arrayBufferView"]],
-            [utils.isArrayBuffer, "arrayBuffer"],
-            [utils.isArrayBufferView, "arrayBufferView"],
-         ] as const;
-
-         const additional = [0, 0.0, "", null, undefined, {}, []];
-
-         for (const [fn, type, _to_test] of fns) {
-            test(`is${ucFirst(type)}`, () => {
-               const to_test = _to_test ?? (Object.keys(types) as string[]);
-               for (const key of to_test) {
-                  const value = types[key as keyof typeof types];
-                  const result = fn(value);
-                  expect(result).toBe(key === type);
-               }
-
-               for (const value of additional) {
-                  const result = fn(value);
-                  expect(result).toBe(false);
-               }
-            });
-         }
-      });
-
-      test("getContentName", () => {
-         const name = "test.json";
-         const text = "attachment; filename=" + name;
-         const headers = new Headers({
-            "Content-Disposition": text,
-         });
-         const request = new Request("http://example.com", {
-            headers,
-         });
-
-         expect(utils.getContentName(text)).toBe(name);
-         expect(utils.getContentName(headers)).toBe(name);
-         expect(utils.getContentName(request)).toBe(name);
-      });
    });
 
    describe("perf", async () => {
@@ -246,6 +196,76 @@ describe("Core Utils", async () => {
       });
    });
 
+   describe("file", async () => {
+      describe("type guards", () => {
+         const types = {
+            blob: new Blob(),
+            file: new File([""], "file.txt"),
+            stream: new ReadableStream(),
+            arrayBuffer: new ArrayBuffer(10),
+            arrayBufferView: new Uint8Array(new ArrayBuffer(10)),
+         };
+
+         const fns = [
+            [utils.isReadableStream, "stream"],
+            [utils.isBlob, "blob", ["stream", "arrayBuffer", "arrayBufferView"]],
+            [utils.isFile, "file", ["stream", "arrayBuffer", "arrayBufferView"]],
+            [utils.isArrayBuffer, "arrayBuffer"],
+            [utils.isArrayBufferView, "arrayBufferView"],
+         ] as const;
+
+         const additional = [0, 0.0, "", null, undefined, {}, []];
+
+         for (const [fn, type, _to_test] of fns) {
+            test(`is${ucFirst(type)}`, () => {
+               const to_test = _to_test ?? (Object.keys(types) as string[]);
+               for (const key of to_test) {
+                  const value = types[key as keyof typeof types];
+                  const result = fn(value);
+                  expect(result).toBe(key === type);
+               }
+
+               for (const value of additional) {
+                  const result = fn(value);
+                  expect(result).toBe(false);
+               }
+            });
+         }
+      });
+
+      test("getContentName", () => {
+         const name = "test.json";
+         const text = "attachment; filename=" + name;
+         const headers = new Headers({
+            "Content-Disposition": text,
+         });
+         const request = new Request("http://example.com", {
+            headers,
+         });
+
+         expect(utils.getContentName(text)).toBe(name);
+         expect(utils.getContentName(headers)).toBe(name);
+         expect(utils.getContentName(request)).toBe(name);
+      });
+
+      test.only("detectImageDimensions", async () => {
+         // wrong
+         // @ts-expect-error
+         expect(utils.detectImageDimensions(new ArrayBuffer(), "text/plain")).rejects.toThrow();
+
+         // successful ones
+         const getFile = (name: string): File => Bun.file(`${assetsPath}/${name}`) as any;
+         expect(await utils.detectImageDimensions(getFile("image.png"))).toEqual({
+            width: 362,
+            height: 387,
+         });
+         expect(await utils.detectImageDimensions(getFile("image.jpg"))).toEqual({
+            width: 453,
+            height: 512,
+         });
+      });
+   });
+
    describe("dates", () => {
       test.only("formats local time", () => {
          expect(utils.datetimeStringUTC("2025-02-21T16:48:25.841Z")).toBe("2025-02-21 16:48:25");

app/__test__/data/specs/Mutator.spec.ts

@@ -288,14 +288,17 @@ describe("[data] Mutator (Events)", async () => {
 
    test("events were fired", async () => {
       const { data } = await mutator.insertOne({ label: "test" });
+      await mutator.emgr.executeAsyncs();
       expect(events.has(MutatorEvents.MutatorInsertBefore.slug)).toBeTrue();
       expect(events.has(MutatorEvents.MutatorInsertAfter.slug)).toBeTrue();
 
       await mutator.updateOne(data.id, { label: "test2" });
+      await mutator.emgr.executeAsyncs();
       expect(events.has(MutatorEvents.MutatorUpdateBefore.slug)).toBeTrue();
       expect(events.has(MutatorEvents.MutatorUpdateAfter.slug)).toBeTrue();
 
       await mutator.deleteOne(data.id);
+      await mutator.emgr.executeAsyncs();
       expect(events.has(MutatorEvents.MutatorDeleteBefore.slug)).toBeTrue();
       expect(events.has(MutatorEvents.MutatorDeleteAfter.slug)).toBeTrue();
    });

app/__test__/data/specs/Repository.spec.ts

@@ -1,6 +1,6 @@
 import { afterAll, describe, expect, test } from "bun:test";
 import type { Kysely, Transaction } from "kysely";
-import { Perf } from "../../../src/core/utils";
+import { Perf } from "core/utils";
 import {
    Entity,
    EntityManager,
@@ -8,7 +8,10 @@ import {
    ManyToOneRelation,
    RepositoryEvents,
    TextField,
-} from "../../../src/data";
+   entity as $entity,
+   text as $text,
+   em as $em,
+} from "data";
 import { getDummyConnection } from "../helper";
 
 type E = Kysely<any> | Transaction<any>;
@@ -177,6 +180,47 @@ describe("[Repository]", async () => {
       const res5 = await em.repository(items).exists({});
       expect(res5.exists).toBe(true);
    });
+
+   test("option: silent", async () => {
+      const em = $em({
+         items: $entity("items", {
+            label: $text(),
+         }),
+      }).proto.withConnection(getDummyConnection().dummyConnection);
+
+      // should throw because table doesn't exist
+      expect(em.repo("items").findMany({})).rejects.toThrow(/no such table/);
+      // should silently return empty result
+      expect(
+         em
+            .repo("items", { silent: true })
+            .findMany({})
+            .then((r) => r.data),
+      ).resolves.toEqual([]);
+   });
+
+   test("option: includeCounts", async () => {
+      const em = $em({
+         items: $entity("items", {
+            label: $text(),
+         }),
+      }).proto.withConnection(getDummyConnection().dummyConnection);
+      await em.schema().sync({ force: true });
+
+      expect(
+         em
+            .repo("items")
+            .findMany({})
+            .then((r) => [r.meta.count, r.meta.total]),
+      ).resolves.toEqual([0, 0]);
+
+      expect(
+         em
+            .repo("items", { includeCounts: false })
+            .findMany({})
+            .then((r) => [r.meta.count, r.meta.total]),
+      ).resolves.toEqual([undefined, undefined]);
+   });
 });
 
 describe("[data] Repository (Events)", async () => {
@@ -198,22 +242,27 @@ describe("[data] Repository (Events)", async () => {
    });
 
    test("events were fired", async () => {
-      await em.repository(items).findId(1);
+      const repo = em.repository(items);
+      await repo.findId(1);
+      await repo.emgr.executeAsyncs();
       expect(events.has(RepositoryEvents.RepositoryFindOneBefore.slug)).toBeTrue();
       expect(events.has(RepositoryEvents.RepositoryFindOneAfter.slug)).toBeTrue();
       events.clear();
 
-      await em.repository(items).findOne({ id: 1 });
+      await repo.findOne({ id: 1 });
+      await repo.emgr.executeAsyncs();
       expect(events.has(RepositoryEvents.RepositoryFindOneBefore.slug)).toBeTrue();
       expect(events.has(RepositoryEvents.RepositoryFindOneAfter.slug)).toBeTrue();
       events.clear();
 
-      await em.repository(items).findMany({ where: { id: 1 } });
+      await repo.findMany({ where: { id: 1 } });
+      await repo.emgr.executeAsyncs();
       expect(events.has(RepositoryEvents.RepositoryFindManyBefore.slug)).toBeTrue();
       expect(events.has(RepositoryEvents.RepositoryFindManyAfter.slug)).toBeTrue();
       events.clear();
 
-      await em.repository(items).findManyByReference(1, "categories");
+      await repo.findManyByReference(1, "categories");
+      await repo.emgr.executeAsyncs();
       expect(events.has(RepositoryEvents.RepositoryFindManyBefore.slug)).toBeTrue();
       expect(events.has(RepositoryEvents.RepositoryFindManyAfter.slug)).toBeTrue();
       events.clear();

app/__test__/data/specs/fields/BooleanField.spec.ts

@@ -1,9 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import { BooleanField } from "../../../../src/data";
-import { runBaseFieldTests, transformPersist } from "./inc";
+import { fieldTestSuite, transformPersist } from "data/fields/field-test-suite";
 
 describe("[data] BooleanField", async () => {
-   runBaseFieldTests(BooleanField, { defaultValue: true, schemaType: "boolean" });
+   fieldTestSuite({ expect, test }, BooleanField, { defaultValue: true, schemaType: "boolean" });
 
    test("transformRetrieve", async () => {
       const field = new BooleanField("test");

app/__test__/data/specs/fields/DateField.spec.ts

@@ -1,9 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import { DateField } from "../../../../src/data";
-import { runBaseFieldTests } from "./inc";
+import { fieldTestSuite } from "data/fields/field-test-suite";
 
 describe("[data] DateField", async () => {
-   runBaseFieldTests(DateField, { defaultValue: new Date(), schemaType: "date" });
+   fieldTestSuite({ expect, test }, DateField, { defaultValue: new Date(), schemaType: "date" });
 
    // @todo: add datefield tests
    test("week", async () => {

app/__test__/data/specs/fields/EnumField.spec.ts

@@ -1,13 +1,15 @@
 import { describe, expect, test } from "bun:test";
 import { EnumField } from "../../../../src/data";
-import { runBaseFieldTests, transformPersist } from "./inc";
+import { fieldTestSuite, transformPersist } from "data/fields/field-test-suite";
 
 function options(strings: string[]) {
    return { type: "strings", values: strings };
 }
 
 describe("[data] EnumField", async () => {
-   runBaseFieldTests(
+   fieldTestSuite(
+      { expect, test },
+      // @ts-ignore
       EnumField,
       { defaultValue: "a", schemaType: "text" },
       { options: options(["a", "b", "c"]) },
@@ -15,11 +17,13 @@ describe("[data] EnumField", async () => {
 
    test("yields if default value is not a valid option", async () => {
       expect(
+         // @ts-ignore
          () => new EnumField("test", { options: options(["a", "b"]), default_value: "c" }),
       ).toThrow();
    });
 
    test("transformPersist (config)", async () => {
+      // @ts-ignore
       const field = new EnumField("test", { options: options(["a", "b", "c"]) });
 
       expect(transformPersist(field, null)).resolves.toBeUndefined();
@@ -29,6 +33,7 @@ describe("[data] EnumField", async () => {
 
    test("transformRetrieve", async () => {
       const field = new EnumField("test", {
+         // @ts-ignore
          options: options(["a", "b", "c"]),
          default_value: "a",
          required: true,

app/__test__/data/specs/fields/Field.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { Default, stripMark } from "../../../../src/core/utils";
 import { baseFieldConfigSchema, Field } from "../../../../src/data/fields/Field";
-import { runBaseFieldTests } from "./inc";
+import { fieldTestSuite } from "data/fields/field-test-suite";
 
 describe("[data] Field", async () => {
    class FieldSpec extends Field {
@@ -19,7 +19,7 @@ describe("[data] Field", async () => {
       });
    });
 
-   runBaseFieldTests(FieldSpec, { defaultValue: "test", schemaType: "text" });
+   fieldTestSuite({ expect, test }, FieldSpec, { defaultValue: "test", schemaType: "text" });
 
    test("default config", async () => {
       const config = Default(baseFieldConfigSchema, {});

app/__test__/data/specs/fields/FieldIndex.spec.ts

@@ -1,19 +1,13 @@
 import { describe, expect, test } from "bun:test";
 import { Type } from "../../../../src/core/utils";
-import {
+import { Entity, EntityIndex, Field } from "../../../../src/data";
-   Entity,
-   EntityIndex,
-   type EntityManager,
-   Field,
-   type SchemaResponse,
-} from "../../../../src/data";
 
 class TestField extends Field {
    protected getSchema(): any {
       return Type.Any();
    }
 
-   schema(em: EntityManager<any>): SchemaResponse {
+   override schema() {
       return undefined as any;
    }
 }

app/__test__/data/specs/fields/JsonField.spec.ts

@@ -1,10 +1,10 @@
 import { describe, expect, test } from "bun:test";
 import { JsonField } from "../../../../src/data";
-import { runBaseFieldTests, transformPersist } from "./inc";
+import { fieldTestSuite, transformPersist } from "data/fields/field-test-suite";
 
 describe("[data] JsonField", async () => {
    const field = new JsonField("test");
-   runBaseFieldTests(JsonField, {
+   fieldTestSuite({ expect, test }, JsonField, {
       defaultValue: { a: 1 },
       sampleValues: ["string", { test: 1 }, 1],
       schemaType: "text",

app/__test__/data/specs/fields/JsonSchemaField.spec.ts

@@ -1,9 +1,10 @@
 import { describe, expect, test } from "bun:test";
 import { JsonSchemaField } from "../../../../src/data";
-import { runBaseFieldTests } from "./inc";
+import { fieldTestSuite } from "data/fields/field-test-suite";
 
 describe("[data] JsonSchemaField", async () => {
-   runBaseFieldTests(JsonSchemaField, { defaultValue: {}, schemaType: "text" });
+   // @ts-ignore
+   fieldTestSuite({ expect, test }, JsonSchemaField, { defaultValue: {}, schemaType: "text" });
 
    // @todo: add JsonSchemaField tests
 });

app/__test__/data/specs/fields/NumberField.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { NumberField } from "../../../../src/data";
-import { runBaseFieldTests, transformPersist } from "./inc";
+import { fieldTestSuite, transformPersist } from "data/fields/field-test-suite";
 
 describe("[data] NumberField", async () => {
    test("transformPersist (config)", async () => {
@@ -15,5 +15,5 @@ describe("[data] NumberField", async () => {
       expect(transformPersist(field2, 10000)).resolves.toBe(10000);
    });
 
-   runBaseFieldTests(NumberField, { defaultValue: 12, schemaType: "integer" });
+   fieldTestSuite({ expect, test }, NumberField, { defaultValue: 12, schemaType: "integer" });
 });

app/__test__/data/specs/fields/TextField.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { TextField } from "../../../../src/data";
-import { runBaseFieldTests, transformPersist } from "./inc";
+import { fieldTestSuite, transformPersist } from "data/fields/field-test-suite";
 
 describe("[data] TextField", async () => {
    test("transformPersist (config)", async () => {
@@ -11,5 +11,5 @@ describe("[data] TextField", async () => {
       expect(transformPersist(field, "abc")).resolves.toBe("abc");
    });
 
-   runBaseFieldTests(TextField, { defaultValue: "abc", schemaType: "text" });
+   fieldTestSuite({ expect, test }, TextField, { defaultValue: "abc", schemaType: "text" });
 });

app/__test__/helper.ts

@@ -78,6 +78,7 @@ export const assetsTmpPath = `${import.meta.dir}/_assets/tmp`;
 export async function enableFetchLogging() {
    const originalFetch = global.fetch;
 
+   // @ts-ignore
    global.fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
       const response = await originalFetch(input, init);
       const url = input instanceof URL || typeof input === "string" ? input : input.url;

app/__test__/media/MediaController.spec.ts

@@ -4,7 +4,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { createApp, registries } from "../../src";
 import { mergeObject, randomString } from "../../src/core/utils";
 import type { TAppMediaConfig } from "../../src/media/media-schema";
-import { StorageLocalAdapter } from "../../src/media/storage/adapters/StorageLocalAdapter";
+import { StorageLocalAdapter } from "adapter/node/storage/StorageLocalAdapter";
 import { assetsPath, assetsTmpPath, disableConsoleLog, enableConsoleLog } from "../helper";
 
 beforeAll(() => {

app/__test__/media/Storage.spec.ts

@@ -1,8 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { type FileBody, Storage, type StorageAdapter } from "../../src/media/storage/Storage";
+import { type FileBody, Storage } from "../../src/media/storage/Storage";
 import * as StorageEvents from "../../src/media/storage/events";
+import { StorageAdapter } from "media";
 
-class TestAdapter implements StorageAdapter {
+class TestAdapter extends StorageAdapter {
    files: Record<string, FileBody> = {};
 
    getName() {
@@ -61,7 +62,7 @@ describe("Storage", async () => {
    test("uploads a file", async () => {
       const {
          meta: { type, size },
-      } = await storage.uploadFile("hello", "world.txt");
+      } = await storage.uploadFile("hello" as any, "world.txt");
       expect({ type, size }).toEqual({ type: "text/plain", size: 0 });
    });
 
@@ -71,6 +72,7 @@ describe("Storage", async () => {
    });
 
    test("events were fired", async () => {
+      await storage.emgr.executeAsyncs();
       expect(events.has(StorageEvents.FileUploadedEvent.slug)).toBeTrue();
       expect(events.has(StorageEvents.FileDeletedEvent.slug)).toBeTrue();
       // @todo: file access must be tested in controllers

app/__test__/media/StorageR2Adapter.native-spec.ts

@@ -1,34 +0,0 @@
-import * as assert from "node:assert/strict";
-import { createWriteStream } from "node:fs";
-import { test } from "node:test";
-import { Miniflare } from "miniflare";
-
-// https://github.com/nodejs/node/issues/44372#issuecomment-1736530480
-console.log = async (message: any) => {
-   const tty = createWriteStream("/dev/tty");
-   const msg = typeof message === "string" ? message : JSON.stringify(message, null, 2);
-   return tty.write(`${msg}\n`);
-};
-
-test("what", async () => {
-   const mf = new Miniflare({
-      modules: true,
-      script: "export default { async fetch() { return new Response(null); } }",
-      r2Buckets: ["BUCKET"],
-   });
-
-   const bucket = await mf.getR2Bucket("BUCKET");
-   console.log(await bucket.put("count", "1"));
-
-   const object = await bucket.get("count");
-   if (object) {
-      /*const headers = new Headers();
-      object.writeHttpMetadata(headers);
-      headers.set("etag", object.httpEtag);*/
-      console.log("yo -->", await object.text());
-
-      assert.strictEqual(await object.text(), "1");
-   }
-
-   await mf.dispose();
-});

app/__test__/media/adapters/StorageCloudinaryAdapter.spec.ts

@@ -1,63 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { randomString } from "../../../src/core/utils";
-import { StorageCloudinaryAdapter } from "../../../src/media";
-
-import { config } from "dotenv";
-const dotenvOutput = config({ path: `${import.meta.dir}/../../../.env` });
-const {
-   CLOUDINARY_CLOUD_NAME,
-   CLOUDINARY_API_KEY,
-   CLOUDINARY_API_SECRET,
-   CLOUDINARY_UPLOAD_PRESET,
-} = dotenvOutput.parsed!;
-
-const ALL_TESTS = !!process.env.ALL_TESTS;
-
-describe.skipIf(ALL_TESTS)("StorageCloudinaryAdapter", () => {
-   if (ALL_TESTS) return;
-
-   const adapter = new StorageCloudinaryAdapter({
-      cloud_name: CLOUDINARY_CLOUD_NAME as string,
-      api_key: CLOUDINARY_API_KEY as string,
-      api_secret: CLOUDINARY_API_SECRET as string,
-      upload_preset: CLOUDINARY_UPLOAD_PRESET as string,
-   });
-
-   const file = Bun.file(`${import.meta.dir}/icon.png`);
-   const _filename = randomString(10);
-   const filename = `${_filename}.png`;
-
-   test("object exists", async () => {
-      expect(await adapter.objectExists("7fCTBi6L8c.png")).toBeTrue();
-      process.exit();
-   });
-
-   test("puts object", async () => {
-      expect(await adapter.objectExists(filename)).toBeFalse();
-
-      const result = await adapter.putObject(filename, file);
-      console.log("result", result);
-      expect(result).toBeDefined();
-      expect(result?.name).toBe(filename);
-   });
-
-   test("object exists", async () => {
-      await Bun.sleep(10000);
-      const one = await adapter.objectExists(_filename);
-      const two = await adapter.objectExists(filename);
-      expect(await adapter.objectExists(filename)).toBeTrue();
-   });
-
-   test("object meta", async () => {
-      const result = await adapter.getObjectMeta(filename);
-      console.log("objectMeta:result", result);
-      expect(result).toBeDefined();
-      expect(result.type).toBe("image/png");
-      expect(result.size).toBeGreaterThan(0);
-   });
-
-   test("list objects", async () => {
-      const result = await adapter.listObjects();
-      console.log("listObjects:result", result);
-   });
-});

app/__test__/media/adapters/StorageLocalAdapter.spec.ts

@@ -1,47 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { randomString } from "../../../src/core/utils";
-import { StorageLocalAdapter } from "../../../src/media/storage/adapters/StorageLocalAdapter";
-import { assetsPath, assetsTmpPath } from "../../helper";
-
-describe("StorageLocalAdapter", () => {
-   const adapter = new StorageLocalAdapter({
-      path: assetsTmpPath,
-   });
-
-   const file = Bun.file(`${assetsPath}/image.png`);
-   const _filename = randomString(10);
-   const filename = `${_filename}.png`;
-
-   let objects = 0;
-
-   test("puts an object", async () => {
-      objects = (await adapter.listObjects()).length;
-      expect(await adapter.putObject(filename, file as unknown as File)).toBeString();
-   });
-
-   test("lists objects", async () => {
-      expect((await adapter.listObjects()).length).toBe(objects + 1);
-   });
-
-   test("file exists", async () => {
-      expect(await adapter.objectExists(filename)).toBeTrue();
-   });
-
-   test("gets an object", async () => {
-      const res = await adapter.getObject(filename, new Headers());
-      expect(res.ok).toBeTrue();
-      // @todo: check the content
-   });
-
-   test("gets object meta", async () => {
-      expect(await adapter.getObjectMeta(filename)).toEqual({
-         type: file.type, // image/png
-         size: file.size,
-      });
-   });
-
-   test("deletes an object", async () => {
-      expect(await adapter.deleteObject(filename)).toBeUndefined();
-      expect(await adapter.objectExists(filename)).toBeFalse();
-   });
-});

app/__test__/media/adapters/StorageS3Adapter.spec.ts

@@ -1,109 +0,0 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { randomString } from "../../../src/core/utils";
-import { StorageS3Adapter } from "../../../src/media";
-
-import { config } from "dotenv";
-//import { enableFetchLogging } from "../../helper";
-const dotenvOutput = config({ path: `${import.meta.dir}/../../../.env` });
-const { R2_ACCESS_KEY, R2_SECRET_ACCESS_KEY, R2_URL, AWS_ACCESS_KEY, AWS_SECRET_KEY, AWS_S3_URL } =
-   dotenvOutput.parsed!;
-
-// @todo: mock r2/s3 responses for faster tests
-const ALL_TESTS = !!process.env.ALL_TESTS;
-console.log("ALL_TESTS?", ALL_TESTS);
-
-/* 
-// @todo: preparation to mock s3 calls + replace fast-xml-parser
-let cleanup: () => void;
-beforeAll(async () => {
-   cleanup = await enableFetchLogging();
-});
-afterAll(() => {
-   cleanup();
-}); */
-
-describe.skipIf(ALL_TESTS)("StorageS3Adapter", async () => {
-   if (ALL_TESTS) return;
-
-   const versions = [
-      [
-         "r2",
-         new StorageS3Adapter({
-            access_key: R2_ACCESS_KEY as string,
-            secret_access_key: R2_SECRET_ACCESS_KEY as string,
-            url: R2_URL as string,
-         }),
-      ],
-      [
-         "s3",
-         new StorageS3Adapter({
-            access_key: AWS_ACCESS_KEY as string,
-            secret_access_key: AWS_SECRET_KEY as string,
-            url: AWS_S3_URL as string,
-         }),
-      ],
-   ] as const;
-
-   const _conf = {
-      adapters: ["r2", "s3"],
-      tests: [
-         "listObjects",
-         "putObject",
-         "objectExists",
-         "getObject",
-         "deleteObject",
-         "getObjectMeta",
-      ],
-   };
-
-   const file = Bun.file(`${import.meta.dir}/icon.png`);
-   const filename = `${randomString(10)}.png`;
-
-   // single (dev)
-   //_conf = { adapters: [/*"r2",*/ "s3"], tests: [/*"putObject",*/ "listObjects"] };
-
-   function disabled(test: (typeof _conf.tests)[number]) {
-      return !_conf.tests.includes(test);
-   }
-
-   // @todo: add mocked fetch for faster tests
-   describe.each(versions)("StorageS3Adapter for %s", async (name, adapter) => {
-      if (!_conf.adapters.includes(name) || ALL_TESTS) {
-         console.log("Skipping", name);
-         return;
-      }
-
-      let objects = 0;
-
-      test.skipIf(disabled("putObject"))("puts an object", async () => {
-         objects = (await adapter.listObjects()).length;
-         expect(await adapter.putObject(filename, file as any)).toBeString();
-      });
-
-      test.skipIf(disabled("listObjects"))("lists objects", async () => {
-         expect((await adapter.listObjects()).length).toBe(objects + 1);
-      });
-
-      test.skipIf(disabled("objectExists"))("file exists", async () => {
-         expect(await adapter.objectExists(filename)).toBeTrue();
-      });
-
-      test.skipIf(disabled("getObject"))("gets an object", async () => {
-         const res = await adapter.getObject(filename, new Headers());
-         expect(res.ok).toBeTrue();
-         // @todo: check the content
-      });
-
-      test.skipIf(disabled("getObjectMeta"))("gets object meta", async () => {
-         expect(await adapter.getObjectMeta(filename)).toEqual({
-            type: file.type, // image/png
-            size: file.size,
-         });
-      });
-
-      test.skipIf(disabled("deleteObject"))("deletes an object", async () => {
-         expect(await adapter.deleteObject(filename)).toBeUndefined();
-         expect(await adapter.objectExists(filename)).toBeFalse();
-      });
-   });
-});

app/__test__/media/mime-types.spec.ts

@@ -5,7 +5,9 @@ import { getRandomizedFilename } from "../../src/media/utils";
 
 describe("media/mime-types", () => {
    test("tiny resolves", () => {
-      const tests = [[".mp4", "video/mp4", ".jpg", "image/jpeg", ".zip", "application/zip"]];
+      const tests = [
+         [".mp4", "video/mp4", ".jpg", "image/jpeg", ".zip", "application/zip"],
+      ] as const;
 
       for (const [ext, mime] of tests) {
          expect(tiny.guess(ext)).toBe(mime);
@@ -69,7 +71,7 @@ describe("media/mime-types", () => {
          ["application/zip", "zip"],
          ["text/tab-separated-values", "tsv"],
          ["application/zip", "zip"],
-      ];
+      ] as const;
 
       for (const [mime, ext] of tests) {
          expect(tiny.extension(mime), `extension(): ${mime} should be ${ext}`).toBe(ext);
@@ -86,7 +88,7 @@ describe("media/mime-types", () => {
          ["image.jpeg", "jpeg"],
          ["-473Wx593H-466453554-black-MODEL.jpg", "jpg"],
          ["-473Wx593H-466453554-black-MODEL.avif", "avif"],
-      ];
+      ] as const;
 
       for (const [filename, ext] of tests) {
          expect(
@@ -94,5 +96,10 @@ describe("media/mime-types", () => {
             `getRandomizedFilename(): ${filename} should end with ${ext}`,
          ).toBe(ext);
       }
+
+      // make sure it keeps the extension, even if the file has a different type
+      const file = new File([""], "image.jpg", { type: "text/plain" });
+      const [, ext] = getRandomizedFilename(file).split(".");
+      expect(ext).toBe("jpg");
    });
 });

app/__test__/modules/AppMedia.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { createApp, registries } from "../../src";
 import { em, entity, text } from "../../src/data";
-import { StorageLocalAdapter } from "../../src/media/storage/adapters/StorageLocalAdapter";
+import { StorageLocalAdapter } from "adapter/node/storage/StorageLocalAdapter";
 import { AppMedia } from "../../src/modules";
 import { moduleTestSuite } from "./module-test-suite";
 

app/__test__/vitest/base.vi-test.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from "vitest";
+
+describe("Example Test Suite", () => {
+   it("should pass basic arithmetic", () => {
+      expect(1 + 1).toBe(2);
+   });
+
+   it("should handle async operations", async () => {
+      const result = await Promise.resolve(42);
+      expect(result).toBe(42);
+   });
+});

app/__test__/vitest/setup.ts

@@ -0,0 +1,8 @@
+import "@testing-library/jest-dom";
+import { afterEach } from "vitest";
+import { cleanup } from "@testing-library/react";
+
+// Automatically cleanup after each test
+afterEach(() => {
+   cleanup();
+});

app/build.ts

@@ -54,7 +54,7 @@ function banner(title: string) {
 }
 
 // collection of always-external packages
-const external = ["bun:test", "@libsql/client"] as const;
+const external = ["bun:test", "node:test", "node:assert/strict", "@libsql/client"] as const;
 
 /**
  * Building backend and general API
@@ -65,7 +65,13 @@ async function buildApi() {
       minify,
       sourcemap,
       watch,
-      entry: ["src/index.ts", "src/data/index.ts", "src/core/index.ts", "src/core/utils/index.ts"],
+      entry: [
+         "src/index.ts",
+         "src/core/index.ts",
+         "src/core/utils/index.ts",
+         "src/data/index.ts",
+         "src/media/index.ts",
+      ],
       outDir: "dist",
       external: [...external],
       metafile: true,

app/e2e/adapters.ts

@@ -0,0 +1,206 @@
+import { $ } from "bun";
+import path from "node:path";
+import c from "picocolors";
+
+const basePath = new URL(import.meta.resolve("../../")).pathname.slice(0, -1);
+
+async function run(
+   cmd: string[] | string,
+   opts: Bun.SpawnOptions.OptionsObject & {},
+   onChunk: (chunk: string, resolve: (data: any) => void, reject: (err: Error) => void) => void,
+): Promise<{ proc: Bun.Subprocess; data: any }> {
+   return new Promise((resolve, reject) => {
+      const proc = Bun.spawn(Array.isArray(cmd) ? cmd : cmd.split(" "), {
+         ...opts,
+         stdout: "pipe",
+         stderr: "pipe",
+      });
+
+      // Read from stdout
+      const reader = proc.stdout.getReader();
+      const decoder = new TextDecoder();
+
+      // Function to read chunks
+      let resolveCalled = false;
+      (async () => {
+         try {
+            while (true) {
+               const { done, value } = await reader.read();
+               if (done) break;
+
+               const text = decoder.decode(value);
+               if (!resolveCalled) {
+                  console.log(c.dim(text.replace(/\n$/, "")));
+               }
+               onChunk(
+                  text,
+                  (data) => {
+                     resolve({ proc, data });
+                     resolveCalled = true;
+                  },
+                  reject,
+               );
+            }
+         } catch (err) {
+            reject(err);
+         }
+      })();
+
+      proc.exited.then((code) => {
+         if (code !== 0 && code !== 130) {
+            throw new Error(`Process exited with code ${code}`);
+         }
+      });
+   });
+}
+
+const adapters = {
+   node: {
+      dir: path.join(basePath, "examples/node"),
+      clean: async function () {
+         const cwd = path.relative(process.cwd(), this.dir);
+         await $`cd ${cwd} && rm -rf uploads data.db && mkdir -p uploads`;
+      },
+      start: async function () {
+         return await run(
+            "npm run start",
+            {
+               cwd: this.dir,
+            },
+            (chunk, resolve, reject) => {
+               const regex = /running on (http:\/\/.*)\n/;
+               if (regex.test(chunk)) {
+                  resolve(chunk.match(regex)?.[1]);
+               }
+            },
+         );
+      },
+   },
+   bun: {
+      dir: path.join(basePath, "examples/bun"),
+      clean: async function () {
+         const cwd = path.relative(process.cwd(), this.dir);
+         await $`cd ${cwd} && rm -rf uploads data.db && mkdir -p uploads`;
+      },
+      start: async function () {
+         return await run(
+            "npm run start",
+            {
+               cwd: this.dir,
+            },
+            (chunk, resolve, reject) => {
+               const regex = /running on (http:\/\/.*)\n/;
+               if (regex.test(chunk)) {
+                  resolve(chunk.match(regex)?.[1]);
+               }
+            },
+         );
+      },
+   },
+   cloudflare: {
+      dir: path.join(basePath, "examples/cloudflare-worker"),
+      clean: async function () {
+         const cwd = path.relative(process.cwd(), this.dir);
+         await $`cd ${cwd} && rm -rf .wrangler node_modules/.cache node_modules/.mf`;
+      },
+      start: async function () {
+         return await run(
+            "npm run dev",
+            {
+               cwd: this.dir,
+            },
+            (chunk, resolve, reject) => {
+               const regex = /Ready on (http:\/\/.*)/;
+               if (regex.test(chunk)) {
+                  resolve(chunk.match(regex)?.[1]);
+               }
+            },
+         );
+      },
+   },
+   "react-router": {
+      dir: path.join(basePath, "examples/react-router"),
+      clean: async function () {
+         const cwd = path.relative(process.cwd(), this.dir);
+         await $`cd ${cwd} && rm -rf .react-router data.db`;
+         await $`cd ${cwd} && rm -rf public/uploads && mkdir -p public/uploads`;
+      },
+      start: async function () {
+         return await run(
+            "npm run dev",
+            {
+               cwd: this.dir,
+            },
+            (chunk, resolve, reject) => {
+               const regex = /Local.*?(http:\/\/.*)\//;
+               if (regex.test(chunk)) {
+                  resolve(chunk.match(regex)?.[1]);
+               }
+            },
+         );
+      },
+   },
+   nextjs: {
+      dir: path.join(basePath, "examples/nextjs"),
+      clean: async function () {
+         const cwd = path.relative(process.cwd(), this.dir);
+         await $`cd ${cwd} && rm -rf .nextjs data.db`;
+         await $`cd ${cwd} && rm -rf public/uploads && mkdir -p public/uploads`;
+      },
+      start: async function () {
+         return await run(
+            "npm run dev",
+            {
+               cwd: this.dir,
+            },
+            (chunk, resolve, reject) => {
+               const regex = /Local.*?(http:\/\/.*)\n/;
+               if (regex.test(chunk)) {
+                  resolve(chunk.match(regex)?.[1]);
+               }
+            },
+         );
+      },
+   },
+   astro: {
+      dir: path.join(basePath, "examples/astro"),
+      clean: async function () {
+         const cwd = path.relative(process.cwd(), this.dir);
+         await $`cd ${cwd} && rm -rf .astro data.db`;
+         await $`cd ${cwd} && rm -rf public/uploads && mkdir -p public/uploads`;
+      },
+      start: async function () {
+         return await run(
+            "npm run dev",
+            {
+               cwd: this.dir,
+            },
+            (chunk, resolve, reject) => {
+               const regex = /Local.*?(http:\/\/.*)\//;
+               if (regex.test(chunk)) {
+                  resolve(chunk.match(regex)?.[1]);
+               }
+            },
+         );
+      },
+   },
+} as const;
+
+for (const [name, config] of Object.entries(adapters)) {
+   console.log("adapter", c.cyan(name));
+   await config.clean();
+
+   const { proc, data } = await config.start();
+   console.log("proc:", proc.pid, "data:", c.cyan(data));
+   //proc.kill();process.exit(0);
+
+   await $`TEST_URL=${data} TEST_ADAPTER=${name} bun run test:e2e`;
+   console.log("DONE!");
+
+   while (!proc.killed) {
+      proc.kill("SIGINT");
+      await Bun.sleep(250);
+      console.log("Waiting for process to exit...");
+   }
+   //process.exit(0);
+}

app/e2e/base.e2e-spec.ts

@@ -0,0 +1,25 @@
+// @ts-check
+import { test, expect } from "@playwright/test";
+import { testIds } from "../src/ui/lib/config";
+
+import { getAdapterConfig } from "./inc/adapters";
+const config = getAdapterConfig();
+
+test("start page has expected title", async ({ page }) => {
+   await page.goto(config.base_path);
+   await expect(page).toHaveTitle(/BKND/);
+});
+
+test("start page has expected heading", async ({ page }) => {
+   await page.goto(config.base_path);
+
+   // Example of checking if a heading with "No entity selected" exists and is visible
+   const heading = page.getByRole("heading", { name: /No entity selected/i });
+   await expect(heading).toBeVisible();
+});
+
+test("modal opens on button click", async ({ page }) => {
+   await page.goto(config.base_path);
+   await page.getByTestId(testIds.data.btnCreateEntity).click();
+   await expect(page.getByRole("dialog")).toBeVisible();
+});

app/e2e/inc/adapters.ts

@@ -0,0 +1,44 @@
+const adapter = process.env.TEST_ADAPTER;
+
+const default_config = {
+   media_adapter: "local",
+   base_path: "",
+} as const;
+
+const configs = {
+   cloudflare: {
+      media_adapter: "r2",
+   },
+   "react-router": {
+      base_path: "/admin",
+   },
+   nextjs: {
+      base_path: "/admin",
+   },
+   astro: {
+      base_path: "/admin",
+   },
+   node: {
+      base_path: "",
+   },
+   bun: {
+      base_path: "",
+   },
+};
+
+export function getAdapterConfig(): typeof default_config {
+   if (adapter) {
+      if (!configs[adapter]) {
+         console.warn(
+            `Adapter "${adapter}" not found. Available adapters: ${Object.keys(configs).join(", ")}`,
+         );
+      } else {
+         return {
+            ...default_config,
+            ...configs[adapter],
+         };
+      }
+   }
+
+   return default_config;
+}

app/e2e/media.e2e-spec.ts

@@ -0,0 +1,55 @@
+// @ts-check
+import { test, expect } from "@playwright/test";
+import { testIds } from "../src/ui/lib/config";
+import type { SchemaResponse } from "../src/modules/server/SystemController";
+import { getAdapterConfig } from "./inc/adapters";
+
+// Annotate entire file as serial.
+test.describe.configure({ mode: "serial" });
+
+const config = getAdapterConfig();
+
+test("can enable media", async ({ page }) => {
+   await page.goto(`${config.base_path}/media/settings`);
+
+   // enable
+   const enableToggle = page.locator("css=button#enabled");
+   if ((await enableToggle.getAttribute("aria-checked")) !== "true") {
+      await expect(enableToggle).toBeVisible();
+      await enableToggle.click();
+      await expect(enableToggle).toHaveAttribute("aria-checked", "true");
+
+      // select local
+      const adapterChoice = page.locator(`css=button#adapter-${config.media_adapter}`);
+      await expect(adapterChoice).toBeVisible();
+      await adapterChoice.click();
+
+      // save
+      const saveBtn = page.getByRole("button", { name: /Update/i });
+      await expect(saveBtn).toBeVisible();
+
+      // intercept network request, wait for it to finish and get the response
+      const [request] = await Promise.all([
+         page.waitForRequest((request) => request.url().includes("api/system/schema")),
+         saveBtn.click(),
+      ]);
+      const response = await request.response();
+      expect(response?.status(), "fresh config 200").toBe(200);
+      const body = (await response?.json()) as SchemaResponse;
+      expect(body.config.media.enabled, "media is enabled").toBe(true);
+      expect(body.config.media.adapter?.type, "correct adapter").toBe(config.media_adapter);
+   }
+});
+
+test("can upload a file", async ({ page }) => {
+   await page.goto(`${config.base_path}/media`);
+   // check any text to contain "Upload files"
+   await expect(page.getByText(/Upload files/i)).toBeVisible();
+
+   // upload a file from disk
+   // Start waiting for file chooser before clicking. Note no await.
+   const fileChooserPromise = page.waitForEvent("filechooser");
+   await page.getByText("Upload file").click();
+   const fileChooser = await fileChooserPromise;
+   await fileChooser.setFiles("./e2e/assets/image.jpg");
+});

app/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "sideEffects": false,
   "bin": "./dist/cli/index.js",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Lightweight Firebase/Supabase alternative built to run anywhere — incl. Next.js, React Router, Astro, Cloudflare, Bun, Node, AWS Lambda & more.",
   "homepage": "https://bknd.io",
   "repository": {
@@ -15,10 +15,9 @@
   },
   "scripts": {
     "dev": "vite",
-    "test": "ALL_TESTS=1 bun test --bail",
-    "test:coverage": "ALL_TESTS=1 bun test --bail --coverage",
     "build": "NODE_ENV=production bun run build.ts --minify --types",
     "build:all": "rm -rf dist && bun run build:static && NODE_ENV=production bun run build.ts --minify --types --clean && bun run build:cli",
+    "build:ci": "mkdir -p dist/static/.vite && echo '{}' > dist/static/.vite/manifest.json && NODE_ENV=production bun run build.ts",
     "build:cli": "bun build src/cli/index.ts --target node --outdir dist/cli --env PUBLIC_* --minify",
     "build:static": "vite build",
     "watch": "bun run build.ts --types --watch",
@@ -27,8 +26,22 @@
     "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly && tsc-alias",
     "updater": "bun x npm-check-updates -ui",
     "cli": "LOCAL=1 bun src/cli/index.ts",
-    "prepublishOnly": "bun run types && bun run test && bun run build:all && cp ../README.md ./",
+    "prepublishOnly": "bun run types && bun run test && bun run test:node && bun run build:all && cp ../README.md ./",
-    "postpublish": "rm -f README.md"
+    "postpublish": "rm -f README.md",
+    "test": "ALL_TESTS=1 bun test --bail",
+    "test:all": "bun run test && bun run test:node",
+    "test:bun": "ALL_TESTS=1 bun test --bail",
+    "test:node": "tsx --test $(find . -type f -name '*.native-spec.ts')",
+    "test:adapters": "bun test src/adapter/**/*.adapter.spec.ts --bail",
+    "test:coverage": "ALL_TESTS=1 bun test --bail --coverage",
+    "test:vitest": "vitest run",
+    "test:vitest:watch": "vitest",
+    "test:vitest:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:adapters": "bun run e2e/adapters.ts",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:debug": "playwright test --debug",
+    "test:e2e:report": "playwright show-report"
   },
   "license": "FSL-1.1-MIT",
   "dependencies": {
@@ -37,7 +50,7 @@
     "@codemirror/lang-json": "^6.0.1",
     "@codemirror/lang-liquid": "^6.2.2",
     "@hello-pangea/dnd": "^18.0.1",
-    "@libsql/client": "^0.14.0",
+    "@libsql/client": "^0.15.2",
     "@mantine/core": "^7.17.1",
     "@mantine/hooks": "^7.17.1",
     "@sinclair/typebox": "^0.34.30",
@@ -58,7 +71,8 @@
     "object-path-immutable": "^4.1.2",
     "picocolors": "^1.1.1",
     "radix-ui": "^1.1.3",
-    "swr": "^2.3.3"
+    "swr": "^2.3.3",
+    "wrangler": "^4.4.1"
   },
   "devDependencies": {
     "@aws-sdk/client-s3": "^3.758.0",
@@ -70,18 +84,23 @@
     "@libsql/kysely-libsql": "^0.4.1",
     "@mantine/modals": "^7.17.1",
     "@mantine/notifications": "^7.17.1",
+    "@playwright/test": "^1.51.1",
     "@rjsf/core": "5.22.2",
     "@tabler/icons-react": "3.18.0",
     "@tailwindcss/postcss": "^4.0.12",
     "@tailwindcss/vite": "^4.0.12",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.2.0",
     "@types/node": "^22.13.10",
     "@types/react": "^19.0.10",
     "@types/react-dom": "^19.0.4",
     "@vitejs/plugin-react": "^4.3.4",
+    "@vitest/coverage-v8": "^3.0.9",
     "autoprefixer": "^10.4.21",
     "clsx": "^2.1.1",
     "dotenv": "^16.4.7",
     "jotai": "^2.12.2",
+    "jsdom": "^26.0.0",
     "kysely-d1": "^0.3.0",
     "open": "^10.1.0",
     "openapi-types": "^12.1.3",
@@ -100,8 +119,10 @@
     "tailwindcss-animate": "^1.0.7",
     "tsc-alias": "^1.8.11",
     "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
     "vite": "^6.2.1",
     "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.0.9",
     "wouter": "^3.6.0"
   },
   "optionalDependencies": {
@@ -118,47 +139,52 @@
     ".": {
       "types": "./dist/types/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "require": "./dist/index.js"
     },
     "./ui": {
       "types": "./dist/types/ui/index.d.ts",
       "import": "./dist/ui/index.js",
-      "require": "./dist/ui/index.cjs"
+      "require": "./dist/ui/index.js"
     },
     "./elements": {
       "types": "./dist/types/ui/elements/index.d.ts",
       "import": "./dist/ui/elements/index.js",
-      "require": "./dist/ui/elements/index.cjs"
+      "require": "./dist/ui/elements/index.js"
     },
     "./client": {
       "types": "./dist/types/ui/client/index.d.ts",
       "import": "./dist/ui/client/index.js",
-      "require": "./dist/ui/client/index.cjs"
+      "require": "./dist/ui/client/index.js"
     },
     "./data": {
       "types": "./dist/types/data/index.d.ts",
       "import": "./dist/data/index.js",
-      "require": "./dist/data/index.cjs"
+      "require": "./dist/data/index.js"
     },
     "./core": {
       "types": "./dist/types/core/index.d.ts",
       "import": "./dist/core/index.js",
-      "require": "./dist/core/index.cjs"
+      "require": "./dist/core/index.js"
     },
     "./utils": {
       "types": "./dist/types/core/utils/index.d.ts",
       "import": "./dist/core/utils/index.js",
-      "require": "./dist/core/utils/index.cjs"
+      "require": "./dist/core/utils/index.js"
     },
     "./cli": {
       "types": "./dist/types/cli/index.d.ts",
       "import": "./dist/cli/index.js",
-      "require": "./dist/cli/index.cjs"
+      "require": "./dist/cli/index.js"
+    },
+    "./media": {
+      "types": "./dist/types/media/index.d.ts",
+      "import": "./dist/media/index.js",
+      "require": "./dist/media/index.js"
     },
     "./adapter/cloudflare": {
       "types": "./dist/types/adapter/cloudflare/index.d.ts",
       "import": "./dist/adapter/cloudflare/index.js",
-      "require": "./dist/adapter/cloudflare/index.cjs"
+      "require": "./dist/adapter/cloudflare/index.js"
     },
     "./adapter": {
       "types": "./dist/types/adapter/index.d.ts",
@@ -167,37 +193,37 @@
     "./adapter/vite": {
       "types": "./dist/types/adapter/vite/index.d.ts",
       "import": "./dist/adapter/vite/index.js",
-      "require": "./dist/adapter/vite/index.cjs"
+      "require": "./dist/adapter/vite/index.js"
     },
     "./adapter/nextjs": {
       "types": "./dist/types/adapter/nextjs/index.d.ts",
       "import": "./dist/adapter/nextjs/index.js",
-      "require": "./dist/adapter/nextjs/index.cjs"
+      "require": "./dist/adapter/nextjs/index.js"
     },
     "./adapter/react-router": {
       "types": "./dist/types/adapter/react-router/index.d.ts",
       "import": "./dist/adapter/react-router/index.js",
-      "require": "./dist/adapter/react-router/index.cjs"
+      "require": "./dist/adapter/react-router/index.js"
     },
     "./adapter/bun": {
       "types": "./dist/types/adapter/bun/index.d.ts",
       "import": "./dist/adapter/bun/index.js",
-      "require": "./dist/adapter/bun/index.cjs"
+      "require": "./dist/adapter/bun/index.js"
     },
     "./adapter/node": {
       "types": "./dist/types/adapter/node/index.d.ts",
       "import": "./dist/adapter/node/index.js",
-      "require": "./dist/adapter/node/index.cjs"
+      "require": "./dist/adapter/node/index.js"
     },
     "./adapter/astro": {
       "types": "./dist/types/adapter/astro/index.d.ts",
       "import": "./dist/adapter/astro/index.js",
-      "require": "./dist/adapter/astro/index.cjs"
+      "require": "./dist/adapter/astro/index.js"
     },
     "./adapter/aws": {
       "types": "./dist/types/adapter/aws/index.d.ts",
       "import": "./dist/adapter/aws/index.js",
-      "require": "./dist/adapter/aws/index.cjs"
+      "require": "./dist/adapter/aws/index.js"
     },
     "./dist/main.css": "./dist/ui/main.css",
     "./dist/styles.css": "./dist/ui/styles.css",

app/playwright.config.ts

@@ -0,0 +1,41 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const baseUrl = process.env.TEST_URL || "http://localhost:28623";
+const startCommand = process.env.TEST_START_COMMAND || "bun run dev";
+const autoStart = ["1", "true", undefined].includes(process.env.TEST_AUTO_START);
+
+export default defineConfig({
+   testMatch: "**/*.e2e-spec.ts",
+   testDir: "./e2e",
+   fullyParallel: true,
+   forbidOnly: !!process.env.CI,
+   retries: process.env.CI ? 2 : 0,
+   workers: process.env.CI ? 1 : undefined,
+   reporter: "html",
+   use: {
+      baseURL: baseUrl,
+      trace: "on-first-retry",
+      video: "on-first-retry",
+   },
+   projects: [
+      {
+         name: "chromium",
+         use: { ...devices["Desktop Chrome"] },
+      },
+      /* {
+         name: "firefox",
+         use: { ...devices["Desktop Firefox"] },
+      },
+      {
+         name: "webkit",
+         use: { ...devices["Desktop Safari"] },
+      }, */
+   ],
+   webServer: autoStart
+      ? {
+           command: startCommand,
+           url: baseUrl,
+           reuseExistingServer: !process.env.CI,
+        }
+      : undefined,
+});

app/src/Api.ts

@@ -78,6 +78,10 @@ export class Api {
       this.buildApis();
    }
 
+   get fetcher() {
+      return this.options.fetcher ?? fetch;
+   }
+
    get baseUrl() {
       return this.options.host ?? "http://localhost";
    }

app/src/App.ts

@@ -4,9 +4,10 @@ import { Event } from "core/events";
 import { Connection, type LibSqlCredentials, LibsqlConnection } from "data";
 import type { Hono } from "hono";
 import {
+   ModuleManager,
    type InitialModuleConfigs,
    type ModuleBuildContext,
-   ModuleManager,
+   type ModuleConfigs,
    type ModuleManagerOptions,
    type Modules,
 } from "modules/ModuleManager";
@@ -16,6 +17,7 @@ import { SystemController } from "modules/server/SystemController";
 
 // biome-ignore format: must be there
 import { Api, type ApiOptions } from "Api";
+import type { ServerEnv } from "modules/Controller";
 
 export type AppPlugin = (app: App) => Promise<void> | void;
 
@@ -29,12 +31,25 @@ export class AppBuiltEvent extends AppEvent {
 export class AppFirstBoot extends AppEvent {
    static override slug = "app-first-boot";
 }
-export const AppEvents = { AppConfigUpdatedEvent, AppBuiltEvent, AppFirstBoot } as const;
+export class AppRequest extends AppEvent<{ request: Request }> {
+   static override slug = "app-request";
+}
+export class AppBeforeResponse extends AppEvent<{ request: Request; response: Response }> {
+   static override slug = "app-before-response";
+}
+export const AppEvents = {
+   AppConfigUpdatedEvent,
+   AppBuiltEvent,
+   AppFirstBoot,
+   AppRequest,
+   AppBeforeResponse,
+} as const;
 
 export type AppOptions = {
    plugins?: AppPlugin[];
    seed?: (ctx: ModuleBuildContext & { app: App }) => Promise<void>;
    manager?: Omit<ModuleManagerOptions, "initial" | "onUpdated" | "seed">;
+   asyncEventsMode?: "sync" | "async" | "none";
 };
 export type CreateAppConfig = {
    connection?:
@@ -53,12 +68,14 @@ export type AppConfig = InitialModuleConfigs;
 export type LocalApiOptions = Request | ApiOptions;
 
 export class App {
-   modules: ModuleManager;
    static readonly Events = AppEvents;
+
+   modules: ModuleManager;
    adminController?: AdminController;
+   _id: string = crypto.randomUUID();
+
    private trigger_first_boot = false;
    private plugins: AppPlugin[];
-   private _id: string = crypto.randomUUID();
    private _building: boolean = false;
 
    constructor(
@@ -70,35 +87,9 @@ export class App {
       this.modules = new ModuleManager(connection, {
          ...(options?.manager ?? {}),
          initial: _initialConfig,
-         onUpdated: async (key, config) => {
+         onUpdated: this.onUpdated.bind(this),
-            // if the EventManager was disabled, we assume we shouldn't
+         onFirstBoot: this.onFirstBoot.bind(this),
-            // respond to events, such as "onUpdated".
+         onServerInit: this.onServerInit.bind(this),
-            // this is important if multiple changes are done, and then build() is called manually
-            if (!this.emgr.enabled) {
-               $console.warn("App config updated, but event manager is disabled, skip.");
-               return;
-            }
-
-            $console.log("App config updated", key);
-            // @todo: potentially double syncing
-            await this.build({ sync: true });
-            await this.emgr.emit(new AppConfigUpdatedEvent({ app: this }));
-         },
-         onFirstBoot: async () => {
-            $console.log("App first boot");
-            this.trigger_first_boot = true;
-         },
-         onServerInit: async (server) => {
-            server.use(async (c, next) => {
-               c.set("app", this);
-               await next();
-
-               try {
-                  // gracefully add the app id
-                  c.res.headers.set("X-bknd-id", this._id);
-               } catch (e) {}
-            });
-         },
       });
       this.modules.ctx().emgr.registerEvents(AppEvents);
    }
@@ -189,7 +180,10 @@ export class App {
    registerAdminController(config?: AdminControllerOptions) {
       // register admin
       this.adminController = new AdminController(this, config);
-      this.modules.server.route(config?.basepath ?? "/", this.adminController.getController());
+      this.modules.server.route(
+         this.adminController.basepath,
+         this.adminController.getController(),
+      );
       return this;
    }
 
@@ -213,6 +207,53 @@ export class App {
 
       return new Api({ host: "http://localhost", ...(options ?? {}), fetcher });
    }
+
+   async onUpdated<Module extends keyof Modules>(module: Module, config: ModuleConfigs[Module]) {
+      // if the EventManager was disabled, we assume we shouldn't
+      // respond to events, such as "onUpdated".
+      // this is important if multiple changes are done, and then build() is called manually
+      if (!this.emgr.enabled) {
+         $console.warn("App config updated, but event manager is disabled, skip.");
+         return;
+      }
+
+      $console.log("App config updated", module);
+      // @todo: potentially double syncing
+      await this.build({ sync: true });
+      await this.emgr.emit(new AppConfigUpdatedEvent({ app: this }));
+   }
+
+   async onFirstBoot() {
+      $console.log("App first boot");
+      this.trigger_first_boot = true;
+   }
+
+   async onServerInit(server: Hono<ServerEnv>) {
+      server.use(async (c, next) => {
+         c.set("app", this);
+         await this.emgr.emit(new AppRequest({ app: this, request: c.req.raw }));
+         await next();
+
+         try {
+            // gracefully add the app id
+            c.res.headers.set("X-bknd-id", this._id);
+         } catch (e) {}
+
+         await this.emgr.emit(
+            new AppBeforeResponse({ app: this, request: c.req.raw, response: c.res }),
+         );
+
+         // execute collected async events (async by default)
+         switch (this.options?.asyncEventsMode ?? "async") {
+            case "sync":
+               await this.emgr.executeAsyncs();
+               break;
+            case "async":
+               this.emgr.executeAsyncs();
+               break;
+         }
+      });
+   }
 }
 
 export function createApp(config: CreateAppConfig = {}) {

app/src/adapter/adapter-test-suite.ts

@@ -0,0 +1,90 @@
+import type { TestRunner } from "core/test";
+import type { BkndConfig, DefaultArgs, FrameworkOptions, RuntimeOptions } from "./index";
+import type { App } from "App";
+
+export function adapterTestSuite<
+   Config extends BkndConfig = BkndConfig,
+   Args extends DefaultArgs = DefaultArgs,
+>(
+   testRunner: TestRunner,
+   {
+      makeApp,
+      makeHandler,
+      label = "app",
+      overrides = {},
+   }: {
+      makeApp: (
+         config: Config,
+         args?: Args,
+         opts?: RuntimeOptions | FrameworkOptions,
+      ) => Promise<App>;
+      makeHandler?: (
+         config?: Config,
+         args?: Args,
+         opts?: RuntimeOptions | FrameworkOptions,
+      ) => (request: Request) => Promise<Response>;
+      label?: string;
+      overrides?: {
+         dbUrl?: string;
+      };
+   },
+) {
+   const { test, expect, mock } = testRunner;
+   const id = crypto.randomUUID();
+
+   test(`creates ${label}`, async () => {
+      const beforeBuild = mock(async () => null) as any;
+      const onBuilt = mock(async () => null) as any;
+
+      const config = {
+         app: (env) => ({
+            connection: { url: env.url },
+            initialConfig: {
+               server: { cors: { origin: env.origin } },
+            },
+         }),
+         beforeBuild,
+         onBuilt,
+      } as const satisfies BkndConfig;
+
+      const app = await makeApp(
+         config as any,
+         {
+            url: overrides.dbUrl ?? ":memory:",
+            origin: "localhost",
+         } as any,
+         { id },
+      );
+      expect(app).toBeDefined();
+      expect(app.toJSON().server.cors.origin).toEqual("localhost");
+      expect(beforeBuild).toHaveBeenCalledTimes(1);
+      expect(onBuilt).toHaveBeenCalledTimes(1);
+   });
+
+   if (makeHandler) {
+      const getConfig = async (fetcher: (r: Request) => Promise<Response>) => {
+         const res = await fetcher(new Request("http://localhost:3000/api/system/config"));
+         const data = (await res.json()) as any;
+         return { res, data };
+      };
+
+      test("responds with the same app id", async () => {
+         const fetcher = makeHandler(undefined, undefined, { id });
+
+         const { res, data } = await getConfig(fetcher);
+         expect(res.ok).toBe(true);
+         expect(res.status).toBe(200);
+         expect(data.server.cors.origin).toEqual("localhost");
+      });
+
+      test("creates fresh & responds to api config", async () => {
+         // set the same id, but force recreate
+         const fetcher = makeHandler(undefined, undefined, { id, force: true });
+
+         const { res, data } = await getConfig(fetcher);
+         expect(res.ok).toBe(true);
+         expect(res.status).toBe(200);
+         expect(data.server.cors.origin).toEqual("*");
+      });
+   }
+}

app/src/adapter/astro/astro.adapter.spec.ts

@@ -0,0 +1,15 @@
+import { afterAll, beforeAll, describe } from "bun:test";
+import * as astro from "./astro.adapter";
+import { disableConsoleLog, enableConsoleLog } from "core/utils";
+import { adapterTestSuite } from "adapter/adapter-test-suite";
+import { bunTestRunner } from "adapter/bun/test";
+
+beforeAll(disableConsoleLog);
+afterAll(enableConsoleLog);
+
+describe("astro adapter", () => {
+   adapterTestSuite(bunTestRunner, {
+      makeApp: astro.getApp,
+      makeHandler: (c, a, o) => (request: Request) => astro.serve(c, a, o)({ request }),
+   });
+});

app/src/adapter/astro/astro.adapter.ts

@@ -1,34 +1,25 @@
-import type { App } from "bknd";
+import { type FrameworkBkndConfig, createFrameworkApp, type FrameworkOptions } from "bknd/adapter";
-import { type FrameworkBkndConfig, createFrameworkApp } from "bknd/adapter";
-import { Api, type ApiOptions } from "bknd/client";
-
-export type AstroBkndConfig<Args = TAstro> = FrameworkBkndConfig<Args>;
 
+type AstroEnv = NodeJS.ProcessEnv;
 type TAstro = {
    request: Request;
 };
+export type AstroBkndConfig<Env = AstroEnv> = FrameworkBkndConfig<Env>;
 
-export type Options = {
+export async function getApp<Env = AstroEnv>(
-   mode?: "static" | "dynamic";
+   config: AstroBkndConfig<Env> = {},
-} & Omit<ApiOptions, "host"> & {
+   args: Env = {} as Env,
-      host?: string;
+   opts: FrameworkOptions = {},
-   };
+) {
-
+   return await createFrameworkApp(config, args ?? import.meta.env, opts);
-export async function getApi(Astro: TAstro, options: Options = { mode: "static" }) {
-   const api = new Api({
-      host: new URL(Astro.request.url).origin,
-      headers: options.mode === "dynamic" ? Astro.request.headers : undefined,
-   });
-   await api.verifyAuth();
-   return api;
 }
 
-let app: App;
+export function serve<Env = AstroEnv>(
-export function serve<Context extends TAstro = TAstro>(config: AstroBkndConfig<Context> = {}) {
+   config: AstroBkndConfig<Env> = {},
-   return async (args: Context) => {
+   args: Env = {} as Env,
-      if (!app) {
+   opts?: FrameworkOptions,
-         app = await createFrameworkApp(config, args);
+) {
-      }
+   return async (fnArgs: TAstro) => {
-      return app.fetch(args.request);
+      return (await getApp(config, args, opts)).fetch(fnArgs.request);
    };
 }

app/src/adapter/aws/aws-lambda.adapter.ts

@@ -1,68 +1,76 @@
 import type { App } from "bknd";
 import { handle } from "hono/aws-lambda";
-import { type RuntimeBkndConfig, createRuntimeApp } from "bknd/adapter";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { type RuntimeBkndConfig, createRuntimeApp, type RuntimeOptions } from "bknd/adapter";
 
-export type AwsLambdaBkndConfig = RuntimeBkndConfig & {
+type AwsLambdaEnv = object;
-   assets?:
+export type AwsLambdaBkndConfig<Env extends AwsLambdaEnv = AwsLambdaEnv> =
-      | {
+   RuntimeBkndConfig<Env> & {
-           mode: "local";
+      assets?:
-           root: string;
+         | {
-        }
+              mode: "local";
-      | {
+              root: string;
-           mode: "url";
+           }
-           url: string;
+         | {
-        };
+              mode: "url";
-};
+              url: string;
+           };
+   };
 
-let app: App;
+export async function createApp<Env extends AwsLambdaEnv = AwsLambdaEnv>(
-export async function createApp({
+   { adminOptions = false, assets, ...config }: AwsLambdaBkndConfig<Env> = {},
-   adminOptions = false,
+   args: Env = {} as Env,
-   assets,
+   opts?: RuntimeOptions,
-   ...config
+): Promise<App> {
-}: AwsLambdaBkndConfig = {}) {
+   let additional: Partial<RuntimeBkndConfig> = {
-   if (!app) {
+      adminOptions,
-      let additional: Partial<RuntimeBkndConfig> = {
+   };
-         adminOptions,
-      };
 
-      if (assets?.mode) {
+   if (assets?.mode) {
-         switch (assets.mode) {
+      switch (assets.mode) {
-            case "local":
+         case "local":
-               // @todo: serve static outside app context
+            // @todo: serve static outside app context
-               additional = {
+            additional = {
-                  adminOptions: adminOptions === false ? undefined : adminOptions,
+               adminOptions: adminOptions === false ? undefined : adminOptions,
-                  serveStatic: (await import("@hono/node-server/serve-static")).serveStatic({
+               serveStatic: serveStatic({
-                     root: assets.root,
+                  root: assets.root,
-                     onFound: (path, c) => {
+                  onFound: (path, c) => {
-                        c.res.headers.set("Cache-Control", "public, max-age=31536000");
+                     c.res.headers.set("Cache-Control", "public, max-age=31536000");
-                     },
+                  },
-                  }),
+               }),
-               };
+            };
-               break;
+            break;
-            case "url":
+         case "url":
-               additional.adminOptions = {
+            additional.adminOptions = {
-                  ...(typeof adminOptions === "object" ? adminOptions : {}),
+               ...(typeof adminOptions === "object" ? adminOptions : {}),
-                  assets_path: assets.url,
+               assetsPath: assets.url,
-               };
+            };
-               break;
+            break;
-            default:
+         default:
-               throw new Error("Invalid assets mode");
+            throw new Error("Invalid assets mode");
-         }
       }
-
-      app = await createRuntimeApp({
-         ...config,
-         ...additional,
-      });
    }
 
-   return app;
+   return await createRuntimeApp(
+      {
+         ...config,
+         ...additional,
+      },
+      args ?? process.env,
+      opts,
+   );
 }
 
-export function serveLambda(config: AwsLambdaBkndConfig = {}) {
+export function serve<Env extends AwsLambdaEnv = AwsLambdaEnv>(
-   console.log("serving lambda");
+   config: AwsLambdaBkndConfig<Env> = {},
+   args: Env = {} as Env,
+   opts?: RuntimeOptions,
+) {
    return async (event) => {
-      const app = await createApp(config);
+      const app = await createApp(config, args, opts);
       return await handle(app.server)(event);
    };
 }
+
+// compatibility with old code
+export const serveLambda = serve;

app/src/adapter/aws/aws.adapter.spec.ts

@@ -0,0 +1,19 @@
+import { afterAll, beforeAll, describe } from "bun:test";
+import * as awsLambda from "./aws-lambda.adapter";
+import { disableConsoleLog, enableConsoleLog } from "core/utils";
+import { adapterTestSuite } from "adapter/adapter-test-suite";
+import { bunTestRunner } from "adapter/bun/test";
+
+beforeAll(disableConsoleLog);
+afterAll(enableConsoleLog);
+
+describe("aws adapter", () => {
+   adapterTestSuite(bunTestRunner, {
+      makeApp: awsLambda.createApp,
+      // @todo: add a request to lambda event translator?
+      makeHandler: (c, a, o) => async (request: Request) => {
+         const app = await awsLambda.createApp(c, a, o);
+         return app.fetch(request);
+      },
+   });
+});

app/src/adapter/bun/bun.adapter.spec.ts

@@ -0,0 +1,15 @@
+import { afterAll, beforeAll, describe } from "bun:test";
+import * as bun from "./bun.adapter";
+import { disableConsoleLog, enableConsoleLog } from "core/utils";
+import { adapterTestSuite } from "adapter/adapter-test-suite";
+import { bunTestRunner } from "adapter/bun/test";
+
+beforeAll(disableConsoleLog);
+afterAll(enableConsoleLog);
+
+describe("bun adapter", () => {
+   adapterTestSuite(bunTestRunner, {
+      makeApp: bun.createApp,
+      makeHandler: bun.createHandler,
+   });
+});

app/src/adapter/bun/bun.adapter.ts

@@ -1,47 +1,64 @@
 /// <reference types="bun-types" />
 
 import path from "node:path";
-import type { App } from "bknd";
+import { type RuntimeBkndConfig, createRuntimeApp, type RuntimeOptions } from "bknd/adapter";
-import { type RuntimeBkndConfig, createRuntimeApp } from "bknd/adapter";
 import { registerLocalMediaAdapter } from "bknd/adapter/node";
 import { config } from "bknd/core";
 import type { ServeOptions } from "bun";
 import { serveStatic } from "hono/bun";
 
-let app: App;
+type BunEnv = Bun.Env;
+export type BunBkndConfig<Env = BunEnv> = RuntimeBkndConfig<Env> & Omit<ServeOptions, "fetch">;
 
-export type BunBkndConfig = RuntimeBkndConfig & Omit<ServeOptions, "fetch">;
+export async function createApp<Env = BunEnv>(
-
+   { distPath, ...config }: BunBkndConfig<Env> = {},
-export async function createApp({ distPath, ...config }: RuntimeBkndConfig = {}) {
+   args: Env = {} as Env,
+   opts?: RuntimeOptions,
+) {
    const root = path.resolve(distPath ?? "./node_modules/bknd/dist", "static");
+   registerLocalMediaAdapter();
 
-   if (!app) {
+   return await createRuntimeApp(
-      registerLocalMediaAdapter();
+      {
-      app = await createRuntimeApp({
          ...config,
          serveStatic: serveStatic({ root }),
-      });
+      },
-   }
+      args ?? (process.env as Env),
-
+      opts,
-   return app;
+   );
 }
 
-export function serve({
+export function createHandler<Env = BunEnv>(
-   distPath,
+   config: BunBkndConfig<Env> = {},
-   connection,
+   args: Env = {} as Env,
-   initialConfig,
+   opts?: RuntimeOptions,
-   options,
+) {
-   port = config.server.default_port,
+   return async (req: Request) => {
-   onBuilt,
+      const app = await createApp(config, args ?? (process.env as Env), opts);
-   buildConfig,
+      return app.fetch(req);
-   adminOptions,
+   };
-   ...serveOptions
+}
-}: BunBkndConfig = {}) {
+
+export function serve<Env = BunEnv>(
+   {
+      distPath,
+      connection,
+      initialConfig,
+      options,
+      port = config.server.default_port,
+      onBuilt,
+      buildConfig,
+      adminOptions,
+      ...serveOptions
+   }: BunBkndConfig<Env> = {},
+   args: Env = {} as Env,
+   opts?: RuntimeOptions,
+) {
    Bun.serve({
       ...serveOptions,
       port,
-      fetch: async (request: Request) => {
+      fetch: createHandler(
-         const app = await createApp({
+         {
             connection,
             initialConfig,
             options,
@@ -49,9 +66,10 @@ export function serve({
             buildConfig,
             adminOptions,
             distPath,
-         });
+         },
-         return app.fetch(request);
+         args,
-      },
+         opts,
+      ),
    });
 
    console.log(`Server is running on http://localhost:${port}`);

app/src/adapter/bun/test.ts

@@ -0,0 +1,7 @@
+import { expect, test, mock } from "bun:test";
+
+export const bunTestRunner = {
+   expect,
+   test,
+   mock,
+};

app/src/adapter/cloudflare/cloudflare-workers.adapter.spec.ts

@@ -0,0 +1,60 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { makeApp } from "./modes/fresh";
+import { makeConfig } from "./config";
+import { disableConsoleLog, enableConsoleLog } from "core/utils";
+import { adapterTestSuite } from "adapter/adapter-test-suite";
+import { bunTestRunner } from "adapter/bun/test";
+import type { CloudflareBkndConfig } from "./cloudflare-workers.adapter";
+
+beforeAll(disableConsoleLog);
+afterAll(enableConsoleLog);
+
+describe("cf adapter", () => {
+   const DB_URL = ":memory:";
+   const $ctx = (env?: any, request?: Request, ctx?: ExecutionContext) => ({
+      request: request ?? (null as any),
+      env: env ?? { DB_URL },
+      ctx: ctx ?? (null as any),
+   });
+
+   it("makes config", async () => {
+      expect(
+         makeConfig(
+            {
+               connection: { url: DB_URL },
+            },
+            {},
+         ),
+      ).toEqual({ connection: { url: DB_URL } });
+
+      expect(
+         makeConfig(
+            {
+               app: (env) => ({
+                  connection: { url: env.DB_URL },
+               }),
+            },
+            {
+               DB_URL,
+            },
+         ),
+      ).toEqual({ connection: { url: DB_URL } });
+   });
+
+   adapterTestSuite<CloudflareBkndConfig, object>(bunTestRunner, {
+      makeApp,
+      makeHandler: (c, a, o) => {
+         return async (request: any) => {
+            const app = await makeApp(
+               // needs a fallback, otherwise tries to launch D1
+               c ?? {
+                  connection: { url: DB_URL },
+               },
+               a,
+               o,
+            );
+            return app.fetch(request);
+         };
+      },
+   });
+});

app/src/adapter/cloudflare/cloudflare-workers.adapter.ts

@@ -1,18 +1,17 @@
 /// <reference types="@cloudflare/workers-types" />
 
-import { type FrameworkBkndConfig, makeConfig } from "bknd/adapter";
+import type { RuntimeBkndConfig } from "bknd/adapter";
 import { Hono } from "hono";
 import { serveStatic } from "hono/cloudflare-workers";
-import { D1Connection } from "./D1Connection";
+import { getFresh } from "./modes/fresh";
-import { registerMedia } from "./StorageR2Adapter";
-import { getBinding } from "./bindings";
 import { getCached } from "./modes/cached";
 import { getDurable } from "./modes/durable";
-import { getFresh, getWarm } from "./modes/fresh";
+import type { App } from "bknd";
 
-export type CloudflareBkndConfig<Env = any> = FrameworkBkndConfig<Context<Env>> & {
+export type CloudflareEnv = object;
+export type CloudflareBkndConfig<Env = CloudflareEnv> = RuntimeBkndConfig<Env> & {
    mode?: "warm" | "fresh" | "cache" | "durable";
-   bindings?: (args: Context<Env>) => {
+   bindings?: (args: Env) => {
       kv?: KVNamespace;
       dobj?: DurableObjectNamespace;
       db?: D1Database;
@@ -22,49 +21,17 @@ export type CloudflareBkndConfig<Env = any> = FrameworkBkndConfig<Context<Env>>
    keepAliveSeconds?: number;
    forceHttps?: boolean;
    manifest?: string;
-   setAdminHtml?: boolean;
-   html?: string;
 };
 
-export type Context<Env = any> = {
+export type Context<Env = CloudflareEnv> = {
    request: Request;
    env: Env;
    ctx: ExecutionContext;
 };
 
-let media_registered: boolean = false;
+export function serve<Env extends CloudflareEnv = CloudflareEnv>(
-export function makeCfConfig(config: CloudflareBkndConfig, context: Context) {
+   config: CloudflareBkndConfig<Env> = {},
-   if (!media_registered) {
+) {
-      registerMedia(context.env as any);
-      media_registered = true;
-   }
-
-   const appConfig = makeConfig(config, context);
-   const bindings = config.bindings?.(context);
-   if (!appConfig.connection) {
-      let db: D1Database | undefined;
-      if (bindings?.db) {
-         console.log("Using database from bindings");
-         db = bindings.db;
-      } else if (Object.keys(context.env ?? {}).length > 0) {
-         const binding = getBinding(context.env, "D1Database");
-         if (binding) {
-            console.log(`Using database from env "${binding.key}"`);
-            db = binding.value;
-         }
-      }
-
-      if (db) {
-         appConfig.connection = new D1Connection({ binding: db });
-      } else {
-         throw new Error("No database connection given");
-      }
-   }
-
-   return appConfig;
-}
-
-export function serve<Env = any>(config: CloudflareBkndConfig<Env> = {}) {
    return {
       async fetch(request: Request, env: Env, ctx: ExecutionContext) {
          const url = new URL(request.url);
@@ -75,7 +42,7 @@ export function serve<Env = any>(config: CloudflareBkndConfig<Env> = {}) {
             throw new Error("manifest is required with static 'kv'");
          }
 
-         if (config.manifest && config.static !== "assets") {
+         if (config.manifest && config.static === "kv") {
             const pathname = url.pathname.slice(1);
             const assetManifest = JSON.parse(config.manifest);
             if (pathname && pathname in assetManifest) {
@@ -99,21 +66,27 @@ export function serve<Env = any>(config: CloudflareBkndConfig<Env> = {}) {
             }
          }
 
-         const context = { request, env, ctx } as Context;
+         const context = { request, env, ctx } as Context<Env>;
          const mode = config.mode ?? "warm";
 
+         let app: App;
          switch (mode) {
             case "fresh":
-               return await getFresh(config, context);
+               app = await getFresh(config, context, { force: true });
+               break;
             case "warm":
-               return await getWarm(config, context);
+               app = await getFresh(config, context);
+               break;
             case "cache":
-               return await getCached(config, context);
+               app = await getCached(config, context);
+               break;
             case "durable":
                return await getDurable(config, context);
             default:
                throw new Error(`Unknown mode ${mode}`);
          }
+
+         return app.fetch(request, env, ctx);
       },
    };
 }

app/src/adapter/cloudflare/config.ts

@@ -0,0 +1,64 @@
+import { registerMedia } from "./storage/StorageR2Adapter";
+import { getBinding } from "./bindings";
+import { D1Connection } from "./D1Connection";
+import type { CloudflareBkndConfig, CloudflareEnv } from ".";
+import { App } from "bknd";
+import { makeConfig as makeAdapterConfig } from "bknd/adapter";
+import type { ExecutionContext } from "hono";
+
+export const constants = {
+   exec_async_event_id: "cf_register_waituntil",
+   cache_endpoint: "/__bknd/cache",
+   do_endpoint: "/__bknd/do",
+};
+
+let media_registered: boolean = false;
+export function makeConfig<Env extends CloudflareEnv = CloudflareEnv>(
+   config: CloudflareBkndConfig<Env>,
+   args: Env = {} as Env,
+) {
+   if (!media_registered) {
+      registerMedia(args as any);
+      media_registered = true;
+   }
+
+   const appConfig = makeAdapterConfig(config, args);
+   const bindings = config.bindings?.(args);
+   if (!appConfig.connection) {
+      let db: D1Database | undefined;
+      if (bindings?.db) {
+         console.log("Using database from bindings");
+         db = bindings.db;
+      } else if (Object.keys(args).length > 0) {
+         const binding = getBinding(args, "D1Database");
+         if (binding) {
+            console.log(`Using database from env "${binding.key}"`);
+            db = binding.value;
+         }
+      }
+
+      if (db) {
+         appConfig.connection = new D1Connection({ binding: db });
+      } else {
+         throw new Error("No database connection given");
+      }
+   }
+
+   return appConfig;
+}
+
+export function registerAsyncsExecutionContext(
+   app: App,
+   ctx: { waitUntil: ExecutionContext["waitUntil"] },
+) {
+   app.emgr.onEvent(
+      App.Events.AppBeforeResponse,
+      async (event) => {
+         ctx.waitUntil(event.params.app.emgr.executeAsyncs());
+      },
+      {
+         mode: "sync",
+         id: constants.exec_async_event_id,
+      },
+   );
+}

app/src/adapter/cloudflare/index.ts

@@ -1,7 +1,7 @@
 import { D1Connection, type D1ConnectionConfig } from "./D1Connection";
 
 export * from "./cloudflare-workers.adapter";
-export { makeApp, getFresh, getWarm } from "./modes/fresh";
+export { makeApp, getFresh } from "./modes/fresh";
 export { getCached } from "./modes/cached";
 export { DurableBkndApp, getDurable } from "./modes/durable";
 export { D1Connection, type D1ConnectionConfig };

app/src/adapter/cloudflare/modes/cached.ts

@@ -1,8 +1,12 @@
 import { App } from "bknd";
 import { createRuntimeApp } from "bknd/adapter";
-import { type CloudflareBkndConfig, type Context, makeCfConfig } from "../index";
+import type { CloudflareBkndConfig, Context, CloudflareEnv } from "../index";
+import { makeConfig, registerAsyncsExecutionContext, constants } from "../config";
 
-export async function getCached(config: CloudflareBkndConfig, { env, ctx, ...args }: Context) {
+export async function getCached<Env extends CloudflareEnv = CloudflareEnv>(
+   config: CloudflareBkndConfig<Env>,
+   { env, ctx, ...args }: Context<Env>,
+) {
    const { kv } = config.bindings?.(env)!;
    if (!kv) throw new Error("kv namespace is not defined in cloudflare.bindings");
    const key = config.key ?? "app";
@@ -16,10 +20,11 @@ export async function getCached(config: CloudflareBkndConfig, { env, ctx, ...arg
 
    const app = await createRuntimeApp(
       {
-         ...makeCfConfig(config, { env, ctx, ...args }),
+         ...makeConfig(config, env),
          initialConfig,
          onBuilt: async (app) => {
-            app.module.server.client.get("/__bknd/cache", async (c) => {
+            registerAsyncsExecutionContext(app, ctx);
+            app.module.server.client.get(constants.cache_endpoint, async (c) => {
                await kv.delete(key);
                return c.json({ message: "Cache cleared" });
             });
@@ -35,7 +40,6 @@ export async function getCached(config: CloudflareBkndConfig, { env, ctx, ...arg
             );
             await config.beforeBuild?.(app);
          },
-         adminOptions: { html: config.html },
       },
       { env, ctx, ...args },
    );

app/src/adapter/cloudflare/modes/durable.ts

@@ -1,9 +1,13 @@
 import { DurableObject } from "cloudflare:workers";
 import type { App, CreateAppConfig } from "bknd";
 import { createRuntimeApp, makeConfig } from "bknd/adapter";
-import type { CloudflareBkndConfig, Context } from "../index";
+import type { CloudflareBkndConfig, Context, CloudflareEnv } from "../index";
+import { constants, registerAsyncsExecutionContext } from "../config";
 
-export async function getDurable(config: CloudflareBkndConfig, ctx: Context) {
+export async function getDurable<Env extends CloudflareEnv = CloudflareEnv>(
+   config: CloudflareBkndConfig<Env>,
+   ctx: Context<Env>,
+) {
    const { dobj } = config.bindings?.(ctx.env)!;
    if (!dobj) throw new Error("durable object is not defined in cloudflare.bindings");
    const key = config.key ?? "app";
@@ -17,13 +21,11 @@ export async function getDurable(config: CloudflareBkndConfig, ctx: Context) {
    const id = dobj.idFromName(key);
    const stub = dobj.get(id) as unknown as DurableBkndApp;
 
-   const create_config = makeConfig(config, ctx);
+   const create_config = makeConfig(config, ctx.env);
 
    const res = await stub.fire(ctx.request, {
       config: create_config,
-      html: config.html,
       keepAliveSeconds: config.keepAliveSeconds,
-      setAdminHtml: config.setAdminHtml,
    });
 
    const headers = new Headers(res.headers);
@@ -67,7 +69,8 @@ export class DurableBkndApp extends DurableObject {
          this.app = await createRuntimeApp({
             ...config,
             onBuilt: async (app) => {
-               app.modules.server.get("/__do", async (c) => {
+               registerAsyncsExecutionContext(app, this.ctx);
+               app.modules.server.get(constants.do_endpoint, async (c) => {
                   // @ts-ignore
                   const context: any = c.req.raw.cf ? c.req.raw.cf : c.env.cf;
                   return c.json({
@@ -92,7 +95,6 @@ export class DurableBkndApp extends DurableObject {
          this.keepAlive(options.keepAliveSeconds);
       }
 
-      console.log("id", this.id);
       const res = await this.app!.fetch(request);
       const headers = new Headers(res.headers);
       headers.set("X-BuildTime", buildtime.toString());
@@ -106,19 +108,17 @@ export class DurableBkndApp extends DurableObject {
    }
 
    async onBuilt(app: App) {}
+
    async beforeBuild(app: App) {}
 
    protected keepAlive(seconds: number) {
-      console.log("keep alive for", seconds);
       if (this.interval) {
-         console.log("clearing, there is a new");
          clearInterval(this.interval);
       }
 
       let i = 0;
       this.interval = setInterval(() => {
          i += 1;
-         //console.log("keep-alive", i);
          if (i === seconds) {
             console.log("cleared");
             clearInterval(this.interval);

app/src/adapter/cloudflare/modes/fresh.ts

@@ -1,27 +1,29 @@
-import type { App } from "bknd";
+import { createRuntimeApp, type RuntimeOptions } from "bknd/adapter";
-import { createRuntimeApp } from "bknd/adapter";
+import type { CloudflareBkndConfig, Context, CloudflareEnv } from "../index";
-import { type CloudflareBkndConfig, type Context, makeCfConfig } from "../index";
+import { makeConfig, registerAsyncsExecutionContext } from "../config";
 
-export async function makeApp(config: CloudflareBkndConfig, ctx: Context) {
+export async function makeApp<Env extends CloudflareEnv = CloudflareEnv>(
-   return await createRuntimeApp(
+   config: CloudflareBkndConfig<Env>,
+   args: Env = {} as Env,
+   opts?: RuntimeOptions,
+) {
+   return await createRuntimeApp<Env>(makeConfig(config, args), args, opts);
+}
+
+export async function getFresh<Env extends CloudflareEnv = CloudflareEnv>(
+   config: CloudflareBkndConfig<Env>,
+   ctx: Context<Env>,
+   opts: RuntimeOptions = {},
+) {
+   return await makeApp(
       {
-         ...makeCfConfig(config, ctx),
+         ...config,
-         adminOptions: config.html ? { html: config.html } : undefined,
+         onBuilt: async (app) => {
+            registerAsyncsExecutionContext(app, ctx.ctx);
+            config.onBuilt?.(app);
+         },
       },
-      ctx,
+      ctx.env,
+      opts,
    );
 }
-
-export async function getFresh(config: CloudflareBkndConfig, ctx: Context) {
-   const app = await makeApp(config, ctx);
-   return app.fetch(ctx.request);
-}
-
-let warm_app: App;
-export async function getWarm(config: CloudflareBkndConfig, ctx: Context) {
-   if (!warm_app) {
-      warm_app = await makeApp(config, ctx);
-   }
-
-   return warm_app.fetch(ctx.request);
-}

app/src/adapter/cloudflare/storage/StorageR2Adapter.native-spec.ts

@@ -0,0 +1,32 @@
+import { createWriteStream, readFileSync } from "node:fs";
+import { test } from "node:test";
+import { Miniflare } from "miniflare";
+import { StorageR2Adapter } from "./StorageR2Adapter";
+import { adapterTestSuite } from "media";
+import { nodeTestRunner } from "adapter/node";
+import path from "node:path";
+
+// https://github.com/nodejs/node/issues/44372#issuecomment-1736530480
+console.log = async (message: any) => {
+   const tty = createWriteStream("/dev/tty");
+   const msg = typeof message === "string" ? message : JSON.stringify(message, null, 2);
+   return tty.write(`${msg}\n`);
+};
+
+test("StorageR2Adapter", async () => {
+   const mf = new Miniflare({
+      modules: true,
+      script: "export default { async fetch() { return new Response(null); } }",
+      r2Buckets: ["BUCKET"],
+   });
+
+   const bucket = (await mf.getR2Bucket("BUCKET")) as unknown as R2Bucket;
+   const adapter = new StorageR2Adapter(bucket);
+
+   const basePath = path.resolve(import.meta.dirname, "../../../../__test__/_assets");
+   const buffer = readFileSync(path.join(basePath, "image.png"));
+   const file = new File([buffer], "image.png", { type: "image/png" });
+
+   await adapterTestSuite(nodeTestRunner, adapter, file);
+   await mf.dispose();
+});

app/src/adapter/cloudflare/storage/StorageR2Adapter.ts

@@ -1,9 +1,8 @@
 import { registries } from "bknd";
 import { isDebug } from "bknd/core";
 import { StringEnum, Type } from "bknd/utils";
-import type { FileBody, StorageAdapter } from "media/storage/Storage";
+import { guessMimeType as guess, StorageAdapter, type FileBody } from "bknd/media";
-import { guess } from "media/storage/mime-types-tiny";
+import { getBindings } from "../bindings";
-import { getBindings } from "./bindings";
 
 export function makeSchema(bindings: string[] = []) {
    return Type.Object(
@@ -47,8 +46,10 @@ export function registerMedia(env: Record<string, any>) {
  * Adapter for R2 storage
  * @todo: add tests (bun tests won't work, need node native tests)
  */
-export class StorageR2Adapter implements StorageAdapter {
+export class StorageR2Adapter extends StorageAdapter {
-   constructor(private readonly bucket: R2Bucket) {}
+   constructor(private readonly bucket: R2Bucket) {
+      super();
+   }
 
    getName(): string {
       return "r2";

app/src/adapter/index.ts

@@ -12,76 +12,113 @@ export type BkndConfig<Args = any> = CreateAppConfig & {
 
 export type FrameworkBkndConfig<Args = any> = BkndConfig<Args>;
 
+export type CreateAdapterAppOptions = {
+   force?: boolean;
+   id?: string;
+};
+export type FrameworkOptions = CreateAdapterAppOptions;
+export type RuntimeOptions = CreateAdapterAppOptions;
+
 export type RuntimeBkndConfig<Args = any> = BkndConfig<Args> & {
    distPath?: string;
    serveStatic?: MiddlewareHandler | [string, MiddlewareHandler];
    adminOptions?: AdminControllerOptions | false;
 };
 
-export function makeConfig<Args = any>(config: BkndConfig<Args>, args?: Args): CreateAppConfig {
+export type DefaultArgs = {
+   [key: string]: any;
+};
+
+export function makeConfig<Args = DefaultArgs>(
+   config: BkndConfig<Args>,
+   args?: Args,
+): CreateAppConfig {
    let additionalConfig: CreateAppConfig = {};
-   if ("app" in config && config.app) {
+   const { app, ...rest } = config;
-      if (typeof config.app === "function") {
+   if (app) {
+      if (typeof app === "function") {
          if (!args) {
             throw new Error("args is required when config.app is a function");
          }
-         additionalConfig = config.app(args);
+         additionalConfig = app(args);
       } else {
-         additionalConfig = config.app;
+         additionalConfig = app;
       }
    }
 
-   return { ...config, ...additionalConfig };
+   return { ...rest, ...additionalConfig };
 }
 
-export async function createFrameworkApp<Args = any>(
+// a map that contains all apps by id
-   config: FrameworkBkndConfig,
+const apps = new Map<string, App>();
+export async function createAdapterApp<Config extends BkndConfig = BkndConfig, Args = DefaultArgs>(
+   config: Config = {} as Config,
    args?: Args,
+   opts?: CreateAdapterAppOptions,
 ): Promise<App> {
-   const app = App.create(makeConfig(config, args));
+   const id = opts?.id ?? "app";
+   let app = apps.get(id);
+   if (!app || opts?.force) {
+      app = App.create(makeConfig(config, args));
+      apps.set(id, app);
+   }
+   return app;
+}
 
-   if (config.onBuilt) {
+export async function createFrameworkApp<Args = DefaultArgs>(
+   config: FrameworkBkndConfig = {},
+   args?: Args,
+   opts?: FrameworkOptions,
+): Promise<App> {
+   const app = await createAdapterApp(config, args, opts);
+
+   if (!app.isBuilt()) {
+      if (config.onBuilt) {
+         app.emgr.onEvent(
+            App.Events.AppBuiltEvent,
+            async () => {
+               await config.onBuilt?.(app);
+            },
+            "sync",
+         );
+      }
+
+      await config.beforeBuild?.(app);
+      await app.build(config.buildConfig);
+   }
+
+   return app;
+}
+
+export async function createRuntimeApp<Args = DefaultArgs>(
+   { serveStatic, adminOptions, ...config }: RuntimeBkndConfig<Args> = {},
+   args?: Args,
+   opts?: RuntimeOptions,
+): Promise<App> {
+   const app = await createAdapterApp(config, args, opts);
+
+   if (!app.isBuilt()) {
       app.emgr.onEvent(
          App.Events.AppBuiltEvent,
          async () => {
+            if (serveStatic) {
+               const [path, handler] = Array.isArray(serveStatic)
+                  ? serveStatic
+                  : [$config.server.assets_path + "*", serveStatic];
+               app.modules.server.get(path, handler);
+            }
+
             await config.onBuilt?.(app);
+            if (adminOptions !== false) {
+               app.registerAdminController(adminOptions);
+            }
          },
          "sync",
       );
+
+      await config.beforeBuild?.(app);
+      await app.build(config.buildConfig);
    }
 
-   await config.beforeBuild?.(app);
-   await app.build(config.buildConfig);
-
-   return app;
-}
-
-export async function createRuntimeApp<Env = any>(
-   { serveStatic, adminOptions, ...config }: RuntimeBkndConfig,
-   env?: Env,
-): Promise<App> {
-   const app = App.create(makeConfig(config, env));
-
-   app.emgr.onEvent(
-      App.Events.AppBuiltEvent,
-      async () => {
-         if (serveStatic) {
-            const [path, handler] = Array.isArray(serveStatic)
-               ? serveStatic
-               : [$config.server.assets_path + "*", serveStatic];
-            app.modules.server.get(path, handler);
-         }
-
-         await config.onBuilt?.(app);
-         if (adminOptions !== false) {
-            app.registerAdminController(adminOptions);
-         }
-      },
-      "sync",
-   );
-
-   await config.beforeBuild?.(app);
-   await app.build(config.buildConfig);
-
    return app;
 }

app/src/adapter/nextjs/nextjs.adapter.spec.ts

@@ -0,0 +1,16 @@
+import { afterAll, beforeAll, describe } from "bun:test";
+import * as nextjs from "./nextjs.adapter";
+import { disableConsoleLog, enableConsoleLog } from "core/utils";
+import { adapterTestSuite } from "adapter/adapter-test-suite";
+import { bunTestRunner } from "adapter/bun/test";
+import type { NextjsBkndConfig } from "./nextjs.adapter";
+
+beforeAll(disableConsoleLog);
+afterAll(enableConsoleLog);
+
+describe("nextjs adapter", () => {
+   adapterTestSuite<NextjsBkndConfig>(bunTestRunner, {
+      makeApp: nextjs.getApp,
+      makeHandler: nextjs.serve,
+   });
+});

app/src/adapter/nextjs/nextjs.adapter.ts

@@ -1,36 +1,19 @@
-import type { App } from "bknd";
+import { createFrameworkApp, type FrameworkBkndConfig, type FrameworkOptions } from "bknd/adapter";
-import { type FrameworkBkndConfig, createFrameworkApp } from "bknd/adapter";
+import { isNode } from "bknd/utils";
-import { isNode } from "core/utils";
+import type { NextApiRequest } from "next";
 
-export type NextjsBkndConfig = FrameworkBkndConfig & {
+type NextjsEnv = NextApiRequest["env"];
+
+export type NextjsBkndConfig<Env = NextjsEnv> = FrameworkBkndConfig<Env> & {
    cleanRequest?: { searchParams?: string[] };
 };
 
-type NextjsContext = {
+export async function getApp<Env = NextjsEnv>(
-   env: Record<string, string | undefined>;
+   config: NextjsBkndConfig<Env>,
-};
+   args: Env = {} as Env,
-
+   opts?: FrameworkOptions,
-let app: App;
-let building: boolean = false;
-
-export async function getApp<Args extends NextjsContext = NextjsContext>(
-   config: NextjsBkndConfig,
-   args?: Args,
 ) {
-   if (building) {
+   return await createFrameworkApp(config, args ?? (process.env as Env), opts);
-      while (building) {
-         await new Promise((resolve) => setTimeout(resolve, 5));
-      }
-      if (app) return app;
-   }
-
-   building = true;
-   if (!app) {
-      app = await createFrameworkApp(config, args);
-      await app.build();
-   }
-   building = false;
-   return app;
 }
 
 function getCleanRequest(req: Request, cleanRequest: NextjsBkndConfig["cleanRequest"]) {
@@ -56,11 +39,13 @@ function getCleanRequest(req: Request, cleanRequest: NextjsBkndConfig["cleanRequ
    });
 }
 
-export function serve({ cleanRequest, ...config }: NextjsBkndConfig = {}) {
+export function serve<Env = NextjsEnv>(
+   { cleanRequest, ...config }: NextjsBkndConfig<Env> = {},
+   args: Env = {} as Env,
+   opts?: FrameworkOptions,
+) {
    return async (req: Request) => {
-      if (!app) {
+      const app = await getApp(config, args, opts);
-         app = await getApp(config, { env: process.env ?? {} });
-      }
       const request = getCleanRequest(req, cleanRequest);
       return app.fetch(request);
    };

app/src/adapter/node/index.ts

@@ -1,12 +1,19 @@
 import { registries } from "bknd";
-import {
+import { type LocalAdapterConfig, StorageLocalAdapter } from "./storage/StorageLocalAdapter";
-   type LocalAdapterConfig,
-   StorageLocalAdapter,
-} from "../../media/storage/adapters/StorageLocalAdapter";
 
 export * from "./node.adapter";
 export { StorageLocalAdapter, type LocalAdapterConfig };
+export { nodeTestRunner } from "./test";
 
+let registered = false;
 export function registerLocalMediaAdapter() {
-   registries.media.register("local", StorageLocalAdapter);
+   if (!registered) {
+      registries.media.register("local", StorageLocalAdapter);
+      registered = true;
+   }
+
+   return (config: Partial<LocalAdapterConfig> = {}) => {
+      const adapter = new StorageLocalAdapter(config);
+      return adapter.toJSON(true);
+   };
 }

app/src/adapter/node/node.adapter.native-spec.ts

@@ -0,0 +1,15 @@
+import { describe, before, after } from "node:test";
+import * as node from "./node.adapter";
+import { adapterTestSuite } from "adapter/adapter-test-suite";
+import { nodeTestRunner } from "adapter/node";
+import { disableConsoleLog, enableConsoleLog } from "core/utils";
+
+before(() => disableConsoleLog());
+after(enableConsoleLog);
+
+describe("node adapter", () => {
+   adapterTestSuite(nodeTestRunner, {
+      makeApp: node.createApp,
+      makeHandler: node.createHandler,
+   });
+});

app/src/adapter/node/node.adapter.spec.ts

@@ -0,0 +1,15 @@
+import { afterAll, beforeAll, describe } from "bun:test";
+import * as node from "./node.adapter";
+import { adapterTestSuite } from "adapter/adapter-test-suite";
+import { bunTestRunner } from "adapter/bun/test";
+import { disableConsoleLog, enableConsoleLog } from "core/utils";
+
+beforeAll(disableConsoleLog);
+afterAll(enableConsoleLog);
+
+describe("node adapter (bun)", () => {
+   adapterTestSuite(bunTestRunner, {
+      makeApp: node.createApp,
+      makeHandler: node.createHandler,
+   });
+});

app/src/adapter/node/node.adapter.ts

@@ -2,11 +2,11 @@ import path from "node:path";
 import { serve as honoServe } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { registerLocalMediaAdapter } from "adapter/node/index";
-import type { App } from "bknd";
+import { type RuntimeBkndConfig, createRuntimeApp, type RuntimeOptions } from "bknd/adapter";
-import { type RuntimeBkndConfig, createRuntimeApp } from "bknd/adapter";
 import { config as $config } from "bknd/core";
 
-export type NodeBkndConfig = RuntimeBkndConfig & {
+type NodeEnv = NodeJS.ProcessEnv;
+export type NodeBkndConfig<Env = NodeEnv> = RuntimeBkndConfig<Env> & {
    port?: number;
    hostname?: string;
    listener?: Parameters<typeof honoServe>[1];
@@ -14,14 +14,11 @@ export type NodeBkndConfig = RuntimeBkndConfig & {
    relativeDistPath?: string;
 };
 
-export function serve({
+export async function createApp<Env = NodeEnv>(
-   distPath,
+   { distPath, relativeDistPath, ...config }: NodeBkndConfig<Env> = {},
-   relativeDistPath,
+   args: Env = {} as Env,
-   port = $config.server.default_port,
+   opts?: RuntimeOptions,
-   hostname,
+) {
-   listener,
-   ...config
-}: NodeBkndConfig = {}) {
    const root = path.relative(
       process.cwd(),
       path.resolve(distPath ?? relativeDistPath ?? "./node_modules/bknd/dist", "static"),
@@ -30,23 +27,39 @@ export function serve({
       console.warn("relativeDistPath is deprecated, please use distPath instead");
    }
 
-   let app: App;
+   registerLocalMediaAdapter();
+   return await createRuntimeApp(
+      {
+         ...config,
+         serveStatic: serveStatic({ root }),
+      },
+      // @ts-ignore
+      args ?? { env: process.env },
+      opts,
+   );
+}
 
+export function createHandler<Env = NodeEnv>(
+   config: NodeBkndConfig<Env> = {},
+   args: Env = {} as Env,
+   opts?: RuntimeOptions,
+) {
+   return async (req: Request) => {
+      const app = await createApp(config, args ?? (process.env as Env), opts);
+      return app.fetch(req);
+   };
+}
+
+export function serve<Env = NodeEnv>(
+   { port = $config.server.default_port, hostname, listener, ...config }: NodeBkndConfig<Env> = {},
+   args: Env = {} as Env,
+   opts?: RuntimeOptions,
+) {
    honoServe(
       {
          port,
          hostname,
-         fetch: async (req: Request) => {
+         fetch: createHandler(config, args, opts),
-            if (!app) {
-               registerLocalMediaAdapter();
-               app = await createRuntimeApp({
-                  ...config,
-                  serveStatic: serveStatic({ root }),
-               });
-            }
-
-            return app.fetch(req);
-         },
       },
       (connInfo) => {
          console.log(`Server is running on http://localhost:${connInfo.port}`);

app/src/adapter/node/storage/StorageLocalAdapter.native-spec.ts

@@ -0,0 +1,17 @@
+import { describe } from "node:test";
+import { StorageLocalAdapter, nodeTestRunner } from "adapter/node";
+import { adapterTestSuite } from "media/storage/adapters/adapter-test-suite";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+describe("StorageLocalAdapter (node)", async () => {
+   const basePath = path.resolve(import.meta.dirname, "../../../../__test__/_assets");
+   const buffer = readFileSync(path.join(basePath, "image.png"));
+   const file = new File([buffer], "image.png", { type: "image/png" });
+
+   const adapter = new StorageLocalAdapter({
+      path: path.join(basePath, "tmp"),
+   });
+
+   await adapterTestSuite(nodeTestRunner, adapter, file);
+});

app/src/adapter/node/storage/StorageLocalAdapter.spec.ts

@@ -0,0 +1,15 @@
+import { describe, test, expect } from "bun:test";
+import { StorageLocalAdapter } from "./StorageLocalAdapter";
+// @ts-ignore
+import { assetsPath, assetsTmpPath } from "../../../../__test__/helper";
+import { adapterTestSuite } from "media/storage/adapters/adapter-test-suite";
+import { bunTestRunner } from "adapter/bun/test";
+
+describe("StorageLocalAdapter (bun)", async () => {
+   const adapter = new StorageLocalAdapter({
+      path: assetsTmpPath,
+   });
+
+   const file = Bun.file(`${assetsPath}/image.png`);
+   await adapterTestSuite(bunTestRunner, adapter, file);
+});

app/src/adapter/node/storage/StorageLocalAdapter.ts

@@ -1,26 +1,21 @@
 import { readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
-import { type Static, Type, isFile, parse } from "core/utils";
+import { type Static, Type, isFile, parse } from "bknd/utils";
-import type {
+import type { FileBody, FileListObject, FileMeta, FileUploadPayload } from "bknd/media";
-   FileBody,
+import { StorageAdapter, guessMimeType as guess } from "bknd/media";
-   FileListObject,
-   FileMeta,
-   FileUploadPayload,
-   StorageAdapter,
-} from "../../Storage";
-import { guess } from "../../mime-types-tiny";
 
 export const localAdapterConfig = Type.Object(
    {
       path: Type.String({ default: "./" }),
    },
-   { title: "Local", description: "Local file system storage" },
+   { title: "Local", description: "Local file system storage", additionalProperties: false },
 );
 export type LocalAdapterConfig = Static<typeof localAdapterConfig>;
 
-export class StorageLocalAdapter implements StorageAdapter {
+export class StorageLocalAdapter extends StorageAdapter {
    private config: LocalAdapterConfig;
 
-   constructor(config: any) {
+   constructor(config: Partial<LocalAdapterConfig> = {}) {
+      super();
       this.config = parse(localAdapterConfig, config);
    }
 

app/src/adapter/node/test.ts

@@ -0,0 +1,99 @@
+import nodeAssert from "node:assert/strict";
+import { test } from "node:test";
+import type { Matcher, Test, TestFn, TestRunner } from "core/test";
+
+// Track mock function calls
+const mockCalls = new WeakMap<Function, number>();
+function createMockFunction<T extends (...args: any[]) => any>(fn: T): T {
+   const mockFn = (...args: Parameters<T>) => {
+      const currentCalls = mockCalls.get(mockFn) || 0;
+      mockCalls.set(mockFn, currentCalls + 1);
+      return fn(...args);
+   };
+   return mockFn as T;
+}
+
+const nodeTestMatcher = <T = unknown>(actual: T, parentFailMsg?: string) =>
+   ({
+      toEqual: (expected: T, failMsg = parentFailMsg) => {
+         nodeAssert.deepEqual(actual, expected, failMsg);
+      },
+      toBe: (expected: T, failMsg = parentFailMsg) => {
+         nodeAssert.strictEqual(actual, expected, failMsg);
+      },
+      toBeString: (failMsg = parentFailMsg) => {
+         nodeAssert.strictEqual(typeof actual, "string", failMsg);
+      },
+      toBeUndefined: (failMsg = parentFailMsg) => {
+         nodeAssert.strictEqual(actual, undefined, failMsg);
+      },
+      toBeDefined: (failMsg = parentFailMsg) => {
+         nodeAssert.notStrictEqual(actual, undefined, failMsg);
+      },
+      toBeOneOf: (expected: T | Array<T> | Iterable<T>, failMsg = parentFailMsg) => {
+         const e = Array.isArray(expected) ? expected : [expected];
+         nodeAssert.ok(e.includes(actual), failMsg);
+      },
+      toHaveBeenCalled: (failMsg = parentFailMsg) => {
+         const calls = mockCalls.get(actual as Function) || 0;
+         nodeAssert.ok(calls > 0, failMsg || "Expected function to have been called at least once");
+      },
+      toHaveBeenCalledTimes: (expected: number, failMsg = parentFailMsg) => {
+         const calls = mockCalls.get(actual as Function) || 0;
+         nodeAssert.strictEqual(
+            calls,
+            expected,
+            failMsg || `Expected function to have been called ${expected} times`,
+         );
+      },
+   }) satisfies Matcher<T>;
+
+const nodeTestResolverProxy = <T = unknown>(
+   actual: Promise<T>,
+   handler: { resolve?: any; reject?: any },
+) => {
+   return new Proxy(
+      {},
+      {
+         get: (_, prop) => {
+            if (prop === "then") {
+               return actual.then(handler.resolve, handler.reject);
+            }
+            return actual;
+         },
+      },
+   ) as Matcher<Awaited<T>>;
+};
+
+function nodeTest(label: string, fn: TestFn, options?: any) {
+   return test(label, fn as any);
+}
+nodeTest.if = (condition: boolean): Test => {
+   if (condition) {
+      return nodeTest;
+   }
+   return (() => {}) as any;
+};
+nodeTest.skip = (label: string, fn: TestFn) => {
+   return test.skip(label, fn as any);
+};
+nodeTest.skipIf = (condition: boolean): Test => {
+   if (condition) {
+      return (() => {}) as any;
+   }
+   return nodeTest;
+};
+
+export const nodeTestRunner: TestRunner = {
+   test: nodeTest,
+   mock: createMockFunction,
+   expect: <T = unknown>(actual?: T, failMsg?: string) => ({
+      ...nodeTestMatcher(actual, failMsg),
+      resolves: nodeTestResolverProxy(actual as Promise<T>, {
+         resolve: (r) => nodeTestMatcher(r, failMsg),
+      }),
+      rejects: nodeTestResolverProxy(actual as Promise<T>, {
+         reject: (r) => nodeTestMatcher(r, failMsg),
+      }),
+   }),
+};

app/src/adapter/react-router/react-router.adapter.spec.ts

@@ -0,0 +1,15 @@
+import { afterAll, beforeAll, describe } from "bun:test";
+import * as rr from "./react-router.adapter";
+import { disableConsoleLog, enableConsoleLog } from "core/utils";
+import { adapterTestSuite } from "adapter/adapter-test-suite";
+import { bunTestRunner } from "adapter/bun/test";
+
+beforeAll(disableConsoleLog);
+afterAll(enableConsoleLog);
+
+describe("react-router adapter", () => {
+   adapterTestSuite(bunTestRunner, {
+      makeApp: rr.getApp,
+      makeHandler: (c, a, o) => (request: Request) => rr.serve(c, a?.env, o)({ request }),
+   });
+});

app/src/adapter/react-router/react-router.adapter.ts

@@ -1,39 +1,26 @@
-import type { App } from "bknd";
 import { type FrameworkBkndConfig, createFrameworkApp } from "bknd/adapter";
+import type { FrameworkOptions } from "adapter";
 
-type ReactRouterContext = {
+type ReactRouterEnv = NodeJS.ProcessEnv;
+type ReactRouterFunctionArgs = {
    request: Request;
 };
-export type ReactRouterBkndConfig<Args = ReactRouterContext> = FrameworkBkndConfig<Args>;
+export type ReactRouterBkndConfig<Env = ReactRouterEnv> = FrameworkBkndConfig<Env>;
 
-let app: App;
+export async function getApp<Env = ReactRouterEnv>(
-let building: boolean = false;
+   config: ReactRouterBkndConfig<Env>,
-
+   args: Env = {} as Env,
-export async function getApp<Args extends ReactRouterContext = ReactRouterContext>(
+   opts?: FrameworkOptions,
-   config: ReactRouterBkndConfig<Args>,
-   args?: Args,
 ) {
-   if (building) {
+   return await createFrameworkApp(config, args ?? process.env, opts);
-      while (building) {
-         await new Promise((resolve) => setTimeout(resolve, 5));
-      }
-      if (app) return app;
-   }
-
-   building = true;
-   if (!app) {
-      app = await createFrameworkApp(config, args);
-      await app.build();
-   }
-   building = false;
-   return app;
 }
 
-export function serve<Args extends ReactRouterContext = ReactRouterContext>(
+export function serve<Env = ReactRouterEnv>(
-   config: ReactRouterBkndConfig<Args> = {},
+   config: ReactRouterBkndConfig<Env> = {},
+   args: Env = {} as Env,
+   opts?: FrameworkOptions,
 ) {
-   return async (args: Args) => {
+   return async (fnArgs: ReactRouterFunctionArgs) => {
-      app = await getApp(config, args);
+      return (await getApp(config, args, opts)).fetch(fnArgs.request);
-      return app.fetch(args.request);
    };
 }

app/src/adapter/vite/vite.adapter.ts

@@ -1,18 +1,24 @@
 import { serveStatic } from "@hono/node-server/serve-static";
-import { type DevServerOptions, default as honoViteDevServer } from "@hono/vite-dev-server";
+import {
+   type DevServerOptions,
+   default as honoViteDevServer,
+} from "@hono/vite-dev-server";
 import type { App } from "bknd";
-import { type RuntimeBkndConfig, createRuntimeApp } from "bknd/adapter";
+import {
+   type RuntimeBkndConfig,
+   createRuntimeApp,
+   type FrameworkOptions,
+} from "bknd/adapter";
 import { registerLocalMediaAdapter } from "bknd/adapter/node";
 import { devServerConfig } from "./dev-server-config";
 
-export type ViteBkndConfig<Env = any> = RuntimeBkndConfig<Env> & {
+export type ViteEnv = NodeJS.ProcessEnv;
-   mode?: "cached" | "fresh";
+export type ViteBkndConfig<Env = ViteEnv> = RuntimeBkndConfig<Env> & {};
-   setAdminHtml?: boolean;
-   forceDev?: boolean | { mainPath: string };
-   html?: string;
-};
 
-export function addViteScript(html: string, addBkndContext: boolean = true) {
+export function addViteScript(
+   html: string,
+   addBkndContext: boolean = true,
+) {
    return html.replace(
       "</head>",
       `<script type="module">
@@ -28,52 +34,40 @@ ${addBkndContext ? "<!-- BKND_CONTEXT -->" : ""}
    );
 }
 
-async function createApp(config: ViteBkndConfig = {}, env?: any) {
+async function createApp<ViteEnv>(
+   config: ViteBkndConfig<ViteEnv> = {},
+   env: ViteEnv = {} as ViteEnv,
+   opts: FrameworkOptions = {},
+): Promise<App> {
    registerLocalMediaAdapter();
    return await createRuntimeApp(
       {
          ...config,
-         adminOptions:
+         adminOptions: config.adminOptions ?? {
-            config.setAdminHtml === false
+            forceDev: {
-               ? undefined
+               mainPath: "/src/main.tsx",
-               : {
+            },
-                    html: config.html,
+         },
-                    forceDev: config.forceDev ?? {
-                       mainPath: "/src/main.tsx",
-                    },
-                 },
          serveStatic: ["/assets/*", serveStatic({ root: config.distPath ?? "./" })],
       },
       env,
+      opts,
    );
 }
 
-export function serveFresh(config: Omit<ViteBkndConfig, "mode"> = {}) {
+export function serve<ViteEnv>(
+   config: ViteBkndConfig<ViteEnv> = {},
+   args?: ViteEnv,
+   opts?: FrameworkOptions,
+) {
    return {
       async fetch(request: Request, env: any, ctx: ExecutionContext) {
-         const app = await createApp(config, env);
+         const app = await createApp(config, env, opts);
          return app.fetch(request, env, ctx);
       },
    };
 }
 
-let app: App;
-export function serveCached(config: Omit<ViteBkndConfig, "mode"> = {}) {
-   return {
-      async fetch(request: Request, env: any, ctx: ExecutionContext) {
-         if (!app) {
-            app = await createApp(config, env);
-         }
-
-         return app.fetch(request, env, ctx);
-      },
-   };
-}
-
-export function serve({ mode, ...config }: ViteBkndConfig = {}) {
-   return mode === "fresh" ? serveFresh(config) : serveCached(config);
-}
-
 export function devServer(options: DevServerOptions) {
    return honoViteDevServer({
       ...devServerConfig,

app/src/auth/authenticate/Authenticator.ts

@@ -1,4 +1,4 @@
-import { type DB, Exception } from "core";
+import { type DB, Exception, type PrimaryFieldType } from "core";
 import { addFlashMessage } from "core/server/flash";
 import {
    type Static,
@@ -14,6 +14,7 @@ import { deleteCookie, getSignedCookie, setSignedCookie } from "hono/cookie";
 import { sign, verify } from "hono/jwt";
 import type { CookieOptions } from "hono/utils/cookie";
 import type { ServerEnv } from "modules/Controller";
+import { pick } from "lodash-es";
 
 type Input = any; // workaround
 export type JWTPayload = Parameters<typeof sign>[0];
@@ -37,11 +38,10 @@ export interface Strategy {
 }
 
 export type User = {
-   id: number;
+   id: PrimaryFieldType;
    email: string;
-   username: string;
    password: string;
-   role: string;
+   role?: string | null;
 };
 
 export type ProfileExchange = {
@@ -158,13 +158,8 @@ export class Authenticator<Strategies extends Record<string, Strategy> = Record<
    }
 
    // @todo: add jwt tests
-   async jwt(user: Omit<User, "password">): Promise<string> {
+   async jwt(_user: Omit<User, "password">): Promise<string> {
-      const prohibited = ["password"];
+      const user = pick(_user, this.config.jwt.fields);
-      for (const prop of prohibited) {
-         if (prop in user) {
-            throw new Error(`Property "${prop}" is prohibited`);
-         }
-      }
 
       const payload: JWTPayload = {
          ...user,

app/src/auth/middlewares.ts

@@ -1,4 +1,4 @@
-import type { Permission } from "core";
+import { $console, type Permission } from "core";
 import { patternMatch } from "core/utils";
 import type { Context } from "hono";
 import { createMiddleware } from "hono/factory";
@@ -49,7 +49,7 @@ export const auth = (options?: {
       // make sure to only register once
       if (authCtx.registered) {
          skipped = true;
-         console.warn(`auth middleware already registered for ${getPath(c)}`);
+         $console.warn(`auth middleware already registered for ${getPath(c)}`);
       } else {
          authCtx.registered = true;
 
@@ -93,7 +93,7 @@ export const permission = (
          if (app?.module.auth.enabled) {
             throw new Error(msg);
          } else {
-            console.warn(msg);
+            $console.warn(msg);
          }
       } else if (!authCtx.skip) {
          const guard = app.modules.ctx().guard;

app/src/cli/commands/create/create.ts

@@ -8,7 +8,7 @@ import { Option } from "commander";
 import { env } from "core";
 import color from "picocolors";
 import { overridePackageJson, updateBkndPackages } from "./npm";
-import { type Template, templates } from "./templates";
+import { type Template, templates, type TemplateSetupCtx } from "./templates";
 import { createScoped, flush } from "cli/utils/telemetry";
 
 const config = {
@@ -35,6 +35,8 @@ export const create: CliCommand = (program) => {
       .addOption(new Option("-i, --integration <integration>", "integration to use"))
       .addOption(new Option("-t, --template <template>", "template to use"))
       .addOption(new Option("-d --dir <directory>", "directory to create in"))
+      .addOption(new Option("-c, --clean", "cleans destination directory"))
+      .addOption(new Option("-y, --yes", "use defaults, skip skippable prompts"))
       .description("create a new project")
       .action(action);
 };
@@ -53,7 +55,7 @@ async function onExit() {
    await flush();
 }
 
-async function action(options: { template?: string; dir?: string; integration?: string }) {
+async function action(options: { template?: string; dir?: string; integration?: string, yes?: boolean, clean?: boolean }) {
    console.log("");
    const $t = createScoped("create");
    $t.capture("start", {
@@ -94,7 +96,7 @@ async function action(options: { template?: string; dir?: string; integration?:
 
    $t.properties.at = "dir";
    if (fs.existsSync(downloadOpts.dir)) {
-      const clean = await $p.confirm({
+      const clean = options.clean ?? await $p.confirm({
          message: `Directory ${color.cyan(downloadOpts.dir)} exists. Clean it?`,
          initialValue: false,
       });
@@ -203,7 +205,7 @@ async function action(options: { template?: string; dir?: string; integration?:
    }
 
    $t.properties.template = template.key;
-   const ctx = { template, dir: downloadOpts.dir, name };
+   const ctx: TemplateSetupCtx = { template, dir: downloadOpts.dir, name, skip: !!options.yes };
 
    {
       const ref = env("cli_create_ref", `#v${version}`, {
@@ -259,7 +261,7 @@ async function action(options: { template?: string; dir?: string; integration?:
    $p.log.success(`Updated package name to ${color.cyan(ctx.name)}`);
 
    {
-      const install = await $p.confirm({
+      const install = options.yes ?? await $p.confirm({
          message: "Install dependencies?",
       });
 

app/src/cli/commands/create/npm.ts

@@ -24,6 +24,32 @@ export async function overrideJson<File extends object = object>(
    await writeFile(pkgPath, JSON.stringify(newPkg, null, opts?.indent || 2));
 }
 
+export async function upsertEnvFile(
+   kv: Record<string, string | number>,
+   opts?: { dir?: string; file?: string },
+) {
+   const file = opts?.file ?? ".env";
+   const envPath = path.resolve(opts?.dir ?? process.cwd(), file);
+   const current: Record<string, string | number> = {};
+
+   try {
+      const values = await readFile(envPath, "utf-8");
+      const lines = values.split("\n");
+      for (const line of lines) {
+         const [key, value] = line.split("=");
+         if (key && value) {
+            current[key] = value;
+         }
+      }
+   } catch (e) {
+      await writeFile(envPath, "");
+   }
+
+   const newEnv = { ...current, ...kv };
+   const lines = Object.entries(newEnv).map(([key, value]) => `${key}=${value}`);
+   await writeFile(envPath, lines.join("\n"));
+}
+
 export async function overridePackageJson(
    fn: (pkg: TPackageJson) => Promise<TPackageJson> | TPackageJson,
    opts?: { dir?: string },

app/src/cli/commands/create/templates/aws.ts

@@ -0,0 +1,85 @@
+import * as $p from "@clack/prompts";
+import { upsertEnvFile } from "cli/commands/create/npm";
+import { typewriter } from "cli/utils/cli";
+import c from "picocolors";
+import type { Template } from ".";
+import open from "open";
+
+export const aws = {
+   key: "aws",
+   title: "AWS Lambda Basic",
+   integration: "aws",
+   description: "A basic bknd AWS Lambda starter",
+   path: "gh:bknd-io/bknd/examples/aws-lambda",
+   ref: true,
+   setup: async (ctx) => {
+      await $p.stream.info(
+         (async function* () {
+            yield* typewriter("You need a running LibSQL instance for this adapter to work.");
+         })(),
+      );
+
+      const choice = await $p.select({
+         message: "How do you want to proceed?",
+         options: [
+            { label: "Enter instance details", value: "enter" },
+            { label: "Create a new instance", value: "new" },
+         ],
+      });
+      if ($p.isCancel(choice)) {
+         process.exit(1);
+      }
+
+      if (choice === "new") {
+         await $p.stream.info(
+            (async function* () {
+               yield* typewriter(c.dim("Proceed on turso.tech to create your instance."));
+            })(),
+         );
+
+         await open("https://sqlite.new");
+      }
+
+      const url = await $p.text({
+         message: "Enter database URL",
+         placeholder: "libsql://<instance>.turso.io",
+         validate: (v) => {
+            if (!v) {
+               return "Invalid URL";
+            }
+            return;
+         },
+      });
+      if ($p.isCancel(url)) {
+         process.exit(1);
+      }
+
+      const token = await $p.text({
+         message: "Enter database token",
+         placeholder: "eyJhbGciOiJIUzI1NiIsInR...",
+         validate: (v) => {
+            if (!v) {
+               return "";
+            }
+            return;
+         },
+      });
+      if ($p.isCancel(token)) {
+         process.exit(1);
+      }
+
+      await upsertEnvFile(
+         {
+            DB_URL: url,
+            DB_TOKEN: token ?? "",
+         },
+         { dir: ctx.dir },
+      );
+
+      await $p.stream.info(
+         (async function* () {
+            yield* typewriter(`Connection details written to ${c.cyan(".env")}`);
+         })(),
+      );
+   },
+} as const satisfies Template;

app/src/cli/commands/create/templates/cloudflare.ts

@@ -4,6 +4,7 @@ import { typewriter, wait } from "cli/utils/cli";
 import { uuid } from "core/utils";
 import c from "picocolors";
 import type { Template, TemplateSetupCtx } from ".";
+import { exec } from "cli/utils/sys";
 
 const WRANGLER_FILE = "wrangler.json";
 
@@ -28,13 +29,15 @@ export const cloudflare = {
          { dir: ctx.dir },
       );
 
-      const db = await $p.select({
+      const db = ctx.skip
-         message: "What database do you want to use?",
+         ? "d1"
-         options: [
+         : await $p.select({
-            { label: "Cloudflare D1", value: "d1" },
+              message: "What database do you want to use?",
-            { label: "LibSQL", value: "libsql" },
+              options: [
-         ],
+                 { label: "Cloudflare D1", value: "d1" },
-      });
+                 { label: "LibSQL", value: "libsql" },
+              ],
+           });
       if ($p.isCancel(db)) {
          process.exit(1);
       }
@@ -56,25 +59,46 @@ export const cloudflare = {
             "Couldn't add database. You can add it manually later. Error: " + c.red(message),
          );
       }
+
+      await createR2(ctx);
    },
 } as const satisfies Template;
 
 async function createD1(ctx: TemplateSetupCtx) {
-   const name = await $p.text({
+   const default_db = "data";
-      message: "Enter database name",
+   const name = ctx.skip
-      initialValue: "data",
+      ? default_db
-      placeholder: "data",
+      : await $p.text({
-      validate: (v) => {
+           message: "Enter database name",
-         if (!v) {
+           initialValue: default_db,
-            return "Invalid name";
+           placeholder: default_db,
-         }
+           validate: (v) => {
-         return;
+              if (!v) {
-      },
+                 return "Invalid name";
-   });
+              }
+              return;
+           },
+        });
    if ($p.isCancel(name)) {
       process.exit(1);
    }
 
+   await $p.stream.info(
+      (async function* () {
+         yield* typewriter("Now running wrangler to create a D1 database...");
+      })(),
+   );
+
+   if (!ctx.skip) {
+      exec(`npx wrangler d1 create ${name}`);
+
+      await $p.stream.info(
+         (async function* () {
+            yield* typewriter("Please update your wrangler configuration with the output above.");
+         })(),
+      );
+   }
+
    await overrideJson(
       WRANGLER_FILE,
       (json) => ({
@@ -89,17 +113,6 @@ async function createD1(ctx: TemplateSetupCtx) {
       }),
       { dir: ctx.dir },
    );
-
-   await $p.stream.info(
-      (async function* () {
-         yield* typewriter(`Database added to ${c.cyan("wrangler.json")}`);
-         await wait();
-         yield* typewriter(
-            `\nNote that if you deploy, you have to create a real database using ${c.cyan("npx wrangler d1 create <name>")} and update your wrangler configuration.`,
-            c.dim,
-         );
-      })(),
-   );
 }
 
 async function createLibsql(ctx: TemplateSetupCtx) {
@@ -142,3 +155,63 @@ async function createLibsql(ctx: TemplateSetupCtx) {
       })(),
    );
 }
+
+async function createR2(ctx: TemplateSetupCtx) {
+   const create = ctx.skip
+      ? false
+      : await $p.confirm({
+           message: "Do you want to use a R2 bucket?",
+           initialValue: true,
+        });
+   if ($p.isCancel(create)) {
+      process.exit(1);
+   }
+
+   if (!create) {
+      await overrideJson(
+         WRANGLER_FILE,
+         (json) => ({
+            ...json,
+            r2_buckets: undefined,
+         }),
+         { dir: ctx.dir },
+      );
+      return;
+   }
+
+   const default_bucket = "bucket";
+   const name = ctx.skip
+      ? default_bucket
+      : await $p.text({
+           message: "Enter bucket name",
+           initialValue: default_bucket,
+           placeholder: default_bucket,
+           validate: (v) => {
+              if (!v) {
+                 return "Invalid name";
+              }
+              return;
+           },
+        });
+   if ($p.isCancel(name)) {
+      process.exit(1);
+   }
+
+   if (!ctx.skip) {
+      exec(`npx wrangler r2 bucket create ${name}`);
+   }
+
+   await overrideJson(
+      WRANGLER_FILE,
+      (json) => ({
+         ...json,
+         r2_buckets: [
+            {
+               binding: "BUCKET",
+               bucket_name: name,
+            },
+         ],
+      }),
+      { dir: ctx.dir },
+   );
+}

app/src/cli/commands/create/templates/index.ts

@@ -4,6 +4,7 @@ export type TemplateSetupCtx = {
    template: Template;
    dir: string;
    name: string;
+   skip: boolean;
 };
 
 export type Integration =

app/src/cli/commands/run/platform.ts

@@ -72,7 +72,8 @@ export async function getConfigPath(filePath?: string) {
       }
    }
 
-   const paths = ["./bknd.config", "./bknd.config.ts", "./bknd.config.js"];
+   const exts = ["", ".js", ".ts", ".mjs", ".cjs", ".json"];
+   const paths = exts.map((e) => `bknd.config${e}`);
    for (const p of paths) {
       const _p = path.resolve(process.cwd(), p);
       if (await fileExists(_p)) {

app/src/cli/commands/run/run.ts

@@ -7,6 +7,7 @@ import { colorizeConsole, config } from "core";
 import dotenv from "dotenv";
 import { registries } from "modules/registries";
 import c from "picocolors";
+import path from "node:path";
 import {
    PLATFORMS,
    type Platform,
@@ -15,9 +16,14 @@ import {
    getConnectionCredentialsFromEnv,
    startServer,
 } from "./platform";
+import { makeConfig } from "adapter";
+import { isBun as $isBun } from "cli/utils/sys";
 
-dotenv.config();
+const env_files = [".env", ".dev.vars"];
-const isBun = typeof Bun !== "undefined";
+dotenv.config({
+   path: env_files.map((file) => path.resolve(process.cwd(), file)),
+});
+const isBun = $isBun();
 
 export const run: CliCommand = (program) => {
    program
@@ -85,27 +91,15 @@ async function makeApp(config: MakeAppConfig) {
    return app;
 }
 
-export async function makeConfigApp(config: CliBkndConfig, platform?: Platform) {
+export async function makeConfigApp(_config: CliBkndConfig, platform?: Platform) {
-   const appConfig = typeof config.app === "function" ? config.app(process.env) : config.app;
+   const config = makeConfig(_config, { env: process.env });
-   const app = App.create(appConfig);
+   return makeApp({
-
+      ...config,
-   app.emgr.onEvent(
+      server: { platform },
-      App.Events.AppBuiltEvent,
+   });
-      async () => {
-         await attachServeStatic(app, platform ?? "node");
-         app.registerAdminController();
-
-         await config.onBuilt?.(app);
-      },
-      "sync",
-   );
-
-   await config.beforeBuild?.(app);
-   await app.build(config.buildConfig);
-   return app;
 }
 
-async function action(options: {
+type RunOptions = {
    port: number;
    memory?: boolean;
    config?: string;
@@ -113,24 +107,37 @@ async function action(options: {
    dbToken?: string;
    server: Platform;
    open?: boolean;
-}) {
+};
-   colorizeConsole(console);
+
+export async function makeAppFromEnv(options: Partial<RunOptions> = {}) {
    const configFilePath = await getConfigPath(options.config);
 
    let app: App | undefined = undefined;
+   // first start from arguments if given
    if (options.dbUrl) {
       console.info("Using connection from", c.cyan("--db-url"));
       const connection = options.dbUrl
          ? { url: options.dbUrl, authToken: options.dbToken }
          : undefined;
       app = await makeApp({ connection, server: { platform: options.server } });
+
+      // check configuration file to be present
    } else if (configFilePath) {
       console.info("Using config from", c.cyan(configFilePath));
-      const config = (await import(configFilePath).then((m) => m.default)) as CliBkndConfig;
+      try {
-      app = await makeConfigApp(config, options.server);
+         const config = (await import(configFilePath).then((m) => m.default)) as CliBkndConfig;
+         app = await makeConfigApp(config, options.server);
+      } catch (e) {
+         console.error("Failed to load config:", e);
+         process.exit(1);
+      }
+
+      // try to use an in-memory connection
    } else if (options.memory) {
       console.info("Using", c.cyan("in-memory"), "connection");
       app = await makeApp({ server: { platform: options.server } });
+
+      // finally try to use env variables
    } else {
       const credentials = getConnectionCredentialsFromEnv();
       if (credentials) {
@@ -139,14 +146,22 @@ async function action(options: {
       }
    }
 
+   // if nothing helps, create a file based app
    if (!app) {
       const connection = { url: "file:data.db" } as Config;
-      console.info("Using connection", c.cyan(connection.url));
+      console.info("Using fallback connection", c.cyan(connection.url));
       app = await makeApp({
          connection,
          server: { platform: options.server },
       });
    }
 
+   return app;
+}
+
+async function action(options: RunOptions) {
+   colorizeConsole(console);
+
+   const app = await makeAppFromEnv(options);
    await startServer(options.server, app, { port: options.port, open: options.open });
 }

app/src/cli/commands/user.ts

@@ -1,28 +1,32 @@
-import { password as $password, text as $text } from "@clack/prompts";
+import {
+   isCancel as $isCancel,
+   log as $log,
+   password as $password,
+   text as $text,
+} from "@clack/prompts";
 import type { App } from "App";
 import type { PasswordStrategy } from "auth/authenticate/strategies";
-import { makeConfigApp } from "cli/commands/run";
+import { makeAppFromEnv } from "cli/commands/run";
-import { getConfigPath } from "cli/commands/run/platform";
+import type { CliCommand } from "cli/types";
-import type { CliBkndConfig, CliCommand } from "cli/types";
 import { Argument } from "commander";
+import { $console } from "core";
+import c from "picocolors";
+import { isBun } from "cli/utils/sys";
 
 export const user: CliCommand = (program) => {
    program
       .command("user")
-      .description("create and update user (auth)")
+      .description("create/update users, or generate a token (auth)")
-      .addArgument(new Argument("<action>", "action to perform").choices(["create", "update"]))
+      .addArgument(
+         new Argument("<action>", "action to perform").choices(["create", "update", "token"]),
+      )
       .action(action);
 };
 
-async function action(action: "create" | "update", options: any) {
+async function action(action: "create" | "update" | "token", options: any) {
-   const configFilePath = await getConfigPath();
+   const app = await makeAppFromEnv({
-   if (!configFilePath) {
+      server: "node",
-      console.error("config file not found");
+   });
-      return;
-   }
-
-   const config = (await import(configFilePath).then((m) => m.default)) as CliBkndConfig;
-   const app = await makeConfigApp(config, options.server);
 
    switch (action) {
       case "create":
@@ -31,6 +35,9 @@ async function action(action: "create" | "update", options: any) {
       case "update":
          await update(app, options);
          break;
+      case "token":
+         await token(app, options);
+         break;
    }
 }
 
@@ -38,7 +45,8 @@ async function create(app: App, options: any) {
    const strategy = app.module.auth.authenticator.strategy("password") as PasswordStrategy;
 
    if (!strategy) {
-      throw new Error("Password strategy not configured");
+      $log.error("Password strategy not configured");
+      process.exit(1);
    }
 
    const email = await $text({
@@ -50,6 +58,7 @@ async function create(app: App, options: any) {
          return;
       },
    });
+   if ($isCancel(email)) process.exit(1);
 
    const password = await $password({
       message: "Enter password",
@@ -60,20 +69,17 @@ async function create(app: App, options: any) {
          return;
       },
    });
-
+   if ($isCancel(password)) process.exit(1);
-   if (typeof email !== "string" || typeof password !== "string") {
-      console.log("Cancelled");
-      process.exit(0);
-   }
 
    try {
       const created = await app.createUser({
          email,
          password: await strategy.hash(password as string),
       });
-      console.log("Created:", created);
+      $log.success(`Created user: ${c.cyan(created.email)}`);
    } catch (e) {
-      console.error("Error", e);
+      $log.error("Error creating user");
+      $console.error(e);
    }
 }
 
@@ -92,17 +98,14 @@ async function update(app: App, options: any) {
          return;
       },
    })) as string;
-   if (typeof email !== "string") {
+   if ($isCancel(email)) process.exit(1);
-      console.log("Cancelled");
-      process.exit(0);
-   }
 
    const { data: user } = await em.repository(users_entity).findOne({ email });
    if (!user) {
-      console.log("User not found");
+      $log.error("User not found");
-      process.exit(0);
+      process.exit(1);
    }
-   console.log("User found:", user);
+   $log.info(`User found: ${c.cyan(user.email)}`);
 
    const password = await $password({
       message: "New Password?",
@@ -113,10 +116,7 @@ async function update(app: App, options: any) {
          return;
       },
    });
-   if (typeof password !== "string") {
+   if ($isCancel(password)) process.exit(1);
-      console.log("Cancelled");
-      process.exit(0);
-   }
 
    try {
       function togglePw(visible: boolean) {
@@ -134,8 +134,42 @@ async function update(app: App, options: any) {
          });
       togglePw(false);
 
-      console.log("Updated:", user);
+      $log.success(`Updated user: ${c.cyan(user.email)}`);
    } catch (e) {
-      console.error("Error", e);
+      $log.error("Error updating user");
+      $console.error(e);
    }
 }
+
+async function token(app: App, options: any) {
+   if (isBun()) {
+      $log.error("Please use node to generate tokens");
+      process.exit(1);
+   }
+
+   const config = app.module.auth.toJSON(true);
+   const users_entity = config.entity_name as "users";
+   const em = app.modules.ctx().em;
+
+   const email = (await $text({
+      message: "Which user? Enter email",
+      validate: (v) => {
+         if (!v.includes("@")) {
+            return "Invalid email";
+         }
+         return;
+      },
+   })) as string;
+   if ($isCancel(email)) process.exit(1);
+
+   const { data: user } = await em.repository(users_entity).findOne({ email });
+   if (!user) {
+      $log.error("User not found");
+      process.exit(1);
+   }
+   $log.info(`User found: ${c.cyan(user.email)}`);
+
+   console.log(
+      `\n${c.dim("Token:")}\n${c.yellow(await app.module.auth.authenticator.jwt(user))}\n`,
+   );
+}

app/src/cli/types.d.ts

@@ -1,12 +1,9 @@
-import type { CreateAppConfig } from "App";
+import type { BkndConfig } from "adapter";
-import type { FrameworkBkndConfig } from "adapter";
 import type { Command } from "commander";
 
 export type CliCommand = (program: Command) => void;
 
-export type CliBkndConfig<Env = any> = FrameworkBkndConfig & {
+export type CliBkndConfig<Env = any> = BkndConfig & {
-   app: CreateAppConfig | ((env: Env) => CreateAppConfig);
-   setAdminHtml?: boolean;
    server?: {
       port?: number;
       platform?: "node" | "bun";

app/src/cli/utils/sys.ts

@@ -3,6 +3,14 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import url from "node:url";
 
+export function isBun(): boolean {
+   try {
+      return typeof Bun !== "undefined";
+   } catch (e) {
+      return false;
+   }
+}
+
 export function getRootPath() {
    const _path = path.dirname(url.fileURLToPath(import.meta.url));
    // because of "src", local needs one more level up

app/src/core/cache/adapters/CloudflareKvCache.ts

@@ -1,127 +0,0 @@
-import type { ICacheItem, ICachePool } from "../cache-interface";
-
-export class CloudflareKVCachePool<Data = any> implements ICachePool<Data> {
-   constructor(private namespace: KVNamespace) {}
-
-   supports = () => ({
-      metadata: true,
-      clear: false,
-   });
-
-   async get(key: string): Promise<ICacheItem<Data>> {
-      const result = await this.namespace.getWithMetadata<any>(key);
-      const hit = result.value !== null && typeof result.value !== "undefined";
-      // Assuming metadata is not supported directly;
-      // you may adjust if Cloudflare KV supports it in future.
-      return new CloudflareKVCacheItem(key, result.value ?? undefined, hit, result.metadata) as any;
-   }
-
-   async getMany(keys: string[] = []): Promise<Map<string, ICacheItem<Data>>> {
-      const items = new Map<string, ICacheItem<Data>>();
-      await Promise.all(
-         keys.map(async (key) => {
-            const item = await this.get(key);
-            items.set(key, item);
-         }),
-      );
-      return items;
-   }
-
-   async has(key: string): Promise<boolean> {
-      const data = await this.namespace.get(key);
-      return data !== null;
-   }
-
-   async clear(): Promise<boolean> {
-      // Cloudflare KV does not support clearing all keys in one operation
-      return false;
-   }
-
-   async delete(key: string): Promise<boolean> {
-      await this.namespace.delete(key);
-      return true;
-   }
-
-   async deleteMany(keys: string[]): Promise<boolean> {
-      const results = await Promise.all(keys.map((key) => this.delete(key)));
-      return results.every((result) => result);
-   }
-
-   async save(item: CloudflareKVCacheItem<Data>): Promise<boolean> {
-      await this.namespace.put(item.key(), (await item.value()) as string, {
-         expirationTtl: item._expirationTtl,
-         metadata: item.metadata(),
-      });
-
-      return true;
-   }
-
-   async put(
-      key: string,
-      value: any,
-      options?: { ttl?: number; expiresAt?: Date; metadata?: Record<string, string> },
-   ): Promise<boolean> {
-      const item = new CloudflareKVCacheItem(key, value, true, options?.metadata);
-
-      if (options?.expiresAt) item.expiresAt(options.expiresAt);
-      if (options?.ttl) item.expiresAfter(options.ttl);
-
-      return await this.save(item);
-   }
-}
-
-export class CloudflareKVCacheItem<Data = any> implements ICacheItem<Data> {
-   _expirationTtl: number | undefined;
-
-   constructor(
-      private _key: string,
-      private data: Data | undefined,
-      private _hit: boolean = false,
-      private _metadata: Record<string, string> = {},
-   ) {}
-
-   key(): string {
-      return this._key;
-   }
-
-   value(): Data | undefined {
-      if (this.data) {
-         try {
-            return JSON.parse(this.data as string);
-         } catch (e) {}
-      }
-
-      return this.data ?? undefined;
-   }
-
-   metadata(): Record<string, string> {
-      return this._metadata;
-   }
-
-   hit(): boolean {
-      return this._hit;
-   }
-
-   set(value: Data, metadata: Record<string, string> = {}): this {
-      this.data = value;
-      this._metadata = metadata;
-      return this;
-   }
-
-   expiresAt(expiration: Date | null): this {
-      // Cloudflare KV does not support specific date expiration; calculate ttl instead.
-      if (expiration) {
-         const now = new Date();
-         const ttl = (expiration.getTime() - now.getTime()) / 1000;
-         return this.expiresAfter(Math.max(0, Math.floor(ttl)));
-      }
-      return this.expiresAfter(null);
-   }
-
-   expiresAfter(time: number | null): this {
-      // Dummy implementation as Cloudflare KV requires setting expiration during PUT operation.
-      // This method will be effectively implemented in the Cache Pool save methods.
-      this._expirationTtl = time ?? undefined;
-      return this;
-   }
-}

app/src/core/cache/adapters/MemoryCache.ts

@@ -1,139 +0,0 @@
-import type { ICacheItem, ICachePool } from "../cache-interface";
-
-export class MemoryCache<Data = any> implements ICachePool<Data> {
-   private cache: Map<string, MemoryCacheItem<Data>> = new Map();
-   private maxSize?: number;
-
-   constructor(options?: { maxSize?: number }) {
-      this.maxSize = options?.maxSize;
-   }
-
-   supports = () => ({
-      metadata: true,
-      clear: true,
-   });
-
-   async get(key: string): Promise<MemoryCacheItem<Data>> {
-      if (!this.cache.has(key)) {
-         // use undefined to denote a miss initially
-         return new MemoryCacheItem<Data>(key, undefined!);
-      }
-      return this.cache.get(key)!;
-   }
-
-   async getMany(keys: string[] = []): Promise<Map<string, MemoryCacheItem<Data>>> {
-      const items = new Map<string, MemoryCacheItem<Data>>();
-      for (const key of keys) {
-         items.set(key, await this.get(key));
-      }
-      return items;
-   }
-
-   async has(key: string): Promise<boolean> {
-      return this.cache.has(key) && this.cache.get(key)!.hit();
-   }
-
-   async clear(): Promise<boolean> {
-      this.cache.clear();
-      return true;
-   }
-
-   async delete(key: string): Promise<boolean> {
-      return this.cache.delete(key);
-   }
-
-   async deleteMany(keys: string[]): Promise<boolean> {
-      let success = true;
-      for (const key of keys) {
-         if (!this.delete(key)) {
-            success = false;
-         }
-      }
-      return success;
-   }
-
-   async save(item: MemoryCacheItem<Data>): Promise<boolean> {
-      this.checkSizeAndPurge();
-      this.cache.set(item.key(), item);
-      return true;
-   }
-
-   async put(
-      key: string,
-      value: Data,
-      options: { expiresAt?: Date; ttl?: number; metadata?: Record<string, string> } = {},
-   ): Promise<boolean> {
-      const item = await this.get(key);
-      item.set(value, options.metadata || {});
-      if (options.expiresAt) {
-         item.expiresAt(options.expiresAt);
-      } else if (typeof options.ttl === "number") {
-         item.expiresAfter(options.ttl);
-      }
-      return this.save(item);
-   }
-
-   private checkSizeAndPurge(): void {
-      if (!this.maxSize) return;
-
-      if (this.cache.size >= this.maxSize) {
-         // Implement logic to purge items, e.g., LRU (Least Recently Used)
-         // For simplicity, clear the oldest item inserted
-         const keyToDelete = this.cache.keys().next().value;
-         this.cache.delete(keyToDelete!);
-      }
-   }
-}
-
-export class MemoryCacheItem<Data = any> implements ICacheItem<Data> {
-   private _key: string;
-   private _value: Data | undefined;
-   private expiration: Date | null = null;
-   private _metadata: Record<string, string> = {};
-
-   constructor(key: string, value: Data, metadata: Record<string, string> = {}) {
-      this._key = key;
-      this.set(value, metadata);
-   }
-
-   key(): string {
-      return this._key;
-   }
-
-   metadata(): Record<string, string> {
-      return this._metadata;
-   }
-
-   value(): Data | undefined {
-      return this._value;
-   }
-
-   hit(): boolean {
-      if (this.expiration !== null && new Date() > this.expiration) {
-         return false;
-      }
-      return this.value() !== undefined;
-   }
-
-   set(value: Data, metadata: Record<string, string> = {}): this {
-      this._value = value;
-      this._metadata = metadata;
-      return this;
-   }
-
-   expiresAt(expiration: Date | null): this {
-      this.expiration = expiration;
-      return this;
-   }
-
-   expiresAfter(time: number | null): this {
-      if (typeof time === "number") {
-         const expirationDate = new Date();
-         expirationDate.setSeconds(expirationDate.getSeconds() + time);
-         this.expiration = expirationDate;
-      } else {
-         this.expiration = null;
-      }
-      return this;
-   }
-}

app/src/core/cache/cache-interface.ts

@@ -1,178 +0,0 @@
-/**
- * CacheItem defines an interface for interacting with objects inside a cache.
- * based on https://www.php-fig.org/psr/psr-6/
- */
-export interface ICacheItem<Data = any> {
-   /**
-    * Returns the key for the current cache item.
-    *
-    * The key is loaded by the Implementing Library, but should be available to
-    * the higher level callers when needed.
-    *
-    * @returns The key string for this cache item.
-    */
-   key(): string;
-
-   /**
-    * Retrieves the value of the item from the cache associated with this object's key.
-    *
-    * The value returned must be identical to the value originally stored by set().
-    *
-    * If isHit() returns false, this method MUST return null. Note that null
-    * is a legitimate cached value, so the isHit() method SHOULD be used to
-    * differentiate between "null value was found" and "no value was found."
-    *
-    * @returns The value corresponding to this cache item's key, or undefined if not found.
-    */
-   value(): Data | undefined;
-
-   /**
-    * Retrieves the metadata of the item from the cache associated with this object's key.
-    */
-   metadata(): Record<string, string>;
-
-   /**
-    * Confirms if the cache item lookup resulted in a cache hit.
-    *
-    * Note: This method MUST NOT have a race condition between calling isHit()
-    * and calling get().
-    *
-    * @returns True if the request resulted in a cache hit. False otherwise.
-    */
-   hit(): boolean;
-
-   /**
-    * Sets the value represented by this cache item.
-    *
-    * The value argument may be any item that can be serialized by PHP,
-    * although the method of serialization is left up to the Implementing
-    * Library.
-    *
-    * @param value The serializable value to be stored.
-    * @param metadata The metadata to be associated with the item.
-    * @returns The invoked object.
-    */
-   set(value: Data, metadata?: Record<string, string>): this;
-
-   /**
-    * Sets the expiration time for this cache item.
-    *
-    * @param expiration The point in time after which the item MUST be considered expired.
-    *                   If null is passed explicitly, a default value MAY be used. If none is set,
-    *                   the value should be stored permanently or for as long as the
-    *                   implementation allows.
-    * @returns The called object.
-    */
-   expiresAt(expiration: Date | null): this;
-
-   /**
-    * Sets the expiration time for this cache item.
-    *
-    * @param time The period of time from the present after which the item MUST be considered
-    *             expired. An integer parameter is understood to be the time in seconds until
-    *             expiration. If null is passed explicitly, a default value MAY be used.
-    *             If none is set, the value should be stored permanently or for as long as the
-    *             implementation allows.
-    * @returns The called object.
-    */
-   expiresAfter(time: number | null): this;
-}
-
-/**
- * CachePool generates CacheItem objects.
- * based on https://www.php-fig.org/psr/psr-6/
- */
-export interface ICachePool<Data = any> {
-   supports(): {
-      metadata: boolean;
-      clear: boolean;
-   };
-
-   /**
-    * Returns a Cache Item representing the specified key.
-    * This method must always return a CacheItemInterface object, even in case of
-    * a cache miss. It MUST NOT return null.
-    *
-    * @param key The key for which to return the corresponding Cache Item.
-    * @throws Error If the key string is not a legal value an Error MUST be thrown.
-    * @returns The corresponding Cache Item.
-    */
-   get(key: string): Promise<ICacheItem<Data>>;
-
-   /**
-    * Returns a traversable set of cache items.
-    *
-    * @param keys An indexed array of keys of items to retrieve.
-    * @throws Error If any of the keys in keys are not a legal value an Error MUST be thrown.
-    * @returns A traversable collection of Cache Items keyed by the cache keys of
-    *          each item. A Cache item will be returned for each key, even if that
-    *          key is not found. However, if no keys are specified then an empty
-    *          traversable MUST be returned instead.
-    */
-   getMany(keys?: string[]): Promise<Map<string, ICacheItem<Data>>>;
-
-   /**
-    * Confirms if the cache contains specified cache item.
-    *
-    * Note: This method MAY avoid retrieving the cached value for performance reasons.
-    * This could result in a race condition with CacheItemInterface.get(). To avoid
-    * such situation use CacheItemInterface.isHit() instead.
-    *
-    * @param key The key for which to check existence.
-    * @throws Error If the key string is not a legal value an Error MUST be thrown.
-    * @returns True if item exists in the cache, false otherwise.
-    */
-   has(key: string): Promise<boolean>;
-
-   /**
-    * Deletes all items in the pool.
-    * @returns True if the pool was successfully cleared. False if there was an error.
-    */
-   clear(): Promise<boolean>;
-
-   /**
-    * Removes the item from the pool.
-    *
-    * @param key The key to delete.
-    * @throws Error If the key string is not a legal value an Error MUST be thrown.
-    * @returns True if the item was successfully removed. False if there was an error.
-    */
-   delete(key: string): Promise<boolean>;
-
-   /**
-    * Removes multiple items from the pool.
-    *
-    * @param keys An array of keys that should be removed from the pool.
-    * @throws Error If any of the keys in keys are not a legal value an Error MUST be thrown.
-    * @returns True if the items were successfully removed. False if there was an error.
-    */
-   deleteMany(keys: string[]): Promise<boolean>;
-
-   /**
-    * Persists a cache item immediately.
-    *
-    * @param item The cache item to save.
-    * @returns True if the item was successfully persisted. False if there was an error.
-    */
-   save(item: ICacheItem<Data>): Promise<boolean>;
-
-   /**
-    * Persists any deferred cache items.
-    * @returns True if all not-yet-saved items were successfully saved or there were none. False otherwise.
-    */
-   put(
-      key: string,
-      value: any,
-      options?: { expiresAt?: Date; metadata?: Record<string, string> },
-   ): Promise<boolean>;
-   put(
-      key: string,
-      value: any,
-      options?: { ttl?: number; metadata?: Record<string, string> },
-   ): Promise<boolean>;
-   put(
-      key: string,
-      value: any,
-      options?: ({ ttl?: number } | { expiresAt?: Date }) & { metadata?: Record<string, string> },
-   ): Promise<boolean>;
-}

app/src/core/console.ts

@@ -65,27 +65,53 @@ function __tty(_type: any, args: any[]) {
 }
 
 export type TConsoleSeverity = keyof typeof __consoles;
-const level = env("cli_log_level", "log");
+declare global {
+   var __consoleConfig:
+      | {
+           level: TConsoleSeverity;
+           id?: string;
+        }
+      | undefined;
+}
+
+// Ensure the config exists only once globally
+const defaultLevel = env("cli_log_level", "log") as TConsoleSeverity;
+
+// biome-ignore lint/suspicious/noAssignInExpressions: <explanation>
+const config = (globalThis.__consoleConfig ??= {
+   level: defaultLevel,
+   //id: crypto.randomUUID(), // for debugging
+});
 
 const keys = Object.keys(__consoles);
-export const $console = new Proxy(
+export const $console = new Proxy(config as any, {
-   {},
+   get: (_, prop) => {
-   {
+      switch (prop) {
-      get: (_, prop) => {
+         case "original":
-         if (prop === "original") {
             return console;
-         }
+         case "setLevel":
+            return (l: TConsoleSeverity) => {
+               config.level = l;
+            };
+         case "resetLevel":
+            return () => {
+               config.level = defaultLevel;
+            };
+      }
 
-         const current = keys.indexOf(level as string);
+      const current = keys.indexOf(config.level);
-         const requested = keys.indexOf(prop as string);
+      const requested = keys.indexOf(prop as string);
-         if (prop in __consoles && requested <= current) {
+
-            return (...args: any[]) => __tty(prop, args);
+      if (prop in __consoles && requested <= current) {
-         }
+         return (...args: any[]) => __tty(prop, args);
-         return () => null;
+      }
-      },
+      return () => null;
    },
-) as typeof console & {
+}) as typeof console & {
    original: typeof console;
+} & {
+   setLevel: (l: TConsoleSeverity) => void;
+   resetLevel: () => void;
 };
 
 export function colorizeConsole(con: typeof console) {

app/src/core/events/EventManager.ts

@@ -22,6 +22,7 @@ export class EventManager<
    protected events: EventClass[] = [];
    protected listeners: EventListener[] = [];
    enabled: boolean = true;
+   protected asyncs: (() => Promise<void>)[] = [];
 
    constructor(
       events?: RegisteredEvents,
@@ -29,7 +30,6 @@ export class EventManager<
          listeners?: EventListener[];
          onError?: (event: Event, e: unknown) => void;
          onInvalidReturn?: (event: Event, e: InvalidEventReturn) => void;
-         asyncExecutor?: typeof Promise.all;
       },
    ) {
       if (events) {
@@ -176,9 +176,15 @@ export class EventManager<
       this.events.forEach((event) => this.onEvent(event, handler, config));
    }
 
-   protected executeAsyncs(promises: (() => Promise<void>)[]) {
+   protected collectAsyncs(promises: (() => Promise<void>)[]) {
-      const executor = this.options?.asyncExecutor ?? ((e) => Promise.all(e));
+      this.asyncs.push(...promises);
-      executor(promises.map((p) => p())).then(() => void 0);
+   }
+
+   async executeAsyncs(executor: typeof Promise.all = (e) => Promise.all(e)): Promise<void> {
+      if (this.asyncs.length === 0) return;
+      const asyncs = [...this.asyncs];
+      this.asyncs = [];
+      await executor(asyncs.map((p) => p()));
    }
 
    async emit<Actual extends Event<any, any>>(event: Actual): Promise<Actual> {
@@ -209,8 +215,8 @@ export class EventManager<
          return !listener.once;
       });
 
-      // execute asyncs
+      // collect asyncs
-      this.executeAsyncs(asyncs);
+      this.collectAsyncs(asyncs);
 
       // execute syncs
       let _event: Actual = event;

app/src/core/test/index.ts

@@ -0,0 +1,51 @@
+export type Matcher<T = unknown> = {
+   toEqual: (expected: T, failMsg?: string) => void;
+   toBe: (expected: T, failMsg?: string) => void;
+   toBeUndefined: (failMsg?: string) => void;
+   toBeString: (failMsg?: string) => void;
+   toBeOneOf: (expected: T | Array<T> | Iterable<T>, failMsg?: string) => void;
+   toBeDefined: (failMsg?: string) => void;
+   toHaveBeenCalled: (failMsg?: string) => void;
+   toHaveBeenCalledTimes: (expected: number, failMsg?: string) => void;
+};
+export type TestFn = (() => void | Promise<unknown>) | ((done: (err?: unknown) => void) => void);
+export interface Test {
+   (label: string, fn: TestFn, options?: any): void;
+   if: (condition: boolean) => (label: string, fn: TestFn, options?: any) => void;
+   skip: (label: string, fn: () => void) => void;
+   skipIf: (condition: boolean) => (label: string, fn: TestFn) => void;
+}
+export type TestRunner = {
+   test: Test;
+   mock: <T extends (...args: any[]) => any>(fn: T) => T | any;
+   expect: <T = unknown>(
+      actual?: T,
+      failMsg?: string,
+   ) => Matcher<T> & {
+      resolves: Matcher<Awaited<T>>;
+      rejects: Matcher<Awaited<T>>;
+   };
+};
+
+export async function retry<T>(
+   fn: () => Promise<T>,
+   condition: (result: T) => boolean,
+   retries: number,
+   delay: number,
+): Promise<T> {
+   let lastError: Error | null = null;
+   for (let i = 0; i < retries; i++) {
+      try {
+         const result = await fn();
+         if (condition(result)) {
+            return result;
+         } else {
+            await new Promise((resolve) => setTimeout(resolve, delay));
+         }
+      } catch (error) {
+         lastError = error as Error;
+         await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+   }
+   throw lastError;
+}

app/src/core/utils/file.ts

@@ -0,0 +1,239 @@
+import { extension, guess, isMimeType } from "media/storage/mime-types-tiny";
+import { randomString } from "core/utils/strings";
+import type { Context } from "hono";
+import { invariant } from "core/utils/runtime";
+
+export function getContentName(request: Request): string | undefined;
+export function getContentName(contentDisposition: string): string | undefined;
+export function getContentName(headers: Headers): string | undefined;
+export function getContentName(ctx: Headers | Request | string): string | undefined {
+   let c: string = "";
+
+   if (typeof ctx === "string") {
+      c = ctx;
+   } else if (ctx instanceof Headers) {
+      c = ctx.get("Content-Disposition") || "";
+   } else if (ctx instanceof Request) {
+      c = ctx.headers.get("Content-Disposition") || "";
+   }
+
+   const match = c.match(/filename\*?=(?:UTF-8'')?("?)([^";]+)\1/);
+   return match ? match[2] : undefined;
+}
+
+export function isReadableStream(value: unknown): value is ReadableStream {
+   return (
+      typeof value === "object" &&
+      value !== null &&
+      typeof (value as ReadableStream).getReader === "function"
+   );
+}
+
+export function isBlob(value: unknown): value is Blob {
+   return (
+      typeof value === "object" &&
+      value !== null &&
+      typeof (value as Blob).arrayBuffer === "function" &&
+      typeof (value as Blob).type === "string"
+   );
+}
+
+export function isFile(value: unknown): value is File {
+   return (
+      isBlob(value) &&
+      typeof (value as File).name === "string" &&
+      typeof (value as File).lastModified === "number"
+   );
+}
+
+export function isArrayBuffer(value: unknown): value is ArrayBuffer {
+   return (
+      typeof value === "object" &&
+      value !== null &&
+      Object.prototype.toString.call(value) === "[object ArrayBuffer]"
+   );
+}
+
+export function isArrayBufferView(value: unknown): value is ArrayBufferView {
+   return typeof value === "object" && value !== null && ArrayBuffer.isView(value);
+}
+
+const FILE_SIGNATURES: Record<string, string> = {
+   "89504E47": "image/png",
+   FFD8FF: "image/jpeg",
+   "47494638": "image/gif",
+   "49492A00": "image/tiff", // Little Endian TIFF
+   "4D4D002A": "image/tiff", // Big Endian TIFF
+   "52494646????57454250": "image/webp", // WEBP (RIFF....WEBP)
+   "504B0304": "application/zip",
+   "25504446": "application/pdf",
+   "00000020667479706D70": "video/mp4",
+   "000001BA": "video/mpeg",
+   "000001B3": "video/mpeg",
+   "1A45DFA3": "video/webm",
+   "4F676753": "audio/ogg",
+   "494433": "audio/mpeg", // MP3 with ID3 header
+   FFF1: "audio/aac",
+   FFF9: "audio/aac",
+   "52494646????41564920": "audio/wav",
+   "52494646????57415645": "audio/wave",
+   "52494646????415550": "audio/aiff",
+};
+
+async function detectMimeType(
+   input: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | File | null,
+): Promise<string | undefined> {
+   if (!input) return;
+
+   let buffer: Uint8Array;
+
+   if (isReadableStream(input)) {
+      const reader = input.getReader();
+      const { value } = await reader.read();
+      if (!value) return;
+      buffer = new Uint8Array(value);
+   } else if (isBlob(input) || isFile(input)) {
+      buffer = new Uint8Array(await input.slice(0, 12).arrayBuffer());
+   } else if (isArrayBuffer(input)) {
+      buffer = new Uint8Array(input);
+   } else if (isArrayBufferView(input)) {
+      buffer = new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+   } else if (typeof input === "string") {
+      buffer = new TextEncoder().encode(input);
+   } else {
+      return;
+   }
+
+   const hex = Array.from(buffer.slice(0, 12))
+      .map((b) => b.toString(16).padStart(2, "0").toUpperCase())
+      .join("");
+
+   for (const [signature, mime] of Object.entries(FILE_SIGNATURES)) {
+      const regex = new RegExp("^" + signature.replace(/\?\?/g, ".."));
+      if (regex.test(hex)) return mime;
+   }
+
+   return;
+}
+
+export async function getFileFromContext(c: Context<any>): Promise<File> {
+   const contentType = c.req.header("Content-Type") ?? "application/octet-stream";
+
+   if (
+      contentType?.startsWith("multipart/form-data") ||
+      contentType?.startsWith("application/x-www-form-urlencoded")
+   ) {
+      try {
+         const f = await c.req.formData();
+         if ([...f.values()].length > 0) {
+            const v = [...f.values()][0];
+            return await blobToFile(v);
+         }
+      } catch (e) {
+         console.warn("Error parsing form data", e);
+      }
+   } else {
+      try {
+         const blob = await c.req.blob();
+         if (isFile(blob)) {
+            return blob;
+         } else if (isBlob(blob)) {
+            return await blobToFile(blob, { name: getContentName(c.req.raw), type: contentType });
+         }
+      } catch (e) {
+         console.warn("Error parsing blob", e);
+      }
+   }
+
+   throw new Error("No file found in request");
+}
+
+export async function getBodyFromContext(c: Context<any>): Promise<ReadableStream | File> {
+   const contentType = c.req.header("Content-Type") ?? "application/octet-stream";
+
+   if (
+      !contentType?.startsWith("multipart/form-data") &&
+      !contentType?.startsWith("application/x-www-form-urlencoded")
+   ) {
+      const body = c.req.raw.body;
+      if (body) {
+         return body;
+      }
+   }
+
+   return getFileFromContext(c);
+}
+
+type ImageDim = { width: number; height: number };
+export async function detectImageDimensions(
+   input: ArrayBuffer,
+   type: `image/${string}`,
+): Promise<ImageDim>;
+export async function detectImageDimensions(input: File): Promise<ImageDim>;
+export async function detectImageDimensions(
+   input: File | ArrayBuffer,
+   _type?: `image/${string}`,
+): Promise<ImageDim> {
+   // Only process images
+   const is_file = isFile(input);
+   const type = is_file ? input.type : _type!;
+
+   invariant(type && typeof type === "string" && type.startsWith("image/"), "type must be image/*");
+
+   const buffer = is_file ? await input.arrayBuffer() : input;
+   invariant(buffer.byteLength >= 128, "Buffer must be at least 128 bytes");
+
+   const dataView = new DataView(buffer);
+
+   if (type === "image/jpeg") {
+      let offset = 2;
+      while (offset < dataView.byteLength) {
+         const marker = dataView.getUint16(offset);
+         offset += 2;
+         if (marker === 0xffc0 || marker === 0xffc2) {
+            return {
+               width: dataView.getUint16(offset + 5),
+               height: dataView.getUint16(offset + 3),
+            };
+         }
+         offset += dataView.getUint16(offset);
+      }
+   } else if (type === "image/png") {
+      return {
+         width: dataView.getUint32(16),
+         height: dataView.getUint32(20),
+      };
+   } else if (type === "image/gif") {
+      return {
+         width: dataView.getUint16(6),
+         height: dataView.getUint16(8),
+      };
+   } else if (type === "image/tiff") {
+      const isLittleEndian = dataView.getUint16(0) === 0x4949;
+      const offset = dataView.getUint32(4, isLittleEndian);
+      const width = dataView.getUint32(offset + 18, isLittleEndian);
+      const height = dataView.getUint32(offset + 10, isLittleEndian);
+      return { width, height };
+   }
+
+   throw new Error("Unsupported image format");
+}
+
+export async function blobToFile(
+   blob: Blob | File | unknown,
+   overrides: FilePropertyBag & { name?: string } = {},
+): Promise<File> {
+   if (isFile(blob)) return blob;
+   if (!isBlob(blob)) throw new Error("Not a Blob");
+
+   const type = isMimeType(overrides.type, ["application/octet-stream"])
+      ? overrides.type
+      : await detectMimeType(blob);
+   const ext = type ? extension(type) : "";
+   const name = overrides.name || [randomString(16), ext].filter(Boolean).join(".");
+
+   return new File([blob], name, {
+      type: type || guess(name),
+      lastModified: Date.now(),
+   });
+}

app/src/core/utils/index.ts

@@ -2,6 +2,7 @@ export * from "./browser";
 export * from "./objects";
 export * from "./strings";
 export * from "./perf";
+export * from "./file";
 export * from "./reqres";
 export * from "./xml";
 export type { Prettify, PrettifyRec } from "./types";

app/src/core/utils/numbers.ts

@@ -11,3 +11,14 @@ export function ensureInt(value?: string | number | null | undefined): number {
 
    return typeof value === "number" ? value : Number.parseInt(value, 10);
 }
+
+export const formatNumber = {
+   fileSize: (bytes: number, decimals = 2): string => {
+      if (bytes === 0) return "0 Bytes";
+      const k = 1024;
+      const dm = decimals < 0 ? 0 : decimals;
+      const sizes = ["Bytes", "KB", "MB", "GB", "TB"];
+      const i = Math.floor(Math.log(bytes) / Math.log(k));
+      return Number.parseFloat((bytes / k ** i).toFixed(dm)) + " " + sizes[i];
+   },
+};

app/src/core/utils/reqres.ts

@@ -97,186 +97,6 @@ export function decodeSearch(str) {
    return out;
 }
 
-export function isReadableStream(value: unknown): value is ReadableStream {
-   return (
-      typeof value === "object" &&
-      value !== null &&
-      typeof (value as ReadableStream).getReader === "function"
-   );
-}
-
-export function isBlob(value: unknown): value is Blob {
-   return (
-      typeof value === "object" &&
-      value !== null &&
-      typeof (value as Blob).arrayBuffer === "function" &&
-      typeof (value as Blob).type === "string"
-   );
-}
-
-export function isFile(value: unknown): value is File {
-   return (
-      isBlob(value) &&
-      typeof (value as File).name === "string" &&
-      typeof (value as File).lastModified === "number"
-   );
-}
-
-export function isArrayBuffer(value: unknown): value is ArrayBuffer {
-   return (
-      typeof value === "object" &&
-      value !== null &&
-      Object.prototype.toString.call(value) === "[object ArrayBuffer]"
-   );
-}
-
-export function isArrayBufferView(value: unknown): value is ArrayBufferView {
-   return typeof value === "object" && value !== null && ArrayBuffer.isView(value);
-}
-
-export function getContentName(request: Request): string | undefined;
-export function getContentName(contentDisposition: string): string | undefined;
-export function getContentName(headers: Headers): string | undefined;
-export function getContentName(ctx: Headers | Request | string): string | undefined {
-   let c: string = "";
-
-   if (typeof ctx === "string") {
-      c = ctx;
-   } else if (ctx instanceof Headers) {
-      c = ctx.get("Content-Disposition") || "";
-   } else if (ctx instanceof Request) {
-      c = ctx.headers.get("Content-Disposition") || "";
-   }
-
-   const match = c.match(/filename\*?=(?:UTF-8'')?("?)([^";]+)\1/);
-   return match ? match[2] : undefined;
-}
-
-const FILE_SIGNATURES: Record<string, string> = {
-   "89504E47": "image/png",
-   FFD8FF: "image/jpeg",
-   "47494638": "image/gif",
-   "49492A00": "image/tiff", // Little Endian TIFF
-   "4D4D002A": "image/tiff", // Big Endian TIFF
-   "52494646????57454250": "image/webp", // WEBP (RIFF....WEBP)
-   "504B0304": "application/zip",
-   "25504446": "application/pdf",
-   "00000020667479706D70": "video/mp4",
-   "000001BA": "video/mpeg",
-   "000001B3": "video/mpeg",
-   "1A45DFA3": "video/webm",
-   "4F676753": "audio/ogg",
-   "494433": "audio/mpeg", // MP3 with ID3 header
-   FFF1: "audio/aac",
-   FFF9: "audio/aac",
-   "52494646????41564920": "audio/wav",
-   "52494646????57415645": "audio/wave",
-   "52494646????415550": "audio/aiff",
-};
-
-async function detectMimeType(
-   input: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | File | null,
-): Promise<string | undefined> {
-   if (!input) return;
-
-   let buffer: Uint8Array;
-
-   if (isReadableStream(input)) {
-      const reader = input.getReader();
-      const { value } = await reader.read();
-      if (!value) return;
-      buffer = new Uint8Array(value);
-   } else if (isBlob(input) || isFile(input)) {
-      buffer = new Uint8Array(await input.slice(0, 12).arrayBuffer());
-   } else if (isArrayBuffer(input)) {
-      buffer = new Uint8Array(input);
-   } else if (isArrayBufferView(input)) {
-      buffer = new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
-   } else if (typeof input === "string") {
-      buffer = new TextEncoder().encode(input);
-   } else {
-      return;
-   }
-
-   const hex = Array.from(buffer.slice(0, 12))
-      .map((b) => b.toString(16).padStart(2, "0").toUpperCase())
-      .join("");
-
-   for (const [signature, mime] of Object.entries(FILE_SIGNATURES)) {
-      const regex = new RegExp("^" + signature.replace(/\?\?/g, ".."));
-      if (regex.test(hex)) return mime;
-   }
-
-   return;
-}
-
-export async function blobToFile(
-   blob: Blob | File | unknown,
-   overrides: FilePropertyBag & { name?: string } = {},
-): Promise<File> {
-   if (isFile(blob)) return blob;
-   if (!isBlob(blob)) throw new Error("Not a Blob");
-
-   const type = isMimeType(overrides.type, ["application/octet-stream"])
-      ? overrides.type
-      : await detectMimeType(blob);
-   const ext = type ? extension(type) : "";
-   const name = overrides.name || [randomString(16), ext].filter(Boolean).join(".");
-
-   return new File([blob], name, {
-      type: type || guess(name),
-      lastModified: Date.now(),
-   });
-}
-
-export async function getFileFromContext(c: Context<any>): Promise<File> {
-   const contentType = c.req.header("Content-Type") ?? "application/octet-stream";
-
-   if (
-      contentType?.startsWith("multipart/form-data") ||
-      contentType?.startsWith("application/x-www-form-urlencoded")
-   ) {
-      try {
-         const f = await c.req.formData();
-         if ([...f.values()].length > 0) {
-            const v = [...f.values()][0];
-            return await blobToFile(v);
-         }
-      } catch (e) {
-         console.warn("Error parsing form data", e);
-      }
-   } else {
-      try {
-         const blob = await c.req.blob();
-         if (isFile(blob)) {
-            return blob;
-         } else if (isBlob(blob)) {
-            return await blobToFile(blob, { name: getContentName(c.req.raw), type: contentType });
-         }
-      } catch (e) {
-         console.warn("Error parsing blob", e);
-      }
-   }
-
-   throw new Error("No file found in request");
-}
-
-export async function getBodyFromContext(c: Context<any>): Promise<ReadableStream | File> {
-   const contentType = c.req.header("Content-Type") ?? "application/octet-stream";
-
-   if (
-      !contentType?.startsWith("multipart/form-data") &&
-      !contentType?.startsWith("application/x-www-form-urlencoded")
-   ) {
-      const body = c.req.raw.body;
-      if (body) {
-         return body;
-      }
-   }
-
-   return getFileFromContext(c);
-}
-
 // https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
 // biome-ignore lint/suspicious/noConstEnum: <explanation>
 export const enum HttpStatus {

app/src/core/utils/runtime.ts

@@ -47,3 +47,9 @@ export function isNode() {
       return false;
    }
 }
+
+export function invariant(condition: boolean | any, message: string) {
+   if (!condition) {
+      throw new Error(message);
+   }
+}

app/src/core/utils/test.ts

@@ -1,3 +1,5 @@
+import { $console } from "core";
+
 type ConsoleSeverity = "log" | "warn" | "error";
 const _oldConsoles = {
    log: console.log,
@@ -34,21 +36,14 @@ export function disableConsoleLog(severities: ConsoleSeverity[] = ["log", "warn"
    severities.forEach((severity) => {
       console[severity] = () => null;
    });
-   return enableConsoleLog;
+   $console.setLevel("error");
 }
 
 export function enableConsoleLog() {
    Object.entries(_oldConsoles).forEach(([severity, fn]) => {
       console[severity as ConsoleSeverity] = fn;
    });
-}
+   $console.resetLevel();
-
-export function tryit(fn: () => void, fallback?: any) {
-   try {
-      return fn();
-   } catch (e) {
-      return fallback || e;
-   }
 }
 
 export function formatMemoryUsage() {