@udt/parser-utils 0.1.0 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ const fileData = { /* ... */ };
 // relevant properties of each group and design token
 // object it encounters to the functions you provide in
 // the config:
-const parsedData = parseData(fileData, {
+const parsedGroup = parseData(fileData, {
   /* Parser config */
 
   // A function that checks whether an object is
@@ -39,7 +39,18 @@ const parsedData = parseData(fileData, {
   // format properties
   groupPropsToExtract: [ /* ... */ ];
 
-  // Function which is called for each group data object
+  // 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;
+  },
+
+  // OPTIONAL function which is called for each group data object
   // that is encountered.
   //
   // Is given the extracted properties of that group and its
@@ -50,24 +61,17 @@ const parsedData = parseData(fileData, {
     return {
       group: parsedGroup,
 
-      // optional:
-      addChild: (childName, childGroupOrToken) => { /*... */ },
-
-      // optional:
+      // OPTIONAL:
       contextForChildren: /* anything you like */,
     }
   },
 
-  // Function which is called for each design token
-  // data object that is encountered.
+  // OPTIONAL function which is called for each design token and/or
+  // nested group found within a group.
   //
-  // 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;
-  },
+  // Useful if your parsed groups and design tokens need to be assembled into
+  // a tree structure.
+  addChildToGroup: (parsedParentGroup, childName, parsedChildGroupOrToken) => { /*... */ },
 });
 ```
 

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
@@ -136,6 +136,17 @@ export declare class InvalidDataError extends Error {
     data: unknown;
     constructor(path: string[], data: unknown);
 }
+/**
+ * Thrown when the outermost object in the data passed to `parseData()`
+ * is not a group.
+ */
+export declare class InvalidStructureError extends Error {
+    /**
+     * The offending value.
+     */
+    data: unknown;
+    constructor(data: unknown);
+}
 /**
  * Parses a nested object structure representing groups
  * and design tokens, such as the data obtained by reading
@@ -156,4 +167,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): ParsedGroup | undefined;

package/dist/parseData.js

@@ -20,6 +20,21 @@ export class InvalidDataError extends Error {
         this.data = data;
     }
 }
+/**
+ * Thrown when the outermost object in the data passed to `parseData()`
+ * is not a group.
+ */
+export class InvalidStructureError extends Error {
+    /**
+     * The offending value.
+     */
+    data;
+    constructor(data) {
+        super(`Expected a group at the root level, but encountered a design token instead`);
+        this.name = "InvalidDataError";
+        this.data = data;
+    }
+}
 /**
  * The internal data parsing implementation.
  *
@@ -35,29 +50,39 @@ 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
+        if (path.length === 0) {
+            throw new InvalidStructureError(data);
+        }
         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;
+        }
+        if (addChildToGroup &&
+            path.length > 0 &&
+            parentGroup !== undefined &&
+            groupOrToken !== undefined) {
+            addChildToGroup(parentGroup, path[path.length - 1], groupOrToken);
         }
-        for (const childName of childNames) {
-            parseDataImpl(data[childName], config, contextForChildren, [...path, childName], addChild);
+        for (const childName in children) {
+            parseDataImpl(children[childName], config, contextForChildren, [...path, childName], groupOrToken);
         }
     }
     return groupOrToken;
@@ -83,5 +108,7 @@ function parseDataImpl(data, config, contextFromParent, path = [], addToParent)
  * @returns The outermost parsed group or design token
  */
 export function parseData(data, config, contextFromParent) {
+    // parseDataImpl() called with an empty path will never return
+    // a ParsedDesignToken
     return parseDataImpl(data, config, contextFromParent);
 }

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "@udt/parser-utils",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Low-level logic and utilities for parsing DTCG and DTCG-like files",
-  "main": "dist/index.js",
   "type": "module",
-  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/"
+  ],
   "scripts": {
     "clean": "del-cli dist/*",
     "build": "tsc -p tsconfig.build.json",
@@ -25,5 +33,8 @@
   "bugs": {
     "url": "https://github.com/universal-design-tokens/udt/issues"
   },
+  "engines": {
+    "node": ">= 18"
+  },
   "homepage": "https://github.com/universal-design-tokens/udt/tree/master/packages/parser-utils#readme"
 }

package/CHANGELOG.md

@@ -1,13 +0,0 @@
-# @udt/parser-utils
-
-## 0.1.0
-
-### Minor Changes
-
-- aa0e5ce: Initial release of `@udt/parser-utils` package.
-
-### Patch Changes
-
-- aa0e5ce: Added `extractProperties()` function for extracting specified properties and their values from an obejct.
-- aa0e5ce: Added `parseData()` function for parsing design token data
-- aa0e5ce: Added `isPlainObject()` function for checking if a value is a plain object.

package/coverage/base.css

@@ -1,224 +0,0 @@
-body, html {
-  margin:0; padding: 0;
-  height: 100%;
-}
-body {
-    font-family: Helvetica Neue, Helvetica, Arial;
-    font-size: 14px;
-    color:#333;
-}
-.small { font-size: 12px; }
-*, *:after, *:before {
-  -webkit-box-sizing:border-box;
-     -moz-box-sizing:border-box;
-          box-sizing:border-box;
-  }
-h1 { font-size: 20px; margin: 0;}
-h2 { font-size: 14px; }
-pre {
-    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
-    margin: 0;
-    padding: 0;
-    -moz-tab-size: 2;
-    -o-tab-size:  2;
-    tab-size: 2;
-}
-a { color:#0074D9; text-decoration:none; }
-a:hover { text-decoration:underline; }
-.strong { font-weight: bold; }
-.space-top1 { padding: 10px 0 0 0; }
-.pad2y { padding: 20px 0; }
-.pad1y { padding: 10px 0; }
-.pad2x { padding: 0 20px; }
-.pad2 { padding: 20px; }
-.pad1 { padding: 10px; }
-.space-left2 { padding-left:55px; }
-.space-right2 { padding-right:20px; }
-.center { text-align:center; }
-.clearfix { display:block; }
-.clearfix:after {
-  content:'';
-  display:block;
-  height:0;
-  clear:both;
-  visibility:hidden;
-  }
-.fl { float: left; }
-@media only screen and (max-width:640px) {
-  .col3 { width:100%; max-width:100%; }
-  .hide-mobile { display:none!important; }
-}
-
-.quiet {
-  color: #7f7f7f;
-  color: rgba(0,0,0,0.5);
-}
-.quiet a { opacity: 0.7; }
-
-.fraction {
-  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
-  font-size: 10px;
-  color: #555;
-  background: #E8E8E8;
-  padding: 4px 5px;
-  border-radius: 3px;
-  vertical-align: middle;
-}
-
-div.path a:link, div.path a:visited { color: #333; }
-table.coverage {
-  border-collapse: collapse;
-  margin: 10px 0 0 0;
-  padding: 0;
-}
-
-table.coverage td {
-  margin: 0;
-  padding: 0;
-  vertical-align: top;
-}
-table.coverage td.line-count {
-    text-align: right;
-    padding: 0 5px 0 20px;
-}
-table.coverage td.line-coverage {
-    text-align: right;
-    padding-right: 10px;
-    min-width:20px;
-}
-
-table.coverage td span.cline-any {
-    display: inline-block;
-    padding: 0 5px;
-    width: 100%;
-}
-.missing-if-branch {
-    display: inline-block;
-    margin-right: 5px;
-    border-radius: 3px;
-    position: relative;
-    padding: 0 4px;
-    background: #333;
-    color: yellow;
-}
-
-.skip-if-branch {
-    display: none;
-    margin-right: 10px;
-    position: relative;
-    padding: 0 4px;
-    background: #ccc;
-    color: white;
-}
-.missing-if-branch .typ, .skip-if-branch .typ {
-    color: inherit !important;
-}
-.coverage-summary {
-  border-collapse: collapse;
-  width: 100%;
-}
-.coverage-summary tr { border-bottom: 1px solid #bbb; }
-.keyline-all { border: 1px solid #ddd; }
-.coverage-summary td, .coverage-summary th { padding: 10px; }
-.coverage-summary tbody { border: 1px solid #bbb; }
-.coverage-summary td { border-right: 1px solid #bbb; }
-.coverage-summary td:last-child { border-right: none; }
-.coverage-summary th {
-  text-align: left;
-  font-weight: normal;
-  white-space: nowrap;
-}
-.coverage-summary th.file { border-right: none !important; }
-.coverage-summary th.pct { }
-.coverage-summary th.pic,
-.coverage-summary th.abs,
-.coverage-summary td.pct,
-.coverage-summary td.abs { text-align: right; }
-.coverage-summary td.file { white-space: nowrap;  }
-.coverage-summary td.pic { min-width: 120px !important;  }
-.coverage-summary tfoot td { }
-
-.coverage-summary .sorter {
-    height: 10px;
-    width: 7px;
-    display: inline-block;
-    margin-left: 0.5em;
-    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
-}
-.coverage-summary .sorted .sorter {
-    background-position: 0 -20px;
-}
-.coverage-summary .sorted-desc .sorter {
-    background-position: 0 -10px;
-}
-.status-line {  height: 10px; }
-/* yellow */
-.cbranch-no { background: yellow !important; color: #111; }
-/* dark red */
-.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
-.low .chart { border:1px solid #C21F39 }
-.highlighted,
-.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
-  background: #C21F39 !important;
-}
-/* medium red */
-.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
-/* light red */
-.low, .cline-no { background:#FCE1E5 }
-/* light green */
-.high, .cline-yes { background:rgb(230,245,208) }
-/* medium green */
-.cstat-yes { background:rgb(161,215,106) }
-/* dark green */
-.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
-.high .chart { border:1px solid rgb(77,146,33) }
-/* dark yellow (gold) */
-.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
-.medium .chart { border:1px solid #f9cd0b; }
-/* light yellow */
-.medium { background: #fff4c2; }
-
-.cstat-skip { background: #ddd; color: #111; }
-.fstat-skip { background: #ddd; color: #111 !important; }
-.cbranch-skip { background: #ddd !important; color: #111; }
-
-span.cline-neutral { background: #eaeaea; }
-
-.coverage-summary td.empty {
-    opacity: .5;
-    padding-top: 4px;
-    padding-bottom: 4px;
-    line-height: 1;
-    color: #888;
-}
-
-.cover-fill, .cover-empty {
-  display:inline-block;
-  height: 12px;
-}
-.chart {
-  line-height: 0;
-}
-.cover-empty {
-    background: white;
-}
-.cover-full {
-    border-right: none !important;
-}
-pre.prettyprint {
-    border: none !important;
-    padding: 0 !important;
-    margin: 0 !important;
-}
-.com { color: #999 !important; }
-.ignore-none { color: #999; font-weight: normal; }
-
-.wrapper {
-  min-height: 100%;
-  height: auto !important;
-  height: 100%;
-  margin: 0 auto -48px;
-}
-.footer, .push {
-  height: 48px;
-}

package/coverage/block-navigation.js

@@ -1,87 +0,0 @@
-/* eslint-disable */
-var jumpToCode = (function init() {
-    // Classes of code we would like to highlight in the file view
-    var missingCoverageClasses = ['.cbranch-no', '.cstat-no', '.fstat-no'];
-
-    // Elements to highlight in the file listing view
-    var fileListingElements = ['td.pct.low'];
-
-    // We don't want to select elements that are direct descendants of another match
-    var notSelector = ':not(' + missingCoverageClasses.join('):not(') + ') > '; // becomes `:not(a):not(b) > `
-
-    // Selecter that finds elements on the page to which we can jump
-    var selector =
-        fileListingElements.join(', ') +
-        ', ' +
-        notSelector +
-        missingCoverageClasses.join(', ' + notSelector); // becomes `:not(a):not(b) > a, :not(a):not(b) > b`
-
-    // The NodeList of matching elements
-    var missingCoverageElements = document.querySelectorAll(selector);
-
-    var currentIndex;
-
-    function toggleClass(index) {
-        missingCoverageElements
-            .item(currentIndex)
-            .classList.remove('highlighted');
-        missingCoverageElements.item(index).classList.add('highlighted');
-    }
-
-    function makeCurrent(index) {
-        toggleClass(index);
-        currentIndex = index;
-        missingCoverageElements.item(index).scrollIntoView({
-            behavior: 'smooth',
-            block: 'center',
-            inline: 'center'
-        });
-    }
-
-    function goToPrevious() {
-        var nextIndex = 0;
-        if (typeof currentIndex !== 'number' || currentIndex === 0) {
-            nextIndex = missingCoverageElements.length - 1;
-        } else if (missingCoverageElements.length > 1) {
-            nextIndex = currentIndex - 1;
-        }
-
-        makeCurrent(nextIndex);
-    }
-
-    function goToNext() {
-        var nextIndex = 0;
-
-        if (
-            typeof currentIndex === 'number' &&
-            currentIndex < missingCoverageElements.length - 1
-        ) {
-            nextIndex = currentIndex + 1;
-        }
-
-        makeCurrent(nextIndex);
-    }
-
-    return function jump(event) {
-        if (
-            document.getElementById('fileSearch') === document.activeElement &&
-            document.activeElement != null
-        ) {
-            // if we're currently focused on the search input, we don't want to navigate
-            return;
-        }
-
-        switch (event.which) {
-            case 78: // n
-            case 74: // j
-                goToNext();
-                break;
-            case 66: // b
-            case 75: // k
-            case 80: // p
-                goToPrevious();
-                break;
-        }
-    };
-})();
-window.addEventListener('keydown', jumpToCode);