@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...

    函数 isMiniProgramFileStat

    • 判断未知值是否具有文件元数据快照的最低 wire 结构。

      参数

      • value: unknown

        来自 file.stat Host 返回值、bridge response 或其他不可信边界的候选元数据。

      返回 value is MiniProgramFileStat

      kind、size 与可选时间字段满足 MiniProgramFileStat 结构时返回 true,并将 TypeScript 类型收窄为文件元数据;否则返回 false。

      对通常的对象字面量,仅允许 kind、size、modifiedAt、createdAt 四个 canonical key:

      • kind 必须固定为 'file'。
      • size 必须是 0 到 Number.MAX_SAFE_INTEGER 范围内的整数。0 表示空文件;负数、小数、NaN、 Infinity、unsafe integer、bigint 和数字字符串都会被拒绝。文件 API 将该值解释为字节数,但本 guard 只验证数字结构,不能证明 Host 使用了正确单位。
      • modifiedAt 与 createdAt 相互独立且都可省略,也可显式为 undefined;提供时必须是非负有限 number。 与 size 不同,时间值不要求是整数或 safe integer,因此非负小数以及大于 Number.MAX_SAFE_INTEGER 但仍有限的值都可通过。

      文件 API 把时间字段解释为 Unix epoch milliseconds,但该 guard 不验证值是否落在 JavaScript Date 可表示范围内,也不要求 createdAt <= modifiedAt、时间不晚于当前时刻,或两项同时存在。消费者若要排序、 格式化或比较时间,仍须按自己的业务范围继续校验。

      canonical 集合之外的可枚举自有字符串键会导致失败,包括值为 undefined 的额外键;非枚举属性、 symbol 键和继承属性不在 Object.keys() 检查范围内,必需字段本身也不要求是自有或可枚举属性。 该函数不会复制、冻结或规范化输入,返回的仍是原始可变对象。

      返回 true 只建立结构类型收窄,不证明该快照来自可信 Host、对应当前 FileHandle 或当前 request,也不证明 文件仍然存在、size 与磁盘内容一致、时间由文件系统提供、handle 属于当前 session/origin、filesystem 权限已启用或 Host 支持 file.stat。这些关联、权限与 I/O 错误必须由 Runtime 和 FileHandle.stat() 调用链处理。

      import { isMiniProgramFileStat } from '@heybox/hb-sdk/protocol';

      const candidate: unknown = {
      kind: 'file',
      size: 4096,
      modifiedAt: 1_795_027_200_000,
      };

      if (isMiniProgramFileStat(candidate)) {
      console.log(`${candidate.size} bytes`);
      if (candidate.modifiedAt !== undefined) {
      console.log(candidate.modifiedAt);
      }
      }

      isMiniProgramFileStat({ kind: 'file', size: 0 }); // true:时间字段可全部省略
      isMiniProgramFileStat({ kind: 'file', size: 1.5 }); // false:size 必须是 safe integer

      0.8.0