@clockworkdog/cogs-client 2.3.0 → 2.4.0

package/README.md

@@ -112,7 +112,7 @@ Initialize a [CogsConnection](https://clockwork-dog.github.io/cogs-client-lib/in
 ```ts
 let connected = false;
 
-import manifest from './cogs-plugin-manifest.js'; // Requires `"allowJs": true` in `tsconfig.json`
+import * as manifest from './cogs-plugin-manifest.js'; // Requires `"allowJs": true` in `tsconfig.json`
 
 const cogsConnection = new CogsConnection(manifest);
 cogsConnection.addEventListener('open', () => {
@@ -147,6 +147,29 @@ function sendPortUpdateToCogs() {
 }
 ```
 
+You can save arbitrary data to COGS which will be restored when reconnecting with COGS:
+
+```ts
+const cogsConnection = new CogsConnection(manifest, {
+  // Initial items in the store
+  'my-key': { foo: 0, bar: '' }
+});
+
+// Update the store
+cogsConnection.store.setItems({ 'my-key': { foo: 1, bar: 'two' } });
+
+// Get item from data store
+cogsConnection.store.items.getItem('my-key')
+
+// Listen for data changes
+cogsConnection.store.addEventListener('item', ({ key, value }) => {
+  console.log(key, 'item changed:', value);
+});
+cogsConnection.store.addEventListener('items', ({ items }) => {
+  console.log('items changed:', items);
+});
+```
+
 ### Support audio actions
 
 Add `audio` to `cogs-plugin-manifest.js`:

package/dist/CogsConnection.d.ts

@@ -5,7 +5,10 @@ import AllMediaClipStatesMessage from './types/AllMediaClipStatesMessage';
 import { CogsPluginManifest, PluginManifestEventJson } from './types/CogsPluginManifest';
 import * as ManifestTypes from './types/ManifestTypes';
 import { DeepReadonly } from './types/utils';
-export default class CogsConnection<Manifest extends CogsPluginManifest> {
+import DataStore from './DataStore';
+export default class CogsConnection<Manifest extends CogsPluginManifest, DataT extends {
+    [key: string]: unknown;
+} = Record<never, never>> {
     readonly manifest: Manifest;
     private websocket;
     private eventTarget;
@@ -35,6 +38,10 @@ export default class CogsConnection<Manifest extends CogsPluginManifest> {
     private audioOutputs;
     private _selectedAudioOutput;
     get selectedAudioOutput(): string;
+    /**
+     * Stores data in COGS
+     */
+    store: DataStore<DataT>;
     /**
      * URL parameters use for the websocket connection and asset URLs
      */
@@ -44,7 +51,7 @@ export default class CogsConnection<Manifest extends CogsPluginManifest> {
         port?: number;
     }, initialClientState?: Partial<ManifestTypes.StateAsObject<Manifest, {
         writableFromClient: true;
-    }>> | undefined);
+    }>>, initialDataStoreData?: DataT);
     get isConnected(): boolean;
     close(): void;
     sendEvent<EventName extends ManifestTypes.EventNameToCogs<Manifest>>(eventName: EventName, ...[eventValue]: ManifestTypes.EventToCogsAsObject<Manifest>[EventName] extends undefined ? [] : [ManifestTypes.EventToCogsAsObject<Manifest>[EventName]]): void;
@@ -55,6 +62,7 @@ export default class CogsConnection<Manifest extends CogsPluginManifest> {
     sendInitialMediaClipStates(allMediaClipStates: AllMediaClipStatesMessage): void;
     sendMediaClipState(mediaClipState: MediaClipStateMessage): void;
     sendAudioOutputs(audioOutputs: MediaDeviceInfo[]): void;
+    private sendDataStoreItems;
     /**
      * Show or hide the plugin window.
      * @param visible Whether to show or hide the window

package/dist/CogsConnection.js

@@ -8,6 +8,7 @@ const compare_versions_1 = require("compare-versions");
 const ShowPhase_1 = __importDefault(require("./types/ShowPhase"));
 const reconnecting_websocket_1 = __importDefault(require("reconnecting-websocket"));
 const urls_1 = require("./helpers/urls");
+const DataStore_1 = __importDefault(require("./DataStore"));
 class CogsConnection {
     get config() {
         return { ...this.currentConfig };
@@ -34,7 +35,7 @@ class CogsConnection {
     get selectedAudioOutput() {
         return this._selectedAudioOutput;
     }
-    constructor(manifest, { hostname = document.location.hostname, port = urls_1.COGS_SERVER_PORT } = {}, initialClientState = undefined) {
+    constructor(manifest, { hostname = document.location.hostname, port = urls_1.COGS_SERVER_PORT } = {}, initialClientState, initialDataStoreData) {
         var _a;
         this.manifest = manifest;
         this.eventTarget = new EventTarget();
@@ -55,6 +56,7 @@ class CogsConnection {
         this.audioOutputs = undefined;
         this._selectedAudioOutput = '';
         this.currentState = { ...initialClientState };
+        this.store = new DataStore_1.default(initialDataStoreData !== null && initialDataStoreData !== void 0 ? initialDataStoreData : {});
         const { useReconnectingWebsocket, path, pathParams, supportsHttp2Assets } = websocketParametersFromUrl(document.location.href);
         // Store the URL parameters for use in asset URLs
         // and add screen dimensions which COGS can use to determine the best asset quality to serve
@@ -122,6 +124,9 @@ class CogsConnection {
                                     }
                                 }
                                 break;
+                            case 'data_store_items':
+                                this.store.handleDataStoreItemsMessage(message);
+                                break;
                         }
                         this.dispatchEvent(new CogsMessageEvent(message));
                     }
@@ -134,6 +139,10 @@ class CogsConnection {
                 console.error('Unable to parse incoming data from server', data, e);
             }
         };
+        // Tell COGS when any data store items change
+        this.store.addEventListener('items', (event) => {
+            this.sendDataStoreItems(event.items);
+        });
         // Send a list of audio outputs to COGS and keep it up to date
         {
             const refreshAudioOutputs = async () => {
@@ -190,6 +199,11 @@ class CogsConnection {
             this.websocket.send(JSON.stringify({ audioOutputs }));
         }
     }
+    sendDataStoreItems(partialItems) {
+        if (this.isConnected) {
+            this.websocket.send(JSON.stringify({ dataStoreItems: partialItems }));
+        }
+    }
     /**
      * Show or hide the plugin window.
      * @param visible Whether to show or hide the window

package/dist/DataStore.d.ts

@@ -0,0 +1,41 @@
+import { DataStoreItemsClientMessage } from './types/CogsClientMessage';
+/**
+ * A simple key-value store for storing data in COGS
+ *
+ * When reconnected the data will be restored.
+ */
+export default class DataStore<ItemsT extends {
+    [key: string]: unknown;
+} = {
+    [key: string]: unknown;
+}> {
+    #private;
+    private _items;
+    constructor(defaultItems: ItemsT);
+    handleDataStoreItemsMessage(message: DataStoreItemsClientMessage): void;
+    get items(): Readonly<typeof this._items>;
+    getItem(key: string): unknown | undefined;
+    setItems(partialItems: Partial<ItemsT>): this;
+    addEventListener<K extends keyof DataStoreEventMap>(type: K, listener: (event: DataStoreEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof DataStoreEventMap>(type: K, listener: (event: DataStoreEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
+    private dispatchEvent;
+}
+export declare class DataStoreItemEvent extends Event {
+    readonly key: string;
+    readonly value: unknown;
+    readonly _cogsConnectionEventType = "item";
+    constructor(key: string, value: unknown);
+}
+export declare class DataStoreItemsEvent extends Event {
+    readonly items: {
+        [key: string]: unknown;
+    };
+    readonly _cogsConnectionEventType = "item";
+    constructor(items: {
+        [key: string]: unknown;
+    });
+}
+export interface DataStoreEventMap {
+    item: DataStoreItemEvent;
+    items: DataStoreItemsEvent;
+}

package/dist/DataStore.js

@@ -0,0 +1,70 @@
+"use strict";
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _DataStore_eventTarget;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataStoreItemsEvent = exports.DataStoreItemEvent = void 0;
+/**
+ * A simple key-value store for storing data in COGS
+ *
+ * When reconnected the data will be restored.
+ */
+class DataStore {
+    constructor(defaultItems) {
+        _DataStore_eventTarget.set(this, new EventTarget());
+        this._items = { ...defaultItems };
+    }
+    handleDataStoreItemsMessage(message) {
+        this._items = { ...this._items, ...message.items };
+        Object.entries(message.items).forEach(([key, value]) => {
+            this.dispatchEvent(new DataStoreItemEvent(key, value));
+        });
+        this.dispatchEvent(new DataStoreItemsEvent(message.items));
+    }
+    get items() {
+        return this._items;
+    }
+    getItem(key) {
+        return this._items[key];
+    }
+    setItems(partialItems) {
+        this._items = { ...this._items, ...partialItems };
+        Object.entries(partialItems).forEach(([key, value]) => {
+            this.dispatchEvent(new DataStoreItemEvent(key, value));
+        });
+        this.dispatchEvent(new DataStoreItemsEvent(partialItems));
+        return this;
+    }
+    // Type-safe listeners
+    addEventListener(type, listener, options) {
+        __classPrivateFieldGet(this, _DataStore_eventTarget, "f").addEventListener(type, listener, options);
+    }
+    removeEventListener(type, listener, options) {
+        __classPrivateFieldGet(this, _DataStore_eventTarget, "f").removeEventListener(type, listener, options);
+    }
+    dispatchEvent(event) {
+        __classPrivateFieldGet(this, _DataStore_eventTarget, "f").dispatchEvent(event);
+    }
+}
+_DataStore_eventTarget = new WeakMap();
+exports.default = DataStore;
+class DataStoreItemEvent extends Event {
+    constructor(key, value) {
+        super('item');
+        this.key = key;
+        this.value = value;
+        this._cogsConnectionEventType = 'item';
+    }
+}
+exports.DataStoreItemEvent = DataStoreItemEvent;
+class DataStoreItemsEvent extends Event {
+    constructor(items) {
+        super('items');
+        this.items = items;
+        this._cogsConnectionEventType = 'item';
+    }
+}
+exports.DataStoreItemsEvent = DataStoreItemsEvent;