@zxncij2390/monorepo3 3.18.0

package/docs/contributing/settings.md

@@ -0,0 +1,98 @@
+# Project Settings
+
+This article discusses creating a project settings file for use in local development and debugging of the libraries. The settings file contains authentication and other settings to enable you to run and debug the project locally.
+
+The settings file is a JavaScript file that exports a single object representing the settings of your project. You can [view the example settings file in the project root](https://github.com/pnp/pnpjs/blob/main/settings.example.js).
+
+## Settings File Format
+
+The settings file is configured with MSAL authentication for both SharePoint and Graph. For more information coinfiguring MSAL please review the section in the [authentication section for node](../concepts/authentication.md#MSAL-Nodejs).
+
+MSAL configuration has two parts, these are the initialization which is passed directly to the MsalFetchClient (and on to the underlying msal-node instance) and the scopes. The scopes are always "https://{tenant}.sharepoint.com/.default" or "https://graph.microsoft.com/.default" depending on what you are calling.
+
+> If you are calling Microsoft Graph sovereign or gov clouds the scope may need to be updated.
+
+You will need to create testing certs for the sample settings file below. Using the following code you end up with three files, "cert.pem", "key.pem", and "keytmp.pem". The "cert.pem" file is uploaded to your AAD application registration. The "key.pem" is read as the private key for the configuration. Copy the contents of the "key.pem" file and paste it in the `privateKey` variable below. The `gitignore` file in this repository will ignore the settings.js file.
+
+>Replace `HereIsMySuperPass` with your own password
+
+```cmd
+mkdir \temp
+cd \temp
+openssl req -x509 -newkey rsa:2048 -keyout keytmp.pem -out cert.pem -days 365 -passout pass:HereIsMySuperPass -subj '/C=US/ST=Washington/L=Seattle'
+openssl rsa -in keytmp.pem -out key.pem -passin pass:HereIsMySuperPass
+```
+
+```JavaScript
+const privateKey = `-----BEGIN RSA PRIVATE KEY-----
+your private key, read from a file or included here
+-----END RSA PRIVATE KEY-----
+`;
+
+var msalInit = {
+    auth: {
+        authority: "https://login.microsoftonline.com/{tenant id}",
+        clientCertificate: {
+            thumbprint: "{certificate thumbnail}",
+            privateKey: privateKey,
+        },
+        clientId: "{AAD App registration id}",
+    }
+}
+
+export const settings = {
+    testing: {
+        enableWebTests: true,
+        testUser: "i:0#.f|membership|user@consto.com",
+        testGroupId:"{ Microsoft 365 Group ID }",
+        sp: {
+            url: "{required for MSAL - absolute url of test site}",
+            notificationUrl: "{ optional: notification url }",
+            msal: {
+                init: msalInit,
+                scopes: ["https://{tenant}.sharepoint.com/.default"]
+            },
+        },
+        graph: {
+            msal: {
+                init: msalInit,
+                scopes: ["https://graph.microsoft.com/.default"]
+            },
+        },
+    },
+}
+
+```
+
+The settings object has a single sub-object `testing` which contains the configuration used for debugging and testing PnPjs. The parts of this object are described in detail below.
+
+|||
+|--|--|
+|**enableWebTests**|Flag to toggle if tests are run against the live services or not. If this is set to false none of the other sections are required.|
+|**testUser**|AAD login account to be used when running tests.|
+|**testGroupId**|Group ID of Microsoft 365 Group to be used when running test cases.|
+|**sp**|Settings used to configure SharePoint (sp library) debugging and tests|
+|**graph**|Settings used to configure Microsoft Graph (graph library) debugging and tests|
+
+### SP values
+
+|name|description|
+|--|--|
+|**url**|The url of the site to use for all requests. If a site parameter is not specified a child web will be created under the web at this url. See [scripts article](./npm-scripts.md) for more details.
+|**notificationUrl**|Url used when registering test subscriptions
+|**msal**|Information about MSAL authentication setup
+
+### Graph value
+
+The graph values are described in the table below and come from [registering an AAD Application](https://docs.microsoft.com/en-us/graph/auth-register-app-v2). The permissions required by the registered application are dictated by the tests you want to run or resources you wish to test against.
+
+|name|description|
+|--|--|
+|**msal**|Information about MSAL authentication setup
+
+## Create Settings.js file
+
+1. Copy the example file and rename it settings.js. Place the file in the root of your project.
+2. Update the settings as needed for your environment.
+
+> If you are only doing SharePoint testing you can leave the graph section off and vice-versa. Also, if you are not testing anything with hooks you can leave off the notificationUrl.

package/docs/contributing/setup-dev-machine.md

@@ -0,0 +1,36 @@
+# Setting up your Developer Machine
+
+If you are a longtime client side developer you likely have your machine already configured and can skip to [forking the repo](#fork-the-repo) and [debugging](./debugging.md).
+
+## Setup your development environment
+
+These steps will help you get your environment setup for contributing to the core library.
+
+1. Install [Visual Studio Code](https://code.visualstudio.com/) - this is the development environment we use so the contribution sections expect you are as well. If you prefer you can use Visual Studio or any editor you like.
+
+1. Install [Node JS](https://nodejs.org/en/download/) - this provides two key capabilities; the first is the nodejs server which will act as our development server (think iisexpress), the second is npm a package manager (think nuget).
+
+    > This library requires node >= 10.18.0
+
+1. On Windows: Install [Python](https://www.python.org/downloads)
+
+1. [Optional] Install the tslint extension in VS Code:
+
+    1. Press Shift + Ctrl + "p" to open the command panel
+    2. Begin typing "install extension" and select the command when it appears in view
+    3. Begin typing "tslint" and select the package when it appears in view
+    4. Restart Code after installation
+
+## Fork The Repo
+
+All of our contributions come via [pull requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) and you'll need to fork the repository
+
+1. Now we need to fork and clone the git repository. This can be done using your [console](https://help.github.com/articles/fork-a-repo/) or using your preferred Git GUI tool.
+
+1. Once you have the code locally, navigate to the root of the project in your console. Type the following command:
+
+     `npm install`
+
+1. Follow the [guidance to complete the one-time local configuration](./local-debug-configuration.md) required to debug and run tests.
+
+1. Then you can follow the guidance in the [debugging](./debugging.md) article.

package/docs/core/behavior-recipes.md

@@ -0,0 +1,199 @@
+# Behavior Recipes
+
+This article contains example recipes for building your own behaviors. We don't want to include every possible behavior within the library, but do want folks to have easy ways to solve the problems they encounter. If have ideas for a missing recipe, please let us know in the [issues list](https://github.com/pnp/pnpjs/issues) OR submit them to this page as a PR! We want to see what types of behaviors folks build and will evaluate options to either include them in the main libraries, leave them here as a reference resource, or possibly release a community behaviors package.
+
+> Alternatively we encourage you to publish your own behaviors as npm packages to share with others!
+
+## Proxy
+
+At times you might need to introduce a proxy for requests for debugging or other networking needs. You can easily do so using your proxy of choice in Nodejs. This example uses "https-proxy-agent" but would work similarly for any implementation. 
+
+_proxy.ts_
+```TypeScript
+import { TimelinePipe } from "@pnp/core";
+import { Queryable } from "@pnp/queryable";
+import { HttpsProxyAgent } from "https-proxy-agent";
+
+export function Proxy(proxyInit: string): TimelinePipe<Queryable>;
+// eslint-disable-next-line no-redeclare
+export function Proxy(proxyInit: any): TimelinePipe<Queryable>;
+// eslint-disable-next-line no-redeclare
+export function Proxy(proxyInit: any): TimelinePipe<Queryable> {
+
+    const proxy = typeof proxyInit === "string" ? new HttpsProxyAgent(proxyInit) : proxyInit;
+
+    return (instance: Queryable) => {
+
+        instance.on.pre(async (url, init, result) => {
+
+            // we add the proxy to the request
+            (<any>init).agent = proxy;
+
+            return [url, init, result];
+        });
+
+        return instance;
+    };
+}
+```
+
+_usage_
+```TypeScript
+import { Proxy } from "./proxy.ts";
+
+import "@pnp/sp/webs";
+import { SPDefault } from "@pnp/nodejs";
+
+// would work with graph library in the same manner
+const sp = spfi("https://tenant.sharepoint.com/sites.dev").using(SPDefault({
+    msal: {
+        config: { config },
+        scopes: {scopes },
+    },
+}), Proxy("http://127.0.0.1:8888"));
+
+const webInfo = await sp.webs();
+```
+
+## Add QueryString to bypass request caching
+
+In some instances users express a desire to append something to the querystring to avoid getting cached responses back for requests. This pattern is an example of doing that in v3.
+
+_query-cache-param.ts_
+```TypeScript
+export function CacheBust(): TimelinePipe<Queryable> {
+
+    return (instance: Queryable) => {
+
+        instance.on.pre(async (url, init, result) => {
+
+            url += url.indexOf("?") > -1 ? "&" : "?";
+
+            url += "nonce=" + encodeURIComponent(new Date().toISOString());
+
+            return [url, init, result];
+        });
+
+        return instance;
+    };
+}
+```
+
+_usage_
+```TypeScript
+import { CacheBust } from "./query-cache-param.ts";
+
+import "@pnp/sp/webs";
+import { SPDefault } from "@pnp/nodejs";
+
+// would work with graph library in the same manner
+const sp = spfi("https://tenant.sharepoint.com/sites.dev").using(SPDefault({
+    msal: {
+        config: { config },
+        scopes: { scopes },
+    },
+}), CacheBust());
+
+const webInfo = await sp.webs();
+```
+
+## ACS Authentication
+
+Starting with v3 we no longer provide support for ACS authentication within the library. However you may have a need (legacy applications, on-premises) to use ACS authentication while wanting to migrate to v3. Below you can find an example implementation of an Authentication observer for ACS. This is not a 100% full implementation, for example the tokens are not cached.
+
+> Whenever possible we encourage you to use AAD authentication and move away from ACS for securing your server-side applications.
+
+```Typescript
+export function ACS(clientId: string, clientSecret: string, authUrl = "https://accounts.accesscontrol.windows.net"): (instance: Queryable) => Queryable {
+
+  const SharePointServicePrincipal = "00000003-0000-0ff1-ce00-000000000000";
+
+  async function getRealm(siteUrl: string): Promise<string> {
+
+    const url = combine(siteUrl, "_vti_bin/client.svc");
+
+    const r = await nodeFetch(url, {
+      "headers": {
+        "Authorization": "Bearer ",
+      },
+      "method": "POST",
+    });
+
+    const data: string = r.headers.get("www-authenticate") || "";
+    const index = data.indexOf("Bearer realm=\"");
+    return data.substring(index + 14, index + 50);
+  }
+
+  function getFormattedPrincipal(principalName: string, hostName: string, realm: string): string {
+    let resource = principalName;
+    if (hostName !== null && hostName !== "") {
+      resource += "/" + hostName;
+    }
+    resource += "@" + realm;
+    return resource;
+  }
+
+  async function getFullAuthUrl(realm: string): Promise<string> {
+
+    const url = combine(authUrl, `/metadata/json/1?realm=${realm}`);
+
+    const r = await nodeFetch(url, { method: "GET" });
+    const json: { endpoints: { protocol: string; location: string }[] } = await r.json();
+
+    const eps = json.endpoints.filter(ep => ep.protocol === "OAuth2");
+    if (eps.length > 0) {
+      return eps[0].location;
+    }
+
+    throw Error("Auth URL Endpoint could not be determined from data.");
+  }
+
+  return (instance: Queryable) => {
+
+    instance.on.auth.replace(async (url: URL, init: RequestInit) => {
+
+      const realm = await getRealm(url.toString());
+      const fullAuthUrl = await getFullAuthUrl(realm);
+
+      const resource = getFormattedPrincipal(SharePointServicePrincipal, url.host, realm);
+      const formattedClientId = getFormattedPrincipal(clientId, "", realm);
+
+      const body: string[] = [];
+      body.push("grant_type=client_credentials");
+      body.push(`client_id=${formattedClientId}`);
+      body.push(`client_secret=${encodeURIComponent(clientSecret)}`);
+      body.push(`resource=${resource}`);
+
+      const r = await nodeFetch(fullAuthUrl, {
+        body: body.join("&"),
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+        },
+        method: "POST",
+      });
+
+      const accessToken: { access_token: string } = await r.json();
+
+      init.headers = { ...init.headers, Authorization: `Bearer ${accessToken.access_token}` };
+
+      return [url, init];
+    });
+
+    return instance;
+  };
+}
+```
+
+_usage_
+```Typescript
+import { CacheBust } from "./acs-auth-behavior.ts";
+import "@pnp/sp/webs";
+import { SPDefault } from "@pnp/nodejs";
+
+const sp = spfi("https://tenant.sharepoint.com/sites.dev").using(SPDefault(), ACS("{client id}", "{client secret}"));
+
+// you can optionally provide the authentication url, here using the one for China's sovereign cloud or an local url if working on-premises
+// const sp = spfi("https://tenant.sharepoint.com/sites.dev").using(SPDefault(), ACS("{client id}", "{client secret}", "https://accounts.accesscontrol.chinacloudapi.cn"));
+
+const webInfo = await sp.webs();
+```

package/docs/core/behaviors.md

@@ -0,0 +1,179 @@
+# @pnp/core : behaviors
+
+While you can always register observers to any Timeline's moments using the `.on.moment` syntax, to make things easier we have included the ability to create behaviors. Behaviors define one or more observer registrations abstracted into a single registration. To differentiate behaviors are applied with the `.using` method. The power of behaviors is they are composable so a behavior can apply other behaviors.
+
+## Basic Example
+
+Let's create a behavior that will register two observers to a Timeline. We'll use error and log since they exist on all Timelines. In this example let's imagine we need to include some special secret into every lifecycle for logging to work. And we also want a company wide method to track errors. So we roll our own behavior.
+
+```TypeScript
+import { Timeline, TimelinePipe } from "@pnp/core";
+import { MySpecialLoggingFunction } from "../mylogging.js";
+
+// top level function allows binding of values within the closure
+export function MyBehavior(specialSecret: string): TimelinePipe {
+
+    // returns the actual behavior function that is applied to the instance
+    return (instance: Timeline<any>) => {
+
+        // register as many observers as needed
+        instance.on.log(function (message: string, severity: number) {
+
+            MySpecialLoggingFunction(message, severity, specialSecret);
+        });
+
+        instance.on.error(function (err: string | Error) {
+
+            MySpecialLoggingFunction(typeof err === "string" ? err : err.toString(), severity, specialSecret);
+        });
+
+        return instance;
+    };
+}
+
+// apply the behavior to a Timeline/Queryable
+obj.using(MyBehavior("HereIsMySuperSecretValue"));
+```
+
+## Composing Behaviors
+
+We encourage you to use our defaults, or create your own default behavior appropriate to your needs. You can see all of the behaviors available in [@pnp/nodejs](../nodejs/behaviors.md), [@pnp/queryable](../queryable/behaviors.md), [@pnp/sp](../sp/behaviors.md), and [@pnp/graph](../graph/behaviors.md).
+
+As an example, let's create our own behavior for a nodejs project. We want to call the graph, default to the beta endpoint, setup MSAL, and include a custom header we need for our environment. To do so we create a composed behavior consisting of graph's DefaultInit, graph's DefaultHeaders, nodejs's MSAL, nodejs's NodeFetchWithRetry, and queryable's DefaultParse & InjectHeaders. Then we can import this behavior into all our projects to configure them.
+
+_company-default.ts_
+```TypeScript
+import { TimelinePipe } from "@pnp/core";
+import { DefaultParse, Queryable, InjectHeaders } from "@pnp/queryable";
+import { DefaultHeaders, DefaultInit } from "@pnp/graph";
+import { NodeFetchWithRetry, MSAL } from "@pnp/nodejs";
+
+export function CompanyDefault(): TimelinePipe<Queryable> {
+
+    return (instance: Queryable) => {
+
+        instance.using(
+            // use the default headers
+            DefaultHeaders(),
+            // use the default init, but change the base url to beta
+            DefaultInit("https://graph.microsoft.com/beta"),
+            // use node-fetch with retry
+            NodeFetchWithRetry(),
+            // use the default parsing
+            DefaultParse(),
+            // inject our special header to all requests
+            InjectHeaders({
+                "X-SomeSpecialToken": "{THE SPECIAL TOKEN VALUE}",
+            }),
+            // setup node's MSAL with configuration from the environment (or any source)
+            MSAL(process.env.MSAL_CONFIG));
+
+        return instance;
+    };
+}
+```
+
+_index.ts_
+```TypeScript
+import { CompanyDefault } from "./company-default.ts";
+import { graphfi } from "@pnp/graph";
+
+// we can consistently and easily setup our graph instance using a single behavior
+const graph = graphfi().using(CompanyDefault());
+```
+
+> You can easily share your composed behaviors across your projects using [library components in SPFx](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/library-component-overview), a company CDN, or an npm package.
+
+[](#assignfrom)
+
+## Core Behaviors
+
+This section describes two behaviors provided by the `@pnp/core` library, AssignFrom and CopyFrom. Likely you won't often need them directly - they are used in some places internally - but they are made available should they prove useful.
+
+### AssignFrom
+
+This behavior creates a ref to the supplied Timeline implementation's observers and resets the inheriting flag. This means that changes to the parent, here being the supplied Timeline, will begin affecting the target to which this behavior is applied.
+
+```TypeScript
+import { spfi, SPBrowser } from "@pnp/sp";
+import "@pnp/sp/webs";
+import { AssignFrom } from "@pnp/core";
+// some local project file
+import { MyCustomeBehavior } from "./behaviors.ts";
+
+const source = spfi().using(SPBrowser());
+
+const target = spfi().using(MyCustomeBehavior());
+
+// target will now hold a reference to the observers contained in source
+// changes to the subscribed observers in source will apply to target
+// anything that was added by "MyCustomeBehavior" will no longer be present
+target.using(AssignFrom(source.web));
+
+// you can always apply additional behaviors or register directly on the events
+// but once you modify target it will not longer ref source and changes to source will no longer apply
+target.using(SomeOtherBehavior());
+target.on.log(console.log);
+```
+
+### CopyFrom
+
+Similar to AssignFrom, this method creates a copy of all the observers on the source and applies them to the target. This can be done either as a `replace` or `append` operation using the second parameter. The default is "append".
+
+- "replace" will first clear each source moment's registered observers then apply each in source-order via the `on` operation.
+- "append" will apply each source moment's registered observers in source-order via the `on` operation
+
+> By design CopyFrom does NOT include moments defined by symbol keys.
+
+```TypeScript
+import { spfi, SPBrowser } from "@pnp/sp";
+import "@pnp/sp/webs";
+import { CopyFrom } from "@pnp/core";
+// some local project file
+import { MyCustomeBehavior } from "./behaviors.ts";
+
+const source = spfi().using(SPBrowser());
+
+const target = spfi().using(MyCustomeBehavior());
+
+// target will have the observers copied from source, but no reference to source. Changes to source's registered observers will not affect target.
+// any previously registered observers in target are maintained as the default behavior is to append
+target.using(CopyFrom(source.web));
+
+// target will have the observers copied from source, but no reference to source. Changes to source's registered observers will not affect target.
+// any previously registered observers in target are removed
+target.using(CopyFrom(source.web, "replace"));
+
+// you can always apply additional behaviors or register directly on the events
+// with CopyFrom no reference to source is maintained
+target.using(SomeOtherBehavior());
+target.on.log(console.log);
+```
+
+As well `CopyFrom` supports a filter parameter if you only want to copy the observers from a subset of moments. This filter is a predicate function taking a single string key and returning true if the observers from that moment should be copied to the target.
+
+```TypeScript
+import { spfi, SPBrowser } from "@pnp/sp";
+import "@pnp/sp/webs";
+import { CopyFrom } from "@pnp/core";
+// some local project file
+import { MyCustomeBehavior } from "./behaviors.ts";
+
+const source = spfi().using(SPBrowser());
+
+const target = spfi().using(MyCustomeBehavior());
+
+// target will have the observers copied from source, but no reference to source. Changes to source's registered observers will not affect target.
+// any previously registered observers in target are maintained as the default behavior is to append
+target.using(CopyFrom(source.web));
+
+// target will have the observers `auth` and `send` copied from source, but no reference to source. Changes to source's registered observers will not affect target.
+// any previously registered observers in target are removed
+target.using(CopyFrom(source.web, "replace", (k) => /(auth|send)/i.test(k)));
+
+// you can always apply additional behaviors or register directly on the events
+// with CopyFrom no reference to source is maintained
+target.using(SomeOtherBehavior());
+target.on.log(console.log);
+```
+