typed-msg 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 vrcalpha
+
+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,184 @@
+# typed-msg
+
+[![npm version](https://badge.fury.io/js/typed-msg.svg)](https://badge.fury.io/js/typed-msg)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+TypeScriptで書かれた、Chrome拡張機能のSW⇔Content Scripts間の通信を型安全にするラッパーライブラリです。
+
+## 例
+
+この例では、ストレージ操作とタブ操作の2つのスコープを持つメッセージインタフェイスを定義します。
+
+### 1. メッセージインターフェース（型）定義
+
+まず、送受信するメッセージの型を定義します。
+
+```ts
+// types/messages.ts
+import {
+  MessageDefinitions,
+  MergeMessageDefinitions,
+  MessageResponse,
+} from 'typed-msg';
+
+// ストレージ関連のメッセージ
+type StorageMessages = MessageDefinitions<{
+  // 設定を保存
+  setSettings: {
+    req: { theme: 'light' | 'dark'; language: string };
+    res: MessageResponse;
+  };
+  // 設定を取得
+  getSettings: {
+    req: void;
+    res: MessageResponse<{ theme: 'light' | 'dark'; language: string }>;
+  };
+}>;
+
+// タブ関連のメッセージ
+type TabMessages = MessageDefinitions<{
+  // 現在のタブ情報を取得
+  getCurrentTab: {
+    req: void;
+    res: MessageResponse<{ id: number; url: string; title: string }>;
+  };
+  // 新しいタブを開く
+  openTab: {
+    req: { url: string };
+    res: MessageResponse<{ tabId: number }>;
+  };
+}>;
+
+// すべてのスコープを統合
+export type Messages = MergeMessageDefinitions<{
+  storage: StorageMessages;
+  tabs: TabMessages;
+}>;
+```
+
+### 2. 受信側（Service Worker）
+
+Service Worker側では `receive` を使ってスコープごとにハンドラーを登録します。
+
+ハンドラーは、スコープごとにファイルを分けても動作します。
+
+```ts
+// background.ts
+import type { Messages } from './types/messages';
+import { receive } from 'typed-msg';
+
+// ストレージ関連のハンドラー
+const storageReceiver = receive<Messages>('storage');
+
+storageReceiver.on('setSettings', async (req) => {
+  await chrome.storage.local.set({ settings: req });
+  return { success: true };
+});
+
+storageReceiver.on('getSettings', async () => {
+  const data = await chrome.storage.local.get('settings');
+  return { success: true, message: data.settings };
+});
+
+// タブ関連のハンドラー
+const tabsReceiver = receive<Messages>('tabs');
+
+tabsReceiver.on('getCurrentTab', async (_, sender) => {
+  const tab = sender.tab;
+  if (!tab?.id || !tab.url || !tab.title) {
+    return { success: false, message: 'タブ情報を取得できませんでした' };
+  }
+  return { success: true, message: { id: tab.id, url: tab.url, title: tab.title } };
+});
+
+tabsReceiver.on('openTab', async (req) => {
+  const tab = await chrome.tabs.create({ url: req.url });
+  if (!tab.id) {
+    return { success: false, message: 'タブを開けませんでした' };
+  }
+  return { success: true, message: { tabId: tab.id } };
+});
+```
+
+### 3. 送信側（Content Scripts）
+
+Content Scripts側では `connect` を使ってメッセージを送信します。
+スコープごとに別々の送信インターフェースを作成できます。
+
+```ts
+// content.ts (Content Script)
+import type { Messages } from './types/messages';
+import { connect } from 'typed-msg';
+
+// スコープごとに送信インターフェースを作成
+const storage = connect<Messages>('storage');
+const tabs = connect<Messages>('tabs');
+
+// 設定を保存
+const saveResult = await storage.setSettings({ theme: 'dark', language: 'ja' });
+if (saveResult.success) {
+  console.log('設定を保存しました');
+}
+
+// 設定を取得
+const settingsResult = await storage.getSettings();
+if (settingsResult.success) {
+  console.log('テーマ:', settingsResult.message.theme);
+  console.log('言語:', settingsResult.message.language);
+}
+
+// 現在のタブ情報を取得
+const tabResult = await tabs.getCurrentTab();
+if (tabResult.success) {
+  console.log('タブID:', tabResult.message.id);
+  console.log('URL:', tabResult.message.url);
+}
+
+// 新しいタブを開く
+const openResult = await tabs.openTab({ url: 'https://example.com' });
+if (openResult.success) {
+  console.log('新しいタブを開きました:', openResult.message.tabId);
+}
+```
+
+## インストール
+
+### npm
+
+```bash
+npm install typed-msg
+```
+
+### yarn
+
+```bash
+yarn add typed-msg
+```
+
+### pnpm
+
+```bash
+pnpm add typed-msg
+```
+
+## 貢献
+
+プロジェクトへの貢献を歓迎します！以下のルールに従うと，あなたの貢献がスムーズになります！
+
+### Issue / PR
+
+Issueを立てる際は，バグ報告・機能要望のどちらかを明記してください。
+PRの説明には，目的・変更点・影響範囲・サンプルコードがあるとありがたいです。
+
+## ライセンス
+
+MIT License
+
+詳細は[LICENSE](./LICENSE)ファイルを参照してください。
+
+## 変更履歴・リリース情報
+
+### v1.0.0 (2026-02-08)
+
+- 初回リリース

package/dist/main.d.ts

@@ -0,0 +1,206 @@
+declare type AsyncOrSync<T> = T | Promise<T>;
+
+/**
+ * メッセージリスナーとの通信を行うための送信用インターフェースを作成します。
+ *
+ * @template T - メッセージ定義の型。`MergeMessageDefinitions` で作成した型を指定します。
+ * @param scope - メッセージのスコープ名。受信側（`receive`）と一致させる必要があります。
+ * @returns メッセージ送信用のProxyオブジェクト。定義したメッセージ名をメソッドとして呼び出せます。
+ *
+ * @example
+ * ```ts
+ * type Messages = MergeMessageDefinitions<{ remote: RemoteMessages }>;
+ *
+ * const sender = connect<Messages>('remote');
+ * const result = await sender.addRepository({ url: 'https://...' });
+ * ```
+ */
+export declare function connect<T extends MergedMessageDefinitions>(scope: keyof T & string): MessageInterface<T[keyof T & string]>;
+
+/**
+ * 失敗時のレスポンス型です。
+ *
+ * エラーメッセージを `message` に格納して返します。
+ *
+ * @example
+ * ```ts
+ * const errorResponse: FailureMessageResponse = {
+ *   success: false,
+ *   message: 'リポジトリが見つかりません',
+ * };
+ * ```
+ */
+export declare type FailureMessageResponse = {
+    success: false;
+    message: string;
+};
+
+declare type JsonArray = JsonValue[];
+
+declare type JsonObject = {
+    [key: string]: JsonValue;
+};
+
+declare type JsonPrimitive = string | number | boolean | null;
+
+declare type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+
+declare type MergedMessageDefinitions = Record<string, ValidatedMessageDefinitions>;
+
+/**
+ * 複数のメッセージ定義をスコープごとに統合するための型エイリアスです。
+ *
+ * `MessageDefinitions` で作成した個別の定義を、スコープ名をキーとしてまとめます。
+ * `connect` と `receive` はこの型を型引数として受け取ります。
+ *
+ * @template T - スコープ名をキー、`MessageDefinitions` を値とするオブジェクト型
+ *
+ * @example
+ * ```ts
+ * type RemoteMessages = MessageDefinitions<{ ... }>;
+ * type BackgroundMessages = MessageDefinitions<{ ... }>;
+ *
+ * type Messages = MergeMessageDefinitions<{
+ *   remote: RemoteMessages;
+ *   background: BackgroundMessages;
+ * }>;
+ *
+ * // 使用時:
+ * const sender = connect<Messages>('remote');
+ * const receiver = receive<Messages>('remote');
+ * ```
+ */
+export declare type MergeMessageDefinitions<T extends MergedMessageDefinitions> = T;
+
+/**
+ * 個別のメッセージ定義を作成するための型エイリアスです。
+ *
+ * 各メッセージは `req`（リクエスト）と `res`（レスポンス）を持つオブジェクトとして定義します。
+ * この型で定義したメッセージ群は、`MergeMessageDefinitions` で統合する必要があります。
+ *
+ * @template T - メッセージ名をキー、`{ req?, res? }` を値とするオブジェクト型
+ *
+ * @example
+ * ```ts
+ * type RemoteMessages = MessageDefinitions<{
+ *   addRepository: {
+ *     req: { url: string };
+ *     res: MessageResponse;
+ *   };
+ *   getRepository: {
+ *     req: { id: number };
+ *     res: MessageResponse<{ name: string; url: string }>;
+ *   };
+ * }>;
+ * ```
+ */
+export declare type MessageDefinitions<T extends ValidatedMessageDefinitions> = T;
+
+declare type MessageHandler<T extends ValidatedMessageDefinitions, K extends string> = K extends keyof T ? (req: SafeExtract<T[K], 'req'>, sender: chrome.runtime.MessageSender) => AsyncOrSync<SafeExtract<T[K], 'res'>> : never;
+
+declare type MessageInterface<T extends ValidatedMessageDefinitions> = {
+    [K in keyof T]: T[K] extends MessageShape ? (req: SafeExtract<T[K], 'req'>) => Promise<SafeExtract<T[K], 'res'>> : never;
+};
+
+/**
+ * メッセージハンドラーのレスポンス型で、成功か失敗かを表すユーティリティ型です。
+ *
+ * 成功時は `{ success: true }` または `{ success: true, message: T }` を、
+ * 失敗時は `{ success: false, message: string }` を返します。
+ *
+ * @template T - 成功時に返すデータの型。省略時は `void` です。
+ *
+ * @example
+ * ```ts
+ * // データなしの成功レスポンス
+ * type SimpleRes = MessageResponse;
+ * // { success: true } | { success: false, message: string }
+ *
+ * // データありの成功レスポンス
+ * type DataRes = MessageResponse<User>;
+ * // { success: true, message: User } | { success: false, message: string }
+ * ```
+ */
+export declare type MessageResponse<T = void> = SuccessMessageResponse<T> | FailureMessageResponse;
+
+declare type MessageShape = {
+    req?: JsonValue;
+    res?: JsonValue;
+};
+
+/**
+ * メッセージを受信するためのレシーバーを作成します。
+ *
+ * @template T - メッセージ定義の型。`MergeMessageDefinitions` で作成した型を指定します。
+ * @param scope - 受信するメッセージのスコープ名。送信側（`connect`）と一致させる必要があります。
+ * @returns メッセージハンドラーを登録するための `Receiver` インスタンスです。
+ *
+ * @example
+ * ```ts
+ * type Messages = MergeMessageDefinitions<{ remote: RemoteMessages }>;
+ *
+ * const receiver = receive<Messages>('remote');
+ * receiver.on('addRepository', (req, sender) => {
+ *   console.log(req.url);
+ *   return { success: true };
+ * });
+ * ```
+ */
+export declare function receive<T extends MergedMessageDefinitions>(scope: keyof T & string): Receiver<T, keyof T & string>;
+
+declare class Receiver<T extends MergedMessageDefinitions, K extends keyof T & string> {
+    private handlers;
+    constructor(scope: K);
+    /**
+     * 指定したメッセージ名に対するハンドラーを登録します。
+     *
+     * 同じスコープ、同じ名前で複数のハンドラーは登録できず、エラーを投げます。
+     *
+     * @param name - 処理するメッセージの名前。`MessageDefinitions` で定義した名前（キー）を指定します。
+     * @param handler - メッセージを処理するコールバック関数。引数は以下の通りです:
+     *   - `req`: 送信側から送られたリクエストデータ
+     *   - `sender`: `chrome.runtime.MessageSender` オブジェクト（タブ情報等）
+     * @returns 送信側に返すレスポンス。Promiseを返すと自動的に解決されます。
+     * @throws 同じスコープ、同じ名前のハンドラーが既に登録されている場合
+     *
+     * @example
+     * ```ts
+     * const receiver = receive<Message>("remote");
+     *
+     * receiver.on('addRepository', (req, sender) => {
+     *   console.log(req.url);
+     *   console.log(sender.tab?.id);
+     *   return { success: true };
+     * });
+     *
+     * // 非同期のハンドラーも指定可能
+     * receiver.on('fetchData', async (req) => {
+     *   const data = await someAsyncOperation(req);
+     *   return { success: true, message: data };
+     * });
+     * ```
+     */
+    on<V extends keyof T[K] & string>(name: V, handler: MessageHandler<T[K], V>): void;
+    private _typed;
+}
+
+declare type SafeExtract<T, K> = K extends keyof T ? T[K] : void;
+
+/**
+ * 成功時のレスポンス型です。
+ *
+ * - `T` が `void` の場合: `{ success: true }`
+ * - `T` が `void` 以外の場合: `{ success: true, message: T }`
+ *
+ * @template T - 成功時に返すデータの型。省略時は `void` です。
+ */
+export declare type SuccessMessageResponse<T = void> = T extends void ? {
+    success: true;
+} : {
+    success: true;
+    message: T;
+};
+
+declare type ValidatedMessageDefinitions = Record<string, MessageShape>;
+
+export { }

package/dist/main.js

@@ -0,0 +1,72 @@
+class c {
+  handlers = {};
+  constructor(r) {
+    chrome.runtime.onMessage.addListener((e, o, i) => {
+      if (this._typed(e) && e.scope === r)
+        return (async () => {
+          const t = this.handlers[e.name];
+          if (!t)
+            throw new Error(
+              `scope: "${r}", name: "${e.name}" のハンドラーが未定義です。`
+            );
+          const s = await Promise.resolve(t(e.req, o));
+          i(s);
+        })(), !0;
+    });
+  }
+  /**
+   * 指定したメッセージ名に対するハンドラーを登録します。
+   *
+   * 同じスコープ、同じ名前で複数のハンドラーは登録できず、エラーを投げます。
+   *
+   * @param name - 処理するメッセージの名前。`MessageDefinitions` で定義した名前（キー）を指定します。
+   * @param handler - メッセージを処理するコールバック関数。引数は以下の通りです:
+   *   - `req`: 送信側から送られたリクエストデータ
+   *   - `sender`: `chrome.runtime.MessageSender` オブジェクト（タブ情報等）
+   * @returns 送信側に返すレスポンス。Promiseを返すと自動的に解決されます。
+   * @throws 同じスコープ、同じ名前のハンドラーが既に登録されている場合
+   *
+   * @example
+   * ```ts
+   * const receiver = receive<Message>("remote");
+   *
+   * receiver.on('addRepository', (req, sender) => {
+   *   console.log(req.url);
+   *   console.log(sender.tab?.id);
+   *   return { success: true };
+   * });
+   *
+   * // 非同期のハンドラーも指定可能
+   * receiver.on('fetchData', async (req) => {
+   *   const data = await someAsyncOperation(req);
+   *   return { success: true, message: data };
+   * });
+   * ```
+   */
+  on(r, e) {
+    if (r in this.handlers)
+      throw new Error("同じ名前のメッセージリスナーは複数登録できません");
+    this.handlers[r] = e;
+  }
+  _typed(r) {
+    return typeof r?.scope == "string" && typeof r?.name == "string";
+  }
+}
+function h(n) {
+  return new Proxy({}, {
+    get(r, e) {
+      return (o) => new Promise(
+        (i, t) => chrome.runtime.sendMessage({ scope: n, name: e, req: o }, (s) => {
+          chrome.runtime.lastError ? t(chrome.runtime.lastError) : i(s);
+        })
+      );
+    }
+  });
+}
+function u(n) {
+  return new c(n);
+}
+export {
+  h as connect,
+  u as receive
+};

package/dist/main.umd.cjs

@@ -0,0 +1 @@
+(function(r,t){typeof exports=="object"&&typeof module<"u"?t(exports):typeof define=="function"&&define.amd?define(["exports"],t):(r=typeof globalThis<"u"?globalThis:r||self,t(r.main={}))})(this,(function(r){"use strict";class t{handlers={};constructor(e){chrome.runtime.onMessage.addListener((n,s,c)=>{if(this._typed(n)&&n.scope===e)return(async()=>{const o=this.handlers[n.name];if(!o)throw new Error(`scope: "${e}", name: "${n.name}" のハンドラーが未定義です。`);const u=await Promise.resolve(o(n.req,s));c(u)})(),!0})}on(e,n){if(e in this.handlers)throw new Error("同じ名前のメッセージリスナーは複数登録できません");this.handlers[e]=n}_typed(e){return typeof e?.scope=="string"&&typeof e?.name=="string"}}function d(i){return new Proxy({},{get(e,n){return s=>new Promise((c,o)=>chrome.runtime.sendMessage({scope:i,name:n,req:s},u=>{chrome.runtime.lastError?o(chrome.runtime.lastError):c(u)}))}})}function f(i){return new t(i)}r.connect=d,r.receive=f,Object.defineProperty(r,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "typed-msg",
+  "version": "1.0.0",
+  "description": "Chrome拡張機能のSW⇔Content Scripts間の通信を型安全にするライブラリ",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "format": "prettier --write \"src/**/*.ts\" --log-level warn",
+    "docs": "npx typedoc"
+  },
+  "author": "vrcalphabet",
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/chrome": "^0.1.36",
+    "@types/node": "^25.2.1",
+    "typedoc": "^0.28.16",
+    "typescript": "^5.8.2",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}