feat: GitHubProject.getInstance(), project.getProperties()

README.md

@@ -46,7 +46,7 @@ A project always belongs to a user or organization account and has a number. For
 `fields` is map of internal field names to the project's column labels. The comparison is case-insensitive. `"Priority"` will match both a field with the label `"Priority"` and one with the label `"priority"`. An error will be thrown if a project field isn't found, unless the field is set to `optional: true`.
 
 ```js
-const project = new GitHubProject({
+const options = {
   owner: "my-org",
   number: 1,
   token: "ghp_s3cR3t",
@@ -55,7 +55,16 @@ const project = new GitHubProject({
     dueAt: "Due",
     lastUpdate: { name: "Last Update", optional: true },
   },
-});
+};
+
+const project = new GitHubProject(options);
+
+// Alternatively, you can call the factory method to get a project instance
+// const project = await GithubProject.getInstance(options)
+
+// get project data
+const projectData = await project.get();
+console.log(projectData.description);
 
 // log out all items
 const items = await project.items.list();
@@ -98,6 +107,14 @@ if (item) {
 const project = new GitHubProject(options);
 ```
 
+### Factory method
+
+The factory method is useful when you want immediate access to the project's data, for example to get the project's title. Will throw an error if the project doesn't exist.
+
+```js
+const project = GitHubProject.getInstance(options);
+```
+
 <table>
   <thead align=left>
     <tr>
@@ -236,6 +253,14 @@ function (fieldOptionValue, userValue) {
   </tbody>
 </table>
 
+### `project.getProperties()`
+
+```js
+const projectData = await project.getProperties();
+```
+
+Returns project level data `url`, `title`, `description` and `databaseId`
+
 ### `project.items.list()`
 
 ```js

api/lib/get-state-with-project-fields.js

@@ -17,20 +17,31 @@ export async function getStateWithProjectFields(project, state) {
     return state;
   }
 
-  const {
-    userOrOrganization: { projectV2 },
-  } = await project.octokit.graphql(getProjectCoreDataQuery, {
+  const response = await project.octokit.graphql(getProjectCoreDataQuery, {
     owner: project.owner,
     number: project.number,
   });
 
+  if (
+    response.userOrOrganization === null ||
+    response.userOrOrganization.projectV2 === null
+  ) {
+    throw new Error(
+      `[github-project] Cannot find project with number: ${project.number} and owner: ${project.owner}`
+    );
+  }
+
+  const {
+    userOrOrganization: { projectV2 },
+  } = response;
+
   const fields = projectFieldsNodesToFieldsMap(
     state,
     project,
     projectV2.fields.nodes
   );
 
-  const { id, title, url } = projectV2;
+  const { id, title, url, databaseId } = projectV2;
 
   // mutate current state and return it
   // @ts-expect-error - TS can't handle Object.assign
@@ -39,6 +50,7 @@ export async function getStateWithProjectFields(project, state) {
     id,
     title,
     url,
+    databaseId,
     fields,
   });
 }

api/lib/project-node-to-properties.js

@@ -0,0 +1,18 @@
+// @ts-check
+
+/**
+ * Takes a GraphQL `projectItem` node and returns a `ProjectItem` object
+ * in the format we return it from the GitHubProject API.
+ *
+ * @param {import("../..").GitHubProjectStateWithFields} state
+ * *
+ * @returns {import("../..").GitHubProjectProperties}
+ */
+export function projectNodeToProperties(state) {
+  return {
+    databaseId: state.databaseId,
+    id: state.id,
+    title: state.title,
+    url: state.url,
+  };
+}

api/lib/queries.js

@@ -35,6 +35,7 @@ const queryProjectNodes = `
   id
   title
   url
+  databaseId
   fields(first: 50) {
     nodes {
       ... on ProjectV2FieldCommon {

api/project.getProperties.js

@@ -0,0 +1,18 @@
+// @ts-check
+
+import { projectNodeToProperties } from "./lib/project-node-to-properties.js";
+import { getStateWithProjectFields } from "./lib/get-state-with-project-fields.js";
+
+/**
+ * Attempts to get a project's properties based on the owner and number.
+ *
+ * @param {import("..").default} project
+ * @param {import("..").GitHubProjectState} state
+ *
+ * @returns {Promise<import("..").GitHubProjectProperties | undefined>}
+ */
+export async function getProperties(project, state) {
+  const stateWithFields = await getStateWithProjectFields(project, state);
+
+  return projectNodeToProperties(stateWithFields);
+}

index.d.ts

@@ -19,6 +19,13 @@ export type DraftItemContent = {
   assigneeIds?: string[];
 };
 
+export type GitHubProjectProperties = {
+  databaseId: string;
+  id: string;
+  title: string;
+  url: string;
+};
+
 export default class GitHubProject<
   TCustomFields extends Record<string, FieldOptions> = {},
   TFields extends BUILT_IN_FIELDS = TCustomFields & BUILT_IN_FIELDS,
@@ -40,6 +47,23 @@ export default class GitHubProject<
   /** Map of fields */
   get fields(): TFields;
 
+  /** Project properties */
+  getProperties(): Promise<GitHubProjectProperties>;
+
+  static getInstance<
+    TCustomFields extends Record<string, FieldOptions> = {},
+    TFields extends BUILT_IN_FIELDS = TCustomFields & BUILT_IN_FIELDS,
+    TItemFields extends {} = Record<
+      Exclude<keyof TFields, ConditionalKeys<TFields, { optional: true }>>,
+      string | null
+    > &
+      Partial<
+        Record<ConditionalKeys<TFields, { optional: true }>, string | null>
+      >
+  >(
+    options: GitHubProjectOptions<TCustomFields>
+  ): Promise<GitHubProject<TCustomFields, TFields, TItemFields>>;
+
   constructor(options: GitHubProjectOptions<TCustomFields>);
 
   items: {
@@ -274,4 +298,5 @@ export type GitHubProjectStateWithFields = GitHubProjectStateCommon & {
   title: string;
   url: string;
   fields: ProjectFieldMap;
+  databaseId: string;
 };

index.js

@@ -17,6 +17,7 @@ import { archiveItemByContentRepositoryAndNumber } from "./api/items.archive-by-
 import { removeItem } from "./api/items.remove.js";
 import { removeItemByContentId } from "./api/items.remove-by-content-id.js";
 import { removeItemByContentRepositoryAndNumber } from "./api/items.remove-by-content-repository-and-name.js";
+import { getProperties } from "./api/project.getProperties.js";
 
 import { defaultMatchFunction } from "./api/lib/default-match-function.js";
 
@@ -72,12 +73,31 @@ export default class GitHubProject {
       removeByContentRepositoryAndNumber:
         removeItemByContentRepositoryAndNumber.bind(null, this, state),
     };
+
     Object.defineProperties(this, {
       owner: { get: () => owner },
       number: { get: () => number },
       fields: { get: () => ({ ...BUILT_IN_FIELDS, ...fields }) },
       octokit: { get: () => octokit },
       items: { get: () => itemsApi },
+      getProperties: { get: () => getProperties.bind(null, this, state) },
     });
   }
+
+  /**
+   * Returns a GithubProject instance and calls `getProperties()` to preload
+   * project level properties.
+   *
+   * @param {import(".").GitHubProjectOptions} options
+   *
+   * @return {Promise<import(".").default>}
+   */
+  static async getInstance(options) {
+    const project = /**  @type {import(".").default} */ (
+      new GitHubProject(options)
+    );
+    await project.getProperties();
+
+    return project;
+  }
 }

index.test-d.ts

@@ -607,3 +607,37 @@ export async function matchFieldNameOption() {
     },
   });
 }
+
+export async function testGetInstance() {
+  const project = await GitHubProject.getInstance({
+    owner: "owner",
+    number: 1,
+    token: "gpg_secret123",
+    fields: {
+      myField: "My Field",
+    },
+  });
+
+  expectType<GitHubProject<{ myField: string }>>(project);
+  expectType<string>(project.fields.myField);
+
+  const items = await project.items.list();
+  expectType<string | null>(items[0].fields.myField);
+}
+
+export async function testGetProperties() {
+  const project = new GitHubProject({
+    owner: "owner",
+    number: 1,
+    token: "gpg_secret123",
+  });
+
+  const properties = await project.getProperties();
+
+  expectType<{
+    databaseId: string;
+    id: string;
+    title: string;
+    url: string;
+  }>(properties);
+}