@zxncij2390/monorepo3 3.18.0

package/docs/concepts/batching.md

@@ -0,0 +1,257 @@
+# Batching
+
+Where possible batching can significantly increase application performance by combining multiple requests to the server into one. This is especially useful when first establishing state, but applies for any scenario where you need to make multiple requests before loading or based on a user action. Batching is supported within the sp and graph libraries as shown below.
+
+## SP Example
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import "@pnp/sp/batching";
+
+const sp = spfi(...);
+
+const [batchedSP, execute] = sp.batched();
+
+let res = [];
+
+// you need to use .then syntax here as otherwise the application will stop and await the result
+batchedSP.web().then(r => res.push(r));
+
+// you need to use .then syntax here as otherwise the application will stop and await the result
+// ODATA operations such as select, filter, and expand are supported as normal
+batchedSP.web.lists.select("Title")().then(r => res.push(r));
+
+// Executes the batched calls
+await execute();
+
+// Results for all batched calls are available
+for(let i = 0; i < res.length; i++) {
+    ///Do something with the results
+}
+```
+
+### Using a batched web
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import "@pnp/sp/batching";
+
+const sp = spfi(...);
+
+const [batchedWeb, execute] = sp.web.batched();
+
+let res = [];
+
+// you need to use .then syntax here as otherwise the application will stop and await the result
+batchedWeb().then(r => res.push(r));
+
+// you need to use .then syntax here as otherwise the application will stop and await the result
+// ODATA operations such as select, filter, and expand are supported as normal
+batchedWeb.lists.select("Title")().then(r => res.push(r));
+
+// Executes the batched calls
+await execute();
+
+// Results for all batched calls are available
+for(let i = 0; i < res.length; i++) {
+    ///Do something with the results
+}
+```
+
+> Batches must be for the same web, you cannot combine requests from multiple webs into a batch.
+
+## Graph Example
+
+```TypeScript
+import { graphfi } from "@pnp/graph";
+import { GraphDefault } from "@pnp/nodejs";
+import "@pnp/graph/users";
+import "@pnp/graph/groups";
+import "@pnp/graph/batching";
+
+const graph = graphfi().using(GraphDefault({ /* ... */ }));
+
+const [batchedGraph, execute] = graph.batched();
+
+let res = [];
+
+// Pushes the results of these calls to an array
+// you need to use .then syntax here as otherwise the application will stop and await the result
+batchedGraph.users().then(r => res.push(r));
+
+// you need to use .then syntax here as otherwise the application will stop and await the result
+// ODATA operations such as select, filter, and expand are supported as normal
+batchedGraph.groups.select("Id")().then(r => res.push(r));
+
+// Executes the batched calls
+await execute();
+
+// Results for all batched calls are available
+for(let i=0; i<res.length; i++){
+    // Do something with the results
+}
+```
+
+## Advanced Batching
+
+For most cases the above usage should be sufficient, however you may be in a situation where you do not have convenient access to either an spfi instance or a web. Let's say for example you want to add a lot of items to a list and have an IList. You can in these cases use the createBatch function directly. We recommend as much as possible using the sp or web or graph batched method, but also provide this additional flexibility if you need it.
+
+```TypeScript
+import { createBatch } from "@pnp/sp/batching";
+import { SPDefault } from "@pnp/nodejs";
+import { IList } from "@pnp/sp/lists";
+import "@pnp/sp/items/list";
+
+const sp = spfi("https://tenant.sharepoint.com/sites/dev").using(SPDefault({ /* ... */ }));
+
+// in one part of your application you setup a list instance
+const list: IList = sp.web.lists.getByTitle("MyList");
+
+
+// in another part of your application you want to batch requests, but do not have the sp instance available, just the IList
+
+// note here the first part of the tuple is NOT the object, rather the behavior that enables batching. You must still register it with `using`.
+const [batchedListBehavior, execute] = createBatch(list);
+// this list is now batching all its requests
+list.using(batchedListBehavior);
+
+// these will all occur within a single batch
+list.items.add({ Title: `1: ${getRandomString(4)}` });
+list.items.add({ Title: `2: ${getRandomString(4)}` });
+list.items.add({ Title: `3: ${getRandomString(4)}` });
+list.items.add({ Title: `4: ${getRandomString(4)}` });
+
+await execute();
+```
+
+This is of course also possible with the graph library as shown below.
+
+```TypeScript
+import { graphfi } from "@pnp/graph";
+import { createBatch } from "@pnp/graph/batching";
+import { GraphDefault } from "@pnp/nodejs";
+import "@pnp/graph/users";
+
+const graph = graphfi().using(GraphDefault({ /* ... */ }));
+
+const users = graph.users;
+
+const [batchedBehavior, execute] = createBatch(users);
+users.using(batchedBehavior);
+
+users();
+// we can only place the 'users' instance into the batch once
+graph.users.using(batchedBehavior)();
+graph.users.using(batchedBehavior)();
+graph.users.using(batchedBehavior)();
+
+await execute();       
+```
+
+[](#reuse)
+
+## Don't reuse objects in Batching
+
+It shouldn't come up often, but you can not make multiple requests using the same instance of a queryable in a batch. Let's consider the **incorrect** example below:
+
+> The error message will be "This instance is already part of a batch. Please review the docs at <https://pnp.github.io/pnpjs/concepts/batching#reuse>."
+
+```TypeScript
+import { graphfi } from "@pnp/graph";
+import { createBatch } from "@pnp/graph/batching";
+import { GraphDefault } from "@pnp/nodejs";
+import "@pnp/graph/users";
+
+const graph = graphfi().using(GraphDefault({ /* ... */ }));
+
+// gain a batched instance of the graph
+const [batchedGraph, execute] = graph.batched();
+
+// we take a reference to the value returned from .users
+const users = batchedGraph.users;
+
+// we invoke it, adding it to the batch (this is a request to /users), it will succeed
+users();
+
+// we invoke it again, because this instance has already been added to the batch, this request will throw an error
+users();
+
+// we execute the batch, this promise will resolve
+await execute();        
+```
+
+To overcome this you can either start a new fluent chain or use the factory method. Starting a new fluent chain at any point will create a new instance. Please review the **corrected** sample below.
+
+```TypeScript
+import { graphfi } from "@pnp/graph";
+import { createBatch } from "@pnp/graph/batching";
+import { GraphDefault } from "@pnp/nodejs";
+import { Users } from "@pnp/graph/users";
+
+const graph = graphfi().using(GraphDefault({ /* ... */ }));
+
+// gain a batched instance of the graph
+const [batchedGraph, execute] = graph.batched();
+
+// we invoke a new instance of users from the batchedGraph
+batchedGraph.users();
+
+// we again invoke a new instance of users from the batchedGraph, this is fine
+batchedGraph.users();
+
+const users = batchedGraph.users;
+// we can do this once
+users();
+
+// by creating a new users instance using the Users factory we can keep adding things to the batch
+// users2 will be part of the same batch
+const users2 = Users(users);
+users2();
+
+// we execute the batch, this promise will resolve
+await execute();        
+```
+
+> In addition you cannot continue using a batch after execute. Once execute has resolved the batch is done. You should create a new batch using one of the described methods to conduct another batched call.
+
+## Case where batch result returns an object that can be invoked
+
+In the following example, the results of adding items to the list is an object with a type of **IItemAddResult** which is `{data: any, item: IItem}`. Since version v1 the expectation is that the `item` object is immediately usable to make additional queries. When this object is the result of a batched call, this was not the case so we have added additional code to reset the observers using the original base from witch the batch was created, mimicing the behavior had the **IItem** been created from that base withyout a batch involved. We use [CopyFrom](../core/behaviors.md#CopyFrom) to ensure that we maintain the references to the InternalResolve and InternalReject events through the end of this timelines lifecycle.
+
+```TypeScript
+import { createBatch } from "@pnp/sp/batching";
+import { SPDefault } from "@pnp/nodejs";
+import { IList } from "@pnp/sp/lists";
+import "@pnp/sp/items/list";
+
+const sp = spfi("https://tenant.sharepoint.com/sites/dev").using(SPDefault({ /* ... */ }));
+
+// in one part of your application you setup a list instance
+const list: IList = sp.web.lists.getByTitle("MyList");
+
+const [batchedListBehavior, execute] = createBatch(list);
+// this list is now batching all its requests
+list.using(batchedListBehavior);
+
+let res: IItemAddResult[] = [];
+
+// these will all occur within a single batch
+list.items.add({ Title: `1: ${getRandomString(4)}` }).then(r => res.push(r));
+list.items.add({ Title: `2: ${getRandomString(4)}` }).then(r => res.push(r));
+list.items.add({ Title: `3: ${getRandomString(4)}` }).then(r => res.push(r));
+list.items.add({ Title: `4: ${getRandomString(4)}` }).then(r => res.push(r));
+
+await execute();
+
+let newItems: IItem[] = [];
+
+for(let i=0; i<res.length; i++){
+    //This line will correctly resolve
+    const newItem = await res[i].item.select("Title")<{Title: string}>();
+    newItems.push(newItem);
+}
+```

package/docs/concepts/calling-other-endpoints.md

@@ -0,0 +1,213 @@
+# Calling other endpoints not currently implemented in PnPjs library
+
+If you find that there are endpoints that have not yet been implemented, or have changed in such a way that there are issues using the implemented endpoint, you can still make those calls and take advantage of the plumbing provided by the library.
+
+## SharePoint
+
+To issue calls against the SharePoint REST endpoints you would use one of the existing [operations](https://github.com/pnp/pnpjs/blob/version-3/packages/sp/operations.ts):
+
+- spGet
+- spPost
+- spDelete
+- spPatch
+and the extended post methods with additional headers.
+- spPostMerge
+- spPostDelete
+- spPostDeleteETag
+
+To construct a call you will need to pass, to the operation call an SPQueryable and optionally a RequestInit object which will be merged with any existing registered init object. To learn more about queryable and the options for constructing one, check out the [documentation](../queryable/queryable.md).
+
+Below are a couple of examples to get you started.
+
+### Example spGet
+
+Let's pretend that the getById method didn't exist on a lists items. The example below shows two methods for constructing our SPQueryable method.
+
+The first is the easiest to use because, as the queryable documentation tells us, this will maintain all the registered observers on the original queryable instance. We would start with the queryable object closest to the endpoint we want to use, in this case `list`. We do this because we need to construct the full URL that will be called. Using `list` in this instance gives us the first part of the URL (e.g. `https://contoso.sharepoint.com/sites/testsite/_api/web/lists/getByTitle('My List')`) and then we can construct the remainder of the call by passing in a string.
+
+The second method essentially starts from scratch where the user constructs the entire url and then registers observers on the SPQuerable instance. Then uses spGet to execute the call. There are many other variations to arrive at the same outcome, all are dependent on your requirements.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import { AssignFrom } from "@pnp/core";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import { spGet, SPQueryable, SPFx } from "@pnp/sp";
+
+// Establish SPFI instance passing in the appropriate behavior to register the initial observers.
+const sp = spfi(...);
+
+// create an instance of the items queryable
+
+const list = sp.web.lists.getByTitle("My List");
+
+// get the item with an id of 1, easiest method
+const item: any = await spGet(SPQueryable(list, "items(1)"));
+
+// get the item with an id of 1, constructing a new queryable and registering behaviors
+const spQueryable = SPQueryable("https://contoso.sharepoint.com/sites/testsite/_api/web/lists/getByTitle('My List')/items(1)").using(SPFx(this.context));
+
+// ***or***
+
+// For v3 the full url is require for SPQuerable when providing just a string
+const spQueryable = SPQueryable("https://contoso.sharepoint.com/sites/testsite/_api/web/lists/getByTitle('My List')/items(1)").using(AssignFrom(sp.web));
+
+// and then use spQueryable to make the request
+const item: any = await spGet(spQueryable);
+```
+
+The resulting call will be to the endpoint:
+`https://contoso.sharepoint.com/sites/testsite/_api/web/lists/getByTitle('My List')/items(1)`
+
+### Example spPost
+
+Let's now pretend that we need to get the changes on a list and want to call the `getchanges` method off list.
+
+```TypeScript
+import { spfi } from "@pnp/sp";
+import "@pnp/sp/webs";
+import "@pnp/sp/lists";
+import { IChangeQuery, spPost, SPQueryable } from "@pnp/sp";
+import { body } from "@pnp/queryable";
+
+// Establish SPFI instance passing in the appropriate behavior to register the initial observers.
+const sp = spfi(...);
+
+
+// build the changeQuery object, here we look att changes regarding Add, DeleteObject and Restore
+const query: IChangeQuery = {
+    Add: true,
+    ChangeTokenEnd: null,
+    ChangeTokenStart: null,
+    DeleteObject: true,
+    Rename: true,
+    Restore: true,
+};
+
+// create an instance of the items queryable
+const list = sp.web.lists.getByTitle("My List");
+
+// get the item with an id of 1
+const changes: any = await spPost(SPQueryable(list, "getchanges"), body({query}));
+
+```
+
+The resulting call will be to the endpoint:
+`https://contoso.sharepoint.com/sites/testsite/_api/web/lists/getByTitle('My List')/getchanges`
+
+## Microsoft Graph
+
+To issue calls against the Microsoft Graph REST endpoints you would use one of the existing [operations](https://github.com/pnp/pnpjs/blob/version-3/packages/graph/operations.ts):
+
+- graphGet
+- graphPost
+- graphDelete
+- graphPatch
+- graphPut
+
+To construct a call you will need to pass, to the operation call an GraphQueryable and optionally a RequestInit object which will be merged with any existing registered init object. To learn more about queryable and the options for constructing one, check out the [documentation](../queryable/queryable.md).
+
+Below are a couple of examples to get you started.
+
+### Example graphGet
+
+Here's an example for getting the chats for a particular user. This uses the simplest method for constructing the graphQueryable which is to start with a instance of a queryable that is close to the endpoint we want to call, in this case `user` and then adding the additional path as a string. For a more advanced example see `spGet` above.
+
+```TypeScript
+import { graphfi } from "@pnp/graph";
+import "@pnp/graph/users";
+import { GraphQueryable, graphGet } from "@pnp/graph";
+
+// Establish GRAPHFI instance passing in the appropriate behavior to register the initial observers.
+const graph = graphfi(...);
+
+// create an instance of the user queryable
+const user = graph.users.getById('jane@contoso.com');
+
+// get the chats for the user
+const chat: any = await graphGet(GraphQueryable(user, "chats"));
+```
+
+The results call will be to the endpoint:
+`https://graph.microsoft.com/v1.0/users/jane@contoso.com/chats`
+
+### Example graphPost
+
+This is an example of adding an event to a calendar.
+
+```TypeScript
+import { graphfi } from "@pnp/graph";
+import "@pnp/graph/users";
+import "@pnp/graph/calendars";
+import { GraphQueryable, graphPost } from "@pnp/graph";
+import { body, InjectHeaders } from "@pnp/queryable";
+
+// Establish GRAPHFI instance passing in the appropriate behavior to register the initial observers.
+const graph = graphfi(...);
+
+// create an instance of the user queryable
+const calendar = graph.users.getById('jane@contoso.com').calendar;
+
+const props = {
+  "subject": "Let's go for lunch",
+  "body": {
+    "contentType": "HTML",
+    "content": "Does noon work for you?"
+  },
+  "start": {
+      "dateTime": "2017-04-15T12:00:00",
+      "timeZone": "Pacific Standard Time"
+  },
+  "end": {
+      "dateTime": "2017-04-15T14:00:00",
+      "timeZone": "Pacific Standard Time"
+  },
+  "location":{
+      "displayName":"Harry's Bar"
+  },
+  "attendees": [
+    {
+      "emailAddress": {
+        "address":"samanthab@contoso.onmicrosoft.com",
+        "name": "Samantha Booth"
+      },
+      "type": "required"
+    }
+  ],
+  "allowNewTimeProposals": true,
+  "transactionId":"7E163156-7762-4BEB-A1C6-729EA81755A7"
+};
+
+// custom request init to add timezone header.
+const graphQueryable = GraphQueryable(calendar, "events").using(InjectHeaders({
+    "Prefer": 'outlook.timezone="Pacific Standard Time"',
+}));
+
+// adds a new event to the user's calendar
+const event: any = await graphPost(graphQueryable, body(props));
+```
+
+The results call will be to the endpoint:
+`https://graph.microsoft.com/v1.0/users/jane@contoso.com/calendar/events`
+
+## Advanced Scenario
+
+If you find you need to create an instance of Queryable (for either graph or SharePoint) that would hang off the root of the url you can use the `AssignFrom` or `CopyFrom` [behaviors](../core/behaviors.md).
+
+```TypeScript
+import { graphfi } from "@pnp/graph";
+import "@pnp/graph/users";
+import { GraphQueryable, graphPost } from "@pnp/graph";
+import { body, InjectHeaders } from "@pnp/queryable";
+import { AssignFrom } from "@pnp/core";
+
+// Establish GRAPHFI instance passing in the appropriate behavior to register the initial observers.
+const graph = graphfi(...);
+
+const chatsQueryable = GraphQueryable("chats").using(AssignFrom(graph.me));
+
+const chat: any = await graphPost(chatsQueryable, body(chatBody));
+```
+
+The results call will be to the endpoint:
+`https://graph.microsoft.com/v1.0/chats`

package/docs/concepts/custom-bundle.md

@@ -0,0 +1,15 @@
+# Custom Bundling
+
+With the introduction of [selective imports](./selective-imports.md) it is now possible to create your own bundle to exactly fit your needs. This provides much greater control over how your solutions are deployed and what is included in your bundles.
+
+Scenarios could include:
+
+- Deploying a company-wide PnPjs custom bundle shared by all your components so it only needs to be downloaded once.
+- Creating SPFx libraries either for one project or a single webpart.
+- Create a single library containing the PnPjs code you need bundled along with your custom [extensions](../queryable/extensions.md).
+
+## Create a custom bundle
+
+### Webpack
+
+You can see/clone a [sample project of this example here](https://github.com/pnp/pnpjs/tree/version-3/samples/custom-bundle-webpack).