xxf_react 0.6.7 → 0.6.8

package/README.md

@@ -18,19 +18,20 @@ This project was created using `bun init` in bun v1.3.2. [Bun](https://bun.com)
 
 ## 模块文档
 
-| 模块 | 说明 |
-|------|------|
-| [event-bus](./src/event-bus/README.md) | 事件总线，支持跨 Tab 通信 |
-| [fetch](./src/fetch/README.md) | 带超时控制的 fetch 封装 |
-| [flow](./src/flow/README.md) | Promise 扩展，全局错误处理 |
-| [foundation](./src/foundation/README.md) | 基础工具，性能监控 |
-| [layout](./src/layout/README.md) | 布局组件，悬浮交互 |
-| [media](./src/media/README.md) | 媒体组件，视频播放 |
-| [models](./src/models/README.md) | 数据模型，API 响应类型 |
-| [refresh](./src/refresh/README.md) | 刷新加载，分页加载更多 |
-| [responsive](./src/responsive/README.md) | 响应式布局，设备检测 |
-| [sse](./src/sse/README.md) | Server-Sent Events 连接管理 |
-| [utils](./src/utils/README.md) | 工具函数，滚动定位、组件刷新 |
+| 模块                                       | 说明                      |
+|------------------------------------------|-------------------------|
+| [event-bus](./src/event-bus/README.md)   | 事件总线，支持跨 Tab 通信         |
+| [fetch](./src/fetch/README.md)           | 带超时控制的 fetch 封装         |
+| [http](./src/http/README.md)             | 超强网络框架设计                |
+| [flow](./src/flow/README.md)             | Promise 扩展，全局错误处理       |
+| [foundation](./src/foundation/README.md) | 基础工具，性能监控               |
+| [layout](./src/layout/README.md)         | 布局组件，悬浮交互               |
+| [media](./src/media/README.md)           | 媒体组件，视频播放               |
+| [models](./src/models/README.md)         | 数据模型，API 响应类型           |
+| [refresh](./src/refresh/README.md)       | 刷新加载，分页加载更多             |
+| [responsive](./src/responsive/README.md) | 响应式布局，设备检测              |
+| [sse](./src/sse/README.md)               | Server-Sent Events 连接管理 |
+| [utils](./src/utils/README.md)           | 工具函数，滚动定位、组件刷新          |
 
 ## 详细文档
 

package/dist/foundation/Copy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 深拷贝
+ *
+ * 业务层只调用 copy()
+ * 不感知具体实现
+ */
+export declare function copy<T>(value: T): T;
+//# sourceMappingURL=Copy.d.ts.map

package/dist/foundation/Copy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Copy.d.ts","sourceRoot":"","sources":["../../src/foundation/Copy.ts"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEnC"}

package/dist/foundation/Copy.js

@@ -0,0 +1,21 @@
+// utils/copy.ts
+import rfdc from 'rfdc';
+/**
+ * 内部深拷贝实现
+ *
+ * proto: false  -> 不拷贝原型链（更安全）
+ * circles: true -> 支持循环引用
+ */
+const deepCloneImpl = rfdc({
+    proto: false,
+    circles: true,
+});
+/**
+ * 深拷贝
+ *
+ * 业务层只调用 copy()
+ * 不感知具体实现
+ */
+export function copy(value) {
+    return deepCloneImpl(value);
+}

package/dist/foundation/index.d.ts

@@ -1,3 +1,5 @@
 export * from './Debug';
 export * from './PerformanceMonitor';
+export * from './LayoutSize';
+export * from './Copy';
 //# sourceMappingURL=index.d.ts.map

package/dist/foundation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/foundation/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/foundation/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,sBAAsB,CAAA;AACpC,cAAc,cAAc,CAAA;AAC5B,cAAc,QAAQ,CAAA"}

package/dist/foundation/index.js

@@ -1,2 +1,4 @@
 export * from './Debug';
 export * from './PerformanceMonitor';
+export * from './LayoutSize';
+export * from './Copy';

package/dist/http/api/ApiBuilder.d.ts

@@ -0,0 +1,115 @@
+/**
+ * API 构建器
+ *
+ * 使用 Builder 模式定义 API，类似 Android Retrofit
+ *
+ * @example
+ * ```ts
+ * const userApi = ApiBuilder.create({
+ *   baseUrl: 'https://api.example.com',
+ * })
+ *   .get<User>('getUser', {
+ *     path: '/users/{id}',
+ *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
+ *   })
+ *   .post<User, CreateUserDTO>('createUser', {
+ *     path: '/users',
+ *   })
+ *   .build()
+ *
+ * // 使用 API
+ * const user = await userApi.getUser({ pathParams: { id: '123' } })
+ *
+ * // 多次响应
+ * for await (const { data, fromCache } of userApi.getUserList()) {
+ *   console.log(data, fromCache)
+ * }
+ * ```
+ */
+import ky, { type Options as KyOptions } from 'ky';
+import { HttpClient } from '../client/HttpClient';
+import { ApiStream } from '../client/ApiStream';
+import type { RequestConfig, ApiOptions, CacheConfig, HttpClientConfig } from '../types';
+/**
+ * API 端点函数类型
+ */
+export type ApiEndpoint<TResponse> = {
+    (options?: ApiOptions): ApiStream<TResponse>;
+    /** 请求配置 */
+    config: RequestConfig;
+};
+/**
+ * API 定义类型
+ */
+export type ApiDefinition = Record<string, ApiEndpoint<unknown>>;
+/**
+ * 端点选项
+ */
+interface EndpointOptions {
+    /** 请求路径，支持 {param} 占位符 */
+    path: string;
+    /** 请求方法 */
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** 超时时间 (ms) */
+    timeout?: number;
+    /** 重试次数 */
+    retry?: number;
+    /** 缓存配置 */
+    cache?: CacheConfig;
+}
+/**
+ * API 构建器
+ */
+export declare class ApiBuilder<T extends ApiDefinition = Record<string, never>> {
+    private client;
+    private endpoints;
+    private constructor();
+    /**
+     * 创建 API 构建器
+     */
+    static create(config: HttpClientConfig): ApiBuilder;
+    /**
+     * 从现有 ky 实例创建
+     */
+    static from(kyInstance: ReturnType<typeof ky.create>, config?: Partial<HttpClientConfig>): ApiBuilder;
+    /**
+     * 定义 GET 请求
+     */
+    get<TResponse>(name: string, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<typeof name, ApiEndpoint<TResponse>>>;
+    /**
+     * 定义 POST 请求
+     */
+    post<TResponse>(name: string, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<typeof name, ApiEndpoint<TResponse>>>;
+    /**
+     * 定义 PUT 请求
+     */
+    put<TResponse>(name: string, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<typeof name, ApiEndpoint<TResponse>>>;
+    /**
+     * 定义 DELETE 请求
+     */
+    delete<TResponse>(name: string, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<typeof name, ApiEndpoint<TResponse>>>;
+    /**
+     * 定义 PATCH 请求
+     */
+    patch<TResponse>(name: string, options: Omit<EndpointOptions, 'method'>): ApiBuilder<T & Record<typeof name, ApiEndpoint<TResponse>>>;
+    /**
+     * 通用端点定义
+     */
+    private endpoint;
+    /**
+     * 扩展 ky 实例（添加 hooks 等）
+     */
+    extend(options: KyOptions): this;
+    /**
+     * 构建 API 服务
+     */
+    build(): T;
+    /**
+     * 获取 HTTP 客户端实例（用于高级操作）
+     */
+    getClient(): HttpClient;
+}
+export {};
+//# sourceMappingURL=ApiBuilder.d.ts.map

package/dist/http/api/ApiBuilder.d.ts.map

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

package/dist/http/api/ApiBuilder.js

@@ -0,0 +1,128 @@
+/**
+ * API 构建器
+ *
+ * 使用 Builder 模式定义 API，类似 Android Retrofit
+ *
+ * @example
+ * ```ts
+ * const userApi = ApiBuilder.create({
+ *   baseUrl: 'https://api.example.com',
+ * })
+ *   .get<User>('getUser', {
+ *     path: '/users/{id}',
+ *     cache: { mode: CacheMode.IfCache, ttl: 60000 },
+ *   })
+ *   .post<User, CreateUserDTO>('createUser', {
+ *     path: '/users',
+ *   })
+ *   .build()
+ *
+ * // 使用 API
+ * const user = await userApi.getUser({ pathParams: { id: '123' } })
+ *
+ * // 多次响应
+ * for await (const { data, fromCache } of userApi.getUserList()) {
+ *   console.log(data, fromCache)
+ * }
+ * ```
+ */
+import { HttpClient } from '../client/HttpClient';
+/**
+ * API 构建器
+ */
+export class ApiBuilder {
+    constructor(config) {
+        this.endpoints = new Map();
+        this.client = new HttpClient(config);
+    }
+    /**
+     * 创建 API 构建器
+     */
+    static create(config) {
+        return new ApiBuilder(config);
+    }
+    /**
+     * 从现有 ky 实例创建
+     */
+    static from(kyInstance, config) {
+        const builder = new ApiBuilder({
+            baseUrl: '',
+            ...config,
+        });
+        builder.client.setKyInstance(kyInstance);
+        return builder;
+    }
+    /**
+     * 定义 GET 请求
+     */
+    get(name, options) {
+        return this.endpoint(name, { ...options, method: 'GET' });
+    }
+    /**
+     * 定义 POST 请求
+     */
+    post(name, options) {
+        return this.endpoint(name, { ...options, method: 'POST' });
+    }
+    /**
+     * 定义 PUT 请求
+     */
+    put(name, options) {
+        return this.endpoint(name, { ...options, method: 'PUT' });
+    }
+    /**
+     * 定义 DELETE 请求
+     */
+    delete(name, options) {
+        return this.endpoint(name, { ...options, method: 'DELETE' });
+    }
+    /**
+     * 定义 PATCH 请求
+     */
+    patch(name, options) {
+        return this.endpoint(name, { ...options, method: 'PATCH' });
+    }
+    /**
+     * 通用端点定义
+     */
+    endpoint(name, options) {
+        var _a;
+        const config = {
+            method: (_a = options.method) !== null && _a !== void 0 ? _a : 'GET',
+            path: options.path,
+            headers: options.headers,
+            timeout: options.timeout,
+            retry: options.retry,
+            cache: options.cache,
+        };
+        this.endpoints.set(name, config);
+        return this;
+    }
+    /**
+     * 扩展 ky 实例（添加 hooks 等）
+     */
+    extend(options) {
+        this.client.extendKy(options);
+        return this;
+    }
+    /**
+     * 构建 API 服务
+     */
+    build() {
+        const api = {};
+        for (const [name, config] of this.endpoints) {
+            const endpoint = ((options) => {
+                return this.client.request(config, options);
+            });
+            endpoint.config = config;
+            api[name] = endpoint;
+        }
+        return api;
+    }
+    /**
+     * 获取 HTTP 客户端实例（用于高级操作）
+     */
+    getClient() {
+        return this.client;
+    }
+}

package/dist/http/api/index.d.ts

@@ -0,0 +1,2 @@
+export { ApiBuilder, type ApiEndpoint, type ApiDefinition } from './ApiBuilder';
+//# sourceMappingURL=index.d.ts.map

package/dist/http/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA"}

package/dist/http/api/index.js

@@ -0,0 +1 @@
+export { ApiBuilder } from './ApiBuilder';

package/dist/http/cache/DiskLruCache.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 基于 IndexedDB 的 LRU 磁盘缓存
+ *
+ * 特点：
+ * - 使用 idb-keyval 简化 IndexedDB 操作
+ * - 维护 LRU 元数据实现淘汰策略
+ * - 支持 TTL 过期
+ * - 批量清理优化性能
+ * - 防污染：返回数据的深拷贝
+ */
+import type { CacheEntry, DiskLruCacheConfig } from '../types';
+export declare class DiskLruCache {
+    private store;
+    private config;
+    private metadata;
+    private metadataDirty;
+    private flushTimer;
+    private evicting;
+    constructor(config: DiskLruCacheConfig);
+    /**
+     * 加载或初始化 LRU 元数据（失败返回空元数据）
+     */
+    private loadMetadata;
+    /**
+     * 保存元数据到磁盘 (批量优化，延迟写入)
+     */
+    private scheduleFlushMetadata;
+    /**
+     * 立即刷新元数据到磁盘（失败静默忽略）
+     */
+    flush(): Promise<void>;
+    /**
+     * 获取缓存（失败返回 null，不影响业务）
+     * @returns 缓存条目的深拷贝
+     */
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * 设置缓存（失败静默忽略，不影响业务）
+     */
+    set<T>(key: string, data: T, ttl?: number): Promise<void>;
+    /**
+     * 删除缓存（失败静默忽略）
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * 检查缓存是否存在（不更新访问时间，失败返回 false）
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * 淘汰最旧的缓存条目（失败静默忽略）
+     */
+    private evict;
+    /**
+     * 清空所有缓存（失败静默忽略）
+     */
+    clear(): Promise<void>;
+    /**
+     * 获取缓存数量（失败返回 0）
+     */
+    size(): Promise<number>;
+    /**
+     * 获取所有缓存 key（失败返回空数组）
+     */
+    keys(): Promise<string[]>;
+}
+//# sourceMappingURL=DiskLruCache.d.ts.map

package/dist/http/cache/DiskLruCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiskLruCache.d.ts","sourceRoot":"","sources":["../../../src/http/cache/DiskLruCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAe,MAAM,UAAU,CAAA;AAK3E,qBAAa,YAAY;IACrB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,MAAM,EAAE,kBAAkB;IAQtC;;OAEG;YACW,YAAY;IAiB1B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAe5B;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmCxD;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,GAAE,MAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BlE;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAexC;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASxC;;OAEG;YACW,KAAK;IAsCnB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAS7B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAQlC"}

package/dist/http/cache/DiskLruCache.js

@@ -0,0 +1,254 @@
+/**
+ * 基于 IndexedDB 的 LRU 磁盘缓存
+ *
+ * 特点：
+ * - 使用 idb-keyval 简化 IndexedDB 操作
+ * - 维护 LRU 元数据实现淘汰策略
+ * - 支持 TTL 过期
+ * - 批量清理优化性能
+ * - 防污染：返回数据的深拷贝
+ */
+import { get, set, del, clear as clearStore, createStore } from 'idb-keyval';
+const META_KEY = '__lru_metadata__';
+export class DiskLruCache {
+    constructor(config) {
+        this.metadata = null;
+        this.metadataDirty = false;
+        this.flushTimer = null;
+        this.evicting = false; // 防止并发淘汰
+        this.config = {
+            cleanupThreshold: 0.1,
+            ...config,
+        };
+        this.store = createStore(config.dbName, config.storeName);
+    }
+    /**
+     * 加载或初始化 LRU 元数据（失败返回空元数据）
+     */
+    async loadMetadata() {
+        if (this.metadata)
+            return this.metadata;
+        try {
+            const stored = await get(META_KEY, this.store);
+            if (stored) {
+                this.metadata = stored;
+            }
+            else {
+                this.metadata = { entries: {}, count: 0 };
+            }
+        }
+        catch {
+            // 加载失败，使用空元数据
+            this.metadata = { entries: {}, count: 0 };
+        }
+        return this.metadata;
+    }
+    /**
+     * 保存元数据到磁盘 (批量优化，延迟写入)
+     */
+    scheduleFlushMetadata() {
+        if (this.flushTimer)
+            return;
+        this.metadataDirty = true;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            if (this.metadataDirty && this.metadata) {
+                set(META_KEY, this.metadata, this.store)
+                    .then(() => {
+                    this.metadataDirty = false;
+                })
+                    .catch(() => {
+                    // 静默处理写入错误，下次会重试
+                });
+            }
+        }, 1000); // 1 秒后批量写入
+    }
+    /**
+     * 立即刷新元数据到磁盘（失败静默忽略）
+     */
+    async flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.metadataDirty && this.metadata) {
+            try {
+                await set(META_KEY, this.metadata, this.store);
+                this.metadataDirty = false;
+            }
+            catch {
+                // 刷新失败静默忽略，下次会重试
+            }
+        }
+    }
+    /**
+     * 获取缓存（失败返回 null，不影响业务）
+     * @returns 缓存条目的深拷贝
+     */
+    async get(key) {
+        try {
+            const meta = await this.loadMetadata();
+            // 检查是否存在
+            if (!meta.entries[key]) {
+                return null;
+            }
+            const entry = await get(key, this.store);
+            if (!entry) {
+                // 数据丢失，清理元数据
+                delete meta.entries[key];
+                meta.count = Math.max(0, meta.count - 1);
+                this.scheduleFlushMetadata();
+                return null;
+            }
+            // 检查是否过期
+            if (entry.ttl > 0 && Date.now() - entry.timestamp > entry.ttl) {
+                await this.delete(key);
+                return null;
+            }
+            // 更新访问时间
+            meta.entries[key] = { accessTime: Date.now() };
+            this.scheduleFlushMetadata();
+            return entry;
+        }
+        catch {
+            // IndexedDB 操作失败，返回 null 不影响业务
+            return null;
+        }
+    }
+    /**
+     * 设置缓存（失败静默忽略，不影响业务）
+     */
+    async set(key, data, ttl = 0) {
+        try {
+            const meta = await this.loadMetadata();
+            const entry = {
+                data,
+                timestamp: Date.now(),
+                ttl,
+                key,
+            };
+            // 检查是否需要淘汰
+            if (!meta.entries[key] && meta.count >= this.config.maxSize) {
+                await this.evict();
+            }
+            await set(key, entry, this.store);
+            // 更新元数据
+            if (!meta.entries[key]) {
+                meta.count++;
+            }
+            meta.entries[key] = { accessTime: Date.now() };
+            this.scheduleFlushMetadata();
+        }
+        catch {
+            // IndexedDB 操作失败，静默忽略不影响业务
+        }
+    }
+    /**
+     * 删除缓存（失败静默忽略）
+     */
+    async delete(key) {
+        try {
+            const meta = await this.loadMetadata();
+            if (meta.entries[key]) {
+                await del(key, this.store);
+                delete meta.entries[key];
+                meta.count = Math.max(0, meta.count - 1);
+                this.scheduleFlushMetadata();
+            }
+        }
+        catch {
+            // 删除失败静默忽略
+        }
+    }
+    /**
+     * 检查缓存是否存在（不更新访问时间，失败返回 false）
+     */
+    async has(key) {
+        try {
+            const meta = await this.loadMetadata();
+            return !!meta.entries[key];
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 淘汰最旧的缓存条目（失败静默忽略）
+     */
+    async evict() {
+        // 防止并发淘汰
+        if (this.evicting)
+            return;
+        this.evicting = true;
+        try {
+            const meta = await this.loadMetadata();
+            // 计算需要淘汰的数量
+            const evictCount = Math.ceil(this.config.maxSize * this.config.cleanupThreshold);
+            // 按访问时间排序
+            const sorted = Object.entries(meta.entries).sort((a, b) => a[1].accessTime - b[1].accessTime);
+            // 淘汰最旧的
+            const toEvict = sorted.slice(0, evictCount);
+            for (const [key] of toEvict) {
+                try {
+                    await del(key, this.store);
+                }
+                catch {
+                    // 单个删除失败继续处理其他
+                }
+                delete meta.entries[key];
+                meta.count = Math.max(0, meta.count - 1);
+            }
+            this.scheduleFlushMetadata();
+        }
+        catch {
+            // 淘汰失败静默忽略
+        }
+        finally {
+            this.evicting = false;
+        }
+    }
+    /**
+     * 清空所有缓存（失败静默忽略）
+     */
+    async clear() {
+        // 取消待处理的元数据写入
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        try {
+            // 使用 idb-keyval 的 clear 方法一次性清空整个 store
+            await clearStore(this.store);
+        }
+        catch {
+            // 清空失败静默忽略
+        }
+        // 重置内存中的元数据
+        this.metadata = { entries: {}, count: 0 };
+        this.metadataDirty = false;
+    }
+    /**
+     * 获取缓存数量（失败返回 0）
+     */
+    async size() {
+        try {
+            const meta = await this.loadMetadata();
+            return meta.count;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * 获取所有缓存 key（失败返回空数组）
+     */
+    async keys() {
+        try {
+            const meta = await this.loadMetadata();
+            return Object.keys(meta.entries);
+        }
+        catch {
+            return [];
+        }
+    }
+}