docs(README): complete docs for existing errors

gr2m · Oct 5, 2023 · ae42f51 · ae42f51
1 parent 604d68a
commit ae42f51
Show file tree

Hide file tree

Showing 7 changed files with 118 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -1011,20 +1011,20 @@ try {
 }
 ```
 
-#### `GitHubProjectUnknownFieldError`
+#### `GitHubProjectNotFoundError`
 
-Thrown when a configured field configured in the `Project` constructor cannot be found in the project.
+Thrown when a project cannot be found based on the `owner` and `number` passed to the `Project` constructor. The error is also thrown if the project exists but cannot be found based on authentication.
 
 ```js
-import Project, { GitHubProjectUnknownFieldError } from "github-project";
+import Project, { GitHubProjectNotFoundError } from "github-project";
 
 try {
   await myScript(new Project(options));
 } catch (error) {
-  if (error instanceof GitHubProjectUnknownFieldError) {
-    analytics.track("GitHubProjectUnknownFieldError", {
-      projectFieldNames: error.details.projectFieldNames,
-      userFieldName: error.details.userFieldName,
+  if (error instanceof GitHubProjectNotFoundError) {
+    analytics.track("GitHubProjectNotFoundError", {
+      owner: error.details.owner,
+      number: error.details.number,
     });
 
     myLogger.error(
@@ -1040,20 +1040,102 @@ try {
 }
 ```
 
-#### `GitHubProjectNotFoundError`
+<table>
+  <thead align=left>
+    <tr>
+      <th>
+        name
+      </th>
+      <th>
+        type
+      </th>
+      <th width=100%>
+        description
+      </th>
+    </tr>
+  </thead>
+  <tbody align=left valign=top>
+    <tr>
+      <th>
+        <code>name</code>
+      </th>
+      <td>
+        <code>constant</code>
+      </td>
+      <td><code>GitHubProjectNotFoundError</code></td>
+    </tr>
+    <tr>
+      <th>
+        <code>message</code>
+      </th>
+      <td>
+        <code>constant</code>
+      </td>
+      <td>
 
-Thrown when a project cannot be found based on the `owner` and `number` passed to the `Project` constructor. The error is also thrown if the project exists but cannot be found based on authentication.
+> Project cannot be found
+
+</td>
+    <tr>
+      <th>
+        <code>details</code>
+      </th>
+      <td>
+        <code>object</code>
+      </td>
+      <td>
+
+Object with error details
+
+</td>
+    </tr>
+    <tr>
+      <th>
+        <code>details.owner</code>
+      </th>
+      <td>
+        <code>string</code>
+      </td>
+      <td>
+
+Login of owner of the project
+
+</td>
+    </tr>
+    <tr>
+      <th>
+        <code>details.number</code>
+      </th>
+      <td>
+        <code>number</code>
+      </td>
+      <td>
+
+Number of the project
+
+</td>
+    </tr>
+  </tbody>
+</table>
+
+Example for `error.toHumanMessage()`:
+
+> Project #1 could not be found for @gr2m
+
+#### `GitHubProjectUnknownFieldError`
+
+Thrown when a configured field configured in the `Project` constructor cannot be found in the project.
 
 ```js
-import Project, { GitHubProjectNotFoundError } from "github-project";
+import Project, { GitHubProjectUnknownFieldError } from "github-project";
 
 try {
   await myScript(new Project(options));
 } catch (error) {
-  if (error instanceof GitHubProjectNotFoundError) {
-    analytics.track("GitHubProjectNotFoundError", {
-      owner: error.details.owner,
-      number: error.details.number,
+  if (error instanceof GitHubProjectUnknownFieldError) {
+    analytics.track("GitHubProjectUnknownFieldError", {
+      projectFieldNames: error.details.projectFieldNames,
+      userFieldName: error.details.userFieldName,
     });
 
     myLogger.error(
@@ -1091,7 +1173,7 @@ try {
       <td>
         <code>constant</code>
       </td>
-      <td><code>GitHubProjectNotFoundError</code></td>
+      <td><code>GitHubProjectUnknownFieldError</code></td>
     </tr>
     <tr>
       <th>
@@ -1127,7 +1209,7 @@ Object with error details
       </td>
       <td>
 
-Names of the fields in the project.
+Names of all project fields as shown in the project
 
 </td>
     </tr>
@@ -1136,24 +1218,24 @@ Names of the fields in the project.
         <code>details.userFieldName</code>
       </th>
       <td>
-        <code>string</code>
+        <code>object</code>
       </td>
       <td>
 
-The stringified value set in the API call.
+Name of the field provided by the user
 
 </td>
     </tr>
     <tr>
       <th>
-        <code>details.userInternalFieldName</code>
+        <code>details.userFieldNameAlias</code>
       </th>
       <td>
-        <code>string</code>
+        <code>object</code>
       </td>
       <td>
 
-The user-provided alias for the field.
+Alias of the field name provided by the user
 
 </td>
     </tr>
@@ -1162,7 +1244,7 @@ The user-provided alias for the field.
 
 Example for `error.toHumanMessage()`:
 
-> "NOPE" could not be matched with any of the existing field names: "Title", "Assignees", "Status", "Labels", "Linked pull requests", "Reviewers", "Repository", "Milestone", "Text", "Number", "Date", "Single select", "Iteration". If the field should be considered optional, then set it to "nope: { name: "NOPE", optional: true}
+> "NOPE" could not be matched with any of the existing field names: "My text", "My number", "My Date". If the field should be considered optional, then set it to "nope: { name: "NOPE", optional: true}
 
 #### `GitHubProjectUnknownFieldOptionError`
 
@@ -1277,7 +1359,7 @@ Object with field details
       </td>
       <td>
 
-The field name as shown in the project.
+The field name as shown in the project
 
 </td>
     </tr>

diff --git a/api/errors.js b/api/errors.js
@@ -34,7 +34,7 @@ export class GitHubProjectUnknownFieldError extends GitHubProjectError {
     const projectFieldNames = this.details.projectFieldNames
       .map((node) => `"${node.name}"`)
       .join(", ");
-    return `"${this.details.userFieldName}" could not be matched with any of the existing field names: ${projectFieldNames}. If the field should be considered optional, then set it to "${this.details.userInternalFieldName}: { name: "${this.details.userFieldName}", optional: true}`;
+    return `"${this.details.userFieldName}" could not be matched with any of the existing field names: ${projectFieldNames}. If the field should be considered optional, then set it to "${this.details.userFieldNameAlias}: { name: "${this.details.userFieldName}", optional: true}`;
   }
 }
 

diff --git a/api/lib/project-fields-nodes-to-fields-map.js b/api/lib/project-fields-nodes-to-fields-map.js
@@ -67,7 +67,7 @@ export function projectFieldsNodesToFieldsMap(state, project, nodes) {
   );
 
   return Object.entries(project.fields).reduce(
-    (acc, [userInternalFieldName, userFieldNameOrConfig]) => {
+    (acc, [userFieldNameAlias, userFieldNameOrConfig]) => {
       let fieldOptional = false;
       let userFieldName = userFieldNameOrConfig;
       if (typeof userFieldNameOrConfig === "object") {
@@ -87,7 +87,7 @@ export function projectFieldsNodesToFieldsMap(state, project, nodes) {
         if (!fieldOptional) {
           throw new GitHubProjectUnknownFieldError({
             userFieldName,
-            userInternalFieldName,
+            userFieldNameAlias,
             projectFieldNames,
           });
         }
@@ -97,19 +97,19 @@ export function projectFieldsNodesToFieldsMap(state, project, nodes) {
         return acc;
       }
 
-      acc[userInternalFieldName] = {
+      acc[userFieldNameAlias] = {
         id: node.id,
         name: node.name,
         dataType: node.dataType,
         userName: userFieldName,
-        optional: userInternalFieldName in optionalFields,
+        optional: userFieldNameAlias in optionalFields,
         existsInProject: true,
       };
 
       // Settings is a JSON string. It contains view information such as column width.
       // If the field is of type "Single select", then the `options` property will be set.
       if (node.options) {
-        acc[userInternalFieldName].optionsById = node.options.reduce(
+        acc[userFieldNameAlias].optionsById = node.options.reduce(
           (acc, option) => {
             return {
               ...acc,
@@ -118,7 +118,7 @@ export function projectFieldsNodesToFieldsMap(state, project, nodes) {
           },
           {}
         );
-        acc[userInternalFieldName].optionsByValue = node.options.reduce(
+        acc[userFieldNameAlias].optionsByValue = node.options.reduce(
           (acc, option) => {
             return {
               ...acc,

diff --git a/index.d.ts b/index.d.ts
@@ -327,7 +327,7 @@ export declare class GitHubProjectNotFoundError<
 type GitHubProjectUnknownFieldErrorDetails = {
   projectFieldNames: string[];
   userFieldName: string;
-  userInternalFieldName: string;
+  userFieldNameAlias: string;
 };
 
 export declare class GitHubProjectUnknownFieldError<

diff --git a/index.test-d.ts b/index.test-d.ts
@@ -673,7 +673,7 @@ export function testGitHubProjectUnknownFieldError() {
   const details = {
     projectFieldNames: ["one", "two"],
     userFieldName: "Three",
-    userInternalFieldName: "three",
+    userFieldNameAlias: "three",
   };
   const error = new GitHubProjectUnknownFieldError(details);
 

diff --git a/test/snapshots/recorded.test.js.md b/test/snapshots/recorded.test.js.md
@@ -38,7 +38,7 @@ Generated by [AVA](https://avajs.dev).
             'Iteration',
           ],
           userFieldName: 'NOPE',
-          userInternalFieldName: 'nope',
+          userFieldNameAlias: 'nope',
         },
         message: 'Project field cannot be found',
       },
@@ -998,7 +998,7 @@ Generated by [AVA](https://avajs.dev).
           'Iteration',
         ],
         userFieldName: 'Nope',
-        userInternalFieldName: 'nonExistingField',
+        userFieldNameAlias: 'nonExistingField',
       },
       message: 'Project field cannot be found',
     }
@@ -7468,7 +7468,7 @@ Generated by [AVA](https://avajs.dev).
           'Iteration',
         ],
         userFieldName: 'Unknown',
-        userInternalFieldName: 'unknown',
+        userFieldNameAlias: 'unknown',
       },
       message: 'Project field cannot be found',
     }
@@ -7528,7 +7528,7 @@ Generated by [AVA](https://avajs.dev).
           'Iteration',
         ],
         userFieldName: 'NOPE',
-        userInternalFieldName: 'nope',
+        userFieldNameAlias: 'nope',
       },
       message: 'Project field cannot be found',
     }

diff --git a/test/snapshots/recorded.test.js.snap b/test/snapshots/recorded.test.js.snap