@ivlev-dev/silent-server 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,163 @@
1
+ # @ivlev-dev/silent-server
2
+
3
+ SSR для Silent Framework без jsdom и linkedom: собственный мини-DOM, асинхронные ViewModel и гидрация серверной разметки.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@ivlev-dev/silent-server)](https://www.npmjs.com/package/@ivlev-dev/silent-server)
6
+ [![license](https://img.shields.io/npm/l/@ivlev-dev/silent-server)](https://github.com/ivlev-dev/silent-framework/blob/main/LICENSE)
7
+ [![node](https://img.shields.io/node/v/@ivlev-dev/silent-server)](https://www.npmjs.com/package/@ivlev-dev/silent-server)
8
+
9
+ ## Возможности
10
+
11
+ - `renderToString` возвращает `{ html, head }`: разметку приложения и метаданные для `<head>`.
12
+ - Собственный мини-DOM: парсер шаблонов компилятора, документ, `TreeWalker` и сериализатор без внешних DOM-зависимостей.
13
+ - Асинхронные ViewModel, `Suspense` и `lazy` дожидаются до сериализации — в результат попадает итоговое содержимое.
14
+ - `<title>` из любого компонента выносится из дерева в `RenderResult.head`, как в React 19.
15
+ - Серверные якоря и маркеры `data-silent-a-*` сохраняются для адоптации узлов при `hydrate`.
16
+ - Вызовы сериализуются внутренней очередью, а DOM-глобалы живут только на время рендера.
17
+
18
+ ## Установка
19
+
20
+ ```bash
21
+ pnpm add @ivlev-dev/silent-server
22
+ ```
23
+
24
+ ```bash
25
+ npm install @ivlev-dev/silent-server
26
+ ```
27
+
28
+ ```bash
29
+ yarn add @ivlev-dev/silent-server
30
+ ```
31
+
32
+ Пакет поставляется как ESM с объявлениями типов и требует Node.js 22 или новее.
33
+
34
+ ## Быстрый старт
35
+
36
+ ```ts
37
+ import { createServer } from "node:http";
38
+ import { renderToString } from "@ivlev-dev/silent-server";
39
+ import { App } from "./app.js";
40
+
41
+ createServer(async (request, response) => {
42
+ try {
43
+ const { html, head } = await renderToString(App, {
44
+ props: { title: "Silent Framework" },
45
+ });
46
+
47
+ const page = `<!doctype html>
48
+ <html lang="ru">
49
+ <head>
50
+ <meta charset="utf-8" />
51
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
52
+ ${head}
53
+ </head>
54
+ <body>
55
+ <div id="app">${html}</div>
56
+ <script type="module" src="/client.js"></script>
57
+ </body>
58
+ </html>`;
59
+
60
+ response.setHeader("content-type", "text/html; charset=utf-8");
61
+ response.end(page);
62
+ } catch (error) {
63
+ response.statusCode = 500;
64
+ response.end("Internal Server Error");
65
+ console.error(error);
66
+ }
67
+ }).listen(3000);
68
+ ```
69
+
70
+ `html` не содержит `<title>`: заголовок уже находится в `head`. Приложение должно быть собрано компилятором Silent Framework — например, плагином `@ivlev-dev/silent-vite` — так же, как для клиентского рендера.
71
+
72
+ ## Гидрация на клиенте
73
+
74
+ Клиентский вход использует `hydrate` из `@ivlev-dev/silent-core` вместо `mount` и получает те же `props`, что и сервер:
75
+
76
+ ```ts
77
+ import { hydrate } from "@ivlev-dev/silent-core";
78
+ import { App } from "./app.js";
79
+
80
+ const target = document.querySelector("#app");
81
+ if (target === null) {
82
+ throw new Error("#app not found");
83
+ }
84
+
85
+ void hydrate(target, App, {
86
+ props: { title: "Silent Framework" },
87
+ onMismatch: (error) => console.warn(error.message),
88
+ });
89
+ ```
90
+
91
+ `hydrate` не перерисовывает приложение заново: view находит свои маркеры, `templateHoles` занимает существующие узлы, а `For`, `Show`, `Suspense`, `lazy` и `fragment` адоптируют свои якоря и регионы. Маркеры `data-silent-a-*` снимаются с адоптированных элементов, значения применяются заново. Пока асинхронные ViewModel не завершились, серверная разметка остаётся видимой, а прелоадеры не показываются.
92
+
93
+ Заголовок страницы в серверной разметке отсутствует: клиент создаёт `<title>` заново и вставляет его в `document.head`. При несовпадении формы узла бросается `HydrationMismatchError`, ближайший view откатывается на клиентский рендер, а ошибка приходит в `onMismatch`.
94
+
95
+ ## Асинхронные ViewModel
96
+
97
+ `renderToString` создаёт корневой компонент и ждёт его `ready`, `whenIdle` и `flushSync`, поэтому асинхронное разрешение ViewModel через DI, границы `Suspense` и загрузка `lazy` завершаются до сериализации:
98
+
99
+ ```tsx
100
+ import { lazy, Suspense } from "@ivlev-dev/silent-core";
101
+
102
+ const Profile = lazy<{ id: number }>(() => import("./profile.js"));
103
+
104
+ export function App() {
105
+ return (
106
+ <Suspense fallback={<span>Загрузка...</span>}>
107
+ <Profile id={1} />
108
+ </Suspense>
109
+ );
110
+ }
111
+ ```
112
+
113
+ Сервер дожидается загрузки модуля и асинхронных view внутри границы, после чего сериализует итоговое содержимое. Опция `preloader` задаёт прелоадер на время рендера, `container` — DI-контейнер корневого view, а `onError` перехватывает ошибки компонентов: без обработчика первая ошибка отклоняет промис `renderToString`.
114
+
115
+ ## API
116
+
117
+ | Символ | Назначение |
118
+ | --- | --- |
119
+ | `renderToString(app, options?)` | Рендерит корневой компонент в `Promise<RenderResult>`; вызовы сериализуются внутренней очередью. |
120
+ | `RenderResult` | Результат рендера: `{ html, head }`. |
121
+ | `RenderResult.html` | Сериализованная разметка приложения без `<title>`, с якорями и маркерами для гидрации. |
122
+ | `RenderResult.head` | HTML метаданных, вынесенных из дерева, в первую очередь `<title>`. |
123
+ | `RenderOptions` | Опции рендера. |
124
+ | `RenderOptions.props` | Props корневого компонента. |
125
+ | `RenderOptions.container` | DI-контейнер корневого view; по умолчанию корневой контейнер `@ivlev-dev/silent-di`. |
126
+ | `RenderOptions.preloader` | Прелоадер на время рендера. |
127
+ | `RenderOptions.onError` | Обработчик ошибок компонентов; если не задан, первая ошибка отклоняет промис. |
128
+
129
+ ## Ограничения и совместимость
130
+
131
+ - Только ESM и Node.js `>=22`; пакет не содержит CommonJS-сборки.
132
+ - Мини-DOM реализует подмножество, необходимое шаблонам компилятора; произвольные браузерные API внутри компонентов недоступны.
133
+ - DOM-глобалы общие на процесс, поэтому параллелизм SSR внутри процесса ограничен внутренней очередью `renderToString`.
134
+ - В Vite-сборке держите рантайм внешним, иначе приложение и `renderToString` получат разные экземпляры модулей:
135
+
136
+ ```ts
137
+ export default defineConfig({
138
+ plugins: [silent()],
139
+ ssr: {
140
+ external: [
141
+ "@ivlev-dev/silent-core",
142
+ "@ivlev-dev/silent-di",
143
+ "@ivlev-dev/silent-reactivity",
144
+ "@ivlev-dev/silent-server",
145
+ ],
146
+ },
147
+ });
148
+ ```
149
+
150
+ - Гидрация адоптирует только значения, созданные через `template()`/`templateHoles()`; DOM, собранный вручную, рендерится клиентски.
151
+ - `<title>` должен быть прямым потомком корневого элемента шаблона view; вложенные глубже заголовки вызывают откат к клиентскому рендеру.
152
+ - Несколько заголовков одновременно не дедуплицируются — рендерите один `<title>`. Заголовки внутри `<svg>` и с `itemProp` не выносятся в `head`.
153
+
154
+ ## Ссылки
155
+
156
+ - Репозиторий: https://github.com/ivlev-dev/silent-framework
157
+ - Документация: https://github.com/ivlev-dev/silent-framework/blob/main/docs/api/core.md
158
+ - CHANGELOG: https://github.com/ivlev-dev/silent-framework/blob/main/CHANGELOG.md
159
+ - Issues: https://github.com/ivlev-dev/silent-framework/issues
160
+
161
+ ---
162
+
163
+ MIT © ivlev-dev
package/dist/index.d.ts CHANGED
@@ -1,2 +1,3 @@
1
1
  export { renderToString, type RenderOptions, type RenderResult } from "./render.js";
2
+ export { renderToStream, type StreamOptions } from "./stream.js";
2
3
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC"}
package/dist/index.js CHANGED
@@ -1,2 +1,3 @@
1
1
  export { renderToString } from "./render.js";
2
+ export { renderToStream } from "./stream.js";
2
3
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAyC,MAAM,aAAa,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAyC,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,cAAc,EAAsB,MAAM,aAAa,CAAC"}
@@ -0,0 +1,8 @@
1
+ import type { AnyComponent } from "@ivlev-dev/silent-core";
2
+ import { type RenderOptions } from "./render.js";
3
+ export interface StreamOptions extends RenderOptions {
4
+ readonly chunkSize?: number;
5
+ readonly onHead?: (head: string) => void;
6
+ }
7
+ export declare function renderToStream(app: AnyComponent, options?: StreamOptions): ReadableStream<string>;
8
+ //# sourceMappingURL=stream.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjE,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAID,wBAAgB,cAAc,CAC5B,GAAG,EAAE,YAAY,EACjB,OAAO,GAAE,aAAkB,GAC1B,cAAc,CAAC,MAAM,CAAC,CA2BxB"}
package/dist/stream.js ADDED
@@ -0,0 +1,30 @@
1
+ import { renderToString } from "./render.js";
2
+ const DEFAULT_CHUNK_SIZE = 16 * 1024;
3
+ export function renderToStream(app, options = {}) {
4
+ const chunkSize = options.chunkSize !== undefined && options.chunkSize > 0
5
+ ? options.chunkSize
6
+ : DEFAULT_CHUNK_SIZE;
7
+ const onHead = options.onHead;
8
+ const renderOptions = {
9
+ ...(options.props !== undefined ? { props: options.props } : {}),
10
+ ...(options.container !== undefined ? { container: options.container } : {}),
11
+ ...(options.preloader !== undefined ? { preloader: options.preloader } : {}),
12
+ ...(options.onError !== undefined ? { onError: options.onError } : {}),
13
+ };
14
+ return new ReadableStream({
15
+ async start(controller) {
16
+ try {
17
+ const { html, head } = await renderToString(app, renderOptions);
18
+ onHead?.(head);
19
+ for (let index = 0; index < html.length; index += chunkSize) {
20
+ controller.enqueue(html.slice(index, index + chunkSize));
21
+ }
22
+ controller.close();
23
+ }
24
+ catch (error) {
25
+ controller.error(error);
26
+ }
27
+ },
28
+ });
29
+ }
30
+ //# sourceMappingURL=stream.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"stream.js","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAsB,MAAM,aAAa,CAAC;AAOjE,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,CAAC;AAErC,MAAM,UAAU,cAAc,CAC5B,GAAiB,EACjB,OAAO,GAAkB,EAAE;IAE3B,MAAM,SAAS,GACb,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,GAAG,CAAC;QACtD,CAAC,CAAC,OAAO,CAAC,SAAS;QACnB,CAAC,CAAC,kBAAkB,CAAC;IACzB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,MAAM,aAAa,GAAkB;QACnC,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC;IAEF,OAAO,IAAI,cAAc,CAAS;QAChC,KAAK,CAAC,KAAK,CAAC,UAAU;YACpB,IAAI,CAAC;gBACH,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;gBAChE,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;gBACf,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;oBAC5D,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC;gBAC3D,CAAC;gBACD,UAAU,CAAC,KAAK,EAAE,CAAC;YACrB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ivlev-dev/silent-server",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "main": "./dist/index.js",
@@ -15,9 +15,9 @@
15
15
  "dist"
16
16
  ],
17
17
  "dependencies": {
18
- "@ivlev-dev/silent-core": "0.1.1",
19
- "@ivlev-dev/silent-di": "0.1.1",
20
- "@ivlev-dev/silent-reactivity": "0.1.1"
18
+ "@ivlev-dev/silent-core": "0.2.0",
19
+ "@ivlev-dev/silent-di": "0.2.0",
20
+ "@ivlev-dev/silent-reactivity": "0.2.0"
21
21
  },
22
22
  "devDependencies": {
23
23
  "jsdom": "^31.0.0",