crx-rpc 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+import type { IMessageAdapter } from './types';
+import type { Identifier } from './id';
+import { Disposable } from './disposable';
+type FunctionArgs<T> = T extends (...args: infer A) => any ? A : never;
+type FunctionReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+type ServiceProxy<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => any ? (...args: FunctionArgs<T[K]>) => Promise<Awaited<FunctionReturnType<T[K]>>> : never;
+};
+export declare class RPCClient extends Disposable {
+    private messageAdapter;
+    private pending;
+    constructor(messageAdapter: IMessageAdapter);
+    call<T = any>(service: string, method: string, args: any[]): Promise<T>;
+    createWebRPCService<T>(serviceIdentifier: Identifier<T>): ServiceProxy<T>;
+}
+export declare class BaseObservable<T> extends Disposable {
+    private identifier;
+    private key;
+    private _callback;
+    private _adapter;
+    private listeners;
+    private completed;
+    private get _finalKey();
+    constructor(identifier: Identifier<T>, key: string, _callback: (value: T) => void, _adapter: IMessageAdapter);
+    unsubscribe(): void;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,88 @@
+import { OBSERVABLE_EVENT, RPC_EVENT_NAME, RPC_RESPONSE_EVENT_NAME, UNSUBSCRIBE_OBSERVABLE } from './const';
+import { Disposable } from './disposable';
+export class RPCClient extends Disposable {
+    messageAdapter;
+    pending = new Map();
+    constructor(messageAdapter) {
+        super();
+        this.messageAdapter = messageAdapter;
+        this.disposeWithMe(messageAdapter.onMessage(RPC_RESPONSE_EVENT_NAME, (event) => {
+            const { id, result, error } = event;
+            const promise = this.pending.get(id);
+            if (!promise)
+                return;
+            this.pending.delete(id);
+            if (error) {
+                const err = new Error(error.message);
+                err.name = error.name || 'RPCError';
+                err.stack = error.stack;
+                promise.reject(err);
+            }
+            else {
+                promise.resolve(result);
+            }
+        }));
+    }
+    call(service, method, args) {
+        const id = crypto.randomUUID();
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            const requestParam = {
+                method,
+                args,
+                id,
+                service,
+            };
+            this.messageAdapter.sendMessage(RPC_EVENT_NAME, requestParam);
+        });
+    }
+    createWebRPCService(serviceIdentifier) {
+        const serviceKey = serviceIdentifier.key;
+        // 创建代理对象，拦截方法调用
+        return new Proxy({}, {
+            get: (target, prop) => {
+                if (typeof prop === 'string') {
+                    // 返回一个代理函数
+                    return (...args) => {
+                        return this.call(serviceKey, prop, args);
+                    };
+                }
+                return target[prop];
+            },
+        });
+    }
+}
+export class BaseObservable extends Disposable {
+    identifier;
+    key;
+    _callback;
+    _adapter;
+    listeners = new Set();
+    completed = false;
+    get _finalKey() {
+        return `${this.identifier.key}-${this.key}`;
+    }
+    constructor(identifier, key, _callback, _adapter) {
+        super();
+        this.identifier = identifier;
+        this.key = key;
+        this._callback = _callback;
+        this._adapter = _adapter;
+        this.disposeWithMe(this._adapter.onMessage(OBSERVABLE_EVENT, (event) => {
+            const msg = event.detail;
+            if (msg.key !== this._finalKey)
+                return;
+            if (msg.operation === 'next' && !this.completed && msg.value) {
+                this._callback(msg.value);
+            }
+            if (msg.operation === 'complete') {
+                this.completed = true;
+                this.listeners.clear();
+            }
+        }));
+        this._adapter.sendMessage(OBSERVABLE_EVENT, { key: this._finalKey });
+    }
+    unsubscribe() {
+        this._adapter.sendMessage(UNSUBSCRIBE_OBSERVABLE, { key: this._finalKey });
+    }
+}

package/dist/const.d.ts

@@ -0,0 +1,5 @@
+export declare const RPC_EVENT_NAME = "__RPC_CALL_CLIPSHEET_AWESOME__";
+export declare const RPC_RESPONSE_EVENT_NAME = "__RPC_RESPONSE_CLIPSHEET_AWESOME__";
+export declare const SUBSCRIBABLE_OBSERVABLE = "__SUBSCRIBABLE_OBSERVABLE__";
+export declare const UNSUBSCRIBE_OBSERVABLE = "__UNSUBSCRIBE_OBSERVABLE__";
+export declare const OBSERVABLE_EVENT = "__OBSERVABLE_EVENT__";

package/dist/const.js

@@ -0,0 +1,5 @@
+export const RPC_EVENT_NAME = '__RPC_CALL_CLIPSHEET_AWESOME__';
+export const RPC_RESPONSE_EVENT_NAME = '__RPC_RESPONSE_CLIPSHEET_AWESOME__';
+export const SUBSCRIBABLE_OBSERVABLE = '__SUBSCRIBABLE_OBSERVABLE__';
+export const UNSUBSCRIBE_OBSERVABLE = '__UNSUBSCRIBE_OBSERVABLE__';
+export const OBSERVABLE_EVENT = '__OBSERVABLE_EVENT__';

package/dist/content.d.ts

@@ -0,0 +1,14 @@
+import { BaseObservable, RPCClient } from './client';
+import { Disposable } from './disposable';
+import { Identifier } from './id';
+import type { IMessageAdapter } from './types';
+export declare class ContentRPC extends Disposable {
+    constructor();
+}
+export declare const contentMessageAdapter: IMessageAdapter;
+export declare class ContentRPCClient extends RPCClient {
+    constructor();
+}
+export declare class ContentObservable<T> extends BaseObservable<T> {
+    constructor(identifier: Identifier<T>, key: string, callback: (value: T) => void);
+}

package/dist/content.js

@@ -0,0 +1,55 @@
+import { BaseObservable, RPCClient } from './client';
+import { OBSERVABLE_EVENT, RPC_EVENT_NAME, RPC_RESPONSE_EVENT_NAME, SUBSCRIBABLE_OBSERVABLE, UNSUBSCRIBE_OBSERVABLE } from './const';
+import { Disposable } from './disposable';
+const WEB_TO_BACKGROUND = [RPC_EVENT_NAME, SUBSCRIBABLE_OBSERVABLE, UNSUBSCRIBE_OBSERVABLE];
+const BACKGROUND_TO_WEB = [RPC_RESPONSE_EVENT_NAME, OBSERVABLE_EVENT];
+export class ContentRPC extends Disposable {
+    constructor() {
+        super();
+        WEB_TO_BACKGROUND.forEach(eventName => {
+            const handler = (event) => {
+                chrome.runtime.sendMessage({ ...event.detail, type: eventName });
+            };
+            window.addEventListener(eventName, handler);
+            this.disposeWithMe(() => {
+                window.removeEventListener(eventName, handler);
+            });
+        });
+        const handler = (msg) => {
+            if (!BACKGROUND_TO_WEB.includes(msg.type))
+                return;
+            const { type, ...detail } = msg;
+            window.dispatchEvent(new CustomEvent(type, { detail }));
+        };
+        chrome.runtime.onMessage.addListener(handler);
+        this.disposeWithMe(() => {
+            chrome.runtime.onMessage.removeListener(handler);
+        });
+    }
+}
+export const contentMessageAdapter = {
+    onMessage(type, callback) {
+        const handler = (msg) => {
+            if (msg.type === type) {
+                callback(msg);
+            }
+        };
+        chrome.runtime.onMessage.addListener(handler);
+        return () => {
+            chrome.runtime.onMessage.removeListener(handler);
+        };
+    },
+    sendMessage(type, message) {
+        chrome.runtime.sendMessage({ ...message, type });
+    },
+};
+export class ContentRPCClient extends RPCClient {
+    constructor() {
+        super(contentMessageAdapter);
+    }
+}
+export class ContentObservable extends BaseObservable {
+    constructor(identifier, key, callback) {
+        super(identifier, key, callback, contentMessageAdapter);
+    }
+}

package/dist/disposable.d.ts

@@ -0,0 +1,7 @@
+export declare class Disposable {
+    private _isDisposed;
+    private _disposeCallbacks;
+    dispose(): void;
+    isDisposed(): boolean;
+    protected disposeWithMe(disposeLike: () => void): void;
+}

package/dist/disposable.js

@@ -0,0 +1,16 @@
+export class Disposable {
+    _isDisposed = false;
+    _disposeCallbacks = new Set();
+    dispose() {
+        if (this._isDisposed)
+            return;
+        this._isDisposed = true;
+        this._disposeCallbacks.forEach(callback => callback());
+    }
+    isDisposed() {
+        return this._isDisposed;
+    }
+    disposeWithMe(disposeLike) {
+        this._disposeCallbacks.add(disposeLike);
+    }
+}

package/dist/id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Identifier 类型，既携带类型信息，又在运行时能唯一标识。
+ */
+export interface Identifier<T> {
+    key: string;
+    __type?: T;
+}
+/**
+ * 创建一个 Identifier。
+ * @param key 唯一字符串标识
+ */
+export declare function createIdentifier<T>(key: string): Identifier<T>;

package/dist/id.js

@@ -0,0 +1,8 @@
+// shared/utils/identifier.ts
+/**
+ * 创建一个 Identifier。
+ * @param key 唯一字符串标识
+ */
+export function createIdentifier(key) {
+    return { key };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './background';
+export * from './content';
+export * from './types';
+export * from './id';
+export * from './web';
+export * from './content';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './background';
+export * from './content';
+export * from './types';
+export * from './id';
+export * from './web';
+export * from './content';

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+export interface RpcRequest {
+    id: string;
+    method: string;
+    service: string;
+    args: any[];
+}
+export interface RpcResponse {
+    id: string;
+    result?: any;
+    error?: {
+        message: string;
+        stack?: string;
+        name?: string;
+    };
+    service: string;
+    method: string;
+}
+export type RpcHandler = (...args: any[]) => Promise<any> | any;
+export type RpcService = Record<string, RpcHandler>;
+export interface ObservableLike<T> {
+    subscribe(next: (value: T) => void): () => void;
+}
+export interface SubjectLike<T> extends ObservableLike<T> {
+    next(value: T): void;
+    complete(): void;
+}
+export interface RpcObservableUpdateMessage<T> {
+    type: string;
+    operation: 'next' | 'complete';
+    key: string;
+    value?: T;
+}
+export interface RpcObservableSubscribeMessage {
+    type: string;
+    key: string;
+}
+export interface IMessageAdapter {
+    onMessage<T>(type: string, callback: (message: T) => void): () => void;
+    sendMessage<T>(type: string, message: T): void;
+}
+export interface IDisposable {
+    dispose(): void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/web.d.ts

@@ -0,0 +1,10 @@
+import { BaseObservable, RPCClient } from "./client";
+import { Identifier } from "./id";
+import { IMessageAdapter } from "./types";
+export declare const webMessageAdapter: IMessageAdapter;
+export declare class WebRPCClient extends RPCClient {
+    constructor();
+}
+export declare class WebObservable<T> extends BaseObservable<T> {
+    constructor(identifier: Identifier<T>, key: string, callback: (value: T) => void);
+}

package/dist/web.js

@@ -0,0 +1,25 @@
+import { BaseObservable, RPCClient } from "./client";
+export const webMessageAdapter = {
+    onMessage(type, callback) {
+        const handler = (event) => {
+            callback(event.detail);
+        };
+        window.addEventListener(type, handler);
+        return () => {
+            window.removeEventListener(type, handler);
+        };
+    },
+    sendMessage(type, message) {
+        window.dispatchEvent(new CustomEvent(type, { detail: message }));
+    },
+};
+export class WebRPCClient extends RPCClient {
+    constructor() {
+        super(webMessageAdapter);
+    }
+}
+export class WebObservable extends BaseObservable {
+    constructor(identifier, key, callback) {
+        super(identifier, key, callback, webMessageAdapter);
+    }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "crx-rpc",
+    "version": "1.0.0",
+    "description": "A lightweight RPC framework for Chrome Extension (background <-> content <-> web)",
+    "author": "YourName",
+    "license": "MIT",
+    "keywords": [
+        "chrome-extension",
+        "rpc",
+        "content-script",
+        "background",
+        "typescript"
+    ],
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsc",
+        "watch": "tsc -w",
+        "clean": "rm -rf dist",
+        "postinstall": "tsc"
+    },
+    "devDependencies": {
+        "@types/chrome": "^0.0.270",
+        "@types/node": "^24.3.0",
+        "typescript": "^5.2.2"
+    }
+}

package/src/background.ts

@@ -0,0 +1,162 @@
+import type { Identifier } from './id';
+import { OBSERVABLE_EVENT, RPC_EVENT_NAME, RPC_RESPONSE_EVENT_NAME, SUBSCRIBABLE_OBSERVABLE, UNSUBSCRIBE_OBSERVABLE } from './const';
+import type { RpcRequest, RpcResponse, RpcService, SubjectLike, RpcObservableUpdateMessage, RpcObservableSubscribeMessage } from './types';
+import { Disposable } from './disposable';
+
+export class BackgroundRPC extends Disposable {
+    private services: Record<string, RpcService> = {};
+
+    constructor() {
+        super();
+        const handler = ((msg: RpcRequest & { type?: string }, sender: chrome.runtime.MessageSender) => {
+            if (msg.type !== RPC_EVENT_NAME) return;
+            const senderId = sender.tab!.id!;
+            const sendResponse = (response: RpcResponse) => {
+                chrome.tabs.sendMessage(senderId, {
+                    ...response,
+                    type: RPC_RESPONSE_EVENT_NAME
+                });
+            };
+
+            const { id, method, args, service } = msg;
+            const serviceInstance = this.services[service];
+
+            if (!serviceInstance) {
+                const resp: RpcResponse = {
+                    id,
+                    error: { message: `Unknown service: ${service}` },
+                    service,
+                    method,
+                };
+                sendResponse(resp);
+                return true;
+            }
+
+            if (!(method in serviceInstance)) {
+                const resp: RpcResponse = {
+                    id,
+                    error: { message: `Unknown method: ${method}` },
+                    service,
+                    method,
+                };
+                sendResponse(resp);
+                return true;
+            }
+
+            Promise.resolve()
+                .then(() => serviceInstance[method](...args))
+                .then((result) => sendResponse({
+                    id,
+                    result,
+                    service,
+                    method
+                }))
+                .catch((err) => sendResponse({
+                    id,
+                    error: {
+                        message: err.message,
+                        stack: err.stack,
+                        name: err.name
+                    },
+                    service,
+                    method
+                }));
+
+            return true; // 异步 sendResponse
+        });
+
+        chrome.runtime.onMessage.addListener(handler);
+        this.disposeWithMe(() => {
+            chrome.runtime.onMessage.removeListener(handler);
+        });
+    }
+
+    register<T>(service: Identifier<T>, serviceInstance: T) {
+        this.services[service.key] = serviceInstance as unknown as RpcService;
+    }
+}
+
+export class RemoteSubject<T> extends Disposable implements SubjectLike<T> {
+    private completed = false;
+
+    private get _finalKey() {
+        return `${this.identifier.key}-${this._key}`;
+    }
+
+    private senders = new Set<number>();
+
+    constructor(
+        private identifier: Identifier<T>,
+        private _key: string,
+        private initialValue: T,
+    ) {
+        super();
+        // 初始化时立即广播一次
+        const handleMessage = (msg: RpcObservableSubscribeMessage, sender: chrome.runtime.MessageSender) => {
+            const senderId = sender.tab!.id!;
+            if (!senderId) return;
+
+            if (msg.type === SUBSCRIBABLE_OBSERVABLE) {
+                const { key } = msg;
+                if (key === this._finalKey) {
+                    this.senders.add(senderId);
+                    chrome.tabs.sendMessage(senderId, {
+                        operation: 'next',
+                        key: this._finalKey,
+                        value: this.initialValue,
+                    });
+                }
+            }
+
+            if (msg.type === UNSUBSCRIBE_OBSERVABLE) {
+                const { key } = msg;
+                if (key === this._finalKey) {
+                    this.senders.delete(senderId);
+                }
+            }
+        }
+        chrome.runtime.onMessage.addListener(handleMessage);
+        this.disposeWithMe(() => {
+            chrome.runtime.onMessage.removeListener(handleMessage);
+        });
+
+        const handleRemove = (tabId: number) => {
+            this.senders.delete(tabId);
+        };
+        chrome.tabs.onRemoved.addListener(handleRemove);
+        this.disposeWithMe(() => {
+            chrome.tabs.onRemoved.removeListener(handleRemove);
+        });
+    }
+
+    private _sendMessage(message: RpcObservableUpdateMessage<any>) {
+        chrome.runtime.sendMessage(message);
+        this.senders.forEach(senderId => {
+            chrome.tabs.sendMessage(senderId, message);
+        });
+    }
+
+    next(value: T): void {
+        if (this.completed) return;
+        this._sendMessage({
+            operation: 'next',
+            key: this._finalKey,
+            value,
+            type: OBSERVABLE_EVENT
+        });
+    }
+
+    complete(): void {
+        if (this.completed) return;
+        this.completed = true;
+        this._sendMessage({
+            operation: 'complete',
+            key: this._finalKey,
+            type: OBSERVABLE_EVENT
+        });
+    }
+
+    subscribe(): () => void {
+        throw new Error('RemoteSubject should not be subscribed locally.');
+    }
+}

package/src/client.ts

@@ -0,0 +1,110 @@
+import { OBSERVABLE_EVENT, RPC_EVENT_NAME, RPC_RESPONSE_EVENT_NAME, UNSUBSCRIBE_OBSERVABLE } from './const';
+import type { RpcRequest, RpcResponse, RpcObservableUpdateMessage, IMessageAdapter } from './types';
+import type { Identifier } from './id';
+import { Disposable } from './disposable';
+
+// 类型工具：提取函数类型的参数和返回值类型
+type FunctionArgs<T> = T extends (...args: infer A) => any ? A : never;
+type FunctionReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+
+// 类型工具：将服务接口转换为客户端代理类型
+type ServiceProxy<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => any
+    ? (...args: FunctionArgs<T[K]>) => Promise<Awaited<FunctionReturnType<T[K]>>>
+    : never;
+};
+
+export class RPCClient extends Disposable {
+    private pending: Map<string, { resolve: Function; reject: Function }> = new Map();
+
+    constructor(
+        private messageAdapter: IMessageAdapter
+    ) {
+        super();
+        this.disposeWithMe(messageAdapter.onMessage<RpcResponse>(RPC_RESPONSE_EVENT_NAME, (event: RpcResponse) => {
+            const { id, result, error } = event as RpcResponse;
+            const promise = this.pending.get(id);
+            if (!promise) return;
+
+            this.pending.delete(id);
+
+            if (error) {
+                const err = new Error(error.message);
+                err.name = error.name || 'RPCError';
+                err.stack = error.stack;
+                promise.reject(err);
+            } else {
+                promise.resolve(result);
+            }
+        }));
+    }
+
+    call<T = any>(service: string, method: string, args: any[]): Promise<T> {
+        const id = crypto.randomUUID();
+        return new Promise<T>((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            const requestParam: RpcRequest = {
+                method,
+                args,
+                id,
+                service,
+            };
+            this.messageAdapter.sendMessage(RPC_EVENT_NAME, requestParam);
+        });
+    }
+
+    createWebRPCService<T>(serviceIdentifier: Identifier<T>): ServiceProxy<T> {
+        const serviceKey = serviceIdentifier.key;
+
+        // 创建代理对象，拦截方法调用
+        return new Proxy({} as ServiceProxy<T>, {
+            get: (target, prop: string | symbol) => {
+                if (typeof prop === 'string') {
+                    // 返回一个代理函数
+                    return (...args: any[]) => {
+                        return this.call(serviceKey, prop, args);
+                    };
+                }
+                return (target as any)[prop];
+            },
+        });
+    }
+}
+
+export class BaseObservable<T> extends Disposable {
+    private listeners = new Set<(value: T) => void>();
+    private completed = false;
+
+    private get _finalKey() {
+        return `${this.identifier.key}-${this.key}`;
+    }
+
+    constructor(
+        private identifier: Identifier<T>,
+        private key: string,
+        private _callback: (value: T) => void,
+        private _adapter: IMessageAdapter
+    ) {
+        super();
+        this.disposeWithMe(this._adapter.onMessage(OBSERVABLE_EVENT, (event: any) => {
+            const msg = event.detail as RpcObservableUpdateMessage<T>;
+            if (msg.key !== this._finalKey) return;
+
+            if (msg.operation === 'next' && !this.completed && msg.value) {
+                this._callback(msg.value);
+            }
+
+            if (msg.operation === 'complete') {
+                this.completed = true;
+                this.listeners.clear();
+            }
+        }));
+
+        this._adapter.sendMessage(OBSERVABLE_EVENT, { key: this._finalKey });
+    }
+
+    unsubscribe(): void {
+        this._adapter.sendMessage(UNSUBSCRIBE_OBSERVABLE, { key: this._finalKey });
+    }
+}
+

package/src/const.ts

@@ -0,0 +1,6 @@
+export const RPC_EVENT_NAME = '__RPC_CALL_CLIPSHEET_AWESOME__';
+export const RPC_RESPONSE_EVENT_NAME = '__RPC_RESPONSE_CLIPSHEET_AWESOME__';
+
+export const SUBSCRIBABLE_OBSERVABLE = '__SUBSCRIBABLE_OBSERVABLE__';
+export const UNSUBSCRIBE_OBSERVABLE = '__UNSUBSCRIBE_OBSERVABLE__';
+export const OBSERVABLE_EVENT = '__OBSERVABLE_EVENT__';