@zxncij2390/monorepo3 3.18.0

package/docs/core/moments.md

@@ -0,0 +1,215 @@
+# @pnp/core : moments
+
+Moments are the name we use to describe the steps executed during a timeline lifecycle. They are defined on a plain object by a series of functions with the general form:
+
+```TypeScript
+// the first argument is the set of observers subscribed to the given moment
+// the rest of the args vary by an interaction between moment and observer types and represent the args passed when emit is called for a given moment
+function (observers: any[], ...args: any[]): any;
+```
+
+Let's have a look at one of the included moment factory functions, which define how the moment interacts with its registered observers, and use it to understand a bit more on how things work. In this example we'll look at the broadcast moment, used to mimic a classic event where no return value is tracked, we just want to emit an event to all the subscribed observers.
+
+```TypeScript
+// the broadcast factory function, returning the actual moment implementation function
+// The type T is used by the typings of Timeline to described the arguments passed in emit
+export function broadcast<T extends ObserverAction>(): (observers: T[], ...args: any[]) => void {
+
+    // this is the actual moment implementation, called each time a given moment occurs in the timeline
+    return function (observers: T[], ...args: any[]): void {
+
+        // we make a local ref of the observers
+        const obs = [...observers];
+
+        // we loop through sending the args to each observer
+        for (let i = 0; i < obs.length; i++) {
+
+            // note that within every moment and observer "this" will be the current timeline object
+            Reflect.apply(obs[i], this, args);
+        }
+    };
+}
+```
+
+Let's use `broadcast` in a couple examples to show how it works. You can also review the [timeline](./timeline.md) article for a fuller example.
+
+```TypeScript
+// our first type determines the type of the observers that will be regsitered to the moment "first"
+type Broadcast1ObserverType = (this: Timeline<any>, message: string) => void;
+
+// our second type determines the type of the observers that will be regsitered to the moment "second"
+type Broadcast2ObserverType = (this: Timeline<any>, value: number, value2: number) => void;
+
+const moments = {
+    first: broadcast<Broadcast1ObserverType>(),
+    second: broadcast<Broadcast2ObserverType>(),
+} as const;
+```
+
+Now that we have defined two moments we can update our Timeline implementing class to emit each as we desire, as covered in the [timeline](./timeline.md) article. Let's focus on the relationship between the moment definition and the typings inherited by `on` and `emit` in Timeline.
+
+Because we want observers of a given moment to understand what arguments they will get the typings of Timeline are setup to use the type defining the moment's observer across all operations. For example, using our moment "first" from above. Each moment can be subscribed by zero or more observers.
+
+```TypeScript
+// our observer function matches the type of Broadcast1ObserverType and the intellisense will reflect that.
+// If you want to change the signature you need only do so in the type Broadcast1ObserverType and the change will update the on and emit typings as well
+// here we want to reference "this" inside our observer function (preferred)
+obj.on.first(function (this: Timeline<any>, message: string) {
+    // we use "this", which will be the current timeline and the default log method to emit a logging event
+    this.log(message, 0);
+});
+
+// we don't need to reference "this" so we use arrow notation
+obj.on.first((message: string) => {
+    console.log(message);
+});
+```
+
+Similarily for `second` our observers would match Broadcast2Observer.
+
+```TypeScript
+obj.on.second(function (this: Timeline<any>, value: number, value2: number) {
+    // we use "this", which will be the current timeline and the default log method to emit a logging event
+    this.log(`got value1: ${value} value2: ${value2}`, 0);
+});
+
+obj.on.second((value: number, value2: number) => {
+    console.log(`got value1: ${value} value2: ${value2}`);
+});
+```
+
+## Existing Moment Factories
+
+You a already familiar with `broadcast` which passes the emited args to all subscribed observers, this section lists the existing built in moment factories:
+
+### broadcast
+
+Creates a moment that passes the emited args to all subscribed observers. Takes a single type parameter defining the observer signature and always returns void. Is not async.
+
+```TypeScript
+import { broadcast } from "@pnp/core";
+
+// can have any method signature you want that returns void, "this" will always be set
+type BroadcastObserver = (this: Timeline<any>, message: string) => void;
+
+const moments = {
+    example: broadcast<BroadcastObserver>(),
+} as const;
+
+obj.on.example(function (this: Timeline<any>, message: string) {
+    this.log(message, 0);
+});
+
+obj.emit.example("Hello");
+```
+
+### asyncReduce
+
+Creates a moment that executes each observer asynchronously, awaiting the result and passes the returned arguments as the arguments to the next observer. This is very much like the redux pattern taking the arguments as the state which each observer may modify then returning a new state.
+
+```TypeScript
+import { asyncReduce } from "@pnp/core";
+
+// can have any method signature you want, so long as it is async and returns a tuple matching in order the arguments, "this" will always be set
+type AsyncReduceObserver = (this: Timeline<any>, arg1: string, arg2: number) => Promise<[string, number]>;
+
+const moments = {
+    example: asyncReduce<AsyncReduceObserver>(),
+} as const;
+
+obj.on.example(async function (this: Timeline<any>, arg1: string, arg2: number) {
+
+    this.log(message, 0);
+
+    // we can manipulate the values
+    arg2++;
+
+    // always return a tuple of the passed arguments, possibly modified
+    return [arg1, arg2];
+});
+
+obj.emit.example("Hello", 42);
+```
+
+### request
+
+Creates a moment where the first registered observer is used to asynchronously execute a request, returning a single result. If no result is returned (undefined) no further action is taken and the result will be undefined (i.e. additional observers are not used).
+
+This is used by us to execute web requets, but would also serve to represent any async request such as a database read, file read, or provisioning step.
+
+```TypeScript
+import { request } from "@pnp/core";
+
+// can have any method signature you want, "this" will always be set
+type RequestObserver = (this: Timeline<any>, arg1: string, arg2: number) => Promise<string>;
+
+const moments = {
+    example: request<RequestObserver>(),
+} as const;
+
+obj.on.example(async function (this: Timeline<any>, arg1: string, arg2: number) {
+
+    this.log(`Sending request: ${arg1}`, 0);
+
+    // request expects a single value result
+    return `result value ${arg2}`;
+});
+
+obj.emit.example("Hello", 42);
+```
+
+## Additional Examples
+
+### waitall
+
+Perhaps you have a situation where you would like to wait until all of the subscribed observers for a given moment complete, but they can run async in parallel.
+
+```TypeScript
+export function waitall<T extends ObserverFunction>(): (observers: T[], ...args: any[]) => Promise<void> {
+
+    // this is the actual moment implementation, called each time a given moment occurs in the timeline
+    return function (observers: T[], ...args: any[]): void {
+
+        // we make a local ref of the observers
+        const obs = [...observers];
+
+        const promises = [];
+
+        // we loop through sending the args to each observer
+        for (let i = 0; i < obs.length; i++) {
+
+            // note that within every moment and observer "this" will be the current timeline object
+            promises.push(Reflect.apply(obs[i], this, args));
+        }
+
+        return Promise.all(promises).then(() => void(0));
+    };
+}
+```
+
+### first
+
+Perhaps you would instead like to only get the result of the first observer to return.
+
+```TypeScript
+export function first<T extends ObserverFunction>(): (observers: T[], ...args: any[]) => Promise<any> {
+
+    // this is the actual moment implementation, called each time a given moment occurs in the timeline
+    return function (observers: T[], ...args: any[]): void {
+
+        // we make a local ref of the observers
+        const obs = [...observers];
+
+        const promises = [];
+
+        // we loop through sending the args to each observer
+        for (let i = 0; i < obs.length; i++) {
+
+            // note that within every moment and observer "this" will be the current timeline object
+            promises.push(Reflect.apply(obs[i], this, args));
+        }
+
+        return Promise.race(promises);
+    };
+}
+```

package/docs/core/observers.md

@@ -0,0 +1,100 @@
+# @pnp/core : observers
+
+Observers are used to implement all of the functionality within a [Timeline's](./timeline.md) [moments](./moments.md). Each moment defines the signature of observers you can register, and calling the observers is orchestrated by the implementation of the moment. A few facts about observers:
+
+- All observers are functions
+- The "this" of an observer is always the Timeline implementation that emitted the moment
+- Do not handle non-recoverable errors in observers, let them throw and they will be handled by the library appropriately and routed to the `error` moment.
+
+> For details on implementing observers for Queryable, [please see this article](../queryable/queryable.md).
+
+## Observer Inheritance
+
+Timelines created from other timelines (i.e. how sp and graph libraries work) inherit all of the observers from the parent. Observers added to the parent will apply for all children.
+
+When you make a change to the set of observers through any of the subscription methods outlined below that inheritance is broken. Meaning changes to the parent will no longer apply to that child, and changes to a child never affect a parent. This applies to ALL moments on change of ANY moment, there is no per-moment inheritance concept.
+
+```TypeScript
+const sp = new spfi().using(...lots of behaviors);
+
+// web is current inheriting all observers from "sp"
+const web = sp.web;
+
+// at this point web no longer inherits from "sp" and has its own observers
+// but still includes everything that was registered in sp before this call
+web.on.log(...);
+
+// web2 inherits from sp as each invocation of .web creates a fresh IWeb instance
+const web2 = sp.web;
+
+// list inherits from web's observers and will contain the extra `log` observer added above
+const list = web.lists.getById("");
+
+// this new behavior will apply to web2 and any subsequent objects created from sp
+sp.using(AnotherBehavior());
+
+// web will again inherit from sp through web2, the extra log handler is gone
+// list now ALSO is reinheriting from sp as it was pointing to web
+web.using(AssignFrom(web2));
+// see below for more information on AssignFrom
+```
+
+## Obserever Subscriptions
+
+All timeline moments are exposed through the `on` property with three options for subscription.
+
+### Append
+
+This is the default, and adds your observer to the end of the array of subscribed observers.
+
+```TypeScript
+obj.on.log(function(this: Queryable, message: string, level: number) {
+    if (level > 1) {
+        console.log(message);
+    }
+});
+```
+
+### Prepend
+
+Using prepend will place your observer as the first item in the array of subscribed observers. There is no gaurantee it will always remain first, other code can also use prepend.
+
+```TypeScript
+obj.on.log.prepend(function(this: Queryable, message: string, level: number) {
+    if (level > 1) {
+        console.log(message);
+    }
+});
+```
+
+### Replace
+
+Replace will remove all other subscribed observers from a moment and add the supplied observer as the only one in the array of subscribed observers.
+
+```TypeScript
+obj.on.log.replace(function(this: Queryable, message: string, level: number) {
+    if (level > 1) {
+        console.log(message);
+    }
+});
+```
+
+### ToArray
+
+The ToArray method creates a cloned copy of the array of registered observers for a given moment. Note that because it is a clone changes to the returned array do not affect the registered observers.
+
+```TypeScript
+const arr = obj.on.log.toArray();
+```
+
+### Clear
+
+This clears ALL observers for a given moment, returning true if any observers were removed, and false if no changes were made.
+
+```TypeScript
+const didChange = obj.on.log.clear();
+```
+
+## Special Behaviors
+
+The core library includes two special behaviors used to help manage observer inheritance. The best case is to manage inheritance using the methods described above, but these provide quick shorthand to help in certain scenarios. These are [AssignFrom](./behaviors.md#assignfrom) and [CopyFrom](./behaviors.md#copyfrom).

package/docs/core/storage.md

@@ -0,0 +1,90 @@
+# @pnp/core : storage
+
+This module provides a thin wrapper over the browser local and session storage. If neither option is available it shims storage with a non-persistent in memory polyfill. Optionally through configuration you can activate expiration. Sample usage is shown below.
+
+## PnPClientStorage
+
+The main export of this module, contains properties representing local and session storage.
+
+```TypeScript
+import { PnPClientStorage } from "@pnp/core";
+
+const storage = new PnPClientStorage();
+const myvalue = storage.local.get("mykey");
+```
+
+## PnPClientStorageWrapper
+
+Each of the storage locations (session and local) are wrapped with this helper class. You can use it directly, but generally it would be used
+from an instance of PnPClientStorage as shown below. These examples all use local storage, the operations are identical for session storage.
+
+```TypeScript
+import { PnPClientStorage } from "@pnp/core";
+
+const storage = new PnPClientStorage();
+
+// get a value from storage
+const value = storage.local.get("mykey");
+
+// put a value into storage
+storage.local.put("mykey2", "my value");
+
+// put a value into storage with an expiration
+storage.local.put("mykey2", "my value", new Date());
+
+// put a simple object into storage
+// because JSON.stringify is used to package the object we do NOT do a deep rehydration of stored objects
+storage.local.put("mykey3", {
+    key: "value",
+    key2: "value2",
+});
+
+// remove a value from storage
+storage.local.delete("mykey3");
+
+// get an item or add it if it does not exist
+// returns a promise in case you need time to get the value for storage
+// optionally takes a third parameter specifying the expiration
+storage.local.getOrPut("mykey4", () => {
+    return Promise.resolve("value");
+});
+
+// delete expired items
+storage.local.deleteExpired();
+```
+
+### Cache Expiration
+
+The ability remove of expired items based on a configured timeout can help if the cache is filling up. This can be accomplished by explicitly calling the deleteExpired method on the cache you wish to clear. A suggested usage is to add this into your page init code as clearing expired items once per page load is likely sufficient.
+
+```TypeScript
+import { PnPClientStorage } from "@pnp/core";
+
+const storage = new PnPClientStorage();
+
+// session storage
+storage.session.deleteExpired();
+
+// local storage
+storage.local.deleteExpired();
+
+// this returns a promise, so you can perform some activity after the expired items are removed:
+storage.local.deleteExpired().then(_ => {
+    // init my application
+});
+```
+
+In previous versions we included code to automatically remove expired items. Due to a lack of necessity we removed that, but you can recreate the concept as shown below:
+
+```TypeScript
+function expirer(timeout = 3000) {
+
+    // session storage
+    storage.session.deleteExpired();
+
+    // local storage
+    storage.local.deleteExpired();
+
+    setTimeout(() => expirer(timeout), timeout);
+}
+```

package/docs/core/timeline.md

@@ -0,0 +1,190 @@
+# @pnp/core : timeline
+
+Timeline provides base functionality for ochestrating async operations. A timeline defines a set of [moments](./moments.md) to which observers can be registered. [Observers](./observers.md) are functions that can act independently or together during a moment in the timeline. The model is event-like but each moment's implementation can be unique in how it interacts with the registered observers. Keep reading under [Define Moments](#define-moments) to understand more about what a moment is and how to create one.
+
+![Timeline Architecture](../img/TimelineArchitecture.jpg)
+
+The easiest way to understand Timeline is to walk through implementing a simple one below. You also review [Queryable](../queryable/queryable.md) to see how we use Timeline internally to the library.
+
+## Create a Timeline
+
+Implementing a timeline involves several steps, each explained below.
+
+1. Define Moments
+2. Implement concrete Timeline class
+
+### Define Moments
+
+A timeline is made up of a set of moments which are themselves defined by a plain object with one or more properties, each of which is a function. You can use predefined [moments](./moments.md), or create your own to meet your exact requirements. Below we define two moments within the `MyMoments` object, first and second. These names are entirely your choice and the order moments are defined in the plain object carries no meaning.
+
+The `first` moment uses a pre-defined moment implementation `asyncReduce`. This moment allows you to define a state based on the arguments of the observer function, in this case `FirstObserver`. `asyncReduce` takes those arguments, does some processing, and returns a promise resolving an array matching the input arguments in order and type with optionally changed values. Those values become the arguments to the next observer registered to that moment.
+
+```TypeScript
+import { asyncReduce, ObserverAction, Timeline } from "@pnp/core";
+
+// the first observer is a function taking a number and async returning a number in an array
+// all asyncReduce observers must follow this pattern of returning async a tuple matching the args
+export type FirstObserver = (this: any, counter: number) => Promise<[number]>;
+
+// the second observer is a function taking a number and returning void
+export type SecondObserver = (this: any, result: number) => void;
+
+// this is a custom moment definition as an example.
+export function report<T extends ObserverAction>(): (observers: T[], ...args: any[]) => void {
+
+    return function (observers: T[], ...args: any[]): void {
+
+        const obs = [...observers];
+
+        // for this 
+        if (obs.length > 0) {
+             Reflect.apply(obs[0], this, args);
+        }
+    };
+}
+
+// this plain object defines the moments which will be available in our timeline
+// the property name "first" and "second" will be the moment names, used when we make calls such as instance.on.first and instance.on.second
+const TestingMoments = {
+    first: asyncReduce<FirstObserver>(),
+    second: report<SecondObserver>(),
+} as const;
+// note as well the use of as const, this allows TypeScript to properly resolve all the complex typings and not treat the plain object as "any"
+```
+
+### Subclass Timeline
+
+After defining our moments we need to subclass Timeline to define how those moments emit through the lifecycle of the Timeline. Timeline has a single abstract method "execute" you must implement. You will also need to provide a way for callers to trigger the protected "start" method.
+
+```TypeScript
+// our implementation of timeline, note we use `typeof TestingMoments` and ALSO pass the testing moments object to super() in the constructor
+class TestTimeline extends Timeline<typeof TestingMoments> {
+
+    // we create two unique refs for our implementation we will use
+    // to resolve the execute promise
+    private InternalResolveEvent = Symbol.for("Resolve");
+    private InternalRejectEvent = Symbol.for("Reject");
+
+    constructor() {
+        // we need to pass the moments to the base Timeline
+        super(TestingMoments);
+    }
+
+    // we implement the execute the method to define when, in what order, and how our moments are called. This give you full control within the Timeline framework
+    // to determine your implementation's behavior
+    protected async execute(init?: any): Promise<any> {
+
+        // we can always emit log to any subscribers
+        this.log("Starting", 0);
+
+        // set our timeline to start in the next tick
+        setTimeout(async () => {
+
+            try {
+
+                // we emit our "first" event
+                let [value] = await this.emit.first(init);
+
+                // we emit our "second" event
+                [value] = await this.emit.second(value);
+
+                // we reolve the execute promise with the final value
+                this.emit[this.InternalResolveEvent](value);
+
+            } catch (e) {
+
+                // we emit our reject event
+                this.emit[this.InternalRejectEvent](e);
+                // we emit error to any subscribed observers
+                this.error(e);
+            }
+        }, 0);
+
+        // return a promise which we will resolve/reject during the timeline lifecycle
+        return new Promise((resolve, reject) => {
+            this.on[this.InternalResolveEvent].replace(resolve);
+            this.on[this.InternalRejectEvent].replace(reject);
+        });
+    }
+
+    // provide a method to trigger our timeline, this could be protected or called directly by the user, your choice
+    public go(startValue = 0): Promise<number> {
+        
+        // here we take a starting number
+        return this.start(startValue);
+    }
+}
+```
+
+### Using your Timeline
+
+```TypeScript
+import { TestTimeline } from "./file.js";
+
+const tl = new TestTimeline();
+
+// register observer
+tl.on.first(async (n) => [++n]);
+
+// register observer
+tl.on.second(async (n) => [++n]);
+
+// h === 2
+const h = await tl.go(0);
+
+// h === 7
+const h2 = await tl.go(5);
+```
+
+## Understanding the Timline Lifecycle
+
+Now that you implemented a simple timeline let's take a minute to understand the lifecycle of a timeline execution. There are four moments always defined for every timeline: init, dispose, log, and error. Of these init and dispose are used within the lifecycle, while log and error are used as you need.
+
+### Timeline Lifecycle
+
+- .on.init (always)
+- your moments as defined in execute, in our example:
+  - .on.first
+  - .on.second
+- .on.dispose (always)
+
+As well the moments log and error exist on every Timeline derived class and can occur at any point during the lifecycle.
+
+## Observer Inheritance
+
+Let's say that you want to contruct a system whereby you can create Timeline based instances from other Timeline based instances - which is what [Queryable](../queryable/queryable.md) does. Imagine we have a class with a pseudo-signature like:
+
+```TypeScript
+class ExampleTimeline extends Timeline<typeof SomeMoments> {
+
+    // we create two unique refs for our implementation we will use
+    // to resolve the execute promise
+    private InternalResolveEvent = Symbol.for("Resolve");
+    private InternalRejectEvent = Symbol.for("Reject");
+
+    constructor(base: ATimeline) {
+
+        // we need to pass the moments to the base Timeline
+        super(TestingMoments, base.observers);
+    }
+
+    //...
+}
+```
+
+We can then use it like:
+
+```TypeScript
+const tl1 = new ExampleTimeline();
+tl1.on.first(async (n) => [++n]);
+tl1.on.second(async (n) => [++n]);
+
+// at this point tl2's observer collection is a pointer to the same collection as tl1
+const tl2 = new ExampleTimeline(tl1);
+
+// we add a second observer to first, it is applied to BOTH tl1 and tl2
+tl1.on.first(async (n) => [++n]);
+
+// BUT when we modify tl2's observers, either by adding or clearing a moment it begins to track its own collection
+tl2.on.first(async (n) => [++n]);
+```