@ubean/app 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+import { Context, Hono, MiddlewareHandler, Next } from "hono";
+import { RegisterOptions, RouteRegistrar } from "@ubean/api-routes";
+import { Hookable } from "hookable";
+import { ScannedApiRoute, ScannedApiRoute as ScannedApiRoute$1, ScannedCronTask, ScannedLayout, ScannedLayout as ScannedLayout$1, ScannedMiddleware, ScannedMiddleware as ScannedMiddleware$1, ScannedPageRoute, ScannedPageRoute as ScannedPageRoute$1 } from "@ubean/routing";
+import { ComposedHandler, ComposedHandler as ComposedHandler$1, RouteMeta, RouteMeta as RouteMeta$1, RouteRule, RouteRule as RouteRule$1, UbeanEnv, UbeanEnv as UbeanEnv$1, UbeanMiddleware, UbeanMiddleware as UbeanMiddleware$1 } from "@ubean/types";
+//#region src/define-server.d.ts
+/**
+ * Apply a resolved server config to a `UbeanApp` instance.
+ *
+ * This must be called BEFORE `app.init()` so that:
+ * - `plugins` are available when `init()` calls `setup` / `ready`
+ * - `hooks` are registered before `init()` fires `app:created` etc.
+ * - `onAppCreate` runs before route registration
+ *
+ * `onServerReady` is NOT called here — the caller must invoke it after
+ * `app.init()` completes.
+ */
+declare function applyServerConfig(app: UbeanApp, config: ResolvedServerConfig): Promise<void>;
+/**
+ * Partial runtime hooks that users can register via `defineServer`.
+ * All hooks are optional — users only declare the ones they need.
+ */
+type ServerHooks = Partial<UbeanRuntimeHooks>;
+/**
+ * Options for `defineServer` — the server-side counterpart of `defineApp`.
+ *
+ * Users create `src/server.ts` (shared), `src/server.dev.ts` (dev-only),
+ * or `src/server.prod.ts` (prod-only) and export the result of
+ * `defineServer(...)` as the default export.
+ */
+interface DefineServerOptions {
+  /**
+   * UbeanApp plugins to inject into `createUbeanApp({ plugins })`.
+   * Each plugin's `setup` runs before route registration; `ready` runs after.
+   */
+  plugins?: UbeanAppPlugin[];
+  /**
+   * Runtime hooks registered on `app.hooks`.
+   * Available hooks: `app:created`, `app:before:register`, `app:after:register`,
+   * `request:start`, `request:end`, `request:error`, `route:register`,
+   * `middleware:register`, `error`.
+   */
+  hooks?: ServerHooks;
+  /**
+   * Called after `UbeanApp` is created but before `app.init()`.
+   * Useful for initializing databases, external service connections, etc.
+   */
+  onAppCreate?: (app: UbeanApp) => void | Promise<void>;
+  /**
+   * Called after `app.init()` completes (all routes/middleware registered).
+   * Useful for starting queue workers, cron schedulers, etc.
+   */
+  onServerReady?: (app: UbeanApp) => void | Promise<void>;
+}
+/**
+ * Resolved server config — the normalized result of `defineServer`.
+ */
+interface ResolvedServerConfig {
+  plugins: UbeanAppPlugin[];
+  hooks: ServerHooks;
+  onAppCreate?: (app: UbeanApp) => void | Promise<void>;
+  onServerReady?: (app: UbeanApp) => void | Promise<void>;
+}
+/**
+ * Define the backend server configuration.
+ *
+ * This is the server-side counterpart of `defineApp`. It allows users to
+ * inject plugins, register runtime hooks, and run startup/ready logic
+ * from a simple entry file (`src/server.ts`).
+ *
+ * @example
+ * ```ts
+ * // src/server.ts
+ * import { defineServer } from '@ubean/app';
+ *
+ * export default defineServer({
+ *   plugins: [
+ *     {
+ *       name: 'my-plugin',
+ *       setup(app) { app.use('/api/custom', handler); },
+ *       ready(app) { /* routes registered *\/ }
+ *     }
+ *   ],
+ *   hooks: {
+ *     'request:start': (c) => { console.log(c.req.method, c.req.path); }
+ *   },
+ *   onAppCreate: async (app) => { /* init db *\/ },
+ *   onServerReady: async (app) => { /* start workers *\/ }
+ * });
+ * ```
+ */
+declare function defineServer(options: DefineServerOptions): ResolvedServerConfig;
+/**
+ * Create an empty server config — used as the fallback when no
+ * `src/server.ts` file exists.
+ */
+declare function createDefaultServerConfig(): ResolvedServerConfig;
+/**
+ * Merge multiple server configs (shared + mode-specific) into one.
+ * Plugins are concatenated; hooks are merged; mode-specific callbacks
+ * override shared ones.
+ */
+declare function mergeServerConfigs(base: ResolvedServerConfig, ...configs: (ResolvedServerConfig | null | undefined)[]): ResolvedServerConfig;
+//#endregion
+//#region src/app.d.ts
+interface UbeanRuntimeHooks {
+  'app:created': (app: Hono<UbeanEnv$1>) => void | Promise<void>;
+  'app:before:register': (app: Hono<UbeanEnv$1>) => void | Promise<void>;
+  'app:after:register': (app: Hono<UbeanEnv$1>) => void | Promise<void>;
+  'request:start': (c: Context<UbeanEnv$1>) => void | Promise<void>;
+  'request:end': (c: Context<UbeanEnv$1>, res: Response) => void | Promise<void>;
+  'request:error': (c: Context<UbeanEnv$1>, err: Error) => void | Promise<void>;
+  'route:register': (route: {
+    method: string;
+    path: string;
+    handler: MiddlewareHandler[] | ComposedHandler$1 | Function;
+    meta?: RouteMeta$1;
+  }) => void | Promise<void>;
+  'middleware:register': (mw: ScannedMiddleware$1) => void | Promise<void>;
+  error: (err: Error, c: Context<UbeanEnv$1>) => void | Promise<void>;
+}
+/**
+ * Page renderer shape (satisfied by `@ubean/ssr`'s `PageRenderer`).
+ * Declared as a type alias to the actual `@ubean/pages`'s `PageRenderer`
+ * interface so consumers don't need to install `@ubean/pages` separately
+ * to type-check against `UbeanAppOptions.pageRenderer`.
+ *
+ * Type-only import works even when `@ubean/pages` is an optional peerDep —
+ * only runtime imports would fail. Consumers without `@ubean/pages` will
+ * see this type fall back to `any` (TS' default for missing modules under
+ * `skipLibCheck`).
+ */
+type PageRenderer = import('@ubean/pages').PageRenderer;
+interface PageAssetTags {
+  head?: string;
+  bodyAttrs?: string;
+  htmlAttrs?: string;
+}
+interface UbeanAppOptions {
+  rootDir?: string;
+  routes?: ScannedApiRoute$1[];
+  middleware?: ScannedMiddleware$1[];
+  pages?: ScannedPageRoute$1[];
+  layouts?: ScannedLayout$1[];
+  crons?: ScannedCronTask[];
+  routeRules?: Record<string, RouteRule$1>;
+  plugins?: UbeanAppPlugin[];
+  routeLoaders?: Record<string, () => Promise<{
+    default?: ComposedHandler$1 | MiddlewareHandler[];
+  } | Record<string, ComposedHandler$1 | MiddlewareHandler[]>>>;
+  middlewareLoaders?: Record<string, () => Promise<{
+    default: UbeanMiddleware$1;
+  }>>;
+  pageLoaders?: Record<string, () => Promise<unknown>>;
+  pageRenderer?: PageRenderer | null;
+  pageAssetTags?: PageAssetTags;
+  publicDir?: string;
+  healthEndpoint?: boolean;
+  openAPI?: boolean | {
+    title?: string;
+    version?: string;
+    description?: string;
+    scalarPath?: string;
+    openAPIPath?: string;
+  };
+  i18nConfig?: {
+    strategy?: 'prefix' | 'prefix_except_default' | 'prefix_and_default' | 'no_prefix';
+    defaultLocale?: string;
+    locales?: string[];
+  };
+}
+interface UbeanAppPlugin {
+  name: string;
+  /** Called after app is created but before routes are registered */
+  setup?: (app: UbeanApp) => void | Promise<void>;
+  /** Called after all routes are registered */
+  ready?: (app: UbeanApp) => void | Promise<void>;
+}
+/**
+ * Structural view of the DevTools middleware returned by `createDevToolsMiddleware`
+ * in `@ubean/devtools`. Defined locally (rather than importing the real return
+ * type) so `ubean` has no static dependency on `@ubean/devtools` — the package is
+ * loaded via a dynamic `import()` only when DevTools is enabled.
+ *
+ * @deprecated DevTools is now a Vite plugin (`@ubean/devtools`'s
+ * `ubeanDevtoolsPlugin`) loaded by the dev runner. The Hono app no longer
+ * hosts DevTools middleware. This placeholder is kept only for type
+ * compatibility with external consumers that may still reference it.
+ */
+interface DevToolsInstance {
+  rpc: {
+    setRoutes(routes: never[]): void;
+    setPages(pages: never[]): void;
+    setMiddlewares(middlewares: never[]): void;
+    setLayouts(layouts: never[]): void;
+    setCrons(crons: never[]): void;
+    setPresets(presets: string[]): void;
+    setOpenAPI(openAPI: {
+      enabled: boolean;
+      scalarPath?: string;
+      openAPIPath?: string;
+    }): void;
+    setCustomTabs(tabs: never[]): void;
+    updateInfo(partial: Record<string, unknown>): void;
+  };
+  middleware: (c: Context<UbeanEnv$1>, next: Next) => Promise<Response | void>;
+}
+declare class UbeanApp {
+  readonly hono: Hono<UbeanEnv$1>;
+  readonly hooks: Hookable<UbeanRuntimeHooks>;
+  readonly plugins: UbeanAppPlugin[];
+  readonly options: UbeanAppOptions;
+  private _ready;
+  constructor(options?: UbeanAppOptions);
+  private _setupBaseMiddleware;
+  init(): Promise<this>;
+  private _lazyInitPromise;
+  lazyInit(): Promise<this>;
+  resetInit(): void;
+  private _setupFallback;
+  use(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  use(...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  on(method: string | string[], path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  get(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  post(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  put(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  patch(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  delete(path: string, ...handlers: MiddlewareHandler<UbeanEnv$1>[]): this;
+  fetch: Hono<UbeanEnv$1>['fetch'];
+  request: Hono<UbeanEnv$1>['request'];
+}
+interface AppPlugin {
+  name: string;
+  setup?: (app: Hono<UbeanEnv$1>) => void | Promise<void>;
+}
+declare function createUbeanApp(options?: UbeanAppOptions): UbeanApp;
+//#endregion
+export { type AppPlugin, type ComposedHandler, type DefineServerOptions, type DevToolsInstance, type PageAssetTags, type PageRenderer, type RegisterOptions, type ResolvedServerConfig, type RouteMeta, type RouteRegistrar, type RouteRule, type ScannedApiRoute, type ScannedLayout, type ScannedMiddleware, type ScannedPageRoute, type ServerHooks, UbeanApp, type UbeanAppOptions, type UbeanAppPlugin, type UbeanEnv, type UbeanMiddleware, type UbeanRuntimeHooks, applyServerConfig, createDefaultServerConfig, createUbeanApp, defineServer, mergeServerConfigs };

package/dist/index.js

@@ -0,0 +1,240 @@
+import { existsSync } from "node:fs";
+import { Hono } from "hono";
+import { createRouteRulesMiddleware, registerOpenAPIRoutes, registerRoutes, setInternalFetcher } from "@ubean/api-routes";
+import { UbeanError, errorToResponse, isUbeanError } from "@ubean/error";
+import { createCacheMiddleware, createMemoryStore, createWebSocketMiddleware, resolveRouteCacheRules, serveStatic, useCacheStore } from "@ubean/server";
+import { requestId } from "hono/request-id";
+import { createHooks } from "hookable";
+import { isAbsolute, join } from "pathe";
+//#region src/define-server.ts
+/**
+* Apply a resolved server config to a `UbeanApp` instance.
+*
+* This must be called BEFORE `app.init()` so that:
+* - `plugins` are available when `init()` calls `setup` / `ready`
+* - `hooks` are registered before `init()` fires `app:created` etc.
+* - `onAppCreate` runs before route registration
+*
+* `onServerReady` is NOT called here — the caller must invoke it after
+* `app.init()` completes.
+*/
+async function applyServerConfig(app, config) {
+	if (config.plugins.length > 0) app.plugins.push(...config.plugins);
+	for (const [name, handler] of Object.entries(config.hooks)) if (handler) app.hooks.hook(name, handler);
+	if (config.onAppCreate) await config.onAppCreate(app);
+}
+/**
+* Define the backend server configuration.
+*
+* This is the server-side counterpart of `defineApp`. It allows users to
+* inject plugins, register runtime hooks, and run startup/ready logic
+* from a simple entry file (`src/server.ts`).
+*
+* @example
+* ```ts
+* // src/server.ts
+* import { defineServer } from '@ubean/app';
+*
+* export default defineServer({
+*   plugins: [
+*     {
+*       name: 'my-plugin',
+*       setup(app) { app.use('/api/custom', handler); },
+*       ready(app) { /* routes registered *\/ }
+*     }
+*   ],
+*   hooks: {
+*     'request:start': (c) => { console.log(c.req.method, c.req.path); }
+*   },
+*   onAppCreate: async (app) => { /* init db *\/ },
+*   onServerReady: async (app) => { /* start workers *\/ }
+* });
+* ```
+*/
+function defineServer(options) {
+	return {
+		plugins: options.plugins || [],
+		hooks: options.hooks || {},
+		onAppCreate: options.onAppCreate,
+		onServerReady: options.onServerReady
+	};
+}
+/**
+* Create an empty server config — used as the fallback when no
+* `src/server.ts` file exists.
+*/
+function createDefaultServerConfig() {
+	return {
+		plugins: [],
+		hooks: {}
+	};
+}
+/**
+* Merge multiple server configs (shared + mode-specific) into one.
+* Plugins are concatenated; hooks are merged; mode-specific callbacks
+* override shared ones.
+*/
+function mergeServerConfigs(base, ...configs) {
+	const result = {
+		plugins: [...base.plugins],
+		hooks: { ...base.hooks },
+		onAppCreate: base.onAppCreate,
+		onServerReady: base.onServerReady
+	};
+	for (const cfg of configs) {
+		if (!cfg) continue;
+		if (cfg.plugins) result.plugins.push(...cfg.plugins);
+		if (cfg.hooks) Object.assign(result.hooks, cfg.hooks);
+		if (cfg.onAppCreate) result.onAppCreate = cfg.onAppCreate;
+		if (cfg.onServerReady) result.onServerReady = cfg.onServerReady;
+	}
+	return result;
+}
+//#endregion
+//#region src/app.ts
+var UbeanApp = class {
+	hono;
+	hooks;
+	plugins;
+	options;
+	_ready = false;
+	constructor(options = {}) {
+		this.options = options;
+		this.hono = new Hono({ strict: false });
+		this.hooks = createHooks();
+		this.plugins = options.plugins || [];
+		this._setupBaseMiddleware();
+		this._setupFallback();
+	}
+	_setupBaseMiddleware() {
+		this.hono.use("*", requestId());
+		if (this.options.routeRules && Object.keys(this.options.routeRules).length > 0) {
+			this.hono.use("*", createRouteRulesMiddleware(this.options.routeRules));
+			const cacheRules = resolveRouteCacheRules(this.options.routeRules);
+			if (Object.keys(cacheRules).length > 0) {
+				useCacheStore(createMemoryStore());
+				this.hono.use("*", createCacheMiddleware({ rules: cacheRules }));
+			}
+		}
+		this.hono.use("*", createWebSocketMiddleware());
+		this.hono.use("*", async (c, next) => {
+			c.set("route", {
+				meta: { requiresAuth: true },
+				path: c.req.path,
+				method: c.req.method
+			});
+			await this.hooks.callHook("request:start", c);
+			try {
+				await next();
+				await this.hooks.callHook("request:end", c, c.res);
+			} catch (err) {
+				await this.hooks.callHook("request:error", c, err);
+				throw err;
+			}
+		});
+		if (this.options.healthEndpoint !== false) this.hono.get("/_health", (c) => {
+			return c.json({
+				status: "ok",
+				timestamp: Date.now()
+			});
+		});
+	}
+	async init() {
+		if (this._ready) return this;
+		await this.hooks.callHook("app:created", this.hono);
+		for (const plugin of this.plugins) if (plugin.setup) await plugin.setup(this);
+		await this.hooks.callHook("app:before:register", this.hono);
+		if (this.options.publicDir) {
+			const publicDir = isAbsolute(this.options.publicDir) ? this.options.publicDir : this.options.rootDir ? join(this.options.rootDir, this.options.publicDir) : this.options.publicDir;
+			if (existsSync(publicDir)) this.hono.use("/*", serveStatic({ publicDir }));
+		}
+		const registerOpts = {
+			routes: this.options.routes || [],
+			middleware: this.options.middleware || [],
+			pages: this.options.pages || [],
+			layouts: this.options.layouts || [],
+			routeLoaders: this.options.routeLoaders || {},
+			middlewareLoaders: this.options.middlewareLoaders || {},
+			pageLoaders: this.options.pageLoaders || {},
+			pageRenderer: this.options.pageRenderer ?? null,
+			pageAssetTags: this.options.pageAssetTags ?? {},
+			i18nConfig: this.options.i18nConfig
+		};
+		await registerRoutes(this, registerOpts);
+		if (this.options.openAPI) {
+			const openAPIOpts = typeof this.options.openAPI === "object" ? this.options.openAPI : {};
+			registerOpenAPIRoutes(this.hono, openAPIOpts);
+		}
+		await this.hooks.callHook("app:after:register", this.hono);
+		setInternalFetcher((req) => this.hono.fetch(req));
+		for (const plugin of this.plugins) if (plugin.ready) await plugin.ready(this);
+		this._ready = true;
+		return this;
+	}
+	_lazyInitPromise = null;
+	lazyInit() {
+		if (this._ready) return Promise.resolve(this);
+		if (!this._lazyInitPromise) this._lazyInitPromise = this.init();
+		return this._lazyInitPromise;
+	}
+	resetInit() {
+		this._ready = false;
+		this._lazyInitPromise = null;
+	}
+	_setupFallback() {
+		this.hono.notFound((c) => {
+			return c.json({
+				error: "Not Found",
+				path: c.req.path,
+				method: c.req.method
+			}, 404);
+		});
+		this.hono.onError((err, c) => {
+			this.hooks.callHook("error", err, c);
+			if (isUbeanError(err)) return errorToResponse(c, err);
+			return errorToResponse(c, new UbeanError(500, err.message || "Internal Server Error"));
+		});
+	}
+	use(pathOrHandler, ...handlers) {
+		this.hono.use(pathOrHandler, ...handlers);
+		return this;
+	}
+	on(method, path, ...handlers) {
+		const methods = Array.isArray(method) ? method : [method];
+		for (const m of methods) this.hono.on(m, path, ...handlers);
+		return this;
+	}
+	get(path, ...handlers) {
+		this.hono.get(path, ...handlers);
+		return this;
+	}
+	post(path, ...handlers) {
+		this.hono.post(path, ...handlers);
+		return this;
+	}
+	put(path, ...handlers) {
+		this.hono.put(path, ...handlers);
+		return this;
+	}
+	patch(path, ...handlers) {
+		this.hono.patch(path, ...handlers);
+		return this;
+	}
+	delete(path, ...handlers) {
+		this.hono.delete(path, ...handlers);
+		return this;
+	}
+	fetch = async (...args) => {
+		await this.lazyInit();
+		return this.hono.fetch(...args);
+	};
+	request = async (...args) => {
+		await this.lazyInit();
+		return this.hono.request(...args);
+	};
+};
+function createUbeanApp(options = {}) {
+	return new UbeanApp(options);
+}
+//#endregion
+export { UbeanApp, applyServerConfig, createDefaultServerConfig, createUbeanApp, defineServer, mergeServerConfigs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/app",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Hono app factory and server config for ubean (createUbeanApp, defineServer)",
   "files": [
     "dist"
@@ -19,21 +19,21 @@
     "hono": "4.12.32",
     "hookable": "^6.1.1",
     "pathe": "^2.0.3",
-    "@ubean/server": "0.1.2",
-    "@ubean/error": "0.1.2",
-    "@ubean/types": "0.1.2",
-    "@ubean/api-routes": "0.1.2"
+    "@ubean/api-routes": "0.1.4",
+    "@ubean/error": "0.1.4",
+    "@ubean/types": "0.1.4",
+    "@ubean/server": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
     "typescript": "6.0.3",
     "vite-plus": "0.2.6",
-    "@ubean/pages": "0.1.2",
-    "@ubean/routing": "0.1.2"
+    "@ubean/pages": "0.1.4",
+    "@ubean/routing": "0.1.4"
   },
   "peerDependencies": {
-    "@ubean/pages": "0.1.2",
-    "@ubean/routing": "0.1.2"
+    "@ubean/pages": "0.1.4",
+    "@ubean/routing": "0.1.4"
   },
   "peerDependenciesMeta": {
     "@ubean/routing": {