@zxncij2390/monorepo3 3.18.0

package/docs/sp/recycle-bin.md

@@ -0,0 +1,72 @@
+# @pnp/sp/recycle-bin
+
+The contents of the recycle bin.
+
+## IRecycleBin, IRecycleBinItem
+
+[![Invokable Banner](https://img.shields.io/badge/Invokable-informational.svg)](../concepts/invokable.md) [![Selective Imports Banner](https://img.shields.io/badge/Selective%20Imports-informational.svg)](../concepts/selective-imports.md)  
+
+### Work with the contents of the web's Recycle Bin
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/recycle-bin";
+
+const sp = spfi(...);
+
+// gets contents of the web's recycle bin
+const bin = await sp.web.recycleBin();
+
+// gets a specific item from the recycle bin
+const rbItem = await sp.web.recycleBin.getById(bin[0].id);
+
+// delete the item from the recycle bin
+await rbItem.delete();
+
+// restore the item from the recycle bin
+await rbItem.restore();
+
+// move the item to the second-stage (site) recycle bin.
+await rbItem.moveToSecondStage();
+
+// deletes everything in the recycle bin
+await sp.web.recycleBin.deleteAll();
+
+// restores everything in the recycle bin
+await sp.web.recycleBin.restoreAll();
+
+// moves contents of recycle bin to second-stage (site) recycle bin.
+await sp.web.recycleBin.moveAllToSecondStage();
+
+// deletes contents of the second-stage (site) recycle bin.
+await sp.web.recycleBin.deleteAllSecondStageItems();
+```
+
+### Work with the contents of the Second-stage (site) Recycle Bin
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/sites";
+import "@pnp/sp/recycle-bin";
+
+const sp = spfi(...);
+
+// gets contents of the second-stage recycle bin
+const ssBin = await sp.site.recycleBin();
+
+// gets a specific item from the second-stage recycle bin
+const rbItem = await sp.site.recycleBin.getById(ssBin[0].id);
+
+// delete the item from the second-stage recycle bin
+await rbItem.delete();
+
+// restore the item from the second-stage recycle bin
+await rbItem.restore();
+
+// deletes everything in the second-stage recycle bin
+await sp.site.recycleBin.deleteAll();
+
+// restores everything in the second-stage recycle bin
+await sp.site.recycleBin.restoreAll();
+```

package/docs/sp/regional-settings.md

@@ -0,0 +1,108 @@
+# @pnp/sp/regional-settings
+
+The regional settings module helps with managing dates and times across various timezones.
+
+## IRegionalSettings
+
+[![Invokable Banner](https://img.shields.io/badge/Invokable-informational.svg)](../concepts/invokable.md) [![Selective Imports Banner](https://img.shields.io/badge/Selective%20Imports-informational.svg)](../concepts/selective-imports.md)  
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/regional-settings/web";
+
+const sp = spfi(...);
+
+// get all the web's regional settings
+const s = await sp.web.regionalSettings();
+
+// select only some settings to return
+const s2 = await sp.web.regionalSettings.select("DecimalSeparator", "ListSeparator", "IsUIRightToLeft")();
+```
+
+### Installed Languages
+
+You can get a list of the installed languages in the web.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/regional-settings/web";
+
+const sp = spfi(...);
+
+const s = await sp.web.regionalSettings.getInstalledLanguages();
+```
+
+> The installedLanguages property accessor is deprecated after 2.0.4 in favor of getInstalledLanguages and will be removed in future versions.
+
+### TimeZones
+
+You can also get information about the selected timezone in the web and all of the defined timezones.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/regional-settings/web";
+
+const sp = spfi(...);
+
+// get the web's configured timezone
+const s = await sp.web.regionalSettings.timeZone();
+
+// select just the Description and Id
+const s2 = await sp.web.regionalSettings.timeZone.select("Description", "Id")();
+
+// get all the timezones
+const s3 = await sp.web.regionalSettings.timeZones();
+
+// get a specific timezone by id
+// list of ids: https://msdn.microsoft.com/en-us/library/office/jj247008.aspx
+const s4 = await sp.web.regionalSettings.timeZones.getById(23);
+const s5 = await s.localTimeToUTC(new Date());
+
+// convert a given date from web's local time to UTC time
+const s6 = await sp.web.regionalSettings.timeZone.localTimeToUTC(new Date());
+
+// convert a given date from UTC time to web's local time
+const s6 = await sp.web.regionalSettings.timeZone.utcToLocalTime(new Date())
+const s7 = await sp.web.regionalSettings.timeZone.utcToLocalTime(new Date(2019, 6, 10, 10, 0, 0, 0))
+```
+
+### Title and Description Resources
+
+Some objects allow you to read language specific title information as shown in the following sample. This applies to Web, List, Field, Content Type, and User Custom Actions.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/regional-settings";
+
+const sp = spfi(...);
+
+//
+// The below methods appears on
+// - Web
+// - List
+// - Field
+// - ContentType
+// - User Custom Action
+//
+// after you import @pnp/sp/regional-settings
+//
+// you can also import just parts of the regional settings:
+// import "@pnp/sp/regional-settings/web";
+// import "@pnp/sp/regional-settings/list";
+// import "@pnp/sp/regional-settings/content-type";
+// import "@pnp/sp/regional-settings/field";
+// import "@pnp/sp/regional-settings/user-custom-actions";
+
+
+const title = await sp.web.titleResource("en-us");
+const title2 = await sp.web.titleResource("de-de");
+
+const description = await sp.web.descriptionResource("en-us");
+const description2 = await sp.web.descriptionResource("de-de");
+```
+
+> You can only read the values through the REST API, not set the value.

package/docs/sp/related-items.md

@@ -0,0 +1,136 @@
+# @pnp/sp/related-items
+
+The related items API allows you to add related items to items within a task or workflow list. Related items need to be in the same site collection.
+
+## Setup
+
+Instead of copying this block of code into each sample, understand that each sample is meant to run with this supporting code to work.
+
+```TypeScript
+import { spfi, SPFx, extractWebUrl } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/related-items/web";
+import "@pnp/sp/lists/web";
+import "@pnp/sp/items/list";
+import "@pnp/sp/files/list";
+import { IList } from "@pnp/sp/lists";
+import { getRandomString } from "@pnp/core";
+
+const sp = spfi(...);
+
+// setup some lists (or just use existing ones this is just to show the complete process)
+// we need two lists to use for creating related items, they need to use template 107 (task list)
+const ler1 = await sp.web.lists.ensure("RelatedItemsSourceList", "", 107);
+const ler2 = await sp.web.lists.ensure("RelatedItemsTargetList", "", 107);
+
+const sourceList = ler1.list;
+const targetList = ler2.list;
+
+const sourceListName = await sourceList.select("Id")().then(r => r.Id);
+const targetListName = await targetList.select("Id")().then(r => r.Id);
+
+// or whatever you need to get the web url, both our example lists are in the same web.
+const webUrl = sp.web.toUrl();
+
+// ...individual samples start here
+```
+
+## addSingleLink
+
+```TypeScript
+const sourceItem = await sourceList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+const targetItem = await targetList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+
+await sp.web.relatedItems.addSingleLink(sourceListName, sourceItem.Id, webUrl, targetListName, targetItem.Id, webUrl);
+```
+
+## addSingleLinkToUrl
+
+This method adds a link to task item based on a url. The list name and item id are to the task item, the url is to the related item/document.
+
+```TypeScript
+// get a file's server relative url in some manner, here we add one
+const file = await sp.web.defaultDocumentLibrary.rootFolder.files.add(`file_${getRandomString(4)}.txt`, "Content", true).then(r => r.data);
+// add an item or get an item from the task list
+const targetItem = await targetList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+
+await sp.web.relatedItems.addSingleLinkToUrl(targetListName, targetItem.Id, file.ServerRelativeUrl);
+```
+
+## addSingleLinkFromUrl
+
+This method adds a link to task item based on a url. The list name and item id are to related item, the url is to task item to which the related reference is being added. I haven't found a use case for this method.
+
+## deleteSingleLink
+
+This method allows you to delete a link previously created.
+
+```TypeScript
+const sourceItem = await sourceList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+const targetItem = await targetList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+
+// add the link
+await sp.web.relatedItems.addSingleLink(sourceListName, sourceItem.Id, webUrl, targetListName, targetItem.Id, webUrl);
+
+// delete the link
+await sp.web.relatedItems.deleteSingleLink(sourceListName, sourceItem.Id, webUrl, targetListName, targetItem.Id, webUrl);
+```
+
+## getRelatedItems
+
+Gets the related items for an item
+
+```TypeScript
+import { IRelatedItem } from "@pnp/sp/related-items";
+
+const sourceItem = await sourceList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+const targetItem = await targetList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+
+// add a link
+await sp.web.relatedItems.addSingleLink(sourceListName, sourceItem.Id, webUrl, targetListName, targetItem.Id, webUrl);
+
+const targetItem2 = await targetList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+
+// add a link
+await sp.web.relatedItems.addSingleLink(sourceListName, sourceItem.Id, webUrl, targetListName, targetItem2.Id, webUrl);
+
+const items: IRelatedItem[] = await sp.web.relatedItems.getRelatedItems(sourceListName, sourceItem.Id);
+
+// items.length === 2
+```
+
+Related items are defined by the IRelatedItem interface
+
+```JSON
+export interface IRelatedItem {
+    ListId: string;
+    ItemId: number;
+    Url: string;
+    Title: string;
+    WebId: string;
+    IconUrl: string;
+}
+```
+
+## getPageOneRelatedItems
+
+Gets an abbreviated set of related items
+
+```TypeScript
+import { IRelatedItem } from "@pnp/sp/related-items";
+
+const sourceItem = await sourceList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+const targetItem = await targetList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+
+// add a link
+await sp.web.relatedItems.addSingleLink(sourceListName, sourceItem.Id, webUrl, targetListName, targetItem.Id, webUrl);
+
+const targetItem2 = await targetList.items.add({ Title: `Item ${getRandomString(4)}` }).then(r => r.data);
+
+// add a link
+await sp.web.relatedItems.addSingleLink(sourceListName, sourceItem.Id, webUrl, targetListName, targetItem2.Id, webUrl);
+
+const items: IRelatedItem[] = await sp.web.relatedItems.getPageOneRelatedItems(sourceListName, sourceItem.Id);
+
+// items.length === 2
+```

package/docs/sp/search.md

@@ -0,0 +1,207 @@
+# @pnp/sp/search
+
+Using search you can access content throughout your organization in a secure and consistent manner. The library provides support for searching and suggest - as well as some interfaces and helper classes to make building your queries and processing responses easier.
+
+## Search
+
+[![Invokable Banner](https://img.shields.io/badge/Invokable-informational.svg)](../concepts/invokable.md) [![Selective Imports Banner](https://img.shields.io/badge/Selective%20Imports-informational.svg)](../concepts/selective-imports.md)  
+
+Search is accessed directly from the root sp object and can take either a string representing the query text, a plain object matching the ISearchQuery interface, or a SearchQueryBuilder instance.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/search";
+import { ISearchQuery, SearchResults, SearchQueryBuilder } from "@pnp/sp/search";
+
+const sp = spfi(...);
+
+// text search using SharePoint default values for other parameters
+const results: SearchResults = await sp.search("test");
+
+console.log(results.ElapsedTime);
+console.log(results.RowCount);
+console.log(results.PrimarySearchResults);
+
+
+// define a search query object matching the ISearchQuery interface
+const results2: SearchResults = await sp.search(<ISearchQuery>{
+    Querytext: "test",
+    RowLimit: 10,
+    EnableInterleaving: true,
+});
+
+console.log(results2.ElapsedTime);
+console.log(results2.RowCount);
+console.log(results2.PrimarySearchResults);
+
+// define a query using a builder
+const builder = SearchQueryBuilder("test").rowLimit(10).enableInterleaving.enableQueryRules.processPersonalFavorites;
+const results3 = await sp.search(builder);
+
+console.log(results3.ElapsedTime);
+console.log(results3.RowCount);
+console.log(results3.PrimarySearchResults);
+```
+
+## Search Result Caching
+
+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(...).using(Caching());
+
+sp.search({/* ... query */}).then((r: SearchResults) => {
+
+    console.log(r.ElapsedTime);
+    console.log(r.RowCount);
+    console.log(r.PrimarySearchResults);
+});
+
+// use a query builder
+const builder = SearchQueryBuilder("test").rowLimit(3);
+
+// supply a search query builder and caching options
+const results2 = await sp.search(builder);
+
+console.log(results2.TotalRows);
+```
+
+## Paging with SearchResults.getPage
+
+Paging is controlled by a start row and page size parameter. You can specify both arguments in your initial query however you can use the getPage method to jump to any page. The second parameter page size is optional and will use the previous RowLimit or default to 10.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/search";
+import { SearchResults, SearchQueryBuilder } from "@pnp/sp/search";
+
+const sp = spfi(...);
+
+// this will hold our current results
+let currentResults: SearchResults = null;
+let page = 1;
+
+// triggered on page load or through some other means
+function onStart() {
+
+    // construct our query that will be used throughout the paging process, likely from user input
+    const q = SearchQueryBuilder("test").rowLimit(5);
+    const results = await sp.search(q);
+    currentResults = results; // set the current results
+    page = 1; // reset page counter
+    // update UI...
+}
+
+// triggered by an event
+async function next() {
+
+    currentResults = await currentResults.getPage(++page);
+    // update UI...
+}
+
+// triggered by an event
+async function prev() {
+
+    currentResults = await currentResults.getPage(--page);
+    // update UI...
+}
+```
+
+## SearchQueryBuilder
+
+The SearchQueryBuilder allows you to build your queries in a fluent manner. It also accepts constructor arguments for query text and a base query plain object, should you have a shared configuration for queries in an application you can define them once. The methods and properties match those on the SearchQuery interface. Boolean properties add the flag to the query while methods require that you supply one or more arguments. Also arguments supplied later in the chain will overwrite previous values.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/search";
+import { SearchQueryBuilder, SearchResults, ISearchQuery } from "@pnp/sp/search";
+
+const sp = spfi(...);
+
+// basic usage
+let q = SearchQueryBuilder().text("test").rowLimit(4).enablePhonetic;
+
+sp.search(q).then(h => { /* ... */ });
+
+// provide a default query text at creation
+let q2 = SearchQueryBuilder("text").rowLimit(4).enablePhonetic;
+
+const results: SearchResults = await sp.search(q2);
+
+// provide query text and a template for
+// shared settings across queries that can
+// be overwritten by individual builders
+const appSearchSettings: ISearchQuery = {
+    EnablePhonetic: true,
+    HiddenConstraints: "reports"
+};
+
+let q3 = SearchQueryBuilder("test", appSearchSettings).enableQueryRules;
+let q4 = SearchQueryBuilder("financial data", appSearchSettings).enableSorting.enableStemming;
+const results2 = await sp.search(q3);
+const results3 = sp.search(q4);
+```
+
+## Search Suggest
+
+Search suggest works in much the same way as search, except against the suggest end point. It takes a string or a plain object that matches ISuggestQuery.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/search";
+import { ISuggestQuery, ISuggestResult } from "@pnp/sp/search";
+
+const sp = spfi(...);
+
+const results = await sp.searchSuggest("test");
+
+const results2 = await sp.searchSuggest({
+    querytext: "test",
+    count: 5,
+} as ISuggestQuery);
+```
+
+## Search Factory
+
+You can also configure a search or suggest query against any valid SP url using the factory methods.
+
+> In this case you'll need to ensure you add observers, or use the [tuple constructor](../queryable/queryable.md/#queryable-constructor) to inherit
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/web";
+import "@pnp/sp/search";
+import { Search, Suggest } from "@pnp/sp/search";
+import { SPDefault } from "@pnp/nodejs";
+
+const sp = spfi(...);
+
+// set the url for search
+const searcher = Search([sp.web, "https://mytenant.sharepoint.com/sites/dev"]);
+
+// this can accept any of the query types (text, ISearchQuery, or SearchQueryBuilder)
+const results = await searcher("test");
+
+// you can reuse the ISearch instance
+const results2 = await searcher("another query");
+
+// same process works for Suggest
+const suggester = Suggest([sp.web, "https://mytenant.sharepoint.com/sites/dev"]);
+
+const suggestions = await suggester({ querytext: "test" });
+
+// resetting the observers on the instance
+const searcher2 = Search("https://mytenant.sharepoint.com/sites/dev").using(SPDefault({
+  msal: {
+    config: {...},
+    scopes: [...],
+  },
+}));
+
+const results3 = await searcher2("test");
+```