来自 directory.list、Host response 或其他不可信边界的候选文件系统实体 descriptor。
值通过文件或目录任一子 guard 时返回 true,并将 TypeScript 类型收窄为
MiniProgramFileSystemEntityDescriptor 判别联合;否则返回 false。
该函数不维护第三套 schema,而是依次调用 isMiniProgramFileDescriptor 和 isMiniProgramDirectoryDescriptor:
kind === 'file' 的值必须同时具有非空 name、'read' | 'readwrite' mode,以及合法 direct/derived
file ref。derived 文件路径必须指向 root 下的具体文件,不接受 relativePath: '.'。kind === 'directory' 的值必须同时具有非空 name、'read' | 'readwrite' mode,以及合法
direct/derived directory ref。derived 目录 ref 可用 relativePath: '.' 表示 root 自身。两个分支的 kind 互斥,因此通过后可直接用 descriptor.kind 判别收窄到对应类型。各分支完整继承子 guard
的键与嵌套 ref 规则:对通常的对象字面量,顶层只允许 kind、name、mode、ref,nested ref/root
也只允许其 canonical key;额外可枚举自有字符串键会导致失败。非枚举属性、symbol 键和继承属性不在
Object.keys() 检查范围内,必需属性本身也不要求是自有或可枚举属性。
返回 true 只建立单个 descriptor 的结构类型收窄。该函数不会复制、冻结或规范化输入,也不会验证
name 的完整平台规则、handle 是否由当前 Runtime 签发并属于当前 session/origin、目标实体是否存在且类型
与 kind 一致、mode 是否真实、filesystem 权限、provenance 或 Host capability。实际创建 FileHandle /
DirectoryHandle 时仍须由 SDK 与 Runtime 完成这些校验。
对 DirectoryListResult,本 guard 只适合逐项验证,不验证外层值是否为稠密数组、结果数量、重复项、
子项 mode 是否继承父目录,或列表是否来自当前请求。DirectoryHandle.list() 调用链必须另行处理这些集合级
与请求级约束。
import { isMiniProgramFileSystemEntityDescriptor } from '@heybox/hb-sdk/protocol';
const candidates: unknown[] = [
{ kind: 'file', name: 'report.json', mode: 'read', ref: { kind: 'file', handleId: 'file_1' } },
{ kind: 'directory', name: 'exports', mode: 'read', ref: { kind: 'directory', handleId: 'directory_1' } },
];
const descriptors = candidates.filter(isMiniProgramFileSystemEntityDescriptor);
for (const descriptor of descriptors) {
if (descriptor.kind === 'file') {
console.log('file', descriptor.ref);
} else {
console.log('directory', descriptor.ref);
}
}
list() 入口。
判断未知值是否为文件或目录 descriptor。