@finesoft/front 0.5.1 → 0.5.3

package/docs/07-di-container.md

@@ -1,264 +1,30 @@
-# 7. DI container
+# Dependencies and resource ownership
 
-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
+Declare typed providers on the app/runtime. Ordinary calls use runtime.execute; it owns the invocation scope. Scope providers share one initialization within that invocation; runtime providers live until runtime.dispose. Transient values are created per acquisition and tracked for cleanup. Created values are owned by default; supplied values are external unless owned is true. Async initialization and disposal are awaited in dependency order. Runtime providers cannot capture request-only bindings. The legacy named Container remains available for existing controller dependencies; new asynchronous services should use context.get(token).
 
 ```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({
-    /* ... */
+import { createToken, provide, defineApp, defineOperation, createRuntime } from "@finesoft/front";
+const tenant = createToken<string>("tenant");
+const who = defineOperation({
+    id: "who",
+    kind: "query",
+    handler: async (_: undefined, context) => context.get(tenant),
 });
-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 app = defineApp({
+    id: "example",
+    operations: [who],
+    providers: [
+        provide({
+            token: tenant,
+            lifetime: "scope",
+            create: ({ bindings }) => String(bindings.tenant),
+        }),
+    ],
 });
-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);
+const runtime = createRuntime({ app });
+try {
+    await runtime.execute(who, undefined, { bindings: { tenant: "one" } });
+} finally {
+    await runtime.dispose();
 }
 ```
-
-### 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

@@ -1,290 +1,10 @@
-# 8. Observability
+# 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:
+Use a runtime recorder for portable structured events. Web logging configuration belongs to app.configuration; do not create another framework instance solely to register diagnostics. ReportingLoggerFactory can forward warnings/errors through an application callback. Do not include private inputs, credentials or arbitrary upstream errors in public diagnostics. Browser impression observation is selected from the browser entry.
 
 ```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 };
-    }
-}
+import { ConsoleEventRecorder, createRuntime } from "@finesoft/front";
+const runtime = createRuntime({ app, recorder: new ConsoleEventRecorder() });
+// In an operation: context.record("checkout.completed", { itemCount: 2 });
+// In defineWebApp: configuration: { eventRecorder: recorder, reportCallback }
 ```
-
-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