npm - @finesoft/front - Versions diffs - 0.1.75 → 0.1.77 - Mend

@finesoft/front 0.1.75 → 0.1.77

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.

Files changed (58) hide show

package/README.md +2 -411
package/dist/browser.d.mts +2 -0
package/dist/browser.mjs +1 -0
package/dist/index.d.mts +2 -1248
package/dist/index.mjs +54 -3557
package/dist/server-data-DGbiKzMS.d.mts +1249 -0
package/dist/start-app-BdXBCcor.mjs +2 -0
package/docs/01-getting-started.md +230 -0
package/docs/02-routing-and-controllers.md +197 -0
package/docs/03-middleware.md +214 -0
package/docs/04-rendering-and-hydration.md +271 -0
package/docs/05-i18n.md +243 -0
package/docs/06-http-client.md +286 -0
package/docs/07-di-container.md +264 -0
package/docs/08-observability.md +290 -0
package/docs/09-server-and-deployment.md +242 -0
package/docs/10-features-platform-pwa.md +238 -0
package/docs/README.md +72 -0
package/docs/advanced/custom-action-handler.md +248 -0
package/docs/advanced/custom-adapter.md +264 -0
package/docs/advanced/custom-event-recorder.md +318 -0
package/docs/advanced/inline-proxy-codegen.md +200 -0
package/docs/advanced/multi-tenant-scopes.md +330 -0
package/docs/engineering/ci-release-flow.md +244 -0
package/docs/engineering/project-structure.md +296 -0
package/docs/engineering/testing.md +317 -0
package/docs/pitfalls/container-scope-leak.md +215 -0
package/docs/pitfalls/i18n-bundle-size.md +182 -0
package/docs/pitfalls/proxy-binary-payloads.md +133 -0
package/docs/pitfalls/redirect-vs-rewrite.md +147 -0
package/docs/pitfalls/ssr-hydration-mismatch.md +163 -0
package/docs/pitfalls/ssr-vs-csr-globals.md +176 -0
package/docs/zh/01-getting-started.md +230 -0
package/docs/zh/02-routing-and-controllers.md +197 -0
package/docs/zh/03-middleware.md +214 -0
package/docs/zh/04-rendering-and-hydration.md +271 -0
package/docs/zh/05-i18n.md +243 -0
package/docs/zh/06-http-client.md +286 -0
package/docs/zh/07-di-container.md +264 -0
package/docs/zh/08-observability.md +287 -0
package/docs/zh/09-server-and-deployment.md +242 -0
package/docs/zh/10-features-platform-pwa.md +238 -0
package/docs/zh/README.md +72 -0
package/docs/zh/advanced/custom-action-handler.md +248 -0
package/docs/zh/advanced/custom-adapter.md +264 -0
package/docs/zh/advanced/custom-event-recorder.md +318 -0
package/docs/zh/advanced/inline-proxy-codegen.md +200 -0
package/docs/zh/advanced/multi-tenant-scopes.md +330 -0
package/docs/zh/engineering/ci-release-flow.md +244 -0
package/docs/zh/engineering/project-structure.md +296 -0
package/docs/zh/engineering/testing.md +317 -0
package/docs/zh/pitfalls/container-scope-leak.md +215 -0
package/docs/zh/pitfalls/i18n-bundle-size.md +182 -0
package/docs/zh/pitfalls/proxy-binary-payloads.md +133 -0
package/docs/zh/pitfalls/redirect-vs-rewrite.md +147 -0
package/docs/zh/pitfalls/ssr-hydration-mismatch.md +163 -0
package/docs/zh/pitfalls/ssr-vs-csr-globals.md +176 -0
package/package.json +12 -3

package/docs/05-i18n.md ADDED Viewed

@@ -0,0 +1,243 @@
+# 5. Internationalization
+The framework handles four i18n concerns:
+1. **Resolving the user's locale** (cookie, accept-language, manual override)
+2. **Loading the right dictionary** without bloating the bundle
+3. **Translating strings** with interpolation and pluralization
+4. **Rendering the correct text direction** (LTR / RTL)
+## Locale resolution
+Pass a default `locale` to `Framework.create()`:
+```ts
+const framework = Framework.create({ locale: "zh-Hans" });
+```
+For SSR, locale priority (highest wins):
+1. `resolveLocale` callback in `createSSRRender({ resolveLocale })` — has access to request headers / cookies
+2. `locale` in `frameworkConfig` (via DI container)
+For the browser, the locale is whatever the server resolved (sent via the `<html lang>` attribute). `startBrowserApp` reads it and writes it back into `documentElement.lang`/`dir` on hydration.
+### Reading at runtime
+```ts
+const { lang, dir } = framework.getLocale();
+// { lang: "zh-Hans", dir: "ltr" }
+```
+## Custom resolver
+```ts
+import { parseAcceptLanguage } from "@finesoft/front";
+createSSRRender({
+    bootstrap,
+    resolveLocale(ctx) {
+        // 1. cookie
+        const fromCookie = ctx.getCookie("locale");
+        if (fromCookie && isSupported(fromCookie)) return fromCookie;
+        // 2. accept-language
+        const accept = ctx.getHeader("accept-language");
+        const best = parseAcceptLanguage(accept ?? "").find((l) => isSupported(l.tag));
+        if (best) return best.tag;
+        // 3. fallback
+        return "en-US";
+    },
+    async renderApp(page) {
+        /* ... */
+    },
+});
+```
+`parseAcceptLanguage` parses `Accept-Language: en;q=0.9,fr;q=0.8` into ranked tags. Tags with `q=0` are filtered out.
+## Dictionary loading via `messagesDir`
+The recommended pattern is JSON files + the Vite plugin:
+```ts
+// vite.config.ts
+finesoftFrontViteConfig({
+    ssr: { entry: "src/ssr.ts" },
+    i18n: { messagesDir: "src/locales" },
+});
+```
+```
+src/locales/
+├── en-US.json
+├── zh-Hans.json
+└── ja-JP.json
+```
+```json
+// src/locales/zh-Hans.json
+{
+    "hello": "你好",
+    "welcome": "欢迎，{name}",
+    "items.one": "{count} 个项目",
+    "items.other": "{count} 个项目"
+}
+```
+The plugin generates code that:
+- Loads only the resolved locale's JSON (server side: read from disk; browser side: dynamic import chunk)
+- Caches across requests on the server
+- Is keyed by the resolved locale, so changing locale triggers a re-fetch
+You **do not** serialize the dictionary into the HTML payload. The browser fetches its locale chunk in parallel with the initial render.
+## `SimpleTranslator`
+For in-memory dictionaries (small apps, tests, or manually loaded data):
+```ts
+import { SimpleTranslator } from "@finesoft/front";
+const t = new SimpleTranslator({
+    locale: "zh-Hans",
+    messages: {
+        hello: "你好",
+        welcome: "欢迎，{name}",
+        "items.one": "{count} 个项目",
+        "items.other": "{count} 个项目",
+    },
+});
+t.t("hello"); // "你好"
+t.t("welcome", { name: "World" }); // "欢迎，World"
+t.plural("items", 5); // "5 个项目"
+t.plural("items", 1); // "1 个项目"
+```
+### Interpolation
+Curly-brace placeholders: `{name}`, `{count}`, `{0}`. Values are HTML-escaped only if you pass them through your view layer's escape — `SimpleTranslator` returns raw strings.
+### Pluralization
+Backed by `Intl.PluralRules`. Keys use CLDR plural categories: `zero`, `one`, `two`, `few`, `many`, `other`. Always provide `other` as the fallback.
+```json
+{
+    "messages.zero": "No messages",
+    "messages.one": "1 message",
+    "messages.other": "{count} messages"
+}
+```
+```ts
+t.plural("messages", 0); // "No messages"
+t.plural("messages", 1); // "1 message"
+t.plural("messages", 5); // "5 messages"
+```
+Languages with richer plural systems (Russian, Arabic) automatically pick `few`/`many` if present.
+## Integrating with DI
+Register the translator in your container:
+```ts
+container.register(
+    "translator",
+    () =>
+        new SimpleTranslator({
+            locale: framework.getLocale().lang,
+            messages: loadedMessages,
+        }),
+);
+```
+Or use the framework's built-in DI key:
+```ts
+import { DEP_KEYS } from "@finesoft/front";
+container.register(DEP_KEYS.TRANSLATOR, () => translator);
+// Later, in any component or controller:
+const t = framework.container.resolve(DEP_KEYS.TRANSLATOR);
+t.t("hello");
+```
+## Custom message source
+If you need to load messages from an API or CDN, override `loadMessages` on `createSSRRender` / `startBrowserApp`:
+```ts
+createSSRRender({
+    bootstrap,
+    async loadMessages(locale) {
+        const resp = await fetch(`https://cdn.example.com/i18n/${locale}.json`);
+        return resp.json();
+    },
+    async renderApp(page) {
+        /* ... */
+    },
+});
+```
+This **overrides** the Vite-generated loader. Use it when:
+- Translations are managed by a service (Lokalise, Phrase) and fetched at runtime
+- You want stale-while-revalidate caching
+- You need to merge multiple namespaces from different sources
+For most apps, the file-based loader is enough — it ships exactly one locale's bytes, no runtime fetch needed.
+## RTL support
+```ts
+import { isRtl, getTextDirection, getLocaleAttributes } from "@finesoft/front";
+isRtl("ar"); // true
+isRtl("he"); // true
+isRtl("zh-Hans"); // false
+getTextDirection("ar"); // "rtl"
+getTextDirection("en"); // "ltr"
+getLocaleAttributes("ar-SA"); // { lang: "ar-SA", dir: "rtl" }
+```
+The framework sets `<html dir="rtl">` automatically for RTL locales. Your CSS should use logical properties (`margin-inline-start` instead of `margin-left`) for layout that mirrors correctly.
+```css
+/* good */
+.card {
+    padding-inline-start: 16px;
+}
+/* avoid — won't mirror in RTL */
+.card {
+    padding-left: 16px;
+}
+```
+## Locale switching
+For a user-initiated locale switch:
+1. Update the cookie / user preference on the server: `Set-Cookie: locale=ja-JP`.
+2. Trigger a full reload (`window.location.reload()`) so the server resolves the new locale, loads the new dictionary, and re-renders.
+A purely client-side switch is possible but skips SSR re-render — first-paint will show the old locale until the new dictionary loads. For most apps the full reload is simpler and correct.
+## Caveats
+- **Don't serialize the entire dictionary into HTML.** It bloats first paint. The file-based loader sends only the current locale, and only its chunk. See [pitfalls: i18n bundle size](./pitfalls/i18n-bundle-size.md).
+- **Don't mutate the dictionary at runtime.** The cache assumes immutability. If you need dynamic strings (user-generated content), keep them separate from translations.
+- **`SimpleTranslator` is synchronous.** If your translation source is async, load it before the controller runs (e.g., in `beforeLoad` or `onBeforeStart`).
+## Next
+- [HTTP client](./06-http-client.md) — making requests, with locale headers when needed
+- [Pitfalls: i18n bundle size](./pitfalls/i18n-bundle-size.md) — keeping translations off the critical path

package/docs/06-http-client.md ADDED Viewed

@@ -0,0 +1,286 @@
+# 6. HTTP client
+`HttpClient` is a thin, typed wrapper over `fetch` that gives you:
+- Class-based subclassing for organizing API surface
+- Request/response interceptors for auth, logging, retries
+- Structured `HttpError` instead of opaque rejections
+- Case-insensitive header handling that matches `Response.headers.get()` semantics
+It is **not** an attempt to be axios. It is a sharp small tool aimed at the framework's needs.
+## Subclassing
+The intended usage is to subclass for each logical API surface:
+```ts
+import { HttpClient } from "@finesoft/front";
+interface User {
+    id: string;
+    name: string;
+}
+interface NewUser {
+    name: string;
+    email: string;
+}
+export class UserApi extends HttpClient {
+    async list(): Promise<User[]> {
+        return this.get<User[]>("/users");
+    }
+    async getById(id: string): Promise<User> {
+        return this.get<User>(`/users/${id}`);
+    }
+    async create(data: NewUser): Promise<User> {
+        return this.post<User>("/users", data);
+    }
+    async update(id: string, data: Partial<NewUser>): Promise<User> {
+        return this.patch<User>(`/users/${id}`, data);
+    }
+    async delete(id: string): Promise<void> {
+        await this.delete(`/users/${id}`);
+    }
+}
+```
+Each subclass instance binds a `baseUrl` and shared options.
+## Instantiation
+```ts
+const api = new UserApi({
+    baseUrl: "/api",
+    defaultHeaders: {
+        "X-App-Version": "1.0.0",
+    },
+});
+```
+Register in DI so controllers can resolve it:
+```ts
+import { DEP_KEYS } from "@finesoft/front";
+container.register("userApi", () => new UserApi({ baseUrl: "/api" }));
+```
+Then in a controller:
+```ts
+async execute(params, container) {
+    const api = container.resolve<UserApi>("userApi");
+    const users = await api.list();
+    return { kind: "users", items: users };
+}
+```
+## Methods
+| Method                            | HTTP verb | Body? |
+| --------------------------------- | --------- | ----- |
+| `get<T>(path, options?)`          | GET       | no    |
+| `post<T>(path, body?, options?)`  | POST      | yes   |
+| `put<T>(path, body?, options?)`   | PUT       | yes   |
+| `patch<T>(path, body?, options?)` | PATCH     | yes   |
+| `delete<T>(path, options?)`       | DELETE    | no    |
+All methods return `Promise<T>`. The response body is parsed based on `Content-Type`:
+- `application/json` → `JSON.parse`
+- `text/*` → `string`
+- everything else → `Response` (you handle parsing)
+## Per-request options
+```ts
+await api.get<User>("/users/42", {
+    headers: { "X-Request-Id": requestId },
+    signal: abortController.signal,
+    credentials: "include",
+});
+```
+All standard `RequestInit` fields pass through. Per-request headers merge with `defaultHeaders` (per-request wins on key conflict).
+## Interceptors
+### Request interceptors
+Transform the URL and `RequestInit` before the request is sent.
+```ts
+const api = new UserApi({
+    baseUrl: "/api",
+    requestInterceptors: [
+        (url, init) => {
+            init.headers = {
+                ...init.headers,
+                Authorization: `Bearer ${getToken()}`,
+            };
+            return init;
+        },
+    ],
+});
+```
+Multiple interceptors run in array order. Each one receives the `init` returned by the previous one.
+### Response interceptors
+Inspect the `Response` after `fetch` resolves but before the body is parsed.
+```ts
+new UserApi({
+    baseUrl: "/api",
+    responseInterceptors: [
+        async (response, url) => {
+            if (response.status === 401) {
+                await refreshToken();
+                // optionally re-throw to trigger a retry in your own code
+            }
+            return response;
+        },
+    ],
+});
+```
+Returning a different `Response` lets you replace the response (e.g., serve from cache on 5xx).
+### Adding interceptors dynamically
+```ts
+api.useRequestInterceptor((url, init) => {
+    init.headers = { ...init.headers, "X-Trace-Id": traceId };
+    return init;
+});
+api.useResponseInterceptor((resp) => {
+    metrics.recordLatency(resp.url, performance.now() - start);
+    return resp;
+});
+```
+Use this for cross-cutting concerns that aren't known at construction time.
+## Error handling
+`HttpClient` throws `HttpError` for non-2xx responses:
+```ts
+import { HttpError } from "@finesoft/front";
+try {
+    const user = await api.getById("missing");
+} catch (e) {
+    if (e instanceof HttpError) {
+        e.status; // 404
+        e.statusText; // "Not Found"
+        e.url; // "/api/users/missing"
+        e.body; // unknown — parsed response body if available
+    }
+}
+```
+Network errors (DNS, refused connection, abort) come through as standard `TypeError` / `DOMException`, not `HttpError`. Catch both if you care about either:
+```ts
+try {
+    await api.list();
+} catch (e) {
+    if (e instanceof HttpError) {
+        if (e.status >= 500) showRetryBanner();
+        else showInputError(e.body);
+    } else {
+        showOfflineBanner();
+    }
+}
+```
+## Server-side vs browser
+`HttpClient` uses `fetch` directly, which is now native on Node 22+. No platform-specific code is needed.
+Browser-side requests can hit:
+- Your framework's own proxy routes (`/api/*` → upstream via `proxies` config)
+- Public origins directly (with CORS configured upstream)
+Server-side requests typically hit:
+- Internal services on the private network
+- The proxy upstream directly (skipping the proxy hop on SSR)
+If you proxy `/api` to `https://upstream.example` and a controller calls `api.get("/api/users")` during SSR, the request goes through your proxy on the way back out to the network — which is wasteful. Configure the API client with `baseUrl: process.env.UPSTREAM_URL` on the server and `baseUrl: "/api"` in the browser, deciding by `framework.platform.isServer`.
+## Retries
+The framework does not ship a retry interceptor. Wrap your client:
+```ts
+async function withRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
+    for (let i = 0; i < attempts; i++) {
+        try {
+            return await fn();
+        } catch (e) {
+            if (i === attempts - 1) throw e;
+            if (e instanceof HttpError && e.status < 500) throw e; // don't retry 4xx
+            await new Promise((r) => setTimeout(r, 2 ** i * 200));
+        }
+    }
+    throw new Error("unreachable");
+}
+const user = await withRetry(() => api.getById(id));
+```
+Add this as a wrapper rather than an interceptor — interceptors run once per request, and retry logic needs to re-run the entire request including all earlier interceptors.
+## Abort and timeouts
+Use `AbortController`:
+```ts
+const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), 5000);
+try {
+    const user = await api.getById(id, { signal: controller.signal });
+} finally {
+    clearTimeout(timeout);
+}
+```
+For controllers that may navigate away mid-fetch, store the controller and abort in `fallback()` cleanup or on the next dispatch.
+## Sending non-JSON bodies
+`post`/`put`/`patch` JSON-stringify the body unless it's already a string, `FormData`, `URLSearchParams`, or `Blob`:
+```ts
+// JSON (default)
+api.post("/users", { name: "Alice" });
+// Form data
+const form = new FormData();
+form.append("file", file);
+api.post("/upload", form);
+// URL-encoded
+api.post("/login", new URLSearchParams({ user: "alice", pass: "secret" }));
+// Raw text
+api.post("/webhook", "raw payload", { headers: { "Content-Type": "text/plain" } });
+```
+The client sets `Content-Type: application/json` automatically for objects, and leaves the header alone for `FormData` (so the browser can set the multipart boundary).
+## Next
+- [DI container](./07-di-container.md) — registering API clients, scoped instances per request
+- [Observability](./08-observability.md) — logging request failures, capturing them in monitoring