来自 bridge payload、Host 返回值或其他不可信边界的候选字节数据。
值是当前 realm 的 Uint8Array(或其子类),且 buffer 是 ArrayBuffer 时返回 true,
并将 TypeScript 类型收窄为 Uint8Array;否则返回 false。
Uint8Array 的每个索引元素由 JavaScript 保证为 0 到 255 的整数。本 guard 接受空视图、非零
byteOffset 以及只覆盖底层 buffer 一部分的视图;它不要求视图覆盖整个 ArrayBuffer,也不限制
byteLength、文件大小或 Companion stdio 消息大小。
普通数组无论是否稀疏、ArrayBuffer 本身、DataView、Int8Array、Uint8ClampedArray 及其他 typed array
都会被拒绝。使用 SharedArrayBuffer 作为 backing buffer 的 Uint8Array 也会被拒绝。由于判断依赖
instanceof,由另一个 JavaScript realm 创建且未经过 structured clone 重建的 Uint8Array 可能无法通过;
当前 realm 的 Uint8Array 子类则可能通过。
该函数不会枚举键,因此挂在 Uint8Array 实例上的额外自有属性不会导致失败;它也不会检查 buffer
是否已 detached、数据来源是否可信、内容是否符合业务格式,或调用方是否拥有文件/Companion 权限。
返回 true 后仍得到原来的可变视图,而不是副本或冻结值。跨异步边界持有或交给其他消费者前,建议使用
new Uint8Array(value) 创建只包含当前视图字节的快照。
文件 readBytes() 用它识别 Host 返回的
FileReadBytesResult,writeBytes() 的
FileWriteBytesPayload content 也采用同一字节表示;
路径、句柄类型和访问模式由文件引用与 descriptor guards 单独校验。Companion stdio 的 stdin、stdout 和 stderr
同样传输 Uint8Array,但 Session ownership、controller generation、stream、sequence、framing、容量与权限
都不属于本 guard 的职责。
import { isMiniProgramByteArray } from '@heybox/hb-sdk/protocol';
const candidate: unknown = new Uint8Array([0, 128, 255]);
if (!isMiniProgramByteArray(candidate)) {
throw new TypeError('需要 ArrayBuffer-backed Uint8Array');
}
// guard 只做结构收窄;复制后再跨异步边界使用。
const snapshot = new Uint8Array(candidate);
isMiniProgramByteArray([0, 128, 255]); // false:普通数组不是 wire 字节视图
isMiniProgramByteArray(new DataView(new ArrayBuffer(3))); // false
readBytes() 与 writeBytes() 的业务入口。
判断未知值是否为使用普通
ArrayBuffer存储的Uint8Array字节视图。