@finesoft/front 0.1.75 → 0.1.77

package/docs/07-di-container.md

@@ -0,0 +1,264 @@
+# 7. DI container
+
+The framework uses a small dependency-injection container with parent/child scopes. It exists for two reasons:
+
+1. **Request isolation on the server** — every SSR request gets its own scope, so per-request state (auth, request id) doesn't leak across requests.
+2. **Decoupled testing** — controllers resolve their dependencies from the container, so tests can swap any of them.
+
+The container is intentionally small. There are no decorators, no annotations, no auto-wiring. You register factories, you resolve by key.
+
+## Registering
+
+```ts
+import { Container } from "@finesoft/front";
+
+const container = new Container();
+
+container.register("userApi", () => new UserApi({ baseUrl: "/api" }));
+container.register("logger", () => new ConsoleLogger());
+```
+
+The factory is invoked **once per container** by default. The result is cached.
+
+For per-resolve construction (non-singleton):
+
+```ts
+container.register("requestId", () => crypto.randomUUID(), false);
+container.resolve("requestId"); // new id every time
+```
+
+## Resolving
+
+```ts
+const api = container.resolve<UserApi>("userApi");
+const logger = container.resolve<Logger>("logger");
+```
+
+The generic parameter is for TypeScript only — there is no runtime type check.
+
+Resolving an unregistered key throws:
+
+```ts
+container.resolve("missing"); // Error: Dependency "missing" not registered
+```
+
+## Scopes — the core feature
+
+```ts
+const requestScope = framework.container.createScope();
+requestScope.register("currentUser", () => loadUserFromSession(request));
+
+// Falls back to parent for keys not in the scope:
+requestScope.resolve("userApi"); // parent
+requestScope.resolve("currentUser"); // scope
+
+requestScope.dispose();
+```
+
+A child scope:
+
+- **Inherits** all parent keys via fallback resolution
+- **Overrides** any key by registering its own factory
+- **Cleans up** on `dispose()` — children are recursively disposed; the scope removes itself from the parent's children set
+
+The framework creates a request-scoped container automatically per SSR request and passes it to your guards and controllers as `ctx.container` / the second argument of `execute()`. You should not need to manually create scopes for normal request handling.
+
+## When to create your own scope
+
+- Multi-tenant apps where each tenant has its own config / API client (see [advanced/multi-tenant-scopes](./advanced/multi-tenant-scopes.md))
+- Long-running operations that need their own short-lived dependencies
+- Test setup where you want to layer overrides on top of a base container
+
+## Disposal and leaks
+
+```ts
+const scope = container.createScope();
+// ... use scope ...
+scope.dispose();
+```
+
+`dispose()`:
+
+1. Recursively disposes any unfinished child scopes
+2. Calls `destroy()` on any registered factory whose result implements it (loggers, recorders)
+3. Removes itself from the parent's children set
+4. Is idempotent — calling twice is safe
+
+**Not disposing a scope leaks every cached value in it.** Request scopes that survive past the response will hold onto:
+
+- HTTP clients (and their pending request state)
+- Loggers / recorders
+- Anything else the controllers resolved
+
+The framework handles disposal for request scopes it creates. Scopes **you** create are yours to dispose.
+
+See [pitfalls: container scope leak](./pitfalls/container-scope-leak.md) for the symptoms when you forget.
+
+## Standard DI keys
+
+Use `DEP_KEYS` constants instead of string literals to catch typos at type-check time:
+
+```ts
+import { DEP_KEYS } from "@finesoft/front";
+
+container.register(DEP_KEYS.LOGGER, () => new ConsoleLogger());
+container.register(DEP_KEYS.EVENT_RECORDER, () => myRecorder);
+
+const logger = container.resolve(DEP_KEYS.LOGGER);
+```
+
+The constants:
+
+| Key                       | Standard type      | Used by                                       |
+| ------------------------- | ------------------ | --------------------------------------------- |
+| `DEP_KEYS.LOGGER`         | `Logger`           | Framework logging                             |
+| `DEP_KEYS.LOGGER_FACTORY` | `LoggerFactory`    | Per-category loggers (`logger.scope("auth")`) |
+| `DEP_KEYS.NET`            | `Net`              | Network state checks (offline / metered)      |
+| `DEP_KEYS.STORAGE`        | `Storage`          | Key-value persistence (localStorage / memory) |
+| `DEP_KEYS.FEATURE_FLAGS`  | `FeatureFlags`     | Feature flag reads                            |
+| `DEP_KEYS.METRICS`        | `MetricsClient`    | Counter / gauge / timing                      |
+| `DEP_KEYS.FETCH`          | `typeof fetch`     | `HttpClient`'s underlying fetch (mockable)    |
+| `DEP_KEYS.EVENT_RECORDER` | `EventRecorder`    | Structured event recording                    |
+| `DEP_KEYS.LOCALE`         | `LocaleAttributes` | Resolved locale (lang + dir)                  |
+| `DEP_KEYS.PLATFORM`       | `PlatformInfo`     | Detected user-agent platform info             |
+| `DEP_KEYS.TRANSLATOR`     | `Translator`       | Translation function                          |
+
+The framework registers default implementations for these during `Framework.create()`. Override them by registering after framework creation:
+
+```ts
+const framework = Framework.create({
+    /* ... */
+});
+framework.container.register(DEP_KEYS.LOGGER, () => myCustomLogger);
+```
+
+## Custom keys
+
+For your own services, use string keys directly:
+
+```ts
+container.register("userApi", () => new UserApi({ baseUrl: "/api" }));
+container.register("session", () => new SessionService());
+container.register("featureBucketing", () => new BucketingService());
+```
+
+To get type safety for your own keys, define your own const map:
+
+```ts
+// src/lib/di-keys.ts
+export const APP_KEYS = {
+    USER_API: "userApi",
+    SESSION: "session",
+    FEATURE_BUCKETING: "featureBucketing",
+} as const;
+
+// Usage
+container.register(APP_KEYS.USER_API, () => new UserApi({ baseUrl: "/api" }));
+const api = container.resolve<UserApi>(APP_KEYS.USER_API);
+```
+
+## Lifecycle ordering
+
+```
+Framework.create({ ... })
+    │
+    ▼
+default DEP_KEYS registered (logger, locale, platform, ...)
+    │
+    ▼
+your custom registrations (in onBeforeStart or bootstrap)
+    │
+    ▼
+─── per request ───────────────────────────────────
+framework.container.createScope()      ← request scope
+    │
+    ▼
+beforeLoad guards (ctx.container = scope)
+    │
+    ▼
+controller.execute(params, scope)
+    │
+    ▼
+afterLoad guards (ctx.container = scope)
+    │
+    ▼
+renderApp() / response
+    │
+    ▼
+scope.dispose()                        ← framework cleans up
+```
+
+## Testing with the container
+
+Inject mocks at the scope level:
+
+```ts
+import { Framework } from "@finesoft/front";
+
+const framework = Framework.create({
+    /* ... */
+});
+const testScope = framework.container.createScope();
+testScope.register("userApi", () => mockUserApi);
+
+const controller = new UserListController();
+const page = await controller.execute({}, testScope);
+
+testScope.dispose();
+```
+
+The full pattern is in [engineering/testing](./engineering/testing.md).
+
+## Antipatterns
+
+### Don't resolve in module top-level
+
+```ts
+// BAD — runs at import time, before framework.create()
+const logger = container.resolve(DEP_KEYS.LOGGER);
+export function log(msg: string) {
+    logger.info(msg);
+}
+```
+
+The `container` you'd reach here isn't the request scope; you'd get the parent and lose request isolation.
+
+Instead, resolve inside the function that has access to the scope:
+
+```ts
+export function logFromController(container: Container, msg: string) {
+    container.resolve<Logger>(DEP_KEYS.LOGGER).info(msg);
+}
+```
+
+### Don't keep refs to scoped instances after dispose
+
+```ts
+// BAD
+let api: UserApi;
+beforeLoad: (ctx) => {
+    api = ctx.container.resolve("userApi");
+    return next();
+};
+// `api` now points at an instance whose scope was disposed
+```
+
+If you need to share state across requests, register it on the parent container, not the request scope.
+
+### Don't register inside a guard
+
+```ts
+// BAD — runs per request
+beforeLoad: (ctx) => {
+    ctx.container.register("userApi", () => new UserApi(/*...*/));
+    return next();
+};
+```
+
+This creates a fresh factory closure per request. Register once at framework setup; the scope inherits.
+
+## Next
+
+- [Observability](./08-observability.md) — wiring Logger / EventRecorder / ReportCallback via DI
+- [Engineering: testing](./engineering/testing.md) — using scopes to isolate tests
+- [Pitfalls: container scope leak](./pitfalls/container-scope-leak.md) — what happens when you forget to dispose

package/docs/08-observability.md

@@ -0,0 +1,290 @@
+# 8. Observability
+
+Three primitives, each composable, each replaceable:
+
+- **`Logger`** — line-oriented (debug/info/warn/error)
+- **`EventRecorder`** — structured event records (`{ name, fields }`)
+- **`ReportCallback`** — fan-out of `warn`/`error` logs to external monitoring
+
+Plus impression tracking via `IntersectionImpressionObserver`.
+
+## Logger
+
+The base `ConsoleLogger` writes to `console.{debug,info,warn,error}` with a category prefix. Scoped loggers add nested prefixes.
+
+```ts
+import { ConsoleLogger } from "@finesoft/front";
+
+const logger = new ConsoleLogger("app");
+logger.info("hello"); // [app] hello
+
+const auth = logger.scope("auth");
+auth.warn("token expired"); // [app:auth] token expired
+```
+
+Levels: `debug`, `info`, `warn`, `error`. The framework calls `warn`/`error` on its own logger for internal failures (failed guards, dispatch errors).
+
+### Replacing the framework logger
+
+```ts
+import { DEP_KEYS } from "@finesoft/front";
+
+framework.container.register(DEP_KEYS.LOGGER, () => myLogger);
+framework.container.register(DEP_KEYS.LOGGER_FACTORY, () => ({
+    create(category) {
+        return myLoggerImpl.scope(category);
+    },
+}));
+```
+
+## `ReportCallback` — forwarding logs to monitoring
+
+The cleanest way to ship `warn`/`error` logs to Sentry / Datadog / your own collector:
+
+```ts
+import { Framework, type ReportCallback } from "@finesoft/front";
+
+const reportCallback: ReportCallback = (level, category, args) => {
+    Sentry.captureMessage(`[${category}] ${args.join(" ")}`, level);
+};
+
+const framework = Framework.create({
+    reportCallback,
+    // ...
+});
+```
+
+How it works:
+
+- `Framework.create({ reportCallback })` installs `ReportingLoggerFactory` over `ConsoleLogger`
+- All `logger.warn(...)` and `logger.error(...)` calls fire the callback **and** continue to the console
+- `debug` and `info` are not forwarded (avoid burying signal in volume)
+- The callback runs inside `try/catch` — a failure in the reporter cannot crash the framework
+
+### Categories
+
+Each `logger.scope("auth")` becomes a category passed to the callback. Use them for routing in your monitoring system:
+
+```ts
+reportCallback(level, category, args) {
+    if (category.startsWith("auth")) {
+        sentry.captureMessage(/* go to auth project */);
+    } else {
+        sentry.captureMessage(/* default project */);
+    }
+}
+```
+
+### Anti-spam
+
+`ReportCallback` runs every time. If you have a hot loop logging the same warning a thousand times, you'll send a thousand events. Add deduplication in the callback itself:
+
+```ts
+const seen = new Map<string, number>();
+const reportCallback: ReportCallback = (level, category, args) => {
+    const key = `${category}:${args[0]}`;
+    const now = Date.now();
+    const last = seen.get(key) ?? 0;
+    if (now - last < 60_000) return; // 1 per minute per (category, message)
+    seen.set(key, now);
+    Sentry.captureMessage(/* ... */);
+};
+```
+
+## `EventRecorder` — structured events
+
+When you want events with fields, not free-form log lines, use `EventRecorder`.
+
+```ts
+import { Framework, ConsoleEventRecorder, type EventRecorder } from "@finesoft/front";
+
+const recorder: EventRecorder = new ConsoleEventRecorder();
+const framework = Framework.create({ eventRecorder: recorder });
+
+// Anywhere:
+recorder.record({
+    name: "PageView",
+    fields: { url: "/products/42", referrer: "/search?q=widget" },
+});
+```
+
+### Built-in events
+
+The framework records `PageView` automatically via `framework.didEnterPage(page)`. This fires:
+
+- After every successful navigation (SSR + CSR)
+- With fields: `{ intentId, url, renderMode }`
+
+### Composing recorders
+
+`CompositeEventRecorder` fans events to multiple sinks:
+
+```ts
+import { ConsoleEventRecorder, CompositeEventRecorder } from "@finesoft/front";
+
+const recorder = new CompositeEventRecorder([
+    new ConsoleEventRecorder(), // dev visibility
+    productionAnalyticsRecorder, // ship to backend
+]);
+```
+
+If one recorder throws, the others still receive the event.
+
+### Adding common fields
+
+`WithFieldsRecorder` decorates another recorder, prepending fields to every event:
+
+```ts
+import { WithFieldsRecorder, ConsoleEventRecorder } from "@finesoft/front";
+
+const recorder = new WithFieldsRecorder(new ConsoleEventRecorder(), [
+    { getFields: () => ({ app: "myApp", version: "1.0.0" }) },
+    { getFields: () => ({ userId: getCurrentUserId() }) },
+]);
+
+recorder.record({ name: "Click", fields: { id: "buy" } });
+// → { app, version, userId, id }
+```
+
+Use this for session-scoped fields you don't want to repeat in every `record()` call.
+
+### Building your own recorder
+
+Implement the `EventRecorder` interface:
+
+```ts
+import type { EventRecorder, EventRecord } from "@finesoft/front";
+
+class HttpEventRecorder implements EventRecorder {
+    constructor(private endpoint: string) {}
+    record(event: EventRecord): void {
+        // fire-and-forget; do NOT await — record() shouldn't block UI
+        navigator.sendBeacon(this.endpoint, JSON.stringify(event));
+    }
+    destroy(): void {
+        // flush, close connections, etc.
+    }
+}
+```
+
+See [advanced/custom-event-recorder](./advanced/custom-event-recorder.md) for batching, retries, and lifecycle handling.
+
+## Impression tracking
+
+Track when elements enter the viewport using `IntersectionObserver` plumbing:
+
+```ts
+import { IntersectionImpressionObserver, type EventRecorder } from "@finesoft/front";
+
+const observer = new IntersectionImpressionObserver((entries) => {
+    for (const entry of entries) {
+        recorder.record({
+            name: "Impression",
+            fields: { id: entry.id, ...entry.metadata },
+        });
+    }
+});
+
+// Attach to an element when it mounts
+observer.observe(productCardElement, "product-card-123", {
+    category: "featured",
+    position: 3,
+});
+
+// Detach when it unmounts
+observer.unobserve(productCardElement);
+
+// On app teardown
+observer.destroy();
+```
+
+The observer fires the callback once per element per visibility transition. It does not deduplicate across observe/unobserve cycles — your callback should decide whether to record again.
+
+## Error handling via `fallback`
+
+A controller error becomes a recorded event automatically:
+
+```ts
+class HomeController extends BaseController<{}, HomePage> {
+    readonly intentId = "home";
+
+    async execute(_params, container) {
+        const api = container.resolve<UserApi>("userApi");
+        return { kind: "home", users: await api.list() };
+    }
+
+    fallback(_params, error) {
+        // 1. framework logs the error via its logger (→ reportCallback)
+        // 2. you return a degraded page
+        return { kind: "home", users: [], degraded: true };
+    }
+}
+```
+
+Order of operations on error:
+
+1. `execute()` throws.
+2. `BaseController` catches, calls `framework.logger.error("[controller:home]", error)`.
+3. Logger fires `reportCallback("error", "controller:home", [error])` → Sentry.
+4. `fallback()` returns a `Page` of your design.
+5. Render proceeds with the fallback page (HTTP 200 by default).
+
+To set a non-200 status, return a page with an "error" marker and check it in an `afterLoad` guard:
+
+```ts
+afterLoad: [
+    (ctx) => {
+        if ("degraded" in ctx.page && ctx.page.degraded) {
+            return deny(503, "Service degraded");
+        }
+        return next();
+    },
+],
+```
+
+## Metrics (counters / gauges / timing)
+
+The framework's `MetricsClient` is minimal:
+
+```ts
+import { DEP_KEYS } from "@finesoft/front";
+
+const metrics = framework.container.resolve(DEP_KEYS.METRICS);
+
+metrics.increment("requests.total");
+metrics.increment("login.failed", { reason: "wrong_password" });
+metrics.gauge("queue.depth", 17);
+metrics.timing("render.duration", 142);
+```
+
+The default implementation is a no-op. Register your own:
+
+```ts
+framework.container.register(DEP_KEYS.METRICS, () => new StatsdMetrics(/* ... */));
+```
+
+For most apps, `EventRecorder` is enough — your analytics backend already aggregates events into metrics.
+
+## Trace IDs and request correlation
+
+A common pattern: tag every log and event with a per-request trace id.
+
+```ts
+// beforeLoad guard
+function traceIdGuard(ctx) {
+    const traceId = ctx.getHeader("x-request-id") ?? crypto.randomUUID();
+    ctx.container.register("traceId", () => traceId);
+    ctx.container.register(
+        DEP_KEYS.EVENT_RECORDER,
+        () => new WithFieldsRecorder(baseRecorder, [{ getFields: () => ({ traceId }) }]),
+    );
+    return next();
+}
+```
+
+Register the scoped recorder via `WithFieldsRecorder` so every event in this request automatically carries the trace id.
+
+## Next
+
+- [Server & deployment](./09-server-and-deployment.md) — where these primitives meet HTTP
+- [Advanced: custom event recorder](./advanced/custom-event-recorder.md) — production-grade implementation