@udt/parser-utils 0.1.0 → 0.2.0

package/coverage/parseData.ts.html

@@ -25,14 +25,14 @@
             <div class='fl pad1y space-right2'>
                 <span class="strong">100% </span>
                 <span class="quiet">Statements</span>
-                <span class='fraction'>68/68</span>
+                <span class='fraction'>77/77</span>
             </div>
         
             
             <div class='fl pad1y space-right2'>
                 <span class="strong">100% </span>
                 <span class="quiet">Branches</span>
-                <span class='fraction'>15/15</span>
+                <span class='fraction'>18/18</span>
             </div>
         
             
@@ -46,7 +46,7 @@
             <div class='fl pad1y space-right2'>
                 <span class="strong">100% </span>
                 <span class="quiet">Lines</span>
-                <span class='fraction'>68/68</span>
+                <span class='fraction'>77/77</span>
             </div>
         
             
@@ -334,7 +334,17 @@
 <a name='L269'></a><a href='#L269'>269</a>
 <a name='L270'></a><a href='#L270'>270</a>
 <a name='L271'></a><a href='#L271'>271</a>
-<a name='L272'></a><a href='#L272'>272</a></td><td class="line-coverage quiet"><span class="cline-any cline-yes">1x</span>
+<a name='L272'></a><a href='#L272'>272</a>
+<a name='L273'></a><a href='#L273'>273</a>
+<a name='L274'></a><a href='#L274'>274</a>
+<a name='L275'></a><a href='#L275'>275</a>
+<a name='L276'></a><a href='#L276'>276</a>
+<a name='L277'></a><a href='#L277'>277</a>
+<a name='L278'></a><a href='#L278'>278</a>
+<a name='L279'></a><a href='#L279'>279</a>
+<a name='L280'></a><a href='#L280'>280</a>
+<a name='L281'></a><a href='#L281'>281</a></td><td class="line-coverage quiet"><span class="cline-any cline-yes">1x</span>
+<span class="cline-any cline-yes">1x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
@@ -540,6 +550,7 @@
 <span class="cline-any cline-yes">69x</span>
 <span class="cline-any cline-yes">69x</span>
 <span class="cline-any cline-yes">69x</span>
+<span class="cline-any cline-yes">69x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-yes">69x</span>
 <span class="cline-any cline-yes">72x</span>
@@ -554,13 +565,20 @@
 <span class="cline-any cline-yes">34x</span>
 <span class="cline-any cline-yes">34x</span>
 <span class="cline-any cline-yes">34x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">34x</span>
+<span class="cline-any cline-yes">34x</span>
 <span class="cline-any cline-yes">34x</span>
 <span class="cline-any cline-yes">34x</span>
 <span class="cline-any cline-yes">34x</span>
-<span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-yes">34x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
 <span class="cline-any cline-yes">34x</span>
+<span class="cline-any cline-yes">34x</span>
+<span class="cline-any cline-yes">6x</span>
+<span class="cline-any cline-yes">2x</span>
+<span class="cline-any cline-yes">2x</span>
+<span class="cline-any cline-yes">34x</span>
 <span class="cline-any cline-yes">2x</span>
 <span class="cline-any cline-yes">2x</span>
 <span class="cline-any cline-neutral">&nbsp;</span>
@@ -646,12 +664,14 @@ export type ParseDesignTokenDataFn&lt;ParsedDesignToken, T&gt; = (
 &nbsp;
 /**
  * A function that adds a parsed group or design token
- * as a child of a parsed group.
+ * 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 desing token to add
+ * @param child The group or design token to add
  */
 export type AddChildFn&lt;ParsedGroup, ParsedDesignToken&gt; = (
+  parent: ParsedGroup,
   name: string,
   child: ParsedGroup | ParsedDesignToken
 ) =&gt; void;
@@ -659,25 +679,15 @@ export type AddChildFn&lt;ParsedGroup, ParsedDesignToken&gt; = (
 /**
  * The return value of a `ParseGroupDataFn`.
  */
-export interface ParseGroupResult&lt;ParsedGroup, ParsedDesignToken, T&gt; {
+export interface ParseGroupResult&lt;ParsedGroup, T&gt; {
   /**
    * The parsed representation of the group.
    *
-   * May be `undefined` if there is no useful result
-   * to return from `parseData()` - e.g. if just
-   * logging group info or something like that.
+   * May be omitted if there is no useful result to
+   * return and we only need to pass along context
+   * data.
    */
-  group: ParsedGroup;
-&nbsp;
-  /**
-   * Optional function that will add other parsed groups
-   * or design tokens as children of this 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.
-   */
-  addChild?: AddChildFn&lt;ParsedGroup, ParsedDesignToken&gt;;
+  group?: ParsedGroup;
 &nbsp;
   /**
    * Optional context data to be passed into the
@@ -703,15 +713,14 @@ export interface ParseGroupResult&lt;ParsedGroup, ParsedDesignToken, T&gt; {
  *              parsed the group containing this group.
  *
  * @returns The parsed representation of the group and,
- *          optionally, a function to add child groups or
- *          design tokens to it and some context data to
- *          pass down when child data is parsed.
+ *          optionally, some context data to pass down
+ *          when child data is parsed.
  */
-export type ParseGroupDataFn&lt;ParsedGroup, ParsedDesignToken, T&gt; = (
+export type ParseGroupDataFn&lt;ParsedGroup, T&gt; = (
   data: PlainObject,
   path: string[],
   contextFromParent?: T
-) =&gt; ParseGroupResult&lt;ParsedGroup, ParsedDesignToken, T&gt;;
+) =&gt; ParseGroupResult&lt;ParsedGroup, T&gt;;
 &nbsp;
 export interface ParserConfig&lt;ParsedDesignToken, ParsedGroup, T&gt; {
   /**
@@ -739,7 +748,7 @@ export interface ParserConfig&lt;ParsedDesignToken, ParsedGroup, T&gt; {
    * path, and should parse that data into whatever structure
    * is desired.
    */
-  parseGroupData: ParseGroupDataFn&lt;ParsedGroup, ParsedDesignToken, T&gt;;
+  parseGroupData?: ParseGroupDataFn&lt;ParsedGroup, T&gt;;
 &nbsp;
   /**
    * Function which is called for each design token
@@ -750,6 +759,16 @@ export interface ParserConfig&lt;ParsedDesignToken, ParsedGroup, T&gt; {
    * desired.
    */
   parseDesignTokenData: ParseDesignTokenDataFn&lt;ParsedDesignToken, T&gt;;
+&nbsp;
+  /**
+   * 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&lt;ParsedGroup, ParsedDesignToken&gt;;
 }
 &nbsp;
 /**
@@ -799,8 +818,8 @@ function parseDataImpl&lt;ParsedDesignToken, ParsedGroup, T&gt;(
   config: ParserConfig&lt;ParsedDesignToken, ParsedGroup, T&gt;,
   contextFromParent?: T,
   path: string[] = [],
-  addToParent?: AddChildFn&lt;ParsedGroup, ParsedDesignToken&gt;
-): ParsedDesignToken | ParsedGroup {
+  parentGroup?: ParsedGroup
+): ParsedDesignToken | ParsedGroup | undefined {
   if (!isPlainObject(data)) {
     throw new InvalidDataError(path, data);
   }
@@ -810,38 +829,46 @@ function parseDataImpl&lt;ParsedDesignToken, ParsedGroup, T&gt;(
     groupPropsToExtract,
     parseGroupData,
     parseDesignTokenData,
+    addChildToGroup,
   } = config;
 &nbsp;
-  let groupOrToken: ParsedGroup | ParsedDesignToken;
+  let groupOrToken: ParsedGroup | ParsedDesignToken | undefined = undefined;
   if (isDesignTokenData(data)) {
     // looks like a token
     groupOrToken = parseDesignTokenData(data, path, contextFromParent);
-    if (addToParent &amp;&amp; path.length &gt; 0) {
-      addToParent(path[path.length - 1], groupOrToken);
+    if (addChildToGroup &amp;&amp; path.length &gt; 0 &amp;&amp; parentGroup !== undefined) {
+      addChildToGroup(parentGroup, path[path.length - 1], groupOrToken);
     }
   } else {
     // must be a group
-    const { extracted: groupData, remainingProps: childNames } =
-      extractProperties(data, groupPropsToExtract);
-    const { group, addChild, contextForChildren } = parseGroupData(
-      groupData,
-      path,
-      contextFromParent
+    const { extracted: groupData, rest: children } = extractProperties(
+      data,
+      groupPropsToExtract
     );
 &nbsp;
-    groupOrToken = group;
+    let contextForChildren: T | undefined;
+    if (parseGroupData) {
+      const parseResult = parseGroupData(groupData, path, contextFromParent);
+      contextForChildren = parseResult.contextForChildren;
+      groupOrToken = parseResult.group;
+    }
 &nbsp;
-    if (addToParent &amp;&amp; path.length &gt; 0) {
-      addToParent(path[path.length - 1], groupOrToken);
+    if (
+      addChildToGroup &amp;&amp;
+      path.length &gt; 0 &amp;&amp;
+      parentGroup !== undefined &amp;&amp;
+      groupOrToken !== undefined
+    ) {
+      addChildToGroup(parentGroup, path[path.length - 1], groupOrToken);
     }
 &nbsp;
-    for (const childName of childNames) {
+    for (const childName in children) {
       parseDataImpl(
-        data[childName],
+        children[childName],
         config,
         contextForChildren,
         [...path, childName],
-        addChild
+        groupOrToken
       );
     }
   }
@@ -873,7 +900,7 @@ export function parseData&lt;ParsedDesignToken, ParsedGroup, T&gt;(
   data: unknown,
   config: ParserConfig&lt;ParsedDesignToken, ParsedGroup, T&gt;,
   contextFromParent?: T
-): ParsedDesignToken | ParsedGroup {
+): ParsedDesignToken | ParsedGroup | undefined {
   return parseDataImpl(data, config, contextFromParent);
 }
 &nbsp;</pre></td></tr></table></pre>
@@ -883,7 +910,7 @@ export function parseData&lt;ParsedDesignToken, ParsedGroup, T&gt;(
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2024-11-22T01:43:01.579Z
+                at 2024-11-28T23:35:17.447Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/dist/extractProperties.d.ts

@@ -16,15 +16,15 @@ import { type PlainObject } from "./isJsonObject.js";
  *          and their values, and an array of all property
  *          names of the input object that were not extracted.
  */
-export declare function extractProperties(object: PlainObject, propsToExtract: (string | RegExp)[]): {
+export declare function extractProperties(object: PlainObject, propsToExtract: readonly (string | RegExp)[]): {
     /**
      * Object containg the extract properties
      * and their respective values.
      */
     extracted: PlainObject;
     /**
-     * Array of property names of the input
-     * object that were not extracted.
+     * Object containing the remaining, unextracted
+     * properties and their respective values.
      */
-    remainingProps: string[];
+    rest: PlainObject;
 };

package/dist/extractProperties.js

@@ -19,18 +19,18 @@ export function extractProperties(object, propsToExtract) {
     const propNamesToExtract = propsToExtract.filter((prop) => typeof prop === "string");
     const propRegexesToExtract = propsToExtract.filter((prop) => prop instanceof RegExp);
     const extracted = {};
-    const remainingProps = [];
+    const rest = {};
     Object.getOwnPropertyNames(object).forEach((prop) => {
         if (propNamesToExtract.some((propNameToExtract) => propNameToExtract === prop) ||
             propRegexesToExtract.some((propRegexToExtract) => propRegexToExtract.test(prop))) {
             extracted[prop] = object[prop];
         }
         else {
-            remainingProps.push(prop);
+            rest[prop] = object[prop];
         }
     });
     return {
         extracted,
-        remainingProps,
+        rest,
     };
 }

package/dist/index.js

@@ -1,3 +1,5 @@
+/* v8 ignore start */
 export * from "./parseData.js";
 export * from "./isJsonObject.js";
 export * from "./extractProperties.js";
+/* v8 ignore end */

package/dist/parseData.d.ts

@@ -31,33 +31,25 @@ export type IsDesignTokenDataFn = (data: PlainObject) => boolean;
 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 a parsed group.
+ * 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 desing token to add
+ * @param child The group or design token to add
  */
-export type AddChildFn<ParsedGroup, ParsedDesignToken> = (name: string, child: ParsedGroup | ParsedDesignToken) => void;
+export type AddChildFn<ParsedGroup, ParsedDesignToken> = (parent: ParsedGroup, name: string, child: ParsedGroup | ParsedDesignToken) => void;
 /**
  * The return value of a `ParseGroupDataFn`.
  */
-export interface ParseGroupResult<ParsedGroup, ParsedDesignToken, T> {
+export interface ParseGroupResult<ParsedGroup, T> {
     /**
      * The parsed representation of the group.
      *
-     * May be `undefined` if there is no useful result
-     * to return from `parseData()` - e.g. if just
-     * logging group info or something like that.
+     * May be omitted if there is no useful result to
+     * return and we only need to pass along context
+     * data.
      */
-    group: ParsedGroup;
-    /**
-     * Optional function that will add other parsed groups
-     * or design tokens as children of this 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.
-     */
-    addChild?: AddChildFn<ParsedGroup, ParsedDesignToken>;
+    group?: ParsedGroup;
     /**
      * Optional context data to be passed into the
      * `parseGroupData()` and `parseDesignTokenData()` calls
@@ -81,11 +73,10 @@ export interface ParseGroupResult<ParsedGroup, ParsedDesignToken, T> {
  *              parsed the group containing this group.
  *
  * @returns The parsed representation of the group and,
- *          optionally, a function to add child groups or
- *          design tokens to it and some context data to
- *          pass down when child data is parsed.
+ *          optionally, some context data to pass down
+ *          when child data is parsed.
  */
-export type ParseGroupDataFn<ParsedGroup, ParsedDesignToken, T> = (data: PlainObject, path: string[], contextFromParent?: T) => ParseGroupResult<ParsedGroup, ParsedDesignToken, T>;
+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
@@ -110,7 +101,7 @@ export interface ParserConfig<ParsedDesignToken, ParsedGroup, T> {
      * path, and should parse that data into whatever structure
      * is desired.
      */
-    parseGroupData: ParseGroupDataFn<ParsedGroup, ParsedDesignToken, T>;
+    parseGroupData?: ParseGroupDataFn<ParsedGroup, T>;
     /**
      * Function which is called for each design token
      *data object that is encountered.
@@ -120,6 +111,15 @@ export interface ParserConfig<ParsedDesignToken, ParsedGroup, T> {
      * 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
@@ -156,4 +156,4 @@ export declare class InvalidDataError extends Error {
  *              or group parser function call.
  * @returns The outermost parsed group or design token
  */
-export declare function parseData<ParsedDesignToken, ParsedGroup, T>(data: unknown, config: ParserConfig<ParsedDesignToken, ParsedGroup, T>, contextFromParent?: T): ParsedDesignToken | ParsedGroup;
+export declare function parseData<ParsedDesignToken, ParsedGroup, T>(data: unknown, config: ParserConfig<ParsedDesignToken, ParsedGroup, T>, contextFromParent?: T): ParsedDesignToken | ParsedGroup | undefined;

package/dist/parseData.js

@@ -35,29 +35,36 @@ export class InvalidDataError extends Error {
  *              to the parent group.
  * @returns The parsed design token or group.
  */
-function parseDataImpl(data, config, contextFromParent, path = [], addToParent) {
+function parseDataImpl(data, config, contextFromParent, path = [], parentGroup) {
     if (!isPlainObject(data)) {
         throw new InvalidDataError(path, data);
     }
-    const { isDesignTokenData, groupPropsToExtract, parseGroupData, parseDesignTokenData, } = config;
-    let groupOrToken;
+    const { isDesignTokenData, groupPropsToExtract, parseGroupData, parseDesignTokenData, addChildToGroup, } = config;
+    let groupOrToken = undefined;
     if (isDesignTokenData(data)) {
         // looks like a token
         groupOrToken = parseDesignTokenData(data, path, contextFromParent);
-        if (addToParent && path.length > 0) {
-            addToParent(path[path.length - 1], groupOrToken);
+        if (addChildToGroup && path.length > 0 && parentGroup !== undefined) {
+            addChildToGroup(parentGroup, path[path.length - 1], groupOrToken);
         }
     }
     else {
         // must be a group
-        const { extracted: groupData, remainingProps: childNames } = extractProperties(data, groupPropsToExtract);
-        const { group, addChild, contextForChildren } = parseGroupData(groupData, path, contextFromParent);
-        groupOrToken = group;
-        if (addToParent && path.length > 0) {
-            addToParent(path[path.length - 1], groupOrToken);
+        const { extracted: groupData, rest: children } = extractProperties(data, groupPropsToExtract);
+        let contextForChildren;
+        if (parseGroupData) {
+            const parseResult = parseGroupData(groupData, path, contextFromParent);
+            contextForChildren = parseResult.contextForChildren;
+            groupOrToken = parseResult.group;
         }
-        for (const childName of childNames) {
-            parseDataImpl(data[childName], config, contextForChildren, [...path, childName], addChild);
+        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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udt/parser-utils",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Low-level logic and utilities for parsing DTCG and DTCG-like files",
   "main": "dist/index.js",
   "type": "module",

package/src/extractProperties.test.ts

@@ -18,12 +18,12 @@ describe("extractProperties()", () => {
     expect(extractResult.extracted).toStrictEqual({ bar: 13, baz: 666 });
   });
 
-  it("returns keys of non-extracted properties", () => {
+  it("returns non-extracted properties", () => {
     const extractResult = extractProperties(
       { foo: 42, bar: 13, baz: 666, quux: 0 },
       ["foo", "baz"]
     );
-    expect(extractResult.remainingProps).toStrictEqual(["bar", "quux"]);
+    expect(extractResult.rest).toStrictEqual({ bar: 13, quux: 0 });
   });
 
   it("ignores props to extract that are not present in input object", () => {

package/src/extractProperties.ts

@@ -19,7 +19,7 @@ import { type PlainObject } from "./isJsonObject.js";
  */
 export function extractProperties(
   object: PlainObject,
-  propsToExtract: (string | RegExp)[]
+  propsToExtract: readonly (string | RegExp)[]
 ): {
   /**
    * Object containg the extract properties
@@ -28,10 +28,10 @@ export function extractProperties(
   extracted: PlainObject;
 
   /**
-   * Array of property names of the input
-   * object that were not extracted.
+   * Object containing the remaining, unextracted
+   * properties and their respective values.
    */
-  remainingProps: string[];
+  rest: PlainObject;
 } {
   const propNamesToExtract = propsToExtract.filter(
     (prop) => typeof prop === "string"
@@ -41,7 +41,7 @@ export function extractProperties(
   );
 
   const extracted: PlainObject = {};
-  const remainingProps: string[] = [];
+  const rest: PlainObject = {};
   Object.getOwnPropertyNames(object).forEach((prop) => {
     if (
       propNamesToExtract.some(
@@ -53,12 +53,12 @@ export function extractProperties(
     ) {
       extracted[prop] = object[prop];
     } else {
-      remainingProps.push(prop);
+      rest[prop] = object[prop];
     }
   });
 
   return {
     extracted,
-    remainingProps,
+    rest,
   };
 }

package/src/index.ts

@@ -1,3 +1,5 @@
+/* v8 ignore start */
 export * from "./parseData.js";
 export * from "./isJsonObject.js";
 export * from "./extractProperties.js";
+/* v8 ignore end */