adding support for termStore.searchTerm pnp#2202

docs/sp/taxonomy.md

@@ -25,6 +25,39 @@ const sp = spfi(...);
 const info: ITermStoreInfo = await sp.termStore();
 ```
 
+### searchTerm
+
+_Added in 3.3.0_
+
+Search for terms starting with provided label under entire termStore or a termSet or a parent term.
+
+The following properties are valid for the supplied query: `label: string`, `setId?: string`, `parentTermId?: string`, `languageTag?: string`, `stringMatchOption?: "ExactMatch" | "StartsWith"`.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/taxonomy";
+
+const sp = spfi(...);
+
+// minimally requires the label
+const results1 = await sp.termStore.searchTerm({
+  label: "test",
+});
+
+// other properties can be included as needed
+const results2 = await sp.termStore.searchTerm({
+  label: "test",
+  setId: "{guid}",
+});
+
+// other properties can be included as needed
+const results3 = await sp.termStore.searchTerm({
+  label: "test",
+  setId: "{guid}",
+  stringMatchOption: "ExactMatch",
+});
+```
+
 ## Term Groups
 
 Access term group information

packages/sp/taxonomy/types.ts

@@ -1,6 +1,7 @@
 import { isArray } from "@pnp/core";
 import { defaultPath } from "../decorators.js";
 import { _SPInstance, spInvokableFactory, _SPCollection } from "../spqueryable.js";
+import { escapeQueryStrValue } from "../utils/escape-query-str.js";
 
 /**
  * Describes a collection of Form objects
@@ -22,11 +23,26 @@ export class _TermStore extends _SPInstance<ITermStoreInfo> {
     public get sets(): ITermSets {
         return TermSets(this);
     }
+
+    /**
+     * Allows you to locate terms within the termStore
+     *
+     * @param params Search parameters used to locate the terms, label is required
+     * @returns Array of terms including set information for each term
+     */
+    public async searchTerm(params: ISearchTermParams): Promise<Required<Pick<ITermInfo, SearchTermPickedProps>>[]> {
+
+        const query = Reflect.ownKeys(params).reduce((c, prop: string) => {
+            c.push(`${prop}='${escapeQueryStrValue(params[prop])}'`);
+            return c;
+        }, []).join(",");
+
+        return TermStore(this, `searchTerm(${query})`).expand("set")();
+    }
 }
 export interface ITermStore extends _TermStore { }
 export const TermStore = spInvokableFactory<ITermStore>(_TermStore);
 
-
 @defaultPath("groups")
 export class _TermGroups extends _SPCollection<ITermGroupInfo[]> {
 
@@ -162,8 +178,8 @@ export class _TermSet extends _SPInstance<ITermSetInfo> {
                 };
 
                 if (child.childrenCount > 0) {
-                    await visitor(this.getTermById(children[i].id), orderedTerm.children);
-                    orderedTerm.children = ensureOrder(orderedTerm.children, child.customSortOrder);
+                    await visitor(this.getTermById(children[i].id), <any>orderedTerm.children);
+                    orderedTerm.children = ensureOrder(<any>orderedTerm.children, child.customSortOrder);
                 }
 
                 parent.push(orderedTerm);
@@ -284,24 +300,52 @@ export interface ITermInfo {
     id: string;
     labels: { name: string; isDefault: boolean; languageTag: string }[];
     createdDateTime: string;
-    customSortOrder: ITermSortOrderInfo[];
+    customSortOrder?: ITermSortOrderInfo[];
     lastModifiedDateTime: string;
     descriptions: { description: string; languageTag: string }[];
     properties?: ITaxonomyProperty[];
     localProperties?: ITaxonomyLocalProperty[];
     isDeprecated: boolean;
     isAvailableForTagging: { setId: string; isAvailable: boolean }[];
-    topicRequested: boolean;
+    topicRequested?: boolean;
     parent?: ITermInfo;
+    set?: ITermSetInfo;
+    relations?: IRelationInfo[];
+    children?: ITermInfo[];
 }
 
+export interface ISearchTermParams {
+    /**
+     * The term label to search for.
+     */
+    label: string;
+    /**
+     * The setId to scope down the search under a termSet.
+     */
+    setId?: string;
+    /**
+     * The parentTermId to scope down the search under a termSet, under a parent term.
+     */
+    parentTermId?: string;
+    /**
+     * The languageTag to scope down the search to a specific language.
+     */
+    languageTag?: string;
+    /**
+     * Indicates what type of string matching should be performed when searching.
+     */
+    stringMatchOption?: "ExactMatch" | "StartsWith";
+}
+
+type SearchTermPickedProps = "childrenCount" | "createdDateTime" | "descriptions" | "id" | "isAvailableForTagging" | "isDeprecated" | "labels" | "lastModifiedDateTime" | "set";
+
 export interface ITermSortOrderInfo {
     setId: string;
     order: string[];
 }
 
 export interface IOrderedTermInfo extends ITermInfo {
-    children: IOrderedTermInfo[];
+    children: ITermInfo[];
     defaultLabel: string;
 }
 

test/sp/taxonomy.ts

@@ -117,12 +117,12 @@ describe("Taxonomy", function () {
             const termById = await termset.getTermById(terms[0].id)();
             return expect(termById).has.property("id");
         });
-        it("getAllChildrenAsOrderedTree", async function(){
+        it("getAllChildrenAsOrderedTree", async function () {
             const tree = await termset.getAllChildrenAsOrderedTree();
             return expect(tree).to.be.an("Array");
         });
         it("getAllChildrenAsOrderedTree-retreiveProperties", async function () {
-            const tree = await termset.getAllChildrenAsOrderedTree({retrieveProperties: true});
+            const tree = await termset.getAllChildrenAsOrderedTree({ retrieveProperties: true });
             if (tree.length < 1) {
                 return;
             }