@zxncij2390/monorepo3 3.18.0

package/docs/concepts/error-handling.md

@@ -0,0 +1,245 @@
+# Error Handling
+
+This article describes the most common types of errors generated by the library. It provides context on the error object, and ways to handle the errors. As always you should tailor your error handling to what your application needs. These are ideas that can be applied to many different patterns.
+
+> For 429, 503, and 504 errors we include retry logic within the library
+
+## The HttpRequestError
+
+All errors resulting from executed web requests will be returned as an `HttpRequestError` object which extends the base `Error`. In addition to the standard Error properties it has some other properties to help you figure out what went wrong. We used a custom error to attempt to normalize what can be a wide assortment of http related errors, while also seeking to provide as much information to library consumers as possible.
+
+|Property Name|Description|
+|---|---|
+|name|Standard Error.name property. Always 'Error'|
+|message|Normalized string containing the status, status text, and the full response text|
+|stack|The callstack producing the error|
+|isHttpRequestError|Always true, allows you to reliably determine if you have an HttpRequestError instance|
+|response|Unread copy of the Response object resulting in the thrown error|
+|status|The Response.status value (such as 404)
+|statusText|The Response.statusText value (such as 'Not Found')
+
+## Basic Handling
+
+For all operations involving a web request you should account for the possibility they might fail. That failure might be transient or permanent - you won't know until they happen 😉. The most basic type of error handling involves a simple try-catch when using the [async/await promises pattern](https://javascript.info/async-await).
+
+```TypeScript
+import { sp } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists/web";
+
+try {
+
+  // get a list that doesn't exist
+  const w = await sp.web.lists.getByTitle("no")();
+
+} catch (e) {
+
+  console.error(e);
+}
+```
+
+This will produce output like:
+
+```console
+Error making HttpClient request in queryable [404] Not Found ::> {"odata.error":{"code":"-1, System.ArgumentException","message":{"lang":"en-US","value":"List 'no' does not exist at site with URL 'https://tenant.sharepoint.com/sites/dev'."}}} Data: {"response":{"size":0,"timeout":0},"status":404,"statusText":"Not Found","isHttpRequestError":true}
+```
+
+This is very descriptive and provides full details as to what happened, but you might want to handle things a little more cleanly.
+
+## Reading the Response
+
+In some cases the response body will have additional details such as a localized error messages which can be nicer to display rather than our normalized string. You can read the response directly and process it however you desire:
+
+```TypeScript
+import { sp } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists/web";
+import { HttpRequestError } from "@pnp/queryable";
+
+try {
+  
+  // get a list that doesn't exist
+  const w = await sp.web.lists.getByTitle("no")();
+
+} catch (e) {
+
+  // are we dealing with an HttpRequestError?
+  if (e?.isHttpRequestError) {
+
+    // we can read the json from the response
+    const json = await (<HttpRequestError>e).response.json();
+
+    // if we have a value property we can show it
+    console.log(typeof json["odata.error"] === "object" ? json["odata.error"].message.value : e.message);
+
+    // add of course you have access to the other properties and can make choices on how to act
+    if ((<HttpRequestError>e).status === 404) {
+       console.error((<HttpRequestError>e).statusText);
+      // maybe create the resource, or redirect, or fallback to a secondary data source
+      // just ideas, handle any of the status codes uniquely as needed
+    }
+
+  } else {
+    // not an HttpRequestError so we just log message
+    console.log(e.message);
+  }
+}
+```
+
+## Logging errors
+
+Using the [PnPjs Logging Framework](../logging/index.md) you can directly pass the error object and the normalized message will be logged. These techniques can be applied to any logging framework.
+
+```TypeScript
+import { Logger } from "@pnp/logging";
+import { sp } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists/web";
+
+try {
+  // get a list that doesn't exist
+  const w = await sp.web.lists.getByTitle("no")();  
+} catch (e) {
+
+  Logger.error(e);
+}
+```
+
+You may want to read the response and customize the message as described above:
+
+```TypeScript
+import { Logger } from "@pnp/logging";
+import { sp } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists/web";
+import { HttpRequestError } from "@pnp/queryable";
+
+try {
+  // get a list that doesn't exist
+  const w = await sp.web.lists.getByTitle("no")();  
+} catch (e) {
+
+  if (e?.isHttpRequestError) {
+
+    // we can read the json from the response
+    const data = await (<HttpRequestError>e).response.json();
+
+    // parse this however you want
+    const message = typeof data["odata.error"] === "object" ? data["odata.error"].message.value : e.message;
+
+    // we use the status to determine a custom logging level
+    const level: LogLevel = (<HttpRequestError>e).status === 404 ? LogLevel.Warning : LogLevel.Info;
+
+    // create a custom log entry
+    Logger.log({
+      data,
+      level,
+      message,
+    });
+
+  } else {
+    // not an HttpRequestError so we just log message
+    Logger.error(e);
+  }
+}
+```
+
+## Putting it All Together
+
+After reviewing the above section you might have thought it seems like a lot of work to include all that logic for every error. One approach is to establish a single function you use application wide to process errors. This allows all the error handling logic to be easily updated and consistent across the application.
+
+### errorhandler.ts
+
+```TypeScript
+import { Logger } from "@pnp/logging";
+import { HttpRequestError } from "@pnp/queryable";
+import { hOP } from "@pnp/core";
+
+export async function handleError(e: Error | HttpRequestError): Promise<void> {
+
+  if (hOP(e, "isHttpRequestError")) {
+
+    // we can read the json from the response
+    const data = await (<HttpRequestError>e).response.json();
+
+    // parse this however you want
+    const message = typeof data["odata.error"] === "object" ? data["odata.error"].message.value : e.message;
+
+    // we use the status to determine a custom logging level
+    const level: LogLevel = (<HttpRequestError>e).status === 404 ? LogLevel.Warning : LogLevel.Info;
+
+    // create a custom log entry
+    Logger.log({
+      data,
+      level,
+      message,
+    });
+
+  } else {
+    // not an HttpRequestError so we just log message
+    Logger.error(e);
+  }
+}
+```
+
+### web-request.ts
+
+```TypeScript
+import { sp } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists/web";
+import { handleError } from "./errorhandler";
+
+try {
+
+  const w = await sp.web.lists.getByTitle("no")();
+
+} catch (e) {
+
+  await handleError(e);
+}
+```
+
+### web-request2.ts
+
+```TypeScript
+import { sp } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists/web";
+import { handleError } from "./errorhandler";
+
+try {
+
+  const w = await sp.web.lists();
+
+} catch (e) {
+
+  await handleError(e);
+}
+```
+
+## Building a Custom Error Handler
+
+In Version 3 the library introduced the concept of a Timeline object and moments. One of the broadcast moments is error. To create your own custom error handler you can define a special handler for the error moment something like the following:
+
+```TypeScript
+
+//Custom Error Behavior
+export function CustomError(): TimelinePipe<Queryable> {
+
+    return (instance: Queryable) => {
+
+        instance.on.error((err) => {
+            if (logging) {
+                console.log(`🛑 PnPjs Testing Error - ${err.toString()}`);
+            }
+        });
+
+        return instance;
+    };
+}
+
+//Adding our CustomError behavior to our timline
+
+const sp = spfi().using(SPDefault(this.context)).using(CustomError());
+```

package/docs/concepts/invokable.md

@@ -0,0 +1,7 @@
+# Invokables
+
+For people who have been using the library since the early days you are familiar with the need to use the `()` method to invoke a method chain: Starting with v3 this is no longer possible, you must invoke the object directly to execute the default action for that class:
+
+```TypeScript
+const lists = await sp.web.lists();
+```

package/docs/concepts/nightly-builds.md

@@ -0,0 +1,19 @@
+# Nightly Builds
+
+Starting with version 3 we support nightly builds, which are built from the version-3 branch each evening and include all the changes merged ahead of a particular build. These are a great way to try out new features before a release, or get a fix or enhancement without waiting for the monthly builds.
+
+You can install the nightly builds using the below examples. While we only show examples for `sp` and `graph` nightly builds are available for all packages.
+
+### SP
+
+```CMD
+npm install @pnp/sp@v3nightly --save
+```
+
+### Microsoft Graph
+
+```CMD
+npm install @pnp/graph@v3nightly --save
+```
+
+> Nightly builds are NOT monthly releases and aren't tested as deeply. We never intend to release broken code, but nightly builds may contain some code that is not entirely final or fully reviewed. As always if you encounter an issue [please let us know](https://github.com/pnp/pnpjs/issues), especially for nightly builds so we can be sure to address it before the next monthly release.

package/docs/concepts/project-preset.md

@@ -0,0 +1,123 @@
+# Project Config/Services Setup
+
+Due to the introduction of [selective imports](./selective-imports.md) it can be somewhat frustrating to import all of the needed dependencies every time you need them across many files. Instead the preferred approach, especially for SPFx, is to create a project config file or establish a service to manage your PnPjs interfaces. Doing so centralizes the imports, configuration, and optionally extensions to PnPjs in a single place.
+
+> If you have multiple projects that share dependencies on PnPjs you can benefit from creating a [custom bundle](./custom-bundle.md) and using them across your projects.
+
+These steps reference an [SPFx](https://docs.microsoft.com/sharepoint/dev/spfx/sharepoint-framework-overview) solution, but apply to any solution.
+
+## Using a config file
+
+Within the src directory create a new file named `pnpjs-config.ts` and copy in the below content.
+
+```TypeScript
+import { WebPartContext } from "@microsoft/sp-webpart-base";
+
+// import pnp, pnp logging system, and any other selective imports needed
+import { spfi, SPFI, SPFx } from "@pnp/sp";
+import { LogLevel, PnPLogging } from "@pnp/logging";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import "@pnp/sp/items";
+import "@pnp/sp/batching";
+
+var _sp: SPFI = null;
+
+export const getSP = (context?: WebPartContext): SPFI => {
+  if (context != null) {
+    //You must add the @pnp/logging package to include the PnPLogging behavior it is no longer a peer dependency
+    // The LogLevel set's at what level a message will be written to the console
+    _sp = spfi().using(SPFx(context)).using(PnPLogging(LogLevel.Warning));
+  }
+  return _sp;
+};
+```
+
+To initialize the configuration, from the `onInit` function (or whatever function runs first in your code) make a call to getSP passing in the SPFx context object (or whatever configuration you would require for your setup).
+
+```TypeScript
+protected async onInit(): Promise<void> {
+  this._environmentMessage = this._getEnvironmentMessage();
+
+  super.onInit();
+
+  //Initialize our _sp object that we can then use in other packages without having to pass around the context.
+  //  Check out pnpjsConfig.ts for an example of a project setup file.
+  getSP(this.context);
+}
+```
+
+Now you can consume your configured `_sp` object from anywhere else in your code by simply referencing the `pnpjs-presets.ts` file via an import statement and then getting a local instance of the `_sp` object using the `getSP()` method without passing any context.
+
+```TypeScript
+import { getSP } from './pnpjs-config.ts';
+...
+export default class PnPjsExample extends React.Component<IPnPjsExampleProps, IIPnPjsExampleState> {
+  
+  private _sp: SPFI;
+
+  constructor(props: IPnPjsExampleProps) {
+    super(props);
+    // set initial state
+    this.state = {
+      items: [],
+      errors: []
+    };
+    this._sp = getSP();
+  }
+
+  ...
+
+}
+```
+
+### Use a service class
+
+Because you do not have full access to the context object within a service you need to setup things a little differently.
+
+```TypeScript
+import { ServiceKey, ServiceScope } from "@microsoft/sp-core-library";
+import { PageContext } from "@microsoft/sp-page-context";
+import { AadTokenProviderFactory } from "@microsoft/sp-http";
+import { spfi, SPFI, SPFx as spSPFx } from "@pnp/sp";
+import { graphfi, GraphFI, SPFx as gSPFx } from "@pnp/graph";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists/web";
+
+export interface ISampleService {
+    getLists(): Promise<any[]>;
+}
+
+export class SampleService {
+
+    public static readonly serviceKey: ServiceKey<ISampleService> = ServiceKey.create<ISampleService>('SPFx:SampleService', SampleService);
+    private _sp: SPFI;
+    private _graph: GraphFI;
+
+    constructor(serviceScope: ServiceScope) {
+
+        serviceScope.whenFinished(() => {
+
+        const pageContext = serviceScope.consume(PageContext.serviceKey);
+        const aadTokenProviderFactory = serviceScope.consume(AadTokenProviderFactory.serviceKey);
+
+        //SharePoint
+        this._sp = spfi().using(spSPFx({ pageContext }));
+
+        //Graph
+        this._graph = graphfi().using(gSPFx({ aadTokenProviderFactory }));
+    }
+
+    public getLists(): Promise<any[]> {
+        return this._sp.web.lists();
+    }
+}
+```
+
+Depending on the architecture of your solution you can also opt to export the service as a global. If you choose this route you would need to modify the service to create an Init function where you would pass the service scope instead of doing so in the constructor. You would then export a constant that creates a global instance of the service.
+
+```ts
+export const mySampleService = new SampleService();
+```
+
+For a full sample, please see our [PnPjs Version 3 Sample Project](https://github.com/pnp/sp-dev-fx-webparts/tree/main/samples/react-pnp-js-sample)

package/docs/concepts/selective-imports.md

@@ -0,0 +1,106 @@
+# Selective Imports
+
+As the libraries have grown to support more of the SharePoint and Graph API they have also grown in size. On one hand this is good as more functionality becomes available but you had to include lots of code you didn't use if you were only doing simple operations. To solve this we introduced selective imports. This allows you to only import the parts of the sp or graph library you need, allowing you to greatly reduce your overall solution bundle size - and enables [treeshaking](https://github.com/rollup/rollup#tree-shaking).
+
+This concept works well with [custom bundling](./custom-bundle.md) to create a shared package tailored exactly to your needs.
+
+If you would prefer to not worry about selective imports please see the section on [presets](#presets).
+
+> A quick note on how TypeScript handles type only imports. If you have a line like `import { IWeb } from "@pnp/sp/webs"` everything will transpile correctly but you will get runtime errors because TS will see that line as a type only import and drop it. You need to include both `import { IWeb } from "@pnp/sp/webs"` and `import "@pnp/sp/webs"` to ensure the webs functionality is correctly included. You can see this in the last example below.
+
+```TypeScript
+// the sp var now has almost nothing attached at import time and relies on
+
+// we need to import each of the pieces we need to "attach" them for chaining
+// here we are importing the specific sub modules we need and attaching the functionality for lists to web and items to list
+import "@pnp/sp/webs";
+import "@pnp/sp/lists/web";
+import "@pnp/sp/items/list";
+
+// placeholder for fully configuring the sp interface
+const sp = spfi();
+
+const itemData = await sp.web.lists.getById('00000000-0000-0000-0000-000000000000').items.getById(1)();
+```
+
+Above we are being very specific in what we are importing, but you can also import entire sub-modules and be slightly less specific
+
+```TypeScript
+// the sp var now has almost nothing attached at import time and relies on
+
+// we need to import each of the pieces we need to "attach" them for chaining
+// here we are importing the specific sub modules we need and attaching the functionality for lists to web and items to list
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import "@pnp/sp/items";
+
+// placeholder for fully configuring the sp interface
+const sp = spfi();
+
+const itemData = await sp.web.lists.getById('00000000-0000-0000-0000-000000000000').items.getById(1)();
+```
+
+The above two examples both work just fine but you may end up with slightly smaller bundle sizes using the first. Consider this example:
+
+```TypeScript
+// this import statement will attach content-type functionality to list, web, and item
+import "@pnp/sp/content-types";
+
+// this import statement will only attach content-type functionality to web
+import "@pnp/sp/content-types/web";
+```
+
+If you only need to access content types on the web object you can reduce size by only importing that piece.
+
+The below example shows the need to import types and module augmentation separately.
+
+```TypeScript
+// this will fail
+import "@pnp/sp/webs";
+import { IList } from "@pnp/sp/lists";
+
+// do this instead
+import { sp } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import { IList } from "@pnp/sp/lists";
+
+// placeholder for fully configuring the sp interface
+const sp = spfi();
+
+const lists = await sp.web.lists();
+```
+
+## Presets
+
+Sometimes you don't care as much about bundle size - testing or node development for example. In these cases we have provided what we are calling presets to allow you to skip importing each module individually. Both libraries supply an "all" preset that will attach all of the available library functionality.
+
+> While the presets provided may be useful, we encourage you to look at making your own [project presets](./project-preset.md) or [custom bundles](./custom-bundle.md) as a preferred solution. Use of the presets in client-side solutions is not recommended.
+
+## SP
+
+```TypeScript
+import "@pnp/sp/presets/all";
+
+
+// placeholder for fully configuring the sp interface
+const sp = spfi();
+
+// sp.* will have all of the library functionality bound to it, tree shaking will not work
+const lists = await sp.web.lists();
+```
+
+## Graph
+
+The graph library contains a single preset, "all" mimicking the v1 structure.
+
+```TypeScript
+import "@pnp/graph/presets/all";
+import { graphfi } from "@pnp/graph";
+
+// placeholder for fully configuring the sp interface
+const graph = graphfi();
+
+// graph.* will have all of the library functionality bound to it, tree shaking will not work
+const me = await graph.me();
+```

package/docs/concepts/typings.md

@@ -0,0 +1,23 @@
+# 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.
+
+By defining the objects type in the <> after the closure of the select method the resulting object is typed.
+
+```TypesScript
+  .select("Title")<{Title: string}>()
+```
+
+Below are some examples of typing the return payload:
+
+```TypeScript
+  const _sp = spfi().using(SPFx(this.context));
+
+  //Typing the Title property of a field
+  const field = await _sp.site.rootWeb.fields.getById(titleFieldId).select("Title")<{ Title: string }>();
+            
+  //Typing the ParentWebUrl property of the selected list.
+  const testList = await _sp.web.lists.getByTitle('MyList').select("ParentWebUrl")<{ ParentWebUrl: string }>();
+```
+
+> There have been discussions in the past around auto-typing based on select and the expected properties of the return object. We haven't done so for a few reasons: there is no even mildly complex way to account for all the possibilities expand introduces to selects, and if we "ignore" expand it effectively makes the select typings back to "any". Looking at template types etc, we haven't yet seen a way to do this that makes it worth the effort and doesn't introduce some other limitation or confusion.

package/docs/contributing/debug-tests.md

@@ -0,0 +1,76 @@
+# Writing Tests
+
+With version 2 we have made a significant effort to improve out test coverage. To keep that up, all changes submitted will require one or more tests be included. For new functionality at least a basic test that the method executes is required. For bug fixes please include a test that would have caught the bug (i.e. fail before your fix) and passes with your fix in place.
+
+## How to write Tests
+
+We use [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/) for our testing framework. You can see many examples of writing tests within the ./test folder. Here is a sample with extra comments to help explain what's happening, taken from [./test/sp/items.ts](https://github.com/pnp/pnpjs/blob/main/test/sp/items.ts):
+
+```TypeScript
+import { getRandomString } from "@pnp/core";
+import { testSettings } from "../main";
+import { expect } from "chai";
+import { sp } from "@pnp/sp";
+import "@pnp/sp/lists/web";
+import "@pnp/sp/items/list";
+import { IList } from "@pnp/sp/lists";
+
+describe("Items", () => {
+
+    // any tests that make a web request should be withing a block checking if web tests are enabled
+    if (testSettings.enableWebTests) {
+
+        // a block scoped var we will use across our tests
+        let list: IList = null;
+
+        // we use the before block to setup
+        // executed before all the tests in this block, see the mocha docs for more details
+        // mocha prefers using function vs arrow functions and this is recommended
+        before(async function () {
+
+            // execute a request to ensure we have a list
+            const ler = await sp.web.lists.ensure("ItemTestList", "Used to test item operations");
+            list = ler.list;
+
+            // in this case we want to have some items in the list for testing so we add those
+            // only if the list was just created
+            if (ler.created) {
+
+                // add a few items to get started
+                const batch = sp.web.createBatch();
+                list.items.inBatch(batch).add({ Title: `Item ${getRandomString(4)}` });
+                list.items.inBatch(batch).add({ Title: `Item ${getRandomString(4)}` });
+                list.items.inBatch(batch).add({ Title: `Item ${getRandomString(4)}` });
+                list.items.inBatch(batch).add({ Title: `Item ${getRandomString(4)}` });
+                list.items.inBatch(batch).add({ Title: `Item ${getRandomString(4)}` });
+                await batch.execute();
+            }
+        });
+
+        // this test has a label "get items" and is run via an async function
+        it("get items", async function () {
+
+            // make a request for the list's items
+            const items = await list.items();
+
+            // report that we expect that result to be an array with more than 0 items
+            expect(items.length).to.be.gt(0);
+        });
+
+        // ... remainder of code removed
+    }
+}
+```
+
+## General Guidelines for Writing Tests
+
+- Tests should operate within the site defined in testSettings
+- Tests should be able to run multiple times on the same site, but do not need to cleanup after themselves
+- Each test should be self contained and not depend on other tests, they can depend on work done in before or beforeAll
+- When writing tests you can use "only" and "skip" from mochajs to focus on only the tests you are writing
+- Be sure to review the [various options](./npm-scripts.md#test) when running your tests
+- If you are writing a test and the endpoint doesn't support app only permissions, you can skip writing a test - but please note that in the PR description
+
+## Next Steps
+
+Now that you've written tests to cover your changes you'll need to [update the docs](./documentation.md).