@sincpro/mobile 0.3.1 → 0.4.2

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) };
+}

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

@@ -0,0 +1,107 @@
+import { Context } from "./context";
+import type { ContextKey } from "./context_key";
+import { createContextKey } from "./context_key";
+import { PropagateContext } from "./decorators/propagate_context";
+import { SetContext, WithContext } from "./decorators/with_context";
+import { managed, ManagedContext } from "./managed_context";
+export declare function run<T>(transform: (ctx: Context) => Context, fn: () => T | Promise<T>): T | Promise<T>;
+export declare const ContextManager: {
+    /**
+     * Creates a typed key for storing values in the context.
+     * Each call produces a unique key — define it as a module-level constant.
+     * @example
+     * const TENANT_KEY = ContextManager.createKey<string>("tenant");
+     */
+    readonly createKey: typeof createContextKey;
+    /**
+     * Reads the value for a key from the active context.
+     * Returns undefined if the key was not set in the current stack.
+     */
+    readonly get: <T>(key: ContextKey<T>) => T | undefined;
+    /**
+     * Returns the full active Context (immutable snapshot).
+     */
+    readonly active: () => Context;
+    /**
+     * Runs fn within a transformed context.
+     * The original context is restored automatically on exit, even on error.
+     * @example
+     * await ContextManager.run(
+     *   (ctx) => ctx.set(TENANT_KEY, "acme").set(USER_KEY, user),
+     *   async () => processOrder(order),
+     * );
+     */
+    readonly run: typeof run;
+    /**
+     * Class decorator. Captures the active context at each method call site and
+     * ensures the method body runs within it. Useful for callbacks, event handlers,
+     * or any pattern where the method is invoked outside the original call stack.
+     * @example
+     * \@ContextManager.Propagate
+     * class BleNotificationHandler { ... }
+     */
+    readonly Propagate: typeof PropagateContext;
+    /**
+     * Method decorator. Enriches the active context before the method runs.
+     * Receives the current context and the instance (`self`), returns the new context.
+     * @example
+     * class BleOrchestrator {
+     *   \@ContextManager.Enrich((ctx, self) =>
+     *     ctx.set(DEVICE_KEY, (self as BleOrchestrator).activeDevice)
+     *   )
+     *   async startSession() { ... }
+     * }
+     */
+    readonly Enrich: typeof WithContext;
+    /**
+     * Shorthand for setting a single key before a method runs.
+     * @example
+     * \@ContextManager.Set(TENANT_KEY, "clinic-001")
+     * async handleRequest() { ... }
+     */
+    readonly Set: typeof SetContext;
+    /**
+     * Generator flavor — define acquire and release in one block, `yield` is the hand-off.
+     *
+     * Code before `yield` runs on enter; code after (or inside `catch`) runs on exit.
+     * Pass an optional `key` to also store the value under that key so nested
+     * code can read it via `ContextManager.get(key)`. Without a key, use `.get()`.
+     *
+     * @example
+     * // Auto key
+     * const dbSession = ContextManager.managed(async function* () {
+     *   const session = await db.openSession();
+     *   try { yield session; await session.commit(); }
+     *   catch (e) { await session.rollback(); throw e; }
+     * });
+     * await dbSession.use(async () => { const s = dbSession.get()!; });
+     *
+     * @example
+     * // Shared key
+     * const SESSION_KEY = ContextManager.createKey<DbSession>("db.session");
+     * const dbSession = ContextManager.managed(async function* () {
+     *   yield await db.openSession();
+     * }, SESSION_KEY);
+     * await dbSession.use(async () => { const s = ContextManager.get(SESSION_KEY)!; });
+     */
+    readonly managed: typeof managed;
+    /**
+     * Class flavor — extend and implement `open()` and `close()`.
+     *
+     * Familiar OOP shape; gives explicit types and IDE completion on each hook.
+     * The key is managed internally — read the value via `.get()`.
+     *
+     * @example
+     * class DbSessionContext extends ContextManager.ManagedContext<DbSession> {
+     *   open()                 { return db.openSession(); }
+     *   close(session, error?) { return error ? session.rollback() : session.commit(); }
+     * }
+     *
+     * const dbSession = new DbSessionContext();
+     * await dbSession.use(async () => {
+     *   const session = dbSession.get()!;
+     *   await session.insert(order);
+     * });
+     */
+    readonly ManagedContext: typeof ManagedContext;
+};

package/dist/infrastructure/context_manager/context_manager_facade.js

@@ -0,0 +1,113 @@
+import { getActiveContext, getContext, runWithContext } from "./context_api";
+import { createContextKey } from "./context_key";
+import { PropagateContext } from "./decorators/propagate_context";
+import { SetContext, WithContext } from "./decorators/with_context";
+import { managed, ManagedContext } from "./managed_context";
+export function run(transform, fn) {
+    const ctx = transform(getActiveContext());
+    return runWithContext(ctx, fn);
+}
+export const ContextManager = {
+    /**
+     * Creates a typed key for storing values in the context.
+     * Each call produces a unique key — define it as a module-level constant.
+     * @example
+     * const TENANT_KEY = ContextManager.createKey<string>("tenant");
+     */
+    createKey: createContextKey,
+    /**
+     * Reads the value for a key from the active context.
+     * Returns undefined if the key was not set in the current stack.
+     */
+    get(key) {
+        return getContext(key);
+    },
+    /**
+     * Returns the full active Context (immutable snapshot).
+     */
+    active() {
+        return getActiveContext();
+    },
+    /**
+     * Runs fn within a transformed context.
+     * The original context is restored automatically on exit, even on error.
+     * @example
+     * await ContextManager.run(
+     *   (ctx) => ctx.set(TENANT_KEY, "acme").set(USER_KEY, user),
+     *   async () => processOrder(order),
+     * );
+     */
+    run,
+    /**
+     * Class decorator. Captures the active context at each method call site and
+     * ensures the method body runs within it. Useful for callbacks, event handlers,
+     * or any pattern where the method is invoked outside the original call stack.
+     * @example
+     * \@ContextManager.Propagate
+     * class BleNotificationHandler { ... }
+     */
+    Propagate: PropagateContext,
+    /**
+     * Method decorator. Enriches the active context before the method runs.
+     * Receives the current context and the instance (`self`), returns the new context.
+     * @example
+     * class BleOrchestrator {
+     *   \@ContextManager.Enrich((ctx, self) =>
+     *     ctx.set(DEVICE_KEY, (self as BleOrchestrator).activeDevice)
+     *   )
+     *   async startSession() { ... }
+     * }
+     */
+    Enrich: WithContext,
+    /**
+     * Shorthand for setting a single key before a method runs.
+     * @example
+     * \@ContextManager.Set(TENANT_KEY, "clinic-001")
+     * async handleRequest() { ... }
+     */
+    Set: SetContext,
+    /**
+     * Generator flavor — define acquire and release in one block, `yield` is the hand-off.
+     *
+     * Code before `yield` runs on enter; code after (or inside `catch`) runs on exit.
+     * Pass an optional `key` to also store the value under that key so nested
+     * code can read it via `ContextManager.get(key)`. Without a key, use `.get()`.
+     *
+     * @example
+     * // Auto key
+     * const dbSession = ContextManager.managed(async function* () {
+     *   const session = await db.openSession();
+     *   try { yield session; await session.commit(); }
+     *   catch (e) { await session.rollback(); throw e; }
+     * });
+     * await dbSession.use(async () => { const s = dbSession.get()!; });
+     *
+     * @example
+     * // Shared key
+     * const SESSION_KEY = ContextManager.createKey<DbSession>("db.session");
+     * const dbSession = ContextManager.managed(async function* () {
+     *   yield await db.openSession();
+     * }, SESSION_KEY);
+     * await dbSession.use(async () => { const s = ContextManager.get(SESSION_KEY)!; });
+     */
+    managed,
+    /**
+     * Class flavor — extend and implement `open()` and `close()`.
+     *
+     * Familiar OOP shape; gives explicit types and IDE completion on each hook.
+     * The key is managed internally — read the value via `.get()`.
+     *
+     * @example
+     * class DbSessionContext extends ContextManager.ManagedContext<DbSession> {
+     *   open()                 { return db.openSession(); }
+     *   close(session, error?) { return error ? session.rollback() : session.commit(); }
+     * }
+     *
+     * const dbSession = new DbSessionContext();
+     * await dbSession.use(async () => {
+     *   const session = dbSession.get()!;
+     *   await session.insert(order);
+     * });
+     */
+    ManagedContext,
+};

package/dist/infrastructure/context_manager/decorators/propagate_context.d.ts

@@ -0,0 +1,24 @@
+type AnyClass = new (...args: never[]) => object;
+/**
+ * Class decorator. Captures the active context at the moment each method is
+ * called and ensures the method body runs within that context.
+ *
+ * Useful for classes whose methods may be invoked from callbacks, event
+ * handlers, or fire-and-forget patterns where the caller's context would
+ * otherwise be lost by the time the method executes.
+ *
+ * For the common sequential-await pattern, context propagates automatically
+ * via the stack — @PropagateContext adds value mainly when methods are called
+ * outside of a runWithContext block or after a timer/event boundary.
+ *
+ * @example
+ * @PropagateContext
+ * class BleNotificationService {
+ *   onHeartRateReading(value: number) {
+ *     // context active when the listener was registered is visible here
+ *     const device = getContext(DEVICE_KEY);
+ *   }
+ * }
+ */
+export declare function PropagateContext<T extends AnyClass>(target: T): T;
+export {};

package/dist/infrastructure/context_manager/decorators/propagate_context.js

@@ -0,0 +1,52 @@
+import { getActiveContext, runWithContext } from "../context_api";
+const PROPAGATED = Symbol("sincpro.context.propagated");
+/**
+ * Class decorator. Captures the active context at the moment each method is
+ * called and ensures the method body runs within that context.
+ *
+ * Useful for classes whose methods may be invoked from callbacks, event
+ * handlers, or fire-and-forget patterns where the caller's context would
+ * otherwise be lost by the time the method executes.
+ *
+ * For the common sequential-await pattern, context propagates automatically
+ * via the stack — @PropagateContext adds value mainly when methods are called
+ * outside of a runWithContext block or after a timer/event boundary.
+ *
+ * @example
+ * @PropagateContext
+ * class BleNotificationService {
+ *   onHeartRateReading(value: number) {
+ *     // context active when the listener was registered is visible here
+ *     const device = getContext(DEVICE_KEY);
+ *   }
+ * }
+ */
+export function PropagateContext(target) {
+    if (target[PROPAGATED]) {
+        throw new Error(`PropagateContext: ${target.name} is already decorated`);
+    }
+    const prototype = target.prototype;
+    for (const key of Object.getOwnPropertyNames(prototype)) {
+        if (key === "constructor")
+            continue;
+        const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+        if (!descriptor || typeof descriptor.value !== "function")
+            continue;
+        const original = descriptor.value;
+        descriptor.value = function (...args) {
+            const ctx = getActiveContext();
+            const result = runWithContext(ctx, () => original.apply(this, args));
+            if (result instanceof Promise) {
+                // Context was captured at call time (above). The Promise itself
+                // resolves outside the runWithContext scope — that is expected for
+                // the stack-based manager. Sequential awaits inside the method body
+                // already saw the correct context when they were initiated.
+                return result;
+            }
+            return result;
+        };
+        Object.defineProperty(prototype, key, descriptor);
+    }
+    Object.defineProperty(target, PROPAGATED, { value: true, enumerable: false });
+    return target;
+}

package/dist/infrastructure/context_manager/decorators/with_context.d.ts

@@ -0,0 +1,34 @@
+import { Context } from "../context";
+import type { ContextKey } from "../context_key";
+/**
+ * Method decorator. Before calling the method, applies transform to the
+ * active context and runs the method within the resulting context.
+ *
+ * Useful when a method needs to enrich the context with values available
+ * on the instance (e.g. the current BLE device, the active session ID).
+ *
+ * transform receives the current active context and must return the new one.
+ * The instance (this) is passed as second argument so instance properties
+ * are accessible without closure hacks.
+ *
+ * @example
+ * class BleOrchestrator {
+ *   private activeDevice: BleDevice;
+ *
+ *   @WithContext((ctx, self) =>
+ *     ctx.set(DEVICE_KEY, (self as BleOrchestrator).activeDevice)
+ *   )
+ *   async startSession() {
+ *     // DEVICE_KEY is now in context for every nested call
+ *   }
+ * }
+ */
+export declare function WithContext(transform: (ctx: Context, self: unknown) => Context): MethodDecorator;
+/**
+ * Shorthand for setting a single key before a method runs.
+ *
+ * @example
+ * @SetContext(TENANT_KEY, "clinic-001")
+ * async handleRequest() { ... }
+ */
+export declare function SetContext<T>(key: ContextKey<T>, value: T): MethodDecorator;

package/dist/infrastructure/context_manager/decorators/with_context.js

@@ -0,0 +1,44 @@
+import { getActiveContext, runWithContext } from "../context_api";
+/**
+ * Method decorator. Before calling the method, applies transform to the
+ * active context and runs the method within the resulting context.
+ *
+ * Useful when a method needs to enrich the context with values available
+ * on the instance (e.g. the current BLE device, the active session ID).
+ *
+ * transform receives the current active context and must return the new one.
+ * The instance (this) is passed as second argument so instance properties
+ * are accessible without closure hacks.
+ *
+ * @example
+ * class BleOrchestrator {
+ *   private activeDevice: BleDevice;
+ *
+ *   @WithContext((ctx, self) =>
+ *     ctx.set(DEVICE_KEY, (self as BleOrchestrator).activeDevice)
+ *   )
+ *   async startSession() {
+ *     // DEVICE_KEY is now in context for every nested call
+ *   }
+ * }
+ */
+export function WithContext(transform) {
+    return function (_target, _key, descriptor) {
+        const original = descriptor.value;
+        descriptor.value = function (...args) {
+            const ctx = transform(getActiveContext(), this);
+            return runWithContext(ctx, () => original.apply(this, args));
+        };
+        return descriptor;
+    };
+}
+/**
+ * Shorthand for setting a single key before a method runs.
+ *
+ * @example
+ * @SetContext(TENANT_KEY, "clinic-001")
+ * async handleRequest() { ... }
+ */
+export function SetContext(key, value) {
+    return WithContext((ctx) => ctx.set(key, value));
+}

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

@@ -0,0 +1,11 @@
+export { ContextManager } from "./context_manager_facade";
+export { Context } from "./context";
+export { getActiveContext, getContext, runWithContext } from "./context_api";
+export type { ContextKey } from "./context_key";
+export { createContextKey } from "./context_key";
+export { PropagateContext } from "./decorators/propagate_context";
+export { SetContext, WithContext } from "./decorators/with_context";
+export type { ContextScope } from "./managed_context";
+export { managed, ManagedContext } from "./managed_context";
+export { _getContextManager, _resetContextManager } from "./context_api";
+export { StackContextManager } from "./stack_context_manager";

package/dist/infrastructure/context_manager/index.js

@@ -0,0 +1,12 @@
+// Main entry point — public facade for framework consumers
+export { ContextManager } from "./context_manager_facade";
+// Public API — safe for framework consumers
+export { Context } from "./context";
+export { getActiveContext, getContext, runWithContext } from "./context_api";
+export { createContextKey } from "./context_key";
+export { PropagateContext } from "./decorators/propagate_context";
+export { SetContext, WithContext } from "./decorators/with_context";
+export { managed, ManagedContext } from "./managed_context";
+// Internal API — for framework adapters and tests only, not for app consumers
+export { _getContextManager, _resetContextManager } from "./context_api";
+export { StackContextManager } from "./stack_context_manager";

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

@@ -0,0 +1,87 @@
+import type { ContextKey } from "./context_key";
+/**
+ * Contract exposed by both managed context flavors.
+ *
+ * Acquire the resource, run a block with it in context, then release —
+ * all guaranteed even on error.
+ */
+export interface ContextScope<T> {
+    /**
+     * Reads the current value from the active context.
+     * Returns `undefined` when called outside an active `use()` block.
+     *
+     * @example
+     * await dbSession.use(async () => {
+     *   const session = dbSession.get(); // defined here
+     * });
+     * dbSession.get(); // undefined — outside the block
+     */
+    get(): T | undefined;
+    /**
+     * Acquires the resource, pushes it into context, calls `fn`, then releases.
+     * The resource is available via `.get()` (or the `fn` argument) throughout
+     * the call, including any nested async code on the same stack.
+     *
+     * @example
+     * await dbSession.use(async (session) => {
+     *   await session.insert(order);
+     * });
+     */
+    use<R>(fn: (value: T) => R | Promise<R>): Promise<R>;
+    /**
+     * Method decorator. Wraps the decorated method in a `use()` call.
+     * The resource is acquired before the method runs and released after.
+     * Read the value inside the method via `.get()`.
+     *
+     * @example
+     * class OrderRepository {
+     *   \@dbSession.inject
+     *   async save(order: Order) {
+     *     const session = dbSession.get()!;
+     *     await session.insert(order);
+     *   }
+     * }
+     */
+    inject: MethodDecorator;
+}
+export declare function managed<T>(factory: () => AsyncGenerator<T, void, unknown>, key?: ContextKey<T>): ContextScope<T>;
+/**
+ * Class flavor — extend and implement `open()` and `close()`.
+ *
+ * Gives explicit method signatures and IDE completion on each lifecycle hook.
+ * The key is managed internally; read the value via `.get()` anywhere in the
+ * active stack.
+ *
+ * Optionally declare a `readonly key` to share the value under a known key,
+ * making it readable via `ContextManager.get(key)` from nested code.
+ *
+ * @example
+ * // Auto key — read via instance.get()
+ * class DbSessionContext extends ContextManager.ManagedContext<DbSession> {
+ *   open()                 { return db.openSession(); }
+ *   close(session, error?) { return error ? session.rollback() : session.commit(); }
+ * }
+ * const dbSession = new DbSessionContext();
+ * await dbSession.use(async () => {
+ *   const session = dbSession.get()!;
+ * });
+ *
+ * @example
+ * // Shared key — readable via ContextManager.get(SESSION_KEY) from nested code
+ * const SESSION_KEY = ContextManager.createKey<DbSession>("db.session");
+ * class DbSessionContext extends ContextManager.ManagedContext<DbSession> {
+ *   readonly key = SESSION_KEY;
+ *   open()                 { return db.openSession(); }
+ *   close(session, error?) { return error ? session.rollback() : session.commit(); }
+ * }
+ */
+export declare abstract class ManagedContext<T> implements ContextScope<T> {
+    readonly key?: ContextKey<T>;
+    private _scope;
+    private _getScope;
+    abstract open(): T | Promise<T>;
+    abstract close(value: T, error?: unknown): void | Promise<void>;
+    get(): T | undefined;
+    use<R>(fn: (value: T) => R | Promise<R>): Promise<R>;
+    get inject(): MethodDecorator;
+}