commands: add OptableCommands command-queue addon (#323)

Author: mosherBT

README.md

@@ -1273,6 +1273,18 @@ if (!SkipTargetingForBots()) {
 
 Matching is substring-based and case-insensitive, covering generic crawlers, headless browsers, HTTP clients and Google's non-search agents. It is deliberately broad and user-agent only — a cost-saving filter, not a fraud signal. For the full match list, see the [bot detection addon README](lib/addons/botDetection.md).
 
+## Command queue
+
+The command queue addon lets a page interact with a wrapper loaded via an async script tag before the script has arrived, in the style of `googletag.cmd` and `pbjs.que`. The page queues functions on a plain-array stub; the wrapper replaces the stub with an instance, which drains the queue and executes later pushes immediately.
+
+```typescript
+import { OptableCommands } from "@optable/web-sdk/lib/dist/addons/commands";
+
+window.optable.cmd = new OptableCommands(window.optable.cmd || []);
+```
+
+For the page-side stub and behaviour details, see the [command queue addon README](lib/addons/commands.md).
+
 ## Demo Pages
 
 The demo pages are working examples of both `identify` and `targeting` APIs, as well as an integration with the [Google Ad Manager 360](https://admanager.google.com/home/) ad server, enabling the targeting of ads served by GAM360 to audiences activated in the [Optable](https://optable.co/) DCN.

lib/addons/commands.md

@@ -0,0 +1,29 @@
+# Command Queue Addon
+
+A command queue for wrappers loaded via an async script tag, in the style of `googletag.cmd` and `pbjs.que`. It lets a page interact with the wrapper before the script has loaded.
+
+## Usage
+
+The page defines a plain-array stub and queues calls against it:
+
+```html
+<script>
+  window.optable = window.optable || { cmd: [] };
+  window.optable.cmd.push(() => {
+    // Runs once the wrapper has loaded.
+  });
+</script>
+<script async src="https://.../wrapper.js"></script>
+```
+
+During initialization the wrapper swaps the stub for an instance:
+
+```js
+import { OptableCommands } from "@optable/web-sdk/lib/dist/addons/commands";
+
+window.optable.cmd = new OptableCommands(window.optable.cmd || []);
+```
+
+The constructor drains everything queued while the script was loading. After the swap, `push()` executes its argument immediately and returns its value.
+
+Non-function entries in the pre-load queue are ignored, a missing or non-array queue is tolerated, and a queued function that throws is logged to the console without stopping the rest of the queue — so a page that clobbers the stub or queues a broken function cannot break wrapper initialization.

lib/addons/commands.test.ts

@@ -0,0 +1,46 @@
+import { OptableCommands } from "./commands";
+
+describe("OptableCommands", () => {
+  it("executes functions queued before construction, in order", () => {
+    const calls: number[] = [];
+    new OptableCommands([() => calls.push(1), () => calls.push(2)]);
+    expect(calls).toEqual([1, 2]);
+  });
+
+  it("ignores non-function entries in the queue", () => {
+    const fn = jest.fn();
+    expect(() => new OptableCommands([null, "x", 42, fn])).not.toThrow();
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("logs a throwing queued function and continues draining", () => {
+    const spy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const after = jest.fn();
+    const boom = new Error("boom");
+    expect(
+      () =>
+        new OptableCommands([
+          () => {
+            throw boom;
+          },
+          after,
+        ])
+    ).not.toThrow();
+    expect(after).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(boom);
+    spy.mockRestore();
+  });
+
+  it("tolerates a missing or non-array queue", () => {
+    expect(() => new OptableCommands()).not.toThrow();
+    expect(() => new OptableCommands(undefined)).not.toThrow();
+    expect(() => new OptableCommands({} as unknown)).not.toThrow();
+  });
+
+  it("executes pushed functions immediately and returns their value", () => {
+    const cmd = new OptableCommands([]);
+    const fn = jest.fn(() => "done");
+    expect(cmd.push(fn)).toBe("done");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+});

lib/addons/commands.ts

@@ -0,0 +1,25 @@
+// Command queue for async script-tag wrappers, in the style of googletag.cmd
+// and pbjs.que. Pages push functions onto a plain-array stub before the
+// wrapper script loads; the wrapper replaces the stub with an instance, which
+// drains the queue and executes later pushes immediately.
+class OptableCommands {
+  constructor(cmds?: unknown) {
+    if (Array.isArray(cmds)) {
+      cmds.forEach((cmd) => {
+        if (typeof cmd !== "function") return;
+        try {
+          cmd();
+        } catch (e) {
+          console.error(e); // eslint-disable-line no-console
+        }
+      });
+    }
+  }
+
+  push<T>(cmd: () => T): T {
+    return cmd();
+  }
+}
+
+export { OptableCommands };
+export default OptableCommands;