@udt/parser-utils 0.2.0 → 0.3.1

package/src/parseData.test.ts

@@ -1,435 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import {
-  parseData,
-  type ParseDesignTokenDataFn,
-  type ParseGroupDataFn,
-  type IsDesignTokenDataFn,
-  type ParserConfig,
-  InvalidDataError,
-  AddChildFn,
-} from "./parseData.js";
-
-interface TestGroup {
-  type: "group";
-}
-
-interface TestDesignToken {
-  type: "token";
-}
-
-interface TestParentContext {
-  dummyData?: number;
-}
-
-interface ParseDataCall {
-  type: "group" | "token";
-  path: string[];
-}
-
-interface AddChildCall {
-  type: "addChild";
-  name: string;
-}
-
-// Used to track the order in which parseXyzData and addChild
-// functions are called
-let parseDataCalls: (ParseDataCall | AddChildCall)[] = [];
-
-/*
- * For the purpose of these tests, any object with a
- * value property will be considered a design token.
- *
- * Intentionally not using (current) DTCG syntax, to
- * demonstrate that parseData() could be used to parse
- * other formats too, as long as they use the same
- * nested object structure for groups and tokens.
- */
-const mockIsDesignTokenData = vi.fn<IsDesignTokenDataFn>(
-  (data) => data.value !== undefined
-);
-
-const mockParseGroupData = vi.fn<
-  ParseGroupDataFn<TestGroup, TestParentContext>
->((_data, path, contextFromParent) => {
-  parseDataCalls.push({
-    type: "group",
-    path,
-  });
-  return {
-    group: {
-      type: "group",
-    },
-    // pass through contextFromParent
-    contextForChildren: contextFromParent,
-  };
-});
-
-const mockAddChildToGroup = vi.fn<AddChildFn<TestGroup, TestDesignToken>>(
-  (_parent, name, _child) => {
-    parseDataCalls.push({
-      type: "addChild",
-      name,
-    });
-  }
-);
-
-const mockParseDesignTokenData = vi.fn<
-  ParseDesignTokenDataFn<TestDesignToken, TestParentContext>
->((_data, path, _contextFromParent) => {
-  parseDataCalls.push({ type: "token", path });
-  const result: TestDesignToken = {
-    type: "token",
-  };
-  return result;
-});
-
-const defaultParserConfig: ParserConfig<
-  TestDesignToken,
-  TestGroup,
-  TestParentContext
-> = {
-  isDesignTokenData: mockIsDesignTokenData,
-  groupPropsToExtract: [],
-  parseGroupData: mockParseGroupData,
-  parseDesignTokenData: mockParseDesignTokenData,
-};
-
-describe("parseData()", () => {
-  let parserConfig: ParserConfig<TestDesignToken, TestGroup, TestParentContext>;
-
-  beforeEach(() => {
-    // Reset stuff
-    parserConfig = defaultParserConfig;
-    parseDataCalls = [];
-    parserConfig.groupPropsToExtract = [];
-    mockIsDesignTokenData.mockClear();
-    mockParseGroupData.mockClear();
-    mockParseDesignTokenData.mockClear();
-  });
-
-  describe("parsing an empty group object", () => {
-    let parsedGroupOrToken: TestGroup | TestDesignToken | undefined;
-
-    beforeEach(() => {
-      parsedGroupOrToken = parseData({}, parserConfig);
-    });
-
-    it("returns a group", () => {
-      expect(parsedGroupOrToken?.type).toBe("group");
-    });
-
-    it("calls isDesignTokenData function once", () => {
-      expect(mockIsDesignTokenData).toHaveBeenCalledOnce();
-    });
-
-    it("class isDesignTokenData function with input data", () => {
-      expect(mockIsDesignTokenData).toHaveBeenCalledWith({});
-    });
-
-    it("calls parseGroupData function once", () => {
-      expect(mockParseGroupData).toHaveBeenCalledOnce();
-    });
-
-    it("calls parseGroupData function with empty group and empty path array", () => {
-      expect(mockParseGroupData).toHaveBeenCalledWith({}, [], undefined);
-    });
-
-    it("does not call parseDesignTokenData function", () => {
-      expect(mockParseDesignTokenData).not.toHaveBeenCalled();
-    });
-  });
-
-  describe("parsing a design token object", () => {
-    const testTokenData = {
-      value: "whatever", // <-- this makes it a token
-      other: "thing",
-      stuff: 123,
-      notAGroup: {},
-    };
-    let parsedGroupOrToken: TestGroup | TestDesignToken | undefined;
-
-    beforeEach(() => {
-      parsedGroupOrToken = parseData(testTokenData, parserConfig);
-    });
-
-    it("returns a design token", () => {
-      expect(parsedGroupOrToken?.type).toBe("token");
-    });
-
-    it("does not call parseGroupData function", () => {
-      expect(mockParseGroupData).not.toHaveBeenCalled();
-    });
-
-    it("calls parseDesignTokenData function once", () => {
-      expect(mockParseDesignTokenData).toHaveBeenCalledOnce();
-    });
-
-    it("calls parseDesignTokenData function with complete data and empty path array", () => {
-      expect(mockParseDesignTokenData).toHaveBeenCalledWith(
-        testTokenData,
-        [],
-        undefined
-      );
-    });
-  });
-
-  describe("parsing a group object containing design tokens and nested groups", () => {
-    /*
-      Contains:
-
-      - 4 groups: <root>, emptyGroup,
-        groupWithTokens, nestedGroup
-
-      - 5 tokens: nestedToken, anotherNestedToken,
-        deeplyNestedToken, token, anotherToken
-    */
-    const testData = {
-      specialGroupProp: {
-        value: "not a token value",
-        description: "This is not a group or token!",
-      },
-      emptyGroup: {},
-      groupWithTokens: {
-        nestedToken: {
-          value: "a",
-        },
-        anotherNestedToken: {
-          value: "b",
-        },
-        nestedGroup: {
-          deeplyNestedToken: {
-            value: "x",
-          },
-        },
-      },
-      token: {
-        value: 1,
-      },
-      anotherToken: {
-        value: 2,
-      },
-    };
-
-    beforeEach(() => {
-      parserConfig.groupPropsToExtract = ["specialGroupProp"];
-      parseData(testData, parserConfig);
-    });
-
-    it("calls parseDesignTokenData function 5 times", () => {
-      expect(mockParseDesignTokenData).toHaveBeenCalledTimes(5);
-    });
-
-    it("calls parseGroupData function 4 times", () => {
-      expect(mockParseGroupData).toHaveBeenCalledTimes(4);
-    });
-
-    it("only passed extracted group props to the parseGroupData function", () => {
-      expect(mockParseGroupData).toHaveBeenNthCalledWith(
-        1,
-        { specialGroupProp: testData.specialGroupProp },
-        [],
-        undefined
-      );
-    });
-
-    it("traverses the data depth-first", () => {
-      // Start with root group
-      expect(parseDataCalls[0]).toStrictEqual({
-        type: "group",
-        path: [],
-      });
-
-      // "emptyGroup" next
-      expect(parseDataCalls[1]).toStrictEqual({
-        type: "group",
-        path: ["emptyGroup"],
-      });
-
-      // "groupWithTokens" next
-      expect(parseDataCalls[2]).toStrictEqual({
-        type: "group",
-        path: ["groupWithTokens"],
-      });
-
-      // "nestedToken" next
-      expect(parseDataCalls[3]).toStrictEqual({
-        type: "token",
-        path: ["groupWithTokens", "nestedToken"],
-      });
-
-      // "anotherNestedToken" next
-      expect(parseDataCalls[4]).toStrictEqual({
-        type: "token",
-        path: ["groupWithTokens", "anotherNestedToken"],
-      });
-
-      // "nestedGroup" next
-      expect(parseDataCalls[5]).toStrictEqual({
-        type: "group",
-        path: ["groupWithTokens", "nestedGroup"],
-      });
-
-      // "deeplyNestedToken" next
-      expect(parseDataCalls[6]).toStrictEqual({
-        type: "token",
-        path: ["groupWithTokens", "nestedGroup", "deeplyNestedToken"],
-      });
-
-      // "token" next
-      expect(parseDataCalls[7]).toStrictEqual({
-        type: "token",
-        path: ["token"],
-      });
-
-      // "anotherToken" next
-      expect(parseDataCalls[8]).toStrictEqual({
-        type: "token",
-        path: ["anotherToken"],
-      });
-    });
-  });
-
-  describe("with context data", () => {
-    const testData = { group: {}, token: { value: 123 } };
-    const testContext: TestParentContext = { dummyData: 42 };
-
-    beforeEach(() => {
-      parseData(testData, parserConfig, testContext);
-    });
-
-    it("passes the context data to outermost parseGroupData call", () => {
-      // 1st call is the root group
-      expect(mockParseGroupData).toHaveBeenNthCalledWith(
-        1,
-        {},
-        [],
-        testContext
-      );
-    });
-
-    it("passes context from parent group to parseGroupData calls for child groups", () => {
-      expect(mockParseGroupData).toHaveBeenNthCalledWith(
-        2,
-        {},
-        ["group"],
-        testContext
-      );
-    });
-
-    it("passes context from parent group to parseDesignTokenData calls for child tokens", () => {
-      expect(mockParseDesignTokenData).toHaveBeenCalledWith(
-        testData.token,
-        ["token"],
-        testContext
-      );
-    });
-  });
-
-  describe("using addChildToGroup function", () => {
-    const testData = {
-      tokenA: { value: 1 },
-      tokenB: { value: 2 },
-      groupC: { tokenX: { value: 99 }, tokenY: { value: 100 } },
-    };
-
-    beforeEach(() => {
-      mockAddChildToGroup.mockClear();
-      parserConfig.addChildToGroup = mockAddChildToGroup;
-      parseData(testData, parserConfig);
-    });
-
-    it("calls addChildToGroup for every child of every group", () => {
-      // Root group contains 3 children: "tokenA", "tokenB" and "groupC"
-      // "groupC" contains 2 children: "tokenX" and "tokenY"
-      // 3 + 2 = 5
-      expect(mockAddChildToGroup).toHaveBeenCalledTimes(5);
-    });
-
-    it("adds a nested group to its parent before parsing its children", () => {
-      // Steps should be:
-      //  0 parse root group
-      expect(parseDataCalls[0]).toStrictEqual({ type: "group", path: [] });
-
-      //  1 parse token "tokenA"
-      expect(parseDataCalls[1]).toStrictEqual({
-        type: "token",
-        path: ["tokenA"],
-      });
-
-      //  2 addChild "tokenA" to root group
-      expect(parseDataCalls[2]).toStrictEqual({
-        type: "addChild",
-        name: "tokenA",
-      });
-
-      //  3 parse token "tokenB"
-      expect(parseDataCalls[3]).toStrictEqual({
-        type: "token",
-        path: ["tokenB"],
-      });
-
-      //  4 addChild "tokenB" to root group
-      expect(parseDataCalls[4]).toStrictEqual({
-        type: "addChild",
-        name: "tokenB",
-      });
-
-      //  5 parse group "groupC"
-      expect(parseDataCalls[5]).toStrictEqual({
-        type: "group",
-        path: ["groupC"],
-      });
-
-      //  6 addChild "groupC" to root group
-      // NOTE that this happens *before* any of groupC's
-      // children are parsed.
-      expect(parseDataCalls[6]).toStrictEqual({
-        type: "addChild",
-        name: "groupC",
-      });
-
-      //  7 parse token "tokenX"
-      expect(parseDataCalls[7]).toStrictEqual({
-        type: "token",
-        path: ["groupC", "tokenX"],
-      });
-
-      //  8 addChild "tokenX" to "groupC"
-      expect(parseDataCalls[8]).toStrictEqual({
-        type: "addChild",
-        name: "tokenX",
-      });
-
-      //  9 parse token "tokenY"
-      expect(parseDataCalls[9]).toStrictEqual({
-        type: "token",
-        path: ["groupC", "tokenY"],
-      });
-
-      // 10 addChild "tokenY" to "groupC"
-      expect(parseDataCalls[10]).toStrictEqual({
-        type: "addChild",
-        name: "tokenY",
-      });
-    });
-  });
-
-  it("throws an InvalidDataError when given a non-object input", () => {
-    expect(() => parseData(123, parserConfig)).toThrowError(InvalidDataError);
-  });
-
-  it("throws an InvalidDataError when encountering a non-object child", () => {
-    expect(() => parseData({ brokenThing: 123 }, parserConfig)).toThrowError(
-      InvalidDataError
-    );
-  });
-
-  it("includes the path and data when throwing an InvalidDataError", () => {
-    try {
-      parseData({ brokenThing: 123 }, parserConfig);
-    } catch (error) {
-      expect((error as InvalidDataError).path).toStrictEqual(["brokenThing"]);
-      expect((error as InvalidDataError).data).toBe(123);
-    }
-  });
-});

package/src/parseData.ts

@@ -1,280 +0,0 @@
-import { isPlainObject, type PlainObject } from "./isJsonObject.js";
-import { extractProperties } from "./extractProperties.js";
-
-/**
- * A function that checks whether an object is a design token
- * or not (if not, it is assumed to be a group).
- *
- * E.g. for DTCG data, this could check for the presence of a
- * `$value` property.
- *
- * @param data A plain object (guaranteed not to `null` or an
- *             array)
- *
- * @returns `true` if `data` is design token data, `false` if
- *          it is group data.
- */
-export type IsDesignTokenDataFn = (data: PlainObject) => boolean;
-
-/**
- * A function that parses design token data.
- *
- * @param data  A plain object containing design token data
- *              (guaranteed not to be `null` or an array)
- * @param path  The path to the design token data.
- * @param contextFromParent Context data (if any) that was
- *              returned by the `parseGroupData()` call that
- *              parsed the group containing this design token.
- *
- * @returns The parsed representation of the design token.
- *          May be `undefined` if there is no useful result
- *          to return from `parseData()` - e.g. if just
- *          logging design token info or something like that.
- */
-export type ParseDesignTokenDataFn<ParsedDesignToken, T> = (
-  data: PlainObject,
-  path: string[],
-  contextFromParent?: T
-) => ParsedDesignToken;
-
-/**
- * A function that adds a parsed group or design token
- * as a child of the given parsed group.
- *
- * @param parent The parent group to add a child to
- * @param name  The name of the child group or design token
- * @param child The group or design token to add
- */
-export type AddChildFn<ParsedGroup, ParsedDesignToken> = (
-  parent: ParsedGroup,
-  name: string,
-  child: ParsedGroup | ParsedDesignToken
-) => void;
-
-/**
- * The return value of a `ParseGroupDataFn`.
- */
-export interface ParseGroupResult<ParsedGroup, T> {
-  /**
-   * The parsed representation of the group.
-   *
-   * May be omitted if there is no useful result to
-   * return and we only need to pass along context
-   * data.
-   */
-  group?: ParsedGroup;
-
-  /**
-   * Optional context data to be passed into the
-   * `parseGroupData()` and `parseDesignTokenData()` calls
-   * for any nested group or design token data.
-   *
-   * Useful if those functions need access to some data from
-   * higher up in the original data structure. For example, if
-   * parsing DTCG data, this could be used to pass inherited
-   * properties like `$type` down.
-   */
-  contextForChildren?: T;
-}
-
-/**
- * A function that parses group data.
- *
- * @param data  A plain object containing group data
- *              (guaranteed not to be `null` or an array)
- * @param path  The path to the group data.
- * @param contextFromParent Context data (if any) that was
- *              returned by the `parseGroupData()` call that
- *              parsed the group containing this group.
- *
- * @returns The parsed representation of the group and,
- *          optionally, some context data to pass down
- *          when child data is parsed.
- */
-export type ParseGroupDataFn<ParsedGroup, T> = (
-  data: PlainObject,
-  path: string[],
-  contextFromParent?: T
-) => ParseGroupResult<ParsedGroup, T>;
-
-export interface ParserConfig<ParsedDesignToken, ParsedGroup, T> {
-  /**
-   * A function that determines whether an object in the input
-   * data is a design token or a group.
-   */
-  isDesignTokenData: IsDesignTokenDataFn;
-
-  /**
-   * Array of strings and/or RegExp which match
-   * properties of group objects that are NOT
-   * names of child design tokens or groups.
-   *
-   * E.g. for DTCG data, this could be a RegEx
-   * like /^$/ which would match all $-prefixed
-   * format properties
-   */
-  groupPropsToExtract: (string | RegExp)[];
-
-  /**
-   * Function which is called for each group data object
-   * that is encountered.
-   *
-   * Is given the extracted properties of that group and its
-   * path, and should parse that data into whatever structure
-   * is desired.
-   */
-  parseGroupData?: ParseGroupDataFn<ParsedGroup, T>;
-
-  /**
-   * Function which is called for each design token
-   *data object that is encountered.
-   *
-   * Is given the design token data and its path, and
-   * should parse that data into whatever structure is
-   * desired.
-   */
-  parseDesignTokenData: ParseDesignTokenDataFn<ParsedDesignToken, T>;
-
-  /**
-   * Optional function that will add parsed groups
-   * or design tokens as children of another parsed group.
-   *
-   * Intended for cases where the parsed representation
-   * of a group needs to contain its children. If not
-   * needed, this property can be omitted.
-   */
-  addChildToGroup?: AddChildFn<ParsedGroup, ParsedDesignToken>;
-}
-
-/**
- * Thrown when `parseData()` encounters group or design token
- * data that is not a plain object.
- */
-export class InvalidDataError extends Error {
-  /**
-   * Path to the value that is not a plain object
-   */
-  public path: string[];
-
-  /**
-   * The offending value.
-   */
-  public data: unknown;
-
-  constructor(path: string[], data: unknown) {
-    super(
-      `Expected object at path "${path.join(
-        "."
-      )}", but got ${typeof data} instead`
-    );
-    this.name = "InvalidDataError";
-    this.path = path;
-    this.data = data;
-  }
-}
-
-/**
- * The internal data parsing implementation.
- *
- * Recursively calls itself for nested group and
- * design token data.
- *
- * @param data  The input data to traverse and parse
- * @param config Parser config
- * @param contextFromParent Context data passed in from
- *              parent calls to this function.
- * @param path The path to the input data
- * @param addToParent A function to add the parsed data
- *              to the parent group.
- * @returns The parsed design token or group.
- */
-function parseDataImpl<ParsedDesignToken, ParsedGroup, T>(
-  data: unknown,
-  config: ParserConfig<ParsedDesignToken, ParsedGroup, T>,
-  contextFromParent?: T,
-  path: string[] = [],
-  parentGroup?: ParsedGroup
-): ParsedDesignToken | ParsedGroup | undefined {
-  if (!isPlainObject(data)) {
-    throw new InvalidDataError(path, data);
-  }
-
-  const {
-    isDesignTokenData,
-    groupPropsToExtract,
-    parseGroupData,
-    parseDesignTokenData,
-    addChildToGroup,
-  } = config;
-
-  let groupOrToken: ParsedGroup | ParsedDesignToken | undefined = undefined;
-  if (isDesignTokenData(data)) {
-    // looks like a token
-    groupOrToken = parseDesignTokenData(data, path, contextFromParent);
-    if (addChildToGroup && path.length > 0 && parentGroup !== undefined) {
-      addChildToGroup(parentGroup, path[path.length - 1], groupOrToken);
-    }
-  } else {
-    // must be a group
-    const { extracted: groupData, rest: children } = extractProperties(
-      data,
-      groupPropsToExtract
-    );
-
-    let contextForChildren: T | undefined;
-    if (parseGroupData) {
-      const parseResult = parseGroupData(groupData, path, contextFromParent);
-      contextForChildren = parseResult.contextForChildren;
-      groupOrToken = parseResult.group;
-    }
-
-    if (
-      addChildToGroup &&
-      path.length > 0 &&
-      parentGroup !== undefined &&
-      groupOrToken !== undefined
-    ) {
-      addChildToGroup(parentGroup, path[path.length - 1], groupOrToken);
-    }
-
-    for (const childName in children) {
-      parseDataImpl(
-        children[childName],
-        config,
-        contextForChildren,
-        [...path, childName],
-        groupOrToken
-      );
-    }
-  }
-
-  return groupOrToken;
-}
-
-/**
- * Parses a nested object structure representing groups
- * and design tokens, such as the data obtained by reading
- * and JSON-parsing a DTCG file.
- *
- * It will recursively traverse the input data (depth first)
- * and, using the functions provided in the config:
- *
- * 1. Check if the object is design token or group data
- * 2. Pass that data to the parsed or processed by the
- *    relevant function
- * 3. Return the outermost parsed group or design token
- *
- * @param data  The input data to traverse and parse
- * @param config  Configuration for this parser
- * @param contextFromParent Optional context data to
- *              pass into the top-most design token
- *              or group parser function call.
- * @returns The outermost parsed group or design token
- */
-export function parseData<ParsedDesignToken, ParsedGroup, T>(
-  data: unknown,
-  config: ParserConfig<ParsedDesignToken, ParsedGroup, T>,
-  contextFromParent?: T
-): ParsedDesignToken | ParsedGroup | undefined {
-  return parseDataImpl(data, config, contextFromParent);
-}