Added API documentation for parser-utils

packages/demos/src/simple-dtcg-parser.ts

@@ -1,4 +1,4 @@
-import { type JsonObject, parseData } from "@udt/parser-utils";
+import { type PlainObject, parseData } from "@udt/parser-utils";
 import { readJsonFile, dtcgDevExampleFile } from "./utils/file.js";
 import { getArgs } from "./utils/cli-args.js";
 
@@ -13,7 +13,7 @@ export interface InheritableProperties {
 
 // Test impl.
 
-function isDtcgDesignToken(data: JsonObject): boolean {
+function isDtcgDesignToken(data: PlainObject): boolean {
   return data.$value !== undefined;
 }
 
@@ -23,9 +23,9 @@ export function parseDtcg(data: unknown) {
   };
 
   function parseDtcgDesignToken(
-    data: JsonObject,
+    data: PlainObject,
     path: string[],
-    contextFromParent?: JsonObject
+    contextFromParent?: PlainObject
   ) {
     console.log(
       `Got token ${path.join(".")}, with data: `,
@@ -36,9 +36,9 @@ export function parseDtcg(data: unknown) {
   }
 
   function parseDtcgGroup(
-    data: JsonObject,
+    data: PlainObject,
     path: string[],
-    contextFromParent?: JsonObject
+    contextFromParent?: PlainObject
   ) {
     if (path.length === 0) {
       console.log(

packages/dtcg-parser/src/extract-common-props.ts

@@ -1,5 +1,5 @@
 import { isValidType, type TOMNodeCommonConstructorProps } from "@udt/tom";
-import { isJsonObject } from "@udt/parser-utils";
+import { isPlainObject } from "@udt/parser-utils";
 
 export interface ExtractedCommonProps {
   commonProps: TOMNodeCommonConstructorProps;
@@ -13,7 +13,7 @@ export function extractCommonProps(dtcgData: any): ExtractedCommonProps {
     commonProps: {
       description: typeof $description === "string" ? $description : undefined,
       type: isValidType($type) ? $type : undefined,
-      extensions: isJsonObject($extensions) ? $extensions : undefined,
+      extensions: isPlainObject($extensions) ? $extensions : undefined,
     },
     rest,
   };

packages/dtcg-parser/src/parse-dtcg-file-data.ts

@@ -1,4 +1,4 @@
-import { type JsonObject, parseData } from "@udt/parser-utils";
+import { type PlainObject, parseData } from "@udt/parser-utils";
 import { RootGroup } from "@udt/tom";
 import { parseGroup } from "./parse-group.js";
 import { parseToken } from "./parse-token.js";
@@ -9,7 +9,7 @@ import { parseToken } from "./parse-token.js";
  * @param data
  * @returns
  */
-function isDesignTokenData(data: JsonObject): boolean {
+function isDesignTokenData(data: PlainObject): boolean {
   return data.$value !== undefined;
 }
 

packages/dtcg-parser/src/parse-group.ts

@@ -1,9 +1,9 @@
 import { type DesignToken, Group, RootGroup } from "@udt/tom";
-import { type JsonObject, type ParseGroupResult } from "@udt/parser-utils";
+import { type PlainObject, type ParseGroupResult } from "@udt/parser-utils";
 import { extractCommonProps } from "./extract-common-props.js";
 
 export function parseGroup(
-  groupProps: JsonObject,
+  groupProps: PlainObject,
   path: string[]
 ): ParseGroupResult<Group | RootGroup, DesignToken, never> {
   const { commonProps, rest } = extractCommonProps(groupProps);

packages/dtcg-parser/src/parse-token.ts

@@ -7,10 +7,10 @@ import {
 import { extractCommonProps } from "./extract-common-props.js";
 import { parseValue } from "./values/parse-value.js";
 import { isReferenceValue, makeReference } from "./values/reference.js";
-import { type JsonObject } from "@udt/parser-utils";
+import { type PlainObject } from "@udt/parser-utils";
 
 export function parseToken(
-  tokenProps: JsonObject,
+  tokenProps: PlainObject,
   path: string[]
 ): DesignToken {
   const name = path[path.length - 1];

packages/parser-utils/README.md

@@ -1,3 +1,78 @@
 # Design Token Parser Utilities
 
-Low-level logic and utilities for parsing DTCG and DTCG-like files. Used by `@udt/dtcg-parser` to parse DTCG to TOM, but also suitable for building libraries or tools that parse DTCG(-like) token files to other representations, or need to traverse tokens and/or groups.
+Low-level logic and utilities to help build parsers for DTCG and DTCG-like files. Will be used by [`@udt/dtcg-parser`](../dtcg-parser/) to parse DTCG to a Token Object Model (TOM), but also suitable for building libraries or tools that parse DTCG(-like) files to other representations, or need to traverse tokens and/or groups.
+
+## Usage
+
+```js
+import { parseData } from "@udt/parser-utils";
+
+// Given a nested object structure representing groups
+// and design tokens (e.g. the result of reading a DTCG file
+// and running it through JSON.parse())...
+const fileData = { /* ... */ };
+
+// ...parseData() will traverse through it and pass the
+// relevant properties of each group and design token
+// object it encounters to the functions you provide in
+// the config:
+const parsedData = parseData(fileData, {
+  /* Parser config */
+
+  // 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.
+  isDesignTokenData: (data) => {
+    /* ... */
+    return /* true for tokens, false otherwise */;
+  },
+
+  // 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: [ /* ... */ ];
+
+  // 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: (data, path, contextFromParent) => {
+    /* ... */
+    return {
+      group: parsedGroup,
+
+      // optional:
+      addChild: (childName, childGroupOrToken) => { /*... */ },
+
+      // optional:
+      contextForChildren: /* anything you like */,
+    }
+  },
+
+  // 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: (data, path, contextFromParent) => {
+    /* ... */
+    return parsedDesignToken;
+  },
+});
+```
+
+Note, this package contains TypeScript typings, which are annotated with doc blocks. Please refer to those for more
+detail about the parameters and return values of the config
+functions. Many popular IDEs (e.g. VSCode) will surface that
+info via auto-completions and tooltips as you code, even if
+you're writing plain JavaScript.

packages/parser-utils/src/extractProperties.ts

@@ -1,10 +1,36 @@
-import { type JsonObject } from "./isJsonObject.js";
+import { type PlainObject } from "./isJsonObject.js";
 
+/**
+ * Extracts specfied properties and their values from
+ * an object.
+ *
+ * A bit like destructuring, except that you can also use
+ * regular expressions to match the properties you want to
+ * extract.
+ *
+ * @param object  The plain object from which to extract
+ *                properties.
+ * @param propsToExtract An array of names, and/or
+ *                regular expressions that match the
+ *                names of the properties to exract.
+ * @returns The object containing the extracted properties
+ *          and their values, and an array of all property
+ *          names of the input object that were not extracted.
+ */
 export function extractProperties(
-  object: JsonObject,
+  object: PlainObject,
   propsToExtract: (string | RegExp)[]
 ): {
-  extracted: JsonObject;
+  /**
+   * Object containg the extract properties
+   * and their respective values.
+   */
+  extracted: PlainObject;
+
+  /**
+   * Array of property names of the input
+   * object that were not extracted.
+   */
   remainingProps: string[];
 } {
   const propNamesToExtract = propsToExtract.filter(
@@ -14,7 +40,7 @@ export function extractProperties(
     (prop) => prop instanceof RegExp
   );
 
-  const extracted: JsonObject = {};
+  const extracted: PlainObject = {};
   const remainingProps: string[] = [];
   Object.getOwnPropertyNames(object).forEach((prop) => {
     if (

packages/parser-utils/src/isJsonObject.test.ts

@@ -1,32 +1,32 @@
 import { describe, it, expect } from "vitest";
-import { isJsonObject } from "./isJsonObject.js";
+import { isPlainObject } from "./isJsonObject.js";
 
-describe("isJsonObject()", () => {
+describe("isPlainObject()", () => {
   it("Returns true for a genuine object", () => {
-    expect(isJsonObject({ foo: "bar" })).toBe(true);
+    expect(isPlainObject({ foo: "bar" })).toBe(true);
   });
 
   it("Returns false for null", () => {
-    expect(isJsonObject(null)).toBe(false);
+    expect(isPlainObject(null)).toBe(false);
   });
 
   it("Returns false for an array", () => {
-    expect(isJsonObject([1, 2, 3])).toBe(false);
+    expect(isPlainObject([1, 2, 3])).toBe(false);
   });
 
   it("Returns false for undefined", () => {
-    expect(isJsonObject(undefined)).toBe(false);
+    expect(isPlainObject(undefined)).toBe(false);
   });
 
   it("Returns false for a function", () => {
-    expect(isJsonObject(function () {})).toBe(false);
+    expect(isPlainObject(function () {})).toBe(false);
   });
 
   it("Returns false for a boolean", () => {
-    expect(isJsonObject(true)).toBe(false);
+    expect(isPlainObject(true)).toBe(false);
   });
 
   it("Returns false for a number", () => {
-    expect(isJsonObject(42)).toBe(false);
+    expect(isPlainObject(42)).toBe(false);
   });
 });

packages/parser-utils/src/isJsonObject.ts

@@ -1,5 +1,19 @@
-export type JsonObject = Record<string, unknown>;
+/**
+ * A plain object.
+ *
+ * I.e. `{ ... }`, and not an array or `null`, which
+ * JavaScript's `typeof` operator would also return
+ * `"object"` for.
+ */
+export type PlainObject = Record<string, unknown>;
 
-export function isJsonObject(data: unknown): data is JsonObject {
-  return typeof data === "object" && data !== null && !Array.isArray(data);
+/**
+ * Checks whether a value is a plain object.
+ *
+ * @param value The value to check.
+ *
+ * @returns `true` if it is a plain object, `false` otherwise.
+ */
+export function isPlainObject(value: unknown): value is PlainObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }