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

@finesoft/front 0.1.75 → 0.1.76

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 (8) 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/package.json +11 -3

package/README.md CHANGED Viewed

@@ -1,421 +1,12 @@
 # @finesoft/front
-Full-stack TypeScript framework — router, DI, actions, SSR, and server — all in one package.
-Works with **Vue**, **React**, and **Svelte**. Deploy to Node.js, Vercel, Cloudflare Workers, Netlify, or static hosting.
-## Install
+Full-stack TypeScript framework — router, DI, actions, SSR, and server — all in one package. Works with **Vue**, **React**, or **Svelte**. Deploys to Node.js, Vercel, Cloudflare Workers, Netlify, or static hosting.
 ```bash
 npx @finesoft/create-app my-app
 ```
-Or add to an existing project:
-```bash
-npm install @finesoft/front
-```
-Peer dependencies: `hono >= 4.0.0`. Optional: `@hono/node-server`, `vite >= 5.0.0`.
-## Setup
-```ts
-// vite.config.ts
-import { finesoftFrontViteConfig } from "@finesoft/front";
-import vue from "@vitejs/plugin-vue";
-import { defineConfig } from "vite";
-export default defineConfig({
-    plugins: [
-        vue(),
-        finesoftFrontViteConfig({
-            ssr: { entry: "src/ssr.ts" },
-            i18n: { messagesDir: "src/locales" },
-            proxies: [{ prefix: "/api", target: "https://api.example.com" }],
-            adapter: "auto",
-        }),
-    ],
-});
-```
-## Routing
-```ts
-// src/bootstrap.ts
-import { type Framework, defineRoutes } from "@finesoft/front";
-import { HomeController } from "./lib/controllers/home";
-import { authGuard } from "./lib/guards/auth";
-export function bootstrap(framework: Framework): void {
-    defineRoutes(framework, [
-        { path: "/", intentId: "home", controller: new HomeController() },
-        {
-            path: "/about",
-            intentId: "about",
-            controller: new AboutController(),
-            renderMode: "csr",
-        },
-        { path: "/admin", intentId: "home", beforeLoad: [authGuard] },
-    ]);
-}
-```
-## Controllers
-```ts
-import { BaseController, type Container } from "@finesoft/front";
-class HomeController extends BaseController<Record<string, string>, HomePage> {
-    readonly intentId = "home";
-    async execute(_params: Record<string, string>, container: Container) {
-        const http = container.resolve<HttpClient>("http");
-        return http.get("/api/home");
-    }
-}
-```
-## Middleware
-Two-phase guards shared between SSR and CSR:
-```ts
-import { next, redirect, type NavigationContext } from "@finesoft/front";
-function authGuard(ctx: NavigationContext) {
-    return ctx.getCookie("token") ? next() : redirect("/login");
-}
-```
-Results: `next()`, `redirect(url, status?)`, `rewrite(url)`, `deny(status?, message?)`.
-## Lifecycle Hooks
-`startBrowserApp` provides hooks for initialization:
-```ts
-import { startBrowserApp } from "@finesoft/front/browser";
-startBrowserApp({
-    bootstrap,
-    // Pass framework config so locale/reporting/etc. are wired into Framework
-    frameworkConfig: {
-        locale: "zh-Hans",
-    },
-    mount: (target, { framework }) => {
-        /* ... */
-    },
-    callbacks: { onNavigate, onExternalUrl },
-    onBeforeStart(framework) {
-        // Runs after Framework creation, before mount.
-        // Good for: error monitoring, analytics SDK, i18n init.
-    },
-    onAfterStart(framework) {
-        // Runs after initial page trigger.
-        // Good for: service worker registration, performance marks.
-    },
-});
-```
-## Locale (i18n)
-Pass `locale` in `FrameworkConfig` to enable automatic locale handling:
-```ts
-const framework = Framework.create({
-    locale: "zh-Hans", // or "en-US", "ar-SA", etc.
-});
-// SSR: automatically injects <html lang="zh-Hans" dir="ltr">
-// Browser: automatically sets document.documentElement.lang/dir on startup
-```
-For SSR, locale is resolved in this order:
-1. Explicit `resolveLocale` callback (if provided)
-2. `locale` from `FrameworkConfig` (via DI container)
-Access at runtime:
-```ts
-const locale = framework.getLocale();
-// { lang: "zh-Hans", dir: "ltr" }
-```
-### Translator
-For synchronous in-memory i18n translation, use `SimpleTranslator`:
-```ts
-import { SimpleTranslator } from "@finesoft/front";
-const t = new SimpleTranslator({
-    locale: "zh-Hans",
-    messages: {
-        hello: "你好",
-        "items.one": "{count} 个项目",
-        "items.other": "{count} 个项目",
-    },
-});
-t.t("hello"); // "你好"
-t.t("hello", { name: "World" }); // "你好"
-t.plural("items", 5); // "5 个项目"
-```
-For locale dictionaries, prefer JSON files plus `finesoftFrontViteConfig()`. The framework
-will automatically load `${locale}.json` before SSR render and before browser hydration,
-without serializing the translations into HTML.
-```ts
-// vite.config.ts
-import { finesoftFrontViteConfig } from "@finesoft/front";
-import { defineConfig } from "vite-plus";
-export default defineConfig({
-    plugins: [
-        finesoftFrontViteConfig({
-            ssr: { entry: "src/ssr.ts" },
-            i18n: {
-                messagesDir: "src/locales",
-            },
-        }),
-    ],
-});
-// src/locales/zh-Hans.json
-{
-    "hello": "你好"
-}
-// src/locales/en-US.json
-{
-    "hello": "Hello"
-}
-```
-If you need a non-file source such as a CDN or API, `loadMessages` is still supported on
-`createSSRRender()` / `startBrowserApp()` and overrides the Vite-generated loader.
-### RTL Support
-```ts
-import { isRtl, getTextDirection, getLocaleAttributes } from "@finesoft/front";
-isRtl("ar"); // true
-getTextDirection("he"); // "rtl"
-getLocaleAttributes("ar-SA"); // { lang: "ar-SA", dir: "rtl" }
-```
-## Metrics & Event Recording
-### EventRecorder (recommended)
-New pipeline for structured event recording. Default: `ConsoleEventRecorder` (logs to console).
-```ts
-import { Framework, type EventRecorder } from "@finesoft/front";
-// Custom recorder
-const framework = Framework.create({
-    eventRecorder: myAnalyticsRecorder,
-});
-// Framework automatically records PageView events via didEnterPage()
-```
-Compose multiple recorders:
-```ts
-import { CompositeEventRecorder, ConsoleEventRecorder } from "@finesoft/front";
-const recorder = new CompositeEventRecorder([new ConsoleEventRecorder(), myProductionRecorder]);
-```
-Inject common fields into every event:
-```ts
-import { WithFieldsRecorder } from "@finesoft/front";
-const recorder = new WithFieldsRecorder(baseRecorder, [
-    { getFields: () => ({ app: "myApp", version: "1.0" }) },
-]);
-```
-### Impression Tracking
-Track element visibility using `IntersectionObserver`:
-```ts
-import { IntersectionImpressionObserver } from "@finesoft/front";
-const observer = new IntersectionImpressionObserver((entries) => {
-    for (const entry of entries) {
-        analytics.track("impression", { id: entry.id, ...entry.metadata });
-    }
-});
-observer.observe(element, "product-card-123", { category: "featured" });
-// Later:
-observer.unobserve(element);
-observer.destroy();
-```
-## Error Reporting
-Send `warn`/`error` logs to an external monitoring service (Sentry, Datadog, etc.):
-```ts
-import { Framework, type ReportCallback } from "@finesoft/front";
-const framework = Framework.create({
-    reportCallback(level, category, args) {
-        sentry.captureMessage(`[${category}] ${args.join(" ")}`, level);
-    },
-});
-// Automatically composes with ConsoleLogger — console output is preserved.
-// All framework.getLogger().warn(...) and .error(...) calls are forwarded.
-```
-## HTTP Client
-Subclass `HttpClient` to create typed API clients:
-```ts
-import { HttpClient } from "@finesoft/front";
-class MyApi extends HttpClient {
-    async getUser(id: string) {
-        return this.get<User>(`/users/${id}`);
-    }
-    async createUser(data: NewUser) {
-        return this.post<User>("/users", data);
-    }
-}
-```
-### Interceptors
-Add request/response interceptors for auth, logging, retries, etc.:
-```ts
-const api = new MyApi({
-    baseUrl: "/api",
-    requestInterceptors: [
-        (url, init) => {
-            init.headers = {
-                ...init.headers,
-                Authorization: `Bearer ${token}`,
-            };
-            return init;
-        },
-    ],
-    responseInterceptors: [
-        (response, url) => {
-            if (response.status === 401) refreshToken();
-            return response;
-        },
-    ],
-});
-// Or add dynamically:
-api.useRequestInterceptor((url, init) => {
-    /* ... */ return init;
-});
-```
-## Platform Detection
-Automatically detected from User-Agent and available via DI:
-```ts
-const platform = framework.getPlatform();
-// { os: "ios", browser: "safari", engine: "webkit", isMobile: true, isTouch: true }
-```
-Standalone usage:
-```ts
-import { detectPlatform } from "@finesoft/front";
-const info = detectPlatform(); // auto-reads navigator.userAgent
-```
-## PWA Detection
-```ts
-import { getPWADisplayMode } from "@finesoft/front";
-const mode = getPWADisplayMode();
-// "standalone" | "twa" | "browser"
-```
-## Feature Flags
-```ts
-const framework = Framework.create({
-    featureFlags: { darkMode: true, maxRetries: 3 },
-});
-// Add remote providers (last registered wins):
-import { type FeatureFlagsProvider } from "@finesoft/front";
-const framework = Framework.create({
-    featureFlags: { darkMode: false },
-    featureFlagsProviders: [remoteConfigProvider],
-});
-```
-## DI Container
-Scoped containers for request isolation (SSR):
-```ts
-const requestScope = framework.container.createScope();
-requestScope.register("user", () => currentUser);
-// Falls back to parent container if key not found
-```
-## SSR
-```ts
-// src/ssr.ts
-import { createSSRRender, serializeServerData } from "@finesoft/front";
-import { createSSRApp } from "vue";
-import { renderToString } from "vue/server-renderer";
-import App from "./App.vue";
-import { bootstrap } from "./bootstrap";
-export const render = createSSRRender({
-    bootstrap,
-    getErrorPage: () => ({ title: "Error", kind: "error" }),
-    async renderApp(page) {
-        const html = await renderToString(createSSRApp(App, { page }));
-        return { html, head: `<title>${page.title}</title>`, css: "" };
-    },
-});
-export { serializeServerData };
-```
-## Adapters
-| Adapter        | Target                     |
-| -------------- | -------------------------- |
-| `"node"`       | Standalone Node.js server  |
-| `"vercel"`     | Vercel Build Output API v3 |
-| `"cloudflare"` | Cloudflare Workers         |
-| `"netlify"`    | Netlify Functions v2       |
-| `"static"`     | Pre-rendered static files  |
-| `"auto"`       | Auto-detect at build time  |
-## Entry Points
-| Import                    | Contents                                   |
-| ------------------------- | ------------------------------------------ |
-| `@finesoft/front`         | Everything (core + browser + SSR + server) |
-| `@finesoft/front/browser` | Browser-only (no server code)              |
+**Documentation: [English](./docs/README.md) · [简体中文](./docs/zh/README.md)** — getting started, engineering practices, pitfalls, and advanced recipes.
 ## License

package/dist/browser.d.mts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ import { $ as RenderMode, $t as Storage, A as IntersectionImpressionObserver, An as isCompoundAction, At as RouteAddOptions, B as buildUrl, Bt as RedirectResult, C as PluralRuleProvider, Cn as ActionDispatcher, Ct as Translator, D as WithFieldsRecorder, Dn as CompoundAction, Dt as ConsoleLoggerFactory, E as resolvePluralKey, En as Action, Et as ConsoleLogger, F as BrowserContextOptions, Ft as DenyResult, G as PWADisplayMode, Gt as rewrite, H as removeHost, Ht as deny, I as ServerContextOptions, It as MiddlewareResult, J as Optional, Jt as FeatureFlags, K as getPWADisplayMode, Kt as BasePage, L as createBrowserContext, Lt as NavigationContext, M as CompositeEventRecorder, Mn as isFlowAction, Mt as Router, N as runAfterLoadGuards, Nn as makeExternalUrlAction, Nt as AfterLoadGuard, O as VoidEventRecorder, On as ExternalUrlAction, Ot as CompositeLogger, P as runBeforeLoadGuards, Pn as makeFlowAction, Pt as BeforeLoadGuard, Q as DefineRoutesOptions, Qt as Net, R as createServerContext, Rt as NextResult, S as PluralCategory, Sn as Container, St as TextDirection, T as interpolate, Tn as ACTION_KINDS, Tt as shouldLog, U as removeQueryParams, Ut as next, V as getBaseUrl, Vt as RewriteResult, W as removeScheme, Wt as redirect, X as isSome, Xt as MakeDependenciesOptions, Y as isNone, Yt as FeatureFlagsProvider, Z as LruMap, Zt as MetricsRecorder, _ as getTextDirection, _n as Logger, _t as FrameworkConfig, a as BrowserAppConfig, an as resolveMessages, at as pipe, b as resolveLocaleFromUrl, bn as Intent, bt as LocaleAttributes, c as registerActionHandlers, cn as EventRecorder, ct as HttpClient, d as registerFlowActionHandler, dn as MetricsFieldsProvider, dt as RequestInterceptor, en as makeDependencies, et as RouteDefinition, f as ExternalUrlDependencies, fn as ReportCallback, ft as ResponseInterceptor, g as getLocaleAttributes, gn as BaseLogger, gt as Framework, h as SimpleTranslatorOptions, hn as ReportingLoggerOptions, ht as BaseShelf, i as History, in as resolveConfiguredMessages, it as mapEach, j as ConsoleEventRecorder, jn as isExternalUrlAction, jt as RouteMatch, k as ImpressionObserverOptions, kn as FlowAction, kt as CompositeLoggerFactory, l as FlowActionCallbacks, ln as ImpressionEntry, lt as HttpClientConfig, m as SimpleTranslator, mn as ReportingLoggerFactory, mt as BaseItem, n as deserializeServerData, nn as MessagesLoaderContext, nt as AsyncMapper, o as startBrowserApp, on as PlatformInfo, ot as pipeAsync, p as registerExternalUrlHandler, pn as ReportingLogger, pt as stableStringify, q as None, qt as DEP_KEYS, r as tryScroll, rn as TranslationMessages, rt as Mapper, s as ActionHandlerDependencies, sn as detectPlatform, st as BaseController, t as createPrefetchedIntentsFromDom, tn as MessagesLoader, tt as defineRoutes, u as FlowActionDependencies, un as ImpressionObserver, ut as HttpError, v as isRtl, vn as LoggerFactory, vt as PrefetchedIntent, w as englishPlural, wn as ActionHandler, wt as resetFilterCache, x as setHtmlLocaleAttributes, xn as IntentController, xt as LocaleInfo, y as makeLocaleInfo, yn as IntentDispatcher, yt as PrefetchedIntents, z as generateUuid, zt as PostLoadContext } from "./server-data-DGbiKzMS.mjs";
2	+ export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, type ActionHandlerDependencies, AfterLoadGuard, AsyncMapper, BaseController, BaseItem, BaseLogger, BasePage, BaseShelf, BeforeLoadGuard, type BrowserAppConfig, BrowserContextOptions, CompositeEventRecorder, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleEventRecorder, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, DefineRoutesOptions, DenyResult, EventRecorder, ExternalUrlAction, type ExternalUrlDependencies, FeatureFlags, FeatureFlagsProvider, FlowAction, type FlowActionCallbacks, type FlowActionDependencies, Framework, FrameworkConfig, History, HttpClient, HttpClientConfig, HttpError, ImpressionEntry, ImpressionObserver, ImpressionObserverOptions, Intent, IntentController, IntentDispatcher, IntersectionImpressionObserver, LocaleAttributes, LocaleInfo, Logger, Logger as LoggerInterface, LoggerFactory, LruMap, MakeDependenciesOptions, Mapper, MessagesLoader, MessagesLoaderContext, MetricsFieldsProvider, MetricsRecorder, MiddlewareResult, NavigationContext, Net, NextResult, None, Optional, PWADisplayMode, PlatformInfo, PluralCategory, PluralRuleProvider, PostLoadContext, PrefetchedIntent, PrefetchedIntents, RedirectResult, RenderMode, ReportCallback, ReportingLogger, ReportingLoggerFactory, ReportingLoggerOptions, RequestInterceptor, ResponseInterceptor, RewriteResult, RouteAddOptions, RouteDefinition, RouteMatch, Router, ServerContextOptions, SimpleTranslator, SimpleTranslatorOptions, Storage, TextDirection, TranslationMessages, Translator, VoidEventRecorder, WithFieldsRecorder, buildUrl, createBrowserContext, createPrefetchedIntentsFromDom, createServerContext, defineRoutes, deny, deserializeServerData, detectPlatform, englishPlural, generateUuid, getBaseUrl, getLocaleAttributes, getPWADisplayMode, getTextDirection, interpolate, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isRtl, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, makeLocaleInfo, mapEach, next, pipe, pipeAsync, redirect, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, removeHost, removeQueryParams, removeScheme, resetFilterCache, resolveConfiguredMessages, resolveLocaleFromUrl, resolveMessages, resolvePluralKey, rewrite, runAfterLoadGuards, runBeforeLoadGuards, setHtmlLocaleAttributes, shouldLog, stableStringify, startBrowserApp, tryScroll };

package/dist/browser.mjs ADDED Viewed

@@ -0,0 +1 @@

+ import{$ as e,A as t,B as n,C as r,D as i,E as a,F as o,G as s,H as c,I as l,J as u,K as d,L as f,M as p,N as m,O as h,P as g,Q as _,R as v,S as y,T as b,U as x,V as S,W as C,X as w,Y as T,Z as E,_ as D,_t as O,a as k,at as A,b as j,bt as M,c as N,ct as P,d as F,dt as I,et as L,f as R,ft as z,g as B,gt as V,h as H,ht as U,i as W,it as G,j as K,k as q,l as J,lt as Y,m as X,mt as Z,n as Q,nt as $,o as ee,ot as te,p as ne,pt as re,q as ie,r as ae,rt as oe,s as se,st as ce,t as le,tt as ue,u as de,ut as fe,v as pe,vt as me,w as he,x as ge,xt as _e,y as ve,yt as ye,z as be}from"./start-app-BdXBCcor.mjs";export{V as ACTION_KINDS,U as ActionDispatcher,m as BaseController,_ as BaseLogger,R as CompositeEventRecorder,e as CompositeLogger,L as CompositeLoggerFactory,s as ConsoleEventRecorder,u as ConsoleLogger,T as ConsoleLoggerFactory,re as Container,c as DEP_KEYS,l as Framework,ee as History,g as HttpClient,o as HttpError,Z as IntentDispatcher,F as IntersectionImpressionObserver,h as LruMap,f as PrefetchedIntents,d as ReportingLogger,ie as ReportingLoggerFactory,S as Router,ue as SimpleTranslator,de as VoidEventRecorder,J as WithFieldsRecorder,j as buildUrl,D as createBrowserContext,Q as createPrefetchedIntentsFromDom,pe as createServerContext,q as defineRoutes,ne as deny,ae as deserializeServerData,C as detectPlatform,$ as englishPlural,ve as generateUuid,ge as getBaseUrl,ce as getLocaleAttributes,b as getPWADisplayMode,P as getTextDirection,oe as interpolate,O as isCompoundAction,me as isExternalUrlAction,ye as isFlowAction,a as isNone,Y as isRtl,i as isSome,x as makeDependencies,M as makeExternalUrlAction,_e as makeFlowAction,fe as makeLocaleInfo,t as mapEach,X as next,K as pipe,p as pipeAsync,H as redirect,W as registerActionHandlers,N as registerExternalUrlHandler,k as registerFlowActionHandler,y as removeHost,r as removeQueryParams,he as removeScheme,w as resetFilterCache,A as resolveConfiguredMessages,I as resolveLocaleFromUrl,te as resolveMessages,G as resolvePluralKey,B as rewrite,be as runAfterLoadGuards,n as runBeforeLoadGuards,z as setHtmlLocaleAttributes,E as shouldLog,v as stableStringify,le as startBrowserApp,se as tryScroll};