@zxncij2390/monorepo3 3.18.0

package/packages/queryable/queryable.ts

@@ -0,0 +1,239 @@
+import { combine, getGUID, Timeline, asyncReduce, reduce, broadcast, request, extendable, isArray, TimelinePipe, lifecycle, stringIsNullOrEmpty } from "@pnp/core";
+import { IInvokable, invokable } from "./invokable.js";
+
+export type QueryableConstructObserver = (this: IQueryableInternal, init: QueryableInit, path?: string) => void;
+
+export type QueryablePreObserver = (this: IQueryableInternal, url: string, init: RequestInit, result: any) => Promise<[string, RequestInit, any]>;
+
+export type QueryableAuthObserver = (this: IQueryableInternal, url: URL, init: RequestInit) => Promise<[URL, RequestInit]>;
+
+export type QueryableSendObserver = (this: IQueryableInternal, url: URL, init: RequestInit) => Promise<Response>;
+
+export type QueryableParseObserver = (this: IQueryableInternal, url: URL, response: Response, result: any | undefined) => Promise<[URL, Response, any]>;
+
+export type QueryablePostObserver = (this: IQueryableInternal, url: URL, result: any | undefined) => Promise<[URL, any]>;
+
+export type QueryableDataObserver<T = any> = (this: IQueryableInternal, result: T) => void;
+
+type QueryablePromiseObserver = (this: IQueryableInternal, promise: Promise<any>) => Promise<[Promise<any>]>;
+
+const DefaultMoments = {
+    construct: lifecycle<QueryableConstructObserver>(),
+    pre: asyncReduce<QueryablePreObserver>(),
+    auth: asyncReduce<QueryableAuthObserver>(),
+    send: request<QueryableSendObserver>(),
+    parse: asyncReduce<QueryableParseObserver>(),
+    post: asyncReduce<QueryablePostObserver>(),
+    data: broadcast<QueryableDataObserver>(),
+} as const;
+
+export type QueryableInit = Queryable<any> | string | [Queryable<any>, string];
+
+@extendable()
+@invokable()
+export class Queryable<R> extends Timeline<typeof DefaultMoments> implements IQueryableInternal<R> {
+
+    // tracks any query paramters which will be appended to the request url
+    private _query: URLSearchParams;
+
+    // tracks the current url for a given Queryable
+    protected _url: string;
+
+    // these keys represent internal events for Queryable, users are not expected to
+    // subscribe directly to these, rather they enable functionality within Queryable
+    // they are Symbols such that there are NOT cloned between queryables as we only grab string keys (by design)
+    protected InternalResolve = Symbol.for("Queryable_Resolve");
+    protected InternalReject = Symbol.for("Queryable_Reject");
+    protected InternalPromise = Symbol.for("Queryable_Promise");
+
+    constructor(init: QueryableInit, path?: string) {
+
+        super(DefaultMoments);
+
+        this._query = new URLSearchParams();
+
+        // add an intneral moment with specific implementaion for promise creation
+        this.moments[this.InternalPromise] = reduce<QueryablePromiseObserver>();
+
+        let parent: Queryable<any>;
+
+        if (typeof init === "string") {
+
+            this._url = combine(init, path);
+
+        } else if (isArray(init)) {
+
+            if (init.length !== 2) {
+                throw Error("When using the tuple param exactly two arguments are expected.");
+            }
+
+            if (typeof init[1] !== "string") {
+                throw Error("Expected second tuple param to be a string.");
+            }
+
+            parent = init[0];
+            this._url = combine(init[1], path);
+
+        } else {
+
+            parent = init as Queryable<any>;
+            this._url = combine(parent._url, path);
+        }
+
+        if (typeof parent !== "undefined") {
+            this.observers = parent.observers;
+            this._inheritingObservers = true;
+        }
+    }
+
+    /**
+     * Directly concatenates the supplied string to the current url, not normalizing "/" chars
+     *
+     * @param pathPart The string to concatenate to the url
+     */
+    public concat(pathPart: string): this {
+        this._url += pathPart;
+        return this;
+    }
+
+    /**
+     * Gets the full url with query information
+     *
+     */
+    public toRequestUrl(): string {
+
+        let url = this.toUrl();
+
+        const query = this.query.toString();
+        if (!stringIsNullOrEmpty(query)) {
+            url += `${url.indexOf("?") > -1 ? "&" : "?"}${query}`;
+        }
+
+        return url;
+    }
+
+    /**
+     * Querystring key, value pairs which will be included in the request
+     */
+    public get query(): URLSearchParams {
+        return this._query;
+    }
+
+    /**
+     * Gets the current url
+     *
+     */
+    public toUrl(): string {
+        return this._url;
+    }
+
+    protected execute(userInit: RequestInit): Promise<void> {
+
+        // if there are NO observers registered this is likely either a bug in the library or a user error, direct to docs
+        if (Reflect.ownKeys(this.observers).length < 1) {
+            throw Error("No observers registered for this request. (https://pnp.github.io/pnpjs/queryable/queryable#no-observers-registered-for-this-request)");
+        }
+
+        // schedule the execution after we return the promise below in the next event loop
+        setTimeout(async () => {
+
+            const requestId = getGUID();
+            let requestUrl: URL;
+
+            const log = (msg: string, level?: number) => {
+                // this allows us to easily and consistently format our messages
+                this.log(`[${requestId}] ${msg}`, level);
+            };
+
+            try {
+
+                log("Beginning request", 0);
+
+                // include the request id in the headers to assist with debugging against logs
+                const initSeed = {
+                    ...userInit,
+                    headers: { ...userInit.headers, "X-PnPjs-RequestId": requestId },
+                };
+
+                // eslint-disable-next-line prefer-const
+                let [url, init, result] = await this.emit.pre(this.toRequestUrl(), initSeed, undefined);
+
+                log(`Url: ${url}`, 1);
+
+                if (typeof result !== "undefined") {
+
+                    log("Result returned from pre, Emitting data");
+                    this.emit.data(result);
+                    log("Emitted data");
+                    return;
+                }
+
+                log("Emitting auth");
+                [requestUrl, init] = await this.emit.auth(new URL(url), init);
+                log("Emitted auth");
+
+                // we always resepect user supplied init over observer modified init
+                init = { ...init, ...userInit, headers: { ...init.headers, ...userInit.headers } };
+
+                log("Emitting send");
+                let response = await this.emit.send(requestUrl, init);
+                log("Emitted send");
+
+                log("Emitting parse");
+                [requestUrl, response, result] = await this.emit.parse(requestUrl, response, result);
+                log("Emitted parse");
+
+                log("Emitting post");
+                [requestUrl, result] = await this.emit.post(requestUrl, result);
+                log("Emitted post");
+
+                log("Emitting data");
+                this.emit.data(result);
+                log("Emitted data");
+
+            } catch (e) {
+
+                log(`Emitting error: "${e.message || e}"`, 3);
+                // anything that throws we emit and continue
+                this.error(e);
+                log("Emitted error", 3);
+
+            } finally {
+
+                log("Finished request", 0);
+            }
+
+        }, 0);
+
+        // this is the promise that the calling code will recieve and await
+        let promise = new Promise<void>((resolve, reject) => {
+
+            // we overwrite any pre-existing internal events as a
+            // given queryable only processes a single request at a time
+            this.on[this.InternalResolve].replace(resolve);
+            this.on[this.InternalReject].replace(reject);
+        });
+
+        // this allows us to internally hook the promise creation and modify it. This was introduced to allow for
+        // cancelable to work as envisioned, but may have other users. Meant for internal use in the library accessed via behaviors.
+        [promise] = this.emit[this.InternalPromise](promise);
+
+        return promise;
+    }
+}
+
+/**
+ * This interface adds the invokable method to Queryable allowing obj() to be called correctly
+ * The code is contained in invokable decorator
+ */
+// eslint-disable-next-line no-redeclare
+export interface Queryable<R = any> extends IInvokable<R> { }
+
+// this interface is required to stop the class from recursively referencing itself through the DefaultBehaviors type
+export interface IQueryableInternal<R = any> extends Timeline<any>, IInvokable {
+    readonly query: URLSearchParams;
+    <T = R>(this: IQueryableInternal, init?: RequestInit): Promise<T>;
+    using(...behaviors: TimelinePipe[]): this;
+    toRequestUrl(): string;
+    toUrl(): string;
+}

package/packages/queryable/request-builders.ts

@@ -0,0 +1,20 @@
+import { jsS } from "@pnp/core";
+
+/**
+ * takes the supplied object of type U, JSON.stringify's it, and sets it as the value of a "body" property
+ */
+export function body<T extends Partial<RequestInit>, U = any>(o: U, previous?: T): T & { body: string } {
+    return Object.assign({ body: jsS(o) }, previous);
+}
+
+/**
+ * Adds headers to an new/existing RequestInit
+ *
+ * @param o Headers to add
+ * @param previous Any previous partial RequestInit
+ * @returns RequestInit combining previous and specified headers
+ */
+// eslint-disable-next-line @typescript-eslint/ban-types
+export function headers<T extends Partial<RequestInit>, U extends Record<string, string> = {}>(o: U, previous?: T): T & { headers: U } {
+    return Object.assign({}, previous, { headers: { ...previous?.headers, ...o } });
+}

package/packages/queryable/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "extends": "../tsconfig.json",
+    "include": [
+        "./**/*.ts"
+    ],
+    "references": [
+        {
+            "path": "../core/tsconfig.json"
+        }
+    ]
+}

package/packages/readme.md

@@ -0,0 +1,21 @@
+![SharePoint Patterns and Practices](https://devofficecdn.azureedge.net/media/Default/PnP/sppnp.png)
+
+The SharePoint Patterns and Practices client side libraries were created to help enable developers to do their best work, without worrying about the exact
+REST api details. Built with feedback from the community they represent a way to simplify your day-to-day dev cycle while relying on tested and proven
+patterns.
+
+Please use [http://aka.ms/community/home](http://aka.ms/community/home) for the latest updates around the whole *Microsoft 365 and Power Platform Community(PnP)* initiative.
+## Source & Docs
+
+This code is managed within the [main pnp repo](https://github.com/pnp/pnpjs), please report issues and submit pull requests there.
+
+Please see the public site for [package documentation](https://pnp.github.io/pnpjs/).
+
+### Code of Conduct
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+### "Sharing is Caring"
+
+### Disclaimer
+**THIS CODE IS PROVIDED *AS IS* WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.**

package/packages/sp/appcatalog/index.ts

@@ -0,0 +1,35 @@
+import { SPFI } from "../fi.js";
+import { IWeb, Web } from "../webs/types.js";
+import { AppCatalog, IAppCatalog } from "./types.js";
+
+import "./web.js";
+
+export {
+    IAppAddResult,
+    IApp,
+    IAppCatalog,
+    App,
+    AppCatalog,
+} from "./types.js";
+
+declare module "../fi" {
+    interface SPFI {
+        tenantAppcatalog: IAppCatalog;
+        getTenantAppCatalogWeb(): Promise<IWeb>;
+    }
+}
+
+Reflect.defineProperty(SPFI.prototype, "tenantAppcatalog", {
+    configurable: true,
+    enumerable: true,
+    get: function (this: SPFI) {
+        return this.create(AppCatalog, "_api/web/tenantappcatalog/AvailableApps");
+    },
+});
+
+SPFI.prototype.getTenantAppCatalogWeb = async function (this: SPFI): Promise<IWeb> {
+
+    const data = await Web(this._root, "_api/SP_TenantSettings_Current")<{ CorporateCatalogUrl: string }>();
+
+    return Web([this._root, data.CorporateCatalogUrl]);
+};

package/packages/sp/appcatalog/types.ts

@@ -0,0 +1,176 @@
+import {
+    _SPCollection,
+    spInvokableFactory,
+    _SPInstance,
+    ISPQueryable,
+    SPCollection,
+} from "../spqueryable.js";
+import { spPost } from "../operations.js";
+import { odataUrlFrom } from "../utils/odata-url-from.js";
+import { extractWebUrl } from "../utils/extract-web-url.js";
+import { File, IFile } from "../files/types.js";
+import { combine } from "@pnp/core";
+import { defaultPath } from "../decorators.js";
+
+function getAppCatalogPath(base: string, path: string): string {
+
+    const paths = ["_api/web/tenantappcatalog/", "_api/web/sitecollectionappcatalog/"];
+
+    for (let i = 0; i < paths.length; i++) {
+        const index = base.indexOf(paths[i]);
+        if (index > -1) {
+            return combine(base.substring(index, index + paths[i].length), path);
+        }
+    }
+
+    return combine(base, path);
+}
+
+@defaultPath("_api/web/tenantappcatalog/AvailableApps")
+export class _AppCatalog extends _SPCollection {
+
+    constructor(base: string | ISPQueryable, path?: string) {
+        super(base, null);
+        this._url = combine(extractWebUrl(this._url), path);
+    }
+
+    /**
+     * Get details of specific app from the app catalog
+     * @param id - Specify the guid of the app
+     */
+    public getAppById(id: string): IApp {
+        return App(this, `getById('${id}')`);
+    }
+
+    /**
+     * Synchronize a solution to the Microsoft Teams App Catalog
+     * @param id - Specify the guid of the app
+     * @param useSharePointItemId (optional) - By default this REST call requires the SP Item id of the app, not the app id.
+     *                            PnPjs will try to fetch the item id, you can still use this parameter to pass your own item id in the first parameter
+     */
+    public async syncSolutionToTeams(id: string | number, useSharePointItemId = false): Promise<void> {
+
+        // This REST call requires that you refer the list item id of the solution in the app catalog site.
+        let appId = null;
+        const webUrl = combine(extractWebUrl(this.toUrl()), "_api/web");
+
+        if (useSharePointItemId) {
+
+            appId = id;
+
+        } else {
+
+            const listId = (await SPCollection([this, webUrl], "lists").select("Id").filter("EntityTypeName eq 'AppCatalog'")<{ Id: string }[]>())[0].Id;
+            const listItems = await SPCollection([this, webUrl], `lists/getById('${listId}')/items`).select("Id").filter(`AppProductID eq '${id}'`).top(1)();
+
+            if (listItems && listItems.length > 0) {
+
+                appId = listItems[0].Id;
+
+            } else {
+
+                throw Error(`Did not find the app with id ${id} in the appcatalog.`);
+            }
+        }
+
+        return spPost(AppCatalog(this, getAppCatalogPath(this.toUrl(), `SyncSolutionToTeams(id=${appId})`)));
+    }
+
+    /**
+     * Uploads an app package. Not supported for batching
+     *
+     * @param filename Filename to create.
+     * @param content app package data (eg: the .app or .sppkg file).
+     * @param shouldOverWrite Should an app with the same name in the same location be overwritten? (default: true)
+     * @returns Promise<IAppAddResult>
+     */
+    public async add(filename: string, content: string | ArrayBuffer | Blob, shouldOverWrite = true): Promise<IAppAddResult> {
+
+        // you don't add to the availableapps collection
+        const adder = AppCatalog(this, getAppCatalogPath(this.toUrl(), `add(overwrite=${shouldOverWrite},url='${filename}')`));
+
+        const r = await spPost(adder, {
+            body: content, headers: {
+                "binaryStringRequestBody": "true",
+            },
+        });
+
+        return {
+            data: r,
+            file: File([this, odataUrlFrom(r)]),
+        };
+    }
+}
+export interface IAppCatalog extends _AppCatalog { }
+export const AppCatalog = spInvokableFactory<IAppCatalog>(_AppCatalog);
+
+export class _App extends _SPInstance {
+
+    /**
+     * This method deploys an app on the app catalog. It must be called in the context
+     * of the tenant app catalog web or it will fail.
+     *
+     * @param skipFeatureDeployment Deploy the app to the entire tenant
+     */
+    public deploy(skipFeatureDeployment = false): Promise<void> {
+        return this.do(`Deploy(${skipFeatureDeployment})`);
+    }
+
+    /**
+     * This method retracts a deployed app on the app catalog. It must be called in the context
+     * of the tenant app catalog web or it will fail.
+     */
+    public retract(): Promise<void> {
+        return this.do("Retract");
+    }
+
+    /**
+     * This method allows an app which is already deployed to be installed on a web
+     */
+    public install(): Promise<void> {
+        return this.do("Install");
+    }
+
+    /**
+     * This method allows an app which is already installed to be uninstalled on a web
+     * Note: when you use the REST API to uninstall a solution package from the site, it is not relocated to the recycle bin
+     */
+    public uninstall(): Promise<void> {
+        return this.do("Uninstall");
+    }
+
+    /**
+     * This method allows an app which is already installed to be upgraded on a web
+     */
+    public upgrade(): Promise<void> {
+        return this.do("Upgrade");
+    }
+
+    /**
+     * This method removes an app from the app catalog. It must be called in the context
+     * of the tenant app catalog web or it will fail.
+     */
+    public remove(): Promise<void> {
+        return this.do("Remove");
+    }
+
+    private do(path: string): Promise<void> {
+        return spPost(App(this, path));
+    }
+}
+export interface IApp extends _App { }
+export const App = spInvokableFactory<IApp>(_App);
+
+/**
+ * Result object after adding an app
+ */
+export interface IAppAddResult {
+    /**
+     * Contains metadata of the added app
+     */
+    data: any;
+    /**
+     * A File instance to the item in SharePoint
+     */
+    file: IFile;
+}

package/packages/sp/appcatalog/web.ts

@@ -0,0 +1,19 @@
+import { addProp } from "@pnp/queryable";
+import { _Web } from "../webs/types.js";
+import { AppCatalog, IAppCatalog } from "./types.js";
+
+declare module "../webs/types" {
+    interface _Web {
+        appcatalog: IAppCatalog;
+    }
+    interface IWeb {
+        /**
+         * Gets the appcatalog (if it exists associated with this web)
+         */
+        appcatalog: IAppCatalog;
+    }
+}
+
+// we use this function to wrap the AppCatalog as we want to ignore any path values addProp
+// will pass and use the defaultPath defined for AppCatalog
+addProp(_Web, "appcatalog", (s: _Web) => AppCatalog(s, "_api/web/sitecollectionappcatalog/AvailableApps"));

package/packages/sp/attachments/index.ts

@@ -0,0 +1,11 @@
+import "./item.js";
+
+export {
+    IAttachment,
+    IAttachments,
+    Attachment,
+    Attachments,
+    IAttachmentAddResult,
+    IAttachmentFileInfo,
+    IAttachmentInfo,
+} from "./types.js";

package/packages/sp/attachments/item.ts

@@ -0,0 +1,17 @@
+import { addProp } from "@pnp/queryable";
+import { _Item } from "../items/types.js";
+import { Attachments, IAttachments } from "./types.js";
+
+declare module "../items/types" {
+    interface _Item {
+        readonly attachmentFiles: IAttachments;
+    }
+    interface IItem {
+        /**
+         * Read the attachment files data for an item
+         */
+        readonly attachmentFiles: IAttachments;
+    }
+}
+
+addProp(_Item, "attachmentFiles", Attachments);

package/packages/sp/attachments/types.ts

@@ -0,0 +1,95 @@
+import { headers } from "@pnp/queryable";
+import { defaultPath } from "../decorators.js";
+import { ReadableFile } from "../files/readable-file.js";
+import { spPost } from "../operations.js";
+import { encodePath } from "../utils/encode-path-str.js";
+import {
+    IDeleteableWithETag,
+    _SPCollection,
+    spInvokableFactory,
+    deleteableWithETag,
+} from "../spqueryable.js";
+
+@defaultPath("AttachmentFiles")
+export class _Attachments extends _SPCollection<IAttachmentInfo[]> {
+
+    /**
+    * Gets a Attachment File by filename
+    *
+    * @param name The name of the file, including extension.
+    */
+    public getByName(name: string): IAttachment {
+        const f = Attachment(this);
+        f.concat(`('${name}')`);
+        return f;
+    }
+
+    /**
+     * Adds a new attachment to the collection. Not supported for batching.
+     *
+     * @param name The name of the file, including extension.
+     * @param content The Base64 file content.
+     */
+    public async add(name: string, content: string | Blob | ArrayBuffer): Promise<IAttachmentAddResult> {
+        const response = await spPost(Attachments(this, `add(FileName='${encodePath(name)}')`), { body: content });
+        return {
+            data: response,
+            file: this.getByName(name),
+        };
+    }
+}
+export interface IAttachments extends _Attachments { }
+export const Attachments = spInvokableFactory<IAttachments>(_Attachments);
+
+export class _Attachment extends ReadableFile<IAttachmentInfo> {
+
+    public delete = deleteableWithETag();
+
+    /**
+     * Sets the content of a file. Not supported for batching
+     *
+     * @param content The value to set for the file contents
+     */
+    public async setContent(body: string | ArrayBuffer | Blob): Promise<IAttachment> {
+
+        await spPost(Attachment(this, "$value"), headers({ "X-HTTP-Method": "PUT" }, { body }));
+
+        return this;
+    }
+
+    /**
+     * Delete this attachment file and send it to recycle bin
+     *
+     * @param eTag Value used in the IF-Match header, by default "*"
+     */
+    public recycle(eTag = "*"): Promise<void> {
+
+        return spPost(Attachment(this, "recycleObject"), headers({
+            "IF-Match": eTag,
+            "X-HTTP-Method": "DELETE",
+        }));
+    }
+}
+export interface IAttachment extends _Attachment, IDeleteableWithETag { }
+export const Attachment = spInvokableFactory<IAttachment>(_Attachment);
+
+export interface IAttachmentAddResult {
+    file: IAttachment;
+    data: IAttachmentFileInfo;
+}
+
+export interface IAttachmentFileInfo {
+    name: string;
+    content: string | Blob | ArrayBuffer;
+}
+
+export interface IAttachmentInfo {
+    FileName: string;
+    FileNameAsPath: {
+        DecodedUrl: string;
+    };
+    ServerRelativePath: {
+        DecodedUrl: string;
+    };
+    ServerRelativeUrl: string;
+}