@sincpro/mobile 0.2.0 → 0.4.1

package/dist/entrypoints/db/migrations.d.ts

@@ -4,7 +4,9 @@ export declare enum DATABASE_TABLES {
     EVENT_QUEUE = "event_queue",
     DEAD_LETTER_QUEUE = "dead_letter_queue",
     DOMAIN_EVENTS = "domain_events",
-    DOMAIN_EVENTS_DEAD_LETTER = "domain_events_dead_letter"
+    DOMAIN_EVENTS_DEAD_LETTER = "domain_events_dead_letter",
+    TELEMETRY_QUEUE = "telemetry_queue",
+    SPANS_QUEUE = "spans_queue"
 }
 declare const MIGRATIONS: IMigration[];
 export default MIGRATIONS;

package/dist/entrypoints/db/migrations.js

@@ -6,6 +6,8 @@ export var DATABASE_TABLES;
     DATABASE_TABLES["DEAD_LETTER_QUEUE"] = "dead_letter_queue";
     DATABASE_TABLES["DOMAIN_EVENTS"] = "domain_events";
     DATABASE_TABLES["DOMAIN_EVENTS_DEAD_LETTER"] = "domain_events_dead_letter";
+    DATABASE_TABLES["TELEMETRY_QUEUE"] = "telemetry_queue";
+    DATABASE_TABLES["SPANS_QUEUE"] = "spans_queue";
 })(DATABASE_TABLES || (DATABASE_TABLES = {}));
 async function createSettingsTable() {
     await DBCursor.execAsync(`
@@ -110,6 +112,66 @@ async function createDomainEventsDeadLetterTable() {
     CREATE INDEX IF NOT EXISTS idx_dead_letter_failed ON ${DATABASE_TABLES.DOMAIN_EVENTS_DEAD_LETTER}(failed_at);
   `);
 }
+async function createTelemetryQueueTable() {
+    await DBCursor.execAsync(`
+    CREATE TABLE IF NOT EXISTS ${DATABASE_TABLES.TELEMETRY_QUEUE} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      level TEXT NOT NULL,
+      message TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+  `);
+    await DBCursor.execAsync(`
+    CREATE INDEX IF NOT EXISTS idx_telemetry_queue_created
+    ON ${DATABASE_TABLES.TELEMETRY_QUEUE}(created_at);
+  `);
+}
+async function createSpansQueueTable() {
+    await DBCursor.execAsync(`
+    CREATE TABLE IF NOT EXISTS ${DATABASE_TABLES.SPANS_QUEUE} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      trace_id TEXT NOT NULL,
+      span_id TEXT NOT NULL,
+      parent_span_id TEXT,
+      name TEXT NOT NULL,
+      kind INTEGER NOT NULL DEFAULT 0,
+      start_time_unixnano TEXT NOT NULL,
+      end_time_unixnano TEXT NOT NULL,
+      attributes TEXT NOT NULL DEFAULT '{}',
+      status_code INTEGER NOT NULL DEFAULT 0,
+      status_message TEXT NOT NULL DEFAULT '',
+      resource_attrs TEXT NOT NULL DEFAULT '{}',
+      events TEXT NOT NULL DEFAULT '[]',
+      links TEXT NOT NULL DEFAULT '[]',
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+  `);
+    await DBCursor.execAsync(`
+    CREATE INDEX IF NOT EXISTS idx_spans_queue_created
+    ON ${DATABASE_TABLES.SPANS_QUEUE}(created_at);
+  `);
+    await DBCursor.execAsync(`
+    CREATE INDEX IF NOT EXISTS idx_spans_queue_trace
+    ON ${DATABASE_TABLES.SPANS_QUEUE}(trace_id);
+  `);
+}
+// Adds events and links columns to spans_queue for existing installs.
+// Fresh installs get them from createSpansQueueTable above; ALTER TABLE is a
+// no-op on those (caught and ignored — duplicate column error is expected).
+async function addSpansQueueEventsLinks() {
+    try {
+        await DBCursor.execAsync(`ALTER TABLE ${DATABASE_TABLES.SPANS_QUEUE} ADD COLUMN events TEXT NOT NULL DEFAULT '[]'`);
+    }
+    catch {
+        // column already exists on fresh installs
+    }
+    try {
+        await DBCursor.execAsync(`ALTER TABLE ${DATABASE_TABLES.SPANS_QUEUE} ADD COLUMN links TEXT NOT NULL DEFAULT '[]'`);
+    }
+    catch {
+        // column already exists on fresh installs
+    }
+}
 const MIGRATIONS = [
     { name: DATABASE_TABLES.SETTINGS, migrationFn: createSettingsTable },
     { name: DATABASE_TABLES.EVENT_QUEUE, migrationFn: createEventQueueTable },
@@ -119,5 +181,8 @@ const MIGRATIONS = [
         name: DATABASE_TABLES.DOMAIN_EVENTS_DEAD_LETTER,
         migrationFn: createDomainEventsDeadLetterTable,
     },
+    { name: DATABASE_TABLES.TELEMETRY_QUEUE, migrationFn: createTelemetryQueueTable },
+    { name: DATABASE_TABLES.SPANS_QUEUE, migrationFn: createSpansQueueTable },
+    { name: "spans_queue_v2_events_links", migrationFn: addSpansQueueEventsLinks },
 ];
 export default MIGRATIONS;

package/dist/entrypoints/queue/QueueProcessor.js

@@ -1,33 +1,9 @@
 import { loggerQueueProcessor } from "../../infrastructure/logger";
 import { EventBus } from "../../infrastructure/workers";
+import { calculateDesiredSubscribers, statesAreEqual, } from "./subscriber_filter";
 let isRunning = false;
 let lastSyncState = null;
 let currentSubscribers = new Set();
-function statesAreEqual(a, b) {
-    if (!a)
-        return false;
-    if (a.isAuthenticated !== b.isAuthenticated)
-        return false;
-    if (a.domains.size !== b.domains.size)
-        return false;
-    for (const domain of a.domains) {
-        if (!b.domains.has(domain))
-            return false;
-    }
-    return true;
-}
-function calculateDesiredSubscribers(domains, isAuthenticated, subscribersByKey) {
-    const desired = new Set();
-    for (const domain of domains) {
-        const domainSubscribers = subscribersByKey[domain] ?? [];
-        for (const subscriber of domainSubscribers) {
-            if (isAuthenticated || !subscriber.requiresAuth) {
-                desired.add(subscriber);
-            }
-        }
-    }
-    return desired;
-}
 export const QueueProcessor = {
     start: () => {
         if (isRunning)

package/dist/entrypoints/queue/subscriber_filter.d.ts

@@ -0,0 +1,9 @@
+export interface HasRequiresAuth {
+    readonly requiresAuth: boolean;
+}
+export interface SyncState {
+    domains: Set<string>;
+    isAuthenticated: boolean;
+}
+export declare function statesAreEqual(a: SyncState | null, b: SyncState): boolean;
+export declare function calculateDesiredSubscribers<T extends HasRequiresAuth>(domains: Set<string>, isAuthenticated: boolean, subscribersByKey: Record<string, T[]>): Set<T>;

package/dist/entrypoints/queue/subscriber_filter.js

@@ -0,0 +1,25 @@
+export function statesAreEqual(a, b) {
+    if (!a)
+        return false;
+    if (a.isAuthenticated !== b.isAuthenticated)
+        return false;
+    if (a.domains.size !== b.domains.size)
+        return false;
+    for (const domain of a.domains) {
+        if (!b.domains.has(domain))
+            return false;
+    }
+    return true;
+}
+export function calculateDesiredSubscribers(domains, isAuthenticated, subscribersByKey) {
+    const desired = new Set();
+    for (const domain of domains) {
+        const domainSubscribers = subscribersByKey[domain] ?? [];
+        for (const subscriber of domainSubscribers) {
+            if (isAuthenticated || !subscriber.requiresAuth) {
+                desired.add(subscriber);
+            }
+        }
+    }
+    return desired;
+}

package/dist/entrypoints/ui/AppShell.d.ts

@@ -5,15 +5,69 @@ import { type ComponentType, type ReactNode } from "react";
 type ProviderComponent = ComponentType<{
     children: ReactNode;
 }>;
+export interface BrandFontWeights {
+    light?: string;
+    regular?: string;
+    medium?: string;
+    semiBold?: string;
+    bold?: string;
+    extraBold?: string;
+    black?: string;
+}
+export interface BrandFontFamilies {
+    /** df — Display & headings. Brand character font. (Default: Inter) */
+    display?: BrandFontWeights;
+    /** bf — Body, labels, buttons. Interface text 13–15px. (Default: Inter) */
+    body?: BrandFontWeights;
+    /** cf — Captions, overlines, metadata. Uppercase + tracking. (Default: Fira Code) */
+    caption?: Pick<BrandFontWeights, "regular" | "medium">;
+    /** mono — Numeric data, SKU, amounts. Fixed-width. (Default: Fira Code) */
+    mono?: Pick<BrandFontWeights, "regular" | "medium">;
+}
+export interface BrandFontConfig {
+    /** Metro asset map: `{ "Satoshi-Bold": require("./assets/fonts/Satoshi-Bold.otf") }` */
+    files: Record<string, string | number>;
+    /** Semantic font family slots aligned with the brand manual (df / bf / cf / mono). */
+    families: BrandFontFamilies;
+}
 export interface AppShellConfig {
+    /**
+     * Domain modules to bootstrap. Each module registers its own repositories,
+     * migrations, subscribers, and cron workers. The built-in `baseModule` is
+     * always included automatically — do not pass it here.
+     */
     domains: DomainModule[];
+    /**
+     * Map of domain key → screen component. Domains without a matching entry
+     * here are bootstrapped (events, repos, crons) but have no UI — they run
+     * silently in the background. Must contain at least `ui[activeDomain]`.
+     */
     ui: Record<string, ComponentType>;
+    /**
+     * Key of the domain whose UI is shown on launch. Must match one of the
+     * keys in `domains` AND have a corresponding entry in `ui`.
+     */
     activeDomain: string;
+    /**
+     * Additional React context providers to wrap around the app. Providers are
+     * applied in array order, outermost last — i.e. the last element in the
+     * array becomes the outermost wrapper and can observe all others.
+     *
+     * Example: `[ConfirmationProvider, ProcessToastProvider]`
+     */
     providers?: ProviderComponent[];
+    /** Light theme tokens. Defaults to the DS base theme if omitted. */
     theme?: ThemeTokens;
+    /** Dark theme tokens. When provided, the system color-scheme toggle activates it. */
     darkTheme?: ThemeTokens;
     branding?: BrandingConfig;
-    /** Component rendered while fonts + domain init complete. Use `AppSplashView` from the DS or roll your own. */
+    /**
+     * Brand typeface declared as semantic slots (df / bf / cf / mono).
+     * The app owns all font asset files; the framework wires them into DS roles.
+     * Omitting a slot keeps the DS default (Inter for body, Fira Code for mono).
+     */
+    brandFont?: BrandFontConfig;
+    /** Component rendered while fonts + domain init complete. */
     splashComponent?: ComponentType;
     /** Minimum time (ms) the splash stays visible. Default 2000. */
     splashDuration?: number;

package/dist/entrypoints/ui/AppShell.js

@@ -5,7 +5,7 @@ import { ToastHost } from "../../infrastructure/ui/ToastHost";
 import { setBranding } from "@sincpro/mobile-ui";
 import { ToastProvider } from "@sincpro/mobile-ui/Feedback";
 import { setActiveTheme, themeToVars, useTheme, } from "@sincpro/mobile-ui/theme";
-import { useAppFonts } from "@sincpro/mobile-ui/theme/typography";
+import { configureFonts, useFonts } from "@sincpro/mobile-ui/theme/typography";
 import * as SplashScreen from "expo-splash-screen";
 import { vars } from "nativewind";
 import { useEffect, useState } from "react";
@@ -15,6 +15,47 @@ import { KeyboardProvider } from "react-native-keyboard-controller";
 import { initialWindowMetrics, SafeAreaProvider, SafeAreaView, } from "react-native-safe-area-context";
 import { CommonProvider } from "./common_provider";
 import { ActiveDomainApp, DomainSwitcherProvider } from "./domain_switcher";
+/** Maps the semantic families object to the low-level DS FontRole record. */
+function familiesToRoles(families) {
+    const roles = {};
+    const { display, body, caption, mono } = families;
+    if (display) {
+        if (display.regular)
+            roles.titleRegular = display.regular;
+        if (display.medium)
+            roles.titleMedium = display.medium;
+        if (display.bold)
+            roles.title = display.bold;
+        if (display.black)
+            roles.titleBlack = display.black;
+    }
+    if (body) {
+        if (body.light)
+            roles.light = body.light;
+        if (body.regular)
+            roles.regular = body.regular;
+        if (body.medium)
+            roles.medium = body.medium;
+        if (body.semiBold)
+            roles.semiBold = body.semiBold;
+        if (body.extraBold)
+            roles.extraBold = body.extraBold;
+    }
+    if (caption) {
+        if (caption.regular)
+            roles.mono = caption.regular;
+        if (caption.medium)
+            roles.monoMedium = caption.medium;
+    }
+    if (mono) {
+        if (mono.regular)
+            roles.mono = mono.regular;
+        if (mono.medium)
+            roles.monoMedium = mono.medium;
+    }
+    return roles;
+}
+/** Wraps children in the provider list. reduceRight → first item = innermost wrapper. */
 function withProviders(providers, children) {
     return providers.reduceRight((acc, Provider) => _jsx(Provider, { children: acc }), children);
 }
@@ -33,10 +74,14 @@ export function createAppShell(config) {
     if (config.branding) {
         setBranding(config.branding);
     }
+    // Wire brand font roles into the DS before first render.
+    if (config.brandFont?.families) {
+        configureFonts(familiesToRoles(config.brandFont.families));
+    }
     return function AppShell() {
         const [isReady, setIsReady] = useState(false);
         const [minDurationMet, setMinDurationMet] = useState(false);
-        const fontsLoaded = useAppFonts();
+        const [brandFontsLoaded] = useFonts(config.brandFont?.files ?? {});
         const activeTheme = useTheme();
         const themeStyle = vars(themeToVars(activeTheme));
         const navTheme = {
@@ -61,11 +106,11 @@ export function createAppShell(config) {
             return () => clearTimeout(t);
         }, []);
         useEffect(() => {
-            if (fontsLoaded && isReady && minDurationMet) {
+            if (brandFontsLoaded && isReady && minDurationMet) {
                 SplashScreen.hideAsync().catch(() => { });
             }
-        }, [fontsLoaded, isReady, minDurationMet]);
-        if (!isReady || !fontsLoaded || !minDurationMet) {
+        }, [brandFontsLoaded, isReady, minDurationMet]);
+        if (!isReady || !brandFontsLoaded || !minDurationMet) {
             const Splash = config.splashComponent;
             return Splash ? (_jsx(Splash, {})) : (_jsx(View, { style: { flex: 1, backgroundColor: activeTheme.bg.page } }));
         }

package/dist/entrypoints/ui/theme.d.ts

@@ -1,15 +1,16 @@
 import { type DeepPartial, type ThemeTokens } from "@sincpro/mobile-ui/theme";
 /**
- * API simple y extensible para que los clientes definan su theme.
- * Parte de los defaults del framework y aplica overrides parciales (tipados).
+ * Build a fully-typed theme from a partial override object.
+ * Starts from the DS base theme and deep-merges your tokens on top.
  *
- *   createApp({
- *     theme: createTheme({ primary: "#FF6600", bg: { page: "#141414" } }),
- *     domains: [...],
+ *   createAppShell({
+ *     theme: createTheme({ primary: "#FF6600", bg: { page: "#F5F5F5" } }),
+ *     darkTheme: createTheme({ bg: { page: "#0A0A0A" }, primary: "#F5F5F5" }),
+ *     ...
  *   });
  *
- * El resultado se inyecta una vez al bootstrap (estático, sin runtime switching)
- * y propaga tanto a `className` (CSS vars) como a `style={theme.x}`.
+ * The result is injected once at bootstrap (static, not swapped at runtime)
+ * and propagates as both NativeWind CSS vars (`className`) and inline style props.
  */
 export declare function createTheme(overrides?: DeepPartial<ThemeTokens>): ThemeTokens;
 export type { DeepPartial, ThemeTokens };

package/dist/entrypoints/ui/theme.js

@@ -1,15 +1,16 @@
 import { extendTheme } from "@sincpro/mobile-ui/theme";
 /**
- * API simple y extensible para que los clientes definan su theme.
- * Parte de los defaults del framework y aplica overrides parciales (tipados).
+ * Build a fully-typed theme from a partial override object.
+ * Starts from the DS base theme and deep-merges your tokens on top.
  *
- *   createApp({
- *     theme: createTheme({ primary: "#FF6600", bg: { page: "#141414" } }),
- *     domains: [...],
+ *   createAppShell({
+ *     theme: createTheme({ primary: "#FF6600", bg: { page: "#F5F5F5" } }),
+ *     darkTheme: createTheme({ bg: { page: "#0A0A0A" }, primary: "#F5F5F5" }),
+ *     ...
  *   });
  *
- * El resultado se inyecta una vez al bootstrap (estático, sin runtime switching)
- * y propaga tanto a `className` (CSS vars) como a `style={theme.x}`.
+ * The result is injected once at bootstrap (static, not swapped at runtime)
+ * and propagates as both NativeWind CSS vars (`className`) and inline style props.
  */
 export function createTheme(overrides) {
     return extendTheme(overrides);

package/dist/framework/base_module.d.ts

@@ -10,5 +10,6 @@ export declare class BaseModule extends DomainModule {
     migrations(): IMigration[];
     subscribers(): Subscriber[];
     crons(): CronWorker[];
+    persistOnReset(): string[];
 }
 export declare const baseModule: BaseModule;

package/dist/framework/base_module.js

@@ -4,7 +4,7 @@ import { DomainEventDeadLetterRepository } from "../adapters/repositories/domain
 import { SettingsRepository } from "../adapters/repositories/setting.repository";
 import { ECommonRepository } from "../domain/repositories";
 import cronCheckNetworkStatus from "../entrypoints/cron/checkNetworkStatus.cron";
-import MIGRATIONS from "../entrypoints/db/migrations";
+import MIGRATIONS, { DATABASE_TABLES } from "../entrypoints/db/migrations";
 import { ActivateDomainSubscriber } from "../entrypoints/queue/activateDomain.subscriber";
 import { NewAppSettingsSubscriber } from "../entrypoints/queue/newAppSettings.handler";
 import { PrintImageSubscriber } from "../entrypoints/queue/printImage.subscriber";
@@ -36,5 +36,10 @@ export class BaseModule extends DomainModule {
     crons() {
         return [cronCheckNetworkStatus];
     }
+    // Both telemetry tables survive restartDatabase() — data generated during
+    // logout must still be delivered; the flush cron runs independently of auth state.
+    persistOnReset() {
+        return [DATABASE_TABLES.TELEMETRY_QUEUE, DATABASE_TABLES.SPANS_QUEUE];
+    }
 }
 export const baseModule = new BaseModule();

package/dist/framework/createApp.d.ts

@@ -1,6 +1,12 @@
+import type { TelemetryConfig } from "../infrastructure/telemetry";
 import type { DomainModule } from "./domain_module";
 import { Kernel } from "./kernel";
 export interface AppConfig {
     domains?: DomainModule[];
+    /**
+     * Opt-in telemetry. When provided, the Loki client and flush cron start automatically
+     * after migrations complete — so the `telemetry_queue` table is guaranteed to exist.
+     */
+    telemetry?: TelemetryConfig;
 }
 export declare function createApp(config?: AppConfig): Promise<Kernel>;

package/dist/framework/createApp.js

@@ -1,9 +1,13 @@
+import { initTelemetry } from "../infrastructure/telemetry";
 import { baseModule } from "./base_module";
 import { Kernel } from "./kernel";
 import { orchestrator } from "./orchestrator";
 export async function createApp(config = {}) {
     const kernel = new Kernel([baseModule, ...(config.domains ?? [])]);
     orchestrator.configure(kernel);
-    await orchestrator.bootstrap();
+    await orchestrator.bootstrap(); // migrations run here — telemetry_queue is ready
+    if (config.telemetry) {
+        await initTelemetry(config.telemetry);
+    }
     return kernel;
 }

package/dist/index.d.ts

@@ -13,3 +13,9 @@ export { DomainModule } from "./framework/domain_module";
 export { Kernel } from "./framework/kernel";
 export { orchestrator } from "./framework/orchestrator";
 export { installGlobalErrorHandler } from "./infrastructure/ui/errorHandler";
+export type { InterceptorHooks, MethodCall, } from "./infrastructure/interceptor/intercept";
+export { interceptClass, interceptFunction, interceptInstance, } from "./infrastructure/interceptor/intercept";
+export type { Logger } from "./infrastructure/interceptor/logging_hooks";
+export { loggingHooks } from "./infrastructure/interceptor/logging_hooks";
+export type { LokiAuth, LokiConfig, TelemetryConfig, } from "./infrastructure/telemetry";
+export { initTelemetry } from "./infrastructure/telemetry";

package/dist/index.js

@@ -8,3 +8,6 @@ export { DomainModule } from "./framework/domain_module";
 export { Kernel } from "./framework/kernel";
 export { orchestrator } from "./framework/orchestrator";
 export { installGlobalErrorHandler } from "./infrastructure/ui/errorHandler";
+export { interceptClass, interceptFunction, interceptInstance, } from "./infrastructure/interceptor/intercept";
+export { loggingHooks } from "./infrastructure/interceptor/logging_hooks";
+export { initTelemetry } from "./infrastructure/telemetry";

package/dist/infrastructure/context_manager/context.d.ts

@@ -0,0 +1,16 @@
+import type { ContextKey } from "./context_key";
+/**
+ * Immutable execution-scoped key-value store.
+ *
+ * Every modification returns a new Context — the original is never mutated.
+ * This makes it safe to pass across async boundaries without defensive copies.
+ */
+export declare class Context {
+    private readonly _map;
+    private constructor();
+    static readonly ROOT: Context;
+    get<T>(key: ContextKey<T>): T | undefined;
+    set<T>(key: ContextKey<T>, value: T): Context;
+    delete<T>(key: ContextKey<T>): Context;
+    describe(): string;
+}

package/dist/infrastructure/context_manager/context.js

@@ -0,0 +1,37 @@
+/**
+ * Immutable execution-scoped key-value store.
+ *
+ * Every modification returns a new Context — the original is never mutated.
+ * This makes it safe to pass across async boundaries without defensive copies.
+ */
+export class Context {
+    _map;
+    constructor(map) {
+        this._map = map;
+    }
+    static ROOT = new Context(new Map());
+    get(key) {
+        return this._map.get(key._symbol);
+    }
+    set(key, value) {
+        const next = new Map(this._map);
+        next.set(key._symbol, value);
+        return new Context(next);
+    }
+    delete(key) {
+        const next = new Map(this._map);
+        next.delete(key._symbol);
+        return new Context(next);
+    }
+    describe() {
+        const parts = [];
+        for (const [sym, val] of this._map) {
+            const name = sym.description ?? "unknown";
+            const repr = val !== null && typeof val === "object"
+                ? (val.constructor?.name ?? "Object")
+                : String(val);
+            parts.push(`${name}: ${repr}`);
+        }
+        return `Context { ${parts.join(", ") || "empty"} }`;
+    }
+}

package/dist/infrastructure/context_manager/context_api.d.ts

@@ -0,0 +1,28 @@
+import { Context } from "./context";
+import type { ContextKey } from "./context_key";
+import { StackContextManager } from "./stack_context_manager";
+/** Returns the context active in the current execution scope. */
+export declare function getActiveContext(): Context;
+/**
+ * Reads a value from the active context.
+ * Equivalent to getActiveContext().get(key).
+ */
+export declare function getContext<T>(key: ContextKey<T>): T | undefined;
+/**
+ * Runs fn within ctx as the active context.
+ *
+ * For async functions, ctx stays active until the returned Promise resolves or
+ * rejects — not just until the first await. This means nested calls at any
+ * point in the async chain see the correct context.
+ *
+ * For sync functions, ctx is active for the duration of the call.
+ */
+export declare function runWithContext<T>(ctx: Context, fn: () => T): T;
+/**
+ * Returns the underlying manager.
+ * Used by interceptor hooks (push/pop) and by adapters (e.g. OTel bridge).
+ * @internal
+ */
+export declare function _getContextManager(): StackContextManager;
+/** @internal — test use only */
+export declare function _resetContextManager(): void;

package/dist/infrastructure/context_manager/context_api.js

@@ -0,0 +1,55 @@
+import { StackContextManager } from "./stack_context_manager";
+const _manager = new StackContextManager();
+/** Returns the context active in the current execution scope. */
+export function getActiveContext() {
+    return _manager.active();
+}
+/**
+ * Reads a value from the active context.
+ * Equivalent to getActiveContext().get(key).
+ */
+export function getContext(key) {
+    return _manager.active().get(key);
+}
+/**
+ * Runs fn within ctx as the active context.
+ *
+ * For async functions, ctx stays active until the returned Promise resolves or
+ * rejects — not just until the first await. This means nested calls at any
+ * point in the async chain see the correct context.
+ *
+ * For sync functions, ctx is active for the duration of the call.
+ */
+export function runWithContext(ctx, fn) {
+    _manager.push(ctx);
+    try {
+        const result = fn();
+        if (result instanceof Promise) {
+            return result.then((v) => {
+                _manager.pop();
+                return v;
+            }, (e) => {
+                _manager.pop();
+                throw e;
+            });
+        }
+        _manager.pop();
+        return result;
+    }
+    catch (e) {
+        _manager.pop();
+        throw e;
+    }
+}
+/**
+ * Returns the underlying manager.
+ * Used by interceptor hooks (push/pop) and by adapters (e.g. OTel bridge).
+ * @internal
+ */
+export function _getContextManager() {
+    return _manager;
+}
+/** @internal — test use only */
+export function _resetContextManager() {
+    _manager.reset();
+}

package/dist/infrastructure/context_manager/context_key.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Opaque typed key for storing values in a Context.
+ *
+ * Two calls to createContextKey with the same description produce different
+ * keys — collision between modules is impossible even if they share names.
+ *
+ * _type_marker is a phantom field: it only exists in the TypeScript type
+ * system to carry T through inference. It is never assigned at runtime.
+ */
+export type ContextKey<T> = {
+    readonly description: string;
+    readonly _symbol: symbol;
+    readonly _type_marker: T;
+};
+export declare function createContextKey<T>(description: string): ContextKey<T>;

package/dist/infrastructure/context_manager/context_key.js

@@ -0,0 +1,3 @@
+export function createContextKey(description) {
+    return { description, _symbol: Symbol(description) };
+}