@amazon/vinyl-util 1.0.0

package/dist/types/current/patch/patchTarget.js

@@ -0,0 +1,219 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createDisposer, DisposedError, } from '../core/disposable';
+import { IllegalArgumentError } from '../error/IllegalArgumentError';
+import { EventHostImpl } from '../event/EventHost';
+import { emptySignal, SignalImpl } from '../event/Signal';
+import { logDebug } from '../logging/Logger';
+import { createLogPrefix } from '../logging/LogTarget';
+/**
+ * Creates a Proxy for patched event and properties on the target. All patches from the provided
+ * factory list will be used in creating a proxy chain. Each patch is applied in order, and
+ * patches can rely on their target having been patched with all previous patches.
+ *
+ * @param target
+ * @param patchFactories A list of factories that each produce a new patch for the target.
+ * @return Returns a disposable object with a Proxy reference with overridden event and property
+ * behavior. When disposed, the event listeners are removed.
+ */
+export function patchTarget(target, ...patchFactories) {
+    const n = patchFactories.length;
+    if (n === 0) {
+        // Not patched
+        let disposed = false;
+        return {
+            patched: target,
+            eventFabricated: emptySignal,
+            eventSquelched: emptySignal,
+            dispose: () => {
+                // For consistency:
+                if (disposed)
+                    throw new DisposedError();
+                disposed = true;
+            },
+        };
+    }
+    else if (n === 1) {
+        return _patchTarget(target, patchFactories[0]);
+    }
+    else {
+        const { add, dispose } = createDisposer();
+        let patched = target;
+        const eventFabricated = add(new SignalImpl());
+        const eventSquelched = add(new SignalImpl());
+        const patchedChain = [];
+        patchFactories.forEach((factory) => {
+            const next = patchTarget(patched, factory);
+            patched = next.patched;
+            patchedChain.push(next);
+            next.eventFabricated.listen((event) => eventFabricated.dispatch(event));
+            next.eventSquelched.listen((event) => eventSquelched.dispatch(event));
+        });
+        // Patches must be disposed in reverse order
+        for (let i = patchedChain.length - 1; i >= 0; i--) {
+            add(patchedChain[i]);
+        }
+        return {
+            patched,
+            eventFabricated,
+            eventSquelched,
+            dispose,
+        };
+    }
+}
+/**
+ * Creates a proxy to an event target that can patch properties and events.
+ *
+ * There are no modifications to the target, the returned proxy should be used in place of the
+ * target.
+ *
+ * @param target
+ * @param patchFactory Produces a new patch for the target.
+ * @return Returns a disposable object with a Proxy reference with overridden event and property
+ * behavior. When disposed, event listeners will be removed and the created patch and proxy will
+ * be disposed.
+ */
+function _patchTarget(target, patchFactory) {
+    const { add, dispose } = createDisposer();
+    const eventFabricated = add(new SignalImpl());
+    const eventSquelched = add(new SignalImpl());
+    // This method takes a factory instead of the EventTargetPatch directly to ensure that the
+    // patch disposal is handled with the proxy disposal.
+    const patch = add(patchFactory(target));
+    // An event target used in place of the original target for patched events.
+    const proxyEventHost = add(new EventHostImpl());
+    patch.eventFabricated?.listen((event) => {
+        eventFabricated.dispatch(event);
+        proxyEventHost.dispatch(event.type, event);
+    });
+    const delegatedEvents = new Set();
+    const subs = new Map();
+    let addEventListener = undefined;
+    let removeEventListener = undefined;
+    if (isEventTarget(target)) {
+        if (patch.events || patch.eventFabricated) {
+            const eventPatches = patch.events ?? {};
+            const observeTargetEvent = (type) => {
+                if (!delegatedEvents.has(type)) {
+                    delegatedEvents.add(type);
+                    const targetHandler = (event) => {
+                        const patchedEvent = event.type in eventPatches
+                            ? eventPatches[event.type](event)
+                            : event;
+                        if (patchedEvent)
+                            proxyEventHost.dispatch(patchedEvent.type, patchedEvent);
+                        else
+                            eventSquelched.dispatch(event);
+                    };
+                    target.addEventListener(type, targetHandler);
+                }
+            };
+            addEventListener = (type, callback, options) => {
+                if (typeof callback !== 'function')
+                    throw new IllegalArgumentError('only function callbacks are supported');
+                observeTargetEvent(type);
+                subs.set(callback, proxyEventHost.on(type, callback, {
+                    once: typeof options === 'object'
+                        ? (options.once ?? false)
+                        : false,
+                }));
+            };
+            removeEventListener = (_, callback) => {
+                if (typeof callback !== 'function')
+                    throw new IllegalArgumentError('only function callbacks are supported');
+                const sub = subs.get(callback);
+                if (sub) {
+                    subs.delete(callback);
+                    sub();
+                }
+            };
+            for (const eventPatchesKey in eventPatches) {
+                observeTargetEvent(eventPatchesKey);
+            }
+        }
+        else {
+            addEventListener = target.addEventListener.bind(target);
+            removeEventListener = target.removeEventListener.bind(target);
+        }
+    }
+    const propertyPatches = patch.properties ?? {};
+    const patched = new Proxy(target, {
+        get(target, p, receiver) {
+            const key = p;
+            if (key === 'addEventListener') {
+                return addEventListener;
+            }
+            else if (key === 'removeEventListener') {
+                return removeEventListener;
+            }
+            const patch = propertyPatches[key];
+            const value = patch && patch.get ? patch.get() : target[key];
+            if (typeof value === 'function') {
+                // Redirect the receiver from the Proxy to the target.
+                // While it may make more sense to just use the Proxy as the receiver (Liskov
+                // substitution principle), HTML DOM methods oddly have checks that enforce that the
+                // receiver is strictly the Element.
+                return function (...args) {
+                    return value.apply(this === receiver ? target : this, args);
+                };
+            }
+            return value;
+        },
+        set(target, p, newValue) {
+            const key = p;
+            const patch = propertyPatches[key];
+            if (patch && patch.set)
+                patch.set(newValue);
+            else
+                target[key] = newValue;
+            return true;
+        },
+    });
+    return {
+        patched,
+        eventFabricated,
+        eventSquelched,
+        // Certain supported platforms do not support Proxy.revocable, but this is not a
+        // requirement; we do not need to provide a Proxy to a consumer that needs its
+        // lifespan controlled.
+        dispose,
+    };
+}
+/**
+ * Logs debug messages when an event was squelched or fabricated.
+ *
+ * @param pathTarget
+ * @param patched
+ * @return Returns a function that when invoked, removes the logging.
+ */
+export function logPatchedEvents(pathTarget, patched) {
+    const eventSquelchedSub = patched.eventSquelched.listen((event) => logDebug(pathTarget, `'${event.type}' event squelched`));
+    const eventFabricatedSub = patched.eventFabricated.listen((event) => logDebug(pathTarget, `'${event.type}' event fabricated`));
+    return () => {
+        eventSquelchedSub();
+        eventFabricatedSub();
+    };
+}
+function isEventTarget(target) {
+    return 'addEventListener' in target;
+}
+/**
+ * Given a list of [flagKey, patchFactory] tuples, patches the target with patches where flag is true.
+ */
+export function patchTargetFromFlags(target, flags, ...patchEntries) {
+    const pathTarget = {
+        logPrefix: createLogPrefix('Patch'),
+    };
+    const filtered = patchEntries.filter(([key]) => {
+        const enabled = flags[key] === true;
+        if (enabled)
+            logDebug(pathTarget, `Applying '${String(key)}' patch`);
+        return enabled;
+    });
+    const patchedRef = patchTarget(target, ...filtered.map(([_, factory]) => factory));
+    // Logs fabricated and squelched events.
+    logPatchedEvents(pathTarget, patchedRef);
+    return patchedRef;
+}

package/dist/types/current/persistence/KeyValuePersistence.d.ts

@@ -0,0 +1,28 @@
+/**
+ * An abstract persistence interface for an async key / value store.
+ */
+export interface KeyValuePersistence<T> {
+    /**
+     * Resolves to the value for the given key, or null if non-existent.
+     * @param key
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Saves the given value to disk.
+     *
+     * @param key
+     * @param value
+     */
+    set(key: string, value: T): Promise<void>;
+    /**
+     * Removes the given key.
+     *
+     * @param key
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Clears all items.
+     */
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=KeyValuePersistence.d.ts.map

package/dist/types/current/persistence/KeyValuePersistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyValuePersistence.d.ts","sourceRoot":"","sources":["../../../../src/persistence/KeyValuePersistence.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IAClC;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IAEnC;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzC;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB"}

package/dist/types/current/persistence/KeyValuePersistence.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/types/current/persistence/PersistentItem.d.ts

@@ -0,0 +1,86 @@
+import type { LogTarget } from '../logging/LogTarget';
+import type { KeyValuePersistence } from '../persistence/KeyValuePersistence';
+import type { Maybe } from '../util/type';
+/**
+ * Configuration for PersistentItemImpl
+ * These values will not be accessed until the persistent item is first used.
+ */
+export interface PersistentItemOptions<T, FormatType> {
+    /**
+     * The key to use in the Persistence layer.
+     */
+    readonly key: string;
+    /**
+     * The default to use when the key is not present or deserialization fails.
+     */
+    readonly defaultValue: T;
+    /**
+     * If provided, will be invoked on the persisted value.
+     */
+    readonly validator?: Maybe<(input: unknown) => asserts input is T>;
+    /**
+     * The key/value persistence raw data provider.
+     *
+     * Provides the KeyValuePersistence controller.
+     * Can be a method to lazily provide the controller, will be invoked once on first access.
+     */
+    readonly persistence: KeyValuePersistence<FormatType> | (() => KeyValuePersistence<FormatType>);
+    /**
+     * Serializes the value for persistence.
+     */
+    readonly serialize: (value: T) => FormatType;
+    /**
+     * Deserializes value into the output value.
+     */
+    readonly deserialize: (value: FormatType) => T;
+}
+export interface PersistentItem<T> {
+    /**
+     * Gets this item from persistence.
+     */
+    get(): Promise<T>;
+    /**
+     * Saves this item to persistence.
+     */
+    set(value: T): Promise<void>;
+    /**
+     * Removes this item from persistence.
+     */
+    remove(): Promise<void>;
+}
+export declare class PersistentItemImpl<T, FormatType> implements PersistentItem<T>, LogTarget {
+    private readonly options;
+    readonly logPrefix: string;
+    private readonly persistence;
+    constructor(options: PersistentItemOptions<T, FormatType>);
+    /**
+     * Gets this item from persistence.
+     */
+    get(): Promise<T>;
+    /**
+     * Saves this item to persistence.
+     */
+    set(value: T): Promise<void>;
+    /**
+     * Removes this item from persistence.
+     */
+    remove(): Promise<void>;
+}
+/**
+ * An alias for persistent item options with reasonable defaults for string
+ * serialization.
+ * This will use JSON stringify/parse and the global KeyValuePersistence object
+ * from `persistenceRef`.
+ */
+export type DefaultStringPersistentItemOptions<T> = Omit<PersistentItemOptions<T, string>, 'persistence' | 'deserialize' | 'serialize'> & Partial<Pick<PersistentItemOptions<T, string>, 'persistence' | 'deserialize' | 'serialize'>>;
+/**
+ * Creates a new PersistenceItem from the given options.
+ * If serializer, deserializer, and persistence is omitted, then
+ * JSON stringify/parse and the global KeyValuePersistence object
+ * from `persistenceRef` will be used.
+ *
+ * @param options
+ */
+export declare function createPersistentItem<T>(options: DefaultStringPersistentItemOptions<T>): PersistentItemImpl<T, string>;
+export declare function createPersistentItem<T, U>(options: PersistentItemOptions<T, U>): PersistentItemImpl<T, U>;
+//# sourceMappingURL=PersistentItem.d.ts.map

package/dist/types/current/persistence/PersistentItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersistentItem.d.ts","sourceRoot":"","sources":["../../../../src/persistence/PersistentItem.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAE5E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAGxC;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,EAAE,UAAU;IAChD;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAEpB;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAA;IAExB;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAAA;IAElE;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EACd,mBAAmB,CAAC,UAAU,CAAC,GAC/B,CAAC,MAAM,mBAAmB,CAAC,UAAU,CAAC,CAAC,CAAA;IAE7C;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,UAAU,CAAA;IAE5C;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,CAAC,CAAA;CACjD;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC7B;;OAEG;IACH,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAA;IAEjB;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,qBAAa,kBAAkB,CAAC,CAAC,EAAE,UAAU,CACzC,YAAW,cAAc,CAAC,CAAC,CAAC,EAAE,SAAS;IAMnC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;gBAG9C,OAAO,EAAE,qBAAqB,CAAC,CAAC,EAAE,UAAU,CAAC;IAUlE;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC;IAgBvB;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAM1B;AAQD;;;;;GAKG;AACH,MAAM,MAAM,kCAAkC,CAAC,CAAC,IAAI,IAAI,CACpD,qBAAqB,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,aAAa,GAAG,aAAa,GAAG,WAAW,CAC9C,GACG,OAAO,CACH,IAAI,CACA,qBAAqB,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,aAAa,GAAG,aAAa,GAAG,WAAW,CAC9C,CACJ,CAAA;AAEL;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAClC,OAAO,EAAE,kCAAkC,CAAC,CAAC,CAAC,GAC/C,kBAAkB,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;AAChC,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EACrC,OAAO,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,GACrC,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA"}

package/dist/types/current/persistence/PersistentItem.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logError, logVerbose } from '../logging/Logger';
+import { persistenceRef } from '../persistence/persistenceRef';
+import { lazy } from '../util/object/lazy';
+export class PersistentItemImpl {
+    options;
+    logPrefix;
+    persistence;
+    constructor(options) {
+        this.options = options;
+        this.logPrefix = `PersistentItem_${options.key}`;
+        this.persistence = lazy(() => {
+            return typeof options.persistence === 'function'
+                ? options.persistence()
+                : options.persistence;
+        });
+    }
+    /**
+     * Gets this item from persistence.
+     */
+    async get() {
+        const { key, defaultValue, deserialize, validator } = this.options;
+        const persistence = this.persistence.value;
+        const rawStr = await persistence.get(key);
+        if (rawStr == null)
+            return defaultValue;
+        try {
+            const value = deserialize(rawStr);
+            validator?.(value);
+            return value;
+        }
+        catch (error) {
+            logError(this, `could not revive <${key}> from persistence`, error);
+            await persistence.remove(key);
+            return defaultValue;
+        }
+    }
+    /**
+     * Saves this item to persistence.
+     */
+    set(value) {
+        const { key, serialize } = this.options;
+        logVerbose(this, 'set', value);
+        const persistence = this.persistence.value;
+        return persistence.set(key, serialize(value));
+    }
+    /**
+     * Removes this item from persistence.
+     */
+    remove() {
+        const { key } = this.options;
+        logVerbose(this, 'remove');
+        const persistence = this.persistence.value;
+        return persistence.remove(key);
+    }
+}
+const persistentItemStringOptionDefaults = {
+    serialize: JSON.stringify,
+    deserialize: JSON.parse,
+    persistence: () => persistenceRef.value,
+};
+export function createPersistentItem(options) {
+    return new PersistentItemImpl({
+        ...persistentItemStringOptionDefaults,
+        ...options,
+    });
+}

package/dist/types/current/persistence/StoragePersistence.d.ts

@@ -0,0 +1,11 @@
+import type { KeyValuePersistence } from '../persistence/KeyValuePersistence';
+import type { Maybe } from '../util/type';
+export declare class StoragePersistence implements KeyValuePersistence<string> {
+    private readonly storage;
+    constructor(storage: Maybe<Storage>);
+    clear(): Promise<void>;
+    get(key: string): Promise<string | null>;
+    remove(key: string): Promise<void>;
+    set(key: string, value: string): Promise<void>;
+}
+//# sourceMappingURL=StoragePersistence.d.ts.map

package/dist/types/current/persistence/StoragePersistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoragePersistence.d.ts","sourceRoot":"","sources":["../../../../src/persistence/StoragePersistence.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAC5E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC,qBAAa,kBAAmB,YAAW,mBAAmB,CAAC,MAAM,CAAC;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC;IAEpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIjD"}

package/dist/types/current/persistence/StoragePersistence.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class StoragePersistence {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    clear() {
+        this.storage?.clear();
+        return Promise.resolve();
+    }
+    get(key) {
+        return Promise.resolve(this.storage?.getItem(key) ?? null);
+    }
+    remove(key) {
+        this.storage?.removeItem(key);
+        return Promise.resolve();
+    }
+    set(key, value) {
+        this.storage?.setItem(key, value);
+        return Promise.resolve();
+    }
+}

package/dist/types/current/persistence/persistenceRef.d.ts

@@ -0,0 +1,7 @@
+import type { KeyValuePersistence } from '../persistence/KeyValuePersistence';
+/**
+ * The default storage persistence for simple key / value pairs.
+ * This may be overridden, and by default resolves to local storage persistence.
+ */
+export declare const persistenceRef: import("../global/globalRegistry").GlobalRef<KeyValuePersistence<string>>;
+//# sourceMappingURL=persistenceRef.d.ts.map

package/dist/types/current/persistence/persistenceRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistenceRef.d.ts","sourceRoot":"","sources":["../../../../src/persistence/persistenceRef.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAG5E;;;GAGG;AACH,eAAO,MAAM,cAAc,0EAIzB,CAAA"}

package/dist/types/current/persistence/persistenceRef.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { globalRef } from '../global/globalRegistry';
+import { StoragePersistence } from '../persistence/StoragePersistence';
+/**
+ * The default storage persistence for simple key / value pairs.
+ * This may be overridden, and by default resolves to local storage persistence.
+ */
+export const persistenceRef = globalRef(() => {
+    return new StoragePersistence(typeof localStorage !== 'undefined' ? localStorage : null);
+});