@composy/app-core
v0.0.2
Published
Framework-agnostic app runtime planning utilities for LDesign.
Maintainers
Readme
@composy/app-core
LDesign 的框架无关应用启动编排核心。它负责配置分层、服务计划、阶段安装与回滚、启动诊断、运行时契约和默认 Shell 数据,不负责实现 Vue、Vanilla 或其它框架的渲染器。
能力边界
- 配置:
defineAppConfigLayer(s)与composeAppConfig()支持命名层、条件启用、对象深合并、生命周期 hook 串联和最终覆盖。 - 服务:
composeServiceDescriptors()校验phase、唯一 key 和依赖;installByPhases()同 phase 并行、跨 phase 串行,并提供AbortSignal、phase 超时和取消宽限期。 - 释放:
destroyAllServices()按实际 commit 顺序 LIFO 释放;优先调用 descriptor 的dispose(),否则兼容实例上的destroy()。 - 诊断:
buildStartupStatuses()、buildRootRuntimeProps()和buildCapabilityLog()支持非关键诊断降级、DiagnosticSink以及 root props 冲突检测。 - 契约:提供后端、路由、环境变量、开发代理、手动分包、RESTful API/Auth 和隔离存储命名空间工厂。
- Shell projection:提供默认菜单、页面、欢迎摘要、路由/设备/主题 helper,以及后端菜单到路由的安全转换。
安全与不可变约束
- 配置合并会递归拒绝
__proto__、constructor、prototype,并使用自有属性定义避免原型 setter。 - 配置层函数接收深度复制并冻结的
current快照;合成结果、公开默认常量和 preset factory 结果均为运行时不可变数据。 - 后端菜单默认只接受语义图标 ID。兼容内联 SVG 时使用标签和属性 allowlist,事件属性、脚本、外部引用、
style、foreignObject等内容会回退为默认图标。 updateBrowserRoute()保留宿主已有的history.state;resolveViewportDevice()默认使用与 device-core 对齐的 768/1024 断点。applyLocalAppearance()保留旧 DOM 兼容路径,也可通过LocalAppearancePort把主题/尺寸变更交给真正的 theme/size/color Owner。
快速开始
配置分层
import { composeAppConfig, defineAppConfigLayers } from '@composy/app-core'
const config = composeAppConfig(
defineAppConfigLayers([
{ name: 'base', config: { appName: 'my-app' } },
{ name: 'env', config: { debug: true } },
{ name: 'feature', enabled: true, config: { features: ['dashboard'] } },
]),
)服务安装与释放
import {
destroyAllServices,
installByPhases,
type ServiceDescriptors,
} from '@composy/app-core/services/registry'
type Services = {
http: { close: () => void }
api: { destroy: () => void }
}
const descriptors: ServiceDescriptors<Services, object, object> = [
{
key: 'http',
phase: 1,
install: async ({ signal }) => {
signal.throwIfAborted?.()
return { close: () => {} }
},
dispose: (service) => service.close(),
},
{
key: 'api',
phase: 2,
dependencies: ['http'],
install: ({ installed }) => ({
destroy: () => installed.http?.close(),
}),
},
]
const services = await installByPhases(
descriptors,
{ engine: {}, appName: 'my-app', debug: true, options: {} },
{ phaseTimeout: 30_000, cancellationGracePeriod: 250 },
)
await destroyAllServices(services, descriptors)
AbortSignal.throwIfAborted()需要由目标运行时提供;跨运行时服务也可以使用signal.aborted和signal.reason做兼容检查。
运行时与 preset
import {
createDefaultAuthOptions,
createDefaultRouterConfig,
createDefaultStateConfig,
createRuntimeBackendContract,
createRuntimeRoutesContract,
createRestfulApiOptions,
resolveAppStoragePrefix,
} from '@composy/app-core'
const backend = createRuntimeBackendContract()
const routes = createRuntimeRoutesContract({ defaultPath: '/welcome/overview' })
const state = createDefaultStateConfig({ appId: 'console' })
const auth = createDefaultAuthOptions({ authBaseUrl: backend.authBaseUrl }, { appId: 'console' })
const api = createRestfulApiOptions({ apiBaseUrl: backend.apiBaseUrl }, backend.paths)
const router = createDefaultRouterConfig(routes.localExamples, {
roles: ['operator'],
})
const prefix = resolveAppStoragePrefix({ appId: 'console' }, 'state')createDefaultRouterConfig() 不会猜测 admin 超级角色或 * 通配权限;产品策略必须通过
roles、superRole、superPermission 显式注入。状态和认证默认使用 ldesign:<appId>:<scope>:
命名空间,避免同源多 App 互相覆盖。
公开入口
根入口 @composy/app-core 聚合 config、services、shell 和 template presets。npm 公开的子路径只有:
@composy/app-core/services/registry@composy/app-core/shell@composy/app-core/package.json
不要依赖未导出的深层源码路径。重要类型包括
ServiceDescriptor、ServiceInstallContext、InstallByPhasesOptions、ServiceDisposer、DiagnosticSink、RuntimeAppIdentityOptions、LocalAppearancePort
和 AppShellMenuItem。
主要签名
function composeAppConfig<TOptions extends object>(
layers: readonly AppConfigLayer<TOptions>[],
options?: ComposeAppConfigOptions<TOptions>,
): TOptions
function installByPhases<TServices extends object, TOptions, TEngine>(
descriptors: ServiceDescriptors<TServices, TOptions, TEngine>,
ctx: Omit<ServiceInstallContext<TServices, TOptions, TEngine>, 'installed' | 'signal'> & {
signal?: AbortSignal
},
options?: InstallByPhasesOptions,
): Promise<TServices>
function destroyAllServices<TServices extends object, TOptions, TEngine>(
services: TServices,
descriptors: ServiceDescriptors<TServices, TOptions, TEngine>,
installationOrder?: readonly string[],
): Promise<void>
function createRestfulAuthOptions(
runtimeEnv: Pick<TemplateRuntimeEnv, 'authBaseUrl'>,
identity?: RuntimeAppIdentityOptions,
): RestfulAuthOptions诊断规则
createStatus 和 capability extra 默认是非关键诊断:回调异常会交给
DiagnosticSink,不会让已经完成的启动流程失败。需要阻止启动时,在 descriptor 上设置
critical: true。多个服务贡献相同 root prop 时,必须通过 overrideProps 显式声明覆盖,否则抛出
RootPropsCollisionError。
构建与发布
本包使用 @composy/builder,默认 bundler 为 rolldown,产物目录为
es/、esm/、lib/、dist/,并提供 ESM/CJS/UMD、声明文件和 sourcemap。@composy/* 与
@ldesign/* 依赖均作为 external 处理。dist/index.min.js 是实际压缩入口,UMD 全局名为
LDesignAppCore。
Core 的 Builder 配置位于 .ldesign/builder.config.ts,TypeScript 配置位于 .ldesign/;根 tsconfig.json 文件是兼容入口。build 脚本在 Builder 完成后归一化产物并执行 package output contract 检查,确保 exports、声明文件、CJS 入口和 CDN 入口都能解析到实际文件。
pnpm --filter @composy/app-core type-check
pnpm --filter @composy/app-core type-check:test
pnpm --filter @composy/app-core lint:check
pnpm --filter @composy/app-core test:run
pnpm --filter @composy/app-core build
npm pack --dry-run --ignore-scripts发布白名单包含 README.md、LICENSE、CHANGELOG.md、es/、esm/、lib/ 和
dist/。构建后应继续检查 package.json 的 exports、DTS 和 tarball 文件集合一致。
目录
src/config/ 配置层与运行时契约
src/services/registry/ 服务计划、安装、回滚、诊断
src/shell/ 默认 Shell 数据与兼容 helper
src/template-presets/ 模板默认配置工厂
src/shared/immutable.ts 配置/默认值复制与冻结工具License
MIT
