npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@composy/app-core

v0.0.2

Published

Framework-agnostic app runtime planning utilities for LDesign.

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