@sincpro/mobile 0.3.1 → 0.4.1

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

package/dist/infrastructure/context_manager/managed_context.js

@@ -0,0 +1,144 @@
+import { _getContextManager, getContext } from "./context_api";
+import { createContextKey } from "./context_key";
+function buildScope(acquire, release, sharedKey) {
+    const key = sharedKey ?? createContextKey("sincpro.managed");
+    async function run(fn) {
+        const value = await acquire();
+        const manager = _getContextManager();
+        manager.push(manager.active().set(key, value));
+        let thrownError;
+        try {
+            return await fn(value);
+        }
+        catch (e) {
+            thrownError = e;
+            throw e;
+        }
+        finally {
+            manager.pop();
+            await release(value, thrownError);
+        }
+    }
+    const inject = function (_target, _key, descriptor) {
+        const original = descriptor.value;
+        descriptor.value = function (...args) {
+            return run(() => original.apply(this, args));
+        };
+        return descriptor;
+    };
+    return { get: () => getContext(key), use: run, inject };
+}
+/**
+ * Generator flavor — define the full lifecycle in one block.
+ *
+ * Code before `yield` runs on enter; code after `yield` (or inside `catch`)
+ * runs on exit. The yielded value is the resource placed into context — it
+ * must be an object (a primitive cannot carry the lifecycle and throws).
+ *
+ * An optional `key` can be provided to also store the value under that key,
+ * making it readable via `ContextManager.get(key)` from anywhere on the stack.
+ * Without a key, use `.get()` on the scope itself.
+ *
+ * @example
+ * // Auto key — read via scope.get()
+ * 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 session = dbSession.get()!;
+ * });
+ *
+ * @example
+ * // Shared key — readable via ContextManager.get(SESSION_KEY) from nested code
+ * 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 session = ContextManager.get(SESSION_KEY)!;
+ * });
+ */
+const GEN_SYM = Symbol("sincpro.managed.gen");
+export function managed(factory, key) {
+    return buildScope(async () => {
+        const gen = factory();
+        const { value, done } = await gen.next();
+        if (done)
+            throw new Error("managed: generator did not yield a value");
+        // The generator is stamped onto the yielded value so `release` can resume it.
+        // A primitive cannot carry the stamp, which would silently break the
+        // commit/rollback lifecycle — fail fast instead.
+        if (value === null || (typeof value !== "object" && typeof value !== "function")) {
+            await gen
+                .throw(new Error("managed: yielded value must be an object"))
+                .catch(() => { });
+            throw new Error("managed: generator must yield an object (got a primitive)");
+        }
+        value[GEN_SYM] = gen;
+        return value;
+    }, async (value, error) => {
+        const gen = value[GEN_SYM];
+        if (!gen)
+            return;
+        if (error !== undefined) {
+            await gen.throw(error).catch(() => { });
+        }
+        else {
+            await gen.next();
+        }
+    }, key);
+}
+/**
+ * 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 class ManagedContext {
+    key;
+    _scope;
+    // Lazy — subclass key field is set before first call, not at parent field init time
+    _getScope() {
+        return (this._scope ??= buildScope(() => this.open(), (v, e) => this.close(v, e), this.key));
+    }
+    get() {
+        return this._getScope().get();
+    }
+    use(fn) {
+        return this._getScope().use(fn);
+    }
+    get inject() {
+        return this._getScope().inject;
+    }
+}