respondable-event 0.1.0-main.fbbbe9d

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 William Wong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# `respondable-event`
+
+Enables event listeners to send response back to the event dispatcher.
+
+## Background
+
+Inspired by the [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent) which is available to [Service Workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) only, the `RespondableEvent` allows event listeners to send a response back to the dispatching [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget).
+
+This is useful in scenarios where custom elements need to communicate with the host asynchronously or infrequently. For persisted messaging, use `RespondableEvent` to set up [Channel Messaging](https://developer.mozilla.org/en-US/docs/Web/API/Channel_Messaging_API/Using_channel_messaging) instead.
+
+## How to use
+
+The code snippet below sends an `"authenticate"` event to the hosting page.
+
+```ts
+const event = new RespondableEvent(
+  'authenticate',
+  token => {
+    if (token) {
+      // Responded.
+    } else {
+      // No response.
+    }
+  },
+  { bubbles: true } // Available to the whole page.
+);
+
+element.dispatchEvent(event);
+
+// If `respondWith()` is not called, `checkResponse()`
+// function will callback with `undefined`.
+event.checkResponse();
+
+const token = await authenticate.promise;
+```
+
+In the hosting page, the following code snippet responds with a token.
+
+```ts
+window.addEventListener('authenticate', event => {
+  if (event.target === myTrustedElement && event.request === myTrustedRequest) {
+    event.respondWith('Hello, World!');
+    event.stopPropagation();
+  }
+});
+```
+
+The callback function passed to the constructor will be called *at most once*. Same as `FetchEvent`, the `respondWith()` function will throw if it is being called for more than once.
+
+### New `checkResponse` function
+
+To reduce code complexity, the `checkResponse()` function guarantees the `callback` function will be called exactly once. The API design is similar to the [`HTMLFormElement.checkValidity()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/checkValidity) function:
+
+- If `respondWith()` was called, `checkResponse()` will return `true`.
+- If `respondWith()` was never called, `checkResponse()` will call the `callback` function with `undefined`, and return `false`.
+
+It is recommended to put `checkResponse()` immediately after `dispatchEvent()`.
+
+## Designs
+
+### Callback function in constructor
+
+The callback function follows the pattern found in [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/MutationObserver) and other observers. It is designed to limit the number of audience who can look at the response.
+
+## Behaviors
+
+### Differences between `RespondableEvent` and `FetchEvent`
+
+- `RespondableEvent` extends from [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event), where [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent) extends from [`ExtendableEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ExtendableEvent)
+- `request` property is optional in `RespondableEvent` where it is required in [`FetchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/FetchEvent/request)
+- [`checkResponse()`](#new-checkresponse-function) function is new in `RespondableEvent`
+
+## Contributions
+
+Like us? [Star](https://github.com/compulim/respondable-event/stargazers) us.
+
+Want to make it better? [File](https://github.com/compulim/respondable-event/issues) us an issue.
+
+Don't like something you see? [Submit](https://github.com/compulim/respondable-event/pulls) a pull request.

package/dist/respondable-event.d.mts

@@ -0,0 +1,28 @@
+interface RespondableEventInit<T> extends EventInit {
+    /** The object that would have triggered the event handler. */
+    request: T;
+}
+declare class RespondableEvent<T, R = undefined> extends Event {
+    #private;
+    constructor(
+    /** A string with the name of the event. */
+    type: string, 
+    /** A function which will be called upon respond. */
+    callback: (result: T | undefined, event: RespondableEvent<T, R>) => void, 
+    /**
+     * An object that, in addition of the properties defined in [Event()](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event), can have the following properties:
+     *
+     * - `request`: The object that would have triggered the event handler.
+     */
+    eventInitDict?: RespondableEventInit<R> | undefined);
+    /** The object that would have triggered the event handler. */
+    get request(): R | undefined;
+    checkResponse(): boolean;
+    respondWith(
+    /**
+     * An object or a Promise that resolves to an object.
+     */
+    response: T | Promise<T>): void;
+}
+
+export { RespondableEvent };

package/dist/respondable-event.d.ts

@@ -0,0 +1,28 @@
+interface RespondableEventInit<T> extends EventInit {
+    /** The object that would have triggered the event handler. */
+    request: T;
+}
+declare class RespondableEvent<T, R = undefined> extends Event {
+    #private;
+    constructor(
+    /** A string with the name of the event. */
+    type: string, 
+    /** A function which will be called upon respond. */
+    callback: (result: T | undefined, event: RespondableEvent<T, R>) => void, 
+    /**
+     * An object that, in addition of the properties defined in [Event()](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event), can have the following properties:
+     *
+     * - `request`: The object that would have triggered the event handler.
+     */
+    eventInitDict?: RespondableEventInit<R> | undefined);
+    /** The object that would have triggered the event handler. */
+    get request(): R | undefined;
+    checkResponse(): boolean;
+    respondWith(
+    /**
+     * An object or a Promise that resolves to an object.
+     */
+    response: T | Promise<T>): void;
+}
+
+export { RespondableEvent };

package/dist/respondable-event.js

@@ -0,0 +1,65 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  RespondableEvent: () => RespondableEvent_default
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/RespondableEvent.ts
+var RespondableEvent = class extends Event {
+  constructor(type, callback, eventInitDict) {
+    super(type, eventInitDict);
+    this.#request = eventInitDict?.request;
+    const resolvers = Promise.withResolvers();
+    resolvers.promise.then((result) => callback(result, this));
+    this.#resolve = (result) => {
+      if (this.#resolved) {
+        throw new Error("respondWith() has already been invoked.");
+      } else if (!this.target) {
+        throw new Error("respondWith() can only be called after dispatched.");
+      }
+      resolvers.resolve(result);
+      this.#resolved = true;
+    };
+  }
+  #request;
+  #resolve;
+  #resolved = false;
+  /** The object that would have triggered the event handler. */
+  get request() {
+    return this.#request;
+  }
+  checkResponse() {
+    const wasResolved = this.#resolved;
+    wasResolved || this.#resolve(void 0);
+    return wasResolved;
+  }
+  respondWith(response) {
+    this.#resolve(response);
+  }
+};
+var RespondableEvent_default = RespondableEvent;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RespondableEvent
+});
+//# sourceMappingURL=respondable-event.js.map

package/dist/respondable-event.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/RespondableEvent.ts"],"sourcesContent":["import RespondableEvent from './RespondableEvent.ts';\n\nexport { RespondableEvent };\n","interface RespondableEventInit<T> extends EventInit {\n  /** The object that would have triggered the event handler. */\n  request: T;\n}\n\nclass RespondableEvent<T, R = undefined> extends Event {\n  constructor(\n    /** A string with the name of the event. */\n    type: string,\n    /** A function which will be called upon respond. */\n    callback: (result: T | undefined, event: RespondableEvent<T, R>) => void,\n    /**\n     * An object that, in addition of the properties defined in [Event()](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event), can have the following properties:\n     *\n     * - `request`: The object that would have triggered the event handler.\n     */\n    eventInitDict?: RespondableEventInit<R> | undefined\n  ) {\n    super(type, eventInitDict);\n\n    this.#request = eventInitDict?.request;\n\n    const resolvers = Promise.withResolvers<T | undefined>();\n\n    resolvers.promise.then(result => callback(result, this));\n\n    this.#resolve = (result: Promise<T> | T | undefined) => {\n      if (this.#resolved) {\n        throw new Error('respondWith() has already been invoked.');\n      } else if (!this.target) {\n        throw new Error('respondWith() can only be called after dispatched.');\n      }\n\n      resolvers.resolve(result);\n\n      this.#resolved = true;\n    };\n  }\n\n  #request: R | undefined;\n  #resolve: (result: Promise<T> | T | undefined) => void;\n  #resolved: boolean = false;\n\n  /** The object that would have triggered the event handler. */\n  get request(): R | undefined {\n    return this.#request;\n  }\n\n  checkResponse(): boolean {\n    const wasResolved = this.#resolved;\n\n    wasResolved || this.#resolve(undefined);\n\n    return wasResolved;\n  }\n\n  respondWith(\n    /**\n     * An object or a Promise that resolves to an object.\n     */\n    response: T | Promise<T>\n  ): void {\n    this.#resolve(response);\n  }\n}\n\nexport default RespondableEvent;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKA,IAAM,mBAAN,cAAiD,MAAM;AAAA,EACrD,YAEE,MAEA,UAMA,eACA;AACA,UAAM,MAAM,aAAa;AAEzB,SAAK,WAAW,eAAe;AAE/B,UAAM,YAAY,QAAQ,cAA6B;AAEvD,cAAU,QAAQ,KAAK,YAAU,SAAS,QAAQ,IAAI,CAAC;AAEvD,SAAK,WAAW,CAAC,WAAuC;AACtD,UAAI,KAAK,WAAW;AAClB,cAAM,IAAI,MAAM,yCAAyC;AAAA,MAC3D,WAAW,CAAC,KAAK,QAAQ;AACvB,cAAM,IAAI,MAAM,oDAAoD;AAAA,MACtE;AAEA,gBAAU,QAAQ,MAAM;AAExB,WAAK,YAAY;AAAA,IACnB;AAAA,EACF;AAAA,EAEA;AAAA,EACA;AAAA,EACA,YAAqB;AAAA;AAAA,EAGrB,IAAI,UAAyB;AAC3B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,gBAAyB;AACvB,UAAM,cAAc,KAAK;AAEzB,mBAAe,KAAK,SAAS,MAAS;AAEtC,WAAO;AAAA,EACT;AAAA,EAEA,YAIE,UACM;AACN,SAAK,SAAS,QAAQ;AAAA,EACxB;AACF;AAEA,IAAO,2BAAQ;","names":[]}

package/dist/respondable-event.mjs

@@ -0,0 +1,38 @@
+// src/RespondableEvent.ts
+var RespondableEvent = class extends Event {
+  constructor(type, callback, eventInitDict) {
+    super(type, eventInitDict);
+    this.#request = eventInitDict?.request;
+    const resolvers = Promise.withResolvers();
+    resolvers.promise.then((result) => callback(result, this));
+    this.#resolve = (result) => {
+      if (this.#resolved) {
+        throw new Error("respondWith() has already been invoked.");
+      } else if (!this.target) {
+        throw new Error("respondWith() can only be called after dispatched.");
+      }
+      resolvers.resolve(result);
+      this.#resolved = true;
+    };
+  }
+  #request;
+  #resolve;
+  #resolved = false;
+  /** The object that would have triggered the event handler. */
+  get request() {
+    return this.#request;
+  }
+  checkResponse() {
+    const wasResolved = this.#resolved;
+    wasResolved || this.#resolve(void 0);
+    return wasResolved;
+  }
+  respondWith(response) {
+    this.#resolve(response);
+  }
+};
+var RespondableEvent_default = RespondableEvent;
+export {
+  RespondableEvent_default as RespondableEvent
+};
+//# sourceMappingURL=respondable-event.mjs.map

package/dist/respondable-event.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/RespondableEvent.ts"],"sourcesContent":["interface RespondableEventInit<T> extends EventInit {\n  /** The object that would have triggered the event handler. */\n  request: T;\n}\n\nclass RespondableEvent<T, R = undefined> extends Event {\n  constructor(\n    /** A string with the name of the event. */\n    type: string,\n    /** A function which will be called upon respond. */\n    callback: (result: T | undefined, event: RespondableEvent<T, R>) => void,\n    /**\n     * An object that, in addition of the properties defined in [Event()](https://developer.mozilla.org/en-US/docs/Web/API/Event/Event), can have the following properties:\n     *\n     * - `request`: The object that would have triggered the event handler.\n     */\n    eventInitDict?: RespondableEventInit<R> | undefined\n  ) {\n    super(type, eventInitDict);\n\n    this.#request = eventInitDict?.request;\n\n    const resolvers = Promise.withResolvers<T | undefined>();\n\n    resolvers.promise.then(result => callback(result, this));\n\n    this.#resolve = (result: Promise<T> | T | undefined) => {\n      if (this.#resolved) {\n        throw new Error('respondWith() has already been invoked.');\n      } else if (!this.target) {\n        throw new Error('respondWith() can only be called after dispatched.');\n      }\n\n      resolvers.resolve(result);\n\n      this.#resolved = true;\n    };\n  }\n\n  #request: R | undefined;\n  #resolve: (result: Promise<T> | T | undefined) => void;\n  #resolved: boolean = false;\n\n  /** The object that would have triggered the event handler. */\n  get request(): R | undefined {\n    return this.#request;\n  }\n\n  checkResponse(): boolean {\n    const wasResolved = this.#resolved;\n\n    wasResolved || this.#resolve(undefined);\n\n    return wasResolved;\n  }\n\n  respondWith(\n    /**\n     * An object or a Promise that resolves to an object.\n     */\n    response: T | Promise<T>\n  ): void {\n    this.#resolve(response);\n  }\n}\n\nexport default RespondableEvent;\n"],"mappings":";AAKA,IAAM,mBAAN,cAAiD,MAAM;AAAA,EACrD,YAEE,MAEA,UAMA,eACA;AACA,UAAM,MAAM,aAAa;AAEzB,SAAK,WAAW,eAAe;AAE/B,UAAM,YAAY,QAAQ,cAA6B;AAEvD,cAAU,QAAQ,KAAK,YAAU,SAAS,QAAQ,IAAI,CAAC;AAEvD,SAAK,WAAW,CAAC,WAAuC;AACtD,UAAI,KAAK,WAAW;AAClB,cAAM,IAAI,MAAM,yCAAyC;AAAA,MAC3D,WAAW,CAAC,KAAK,QAAQ;AACvB,cAAM,IAAI,MAAM,oDAAoD;AAAA,MACtE;AAEA,gBAAU,QAAQ,MAAM;AAExB,WAAK,YAAY;AAAA,IACnB;AAAA,EACF;AAAA,EAEA;AAAA,EACA;AAAA,EACA,YAAqB;AAAA;AAAA,EAGrB,IAAI,UAAyB;AAC3B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,gBAAyB;AACvB,UAAM,cAAc,KAAK;AAEzB,mBAAe,KAAK,SAAS,MAAS;AAEtC,WAAO;AAAA,EACT;AAAA,EAEA,YAIE,UACM;AACN,SAAK,SAAS,QAAQ;AAAA,EACxB;AACF;AAEA,IAAO,2BAAQ;","names":[]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "respondable-event",
+  "version": "0.1.0-main.fbbbe9d",
+  "description": "Enables event listeners to send zero-or-one response back to the event dispatcher.",
+  "files": [
+    "./dist/"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/respondable-event.d.mts",
+        "default": "./dist/respondable-event.mjs"
+      },
+      "require": {
+        "types": "./dist/respondable-event.d.ts",
+        "default": "./dist/respondable-event.js"
+      }
+    }
+  },
+  "main": "./dist/respondable-event.js",
+  "typings": "./dist/respondable-event.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "bump": "npm run bump:prod && npm run bump:dev",
+    "bump:dev": "PACKAGES_TO_BUMP=$(cat package.json | jq -r '(.pinDependencies // {}) as $P | (.localPeerDependencies // {}) as $L | (.devDependencies // {}) | to_entries | map(select(.key as $K | $L | has($K) | not)) | map(.key + \"@\" + ($P[.key] // [\"latest\"])[0]) | join(\" \")') && [ ! -z \"$PACKAGES_TO_BUMP\" ] && npm install $PACKAGES_TO_BUMP || true",
+    "bump:prod": "PACKAGES_TO_BUMP=$(cat package.json | jq -r '(.pinDependencies // {}) as $P | (.localPeerDependencies // {}) as $L | (.dependencies // {}) | to_entries | map(select(.key as $K | $L | has($K) | not)) | map(.key + \"@\" + ($P[.key] // [\"latest\"])[0]) | join(\" \")') && [ ! -z \"$PACKAGES_TO_BUMP\" ] && npm install $PACKAGES_TO_BUMP || true",
+    "precommit": "npm run precommit:eslint && npm run precommit:publint && npm run precommit:typescript:production && npm run precommit:typescript:test",
+    "precommit:eslint": "ESLINT_USE_FLAT_CONFIG=false eslint ./src/",
+    "precommit:publint": "publint",
+    "precommit:typescript:production": "tsc --noEmit --project ./src/tsconfig.precommit.production.json",
+    "precommit:typescript:test": "tsc --noEmit --project ./src/tsconfig.precommit.test.json",
+    "prepack": "cp ../../CHANGELOG.md . && cp ../../LICENSE . && cp ../../README.md .",
+    "start": "npm run build -- --onSuccess \"touch ../pages/package.json\" --watch",
+    "switch": "cat package.json | jq --arg SWITCH_NAME $SWITCH_NAME -r '(.[\"switch:\" + $SWITCH_NAME] // {}) as $TEMPLATE | .devDependencies += ($TEMPLATE.devDependencies // {}) | .dependencies += ($TEMPLATE.dependencies // {})' | tee ./package.json.tmp && mv ./package.json.tmp ./package.json",
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/compulim/respondable-event.git"
+  },
+  "keywords": [
+    "event-target",
+    "extendable-event",
+    "fetch-event",
+    "respond-with"
+  ],
+  "author": "William Wong (https://github.com/compulim)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/compulim/respondable-event/issues"
+  },
+  "homepage": "https://github.com/compulim/respondable-event#readme",
+  "devDependencies": {
+    "@babel/core": "^7.26.0",
+    "@babel/preset-env": "^7.26.0",
+    "@babel/preset-typescript": "^7.26.0",
+    "@testing-library/react": "^16.0.1",
+    "@tsconfig/recommended": "^1.0.7",
+    "@tsconfig/strictest": "^2.0.5",
+    "@types/jest": "^29.5.13",
+    "babel-jest": "^29.7.0",
+    "esbuild": "^0.24.0",
+    "jest": "^29.7.0",
+    "nodemon": "^3.1.7",
+    "prettier": "^3.3.3",
+    "publint": "^0.2.11",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.3"
+  },
+  "dependencies": {
+    "respondable-event": "^0.1.0-main.fbbbe9d"
+  }
+}