@zxncij2390/monorepo3 3.18.0

package/docs/contributing/debugging.md

@@ -0,0 +1,135 @@
+# Debugging
+
+Using the steps in this article you will be able to locally debug the library internals as well as new features you are working on.
+
+Before proceeding be sure you have reviewed how to [setup for local configuration](./local-debug-configuration.md) and debugging.
+
+## Debugging Library Features
+
+The easiest way to debug the library when working on new features is using F5 in Visual Studio Code. This uses [launch.json](https://github.com/pnp/pnpjs/blob/main/.vscode/launch.json) to build and run the library using [./debug/launch/main.ts](https://github.com/pnp/pnpjs/blob/main/debug/launch/main.ts) as the entry point.
+
+### Basic SharePoint Testing
+
+You can start the base debugging case by hitting F5. Before you do place a break point in ./debug/launch/sp.ts. You can also place a break point within any of the libraries or modules. Feel free to edit the sp.ts file to try things out, debug suspected issues, or test new features, etc - but please don't commit any changes as this is a shared file. See [the section on creating your own debug modules](#how-to-create-a-debug-module).
+
+All of the setup for the node client is handled within sp.ts using the [settings from the local configuration](./local-debug-configuration.md).
+
+### Basic Graph Testing
+
+Testing and debugging Graph calls follows the same process as outlined for SharePoint, however you need to update main.ts to import graph instead of sp. You can place break points anywhere within the library code and they should be hit.
+
+All of the setup for the node client is handled within graph.ts using the [settings from the local configuration](./local-debug-configuration.md).
+
+## How to: Create a Debug Module
+
+If you are working on multiple features or want to save sample code for various tasks you can create your own debugging modules and leave them in the debug/launch folder locally. The gitignore file is setup to ignore any files that aren't already in git.
+
+Using [./debug/launch/sp.ts](https://github.com/pnp/pnpjs/blob/main/debug/launch/sp.ts) as a reference create a file in the debug/launch folder, let's call it mydebug.ts and add this content:
+
+```TypeScript
+// note we can use the actual package names for our imports (ex: @pnp/logging)
+import { Logger, LogLevel, ConsoleListener } from "@pnp/logging";
+// using the all preset for simplicity in the example, selective imports work as expected
+import { sp, ListEnsureResult } from "@pnp/sp/presets/all";
+
+declare var process: { exit(code?: number): void };
+
+export async function MyDebug() {
+
+  // configure your options
+  // you can have different configs in different modules as needed for your testing/dev work
+  sp.setup({
+    sp: {
+      fetchClientFactory: () => {
+        return new SPFetchClient(settings.testing.sp.url, settings.testing.sp.id, settings.testing.sp.secret);
+      },
+    },
+  });
+
+  // run some debugging
+  const list = await sp.web.lists.ensure("MyFirstList");
+
+  Logger.log({
+    data: list.created,
+    level: LogLevel.Info,
+    message: "Was list created?",
+  });
+
+  if (list.created) {
+
+    Logger.log({
+      data: list.data,
+      level: LogLevel.Info,
+      message: "Raw data from list creation.",
+    });
+
+  } else {
+
+    Logger.log({
+      data: null,
+      level: LogLevel.Info,
+      message: "List already existed!",
+    });
+  }
+
+  process.exit(0);
+}
+```
+
+### Update main.ts to launch your module
+
+First comment out the import for the default example and then add the import and function call for yours, the updated launch/main.ts should look like this:
+
+```TypeScript
+// ...
+
+// comment out the example
+// import { Example } from "./example";
+// Example();
+
+import { MyDebug } from "./mydebug"
+MyDebug();
+
+// ...
+```
+
+> Remember, please don't commit any changes to the shared files within the debug folder. (Unless you've found a bug that needs fixing in the original file)
+
+### Debug
+
+Place a break point within the mydebug.ts file and hit F5. Your module should run and your break point hit. You can then examine the contents of the objects and see the run time state. Remember, you can also set breakpoints within the package src folders to see exactly how things are working during your debugging scenarios.
+
+### Debug Module Next Steps
+
+Using this pattern you can create and preserve multiple debugging scenarios in separate modules locally - they won't be added to git. You just have to update main.ts to point to the one you want to run.
+
+## In Browser Debugging
+
+You can also serve files locally to debug as a user in the browser by serving code using ./debug/serve/main.ts as the entry. The file is served as `https://localhost:8080/assets/pnp.js`, allowing you to create a single page in your tenant for in browser testing. The remainder of this section describes the process to setup a SharePoint page to debug in this manner.
+
+### Start the local serve
+
+This will serve a package with ./debug/serve/main.ts as the entry.
+
+`npm run serve`
+
+### Add reference to library
+
+Within a SharePoint page add a script editor web part and then paste in the following code. The div is to give you a place to target with visual updates should you desire.
+
+```HTML
+<script src="https://localhost:8080/assets/pnp.js"></script>
+<div id="pnp-test"></div>
+```
+
+You should see an alert with the current web's title using the default main.ts. Feel free to update main.ts to do whatever you would like, but remember not to commit changes to the shared files.
+
+### Debug
+
+Refresh the page and open the developer tools in your browser of choice. If the pnp.js file is blocked due to security restrictions you will need to allow it.
+
+### Next Steps
+
+You can make changes to the library and immediately see them reflected in the browser. All files are watched so changes will be available as soon as webpack reloads the package. This allows you to rapidly test the library in the browser.
+
+Now you can learn about [extending the library](./extending-the-library.md).

package/docs/contributing/documentation.md

@@ -0,0 +1,34 @@
+# Documentation
+
+Just like with tests we have invested much time in updating the documentation and when you make a change to the library you should update the associated documentation as part of the pull request.
+
+## Writing Docs
+
+Our docs are all written in markdown and processed using MkDocs. You can use code blocks, tables, and other markdown formatting. You can review the other articles for examples on writing docs. Generally articles should focus on how to use the library and where appropriate link to official outside documents as needed. Official documentation could be Microsoft, other library project docs such as MkDocs, or other sources.
+
+## Building Docs Locally
+
+Building the documentation locally can help you visualize change you are making to the docs. What you see locally will be what you see online. Documentation is built using MkDocs. You will need to latest version of Python (tested on version 3.7.1) and pip. If you're on the Windows operating system, make sure you have added Python to your [Path environment variable](https://docs.python.org/3/using/windows.html).
+
+When executing the pip module on Windows you can prefix it with **python -m**.
+For example:
+
+`python -m pip install mkdocs-material`
+
+- [Install MkDocs](https://www.mkdocs.org/#installation)
+    - pip install mkdocs
+- Install the Material theme
+    - pip install mkdocs-material
+- install the mkdocs-markdownextradata-plugin - this is used for the version variable
+    - pip install mkdocs-markdownextradata-plugin (doesn't work on Python v2.7)
+- install redirect plugin - used to redirect from moved pages
+    - pip install mkdocs-redirects
+- Serve it up
+    - `mkdocs serve`
+    - Open a browser to `http://127.0.0.1:8000/`
+
+> Please see the [official mkdocs site](https://www.mkdocs.org/) for more details on working with mkdocs
+
+## Next Steps
+
+After your changes are made, you've added/updated tests, and updated the docs you're ready to [submit a pull request](./pull-requests.md)!

package/docs/contributing/extending-the-library.md

@@ -0,0 +1,223 @@
+# Extending PnPjs
+
+> This article is targeted at people wishing to extend PnPjs itself, usually by adding a method or property.
+
+At the most basic level PnPjs is a set of libraries used to build and execute a web request and handle the response from that request. Conceptually each object in the fluent chain serves as input when creating the next object in the chain. This is how configuration, url, query, and other values are passed along. To get a sense for what this looks like see the code below. This is taken from inside the [webs submodule](https://github.com/pnp/pnpjs/blob/version-2/packages/sp/webs/types.ts#L77) and shows how the "webs" property is added to the web class.
+
+```TypeScript
+// TypeScript property, returning an interface
+public get webs(): IWebs {
+    // using the Webs factory function and providing "this" as the first parameter
+    return Webs(this);
+}
+```
+
+## Understanding Factory Functions
+
+PnPjs v3 is designed to only expose interfaces and factory functions. Let's look at the Webs factory function, used above as an example. All factory functions in sp and graph have a similar form.
+
+```TypeScript
+// create a constant which is a function of type ISPInvokableFactory having the name Webs
+// this is bound by the generic type param to return an IWebs instance
+// and it will use the _Webs concrete class to form the internal type of the invocable
+export const Webs = spInvokableFactory<IWebs>(_Webs);
+```
+
+The ISPInvokableFactory type looks like:
+
+```TypeScript
+export type ISPInvokableFactory<R = any> = (baseUrl: string | ISharePointQueryable, path?: string) => R;
+```
+
+And the matching graph type:
+
+```TypeScript
+<R>(f: any): (baseUrl: string | IGraphQueryable, path?: string) => R
+```
+
+The general idea of a factory function is that it takes two parameters. The first is either a string or Queryable derivative which forms base for the new object. The second is the next part of the url. In some cases (like the webs property example above) you will note there is no second parameter. Some classes are decorated with defaultPath, which automatically fills the second param. Don't worry too much right now about the deep internals of the library, let's instead focus on some concrete examples.
+
+```TypeScript
+import { SPFx } from "@pnp/sp";
+import { Web } from "@pnp/sp/webs";
+
+// create a web from an absolute url
+const web = Web("https://tenant.sharepoint.com").using(SPFx(this.context));
+
+// as an example, create a new web using the first as a base
+// targets: https://tenant.sharepoint.com/sites/dev
+const web2 = Web(web, "sites/dev");
+
+// or you can add any path components you want, here as an example we access the current user property
+const cu = Web(web, "currentuser");
+const currentUserInfo = cu();
+```
+
+Now hey you might say - you can't create a request to current user using the Web factory. Well you can, since everything is just based on urls under the covers the actual factory names don't mean anything other than they have the appropriate properties and method hung off them. This is brought up as you will see in many cases objects being used to create queries _within_ methods and properties that don't match their "type". It is an important concept when working with the library to always remember we are just building strings.
+
+## Class structure
+
+Internally to the library we have a bit of complexity to make the whole invocable proxy architecture work and provide the typings folks expect. Here is an example implementation with extra comments explaining what is happening. You don't need to understand the entire stack to [add a property](#add-a-property) or [method](#add-a-method)
+
+```TypeScript
+/*
+The concrete class implementation. This is never exported or shown directly
+to consumers of the library. It is wrapped by the Proxy we do expose.
+
+It extends the _SharePointQueryableInstance class for which there is a matching
+_SharePointQueryableCollection. The generic parameter defines the return type
+of a get operation and the invoked result.
+
+Classes can have methods and properties as normal. This one has a single property as a simple example
+*/
+export class _HubSite extends _SharePointQueryableInstance<IHubSiteInfo> {
+
+    /**
+     * Gets the ISite instance associated with this hub site
+     */
+    // the tag decorator is used to provide some additional telemetry on what methods are
+    // being called.
+    @tag("hs.getSite")
+    public async getSite(): Promise<ISite> {
+
+        // we execute a request using this instance, selecting the SiteUrl property, and invoking it immediately and awaiting the result
+        const d = await this.select("SiteUrl")();
+
+        // we then return a new ISite instance created from the Site factory using the returned SiteUrl property as the baseUrl
+        return Site(d.SiteUrl);
+    }
+}
+
+/*
+This defines the interface we export and expose to consumers.
+In most cases this extends the concrete object but may add or remove some methods/properties
+in special cases
+*/
+export interface IHubSite extends _HubSite { }
+
+/*
+This defines the HubSite factory function as discussed above
+binding the spInvokableFactory to a generic param of IHubSite and a param of _HubSite.
+
+This is understood to mean that HubSite is a factory function that returns a types of IHubSite
+which the spInvokableFactory will create using _HubSite as the concrete underlying type.
+*/
+export const HubSite = spInvokableFactory<IHubSite>(_HubSite);
+```
+
+## Add a Property
+
+In most cases you won't need to create the class, interface, or factory - you just want to add a property or method. An example of this is sp.web.lists. web is a property of sp and lists is a property of web. You can have a look at those classes as examples. Let's have a look at the fields on the _View class.
+
+```TypeScript
+export class _View extends _SharePointQueryableInstance<IViewInfo> {
+
+    // ... other code removed
+ 
+    // add the property, and provide a return type
+    // return types should be interfaces
+    public get fields(): IViewFields {
+        // we use the ViewFields factory function supplying "this" as the first parameter
+        // this will create a url like ".../fields/viewfields" due to the defaultPath decorator
+        // on the _ViewFields class. This is equivalent to: ViewFields(this, "viewfields")
+        return ViewFields(this);
+    }
+
+    // ... other code removed
+}
+```
+
+> There are many examples throughout the library that follow this pattern.
+
+## Add a Method
+
+Adding a method is just like adding a property with the key difference that a method usually _does_ something like make a web request or act like a property but take parameters. Let's look at the _Items getById method:
+
+```TypeScript
+@defaultPath("items")
+export class _Items extends _SharePointQueryableCollection {
+
+    /**
+    * Gets an Item by id
+    *
+    * @param id The integer id of the item to retrieve
+    */
+    // we declare a method and set the return type to an interface
+    public getById(id: number): IItem {
+        // here we use the tag helper to add some telemetry to our request
+        // we create a new IItem using the factory and appending the id value to the end
+        // this gives us a valid url path to a single item .../items/getById(2)
+        // we can then use the returned IItem to extend our chain or execute a request
+        return tag.configure(Item(this).concat(`(${id})`), "is.getById");
+    }
+
+    // ... other code removed
+}
+```
+
+### Web Request Method
+
+A second example is a method that performs a request. Here we use the _Item recycle method as an example:
+
+```TypeScript
+/**
+ * Moves the list item to the Recycle Bin and returns the identifier of the new Recycle Bin item.
+ */
+// we use the tag decorator to add telemetry
+@tag("i.recycle")
+// we return a promise
+public recycle(): Promise<string> {
+    // we use the spPost method to post the request created by cloning our current instance IItem using
+    // the Item factory and adding the path "recycle" to the end. Url will look like .../items/getById(2)/recycle
+    return spPost<string>(Item(this, "recycle"));
+}
+```
+
+## Augment Using Selective Imports
+
+To understand is how to extend functionality within the selective imports structures look at [list.ts](https://github.com/pnp/pnpjs/blob/main/packages/sp/items/list.ts) file in the items submodule. Here you can see the code below, with extra comments to explain what is happening. Again, you will see this pattern repeated throughout the library so there are many examples available.
+
+```TypeScript
+// import the addProp helper
+import { addProp } from "@pnp/queryable";
+// import the _List concrete class from the types module (not the index!)
+import { _List } from "../lists/types";
+// import the interface and factory we are going to add to the List
+import { Items, IItems } from "./types";
+
+// This module declaration fixes up the types, allowing .items to appear in intellisense
+// when you import "@pnp/sp/items/list";
+declare module "../lists/types" {
+    // we need to extend the concrete type
+    interface _List {
+        readonly items: IItems;
+    }
+    // we need to extend the interface
+    // this may not be strictly necessary as the IList interface extends _List so it
+    // should pick up the same additions, but we have seen in some cases this does seem
+    // to be required. So we include it for safety as it will all be removed during
+    // transpilation we don't need to care about the extra code
+    interface IList {
+        readonly items: IItems;
+    }
+}
+
+// finally we add the property to the _List class
+// this method call says add a property to _List named "items" and that property returns a result using the Items factory
+// The factory will be called with "this" when the property is accessed. If needed there is a fourth parameter to append additional path
+// information to the property url
+addProp(_List, "items", Items);
+```
+
+## General Rules for Extending PnPjs
+
+- Only expose interfaces to consumers
+- Use the factory functions except in very special cases
+- Look for other properties and methods as examples
+- Simple is always preferable, but not always possible - use your best judgement
+- If you find yourself writing a ton of code to solve a problem you think should be easy, ask
+- If you find yourself deep within the core classes or odata library trying to make a change, ask - changes to the core classes are rarely needed
+
+## Next Steps
+
+Now that you have extended the library you need to [write a test](./debug-tests.md) to cover it!

package/docs/contributing/index.md

@@ -0,0 +1,22 @@
+# Contributing to PnPjs
+
+Thank you for your interest in contributing to PnPjs. We have updated our contribution section to make things easier to get started, debug the library locally, and learn how to extend the functionality.
+
+|Section|Description|
+|---|---|
+|[NPM Scripts](./npm-scripts.md)|Explains the npm scripts and their uses|
+|[Setup Dev Machine](./setup-dev-machine.md)|Covers setting up your machine to ensure you are ready to debug the solution|
+|[Local Debug Configuration](./local-debug-configuration.md)|Discusses the steps required to establish local configuration used for debugging and running tests|
+|[Debugging](./debugging.md)|Describes how to debug PnPjs locally
+|[Extending the library](./extending-the-library.md)|Basic examples on how to extend the library such as adding a method or property
+|[Writing Tests](./debug-tests.md)|How to write and debug tests|
+|[Update Documentation](./documentation.md)|Describes the steps required to edit and locally view the documentation|
+|[Submit a Pull Request](./pull-requests.md)|Outlines guidance for submitting a pull request|
+
+## Need Help?
+
+The PnP "Sharing Is Caring" initiative teaches the basics around making changes in GitHub, submitting pull requests to the PnP & Microsoft 365 open-source repositories such as PnPjs. 
+
+Every month, we provide multiple live hands-on sessions that walk attendees through the process of using and contributing to PnP initiatives.
+
+To learn more and register for an upcoming session, please visit the [Sharing is Caring](https://aka.ms/sharing-is-caring) website.

package/docs/contributing/local-debug-configuration.md

@@ -0,0 +1,28 @@
+# Local Debugging Configuration
+
+This article covers the local setup required to debug the library and run tests. This only needs to be done once (unless you update the app registrations, then you just need to update the settings.js file accordingly).
+
+## Create settings.js
+
+Both local debugging and tests make use of a settings.js file located in the root of the project. Ensure you create a settings.js files by copying settings.example.js and renaming it to settings.js.
+For more information the settings file please see [`Settings`](./settings.md)
+
+### Minimal Configuration
+
+You can control which tests are run by including or omitting sp and graph sections. If sp is present and graph is not, only sp tests are run. Include both and all tests are run, respecting the enableWebTests flag.
+
+The following configuration file allows you to run all the tests that do not contact services.
+
+```js
+ var sets = {
+     testing: {
+         enableWebTests: false,
+     }
+ }
+
+module.exports = sets;
+```
+
+## Test your setup
+
+If you hit F5 in VSCode now you should be able to see the full response from getting the web's title in the internal console window. If not, ensure that you have properly updated the settings file and registered the add-in perms correctly.

package/docs/contributing/npm-scripts.md

@@ -0,0 +1,148 @@
+# Supported NPM Scripts
+
+As you likely are aware you can embed scripts within package.json. Using this capability coupled with the knowledge that pretty much all of the tools we use now support code files (.js/.ts) as configuration we have removed gulp from our tooling and now execute our various actions via scripts. This is not a knock on gulp, it remains a great tool, rather an opportunity for us to remove some dependencies.
+
+This article outlines the current scripts we've implemented and how to use them, with available options and examples.
+
+## Start
+
+Executes the `serve` command
+
+```cmd
+npm start
+```
+
+## Serve
+
+Starts a debugging server serving a bundled script with ./debug/serve/main.ts as the entry point. This allows you to run tests and debug code running within the context of a webpage rather than node.
+
+```cmd
+npm run serve
+```
+
+## Test
+
+Runs the tests and coverage for the library.
+
+[More details on setting up MSAL for node.](https://pnp.github.io/pnpjs/getting-started/#getting-started-with-nodejs)
+
+### Options
+
+There are several options you can provide to the test command. All of these need to be separated using a "--" double hyphen so they are passed to the spawned sub-commands.
+
+#### Test a Single Package
+
+>`--package` or `-p`
+
+This option will only run the tests associated with the package you specify. The values are the folder names within the ./packages directory.
+
+```cmd
+# run only sp tests
+npm test -- -p sp
+
+# run only logging tests
+npm test -- -package logging
+```
+
+#### Run a Single Test File
+
+>`--single` or `--s`
+
+You can also run a specific file with a package. This option _must_ be used with the single package option as you are essentially specifying the folder and file. This option uses either the  flags.
+
+```cmd
+# run only sp web tests
+npm test -- -p sp -s web
+
+# run only graph groups tests
+npm test -- -package graph -single groups
+```
+
+#### Specify a Site
+
+>`--site`
+
+By default every time you run the tests a new sub-site is created below the site specified in your [settings file](./settings.md). You can choose to reuse a site for testing, which saves time when re-running a set of tests frequently. Testing content is not deleted after tests, so if you need to inspect the created content from testing you may wish to forgo this option.
+
+This option can be used with any or none of the other testing options.
+
+```cmd
+# run only sp web tests with a certain site
+npm test -- -p sp -s web --site https://some.site.com/sites/dev
+```
+
+#### Cleanup
+
+>`--cleanup`
+
+If you include this flag the testing web will be deleted once tests are complete. Useful for local testing where you do not need to inspect the web once the tests are complete. Works with any of the other options, be careful when specifying a web using `--site` as it will be deleted.
+
+```cmd
+# clean up our testing site
+npm test -- --cleanup
+```
+
+#### Logging
+
+>`--logging`
+
+If you include this flag a console logger will be subscribed and the log level will be set to Info. This will provide console output for all the requests being made during testing. This flag is compatible with all other flags - however unless you are trying to debug a specific test this will produce a lot of chatty output.
+
+```cmd
+# enable logging during testing
+npm test -- --logging
+```
+
+You can also optionally set a log level of error, warning, info, or verbose:
+
+```cmd
+# enable logging during testing in verbose (lots of info)
+npm test -- --logging verbose
+```
+
+```cmd
+# enable logging during testing in error
+npm test -- --logging error
+```
+
+#### spVerbose
+
+>`--spverbose`
+
+This flag will enable "verbose" OData mode for SharePoint tests. This flag is compatible with other flags.
+
+```cmd
+npm test -- --spverbose
+```
+
+## build
+
+Invokes the pnpbuild cli to transpile the TypeScript into JavaScript. All behavior is controlled via the tsconfig.json in the root of the project and sub folders as needed.
+
+```cmd
+npm run build
+```
+
+## package
+
+Invokes the pnpbuild cli to create the package directories under the dist folder. This will allow you to see exactly what will end up in the npm packages once they are published.
+
+```cmd
+npm run package
+```
+
+## lint
+
+Runs the linter.
+
+```cmd
+npm run lint
+```
+
+## clean
+
+Removes any generated folders from the working directory.
+
+```cmd
+npm run clean
+```

package/docs/contributing/pull-requests.md

@@ -0,0 +1,27 @@
+# Submitting Pull Requests
+
+Pull requests may be large or small - adding whole new features or fixing some misspellings. Regardless, they are all appreciated and help improve the library for everyone! By following the below guidelines we'll have an easier time merging your work and getting it into the next release.
+
+* Target your pull requests to the **version-3** branch
+* Add/Update any relevant docs articles in the relevant package's docs folder related to your changes
+* Include a test for any new functionality and ensure all existing tests are passing by running `npm test`
+* Ensure linting checks pass by typing `npm run lint`
+* Ensure everything works for a build by running `npm run package`
+* Keep your PRs as simple as possible and describe the changes to help the reviewer understand your work
+* If you have an idea for a larger change to the library please [open an issue](https://github.com/pnp/pnpjs/issues) and let's discuss before you invest many hours - these are very welcome but want to ensure it is something we can merge before you spend the time :)
+
+> If you need to target a PR for version 1, please target the "version-1" branch
+
+## Sharing is Caring - Pull Request Guidance
+
+The PnP "Sharing Is Caring" initiative teaches the basics around making changes in GitHub, submitting pull requests to the PnP & Microsoft 365 open-source repositories such as PnPjs. 
+
+Every month, we provide multiple live hands-on sessions that walk attendees through the process of using and contributing to PnP initiatives.
+
+To learn more and register for an upcoming session, please visit the [Sharing is Caring](https://aka.ms/sharing-is-caring) website.
+
+## Next Steps
+
+Now that you've submitted your PR please keep an eye on it as we might have questions. Once an initial review is complete we'll tag it with the expected version number for which it is targeted.
+
+Thank you for helping PnPjs grow and improve!!