@sincpro/mobile 0.1.0

package/dist/framework/orchestrator.js

@@ -0,0 +1,118 @@
+import { cron } from "../entrypoints/cron/Cron";
+import { QueueProcessor } from "../entrypoints/queue/QueueProcessor";
+import logger from "../infrastructure/logger";
+import { AppState } from "react-native";
+class Orchestrator {
+    kernel = null;
+    authenticated = false;
+    activeDomains = new Set();
+    sharedKeys = new Set();
+    appStateSubscription = null;
+    appStateCallbacks = [];
+    mutex = Promise.resolve();
+    configure(kernel) {
+        this.kernel = kernel;
+        this.authenticated = false;
+        this.sharedKeys = new Set(kernel.sharedKeys());
+        this.activeDomains = new Set(kernel.keys());
+    }
+    requireKernel() {
+        if (!this.kernel) {
+            throw new Error("Orchestrator not configured. Call createApp() first.");
+        }
+        return this.kernel;
+    }
+    async withMutex(operation) {
+        const previous = this.mutex;
+        let release;
+        this.mutex = new Promise((resolve) => (release = resolve));
+        try {
+            await previous;
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    async orchestrateQueue() {
+        await QueueProcessor.sync(this.activeDomains, this.authenticated, this.requireKernel().subscribersByKey());
+    }
+    async orchestrateCron() {
+        await cron.sync(this.activeDomains, this.authenticated, this.requireKernel().cronsByKey());
+    }
+    async restoreConsistency() {
+        await this.orchestrateQueue();
+        await this.orchestrateCron();
+    }
+    initAppStateWatcher() {
+        if (this.appStateSubscription)
+            return;
+        const subscription = AppState.addEventListener("change", async (state) => {
+            if (state === "active") {
+                await this.restoreConsistency();
+            }
+            this.appStateCallbacks.forEach((callback) => callback(state));
+        });
+        this.appStateSubscription = () => subscription.remove();
+    }
+    async bootstrap() {
+        await this.requireKernel().bootstrap();
+        QueueProcessor.start();
+        await this.orchestrateQueue();
+        await this.orchestrateCron();
+        this.initAppStateWatcher();
+        logger.info("[Orchestrator] Infrastructure ready");
+    }
+    async authenticateSession() {
+        this.authenticated = true;
+        await this.orchestrateQueue();
+        await this.orchestrateCron();
+    }
+    async restoreSession() {
+        this.authenticated = true;
+        await this.orchestrateQueue();
+        await this.orchestrateCron();
+    }
+    async unauthenticateSession(cleanData = true) {
+        this.authenticated = false;
+        await this.orchestrateQueue();
+        await this.orchestrateCron();
+        if (cleanData) {
+            await QueueProcessor.clearQueue();
+            await this.requireKernel().restartDatabase();
+        }
+    }
+    async enableDomain(key) {
+        if (this.activeDomains.has(key))
+            return;
+        this.activeDomains.add(key);
+        await this.withMutex(async () => {
+            await this.orchestrateQueue();
+            await this.orchestrateCron();
+        });
+    }
+    async disableDomain(key) {
+        if (this.sharedKeys.has(key))
+            return;
+        if (!this.activeDomains.has(key))
+            return;
+        this.activeDomains.delete(key);
+        await this.withMutex(async () => {
+            await this.orchestrateQueue();
+            await this.orchestrateCron();
+        });
+    }
+    isSessionAuthenticated() {
+        return this.authenticated;
+    }
+    subscribeToAppState(callback) {
+        this.appStateCallbacks.push(callback);
+        return () => {
+            const index = this.appStateCallbacks.indexOf(callback);
+            if (index > -1) {
+                this.appStateCallbacks.splice(index, 1);
+            }
+        };
+    }
+}
+export const orchestrator = new Orchestrator();

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export type { AppShellConfig } from "./entrypoints/ui/AppShell";
+export { createAppShell } from "./entrypoints/ui/AppShell";
+export type { TimezoneLocale } from "./entrypoints/ui/common_provider";
+export { CommonProvider, useCommon } from "./entrypoints/ui/common_provider";
+export type { DomainApp } from "./entrypoints/ui/domain_switcher";
+export { ActiveDomainApp, DomainSwitcherProvider, useDomainSwitcher, } from "./entrypoints/ui/domain_switcher";
+export type { DeepPartial, ThemeTokens } from "./entrypoints/ui/theme";
+export { createTheme } from "./entrypoints/ui/theme";
+export { BaseModule, baseModule } from "./framework/base_module";
+export type { AppConfig } from "./framework/createApp";
+export { createApp } from "./framework/createApp";
+export { DomainModule } from "./framework/domain_module";
+export { Kernel } from "./framework/kernel";
+export { orchestrator } from "./framework/orchestrator";
+export { installGlobalErrorHandler } from "./infrastructure/ui/errorHandler";
+export { PlainLayout, TabNavigatorLayout } from "./ui/layouts/router_layouts";

package/dist/index.js

@@ -0,0 +1,11 @@
+export { createAppShell } from "./entrypoints/ui/AppShell";
+export { CommonProvider, useCommon } from "./entrypoints/ui/common_provider";
+export { ActiveDomainApp, DomainSwitcherProvider, useDomainSwitcher, } from "./entrypoints/ui/domain_switcher";
+export { createTheme } from "./entrypoints/ui/theme";
+export { BaseModule, baseModule } from "./framework/base_module";
+export { createApp } from "./framework/createApp";
+export { DomainModule } from "./framework/domain_module";
+export { Kernel } from "./framework/kernel";
+export { orchestrator } from "./framework/orchestrator";
+export { installGlobalErrorHandler } from "./infrastructure/ui/errorHandler";
+export { PlainLayout, TabNavigatorLayout } from "./ui/layouts/router_layouts";

package/dist/infrastructure/database/connector.d.ts

@@ -0,0 +1,13 @@
+import { SQLiteDatabase, SQLiteRunResult, SQLiteVariadicBindParams } from "expo-sqlite";
+export declare const DB_NAME = "distribution.db";
+export declare function getDatabase(): Promise<SQLiteDatabase>;
+export declare function getDatabaseSync(): SQLiteDatabase;
+export declare const DBCursor: {
+    mutateDatabase(query: string, ...params: SQLiteVariadicBindParams): Promise<SQLiteRunResult>;
+    getFirstAsync<T>(query: string, ...params: SQLiteVariadicBindParams): Promise<T | null>;
+    getAllAsync<T>(query: string, ...params: SQLiteVariadicBindParams): Promise<T[]>;
+    execAsync(query: string): Promise<void>;
+    getFirstSync<T>(query: string, ...params: SQLiteVariadicBindParams): T | null;
+    getAllSync<T>(query: string, ...params: SQLiteVariadicBindParams): T[];
+    mutateDatabaseSync(query: string, ...params: SQLiteVariadicBindParams): SQLiteRunResult;
+};

package/dist/infrastructure/database/connector.js

@@ -0,0 +1,165 @@
+import logger, { loggerRepositories } from "../../infrastructure/logger";
+import { Mutex } from "async-mutex";
+import { openDatabaseAsync, openDatabaseSync, } from "expo-sqlite";
+export const DB_NAME = "distribution.db";
+let dbInstance = null;
+const dbLock = new Mutex();
+const SKIP_LOG_TABLES = ["event_queue", "dead_letter_queue"];
+function shouldLogQuery(query) {
+    const lowerQuery = query.toLowerCase();
+    return !SKIP_LOG_TABLES.some((table) => lowerQuery.includes(table));
+}
+async function initDatabase() {
+    logger.info("Initializing database connection...");
+    const db = await openDatabaseAsync(DB_NAME);
+    await db.execAsync("PRAGMA journal_mode = WAL;");
+    await db.execAsync("PRAGMA foreign_keys = ON;");
+    return db;
+}
+export async function getDatabase() {
+    if (!dbInstance) {
+        dbInstance = await initDatabase();
+    }
+    return dbInstance;
+}
+function initDatabaseSync() {
+    logger.info("Initializing database connection (sync)...");
+    const db = openDatabaseSync(DB_NAME);
+    db.execSync("PRAGMA journal_mode = WAL;");
+    db.execSync("PRAGMA foreign_keys = ON;");
+    return db;
+}
+export function getDatabaseSync() {
+    if (!dbInstance) {
+        dbInstance = initDatabaseSync();
+    }
+    return dbInstance;
+}
+async function withDB(fn) {
+    return dbLock.runExclusive(async () => fn(await getDatabase()));
+}
+function withDBSync(fn) {
+    return fn(getDatabaseSync());
+}
+export const DBCursor = {
+    async mutateDatabase(query, ...params) {
+        const safeQuery = `${query.trim()};`;
+        return withDB(async (db) => {
+            try {
+                if (shouldLogQuery(safeQuery)) {
+                    loggerRepositories.info(`Database mutation: ${safeQuery}]`);
+                }
+                const result = await db.runAsync(safeQuery, ...params);
+                if (shouldLogQuery(safeQuery)) {
+                    loggerRepositories.debug("Database mutation result:", result.lastInsertRowId);
+                }
+                return result;
+            }
+            catch (error) {
+                loggerRepositories.error("Database mutation error:", error);
+                loggerRepositories.error("SQL:", safeQuery, params);
+                throw error;
+            }
+        });
+    },
+    async getFirstAsync(query, ...params) {
+        const safeQuery = `${query.trim()};`;
+        return withDB(async (db) => {
+            try {
+                if (shouldLogQuery(safeQuery)) {
+                    loggerRepositories.info("Database query:", safeQuery, params);
+                }
+                return await db.getFirstAsync(safeQuery, ...params);
+            }
+            catch (error) {
+                loggerRepositories.error("Database query error:", error);
+                loggerRepositories.error("SQL:", safeQuery, params);
+                throw error;
+            }
+        });
+    },
+    async getAllAsync(query, ...params) {
+        const safeQuery = `${query.trim()};`;
+        return withDB(async (db) => {
+            try {
+                if (shouldLogQuery(safeQuery)) {
+                    loggerRepositories.info("Database query:", safeQuery, params);
+                }
+                return await db.getAllAsync(safeQuery, ...params);
+            }
+            catch (error) {
+                loggerRepositories.error("Database query error:", error);
+                loggerRepositories.error("SQL:", safeQuery, params);
+                throw error;
+            }
+        });
+    },
+    async execAsync(query) {
+        const safeQuery = `${query.trim()};`;
+        return withDB(async (db) => {
+            try {
+                if (shouldLogQuery(safeQuery)) {
+                    loggerRepositories.info("Executing database command:", safeQuery);
+                }
+                await db.execAsync(safeQuery);
+            }
+            catch (error) {
+                loggerRepositories.error("Database command error:", error);
+                loggerRepositories.error("SQL:", safeQuery);
+                throw error;
+            }
+        });
+    },
+    getFirstSync(query, ...params) {
+        const safeQuery = `${query.trim()};`;
+        return withDBSync((db) => {
+            try {
+                if (shouldLogQuery(safeQuery)) {
+                    loggerRepositories.debug("Sync database query:", safeQuery);
+                }
+                return db.getFirstSync(safeQuery, ...params);
+            }
+            catch (error) {
+                loggerRepositories.error("Sync database query error:", error);
+                loggerRepositories.error("SQL:", safeQuery, params);
+                throw error;
+            }
+        });
+    },
+    getAllSync(query, ...params) {
+        const safeQuery = `${query.trim()};`;
+        return withDBSync((db) => {
+            try {
+                if (shouldLogQuery(safeQuery)) {
+                    loggerRepositories.debug("Sync database query:", safeQuery);
+                }
+                return db.getAllSync(safeQuery, ...params);
+            }
+            catch (error) {
+                loggerRepositories.error("Sync database query error:", error);
+                loggerRepositories.error("SQL:", safeQuery, params);
+                throw error;
+            }
+        });
+    },
+    mutateDatabaseSync(query, ...params) {
+        const safeQuery = `${query.trim()};`;
+        return withDBSync((db) => {
+            try {
+                if (shouldLogQuery(safeQuery)) {
+                    loggerRepositories.debug("Sync database mutation:", safeQuery);
+                }
+                const result = db.runSync(safeQuery, ...params);
+                if (shouldLogQuery(safeQuery)) {
+                    loggerRepositories.debug("Sync mutation result:", result.lastInsertRowId);
+                }
+                return result;
+            }
+            catch (error) {
+                loggerRepositories.error("Sync database mutation error:", error);
+                loggerRepositories.error("SQL:", safeQuery, params);
+                throw error;
+            }
+        });
+    },
+};

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

@@ -0,0 +1,2 @@
+export { DB_NAME, DBCursor } from "./connector";
+export { mapped, resolveEntity } from "./mapped";

package/dist/infrastructure/database/index.js

@@ -0,0 +1,2 @@
+export { DB_NAME, DBCursor } from "./connector";
+export { mapped, resolveEntity } from "./mapped";

package/dist/infrastructure/database/mapped.d.ts

@@ -0,0 +1,128 @@
+import type { RepositoriesContainer } from "../../entrypoints/db/repositories";
+/**
+ * Initializes the repository facade for use with the @mapped decorator.
+ *
+ * This function MUST be called during application bootstrap, after all repositories
+ * are loaded but before any entity with @mapped decorator is instantiated.
+ *
+ * @param repos - The repository facade object containing all domain repositories
+ *
+ * @example
+ * // In your app bootstrap (e.g., InfrastructureOrchestrator)
+ * import { initializeRepositoryFacade } from "../../infrastructure/database";
+ * import { repos } from "../../entrypoints/db";
+ *
+ * async function bootstrap() {
+ *   await initDatabase();
+ *   initializeRepositoryFacade(repos); // ← Initialize after DB and repos are ready
+ *   await runMigrations();
+ * }
+ */
+export declare function initializeRepositoryFacade(repos: RepositoriesContainer): void;
+/**
+ * Resolves an entity or collection from repository by foreign key value.
+ *
+ * @param repositoryKey - Repository enum key (EDistributionRepository, ECommonRepository)
+ * @param fkValue - Foreign key: single ID (uuid/remoteId) or array of IDs
+ * @param remote - Use remoteId lookup instead of uuid (default: false)
+ * @returns Single entity, EntityCollection, or undefined if not found
+ * @throws DomainAppError if repository key doesn't exist in registry
+ *
+ * @example
+ * // Local entity by uuid
+ * const customer = resolveEntity(EDistributionRepository.CUSTOMER, "uuid-123");
+ *
+ * @example
+ * // Remote entity by remoteId
+ * const product = resolveEntity(EDistributionRepository.PRODUCT, 456, true);
+ *
+ * @example
+ * // Collection by array of IDs
+ * const payments = resolveEntity(EDistributionRepository.PAYMENT, [1, 2, 3], true);
+ *
+ * @example
+ * // Usage in Entity to refresh from DB
+ * async getRefreshedEntity(repositoryKey: string): Promise<this> {
+ *   return resolveEntity(repositoryKey, this.uuid) as this;
+ * }
+ */
+export declare function resolveEntity(repositoryKey: string, fkValue: any, remote?: boolean): any;
+/**
+ * Decorator for automatic runtime resolution of database relations using synchronous queries.
+ *
+ * This decorator enables entities to resolve their relationships automatically using getters,
+ * eliminating the need for manual hydration functions and avoiding circular import issues.
+ *
+ * **Important:** This decorator does NOT cache results. Every access to the getter will
+ * query the database to ensure you always get fresh, up-to-date data.
+ *
+ * It works by:
+ * 1. Detecting the foreign key type (scalar vs array) automatically
+ * 2. Calling the appropriate repository sync method (findByIdSync or findByIdsSync)
+ * 3. Returning fresh data on every access (no caching)
+ *
+ * @param repositoryKey - The repository key from the enum (EDistributionRepository or ECommonRepository)
+ * @param foreignKey - The name of the property on the entity that contains the foreign key (ID or array of IDs)
+ *
+ * @param remote - Optional flag indicating if the foreign keys are remote IDs.
+ * @returns A decorator function that can be applied to entity getters
+ *
+ * @example
+ * // One-to-One relationship (hasOne)
+ * import { mapped } from "../../infrastructure/database";
+ * import { EDistributionDomainRepository } from "../../entrypoints/db";
+ *
+ * export class SaleOrder {
+ *   customerId: number;
+ *
+ *   @mapped(EDistributionDomainRepository.CUSTOMER, "customerId")
+ *   get customer() {
+ *     return undefined; // This value is replaced by the decorator at runtime
+ *   }
+ * }
+ *
+ * // Usage:
+ * const order = new SaleOrder({ id: 1, customerId: 123 });
+ * console.log(order.customer.name); // Queries database on every access
+ * console.log(order.customer.vat);  // Queries database again (fresh data)
+ *
+ * @example
+ * // One-to-Many relationship (hasMany)
+ * export class SaleOrder {
+ *   paymentIds: number[];
+ *
+ *   @mapped(EDistributionRepository.PAYMENT, "paymentIds")
+ *   get payments() {
+ *     return []; // This value is replaced by the decorator at runtime
+ *   }
+ * }
+ *
+ * // Usage:
+ * const order = new SaleOrder({ id: 1, paymentIds: [10, 20, 30] });
+ * order.payments.forEach(payment => console.log(payment.amount)); // Fresh data on every access
+ *
+ * @remarks
+ * **Requirements:**
+ * - The target repository MUST implement `findByIdSync()` for scalar foreign keys
+ * - The target repository MUST implement `findByIdsSync()` for array foreign keys
+ * - The database must be initialized before accessing decorated properties
+ *
+ * **Advantages:**
+ * - ✅ No circular import issues (uses enum-based repository keys resolved at runtime)
+ * - ✅ Automatic type detection (scalar vs array)
+ * - ✅ Always returns fresh data from the database (no stale cache)
+ * - ✅ Clean, declarative syntax
+ * - ✅ Type-safe when using repository enums
+ * - ✅ No memory overhead from caching
+ * - ✅ No domain knowledge needed - just use the enum
+ *
+ * **Limitations:**
+ * - ⚠️ Blocks the main thread on every access (uses synchronous SQLite queries)
+ * - ⚠️ Performance cost on repeated access (queries database each time)
+ * - ⚠️ Only works for simple ID-based lookups (no complex filters or joins)
+ * - ⚠️ Repository must support sync operations (optional methods in IRepository)
+ *
+ * @see {@link IRepository.findByIdSync} - Required repository method for hasOne relations
+ * @see {@link IRepository.findByIdsSync} - Required repository method for hasMany relations
+ */
+export declare function mapped(repositoryKey: string, foreignKey: string, remote?: boolean): (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;

package/dist/infrastructure/database/mapped.js

@@ -0,0 +1,174 @@
+import { DomainAppError } from "../../exceptions";
+import { loggerRepositories } from "../../infrastructure/logger";
+/**
+ * Repository facade reference that will be injected after initialization.
+ * This avoids circular import issues by delaying the repository resolution.
+ */
+let repositoryFacade = null;
+/**
+ * Initializes the repository facade for use with the @mapped decorator.
+ *
+ * This function MUST be called during application bootstrap, after all repositories
+ * are loaded but before any entity with @mapped decorator is instantiated.
+ *
+ * @param repos - The repository facade object containing all domain repositories
+ *
+ * @example
+ * // In your app bootstrap (e.g., InfrastructureOrchestrator)
+ * import { initializeRepositoryFacade } from "../../infrastructure/database";
+ * import { repos } from "../../entrypoints/db";
+ *
+ * async function bootstrap() {
+ *   await initDatabase();
+ *   initializeRepositoryFacade(repos); // ← Initialize after DB and repos are ready
+ *   await runMigrations();
+ * }
+ */
+export function initializeRepositoryFacade(repos) {
+    repositoryFacade = repos;
+    loggerRepositories.info("[Mapped] Repository facade initialized for @mapped decorator");
+}
+function resolveEntityInternal(context, repositoryKey, fkValue, remote = false) {
+    if (!repositoryFacade) {
+        throw new DomainAppError(`[${context}] Repository facade not initialized. ` +
+            "Call initializeRepositoryFacade(repos) during app bootstrap.");
+    }
+    try {
+        repositoryFacade.get(repositoryKey);
+    }
+    catch (error) {
+        throw new DomainAppError(`[${context}] ${error.message}`);
+    }
+    return repositoryFacade.resolveRelation(repositoryKey, fkValue, remote);
+}
+/**
+ * Resolves an entity or collection from repository by foreign key value.
+ *
+ * @param repositoryKey - Repository enum key (EDistributionRepository, ECommonRepository)
+ * @param fkValue - Foreign key: single ID (uuid/remoteId) or array of IDs
+ * @param remote - Use remoteId lookup instead of uuid (default: false)
+ * @returns Single entity, EntityCollection, or undefined if not found
+ * @throws DomainAppError if repository key doesn't exist in registry
+ *
+ * @example
+ * // Local entity by uuid
+ * const customer = resolveEntity(EDistributionRepository.CUSTOMER, "uuid-123");
+ *
+ * @example
+ * // Remote entity by remoteId
+ * const product = resolveEntity(EDistributionRepository.PRODUCT, 456, true);
+ *
+ * @example
+ * // Collection by array of IDs
+ * const payments = resolveEntity(EDistributionRepository.PAYMENT, [1, 2, 3], true);
+ *
+ * @example
+ * // Usage in Entity to refresh from DB
+ * async getRefreshedEntity(repositoryKey: string): Promise<this> {
+ *   return resolveEntity(repositoryKey, this.uuid) as this;
+ * }
+ */
+export function resolveEntity(repositoryKey, fkValue, remote = false) {
+    return resolveEntityInternal("resolveEntity", repositoryKey, fkValue, remote);
+}
+/**
+ * Decorator for automatic runtime resolution of database relations using synchronous queries.
+ *
+ * This decorator enables entities to resolve their relationships automatically using getters,
+ * eliminating the need for manual hydration functions and avoiding circular import issues.
+ *
+ * **Important:** This decorator does NOT cache results. Every access to the getter will
+ * query the database to ensure you always get fresh, up-to-date data.
+ *
+ * It works by:
+ * 1. Detecting the foreign key type (scalar vs array) automatically
+ * 2. Calling the appropriate repository sync method (findByIdSync or findByIdsSync)
+ * 3. Returning fresh data on every access (no caching)
+ *
+ * @param repositoryKey - The repository key from the enum (EDistributionRepository or ECommonRepository)
+ * @param foreignKey - The name of the property on the entity that contains the foreign key (ID or array of IDs)
+ *
+ * @param remote - Optional flag indicating if the foreign keys are remote IDs.
+ * @returns A decorator function that can be applied to entity getters
+ *
+ * @example
+ * // One-to-One relationship (hasOne)
+ * import { mapped } from "../../infrastructure/database";
+ * import { EDistributionDomainRepository } from "../../entrypoints/db";
+ *
+ * export class SaleOrder {
+ *   customerId: number;
+ *
+ *   @mapped(EDistributionDomainRepository.CUSTOMER, "customerId")
+ *   get customer() {
+ *     return undefined; // This value is replaced by the decorator at runtime
+ *   }
+ * }
+ *
+ * // Usage:
+ * const order = new SaleOrder({ id: 1, customerId: 123 });
+ * console.log(order.customer.name); // Queries database on every access
+ * console.log(order.customer.vat);  // Queries database again (fresh data)
+ *
+ * @example
+ * // One-to-Many relationship (hasMany)
+ * export class SaleOrder {
+ *   paymentIds: number[];
+ *
+ *   @mapped(EDistributionRepository.PAYMENT, "paymentIds")
+ *   get payments() {
+ *     return []; // This value is replaced by the decorator at runtime
+ *   }
+ * }
+ *
+ * // Usage:
+ * const order = new SaleOrder({ id: 1, paymentIds: [10, 20, 30] });
+ * order.payments.forEach(payment => console.log(payment.amount)); // Fresh data on every access
+ *
+ * @remarks
+ * **Requirements:**
+ * - The target repository MUST implement `findByIdSync()` for scalar foreign keys
+ * - The target repository MUST implement `findByIdsSync()` for array foreign keys
+ * - The database must be initialized before accessing decorated properties
+ *
+ * **Advantages:**
+ * - ✅ No circular import issues (uses enum-based repository keys resolved at runtime)
+ * - ✅ Automatic type detection (scalar vs array)
+ * - ✅ Always returns fresh data from the database (no stale cache)
+ * - ✅ Clean, declarative syntax
+ * - ✅ Type-safe when using repository enums
+ * - ✅ No memory overhead from caching
+ * - ✅ No domain knowledge needed - just use the enum
+ *
+ * **Limitations:**
+ * - ⚠️ Blocks the main thread on every access (uses synchronous SQLite queries)
+ * - ⚠️ Performance cost on repeated access (queries database each time)
+ * - ⚠️ Only works for simple ID-based lookups (no complex filters or joins)
+ * - ⚠️ Repository must support sync operations (optional methods in IRepository)
+ *
+ * @see {@link IRepository.findByIdSync} - Required repository method for hasOne relations
+ * @see {@link IRepository.findByIdsSync} - Required repository method for hasMany relations
+ */
+export function mapped(repositoryKey, foreignKey, remote = false) {
+    return function (target, propertyKey, descriptor) {
+        loggerRepositories.warn(`[Mapped] Setting up mapped relation for ${target.constructor.name}.${propertyKey} ` +
+            `using repository "${repositoryKey}" and foreign key "${foreignKey}"`);
+        const getter = function () {
+            const fkValue = this[foreignKey];
+            if (!fkValue) {
+                return undefined;
+            }
+            return resolveEntityInternal("mapped", repositoryKey, fkValue, remote);
+        };
+        if (descriptor) {
+            descriptor.get = getter;
+        }
+        else {
+            Object.defineProperty(target, propertyKey, {
+                get: getter,
+                enumerable: true,
+                configurable: true,
+            });
+        }
+    };
+}

package/dist/infrastructure/database/utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Constructs a SQL placeholder string and corresponding values for use in a query based on the provided field and data.
+ *
+ * @param {string} field - The database field name to be used in the placeholder condition.
+ * @param {any} data - The data used to generate placeholders and corresponding values. Can be an array, object, set, or a single value.
+ * @return {[string, string]} - A tuple where the first element is the formatted placeholder condition string,
+ * and the second element is the corresponding values. IE: `["field IN (?, ?, ?)", [value1, value2, value3]]`.
+ */
+export declare function getPlaceholders(field: string, data: any | any[]): [string, string];
+export declare function generateUUID(): string;