Moving from 2.0.* to 3.0.*

This article discusses a beta version. Parts of this may change BEFORE the 3.0.0 release. It is not recommended to upgrade your production projects to 3.0.0 until the release.

The transition from 2 -> 3 versions of the library is disruptive, but we have made these changes with an eye to reducing future pain as we expand. This article outlines all of the changes that are externally visible and maps the previous to new way of doing things to try and make transitioning easier. We recognize updates like this create work on your end - but there is no immediate need to upgrade unless you need MS Graph support or are blocked by a bug fix contained in a 3.0.* version. We will also be updating the other main articles after the release to match these changes. As always feedback is welcome and appreciated.

Breaking Changes

This section outlines those changes that will break your code if you are using particular classes or patterns. Please review each change to see if it applies to you.

Configuration Interface Update

We have updated the configuration interface to split the SharePoint and MS Graph configurations. This is to make it clear what settings you are applying and take the area specific settings out of the global namespace. The properties on the internal RuntimeConfig class were renamed as appropriate.

New Interface Definition

export interface LibraryConfiguration {

    /**
     * Allows caching to be global disabled, default: false
     */
    globalCacheDisable?: boolean;

    /**
     * Defines the default store used by the usingCaching method, default: session
     */
    defaultCachingStore?: "session" | "local";

    /**
     * Defines the default timeout in seconds used by the usingCaching method, default 30
     */
    defaultCachingTimeoutSeconds?: number;

    /**
     * If true a timeout expired items will be removed from the cache in intervals determined by cacheTimeoutInterval
     */
    enableCacheExpiration?: boolean;

    /**
     * Determines the interval in milliseconds at which the cache is checked to see if items have expired (min: 100)
     */
    cacheExpirationIntervalMilliseconds?: number;

    /**
     * SharePoint specific library settings
     */
    sp?: {

        /**
         * Any headers to apply to all requests
         */
        headers?: TypedHash<string>;

        /**
         * Defines a factory method used to create fetch clients
         */
        fetchClientFactory?: () => HttpClientImpl;

        /**
         * The base url used for all requests
         */
        baseUrl?: string;
    };

    /**
     * MS Graph specific library settings
     */
    graph?: {

        /**
         * Any headers to apply to all requests
         */
        headers?: TypedHash<string>;

        /**
         * Defines a factory method used to create fetch clients
         */
        fetchClientFactory?: () => GraphHttpClientImpl;
    };

    /**
     * Used to supply the current context from an SPFx webpart to the library
     */
    spfxContext?: any;
}

Example

pnp.setup({

    sp: {
        baseUrl: "https://mytenant.sharepoint.com/sites/dev",
        headers: {
            "Header1": "Header1Value"

        },
    },

    graph: {
        headers: {
            "Header2": "Header2Value"
        }
    }
});

Renamed Exports

The following classes and functions were renamed as they are SharePoint specific. It is likely you are not using these directly but please review your code. This would apply especially if you are creating your own entities for use with getAs.

• ODataEntity => spODataEntity
• ODataEntityArray => spODataEntityArray
• extractODataId => spExtractODataId
• getEntityUrl => spGetEntityUrl

Exports refactoring

Taking a look at our exports we had filled the global pnp space with many types. This would eventually cause overlap as we add Graph support and potentially other endpoints. We have moved the exports to a sub-path with specific namespaces. Note in the Beta.0 release this removes all exports from the global space meaning they are NOT available to code running in script tags. We are looking at options to address this for the final release. This is a disruptive change and we welcome feedback.

Old

import { Web } from "sp-pnp-js";

New

There are currently 5 export namespaces "sp", "graph", "core", "odata", and "net"

import { Web } from "sp-pnp-js/exports/sp";
import { Util } from "sp-pnp-js/exports/core";

Queryable Generification

To support the graph work we have consolidated to a shared Queryable base class. This necessitated a rename of the existing Queryable to SharePointQueryable.

• Queryable is now a generic and exported under the /exports/odata namespace
• The previous Queryable* classes are renamed to SharePointQueryable* and are exported under /exports/sp
• The new classes for graph are GraphQueryable* and exported under /exports/graph

Non-breaking Changes

Graph Support

This release adds initial support for calling MS Graph through the SPFx GraphHttpClient. You can access the methods from the "graph" property from the root.

pnp.graph.groups.get().then({ 
  //...
});

Remove Locale.ts

Please see this page if you need to reference or use this enum.

Change to .clone behavior

The internally used clone method was updated to include the batch by default. Saving a lot of "true" literals within the code.

Locked package.json versions

The "^" was removed from all versions in package.json. This will avoid the cases where minor updates to dependencies resulted in breaking changes for folks. The dependencies will be updated with each release to the latest available at that time. This allows proper testing of new versions and removes the element of surprise.