@taicode/common-server 4.0.0-beta.4 → 4.0.0-beta.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TaicodeLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/output/app/index.d.ts

@@ -6,7 +6,8 @@ export { createCorsMiddleware } from '../cors/index.js';
 export { createAuthMiddleware } from '../auth/index.js';
 export { createRateLimitMiddleware } from '../rate-limit/index.js';
 export { createRedis, createCache } from '../redis/index.js';
-export type { AppInstance, ClientsContext, ClientsFactory, ClientsView, ConfigContext, LoggerLike, Middleware, MiddlewareContext, ResourcesContext, ResourcesView, RouterContext, ServiceContext, } from '../core/types.js';
+export { defineResource } from '../core/resource.js';
+export type { AppEnv, AppInstance, ClientsContext, ClientsFactory, ClientsView, ConfigContext, LoggerLike, Middleware, MiddlewareContext, MiddlewareEntry, MiddlewareUnit, ResourceUnit, ResourcesContext, ResourcesView, RouterContext, ServiceContext, } from '../core/types.js';
 export type { AuthVerifyInput, AuthVerifyMetadata, AuthVerifyResult } from '../auth/index.js';
 export type { AuthMiddlewareOptions } from '../auth/index.js';
 export type { AuthClient, AuthVerifyPayload, RegisterPermissionOperationsPayload, } from '../core/modules/auth-provider/index.js';

package/output/app/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AAsHA,OAAO,yBAAyB,CAAA;AAGhC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAiE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAyBtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAA;AA6B5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAiBlE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAG5D,YAAY,EACV,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAC7F,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAC7D,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,mCAAmC,GACpC,MAAM,wCAAwC,CAAA;AAC/C,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AA8HA,OAAO,yBAAyB,CAAA;AAGhC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAiE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAyBtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAA;AAiC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAiBlE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAsB5D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGpD,YAAY,EACV,MAAM,EACN,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAC7F,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAC7D,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,mCAAmC,GACpC,MAAM,wCAAwC,CAAA;AAC/C,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA"}

package/output/app/index.js

@@ -15,20 +15,23 @@
 // export const server = defineServer({
 //   app: { service: 'release', title: 'Release Service', version: packageJson.version },
 //
-//   // 我们拥有的基础设施：**只读 env**，构造时不建连
+//   // 我们拥有的基础设施：**只读 env**，构造时不建连。
+//   // 要扩展 env 类型？两种写法：① 手写首位泛型 `defineServer<{ FOO?: string }>({...})`（简单，但
+//   // 其余泛型会退化为 object）；② 给工厂 ctx 标注 `ResourcesContext<{ FOO?: string }>`（其余泛型照常推导）。
+//   // 加载都走内置逻辑，框架不提供自定义加载。
 //   resources: ({ env, disposer }) => ({ database: createDatabase(env.DATABASE_URL) }),
 //
 //   // 启动期的配置快照：可以读库，一次读完、进程内不再变
 //   config: ({ resources }) => loadConfig(resources),
 //
-//   // 我们调用的外部服务：地址 / 凭证来自 config，故排在 config 之后
+//   // 可选：我们调用的外部服务（地址 / 凭证来自 config，故排在 config 之后）；没有就省略
 //   clients: ({ config }) => ({ webhook: createWebhookClient(config.webhook) }),
 //
 //   // 业务单元：**服务之间禁止互依**，要共享的东西放 clients
 //   services: ({ resources, config, clients }) => ({ user: createUserService({ resources, config, clients }) }),
 //
-//   // 中间件：对象 **键即名字、键序即注册序**；`client` 是本仓自己的 `AuthClient` 实现
-//   middlewares: (ctx) => ({ cors: createCorsMiddleware(ctx), auth: createAuthMiddleware(ctx, { client }) }),
+//   // 中间件：**有序数组，数组位置即注册序**；标准工厂返回具名单元，直接按序摆进去
+//   middlewares: (ctx) => [createCorsMiddleware(ctx), createAuthMiddleware(ctx, { client })],
 //
 //   // 业务路由：**只能拿 app / services / clients**（绕不过 service 直连数据层）
 //   routers: ({ app, services }) => {
@@ -59,13 +62,18 @@
 //
 // | 槽位 | ctx 里有 | 刻意没有 | 为什么 |
 // |---|---|---|---|
-// | `resources` | `env` / `log` / `disposer` / `registerClassifyError` | `config` / `services` / `app` | 资源只依赖 env，从结构上消灭「资源依赖配置」的循环 |
-// | `config` | `env` / `log` / `disposer` / `resources` | `services` / `app` | 此时服务还没构造 |
-// | `clients` | `log` / `disposer` / `resources` / `config` | `env` / `services` / `app` | 运行期不许回头读 env；客户端地址来自 config |
+// | `resources` | `env`（可标注扩展） / `log` / `disposer` / `registerClassifyError` | `config` / `services` / `app` | 资源只依赖 env，从结构上消灭「资源依赖配置」的循环 |
+// | `config` | `env`（可标注扩展） / `log` / `disposer` / `resources` | `services` / `app` | 此时服务还没构造 |
+// | `clients`（可选） | `log` / `disposer` / `resources` / `config` | `env` / `services` / `app` | 运行期不许回头读 env；客户端地址来自 config |
 // | `services` | `log` / `disposer` / `resources` / `config` / `clients` | `env` / `services` / `app` | 服务层属运行期；禁 service 互依 |
 // | `middlewares` | `app` / `log` / `disposer` / `services` / `config` / `clients` | `resources` / `env` | 中间件碰数据必须穿过 service |
 // | `routers` | `app` / `log` / `disposer` / `services` / `clients` | `resources` / `env` / `config` | 路由只能穿过 service |
 //
+// 唯一的**可选**槽位是 `clients`（省略即空客户端包）；其余槽位恒定，没有业务路由也要写
+// `routers: () => {}`。应用扩展 env **不是槽位**，而是 `defineServer` 的**第一个泛型**：可手写
+// `defineServer<{ FOO?: string }>({...})`（简单，但其余泛型退化为 object），或给 `resources` /
+// `config` 的 `ctx` 标注 `ResourcesContext<Env>`（其余泛型照常推导）。加载仍走内置逻辑，框架不提供自定义加载。
+//
 // 资源释放**在创建处登记**：`ctx.disposer.add(() => closeXxx())`，关闭时框架按阶段逆序 flush，
 // 调用方不需要在任何地方再写一遍 close 逻辑。
 //
@@ -141,7 +149,7 @@ export { defineServer, startServer, generateOpenApi } from '../core/entries.js';
 //   })
 //
 //   afterAll(async () => {
-//     await testServer.app.close()                  // 七步关闭，与生产同一条路径
+//     await testServer.app.close()                  // 八步关闭，与生产同一条路径
 //   })
 //
 //   beforeEach(async () => {
@@ -210,16 +218,20 @@ export { createTestServer } from '../core/test-support/test-server.js';
 export { loadRuntimeEnvironment } from '../core/test-support/environment.js';
 // ── 可替换的标准中间件工厂 ────────────────────────────────────────
 //
-// 只在**要改默认行为**时才出现；不写就是框架默认。三者都接收 `middlewares` 槽位的 `ctx`：
+// 只在**要改默认行为**时才出现；不写就是框架默认。三者都接收 `middlewares` 槽位的 `ctx`，
+// 都返回**具名单元**（`MiddlewareUnit`），按顺序摆进 `middlewares` 数组即可：
 //
 // ```ts
-// middlewares: (ctx) => ({
-//   cors: createCorsMiddleware(ctx),                 // 允许的源来自 config 的 `cors` 键（请求期现读）
-//   auth: createAuthMiddleware(ctx, { client }),     // client 必填：鉴权提供方实现
-//   rateLimit: createRateLimitMiddleware(ctx, { store }), // store 可选，缺省进程内 memory
-// })
+// middlewares: (ctx) => [
+//   createCorsMiddleware(ctx),                      // 允许的源来自 config 的 `cors` 键（请求期现读）
+//   createAuthMiddleware(ctx, { client }),          // client 必填：鉴权提供方实现
+//   createRateLimitMiddleware(ctx, { store }),      // store 可选，缺省进程内 memory
+// ]
 // ```
 //
+// **数组位置即注册序**（cors → auth → rateLimit）：不再用对象键序（键序由引擎决定、纯数字键
+// 还会被重排）。要插入自定义中间件，返回具名单元 `{ name, register }` 或一个裸注册函数即可。
+//
 // `cors` / `rateLimit` 都**没有行为开关**，配置面只有输入参数：
 // - `cors`：允许的源来自 `config.cors`（`{ enabled, origins }`）；未配置 → 放行任意源并 warn 一次。
 // - `rateLimit`：**限流规则写在路由上**，不在中间件里：
@@ -254,3 +266,24 @@ export { createRateLimitMiddleware } from '../rate-limit/index.js';
 // Redis」因此是结构性的，而不是靠调用方自觉。`createCache` 不传 `redis` 也能用（自建客户端，
 // 或在没有 `REDIS_URL` 时退化成纯进程内一级缓存）。
 export { createRedis, createCache } from '../redis/index.js';
+// ── 资源单元（槽位内的生命周期）────────────────────────────────
+//
+// 资源多是第三方对象（PrismaClient / Redis client），形状改不了，所以 `setup()` 挂在外壳上：
+//
+// ```ts
+// resources: (ctx) => ({
+//   database: defineResource(createPrisma(ctx.env.DATABASE_URL), {
+//     async setup() { await pushSchema(ctx.env.DATABASE_URL) },   // 框架在 config 之前调
+//   }),
+// })
+// ```
+//
+// 两个生命周期各管一段：
+// - `setup()`     框架在 `config` 之前调（两个入口都跑）；
+// - `dispose()`   框架在关闭流程最后一步调（两个入口都跑）。
+//
+// 「用例之间重置数据」（清表、清缓存、重新插入样本数据）**不在资源上**：资源只知道有哪些表 /
+// 哪些 key，不知道谁往里写了什么。它由一套独立机制承担：`packages/server/testdata/*.ts|js`，
+// 每个脚本自带 `load()` / `cleanup()`，框架在 `development` / `test` 下自动装载并执行。
+// 详见 `createTestServer` 的 `resetTestData()`。
+export { defineResource } from '../core/resource.js';

package/output/auth/index.d.ts

@@ -1,5 +1,5 @@
 import type { AuthClient, AuthVerifyPayload } from '../core/modules/auth-provider/index.js';
-import type { Middleware, MiddlewareContext } from '../core/types.js';
+import type { MiddlewareContext, MiddlewareUnit } from '../core/types.js';
 /**
  * 标准中间件单元 `auth`（可替换）。
  *
@@ -63,10 +63,10 @@ export interface AuthMiddlewareOptions {
     cookieNames?: readonly string[];
 }
 /**
- * 构造标准 `auth` 中间件。
+ * 构造标准 `auth` 中间件（具名单元 `name: 'auth'`）。
  *
  * `client` **必填**（类型上）且必须有运行期实现：装了鉴权却没有校验实现是配置错误，
  * 构造期直接抛错——不留「请求期才 fail-closed」的窗口，也不允许静默放行。
  */
-export declare function createAuthMiddleware<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>, options: AuthMiddlewareOptions): Middleware;
+export declare function createAuthMiddleware<C = unknown, S = unknown>(ctx: MiddlewareContext<C, S>, options: AuthMiddlewareOptions): MiddlewareUnit;
 //# sourceMappingURL=index.d.ts.map

package/output/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/auth/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAG3F,OAAO,KAAK,EAA2B,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAG9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,gCAAgC;AAChC,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAE/C,4CAA4C;AAC5C,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAA;AAElG;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,MAAM,EAAE,UAAU,CAAA;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAqID;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAkEvI"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/auth/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAG3F,OAAO,KAAK,EAAuC,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAG9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,gCAAgC;AAChC,MAAM,MAAM,eAAe,GAAG,iBAAiB,CAAA;AAE/C,4CAA4C;AAC5C,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAA;AAElG;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;OAOG;IACH,MAAM,EAAE,UAAU,CAAA;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAqID;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAoE3I"}

package/output/auth/index.js

@@ -110,7 +110,7 @@ async function submitPermissionOperations(client, log, identity, operations) {
     log.info({ service, version, count: operations.length }, '[PermissionOperation][auth] 权限目录自注册完成');
 }
 /**
- * 构造标准 `auth` 中间件。
+ * 构造标准 `auth` 中间件（具名单元 `name: 'auth'`）。
  *
  * `client` **必填**（类型上）且必须有运行期实现：装了鉴权却没有校验实现是配置错误，
  * 构造期直接抛错——不留「请求期才 fail-closed」的窗口，也不允许静默放行。
@@ -120,7 +120,7 @@ export function createAuthMiddleware(ctx, options) {
     if (!client || typeof client.verify !== 'function') {
         throw new Error('[auth] auth 中间件缺少校验实现：请通过 `createAuthMiddleware(ctx, { client })` 注入鉴权提供方');
     }
-    return (app) => {
+    const register = (app) => {
         const identity = readServerIdentity(app);
         if (!identity) {
             throw new Error('[auth] 读不到身份块：`createAuthMiddleware` 必须挂在 `startServer` / `generateOpenApi` 的 app 上');
@@ -173,4 +173,5 @@ export function createAuthMiddleware(ctx, options) {
             await submitPermissionOperations(client, ctx.log, identity, collectPermissionOperations(app, ctx.log));
         });
     };
+    return { name: 'auth', register };
 }

package/output/core/boot/context.d.ts

@@ -1,6 +1,6 @@
+import type { ResourceSetupUnit } from './lifecycle.js';
 import type { Disposer } from '@taicode/common-base';
-import type { ConfigEnv } from '../env.js';
-import type { AppInstance, ClientsContext, ClientsView, ConfigContext, ErrorClassifier, LoggerLike, MiddlewareContext, ResourcesContext, ResourcesView, RouterContext, ServiceContext } from '../types.js';
+import type { AppEnv, AppInstance, ClientsContext, ClientsView, ConfigContext, ErrorClassifier, LoggerLike, MiddlewareContext, ResourcesContext, ResourcesView, RouterContext, ServiceContext } from '../types.js';
 /**
  * 分阶段 ctx 的运行时构造（N1 §2）。
  *
@@ -8,10 +8,30 @@ import type { AppInstance, ClientsContext, ClientsView, ConfigContext, ErrorClas
  * （`generateOpenApi` 不跑 `config` 槽位）读到它时抛 `SystemError('CONFIG_UNAVAILABLE')`
  * —— 让「构造期不得读配置」有运行期护栏，而不仅是文档规则。
  */
-/** 运行时镜像 `Live<T>`：剔除值为 `false` 的键（编译期静态关闭） */
+/**
+ * 运行时镜像 `Live<Value>`：剔除值为 `false` 的键（编译期静态关闭）。
+ *
+ * `resources` 与 `clients` 两个槽位共用这套口径。
+ */
 export declare function liveResources(resources: object): Record<string, unknown>;
-/** 客户端包的运行时镜像（口径与 `liveResources` 完全一致，另立一名只为调用处可读） */
-export declare function liveClients(clients: object): Record<string, unknown>;
+/**
+ * 把 `resources(ctx)` 的返回值拆成「对外视图」与「可执行生命周期列表」。
+ *
+ * 三件事：
+ * - **解包**：`defineResource(client, …)` → 视图里是 `client` 本身；裸对象原样（单元可选）；
+ * - **收集**：有 `setup` / `dispose` 的单元按**对象声明序**收集成
+ *   `{ name, setup, dispose }`，分别交给 `setupResourceUnits` / `disposeResourceUnits`
+ *   执行；
+ * - **剔除**：`false` 键与 `liveResources` 同口径（静态关闭的资源不参与生命周期）。
+ *
+ * ❗识别靠 `'value' in obj && !('then' in obj)`：`Resources` 允许是 Promise（`Awaited<>`
+ * 归一），但**单个资源值本身是 thenable 的极端情况**不当单元——宁可把它当裸值，
+ * 也不要把它错当单元。
+ */
+export declare function splitResourceUnits(resources: object): {
+    view: Record<string, unknown>;
+    units: ResourceSetupUnit[];
+};
 /**
  * `config` 槽位的**读取能力**（不是容器）。
  *
@@ -22,68 +42,68 @@ export declare function liveClients(clients: object): Record<string, unknown>;
  * 写入通道是**私有 Symbol**（本文件内、不导出）：调用方连键名都写不出来，只能通过
  * `provideConfig()` 写，而它只被 `buildConfig` 调用。
  */
-export interface ConfigAccess<C> {
+export interface ConfigAccess<Config> {
     /** `config` 槽位是否已产出（出 spec 路径恒为 `false`） */
     readonly available: boolean;
     /** 读配置；未产出时抛 `SystemError('CONFIG_UNAVAILABLE')` */
-    read(): Awaited<C>;
+    read(): Awaited<Config>;
 }
-export declare function createConfigAccess<C>(): ConfigAccess<C>;
+export declare function createConfigAccess<Config>(): ConfigAccess<Config>;
 /** 写入 `config` 产物（唯一的写入口：由 `buildConfig` 调用，不在 `BootContext` 上暴露） */
-export declare function provideConfig<C>(access: ConfigAccess<C>, value: Awaited<C>): void;
+export declare function provideConfig<Config>(access: ConfigAccess<Config>, value: Awaited<Config>): void;
 /** 按**已知键**从配置值里取字段（框架内置单元消费配置的单一入口；不做形状校验） */
 export declare function readConfigKey(config: unknown, key: string): unknown;
 /** `resources(ctx)` 入参 */
-export interface ResourcesContextParams {
-    env: ConfigEnv;
+export interface ResourcesContextParams<Env = object> {
+    env: AppEnv<Env>;
     log: LoggerLike;
     disposer: Disposer;
     /** 收集器：`buildResources` 注入，把各资源注册的分类器按注册顺序收起来 */
     registerClassifyError: (classifier: ErrorClassifier) => void;
 }
-export declare function createResourcesContext(params: ResourcesContextParams): ResourcesContext;
+export declare function createResourcesContext<Env = object>(params: ResourcesContextParams<Env>): ResourcesContext<Env>;
 /** `config(ctx)` 入参 */
-export interface ConfigContextParams<R> {
-    env: ConfigEnv;
+export interface ConfigContextParams<Resources, Env = object> {
+    env: AppEnv<Env>;
     log: LoggerLike;
     disposer: Disposer;
-    resources: ResourcesView<R>;
+    resources: ResourcesView<Resources>;
 }
-export declare function createConfigContext<R>(params: ConfigContextParams<R>): ConfigContext<R>;
+export declare function createConfigContext<Resources, Env = object>(params: ConfigContextParams<Resources, Env>): ConfigContext<Resources, Env>;
 /** `clients(ctx)` 入参（与 `services` 同依赖集：`resources` + `config`） */
-export interface ClientsContextParams<R, C> {
+export interface ClientsContextParams<Resources, Config> {
     log: LoggerLike;
     disposer: Disposer;
-    resources: ResourcesView<R>;
-    configAccess: ConfigAccess<C>;
+    resources: ResourcesView<Resources>;
+    configAccess: ConfigAccess<Config>;
 }
-export declare function createClientsContext<R, C>(params: ClientsContextParams<R, C>): ClientsContext<R, C>;
+export declare function createClientsContext<Resources, Config>(params: ClientsContextParams<Resources, Config>): ClientsContext<Resources, Config>;
 /** `services(ctx)` 入参 */
-export interface ServiceContextParams<R, C, CL> {
+export interface ServiceContextParams<Resources, Config, Clients> {
     log: LoggerLike;
     disposer: Disposer;
-    resources: ResourcesView<R>;
-    configAccess: ConfigAccess<C>;
-    clients: ClientsView<CL>;
+    resources: ResourcesView<Resources>;
+    configAccess: ConfigAccess<Config>;
+    clients: ClientsView<Clients>;
 }
-export declare function createServiceContext<R, C, CL>(params: ServiceContextParams<R, C, CL>): ServiceContext<R, C, CL>;
+export declare function createServiceContext<Resources, Config, Clients>(params: ServiceContextParams<Resources, Config, Clients>): ServiceContext<Resources, Config, Clients>;
 /** `middlewares(ctx)` 入参 */
-export interface MiddlewareContextParams<C, S, CL> {
+export interface MiddlewareContextParams<Config, Services, Clients> {
     app: AppInstance;
     log: LoggerLike;
     disposer: Disposer;
-    services: Awaited<S>;
-    configAccess: ConfigAccess<C>;
-    clients: ClientsView<CL>;
+    services: Awaited<Services>;
+    configAccess: ConfigAccess<Config>;
+    clients: ClientsView<Clients>;
 }
-export declare function createMiddlewareContext<C, S, CL>(params: MiddlewareContextParams<C, S, CL>): MiddlewareContext<C, S, CL>;
+export declare function createMiddlewareContext<Config, Services, Clients>(params: MiddlewareContextParams<Config, Services, Clients>): MiddlewareContext<Config, Services, Clients>;
 /** `routers(ctx)` 入参 */
-export interface RouterContextParams<S, CL> {
+export interface RouterContextParams<Services, Clients> {
     app: AppInstance;
     log: LoggerLike;
     disposer: Disposer;
-    services: Awaited<S>;
-    clients: ClientsView<CL>;
+    services: Awaited<Services>;
+    clients: ClientsView<Clients>;
 }
-export declare function createRouterContext<S, CL>(params: RouterContextParams<S, CL>): RouterContext<S, CL>;
+export declare function createRouterContext<Services, Clients>(params: RouterContextParams<Services, Clients>): RouterContext<Services, Clients>;
 //# sourceMappingURL=context.d.ts.map

package/output/core/boot/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../source/core/boot/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,EACf,MAAM,aAAa,CAAA;AAEpB;;;;;;GAMG;AAEH,+CAA+C;AAC/C,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQxE;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEpE;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,oDAAoD;IACpD,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,CAAA;CACnB;AAQD,wBAAgB,kBAAkB,CAAC,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,CAuBvD;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAMjF;AAED,+CAA+C;AAC/C,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,0BAA0B;AAC1B,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,SAAS,CAAA;IACd,GAAG,EAAE,UAAU,CAAA;IACf,QAAQ,EAAE,QAAQ,CAAA;IAClB,iDAAiD;IACjD,qBAAqB,EAAE,CAAC,UAAU,EAAE,eAAe,KAAK,IAAI,CAAA;CAC7D;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,gBAAgB,CAOvF;AAED,uBAAuB;AACvB,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,GAAG,EAAE,SAAS,CAAA;IACd,GAAG,EAAE,UAAU,CAAA;IACf,QAAQ,EAAE,QAAQ,CAAA;IAClB,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAC5B;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAEvF;AAED,kEAAkE;AAClE,MAAM,WAAW,oBAAoB,CAAC,CAAC,EAAE,CAAC;IACxC,GAAG,EAAE,UAAU,CAAA;IACf,QAAQ,EAAE,QAAQ,CAAA;IAClB,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IAC3B,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;CAC9B;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CASnG;AAED,yBAAyB;AACzB,MAAM,WAAW,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;IAC5C,GAAG,EAAE,UAAU,CAAA;IACf,QAAQ,EAAE,QAAQ,CAAA;IAClB,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IAC3B,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;IAC7B,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,CAAA;CACzB;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAU/G;AAED,4BAA4B;AAC5B,MAAM,WAAW,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;IAC/C,GAAG,EAAE,WAAW,CAAA;IAChB,GAAG,EAAE,UAAU,CAAA;IACf,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACpB,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAA;IAC7B,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,CAAA;CACzB;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAWxH;AAED,wBAAwB;AACxB,MAAM,WAAW,mBAAmB,CAAC,CAAC,EAAE,EAAE;IACxC,GAAG,EAAE,WAAW,CAAA;IAChB,GAAG,EAAE,UAAU,CAAA;IACf,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACpB,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,CAAA;CACzB;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,EAAE,EAAE,CAAC,CAQnG"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../source/core/boot/context.ts"],"names":[],"mappings":"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"}

package/output/core/boot/context.js

@@ -6,7 +6,11 @@ import { SystemError } from '@taicode/common-base';
  * （`generateOpenApi` 不跑 `config` 槽位）读到它时抛 `SystemError('CONFIG_UNAVAILABLE')`
  * —— 让「构造期不得读配置」有运行期护栏，而不仅是文档规则。
  */
-/** 运行时镜像 `Live<T>`：剔除值为 `false` 的键（编译期静态关闭） */
+/**
+ * 运行时镜像 `Live<Value>`：剔除值为 `false` 的键（编译期静态关闭）。
+ *
+ * `resources` 与 `clients` 两个槽位共用这套口径。
+ */
 export function liveResources(resources) {
     const result = {};
     for (const [key, value] of Object.entries(resources)) {
@@ -16,9 +20,43 @@ export function liveResources(resources) {
     }
     return result;
 }
-/** 客户端包的运行时镜像（口径与 `liveResources` 完全一致，另立一名只为调用处可读） */
-export function liveClients(clients) {
-    return liveResources(clients);
+/** 单元外壳的运行时识别（`defineResource` 产物的唯一形状） */
+function isResourceUnit(value) {
+    return typeof value === 'object' && value !== null && 'value' in value && !('then' in value);
+}
+/**
+ * 把 `resources(ctx)` 的返回值拆成「对外视图」与「可执行生命周期列表」。
+ *
+ * 三件事：
+ * - **解包**：`defineResource(client, …)` → 视图里是 `client` 本身；裸对象原样（单元可选）；
+ * - **收集**：有 `setup` / `dispose` 的单元按**对象声明序**收集成
+ *   `{ name, setup, dispose }`，分别交给 `setupResourceUnits` / `disposeResourceUnits`
+ *   执行；
+ * - **剔除**：`false` 键与 `liveResources` 同口径（静态关闭的资源不参与生命周期）。
+ *
+ * ❗识别靠 `'value' in obj && !('then' in obj)`：`Resources` 允许是 Promise（`Awaited<>`
+ * 归一），但**单个资源值本身是 thenable 的极端情况**不当单元——宁可把它当裸值，
+ * 也不要把它错当单元。
+ */
+export function splitResourceUnits(resources) {
+    const view = {};
+    const units = [];
+    for (const [key, value] of Object.entries(resources)) {
+        if (value === false) {
+            continue;
+        }
+        if (isResourceUnit(value)) {
+            view[key] = value.value;
+            const setup = typeof value.setup === 'function' ? value.setup.bind(value) : undefined;
+            const dispose = typeof value.dispose === 'function' ? value.dispose.bind(value) : undefined;
+            if (setup || dispose) {
+                units.push({ name: key, setup, dispose });
+            }
+            continue;
+        }
+        view[key] = value;
+    }
+    return { view, units };
 }
 const CONFIG_WRITE = Symbol('config.write');
 export function createConfigAccess() {

package/output/core/boot/lifecycle.d.ts

@@ -17,7 +17,7 @@ import type { LoggerLike } from '../types.js';
  * - `init` 按**对象声明序**，`dispose` **逆序**；
  * - services 阶段内部**先 flush `ctx.disposer`**（构造期注册的清理），再逐单元 `dispose`。
  *
- * `middlewares` 按**对象键序**注册；它只有 `disposer`，没有逐单元生命周期。
+ * `middlewares` 按**数组顺序**注册；它只有 `disposer`，没有逐单元生命周期。
  */
 export declare const RESOURCES_STAGE = "resources";
 export declare const CONFIG_STAGE = "config";
@@ -25,12 +25,11 @@ export declare const CLIENTS_STAGE = "clients";
 export declare const SERVICES_STAGE = "services";
 export declare const MIDDLEWARES_STAGE = "middlewares";
 export declare const ROUTERS_STAGE = "routers";
-/** `middlewares` 的**注册期日志**阶段标签（与生命周期阶段同名） */
-export declare const MIDDLEWARES_LOG_STAGE = "middlewares";
 /** 生命周期相位（逐单元日志字段 `phase`） */
+export declare const LIFECYCLE_PHASE_SETUP = "setup";
 export declare const LIFECYCLE_PHASE_INIT = "init";
 export declare const LIFECYCLE_PHASE_DISPOSE = "dispose";
-export type LifecyclePhase = typeof LIFECYCLE_PHASE_INIT | typeof LIFECYCLE_PHASE_DISPOSE;
+export type LifecyclePhase = typeof LIFECYCLE_PHASE_SETUP | typeof LIFECYCLE_PHASE_INIT | typeof LIFECYCLE_PHASE_DISPOSE;
 /**
  * 逐单元生命周期日志上下文。
  *
@@ -51,20 +50,53 @@ export interface LifecycleUnitLogFields {
     phase: LifecyclePhase;
 }
 /**
- * `middlewares` 日志名字：**对象键即单元名**（与 `services` 同口径）。
+ * `middlewares` 日志名字：**数组项的名字**（`MiddlewareUnit.name`，或裸函数的占位名 `middleware[i]`）。
  *
- * 键为空串时退路 `<service>:middleware`（仅用于注册期日志，不影响注册序）。
+ * 名字为空串时退路 `<service>:middleware`（仅用于注册期日志，不影响注册序——顺序由数组位置决定）。
  */
-export declare function middlewareUnitName(service: string, key: string): string;
+export declare function middlewareUnitName(service: string, name: string): string;
 /** `initServiceUnits` 入参（参数签名内联对象类型已按 lint 规则外提） */
 export interface InitServiceUnitsParams extends LifecycleLogContext {
     /** `services(ctx)` 返回的对象（**对象键即单元名**） */
     services?: Record<string, unknown>;
 }
+/** `setupResourceUnits` / `disposeResourceUnits` 入参（资源单元有 `setup` / `dispose`） */
+export interface ResourceLifecycleParams extends LifecycleLogContext {
+    /** 有生命周期方法的资源单元（**按 `resources` 对象声明序**） */
+    units?: readonly ResourceSetupUnit[];
+}
+/** 一个资源单元的可执行生命周期（含名字，用于日志） */
+export interface ResourceSetupUnit {
+    /** `resources` 对象里的键 */
+    name: string;
+    /** `setup()` 本身（已从单元外壳上取好）；无 `setup` 时为 `undefined` */
+    setup?: () => void | Promise<void>;
+    /** `dispose()` 本身（已从单元外壳上取好）；无 `dispose` 时为 `undefined` */
+    dispose?: () => void | Promise<void>;
+}
 /**
  * 启动序：`services` 按**对象声明序**逐项 `await init?.()`；逐项打日志。
  */
 export declare function initServiceUnits(params: InitServiceUnitsParams): Promise<void>;
+/**
+ * `resources` 的装配期准备：按**对象声明序**逐项 `await setup()`；逐项打日志。
+ *
+ * 与 `initServiceUnits` 同形，差别在单元来源：资源值往往是第三方对象（没有 `setup` 方法），
+ * 单元外壳由 `buildResources` 在解包时收集成 `{ name, setup, dispose }`。
+ *
+ * **失败即中断**：资源准备失败时后续资源、`config`、`services` 都没有意义，直接冒泡给入口，
+ * 由入口把已构造的资源释放掉（与「端口占用」同一处理）。不放进关闭流程聚合——那不是关闭失败。
+ */
+export declare function setupResourceUnits(params: ResourceLifecycleParams): Promise<void>;
+/**
+ * `resources` 的关闭：按声明序**逆序**逐项 `await dispose()`。
+ *
+ * 与 `disposeServices` 同语义：单元级失败已 `log.error`，此处吞掉以保证单个资源不阻断其他资源。
+ *
+ * 在关闭流程中排在 `flushResources`（阶段 `Disposer`）**之前**：单元 `dispose` 是资源自己的
+ * 正事（断连），而 `disposer` 是本阶段临时产物的逃生口，后者不应挡住前者。
+ */
+export declare function disposeResourceUnits(params: ResourceLifecycleParams): Promise<void>;
 /** `buildDisposeOrder` / `disposeServiceUnits` 入参（参数签名内联对象类型已按 lint 规则外提） */
 export interface DisposeServiceUnitsParams extends LifecycleLogContext {
     /** `services(ctx)` 返回的对象（**对象键即单元名**） */

package/output/core/boot/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../source/core/boot/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,eAAe,cAAc,CAAA;AAC1C,eAAO,MAAM,YAAY,WAAW,CAAA;AACpC,eAAO,MAAM,aAAa,YAAY,CAAA;AACtC,eAAO,MAAM,cAAc,aAAa,CAAA;AACxC,eAAO,MAAM,iBAAiB,gBAAgB,CAAA;AAC9C,eAAO,MAAM,aAAa,YAAY,CAAA;AACtC,8CAA8C;AAC9C,eAAO,MAAM,qBAAqB,gBAAoB,CAAA;AAEtD,8BAA8B;AAC9B,eAAO,MAAM,oBAAoB,SAAS,CAAA;AAC1C,eAAO,MAAM,uBAAuB,YAAY,CAAA;AAChD,MAAM,MAAM,cAAc,GAAG,OAAO,oBAAoB,GAAG,OAAO,uBAAuB,CAAA;AAEzF;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sCAAsC;IACtC,GAAG,CAAC,EAAE,UAAU,CAAA;CACjB;AAED,8DAA8D;AAC9D,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,cAAc,CAAA;CACtB;AAaD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,oDAAoD;AACpD,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAmCD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpF;AAED,6EAA6E;AAC7E,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAaD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQtF;AAED,gDAAgD;AAChD,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IACb,6CAA6C;IAC7C,QAAQ,EAAE,QAAQ,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5E"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../source/core/boot/lifecycle.ts"],"names":[],"mappings":"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"}