afx-team / afx-team/evjs

Refine @evjs/ev public export paths and boundaries

未关闭
#134 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
主要语言
TypeScript
星标
23
派生
6
平均合并
10 小时 8 分钟
30 天内合并 PR
27

描述

## Background

Follow-up to #133. An audit of `@evjs/ev` at [a4037cd](https://github.com/afx-team/evjs/commit/a4037cd14ca0109ee766ffa813c26a45173a1216) found 26 explicit export paths: 12 public entries and 14 `_internal` entries. Most boundaries are coherent, but some public paths describe their contents poorly or expose framework implementation details.

Track the cleanup here for a later implementation, independently of the middleware PR.

## Current public surface

Paths below omit the `@evjs/ev` prefix.

| Path | Main exports / responsibility | Proposed direction |
| --- | --- | --- |
| Root | `defineConfig`, `definePageConfig`, basic config types | Keep the convenient config entry |
| `/config` | Config authoring, `merge`, resolution helpers, config types | Narrow implementation-only exports |
| `/plugin` | `definePlugin`, `pluginOptions`, hooks, contributions, framework views | Keep the plugin lifecycle vocabulary together |
| `/api` | `withMiddlewares`, `RouteHandlerFn` | Keep |
| `/middleware` | `requestLogger`, middleware and logging types | Keep |
| `/route` | `usePage*`, `useRouteParams`, Page route types | Rename to `/page`; retain the existing exports and behavior |
| `/navigation` | Links, outlets, navigation, locations, History | Keep |
| `/query` | Query hooks/client, server-function query helpers | Keep the shared query/cache layer |
| `/server-context` | Request context, cookies, `waitUntil`, `ServerError` | Keep request helpers; consider error ownership separately |
| `/transport` | Transport configuration, function references/metadata, errors | Remove generated-code-only reference creation |
| `/deployment` | Node/Static/Edge adapters and deployment file generation | Keep |
| `/build-tools` | `loadConfigFile`, `LoadConfigFileOptions` | Pending removal |

## Page API entry decision

Rename `@evjs/ev/route` to `@evjs/ev/page` as the public entry for authoring framework Pages and their layouts. Move the existing exports together: `usePage*`, `useRouteParams`, `PageProps`, `Register`, and the Page route types. Keep the existing `/navigation` surface.

Preserve hook names, signatures, and runtime semantics:

- `usePageParams()` reads the Page context and supports SPA, MPA, and RSC.
- `useRouteParams()` reads the merged parameters of the active SPA route branch and works in both Pages and layouts. Its scope does not change with the calling component's position in the tree.
- Keep the existing explicit generic annotations and generated route type registration. Update their import and augmentation targets for `/page`.

This work changes the public import boundary and its supporting references. Per-layout parameter filtering, new component-prop contracts, renamed parameter hooks, and per-file generated type imports such as `./+types/layout` are outside this issue.

## Proposed work

- [ ] **Rename `/route` to `/page`.** Move the full current authoring surface, including `usePageContext`, `usePageLoaderData`, `usePageParams`, `usePageSearch`, `useRouteParams`, `PageProps`, `Register`, and the related Page route types. Update the package export map, module augmentation targets, navigation type dependencies, generated declarations, and RSC aliases together. Preserve the existing parameter model and type-generation design.
- [ ] **Narrow `/config`.** Remove the public exports of `resolveBundlerConfig`, `resolvePluginsConfig`, `PageAnchorMetadata`, and `PageRouteDiscoveryMetadata`. Keep local validators and discovery metadata in their internal implementation domains, exposing cross-package build contracts through `_internal/build` only where needed. Review `ResolvedPageRoutingConfig.metadata` and plugin config views as well: removing named exports alone does not hide internal structure. Preserve useful authoring/normalization APIs and types needed by public plugin contexts.
- [ ] **Narrow `/transport`.** Remove its public `createServerReference` export; generated code already uses `/_internal/client/server-functions`. Preserve transport configuration, adapters, request controls, and error handling. `getFnId`/`getFnName` may serve advanced metadata consumers, and `RuntimeTransportOptions` supports host-provided `__EVJS_TRANSPORT__`; do not remove them merely because examples do not use them.
- [ ] **Remove the public `/build-tools` entry.** Remove it from the package export map. Keep `loadConfigFile` and `LoadConfigFileOptions` available to framework tooling through the existing `/_internal/build` entry; no new public replacement entry is planned.

## Lower-priority design question

`ServerError` under `/server-context` and `ServerFunctionError` under `/transport` describe the same server-function error protocol. Consider a shared `/server-functions` entry for error classes and shared types if that improves the authoring model. Such an entry should avoid loading client transport or Node request-context runtimes. This decision can be handled separately from the four primary changes.

## Boundaries to retain

- The root/config overlap is an intentional convenience; plugin and query types belong with their respective authoring APIs.
- The 14 `_internal` entries separate build tooling, generated startup, ordinary React and React Server contexts, pure types, polyfill side effects, and Node/Fetch runtimes. Preserve these dependency and execution-environment boundaries.
- Keep this work focused on `@evjs/ev`; changes to standalone `@evjs/client` or `@evjs/server` contracts require their own rationale.

## Acceptance criteria

- [ ] Package exports and runtime/type surface tests enforce the agreed public entry boundaries.
- [ ] `/page` exports all members previously exposed by `/route`, including both `usePageParams` and `useRouteParams`, with their existing signatures and runtime behavior.
- [ ] The public `/build-tools` entry is removed, while CLI and bundler tooling can still load configuration through `/_internal/build`.
- [ ] Generated Page type registration, typed navigation, and SPA/MPA/RSC Page data behavior continue to work with the new paths.
- [ ] Generated server-function references, custom transports, and host-provided transport options continue to work.
- [ ] Examples, scaffolds, repository authoring guidance, and English/Chinese docs use the final paths. Record import migrations and breaking changes in the changelog.
- [ ] Run the focused package-surface/type-generation/transport tests and repository gates: `npm run check-types`, `npm run lint`, `npm test`, `npm --workspace evjs-docs run build`, and `git diff --check`.

## Source references

- [Package export map](https://github.com/afx-team/evjs/blob/a4037cd14ca0109ee766ffa813c26a45173a1216/packages/ev/package.json)
- [Page authoring exports](https://github.com/afx-team/evjs/blob/a4037cd14ca0109ee766ffa813c26a45173a1216/packages/ev/src/route/index.ts), [generated type registration](https://github.com/afx-team/evjs/blob/a4037cd14ca0109ee766ffa813c26a45173a1216/packages/ev/src/_internal/build/typegen/page-route-types.ts#L19), [RSC alias](https://github.com/afx-team/evjs/blob/a4037cd14ca0109ee766ffa813c26a45173a1216/packages/bundler-webpack/src/adapter/config/create-config.ts#L963)
- [Public config exports](https://github.com/afx-team/evjs/blob/a4037cd14ca0109ee766ffa813c26a45173a1216/packages/ev/src/config/index.ts), [internal discovery metadata](https://github.com/afx-team/evjs/blob/a4037cd14ca0109ee766ffa813c26a45173a1216/packages/ev/src/config/resolution.ts#L540)
- [Public transport exports](https://github.com/afx-team/evjs/blob/a4037cd14ca0109ee766ffa813c26a45173a1216/packages/ev/src/transport/index.ts), [generated reference entry](https://github.com/afx-team/evjs/blob/a4037cd14ca0109ee766ffa813c26a45173a1216/packages/ev/src/_internal/build/types.ts#L27)
- [Public config loader entry](https://github.com/afx-team/evjs/blob/a4037cd14ca0109ee766ffa813c26a45173a1216/packages/ev/src/build-tools/index.ts)

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。