@salesforce/lds-store-binary 1.100.1

package/LICENSE.txt

@@ -0,0 +1,82 @@
+Terms of Use
+
+Copyright 2022 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this
+software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were
+last updated on April 15, 2022, and constitute a legally binding
+agreement between you and Salesforce. If you do not agree to these Terms of
+Use, do not install or use the Software.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free
+copyright license to reproduce, prepare derivative works of, publicly
+display, publicly perform, sublicense, and distribute the Software and
+derivative works subject to these Terms. These Terms shall be included in
+all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce
+reserves all rights, title, and interest in and to all intellectual
+property subsisting in the Software. No rights are granted to you hereunder
+other than as expressly set forth herein. Users residing in countries on
+the United States Office of Foreign Assets Control sanction list, or which
+are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you
+are responsible. The Software may contain bugs, errors and
+incompatibilities and is made available on an AS IS basis without support,
+updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or
+discontinue, the Software (or any part thereof) with or without notice. You
+agree that Salesforce shall not be liable to you or to any third party for
+any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or
+proceeding made or brought against Salesforce by a third party arising out
+of or accruing from (a) your use of the Software, and (b) any application
+you develop with the Software that infringes any copyright, trademark,
+trade secret, trade dress, patent, or other intellectual property right of
+any person or defames any person or violates their rights of publicity or
+privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce
+from any damages, attorney fees, and costs finally awarded against
+Salesforce as a result of, or for any amounts paid by Salesforce under a
+settlement approved by you in writing of, a Claim Against Salesforce,
+provided Salesforce (x) promptly gives you written notice of the Claim
+Against Salesforce, (y) gives you sole control of the defense and
+settlement of the Claim Against Salesforce (except that you may not settle
+any Claim Against Salesforce unless it unconditionally releases Salesforce
+of all liability), and (z) gives you all reasonable assistance, at your
+expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT
+SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES,
+INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
+PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA,
+OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN
+CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU
+HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of
+the State of California, without regard to its conflicts of laws
+rules. Each party hereby consents to the exclusive jurisdiction of the
+state and federal courts located in San Francisco County, California to
+adjudicate any dispute arising out of or relating to these Terms of Use and
+the download, installation, and/or use of the Software. Except as expressly
+stated herein, these Terms of Use constitute the entire agreement between
+the parties, and supersede all prior and contemporaneous agreements,
+proposals, or representations, written or oral, concerning their subject
+matter. No modification, amendment, or waiver of any provision of these
+Terms of Use shall be effective unless it is by an update to these Terms of
+Use that Salesforce makes available, or is in writing and signed by the
+party against whom the modification, amendment, or waiver is to be
+asserted.
+
+Data Privacy: Salesforce may collect, process, and store device,
+system, and other information related to your use of the Software. This
+information includes, but is not limited to, IP address, user metrics, and
+other data ("Usage Data"). Salesforce may use Usage Data for analytics,
+product development, and marketing purposes. You acknowledge that files
+generated in conjunction with the Software may contain sensitive or
+confidential data, and you are solely responsible for anonymizing and
+protecting such data.

package/dist/BinaryStore.d.ts

@@ -0,0 +1,124 @@
+/**
+ * An object that sets options for the get operation.  Loosely based on
+ * https://developer.mozilla.org/en-US/docs/Web/API/Cache/match#options
+ */
+export interface GetOptions {
+    /**
+     * A boolean value that specifies whether to ignore the query string in the
+     * URL as a fallback when an exact match isn't found in the cache.
+     *
+     * It defaults to false.
+     *
+     * Ignoring the query string means everything after a "?" in the URI
+     * will be ignored. For example, if set to true the ?value=bar part of
+     * http://foo.com/?value=bar would be ignored when performing a fallback match.
+     *
+     * Cache lookup behavior when set to true:
+     * 1. If there is an exact match (ie: URI including query string) in the cache
+     * that will be returned.
+     * 2. If that is not present then the first non-exact match (ie: URI ignoring
+     * query string) will be returned while the exact match is retrieved in the
+     * background (a sort-of "fallback-while-revalidate" cache policy).  Note that
+     * a background download of the exact match will only happen if the fallback entry
+     * has a remote (ie: canonical) URL (because you can't "download" from a local URI).
+     * 3. If a fallback match is not present then null will be returned.
+     */
+    ignoreQueryFallback: boolean;
+}
+/**
+ * An interface for interacting with a store for binary files.
+ *
+ * Implementation Notes:
+ *
+ * The BinaryStore can be used as a "store" where the file in the store is the only
+ * copy and there is essentially no expiration (the file is never stale). Or it can be
+ * used as a "cache" where the canonical copy of the file exists somewhere else (like
+ * on a remote server).
+ *
+ * The caching behavior should follow the "stale-while-revalidate" pattern, where
+ * a cached file (which has a non-null expiration and a canonical URI) should always
+ * return the cached version, and if the file is past expiration (ie: "stale") then
+ * the implementation should attempt to re-downloaded the file from the canonical
+ * URL in the background.
+ *
+ * Implementations should adhere to the following requirements:
+ *   - if {@link get} is called for a stale binary file then return the stale
+ *     file to the caller and attempt to download the latest version of the file
+ *     from the canonical URL in the background.
+ */
+export interface BinaryStore {
+    /**
+     * Stores a binary file in the store.  The file will not have a TTL. This is
+     * meant to store local-only files.
+     *
+     * @param data The data of the binary file to put into the store.
+     * @param type The MIME type of the binary file. Ex: "image/png".
+     * @param size The number of bytes of data contained within the file.
+     * @returns A Promise of a string representing the URI of the binary file. NOTE: the URI
+     *          to a binary file should be treated as opaque (only use it to pass into methods
+     *          on this interface).
+     */
+    store(data: Uint8Array, type: string, size: number): Promise<string>;
+    /**
+     * Caches a binary file in the store.  This is meant to locally cache a file
+     * thats source-of-truth exists at the given URL.
+     *
+     * If the file is unable to be downloaded this will return a rejected promise
+     * of an {@link Error}.
+     *
+     * This method should return a URI to the file, which may or may not be the
+     * same as the remote URL. In other words, the URI returned to callers should
+     * be treated as opaque by the callers.
+     *
+     * @param url The URL of the file.
+     * @param ttlSeconds The TTL in seconds for this file.  The file's expiration
+     *        should be calculated by Date.now + ttlSeconds.
+     * @returns A Promise of a string representing the URI of the binary file. NOTE: the URI
+     *          to a binary file should be treated as opaque (only use it to pass into methods
+     *          on this interface).
+     */
+    cache(url: string, ttlSeconds: number): Promise<string>;
+    /**
+     * Gets the binary file given its URI.
+     *
+     * @param uri The URI of the binary file
+     * @returns A Promise of the data of the binary file, or null if not present. If the file
+     *          is stale then the stale file will be returned and a network request to re-download
+     *          the latest version of the file will be kicked off (ie: stale-while-revalidate).
+     */
+    get(uri: string, options?: GetOptions): Promise<Uint8Array | null>;
+    /**
+     * Deletes the binary file given its URI. If the file doesn't exist this
+     * method will do nothing.
+     *
+     * @param uri The URI of the binary file
+     * @returns A Promise that is resolved once the binary file is removed from
+     *          the store.
+     */
+    delete(uri: string): Promise<void>;
+    /**
+     * Set the canonical URL for the file at the given uri.  The file will immediately
+     * be marked as stale (since we know the file's source of truth has changed).
+     *
+     * If there is no file at the given URI then this method will immediately cache
+     * the file at the canonicalUrl (essentially the same as calling {@link cache}).
+     *
+     * This method should return a URI to the file, which may or may not be
+     * different from the original URI, and may or may not be the same as the
+     * canonicalUrl. In other words, the URI returned to callers should be treated
+     * as opaque by the callers.
+     *
+     * This will most commonly be called by code that knows that the local file at the
+     * URI has been uploaded to a server and knows the new canonical URL to that file.
+     *
+     * @param uri The URI of the existing, local binary file
+     * @param canonicalUrl The new, canonical URL (a URL is a type of URI) of the file
+     * @param ttlSeconds The TTL in seconds for this file.  The file's expiration
+     *        should be calculated by Date.now + ttlSeconds.
+     * @returns The new URI to the file, which may or may not be the same as canonicalUrl
+     *          (some hybrid implementations might pass back a custom protocol-based URI
+     *          different from the canonicalUrl, remember that callers should treat URIs
+     *          as opaque).
+     */
+    setCanonicalUrl(uri: string, canonicalUrl: string, ttlSeconds: number): Promise<string>;
+}

package/dist/BinaryStore.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=BinaryStore.js.map

package/dist/BinaryStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BinaryStore.js","sourceRoot":"","sources":["../src/BinaryStore.ts"],"names":[],"mappings":""}

package/dist/InMemoryBinaryStore.d.ts

@@ -0,0 +1,20 @@
+import type { BinaryStore, GetOptions } from './BinaryStore';
+/**
+ * A simple in-memory implementation of BinaryStore interface.  Useful for
+ * testing/debugging.
+ */
+export declare class InMemoryBinaryStore implements BinaryStore {
+    private readonly networkAdapter;
+    private counter;
+    private fileInfoMap;
+    private buildUniqueUri;
+    constructor(networkAdapter: (uri: string) => Promise<{
+        data: Uint8Array;
+        type: string;
+    }>);
+    store(data: Uint8Array, type: string, size: number): Promise<string>;
+    cache(url: string, ttlSeconds: number): Promise<string>;
+    get(uri: string, options?: GetOptions): Promise<Uint8Array | null>;
+    delete(uri: string): Promise<void>;
+    setCanonicalUrl(uri: string, canonicalUrl: string, ttlSeconds: number): Promise<string>;
+}

package/dist/InMemoryBinaryStore.js

@@ -0,0 +1,114 @@
+/**
+ * A simple in-memory implementation of BinaryStore interface.  Useful for
+ * testing/debugging.
+ */
+export class InMemoryBinaryStore {
+    // going to use valid URLs for our local URIs so that we can leverage
+    // the URL class when we need to strip off query params
+    buildUniqueUri() {
+        return `inmemorybinarystore://${this.counter++}`;
+    }
+    constructor(networkAdapter) {
+        this.networkAdapter = networkAdapter;
+        this.counter = 0;
+        this.fileInfoMap = new Map();
+    }
+    async store(data, type, size) {
+        const uri = this.buildUniqueUri();
+        this.fileInfoMap.set(uri, {
+            data,
+            type,
+            size,
+            canonicalUrl: null,
+            ttlSeconds: null,
+            expiration: null,
+        });
+        return uri;
+    }
+    async cache(url, ttlSeconds) {
+        const { data, type } = await this.networkAdapter(url);
+        const uri = this.buildUniqueUri();
+        this.fileInfoMap.set(uri, {
+            data,
+            type,
+            size: data.length,
+            canonicalUrl: url,
+            ttlSeconds,
+            expiration: Date.now() + ttlSeconds * 1000,
+        });
+        return uri;
+    }
+    async get(uri, options) {
+        const fileInfo = this.fileInfoMap.get(uri);
+        if (fileInfo !== undefined) {
+            const { expiration, canonicalUrl, ttlSeconds, data } = fileInfo;
+            if (expiration !== null &&
+                canonicalUrl !== null &&
+                ttlSeconds !== null &&
+                expiration > Date.now()) {
+                // if expired then refresh in background
+                this.networkAdapter(canonicalUrl).then(({ data: refreshedData, type }) => {
+                    this.fileInfoMap.set(uri, {
+                        ...fileInfo,
+                        data: refreshedData,
+                        type,
+                        size: refreshedData.length,
+                        expiration: Date.now() + ttlSeconds * 1000,
+                    });
+                });
+            }
+            return data;
+        }
+        // fallback to ignoreQuery match if requested
+        if (options && options.ignoreQueryFallback === true) {
+            const asUrl = new URL(uri);
+            const originalSearchString = asUrl.search;
+            // set the URL search to empty as an easy way to strip query string
+            asUrl.search = '';
+            const noQuery = asUrl.toString();
+            const noQueryMatch = this.fileInfoMap.get(noQuery);
+            if (noQueryMatch !== undefined) {
+                // if the non-exact match has a canonicalUrl then attempt to get
+                // exact match from network in background
+                const { canonicalUrl, ttlSeconds, data } = noQueryMatch;
+                if (canonicalUrl !== null && ttlSeconds !== null) {
+                    const refreshUrl = new URL(canonicalUrl);
+                    refreshUrl.search = originalSearchString;
+                    const refreshCanonicalUrl = refreshUrl.toString();
+                    this.networkAdapter(refreshCanonicalUrl).then(({ data: refreshedData, type }) => {
+                        this.fileInfoMap.set(uri, {
+                            canonicalUrl: refreshCanonicalUrl,
+                            ttlSeconds,
+                            data: refreshedData,
+                            type,
+                            size: refreshedData.length,
+                            expiration: Date.now() + ttlSeconds * 1000,
+                        });
+                    });
+                }
+                return data;
+            }
+        }
+        return null;
+    }
+    async delete(uri) {
+        this.fileInfoMap.delete(uri);
+    }
+    async setCanonicalUrl(uri, canonicalUrl, ttlSeconds) {
+        const fileInfo = this.fileInfoMap.get(uri);
+        // if the local file doesn't exist treat this same as calling "cache"
+        if (fileInfo === undefined) {
+            return this.cache(canonicalUrl, ttlSeconds);
+        }
+        // else update the canonicalUrl and expiration info
+        this.fileInfoMap.set(uri, {
+            ...fileInfo,
+            canonicalUrl,
+            ttlSeconds,
+            // immediately expire
+            expiration: Date.now() - 1,
+        });
+        return uri;
+    }
+}
+//# sourceMappingURL=InMemoryBinaryStore.js.map

package/dist/InMemoryBinaryStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryBinaryStore.js","sourceRoot":"","sources":["../src/InMemoryBinaryStore.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { BinaryStore, GetOptions } from './BinaryStore';
+export { InMemoryBinaryStore } from './InMemoryBinaryStore';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { InMemoryBinaryStore } from './InMemoryBinaryStore';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}

package/package.json

@@ -0,0 +1,24 @@
+{
+    "name": "@salesforce/lds-store-binary",
+    "version": "1.100.1",
+    "license": "SEE LICENSE IN LICENSE.txt",
+    "description": "Interface for interacting with a binary file store/cache",
+    "types": "dist/index.d.ts",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "prepare": "yarn build",
+        "clean": "rm -rf dist",
+        "build": "tsc"
+    }
+}