@quanxiaoxiao/datav 0.4.0 → 0.5.1

package/src/createDataTransformer.ts

@@ -0,0 +1,173 @@
+import { createDataAccessor } from './createDataAccessor.js';
+import { parseValueByType } from './parseValueByType.js';
+import { isEmpty, isPlainObject } from './utils.js';
+import { type ExpressSchema,validateExpressSchema } from './validateExpressSchema.js';
+
+interface SchemaExpress {
+  type: 'string' | 'number' | 'boolean' | 'integer' | 'object' | 'array';
+  properties?: Record<string, SchemaExpress> | [string, SchemaExpress] | SchemaExpress[];
+  resolve?: (value: unknown, root: unknown) => unknown;
+}
+
+interface FieldHandler {
+  fieldKey: string;
+  schema: SchemaExpress;
+  transform: (data: unknown, root: unknown) => unknown;
+}
+
+type SchemaTransformer = (data: unknown, root?: unknown) => unknown;
+
+type TransformFn = (schema: SchemaExpress | [string, SchemaExpress]) => SchemaTransformer;
+
+const createObjectTransformer = (
+  properties: Record<string, SchemaExpress>,
+  createTransform: TransformFn,
+): ((data: unknown, root: unknown) => object) => {
+  const handlers: FieldHandler[] = Object.entries(properties).map(([fieldKey, schema]) => ({
+    fieldKey,
+    schema,
+    transform: createTransform(schema),
+  }));
+
+  return (data: unknown, root: unknown) => {
+    const rootData = root ?? data;
+
+    return handlers.reduce((result, handler) => {
+      const fieldValue = Array.isArray(handler.schema)
+        ? handler.transform(data, rootData)
+        : handler.transform(data == null ? data : (data as Record<string, unknown>)[handler.fieldKey], rootData);
+
+      return {
+        ...result,
+        [handler.fieldKey]: fieldValue,
+      };
+    }, {} as object);
+  };
+};
+
+/**
+ * 处理路径访问的数据提取
+ */
+const extractDataByPath = (pathname: string, data: unknown, root: unknown): unknown => {
+  if (pathname.startsWith('$')) {
+    return createDataAccessor(pathname.slice(1))(root);
+  }
+  return createDataAccessor(pathname)(data);
+};
+
+/**
+ * 创建基础类型转换器
+ */
+const createPrimitiveTransformer = (schema: SchemaExpress): SchemaTransformer => {
+  return (value: unknown, root?: unknown) => {
+    const rootData = root ?? value;
+    const resolvedValue = schema.resolve ? schema.resolve(value, rootData) : value;
+    return parseValueByType(resolvedValue, schema.type);
+  };
+};
+
+/**
+ * 创建简单对象转换器（无 properties）
+ */
+const createPlainObjectTransformer = (): SchemaTransformer => {
+  return (value: unknown) => {
+    return isPlainObject(value) ? value : {};
+  };
+};
+
+/**
+ * 创建数组转换器（tuple 形式的 properties）
+ */
+const createArrayTransformer = (
+  properties: [string, SchemaExpress],
+  createTransform: TransformFn,
+): SchemaTransformer => {
+  const [pathname, itemSchema] = properties;
+  const itemTransform = createTransform(itemSchema);
+
+  return (data: unknown, root?: unknown) => {
+    const rootData = root ?? data;
+
+    if (!Array.isArray(data)) {
+      if (pathname.startsWith('$')) {
+        const extractedData = createDataAccessor(pathname.slice(1))(rootData);
+        return extractedData == null ? [] : [itemTransform(extractedData, rootData)];
+      }
+      return [];
+    }
+
+    return data.map((item) => {
+      if (pathname === '' || pathname === '.') {
+        return itemTransform(item, rootData);
+      }
+      return itemTransform(createDataAccessor(pathname)(item), rootData);
+    });
+  };
+};
+
+/**
+ * 创建数组对象转换器（对象形式的 properties）
+ */
+const createArrayObjectTransformer = (
+  properties: Record<string, SchemaExpress>,
+  createTransform: TransformFn,
+): SchemaTransformer => {
+  const objectTransform = createObjectTransformer(properties, createTransform);
+
+  return (data: unknown, root?: unknown) => {
+    const rootData = root ?? data;
+
+    if (!Array.isArray(data)) {
+      return isEmpty(properties) ? [] : [objectTransform(data, rootData)];
+    }
+
+    return data.map((item) => objectTransform(item, rootData));
+  };
+};
+
+/**
+ * 创建数据转换器
+ * 根据 schema 表达式递归创建数据转换函数
+ */
+export const createDataTransformer: TransformFn = (schema) => {
+  // 处理路径访问形式: [pathname, schema]
+  if (Array.isArray(schema)) {
+    const [pathname, nestedSchema] = schema;
+
+    if (typeof pathname !== 'string' || !isPlainObject(nestedSchema)) {
+      throw new Error(`Invalid schema expression: ${JSON.stringify(schema)}`);
+    }
+
+    const nestedTransform = createDataTransformer(nestedSchema);
+
+    return (data: unknown, root?: unknown) => {
+      const rootData = root ?? data;
+      const extractedData = extractDataByPath(pathname, data, rootData);
+      return nestedTransform(extractedData, rootData);
+    };
+  }
+
+  validateExpressSchema(schema as ExpressSchema);
+
+  if (['string', 'number', 'boolean', 'integer'].includes(schema.type)) {
+    return createPrimitiveTransformer(schema);
+  }
+
+  if (schema.resolve) {
+    console.warn('Data type `array` or `object` does not support resolve function');
+  }
+
+  if (schema.type === 'object') {
+    if (isEmpty(schema.properties)) {
+      return createPlainObjectTransformer();
+    }
+    return createObjectTransformer(schema.properties as Record<string, SchemaExpress>, createDataTransformer);
+  }
+
+  if (Array.isArray(schema.properties)) {
+    return createArrayTransformer(schema.properties as [string, SchemaExpress], createDataTransformer);
+  }
+
+  // 处理数组对象类型
+  return createArrayObjectTransformer(schema.properties as Record<string, SchemaExpress>, createDataTransformer);
+};

package/src/createPathAccessor.test.ts

@@ -0,0 +1,217 @@
+import * as assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+
+import { createPathAccessor } from './createPathAccessor.js';
+
+describe('createPathAccessor', () => {
+  describe('空路径', () => {
+    test('应该返回原始数据', () => {
+      const accessor = createPathAccessor([]);
+      const data = { name: 'test', value: 123 };
+      assert.deepEqual(accessor(data), data);
+    });
+
+    test('应该返回原始数组', () => {
+      const accessor = createPathAccessor([]);
+      const data = [1, 2, 3];
+      assert.deepEqual(accessor(data), data);
+    });
+
+    test('应该返回原始基本类型', () => {
+      const accessor = createPathAccessor([]);
+      assert.equal(accessor('hello'), 'hello');
+      assert.equal(accessor(42), 42);
+      assert.equal(accessor(null), null);
+    });
+  });
+
+  describe('单层路径 - 对象访问', () => {
+    test('应该正确访问对象属性', () => {
+      const accessor = createPathAccessor(['name']);
+      const data = { name: 'Alice', age: 30 };
+      assert.equal(accessor(data), 'Alice');
+    });
+
+    test('不存在的属性应该返回 null', () => {
+      const accessor = createPathAccessor(['missing']);
+      const data = { name: 'Alice' };
+      assert.equal(accessor(data), null);
+    });
+
+    test('null 或 undefined 数据应该返回 null', () => {
+      const accessor = createPathAccessor(['name']);
+      assert.equal(accessor(null), null);
+      assert.equal(accessor(undefined), null);
+    });
+
+    test('应该访问嵌套对象', () => {
+      const accessor = createPathAccessor(['user']);
+      const data = { user: { name: 'Bob', age: 25 } };
+      assert.deepEqual(accessor(data), { name: 'Bob', age: 25 });
+    });
+  });
+
+  describe('单层路径 - 数组访问', () => {
+    test('应该通过 createArrayAccessor 访问数组', () => {
+      // 假设 createArrayAccessor 支持索引访问
+      const accessor = createPathAccessor(['0']);
+      const data = ['first', 'second', 'third'];
+      // 这里的行为取决于 createArrayAccessor 的实现
+      const result = accessor(data);
+      assert.ok(result !== null);
+    });
+  });
+
+  describe('多层路径 - 嵌套对象', () => {
+    test('应该访问嵌套对象的属性', () => {
+      const accessor = createPathAccessor(['user', 'profile', 'name']);
+      const data = {
+        user: {
+          profile: {
+            name: 'Charlie',
+            email: 'charlie@example.com',
+          },
+        },
+      };
+      assert.equal(accessor(data), 'Charlie');
+    });
+
+    test('中间路径不存在应该返回 null', () => {
+      const accessor = createPathAccessor(['user', 'profile', 'name']);
+      const data = { user: {} };
+      assert.equal(accessor(data), null);
+    });
+
+    test('中间路径为 null 应该返回 null', () => {
+      const accessor = createPathAccessor(['user', 'profile', 'name']);
+      const data = { user: null };
+      assert.equal(accessor(data), null);
+    });
+  });
+
+  describe('混合路径 - 对象和数组', () => {
+    test('应该访问对象中的数组元素', () => {
+      const accessor = createPathAccessor(['users', '0', 'name']);
+      const data = {
+        users: [
+          { name: 'David', age: 28 },
+          { name: 'Eve', age: 32 },
+        ],
+      };
+      // 行为取决于 createArrayAccessor 的实现
+      const result = accessor(data);
+      assert.ok(result !== undefined);
+    });
+
+    test('应该访问数组中的对象属性', () => {
+      const accessor = createPathAccessor(['0', 'name']);
+      const data = [
+        { name: 'Frank', age: 35 },
+        { name: 'Grace', age: 29 },
+      ];
+      const result = accessor(data);
+      assert.ok(result !== undefined);
+    });
+
+    test('复杂嵌套结构', () => {
+      const accessor = createPathAccessor(['company', 'departments', '0', 'manager', 'name']);
+      const data = {
+        company: {
+          departments: [
+            {
+              name: 'Engineering',
+              manager: { name: 'Helen', id: 101 },
+            },
+            {
+              name: 'Sales',
+              manager: { name: 'Ivan', id: 102 },
+            },
+          ],
+        },
+      };
+      const result = accessor(data);
+      assert.ok(result !== undefined);
+    });
+  });
+
+  describe('边界情况', () => {
+    test('路径指向 undefined 值', () => {
+      const accessor = createPathAccessor(['value']);
+      const data = { value: undefined };
+      assert.equal(accessor(data), undefined);
+    });
+
+    test('路径指向 0 值', () => {
+      const accessor = createPathAccessor(['count']);
+      const data = { count: 0 };
+      assert.equal(accessor(data), 0);
+    });
+
+    test('路径指向空字符串', () => {
+      const accessor = createPathAccessor(['text']);
+      const data = { text: '' };
+      assert.equal(accessor(data), '');
+    });
+
+    test('路径指向 false 值', () => {
+      const accessor = createPathAccessor(['flag']);
+      const data = { flag: false };
+      assert.equal(accessor(data), false);
+    });
+
+    test('空对象', () => {
+      const accessor = createPathAccessor(['key']);
+      const data = {};
+      assert.equal(accessor(data), null);
+    });
+
+    test('空数组', () => {
+      const accessor = createPathAccessor(['0']);
+      const data = [];
+      const result = accessor(data);
+      // 行为取决于 createArrayAccessor 的实现
+      assert.ok(result !== undefined);
+    });
+  });
+
+  describe('特殊键名', () => {
+    test('包含特殊字符的键名', () => {
+      const accessor = createPathAccessor(['user-name']);
+      const data = { 'user-name': 'Jack' };
+      assert.equal(accessor(data), 'Jack');
+    });
+
+    test('数字字符串键名', () => {
+      const accessor = createPathAccessor(['123']);
+      const data = { 123: 'numeric key' };
+      assert.equal(accessor(data), 'numeric key');
+    });
+
+    test('包含点号的键名', () => {
+      const accessor = createPathAccessor(['user.name']);
+      const data = { 'user.name': 'Kelly' };
+      assert.equal(accessor(data), 'Kelly');
+    });
+  });
+
+  describe('性能和缓存', () => {
+    test('多次调用相同访问器应该得到一致结果', () => {
+      const accessor = createPathAccessor(['user', 'name']);
+      const data = { user: { name: 'Liam' } };
+
+      assert.equal(accessor(data), 'Liam');
+      assert.equal(accessor(data), 'Liam');
+      assert.equal(accessor(data), 'Liam');
+    });
+
+    test('访问器应该是纯函数', () => {
+      const accessor = createPathAccessor(['value']);
+      const data1 = { value: 'first' };
+      const data2 = { value: 'second' };
+
+      assert.equal(accessor(data1), 'first');
+      assert.equal(accessor(data2), 'second');
+      assert.equal(accessor(data1), 'first');
+    });
+  });
+});

package/src/createPathAccessor.ts

@@ -0,0 +1,45 @@
+import { createArrayAccessor } from './createArrayAccessor.js';
+
+const getObjectValue = (key: string) => (obj: Record<string, unknown> | null): unknown => {
+  if (obj == null || !Object.hasOwnProperty.call(obj, key)) {
+    return null;
+  }
+  return obj[key];
+};
+
+const traversePath = (target: unknown, pathSegments: string[]): unknown => {
+  const [currentKey, ...remainingPath] = pathSegments;
+
+  if (Array.isArray(target)) {
+    const value = createArrayAccessor(currentKey)(target);
+    if (value == null || remainingPath.length === 0) {
+      return value;
+    }
+    return traversePath(value, remainingPath);
+  }
+
+  const value = getObjectValue(currentKey)(target as Record<string, unknown>);
+  if (value == null || remainingPath.length === 0) {
+    return value;
+  }
+
+  return traversePath(value, remainingPath);
+};
+
+export function createPathAccessor(pathSegments: string[]): (data: unknown) => unknown {
+  if (pathSegments.length === 0) {
+    return (data: unknown) => data;
+  }
+
+  if (pathSegments.length === 1) {
+    const key = pathSegments[0];
+    return (data: unknown) => {
+      if (Array.isArray(data)) {
+        return createArrayAccessor(key)(data);
+      }
+      return getObjectValue(key)(data as Record<string, unknown>);
+    };
+  }
+
+  return (data: unknown) => traversePath(data, pathSegments);
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+import { createDataTransformer } from './createDataTransformer.js';
+import { type DataType,parseValueByType } from './parseValueByType.js';
+import { type ExpressSchema,validateExpressSchema } from './validateExpressSchema.js';
+
+export {
+  createDataTransformer,
+  type DataType,
+  type ExpressSchema,
+  parseValueByType,
+  validateExpressSchema,
+};

package/src/parseDotPath.test.ts

@@ -0,0 +1,132 @@
+import assert from 'node:assert';
+import test from 'node:test';
+
+import { parseDotPath } from './parseDotPath.js';
+
+const testCases = (description: string, cases: Array<[string, string[], string?]>): void => {
+  test(description, async (t) => {
+    for (const [input, expected, testDesc] of cases) {
+      await t.test(testDesc || `输入: "${input}"`, () => {
+        assert.deepStrictEqual(parseDotPath(input), expected);
+      });
+    }
+  });
+};
+
+const errorCases = (description: string, cases: Array<[string, string | null, string?]>): void => {
+  test(description, async (t) => {
+    for (const [input, errorMsg, testDesc] of cases) {
+      await t.test(testDesc || `输入: "${input}"`, () => {
+        assert.throws(
+          () => parseDotPath(input),
+          {
+            name: 'Error',
+            message: errorMsg || `Path "${input}" parse failed: contains empty segment`,
+          },
+        );
+      });
+    }
+  });
+};
+
+testCases('基本路径解析', [
+  ['', [], '空字符串应返回空数组'],
+  ['.', [], '单个点应返回空数组'],
+  ['single', ['single'], '单个段'],
+  ['a.b', ['a', 'b'], '两个段'],
+  ['a.b.c', ['a', 'b', 'c'], '三个段'],
+  ['first.second.third.fourth', ['first', 'second', 'third', 'fourth'], '多个段'],
+]);
+
+testCases('前导点处理', [
+  ['.aa', ['aa'], '前导点 + 单段'],
+  ['.a.b.c', ['a', 'b', 'c'], '前导点 + 多段'],
+  ['.aa.bb.cc', ['aa', 'bb', 'cc'], '前导点 + 多段（长名称）'],
+]);
+
+testCases('转义点号处理', [
+  ['a\\.b', ['a.b'], '单个转义点'],
+  ['a\\.b.c', ['a.b', 'c'], '转义点在中间段'],
+  ['a\\.b\\.c', ['a.b.c'], '多个转义点在同一段'],
+  ['a\\.b\\.c.d', ['a.b.c', 'd'], '连续转义点 + 普通分隔'],
+  ['a.b\\.c.d', ['a', 'b.c', 'd'], '混合转义和非转义'],
+  ['\\.aa', ['.aa'], '转义点在开头'],
+  ['.\\.aa', ['.aa'], '前导点 + 转义点'],
+  ['a.b\\.', ['a', 'b.'], '转义点在结尾'],
+  ['a.b.c\\.', ['a', 'b', 'c.'], '转义点在最后段末尾'],
+  ['\\.\\.\\.', ['...'], '多个连续转义点'],
+  ['a\\\\.b.c', ['a\\.b', 'c'], '转义反斜杠 + 点'],
+  ['a\\\\.b\\\\.c', ['a\\.b\\.c'], '多个转义反斜杠'],
+  ['a\\.\\.b', ['a..b'], '转义的连续点号'],
+]);
+
+testCases('特殊字符处理', [
+  ['aa. .bb', ['aa', ' ', 'bb'], '空格段'],
+  ['a-b.c_d.e123', ['a-b', 'c_d', 'e123'], '连字符和下划线'],
+  ['用户.姓名.firstName', ['用户', '姓名', 'firstName'], '中文字符'],
+  ['0.1.2', ['0', '1', '2'], '数字段'],
+  ['_private.public', ['_private', 'public'], '下划线开头'],
+  ['$var.prop', ['$var', 'prop'], '美元符号开头'],
+]);
+
+testCases('长路径处理', [
+  [
+    'a.b.c.d.e.f.g.h.i.j.k.l.m.n.o.p',
+    ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p'],
+    '16段长路径',
+  ],
+  [
+    'a\\.b.c\\.d.e',
+    ['a.b', 'c.d', 'e'],
+    '带转义的混合路径',
+  ],
+]);
+
+errorCases('错误：空段检测', [
+  ['..aa', null, '开头的连续点'],
+  ['a..b', null, '中间的连续点'],
+  ['aa..bb', null, '中间的连续点（长名称）'],
+  ['a...b', null, '多个连续点'],
+  ['bb.', null, '结尾的点'],
+  ['a.b.', null, '多段后结尾的点'],
+  ['a.b.c.', null, '更多段后结尾的点'],
+  ['.a.', null, '前导点 + 结尾点'],
+  ['.a\\.b..c\\.d.e\\..f', null, '复杂的空段错误'],
+]);
+
+test('parseDotPath - 完整兼容性测试', () => {
+  const validCases = [
+    ['', []],
+    ['.', []],
+    ['.aa', ['aa']],
+    ['a.b.c', ['a', 'b', 'c']],
+    ['.aa.bb.cc', ['aa', 'bb', 'cc']],
+    ['aa.bb.cc', ['aa', 'bb', 'cc']],
+    ['aa\\.bb.cc', ['aa.bb', 'cc']],
+    ['.\\.aa', ['.aa']],
+    ['\\.aa', ['.aa']],
+    ['aa. .bb', ['aa', ' ', 'bb']],
+    ['a\\.b\\.c', ['a.b.c']],
+    ['a\\.b.c\\.d.e', ['a.b', 'c.d', 'e']],
+    ['a.b.c\\.', ['a', 'b', 'c.']],
+    ['\\.\\.\\.', ['...']],
+    ['a\\\\.b.c', ['a\\.b', 'c']],
+    ['a\\\\.b\\\\.c', ['a\\.b\\.c']],
+  ];
+
+  validCases.forEach(([input, expected]) => {
+    assert.deepStrictEqual(parseDotPath(input), expected, `Failed for input: "${input}"`);
+  });
+
+  const errorInputs = [
+    '..aa',
+    'aa..bb',
+    'bb.',
+    'a.b.c.',
+    '.a\\.b..c\\.d.e\\..f',
+  ];
+
+  errorInputs.forEach((input) => {
+    assert.throws(() => parseDotPath(input), `Should throw for input: "${input}"`);
+  });
+});

package/src/parseDotPath.ts

@@ -0,0 +1,13 @@
+export function parseDotPath(path: string): string[] {
+  const normalizedPath = path.startsWith('.') ? path.slice(1) : path;
+  if (normalizedPath === '') {
+    return [];
+  }
+  const segments = normalizedPath
+    .split(/(?<!\\)\./)
+    .map((segment) => segment.replace(/\\\./g, '.'));
+  if (segments.some((segment) => segment === '')) {
+    throw new Error(`Path "${path}" parse failed: contains empty segment`);
+  }
+  return segments;
+}