feat: introduce new modes helpers

app/src/App.ts

@@ -385,6 +385,7 @@ export class App<
             }
          }
       }
+      await this.options?.manager?.onModulesBuilt?.(ctx);
    }
 }
 

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

@@ -8,12 +8,15 @@ export type AstroBkndConfig<Env = AstroEnv> = FrameworkBkndConfig<Env>;
 
 export async function getApp<Env = AstroEnv>(
    config: AstroBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = import.meta.env as Env,
 ) {
-   return await createFrameworkApp(config, args ?? import.meta.env);
+   return await createFrameworkApp(config, args);
 }
 
-export function serve<Env = AstroEnv>(config: AstroBkndConfig<Env> = {}, args: Env = {} as Env) {
+export function serve<Env = AstroEnv>(
+   config: AstroBkndConfig<Env> = {},
+   args: Env = import.meta.env as Env,
+) {
    return async (fnArgs: TAstro) => {
       return (await getApp(config, args)).fetch(fnArgs.request);
    };

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

@@ -12,7 +12,7 @@ export type BunBkndConfig<Env = BunEnv> = RuntimeBkndConfig<Env> & Omit<ServeOpt
 
 export async function createApp<Env = BunEnv>(
    { distPath, serveStatic: _serveStatic, ...config }: BunBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = Bun.env as Env,
 ) {
    const root = path.resolve(distPath ?? "./node_modules/bknd/dist", "static");
    registerLocalMediaAdapter();
@@ -26,18 +26,18 @@ export async function createApp<Env = BunEnv>(
             }),
          ...config,
       },
-      args ?? (process.env as Env),
+      args,
    );
 }
 
 export function createHandler<Env = BunEnv>(
    config: BunBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = Bun.env as Env,
 ) {
    let app: App | undefined;
    return async (req: Request) => {
       if (!app) {
-         app = await createApp(config, args ?? (process.env as Env));
+         app = await createApp(config, args);
       }
       return app.fetch(req);
    };
@@ -54,9 +54,10 @@ export function serve<Env = BunEnv>(
       buildConfig,
       adminOptions,
       serveStatic,
+      beforeBuild,
       ...serveOptions
    }: BunBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = Bun.env as Env,
 ) {
    Bun.serve({
       ...serveOptions,
@@ -71,6 +72,7 @@ export function serve<Env = BunEnv>(
             adminOptions,
             distPath,
             serveStatic,
+            beforeBuild,
          },
          args,
       ),

app/src/adapter/bun/index.ts

@@ -1,3 +1,11 @@
 export * from "./bun.adapter";
 export * from "../node/storage";
 export * from "./connection/BunSqliteConnection";
+
+export async function writer(path: string, content: string) {
+   await Bun.write(path, content);
+}
+
+export async function reader(path: string) {
+   return await Bun.file(path).text();
+}

app/src/adapter/index.ts

@@ -6,18 +6,23 @@ import {
    guessMimeType,
    type MaybePromise,
    registries as $registries,
+   type Merge,
 } from "bknd";
 import { $console } from "bknd/utils";
 import type { Context, MiddlewareHandler, Next } from "hono";
 import type { AdminControllerOptions } from "modules/server/AdminController";
 import type { Manifest } from "vite";
 
-export type BkndConfig<Args = any> = CreateAppConfig & {
+export type BkndConfig<Args = any, Additional = {}> = Merge<
-   app?: Omit<BkndConfig, "app"> | ((args: Args) => MaybePromise<Omit<BkndConfig<Args>, "app">>);
+   CreateAppConfig & {
+      app?:
+         | Merge<Omit<BkndConfig, "app"> & Additional>
+         | ((args: Args) => MaybePromise<Merge<Omit<BkndConfig<Args>, "app"> & Additional>>);
       onBuilt?: (app: App) => MaybePromise<void>;
       beforeBuild?: (app?: App, registries?: typeof $registries) => MaybePromise<void>;
       buildConfig?: Parameters<App["build"]>[0];
-};
+   } & Additional
+>;
 
 export type FrameworkBkndConfig<Args = any> = BkndConfig<Args>;
 
@@ -51,11 +56,10 @@ export async function makeConfig<Args = DefaultArgs>(
    return { ...rest, ...additionalConfig };
 }
 
-// a map that contains all apps by id
 export async function createAdapterApp<Config extends BkndConfig = BkndConfig, Args = DefaultArgs>(
    config: Config = {} as Config,
    args?: Args,
-): Promise<App> {
+): Promise<{ app: App; config: BkndConfig<Args> }> {
    await config.beforeBuild?.(undefined, $registries);
 
    const appConfig = await makeConfig(config, args);
@@ -65,34 +69,37 @@ export async function createAdapterApp<Config extends BkndConfig = BkndConfig, A
          connection = config.connection;
       } else {
          const sqlite = (await import("bknd/adapter/sqlite")).sqlite;
-         const conf = appConfig.connection ?? { url: ":memory:" };
+         const conf = appConfig.connection ?? { url: "file:data.db" };
          connection = sqlite(conf) as any;
          $console.info(`Using ${connection!.name} connection`, conf.url);
       }
       appConfig.connection = connection;
    }
 
-   return App.create(appConfig);
+   return {
+      app: App.create(appConfig),
+      config: appConfig,
+   };
 }
 
 export async function createFrameworkApp<Args = DefaultArgs>(
    config: FrameworkBkndConfig = {},
    args?: Args,
 ): Promise<App> {
-   const app = await createAdapterApp(config, args);
+   const { app, config: appConfig } = await createAdapterApp(config, args);
 
    if (!app.isBuilt()) {
       if (config.onBuilt) {
          app.emgr.onEvent(
             App.Events.AppBuiltEvent,
             async () => {
-               await config.onBuilt?.(app);
+               await appConfig.onBuilt?.(app);
             },
             "sync",
          );
       }
 
-      await config.beforeBuild?.(app, $registries);
+      await appConfig.beforeBuild?.(app, $registries);
       await app.build(config.buildConfig);
    }
 
@@ -103,7 +110,7 @@ export async function createRuntimeApp<Args = DefaultArgs>(
    { serveStatic, adminOptions, ...config }: RuntimeBkndConfig<Args> = {},
    args?: Args,
 ): Promise<App> {
-   const app = await createAdapterApp(config, args);
+   const { app, config: appConfig } = await createAdapterApp(config, args);
 
    if (!app.isBuilt()) {
       app.emgr.onEvent(
@@ -116,7 +123,7 @@ export async function createRuntimeApp<Args = DefaultArgs>(
                app.modules.server.get(path, handler);
             }
 
-            await config.onBuilt?.(app);
+            await appConfig.onBuilt?.(app);
             if (adminOptions !== false) {
                app.registerAdminController(adminOptions);
             }
@@ -124,7 +131,7 @@ export async function createRuntimeApp<Args = DefaultArgs>(
          "sync",
       );
 
-      await config.beforeBuild?.(app, $registries);
+      await appConfig.beforeBuild?.(app, $registries);
       await app.build(config.buildConfig);
    }
 

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

@@ -9,9 +9,9 @@ export type NextjsBkndConfig<Env = NextjsEnv> = FrameworkBkndConfig<Env> & {
 
 export async function getApp<Env = NextjsEnv>(
    config: NextjsBkndConfig<Env>,
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
-   return await createFrameworkApp(config, args ?? (process.env as Env));
+   return await createFrameworkApp(config, args);
 }
 
 function getCleanRequest(req: Request, cleanRequest: NextjsBkndConfig["cleanRequest"]) {
@@ -39,7 +39,7 @@ function getCleanRequest(req: Request, cleanRequest: NextjsBkndConfig["cleanRequ
 
 export function serve<Env = NextjsEnv>(
    { cleanRequest, ...config }: NextjsBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
    return async (req: Request) => {
       const app = await getApp(config, args);

app/src/adapter/node/index.ts

@@ -1,3 +1,13 @@
+import { readFile, writeFile } from "node:fs/promises";
+
 export * from "./node.adapter";
 export * from "./storage";
 export * from "./connection/NodeSqliteConnection";
+
+export async function writer(path: string, content: string) {
+   await writeFile(path, content);
+}
+
+export async function reader(path: string) {
+   return await readFile(path, "utf-8");
+}

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

@@ -17,7 +17,7 @@ export type NodeBkndConfig<Env = NodeEnv> = RuntimeBkndConfig<Env> & {
 
 export async function createApp<Env = NodeEnv>(
    { distPath, relativeDistPath, ...config }: NodeBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
    const root = path.relative(
       process.cwd(),
@@ -33,19 +33,18 @@ export async function createApp<Env = NodeEnv>(
          serveStatic: serveStatic({ root }),
          ...config,
       },
-      // @ts-ignore
+      args,
-      args ?? { env: process.env },
    );
 }
 
 export function createHandler<Env = NodeEnv>(
    config: NodeBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
    let app: App | undefined;
    return async (req: Request) => {
       if (!app) {
-         app = await createApp(config, args ?? (process.env as Env));
+         app = await createApp(config, args);
       }
       return app.fetch(req);
    };
@@ -53,7 +52,7 @@ export function createHandler<Env = NodeEnv>(
 
 export function serve<Env = NodeEnv>(
    { port = $config.server.default_port, hostname, listener, ...config }: NodeBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
    honoServe(
       {

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

@@ -8,14 +8,14 @@ export type ReactRouterBkndConfig<Env = ReactRouterEnv> = FrameworkBkndConfig<En
 
 export async function getApp<Env = ReactRouterEnv>(
    config: ReactRouterBkndConfig<Env>,
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
-   return await createFrameworkApp(config, args ?? process.env);
+   return await createFrameworkApp(config, args);
 }
 
 export function serve<Env = ReactRouterEnv>(
    config: ReactRouterBkndConfig<Env> = {},
-   args: Env = {} as Env,
+   args: Env = process.env as Env,
 ) {
    return async (fnArgs: ReactRouterFunctionArgs) => {
       return (await getApp(config, args)).fetch(fnArgs.request);

app/src/core/types.ts

@@ -6,3 +6,7 @@ export interface Serializable<Class, Json extends object = object> {
 export type MaybePromise<T> = T | Promise<T>;
 
 export type PartialRec<T> = { [P in keyof T]?: PartialRec<T[P]> };
+
+export type Merge<T> = {
+   [K in keyof T]: T[K];
+};

app/src/index.ts

@@ -41,7 +41,7 @@ export { getSystemMcp } from "modules/mcp/system-mcp";
 /**
  * Core
  */
-export type { MaybePromise } from "core/types";
+export type { MaybePromise, Merge } from "core/types";
 export { Exception, BkndError } from "core/errors";
 export { isDebug, env } from "core/env";
 export { type PrimaryFieldType, config, type DB, type AppEntity } from "core/config";

app/src/modes/code.ts

@@ -0,0 +1,49 @@
+import type { BkndConfig } from "bknd/adapter";
+import { makeModeConfig, type BkndModeConfig } from "./shared";
+import { $console } from "bknd/utils";
+
+export type BkndCodeModeConfig<Args = any> = BkndModeConfig<Args>;
+
+export type CodeMode<AdapterConfig extends BkndConfig> = AdapterConfig extends BkndConfig<
+   infer Args
+>
+   ? BkndModeConfig<Args, AdapterConfig>
+   : never;
+
+export function code<Args>(config: BkndCodeModeConfig<Args>): BkndConfig<Args> {
+   return {
+      ...config,
+      app: async (args) => {
+         const {
+            config: appConfig,
+            plugins,
+            isProd,
+            syncSchemaOptions,
+         } = await makeModeConfig(config, args);
+
+         if (appConfig?.options?.mode && appConfig?.options?.mode !== "code") {
+            $console.warn("You should not set a different mode than `db` when using code mode");
+         }
+
+         return {
+            ...appConfig,
+            options: {
+               ...appConfig?.options,
+               mode: "code",
+               plugins,
+               manager: {
+                  // skip validation in prod for a speed boost
+                  skipValidation: isProd,
+                  onModulesBuilt: async (ctx) => {
+                     if (!isProd && syncSchemaOptions.force) {
+                        $console.log("[code] syncing schema");
+                        await ctx.em.schema().sync(syncSchemaOptions);
+                     }
+                  },
+                  ...appConfig?.options?.manager,
+               },
+            },
+         };
+      },
+   };
+}

app/src/modes/hybrid.ts

@@ -0,0 +1,88 @@
+import type { BkndConfig } from "bknd/adapter";
+import { makeModeConfig, type BkndModeConfig } from "./shared";
+import { getDefaultConfig, type MaybePromise, type ModuleConfigs, type Merge } from "bknd";
+import type { DbModuleManager } from "modules/db/DbModuleManager";
+import { invariant, $console } from "bknd/utils";
+
+export type BkndHybridModeOptions = {
+   /**
+    * Reader function to read the configuration from the file system.
+    * This is required for hybrid mode to work.
+    */
+   reader?: (path: string) => MaybePromise<string>;
+   /**
+    * Provided secrets to be merged into the configuration
+    */
+   secrets?: Record<string, any>;
+};
+
+export type HybridBkndConfig<Args = any> = BkndModeConfig<Args, BkndHybridModeOptions>;
+export type HybridMode<AdapterConfig extends BkndConfig> = AdapterConfig extends BkndConfig<
+   infer Args
+>
+   ? BkndModeConfig<Args, Merge<BkndHybridModeOptions & AdapterConfig>>
+   : never;
+
+export function hybrid<Args>({
+   configFilePath = "bknd-config.json",
+   ...rest
+}: HybridBkndConfig<Args>): BkndConfig<Args> {
+   return {
+      ...rest,
+      config: undefined,
+      app: async (args) => {
+         const {
+            config: appConfig,
+            isProd,
+            plugins,
+            syncSchemaOptions,
+         } = await makeModeConfig(
+            {
+               ...rest,
+               configFilePath,
+            },
+            args,
+         );
+
+         if (appConfig?.options?.mode && appConfig?.options?.mode !== "db") {
+            $console.warn("You should not set a different mode than `db` when using hybrid mode");
+         }
+         invariant(
+            typeof appConfig.reader === "function",
+            "You must set the `reader` option when using hybrid mode",
+         );
+
+         let fileConfig: ModuleConfigs;
+         try {
+            fileConfig = JSON.parse(await appConfig.reader!(configFilePath)) as ModuleConfigs;
+         } catch (e) {
+            const defaultConfig = (appConfig.config ?? getDefaultConfig()) as ModuleConfigs;
+            await appConfig.writer!(configFilePath, JSON.stringify(defaultConfig, null, 2));
+            fileConfig = defaultConfig;
+         }
+
+         return {
+            ...(appConfig as any),
+            beforeBuild: async (app) => {
+               if (app && !isProd) {
+                  const mm = app.modules as DbModuleManager;
+                  mm.buildSyncConfig = syncSchemaOptions;
+               }
+            },
+            config: fileConfig,
+            options: {
+               ...appConfig?.options,
+               mode: isProd ? "code" : "db",
+               plugins,
+               manager: {
+                  // skip validation in prod for a speed boost
+                  skipValidation: isProd,
+                  // secrets are required for hybrid mode
+                  secrets: appConfig.secrets,
+                  ...appConfig?.options?.manager,
+               },
+            },
+         };
+      },
+   };
+}

app/src/modes/index.ts

@@ -0,0 +1,3 @@
+export * from "./code";
+export * from "./hybrid";
+export * from "./shared";

app/src/modes/shared.ts

@@ -0,0 +1,183 @@
+import type { AppPlugin, BkndConfig, MaybePromise, Merge } from "bknd";
+import { syncTypes, syncConfig } from "bknd/plugins";
+import { syncSecrets } from "plugins/dev/sync-secrets.plugin";
+import { invariant, $console } from "bknd/utils";
+
+export type BkndModeOptions = {
+   /**
+    * Whether the application is running in production.
+    */
+   isProduction?: boolean;
+   /**
+    * Writer function to write the configuration to the file system
+    */
+   writer?: (path: string, content: string) => MaybePromise<void>;
+   /**
+    * Configuration file path
+    */
+   configFilePath?: string;
+   /**
+    * Types file path
+    * @default "bknd-types.d.ts"
+    */
+   typesFilePath?: string;
+   /**
+    * Syncing secrets options
+    */
+   syncSecrets?: {
+      /**
+       * Whether to enable syncing secrets
+       */
+      enabled?: boolean;
+      /**
+       * Output file path
+       */
+      outFile?: string;
+      /**
+       * Format of the output file
+       * @default "env"
+       */
+      format?: "json" | "env";
+      /**
+       * Whether to include secrets in the output file
+       * @default false
+       */
+      includeSecrets?: boolean;
+   };
+   /**
+    * Determines whether to automatically sync the schema if not in production.
+    * @default true
+    */
+   syncSchema?: boolean | { force?: boolean; drop?: boolean };
+};
+
+export type BkndModeConfig<Args = any, Additional = {}> = BkndConfig<
+   Args,
+   Merge<BkndModeOptions & Additional>
+>;
+
+export async function makeModeConfig<
+   Args = any,
+   Config extends BkndModeConfig<Args> = BkndModeConfig<Args>,
+>(_config: Config, args: Args) {
+   const appConfig = typeof _config.app === "function" ? await _config.app(args) : _config.app;
+
+   const config = {
+      ..._config,
+      ...appConfig,
+   } as Omit<Config, "app">;
+
+   if (typeof config.isProduction !== "boolean") {
+      $console.warn(
+         "You should set `isProduction` option when using managed modes to prevent accidental issues",
+      );
+   }
+
+   invariant(
+      typeof config.writer === "function",
+      "You must set the `writer` option when using managed modes",
+   );
+
+   const { typesFilePath, configFilePath, writer, syncSecrets: syncSecretsOptions } = config;
+
+   const isProd = config.isProduction;
+   const plugins = appConfig?.options?.plugins ?? ([] as AppPlugin[]);
+   const syncSchemaOptions =
+      typeof config.syncSchema === "object"
+         ? config.syncSchema
+         : {
+              force: config.syncSchema !== false,
+              drop: true,
+           };
+
+   if (!isProd) {
+      if (typesFilePath) {
+         if (plugins.some((p) => p.name === "bknd-sync-types")) {
+            throw new Error("You have to unregister the `syncTypes` plugin");
+         }
+         plugins.push(
+            syncTypes({
+               enabled: true,
+               includeFirstBoot: true,
+               write: async (et) => {
+                  try {
+                     await config.writer?.(typesFilePath, et.toString());
+                  } catch (e) {
+                     console.error(`Error writing types to"${typesFilePath}"`, e);
+                  }
+               },
+            }) as any,
+         );
+      }
+
+      if (configFilePath) {
+         if (plugins.some((p) => p.name === "bknd-sync-config")) {
+            throw new Error("You have to unregister the `syncConfig` plugin");
+         }
+         plugins.push(
+            syncConfig({
+               enabled: true,
+               includeFirstBoot: true,
+               write: async (config) => {
+                  try {
+                     await writer?.(configFilePath, JSON.stringify(config, null, 2));
+                  } catch (e) {
+                     console.error(`Error writing config to "${configFilePath}"`, e);
+                  }
+               },
+            }) as any,
+         );
+      }
+
+      if (syncSecretsOptions?.enabled) {
+         if (plugins.some((p) => p.name === "bknd-sync-secrets")) {
+            throw new Error("You have to unregister the `syncSecrets` plugin");
+         }
+
+         let outFile = syncSecretsOptions.outFile;
+         const format = syncSecretsOptions.format ?? "env";
+         if (!outFile) {
+            outFile = ["env", !syncSecretsOptions.includeSecrets && "example", format]
+               .filter(Boolean)
+               .join(".");
+         }
+
+         plugins.push(
+            syncSecrets({
+               enabled: true,
+               includeFirstBoot: true,
+               write: async (secrets) => {
+                  const values = Object.fromEntries(
+                     Object.entries(secrets).map(([key, value]) => [
+                        key,
+                        syncSecretsOptions.includeSecrets ? value : "",
+                     ]),
+                  );
+
+                  try {
+                     if (format === "env") {
+                        await writer?.(
+                           outFile,
+                           Object.entries(values)
+                              .map(([key, value]) => `${key}=${value}`)
+                              .join("\n"),
+                        );
+                     } else {
+                        await writer?.(outFile, JSON.stringify(values, null, 2));
+                     }
+                  } catch (e) {
+                     console.error(`Error writing secrets to "${outFile}"`, e);
+                  }
+               },
+            }) as any,
+         );
+      }
+   }
+
+   return {
+      config,
+      isProd,
+      plugins,
+      syncSchemaOptions,
+   };
+}

app/src/modules/db/DbModuleManager.ts

@@ -70,6 +70,9 @@ export class DbModuleManager extends ModuleManager {
    private readonly _booted_with?: "provided" | "partial";
    private _stable_configs: ModuleConfigs | undefined;
 
+   // config used when syncing database
+   public buildSyncConfig: { force?: boolean; drop?: boolean } = { force: true };
+
    constructor(connection: Connection, options?: Partial<ModuleManagerOptions>) {
       let initial = {} as InitialModuleConfigs;
       let booted_with = "partial" as any;
@@ -393,7 +396,7 @@ export class DbModuleManager extends ModuleManager {
 
                const version_before = this.version();
                const [_version, _configs] = await migrate(version_before, result.configs.json, {
-                  db: this.db
+                  db: this.db,
                });
 
                this._version = _version;
@@ -463,7 +466,7 @@ export class DbModuleManager extends ModuleManager {
             this.logger.log("db sync requested");
 
             // sync db
-            await ctx.em.schema().sync({ force: true });
+            await ctx.em.schema().sync(this.buildSyncConfig);
             state.synced = true;
 
             // save

app/tsconfig.json

@@ -33,7 +33,9 @@
       "bknd": ["./src/index.ts"],
       "bknd/utils": ["./src/core/utils/index.ts"],
       "bknd/adapter": ["./src/adapter/index.ts"],
-      "bknd/client": ["./src/ui/client/index.ts"]
+      "bknd/adapter/*": ["./src/adapter/*/index.ts"],
+      "bknd/client": ["./src/ui/client/index.ts"],
+      "bknd/modes": ["./src/modes/index.ts"]
     }
   },
   "include": [