@ubean/shared 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -50,11 +50,9 @@ interface IsrRule {
  * - `prerender: true`  该路由加入 SSG 预渲染队列(由 `@ubean/prerender` 自动发现)
  * - `isr: 60` 或 `isr: { ttl: 60, swr: true }`  启用 ISR,以 TTL 秒缓存渲染 HTML
  *
- * P9-04 扩展:支持 Partial Prerendering(`ppr`)。
- * - `ppr: true` 启用 PPR:静态壳预渲染 + Suspense 流式动态内容
- *   (对齐 Next.js 16 PPR / Astro `server:defer`)。运行时强制流式 SSR,
- *   覆盖全局 `ssr.exclude`;同时该路由加入预渲染队列(等价于 `prerender: true`),
- *   预渲染产物作为静态壳供运行时复用。
+ * `ppr: true` 是强制流式 SSR + 预渲染发现的便利别名（等价 `ssr: 'streaming'`
+ * 且隐含 `prerender: true`）。**不是** Next.js 的静态壳 / 动态洞 PPR。
+ * 流式响应带 `X-SSR-Mode: streaming` 与 `X-PPR: streaming`。
  *
  * 注意:构建时预渲染策略已迁移至 `PrerenderConfig`(由 `ubean.config.ts` 的
  * `prerender` 字段统一管理),`RouteRule.prerender` 仅作为自动发现标记 ——
@@ -79,8 +77,9 @@ interface RouteRule {
    * - `true`  强制 SSR(即使命中全局 exclude)
    * - `false` 强制 CSR(即使全局未排除)
    * - `'streaming'` 强制流式 SSR(等同于 `ssr: true` + 流式输出)
+   * - `'data-only'` 跑 loader，返回 CSR shell + 脱水数据（不对页面做 HTML SSR）
    */
-  ssr?: boolean | 'streaming';
+  ssr?: boolean | 'streaming' | 'data-only';
   /**
    * 标记该路由加入 SSG 预渲染队列(P9-03)。
    * 由 `collectPrerenderRoutes` 自动从 `routeRules` 中扫描发现。
@@ -94,17 +93,9 @@ interface RouteRule {
    */
   isr?: number | IsrRule;
   /**
-   * 启用 Partial Prerendering / Server Islands(P9-04)。
-   *
-   * - `true` 该路由启用 PPR:静态壳预渲染 + Suspense 流式动态内容
-   *
-   * 运行时行为:
-   * - 强制流式 SSR(覆盖 `ssr.exclude` / 全局 `streaming`),等价于 `ssr: 'streaming'`
-   * - 隐含 `prerender: true`,该路由会被预渲染(产物作为静态壳)
-   * - 页面内带 `server:defer` 指令的组件在预渲染时仅渲染 fallback,
-   *   在流式 SSR 时通过 Suspense 边界流式输出实际内容
-   *
-   * 对齐:Next.js 16 PPR(稳定)、Astro 5 `server:defer`。
+   * 强制流式 SSR + 加入预渲染队列的便利开关。
+   * 等价 `ssr: 'streaming'`，隐含 `prerender: true`。
+   * 不是 Next.js Partial Prerendering 静态壳。
    */
   ppr?: boolean;
 }
@@ -282,6 +273,18 @@ interface ActionSchema<TOutput = unknown> {
   };
   parse?(value: unknown): TOutput;
   _output?: TOutput;
+  '~standard'?: {
+    version: 1;
+    vendor: string;
+    validate: (value: unknown) => {
+      value: TOutput;
+    } | {
+      issues: Array<{
+        message?: string;
+        path?: unknown;
+      }>;
+    } | Promise<unknown>;
+  };
 }
 /**
  * A registered server action — the runtime representation produced by

package/dist/logger/hono.d.ts

@@ -0,0 +1,25 @@
+import { n as RequestLoggerOptions } from "../types-CFy62PZV.js";
+import { MiddlewareHandler } from "hono";
+//#region src/logger/hono.d.ts
+/**
+ * Hono 请求日志中间件。
+ *
+ * 记录每个请求:方法、路径、状态码、耗时,以及错误与慢请求(按 `slowThreshold`)。
+ * 利用 Hono compose 设置的 `c.error` 识别被 `onError` 收敛的异常(此时 `next()` 不抛出,
+ * 而是以 500 Response 正常返回);若中间件链本身向外抛出异常也会被记录后重新抛出。
+ *
+ * @example
+ * ```ts
+ * import { createRequestLoggerMiddleware } from '@ubean/shared/logger/hono';
+ * import { createUbeanApp } from 'ubean/runtime/app';
+ *
+ * const app = createUbeanApp();
+ * app.use('*', createRequestLoggerMiddleware({
+ *   exclude: ['/_health', '/_devtools/**'],
+ *   slowThreshold: 2000
+ * }));
+ * ```
+ */
+declare function createRequestLoggerMiddleware(options?: RequestLoggerOptions): MiddlewareHandler;
+//#endregion
+export { createRequestLoggerMiddleware };

package/dist/logger/hono.js

@@ -0,0 +1,104 @@
+import { n as getLogger } from "../logger-CG0K8cWb.js";
+//#region src/logger/hono.ts
+/**
+* 判断路径是否应被跳过。
+*/
+function shouldSkip(path, exclude) {
+	if (!exclude) return false;
+	if (typeof exclude === "function") return exclude(path);
+	for (const pattern of exclude) if (typeof pattern === "string") {
+		if (pattern === path) return true;
+		if (pattern === "**" || pattern === "/**") return true;
+		if (pattern.endsWith("/**")) {
+			const prefix = pattern.slice(0, -3);
+			if (path === prefix || path.startsWith(`${prefix}/`)) return true;
+		}
+		if (path.startsWith(pattern)) return true;
+	} else if (pattern instanceof RegExp) {
+		if (pattern.test(path)) return true;
+	}
+	return false;
+}
+/**
+* Hono 请求日志中间件。
+*
+* 记录每个请求:方法、路径、状态码、耗时,以及错误与慢请求(按 `slowThreshold`)。
+* 利用 Hono compose 设置的 `c.error` 识别被 `onError` 收敛的异常(此时 `next()` 不抛出,
+* 而是以 500 Response 正常返回);若中间件链本身向外抛出异常也会被记录后重新抛出。
+*
+* @example
+* ```ts
+* import { createRequestLoggerMiddleware } from '@ubean/shared/logger/hono';
+* import { createUbeanApp } from 'ubean/runtime/app';
+*
+* const app = createUbeanApp();
+* app.use('*', createRequestLoggerMiddleware({
+*   exclude: ['/_health', '/_devtools/**'],
+*   slowThreshold: 2000
+* }));
+* ```
+*/
+function createRequestLoggerMiddleware(options = {}) {
+	const log = options.logger ?? getLogger("http");
+	const slowThreshold = options.slowThreshold ?? 1e3;
+	return async (c, next) => {
+		const { method } = c.req;
+		const path = c.req.path;
+		const url = options.logQuery ? c.req.url : path;
+		if (shouldSkip(path, options.exclude)) return next();
+		const requestId = c.get("requestId");
+		const start = Date.now();
+		log.info({
+			method,
+			path,
+			requestId
+		}, `--> ${method} ${url}`);
+		try {
+			await next();
+			const duration = Date.now() - start;
+			const status = c.res.status;
+			const error = c.error;
+			if (error) log.error({
+				method,
+				path,
+				status,
+				durationMs: duration,
+				requestId,
+				error: error.message
+			}, `<!- ${method} ${url} ${status} ${duration}ms ERROR`);
+			else if (status >= 500) log.error({
+				method,
+				path,
+				status,
+				durationMs: duration,
+				requestId
+			}, `<-- ${method} ${url} ${status} ${duration}ms`);
+			else if (status >= 400 || duration >= slowThreshold) log.warn({
+				method,
+				path,
+				status,
+				durationMs: duration,
+				requestId
+			}, `<-- ${method} ${url} ${status} ${duration}ms`);
+			else log.info({
+				method,
+				path,
+				status,
+				durationMs: duration,
+				requestId
+			}, `<-- ${method} ${url} ${status} ${duration}ms`);
+		} catch (err) {
+			const duration = Date.now() - start;
+			log.error({
+				method,
+				path,
+				durationMs: duration,
+				requestId,
+				error: err instanceof Error ? err.message : String(err)
+			}, `<!- ${method} ${url} ERROR ${duration}ms`);
+			throw err;
+		}
+	};
+}
+//#endregion
+export { createRequestLoggerMiddleware };

package/dist/logger/index.d.ts

@@ -0,0 +1,34 @@
+import { i as UbeanLoggerOptions, n as RequestLoggerOptions, r as UbeanLogger, t as LogLevelName } from "../types-CFy62PZV.js";
+//#region src/logger/logger.d.ts
+/**
+ * 创建一个 ubean 命名的 tslog logger(默认 name 为 `ubean`)。
+ *
+ * - 未显式提供 `minLevel` 时读取 `LOG_LEVEL`/`TSLOG_LEVEL` 环境变量
+ * - 输出格式沿用 tslog 默认:交互式终端彩色 pretty,管道/CI 自动去色;需要结构化 JSON 时显式
+ *   `{ type: 'json' }` 或设 `TSLOG_TYPE=json`
+ *
+ * @example
+ * ```ts
+ * const log = createUbeanLogger({ name: 'api' });
+ * log.info({ port: 3000 }, 'server started');
+ * ```
+ */
+declare function createUbeanLogger(options?: UbeanLoggerOptions): UbeanLogger;
+/** ubean 全局默认 logger(供应用侧 `import { logger } from 'ubean'` 使用) */
+declare const logger: UbeanLogger;
+/**
+ * 获取命名(scope)logger。
+ *
+ * - 不传 scope 时返回全局默认 `logger`
+ * - 传 scope 时返回其子 logger(name 组合为 `ubean:<scope>`,如 `getLogger('cli')` → `ubean:cli`),
+ *   继承父 logger 的 settings/minLevel,可通过 `options` 覆盖
+ *
+ * @example
+ * ```ts
+ * const cli = getLogger('cli');
+ * cli.info('building...');
+ * ```
+ */
+declare function getLogger(scope?: string, options?: UbeanLoggerOptions): UbeanLogger;
+//#endregion
+export { type LogLevelName, type RequestLoggerOptions, type UbeanLogger, type UbeanLoggerOptions, createUbeanLogger, getLogger, logger };

package/dist/logger/index.js

@@ -0,0 +1,2 @@
+import { n as getLogger, r as logger, t as createUbeanLogger } from "../logger-CG0K8cWb.js";
+export { createUbeanLogger, getLogger, logger };

package/dist/logger-CG0K8cWb.js

@@ -0,0 +1,61 @@
+import { Logger } from "tslog";
+//#region src/logger/logger.ts
+const DEFAULT_NAME = "ubean";
+/**
+* 从环境变量解析日志等级:
+* 1. `LOG_LEVEL`(ubean 约定,友好别名)
+* 2. `TSLOG_LEVEL`(tslog 原生)
+*
+* 返回 undefined 时沿用 tslog 默认 minLevel。
+*/
+function getLogLevelFromEnv() {
+	if (typeof process === "undefined" || !process.env) return void 0;
+	const value = process.env.LOG_LEVEL ?? process.env.TSLOG_LEVEL;
+	if (!value) return void 0;
+	return value;
+}
+/**
+* 创建一个 ubean 命名的 tslog logger(默认 name 为 `ubean`)。
+*
+* - 未显式提供 `minLevel` 时读取 `LOG_LEVEL`/`TSLOG_LEVEL` 环境变量
+* - 输出格式沿用 tslog 默认:交互式终端彩色 pretty,管道/CI 自动去色;需要结构化 JSON 时显式
+*   `{ type: 'json' }` 或设 `TSLOG_TYPE=json`
+*
+* @example
+* ```ts
+* const log = createUbeanLogger({ name: 'api' });
+* log.info({ port: 3000 }, 'server started');
+* ```
+*/
+function createUbeanLogger(options = {}) {
+	const minLevel = options.minLevel ?? getLogLevelFromEnv();
+	return new Logger({
+		name: DEFAULT_NAME,
+		...options,
+		minLevel
+	});
+}
+/** ubean 全局默认 logger(供应用侧 `import { logger } from 'ubean'` 使用) */
+const logger = createUbeanLogger();
+/**
+* 获取命名(scope)logger。
+*
+* - 不传 scope 时返回全局默认 `logger`
+* - 传 scope 时返回其子 logger(name 组合为 `ubean:<scope>`,如 `getLogger('cli')` → `ubean:cli`),
+*   继承父 logger 的 settings/minLevel,可通过 `options` 覆盖
+*
+* @example
+* ```ts
+* const cli = getLogger('cli');
+* cli.info('building...');
+* ```
+*/
+function getLogger(scope, options = {}) {
+	if (!scope) return logger;
+	return logger.getSubLogger({
+		name: scope,
+		...options
+	});
+}
+//#endregion
+export { getLogger as n, logger as r, createUbeanLogger as t };

package/dist/types-CFy62PZV.d.ts

@@ -0,0 +1,40 @@
+import { ILogObj, ISettingsParam, Logger } from "tslog";
+//#region src/logger/types.d.ts
+/**
+ * 日志等级名称(与 tslog v5 默认等级表一致)。
+ * 仅用于类型标注;`minLevel` 实际接受 number / tslog LogLevel 枚举 / 大小写不敏感的名称。
+ */
+type LogLevelName = 'silly' | 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/** 由 `@ubean/shared/logger` 创建的 tslog 实例 */
+type UbeanLogger = Logger<ILogObj>;
+/**
+ * ubean logger 选项 —— 透传 tslog v5 分组 settings(type/pretty/json/mask/stack/meta/…)。
+ * 约定:未显式提供 `minLevel` 时,由 `LOG_LEVEL`/`TSLOG_LEVEL` 环境变量决定(见 {@link createUbeanLogger})。
+ */
+interface UbeanLoggerOptions extends ISettingsParam<ILogObj> {}
+/**
+ * `createRequestLoggerMiddleware` 选项。
+ */
+interface RequestLoggerOptions {
+  /**
+   * 用于输出请求日志的 logger;默认 `getLogger('http')`(name 为 `ubean:http`)。
+   */
+  logger?: UbeanLogger;
+  /**
+   * 跳过的路径:
+   * - glob 模式字符串(如 `'/_health'`、`'/api/**'`、`'/favicon.ico'`)
+   * - RegExp(如 `/^\/_/`)
+   * - 或自定义谓词 `(path) => boolean`
+   */
+  exclude?: Array<string | RegExp> | ((path: string) => boolean);
+  /**
+   * 超过该毫秒数的请求以 `warn` 记录(用于慢请求告警)。默认 `1000`。
+   */
+  slowThreshold?: number;
+  /**
+   * 记录完整 URL(含 query string)而非仅 path。默认 `false`。
+   */
+  logQuery?: boolean;
+}
+//#endregion
+export { UbeanLoggerOptions as i, RequestLoggerOptions as n, UbeanLogger as r, LogLevelName as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ubean/shared",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Shared protocol types, errors, env and universal utilities for ubean",
   "files": [
     "dist"
@@ -17,6 +17,14 @@
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.js"
+    },
+    "./logger": {
+      "types": "./dist/logger/index.d.ts",
+      "import": "./dist/logger/index.js"
+    },
+    "./logger/hono": {
+      "types": "./dist/logger/hono.d.ts",
+      "import": "./dist/logger/hono.js"
     }
   },
   "dependencies": {
@@ -24,6 +32,7 @@
     "hono": "4.13.3",
     "pathe": "^2.0.3",
     "scule": "^1.3.0",
+    "tslog": "^5.1.0",
     "ufo": "1.6.4"
   },
   "devDependencies": {