Merge branch 'version-3' into version-3

docs/concepts/typings.md

@@ -1,6 +1,6 @@
 # Typing Return Objects
 
-Whenever you make a request of the library for data from an object and utilize the `select` method to reduce the size of the objects in the payload its preferable in Typescript to be able to type that returned object. The library provides you a method to do so by using TypeScript's Generics declaration.
+Whenever you make a request of the library for data from an object and utilize the `select` method to reduce the size of the objects in the payload its preferable in TypeScript to be able to type that returned object. The library provides you a method to do so by using TypeScript's Generics declaration.
 
 By defining the objects type in the <> after the closure of the select method the resulting object is typed.
 

docs/getting-started.md

@@ -94,7 +94,7 @@ import { spfi, SPFx } from "@pnp/sp";
 protected async onInit(): Promise<void> {
 
     await super.onInit();
-    const sp = spfi().using(spSPFx(this.context));
+    const sp = spfi().using(SPFx(this.context));
 
 }
 
@@ -189,6 +189,13 @@ export class SampleService {
 
 > Due to the way in which Node resolves ESM modules when you use selective imports in node you must include the `index.js` part of the path. Meaning an import like `import "@pnp/sp/webs"` in examples must be `import "@pnp/sp/webs/index.js"`. Root level imports such as `import { spfi } from "@pnp/sp"` remain correct. The samples in this section demonstrate this for their selective imports.
 
+### Importing NodeJS support
+
+> Note that the NodeJS integration relies on code in the module `@pnp/nodejs`. It is therefore required that you import this near the beginning of your program, using simply
+> ```js
+> import "@pnp/nodejs";
+> ```
+
 ### Authentication
 
 To call the SharePoint APIs via MSAL you are required to use certificate authentication with your application. Fully covering certificates is outside the scope of these docs, but the following commands were used with openssl to create testing certs for the sample code below.

docs/queryable/queryable.md

@@ -68,6 +68,12 @@ The Queryable lifecycle is:
 
 As well `log` and `error` can emit at any point during the lifecycle.
 
+## No observers registered for this request
+
+If you see an error thrown with the message `No observers registered for this request.` it means at the time of execution the given object has no actions to take. Because all the request logic is defined within observers, an absence of observers is _likely_ an error condition. If the object was created by a method within the library please report an issue as it is likely a bug. If you created the object through direct use of one of the factory functions, please be sure you have registered observers with `using` or `on` as appropriate. [More information on observers is available in this article](../core/observers.md).
+
+If you for some reason want to execute a queryable with no registred observers, you can simply register a noop observer to any of the moments.
+
 ## Queryable Observers
 
 This section outlines how to write observers for the Queryable lifecycle, and the expectations of each moment's observer behaviors.

docs/sp/files.md

@@ -46,6 +46,28 @@ const file = sp.web.getFileByUrl(url);
 const fileContent = await file.getText();
 ```
 
+### fileFromServerRelativePath
+
+_Added in 3.3.0_
+
+Utility method allowing you to get an IFile reference using any SPQueryable as a base and the server relative path to the file. Helpful when you do not have convenient access to an IWeb to use `getFileByServerRelativePath`.
+
+```TS
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import { fileFromServerRelativePath } from "@pnp/sp/files";
+
+const sp = spfi(...);
+
+const url = "/sites/dev/documents/file.txt";
+
+// file is an IFile and supports all the file operations
+const file = fileFromServerRelativePath(sp.web, url);
+
+// for example
+const fileContent = await file.getText();
+```
+
 ## Adding Files
 
 Likewise you can add files using one of two methods, addUsingPath or addChunked. AddChunked is appropriate for larger files, generally larger than 10 MB but this may differ based on your bandwidth/latency so you can adjust the code to use the chunked method. The below example shows getting the file object from an input and uploading it to SharePoint, choosing the upload method based on file size.

docs/sp/folders.md

@@ -29,6 +29,25 @@ const listFolders = await sp.web.lists.getByTitle("My List").rootFolder.folders(
 const itemFolders = await sp.web.lists.getByTitle("My List").items.getById(1).folder.folders();
 ```
 
+### folderFromServerRelativePath
+
+_Added in 3.3.0_
+
+Utility method allowing you to get an IFolder reference using any SPQueryable as a base and the server relative path to the folder. Helpful when you do not have convenient access to an IWeb to use `getFolderByServerRelativePath`.
+
+```TS
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import { folderFromServerRelativePath } from "@pnp/sp/folders";
+
+const sp = spfi(...);
+
+const url = "/sites/dev/documents/folder4";
+
+// file is an IFile and supports all the file operations
+const folder = folderFromServerRelativePath(sp.web, url);
+```
+
 ### add
 
 Adds a new folder to collection of folders

docs/sp/items.md

@@ -246,7 +246,7 @@ await sp.web.lists.getById("4D5A36EA-6E84-4160-8458-65C436DB765C").items.add({
 
 There are two types of user fields, those that allow a single value and those that allow multiple. For both types, you first need to determine the Id field name, which you can do by doing a GET REST request on an existing item. Typically the value will be the user field internal name with "Id" appended. So in our example, we have two fields User1 and User2 so the Id fields are User1Id and User2Id.
 
-Next, you need to remember there are two types of user fields, those that take a single value and those that allow multiple - these are updated in different ways. For single value user fields you supply just the user's id. For multiple value fields, you need to supply an object with a "results" property and an array. Examples for both are shown below.
+Next, you need to remember there are two types of user fields, those that take a single value and those that allow multiple - these are updated in different ways. For single value user fields you supply just the user's id. For multiple value fields, you need to supply an array. Examples for both are shown below.
 
 ```TypeScript
 import { spfi } from "@pnp/sp";

docs/sp/search.md

@@ -45,20 +45,17 @@ console.log(results3.PrimarySearchResults);
 
 ## Search Result Caching
 
-You can use the searchWithCaching method to enable cache support for your search results this option works with any of the options for providing a query, just replace "search" with "searchWithCaching" in your method chain and gain all the benefits of caching. The second parameter is optional and allows you to specify the cache options
+Starting with v3 you can use any of the caching behaviors with search and the results will be cached. Please see here [for more details on caching options](https://pnp.github.io/pnpjs/queryable/behaviors/#caching).
 
 ```TypeScript
 import { spfi } from "@pnp/sp";
 import "@pnp/sp/search";
 import { ISearchQuery, SearchResults, SearchQueryBuilder } from "@pnp/sp/search";
+import { Caching } from "@pnp/queryable";
 
-const sp = spfi(...);
+const sp = spfi(...).using(Caching());
 
-sp.searchWithCaching({
-    Querytext: "test",
-    RowLimit: 10,
-    EnableInterleaving: true,
-} as ISearchQuery).then((r: SearchResults) => {
+sp.search({/* ... query */}).then((r: SearchResults) => {
 
     console.log(r.ElapsedTime);
     console.log(r.RowCount);
@@ -69,7 +66,7 @@ sp.searchWithCaching({
 const builder = SearchQueryBuilder("test").rowLimit(3);
 
 // supply a search query builder and caching options
-const results2 = await sp.searchWithCaching(builder, { key: "mykey", expiration: dateAdd(new Date(), "month", 1) });
+const results2 = await sp.search(builder);
 
 console.log(results2.TotalRows);
 ```

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