@zintrust/core 0.1.20 → 0.1.21

package/src/orm/DatabaseRuntimeRegistration.js

@@ -22,6 +22,7 @@ const toOrmConfig = (cfg) => {
                 database: cfg.database,
                 username: cfg.username,
                 password: cfg.password,
+                readHosts: cfg.readHosts,
             };
         case 'mysql':
             return {
@@ -31,6 +32,17 @@ const toOrmConfig = (cfg) => {
                 database: cfg.database,
                 username: cfg.username,
                 password: cfg.password,
+                readHosts: cfg.readHosts,
+            };
+        case 'sqlserver':
+            return {
+                driver: 'sqlserver',
+                host: cfg.host,
+                port: cfg.port,
+                database: cfg.database,
+                username: cfg.username,
+                password: cfg.password,
+                readHosts: cfg.readHosts,
             };
         default:
             // Exhaustive check (kept for future driver additions)

package/src/orm/QueryBuilder.d.ts

@@ -14,7 +14,7 @@ export interface WhereClause {
  * Provides access to the created record ID, affected rows count, and the full record if available
  */
 export interface InsertResult {
-    id: string | number | null;
+    id: string | number | bigint | null;
     affectedRows: number;
     insertedRecords?: Record<string, unknown>[];
 }

package/src/orm/QueryBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"QueryBuilder.d.ts","sourceRoot":"","sources":["../../../src/orm/QueryBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"QueryBuilder.d.ts","sourceRoot":"","sources":["../../../src/orm/QueryBuilder.ts"],"names":[],"mappings":"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"}

package/src/orm/QueryBuilder.js

@@ -570,13 +570,14 @@ function attachWriteMethods(builder, state, db) {
             throw ErrorFactory.createDatabaseError('INSERT requires a table name');
         const compiled = compileInsert(tableName, values, state.dialect);
         const items = Array.isArray(values) ? values : [values];
-        await currentDb.query(compiled.sql, compiled.parameters, false);
+        const result = await currentDb.execute(compiled.sql, compiled.parameters, false);
         // Return InsertResult with metadata
         // Note: lastInsertId typically only available for single-row inserts in most databases
         // For multi-row inserts, use the insertedRecords array
         return {
-            id: items.length === 1 ? (items[0]?.['id'] ?? null) : null,
-            affectedRows: items.length,
+            id: result.lastInsertId ??
+                (items.length === 1 ? (items[0]?.['id'] ?? null) : null),
+            affectedRows: result.rowCount,
             insertedRecords: items,
         };
     };

package/src/orm/adapters/SQLiteAdapter.js

@@ -83,7 +83,7 @@ function executeQuery(db, sql, parameters) {
     if (databaseConfig.logging.enabled) {
         Logger.debug('SQLite query executed', { durationMs: performance.now() - start, sql });
     }
-    return { rows: [], rowCount: info.changes };
+    return { rows: [], rowCount: info.changes, lastInsertId: info.lastInsertRowid };
 }
 function executeRawQuery(db, sql, parameters) {
     const stmt = db.prepare(sql);

package/src/performance/Optimizer.d.ts

@@ -3,16 +3,16 @@
  * Implements caching, lazy-loading, and parallel generation
  */
 export interface IGenerationCache {
-    get(type: string, params: Record<string, unknown>): string | null;
-    set(type: string, params: Record<string, unknown>, code: string): void;
-    save(): void;
-    clear(): void;
-    getStats(): {
+    get(type: string, params: Record<string, unknown>): Promise<string | null>;
+    set(type: string, params: Record<string, unknown>, code: string): Promise<void>;
+    save(): Promise<void>;
+    clear(): Promise<void>;
+    getStats(): Promise<{
         size: number;
         entries: number;
         diskUsage: string;
         keys: string[];
-    };
+    }>;
 }
 /**
  * Generation Cache - Cache generated code to avoid re-generating identical code

package/src/performance/Optimizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Optimizer.d.ts","sourceRoot":"","sources":["../../../src/performance/Optimizer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Optimizer.d.ts","sourceRoot":"","sources":["../../../src/performance/Optimizer.ts"],"names":[],"mappings":"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"}

package/src/performance/Optimizer.js

@@ -95,26 +95,26 @@ function startCacheCleanup(state) {
 function createCacheInstance(state) {
     return {
         /**
-         * Get from cache
+         * Get from cache (async)
          */
-        get(type, params) {
+        async get(type, params) {
             const key = getCacheKey(type, params);
             const entry = state.cache.get(key);
             if (entry === undefined)
-                return null;
+                return Promise.resolve(null); //NoSONAR
             // Check TTL
             if (Date.now() - entry.timestamp > state.ttlMs) {
                 state.cache.delete(key);
                 const file = path.join(state.cacheDir, `${key}.json`);
                 deleteFileNonBlocking(file);
-                return null;
+                return Promise.resolve(null); //NoSONAR
             }
-            return entry.code;
+            return Promise.resolve(entry.code); //NoSONAR
         },
         /**
-         * Set in cache
+         * Set in cache (async)
          */
-        set(type, params, code) {
+        async set(type, params, code) {
             const key = getCacheKey(type, params);
             // If key already exists, delete first so insertion order updates for LRU
             if (state.cache.has(key))
@@ -134,27 +134,36 @@ function createCacheInstance(state) {
                     deleteFileNonBlocking(file);
                 }
             }
+            // Save to disk asynchronously
+            const file = path.join(state.cacheDir, `${key}.json`);
+            try {
+                await fs.fsPromises.access(state.cacheDir);
+            }
+            catch {
+                await fs.fsPromises.mkdir(state.cacheDir, { recursive: true });
+            }
+            await fs.fsPromises.writeFile(file, JSON.stringify({ code, timestamp: Date.now() }, null, 2));
         },
         /**
-         * Save cache to disk
+         * Save cache to disk (async)
          */
-        save() {
-            saveCacheToDisk(state);
+        async save() {
+            await saveCacheToDisk(state);
         },
         /**
-         * Clear cache
+         * Clear cache (async)
          */
-        clear() {
+        async clear() {
             if (state.cleanupInterval) {
                 clearInterval(state.cleanupInterval);
                 state.cleanupInterval = undefined;
             }
-            clearCache(state);
+            await clearCache(state);
         },
         /**
-         * Get cache statistics
+         * Get cache statistics (async)
          */
-        getStats() {
+        async getStats() {
             return getCacheStats(state);
         },
     };
@@ -166,38 +175,66 @@ function attachCacheStateForTests(instance, state) {
     });
 }
 /**
- * Save cache to disk
+ * Save cache to disk (async)
  */
-function saveCacheToDisk(state) {
-    if (fs.existsSync(state.cacheDir) === false) {
-        fs.mkdirSync(state.cacheDir, { recursive: true });
+async function saveCacheToDisk(state) {
+    try {
+        try {
+            await fs.fsPromises.access(state.cacheDir);
+        }
+        catch {
+            await fs.fsPromises.mkdir(state.cacheDir, { recursive: true });
+        }
+        const writes = Array.from(state.cache.entries()).map(async ([key, entry]) => {
+            const file = path.join(state.cacheDir, `${key}.json`);
+            await fs.fsPromises.writeFile(file, JSON.stringify(entry, null, 2));
+        });
+        await Promise.all(writes);
     }
-    for (const [key, entry] of state.cache.entries()) {
-        const file = path.join(state.cacheDir, `${key}.json`);
-        fs.writeFileSync(file, JSON.stringify(entry, null, 2));
+    catch (error) {
+        Logger.error('Failed to save cache to disk', error);
     }
 }
 /**
- * Clear cache
+ * Clear cache (async)
  */
-function clearCache(state) {
+async function clearCache(state) {
     state.cache.clear();
-    if (fs.existsSync(state.cacheDir) === true) {
-        fs.rmSync(state.cacheDir, { recursive: true });
+    try {
+        try {
+            await fs.fsPromises.access(state.cacheDir);
+        }
+        catch {
+            return; // Dir doesn't exist
+        }
+        await fs.fsPromises.rm(state.cacheDir, { recursive: true });
+    }
+    catch (error) {
+        Logger.error('Failed to clear cache', error);
     }
 }
 /**
- * Get cache statistics
+ * Get cache statistics (async)
  */
-function getCacheStats(state) {
+async function getCacheStats(state) {
     let diskUsage = 0;
-    if (fs.existsSync(state.cacheDir) === true) {
-        const files = fs.readdirSync(state.cacheDir);
-        for (const file of files) {
-            const stats = fs.statSync(path.join(state.cacheDir, file));
-            diskUsage += stats.size;
+    try {
+        try {
+            await fs.fsPromises.access(state.cacheDir);
+            const files = await fs.fsPromises.readdir(state.cacheDir);
+            const sizes = await Promise.all(files.map(async (file) => {
+                const stats = await fs.fsPromises.stat(path.join(state.cacheDir, file));
+                return stats.size;
+            }));
+            diskUsage = sizes.reduce((sum, size) => sum + size, 0);
+        }
+        catch {
+            // ignore
         }
     }
+    catch {
+        // ignore
+    }
     return {
         size: diskUsage,
         entries: state.cache.size,
@@ -242,24 +279,39 @@ function toInt32(value) {
     return uint32 > 2147483647 ? uint32 - 4294967296 : uint32;
 }
 /**
- * Load cache from disk
+ * Load cache from disk (async)
  */
-function loadFromDisk(state) {
-    if (fs.existsSync(state.cacheDir) === true) {
+async function loadFromDisk(state) {
+    try {
         try {
-            const files = fs.readdirSync(state.cacheDir);
-            for (const file of files) {
-                if (file.endsWith('.json') === true) {
-                    const content = fs.readFileSync(path.join(state.cacheDir, file), 'utf-8');
-                    const data = JSON.parse(content);
-                    state.cache.set(file.replace('.json', ''), data);
-                }
-            }
+            await fs.fsPromises.access(state.cacheDir);
         }
-        catch (err) {
-            Logger.error(`Failed to load cache from disk: ${err instanceof Error ? err.message : String(err)}`);
+        catch {
+            return;
+        }
+        const files = await fs.fsPromises.readdir(state.cacheDir);
+        const jsonFiles = files.filter((file) => file.endsWith('.json') === true);
+        const parsedEntries = await Promise.all(jsonFiles.map(async (file) => {
+            const filePath = path.join(state.cacheDir, file);
+            const content = await fs.fsPromises.readFile(filePath, 'utf-8');
+            try {
+                const data = JSON.parse(content);
+                return { key: file.replace('.json', ''), data };
+            }
+            catch {
+                // ignore corrupted files
+                return null;
+            }
+        }));
+        for (const entry of parsedEntries) {
+            if (entry !== null) {
+                state.cache.set(entry.key, entry.data);
+            }
         }
     }
+    catch (err) {
+        Logger.error(`Failed to load cache from disk: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }
 /**
  * Lazy Module Loader - Load dependencies only when needed
@@ -474,17 +526,36 @@ async function generateInParallel(stats, generators, batchSize) {
  */
 async function generateWithCache(cache, stats, type, params, generatorFn) {
     // Try cache
-    const cached = cache.get(type, params);
+    let cached = null;
+    try {
+        cached = await cache.get(type, params);
+    }
+    catch (err) {
+        Logger.warn('GenerationCache.get failed; treating as cache miss', {
+            type,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
     if (cached !== null) {
-        stats.cacheHits++;
-        return JSON.parse(cached);
+        try {
+            stats.cacheHits++;
+            return JSON.parse(cached);
+        }
+        catch (err) {
+            Logger.warn('Failed to parse cached generation result; treating as cache miss', {
+                type,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
     }
     // Generate
     const startTime = performance.now();
     const result = await generatorFn();
     const duration = performance.now() - startTime;
-    // Cache result
-    cache.set(type, params, JSON.stringify(result));
+    // Cache result (fire-and-forget)
+    void cache
+        .set(type, params, JSON.stringify(result))
+        .catch((err) => Logger.error('GenerationCache.set failed', err));
     stats.cacheMisses++;
     stats.savedTime += duration;
     return result;
@@ -492,6 +563,16 @@ async function generateWithCache(cache, stats, type, params, generatorFn) {
 /**
  * Get optimization statistics
  */
+function getCacheStatusSync(cache) {
+    const state = cache[GENERATION_CACHE_STATE_SYMBOL];
+    const map = state?.cache;
+    if (!(map instanceof Map))
+        return { size: 0, keys: [] };
+    return {
+        size: map.size,
+        keys: Array.from(map.keys()),
+    };
+}
 function getOptimizerStats(cache, stats) {
     const total = stats.cacheHits + stats.cacheMisses;
     const hitRate = total > 0 ? (stats.cacheHits / total) * 100 : 0;
@@ -501,7 +582,7 @@ function getOptimizerStats(cache, stats) {
         hitRate: `${hitRate.toFixed(1)}%`,
         parallelRuns: stats.parallelRuns,
         estimatedSavedTime: `${stats.savedTime.toFixed(2)}ms`,
-        cacheStatus: cache.getStats(),
+        cacheStatus: getCacheStatusSync(cache),
     };
 }
 export default PerformanceOptimizer;

package/src/routing/doc.d.ts

@@ -8,21 +8,20 @@ export { MIME_TYPES_MAP } from './common';
 /**
  * Find the package root directory
  */
-export { findPackageRoot, getFrameworkPublicRoots, getPublicRoot } from './publicRoot';
+export { findPackageRoot, findPackageRootAsync, getFrameworkPublicRoots, getFrameworkPublicRootsAsync, getPublicRoot, getPublicRootAsync, } from './publicRoot';
 /**
  * Set relaxed CSP headers for docs (allows external assets like Tailwind CDN, Google Fonts)
  */
 export declare const setDocumentationCSPHeaders: (response: IResponse) => void;
 /**
- * Serve a documentation static file
- * Returns true if file was served, false if not found
+ * Serve a documentation static file (async)
  */
-export declare const serveDocumentationFile: (urlPath: string, response: IResponse) => boolean;
+export declare const serveDocumentationFileAsync: (urlPath: string, response: IResponse) => Promise<boolean>;
 export declare const registerDocRoutes: (router: IRouter) => void;
 declare const _default: {
     registerDocRoutes: (router: IRouter) => void;
     setDocumentationCSPHeaders: (response: IResponse) => void;
-    serveDocumentationFile: (urlPath: string, response: IResponse) => boolean;
+    serveDocumentationFileAsync: (urlPath: string, response: IResponse) => Promise<boolean>;
 };
 export default _default;
 //# sourceMappingURL=doc.d.ts.map

package/src/routing/doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../src/routing/doc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAMhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAoB9F;;GAEG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU,SAAS,KAAG,IAWhE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,EAAE,UAAU,SAAS,KAAG,OAkC7E,CAAC;AASF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,OAAO,KAAG,IAMnD,CAAC;;gCANwC,OAAO,KAAG,IAAI;2CA5DH,SAAS,KAAG,IAAI;sCAiBrB,MAAM,YAAY,SAAS,KAAG,OAAO;;AAmDrF,wBAAyF"}
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../src/routing/doc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAMhD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AAEH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,aAAa,EACb,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAiB7B;;GAEG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU,SAAS,KAAG,IAWhE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,GACtC,SAAS,MAAM,EACf,UAAU,SAAS,KAClB,OAAO,CAAC,OAAO,CAgDjB,CAAC;AASF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,OAAO,KAAG,IAMnD,CAAC;;gCANwC,OAAO,KAAG,IAAI;2CA5EH,SAAS,KAAG,IAAI;2CAiB1D,MAAM,YACL,SAAS,KAClB,OAAO,CAAC,OAAO,CAAC;;AAiEnB,wBAIE"}

package/src/routing/doc.js

@@ -8,19 +8,16 @@ import * as fs from '../node-singletons/fs.js';
 import * as path from '../node-singletons/path.js';
 import { MIME_TYPES_MAP, resolveSafePath, tryDecodeURIComponent } from './common.js';
 import { ErrorRouting } from './error.js';
-import { getPublicRoot } from './publicRoot.js';
+import { getPublicRootAsync } from './publicRoot.js';
 import { Router } from './Router.js';
 export { MIME_TYPES_MAP } from './common.js';
 /**
  * Find the package root directory
  */
 // Backward-compatible re-exports
-export { findPackageRoot, getFrameworkPublicRoots, getPublicRoot } from './publicRoot.js';
-/**
- * Map URL path to physical file path for /doc routes
- */
-const mapStaticPath = (urlPath) => {
-    const publicRoot = getPublicRoot();
+export { findPackageRoot, findPackageRootAsync, getFrameworkPublicRoots, getFrameworkPublicRootsAsync, getPublicRoot, getPublicRootAsync, } from './publicRoot.js';
+const mapStaticPathAsync = async (urlPath) => {
+    const publicRoot = await getPublicRootAsync();
     const normalize = (p) => (p.startsWith('/') ? p.slice(1) : p);
     if (urlPath === '/doc' || urlPath === '/doc/')
         return publicRoot;
@@ -45,28 +42,42 @@ export const setDocumentationCSPHeaders = (response) => {
         "font-src 'self' data: https://fonts.gstatic.com;");
 };
 /**
- * Serve a documentation static file
- * Returns true if file was served, false if not found
+ * Serve a documentation static file (async)
  */
-export const serveDocumentationFile = (urlPath, response) => {
-    let filePath = mapStaticPath(urlPath);
+export const serveDocumentationFileAsync = async (urlPath, response) => {
+    let filePath = await mapStaticPathAsync(urlPath);
     if (filePath === undefined) {
         return false;
     }
     try {
-        if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
-            filePath = path.join(filePath, 'index.html');
+        try {
+            const stats = await fs.fsPromises.stat(filePath);
+            if (stats.isDirectory()) {
+                filePath = path.join(filePath, 'index.html');
+            }
+        }
+        catch {
+            // ignore
         }
-        if (!fs.existsSync(filePath) && !path.extname(filePath)) {
+        const exists = async (p) => {
+            try {
+                await fs.fsPromises.access(p);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        if (!(await exists(filePath)) && !path.extname(filePath)) {
             const htmlPath = `${filePath}.html`;
-            if (fs.existsSync(htmlPath)) {
+            if (await exists(htmlPath)) {
                 filePath = htmlPath;
             }
         }
-        if (fs.existsSync(filePath)) {
+        if (await exists(filePath)) {
             const ext = path.extname(filePath).toLowerCase();
             const contentType = MIME_TYPES_MAP[ext] || 'application/octet-stream';
-            const content = fs.readFileSync(filePath);
+            const content = await fs.fsPromises.readFile(filePath);
             response.setStatus(200);
             response.setHeader('Content-Type', contentType);
             response.send(content);
@@ -78,10 +89,10 @@ export const serveDocumentationFile = (urlPath, response) => {
     }
     return false;
 };
-const handleDocRequest = (req, res) => {
+const handleDocRequest = async (req, res) => {
     setDocumentationCSPHeaders(res);
     const urlPath = req.getPath();
-    if (serveDocumentationFile(urlPath, res))
+    if (await serveDocumentationFileAsync(urlPath, res))
         return;
     ErrorRouting.handleNotFound(req, res);
 };
@@ -92,4 +103,8 @@ export const registerDocRoutes = (router) => {
     // Greedy path match for nested assets like /doc/assets/app.js
     Router.get(router, '/doc/:path*', handleDocRequest);
 };
-export default { registerDocRoutes, setDocumentationCSPHeaders, serveDocumentationFile };
+export default {
+    registerDocRoutes,
+    setDocumentationCSPHeaders,
+    serveDocumentationFileAsync,
+};

package/src/routing/publicRoot.d.ts

@@ -6,13 +6,22 @@
  * Find the package root directory.
  */
 export declare const findPackageRoot: (startDir: string) => string;
+/**
+ * Find the package root directory (async).
+ */
+export declare const findPackageRootAsync: (startDir: string) => Promise<string>;
 /**
  * Framework public roots (dist/public preferred).
  */
 export declare const getFrameworkPublicRoots: () => string[];
+export declare const getFrameworkPublicRootsAsync: () => Promise<string[]>;
 /**
  * Resolve the effective public root.
  * Prefers app-local `public/` when present; otherwise falls back to framework public roots.
  */
 export declare const getPublicRoot: () => string;
+/**
+ * Resolve the effective public root (async).
+ */
+export declare const getPublicRootAsync: () => Promise<string>;
 //# sourceMappingURL=publicRoot.d.ts.map

package/src/routing/publicRoot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publicRoot.d.ts","sourceRoot":"","sources":["../../../src/routing/publicRoot.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,KAAG,MASlD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,QAAO,MAAM,EAIhD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAO,MAgBhC,CAAC"}
+{"version":3,"file":"publicRoot.d.ts","sourceRoot":"","sources":["../../../src/routing/publicRoot.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,KAAG,MAalD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAkB3E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,QAAO,MAAM,EAIhD,CAAC;AAEF,eAAO,MAAM,4BAA4B,QAAa,OAAO,CAAC,MAAM,EAAE,CAIrE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAO,MAgBhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,QAAa,OAAO,CAAC,MAAM,CA+BzD,CAAC"}

package/src/routing/publicRoot.js

@@ -11,8 +11,13 @@ import * as path from '../node-singletons/path.js';
 export const findPackageRoot = (startDir) => {
     let current = startDir;
     for (let i = 0; i < 10; i++) {
-        if (fs.existsSync(path.join(current, 'package.json')))
-            return current;
+        try {
+            if (fs.existsSync(path.join(current, 'package.json')))
+                return current;
+        }
+        catch {
+            // ignore access errors
+        }
         const parent = path.dirname(current);
         if (parent === current)
             break;
@@ -20,6 +25,27 @@ export const findPackageRoot = (startDir) => {
     }
     return startDir;
 };
+/**
+ * Find the package root directory (async).
+ */
+export const findPackageRootAsync = async (startDir) => {
+    const findUp = async (current, depth) => {
+        if (depth >= 10)
+            return startDir;
+        try {
+            await fs.fsPromises.access(path.join(current, 'package.json'));
+            return current;
+        }
+        catch {
+            // ignore
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return startDir;
+        return findUp(parent, depth + 1);
+    };
+    return findUp(startDir, 0);
+};
 /**
  * Framework public roots (dist/public preferred).
  */
@@ -28,6 +54,11 @@ export const getFrameworkPublicRoots = () => {
     const packageRoot = findPackageRoot(thisDir);
     return [path.join(packageRoot, 'dist/public'), path.join(packageRoot, 'public')];
 };
+export const getFrameworkPublicRootsAsync = async () => {
+    const thisDir = esmDirname(import.meta.url);
+    const packageRoot = await findPackageRootAsync(thisDir);
+    return [path.join(packageRoot, 'dist/public'), path.join(packageRoot, 'public')];
+};
 /**
  * Resolve the effective public root.
  * Prefers app-local `public/` when present; otherwise falls back to framework public roots.
@@ -47,3 +78,33 @@ export const getPublicRoot = () => {
     }
     return candidates[0];
 };
+/**
+ * Resolve the effective public root (async).
+ */
+export const getPublicRootAsync = async () => {
+    const appRoots = [path.join(process.cwd(), 'public')];
+    const fwRoots = await getFrameworkPublicRootsAsync();
+    const candidates = [...appRoots, ...fwRoots];
+    const exists = async (p) => {
+        try {
+            await fs.fsPromises.access(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const hasIndex = async (root) => exists(path.join(root, 'index.html'));
+    const checks = await Promise.all(candidates.map(async (candidate) => {
+        const rootExists = await exists(candidate);
+        const indexExists = rootExists ? await hasIndex(candidate) : false;
+        return { candidate, rootExists, indexExists };
+    }));
+    const withIndex = checks.find((c) => c.indexExists);
+    if (withIndex)
+        return withIndex.candidate;
+    const firstExisting = checks.find((c) => c.rootExists);
+    if (firstExisting)
+        return firstExisting.candidate;
+    return candidates[0];
+};