isJSONArray

检查给定值是否为有效的 JSON 数组。

const result = isJSONArray(value);

参考

isJSONArray(value)

当您想确认数组的所有元素是否都是有效的 JSON 值时，请使用 isJSONArray。有效的 JSON 数组是指所有项都可以序列化为 JSON 的值（null、对象、数组、字符串、数字、布尔值）组成的数组。

import { isJSONArray } from 'es-toolkit/predicate';

// 有效的 JSON 数组
console.log(isJSONArray([1, 2, 3])); // true
console.log(isJSONArray(['hello', 'world'])); // true
console.log(isJSONArray([true, false, null])); // true
console.log(isJSONArray([{ name: 'John' }, { name: 'Jane' }])); // true
console.log(
  isJSONArray([
    [1, 2],
    [3, 4],
  ])
); // true (嵌套数组)
console.log(isJSONArray([])); // true (空数组)

// 复合有效 JSON 数组
const complexArray = [42, 'text', true, null, { key: 'value' }, [1, 2, 3]];
console.log(isJSONArray(complexArray)); // true

与无效的 JSON 数组区分：

// 包含函数的数组 - 无效
console.log(isJSONArray([1, 2, () => {}])); // false
console.log(isJSONArray([function () {}])); // false

// 包含 undefined 的数组 - 无效
console.log(isJSONArray([1, undefined, 3])); // false

// 包含 Symbol 的数组 - 无效
console.log(isJSONArray([Symbol('test')])); // false

// 包含 Date 对象的数组 - 无效（在 JSON 中必须转换为字符串）
console.log(isJSONArray([new Date()])); // false

// 非数组值
console.log(isJSONArray('not an array')); // false
console.log(isJSONArray({ 0: 'a', 1: 'b', length: 2 })); // false (类数组对象)
console.log(isJSONArray(42)); // false
console.log(isJSONArray(null)); // false

在 API 响应验证或数据序列化前验证时很有用。

// API 响应验证
function processApiArray(data: unknown) {
  if (isJSONArray(data)) {
    // 可以安全使用 JSON.stringify
    const jsonString = JSON.stringify(data);
    console.log('序列化的数组:', jsonString);
    return data;
  }

  throw new Error('不是有效的 JSON 数组');
}

// 用户输入数据验证
function validateUserList(input: unknown): any[] {
  if (isJSONArray(input)) {
    // TypeScript 将 input 推断为 any[]
    return input;
  }

  return [];
}

// 配置数组验证
function loadArrayConfig(config: unknown) {
  if (isJSONArray(config)) {
    return {
      isValid: true,
      items: config,
      count: config.length,
    };
  }

  return {
    isValid: false,
    items: [],
    count: 0,
  };
}

// 在嵌套结构中也能工作
const nestedData = [{ users: [{ name: 'Alice' }, { name: 'Bob' }] }, { users: [{ name: 'Charlie' }] }];
console.log(isJSONArray(nestedData)); // true

对于包含函数作为元素的数组或 TypedArray 对象等无法序列化为 JSON 的数组，返回 false。

// 一般数组 vs JSON 数组
const regularArray = [1, 2, function () {}]; // 一般有效的数组
const jsonArray = [1, 2, 3]; // 可序列化为 JSON 的数组

console.log(Array.isArray(regularArray)); // true (一般数组检查)
console.log(isJSONArray(regularArray)); // false (JSON 数组检查)

console.log(Array.isArray(jsonArray)); // true
console.log(isJSONArray(jsonArray)); // true

// TypedArray 不是 JSON 数组
const typedArray = new Int32Array([1, 2, 3]);
console.log(Array.isArray(typedArray)); // false
console.log(isJSONArray(typedArray)); // false

参数

• value (unknown): 要检查是否为有效 JSON 数组的值。

返回值

(value is any[]): 如果值为有效的 JSON 数组则返回 true，否则返回 false。