rimless 0.8.1 → 0.8.2

package/lib/guest.d.ts

@@ -0,0 +1,6 @@
+import { Connection, EventHandlers, Schema } from './types';
+declare function connect(schema?: Schema, eventHandlers?: EventHandlers): Promise<Connection>;
+declare const _default: {
+    connect: typeof connect;
+};
+export default _default;

package/lib/helpers.d.ts

@@ -0,0 +1,65 @@
+import { Guest, NodeWorker, Target, WorkerLike } from './types';
+type RuntimeEnvironment = "browser" | "worker" | "node" | "bun";
+export declare function getRuntimeEnvironment(): RuntimeEnvironment;
+export declare function isBrowserEnv(): boolean;
+/**
+ * check if run in a webworker
+ *
+ * @returns boolean
+ */
+export declare function isWorker(): boolean;
+/**
+ * check if run in a Node.js environment
+ *
+ * @returns boolean
+ */
+export declare function isNodeEnv(): boolean;
+export declare function isBunEnv(): boolean;
+export declare function isServerEnv(): boolean;
+/**
+ * check if run in an iframe
+ *
+ * @returns boolean
+ */
+export declare function isIframe(): boolean;
+/**
+ * we cannot send functions through postMessage
+ * extract the path to all functions in the schema
+ *
+ * @param obj
+ */
+export declare function extractMethods(obj: any): Record<string, (...args: any) => any>;
+/**
+ * convert the url into an origin (remove paths)
+ *
+ * @param url
+ */
+export declare function getOriginFromURL(url: string | null): string | null;
+export declare function resolveTargetOrigin(origin?: string | null): string;
+export declare function get(obj: any, path: string | Array<string | number>, defaultValue?: any): any;
+export declare function set(obj: any, path: string | (string | number)[], value: any): any;
+export declare function generateId(length?: number): string;
+/**
+ * Get the appropriate target host for messaging based on the current environment
+ * @returns The messaging target for the current environment
+ */
+export declare function getTargetHost(): any;
+/**
+ * Send a message to a target, handling different environments (iframe, web worker, node worker)
+ * @param target The target to send the message to
+ * @param message The message to send
+ * @param origin Optional origin for iframe communication
+ * @param transferables Optional transferables for postMessage
+ */
+export declare function postMessageToTarget(target: Target, message: any, origin?: string | null, transferables?: Transferable[]): void;
+export declare function isNodeWorker(guest: Guest | Target): guest is NodeWorker;
+export declare function isWorkerLike(guest: Guest): guest is WorkerLike;
+export declare function addEventListener(target: Target, event: string, handler: EventListenerOrEventListenerObject): void;
+export declare function removeEventListener(target: Target, event: string, handler: EventListenerOrEventListenerObject): void;
+/**
+ * Normalize message event data across Web and Node.js environments
+ * In web, data is in event.data
+ * In Node.js, the event itself contains the data
+ */
+export declare function getEventData(event: any): any;
+export {};

package/lib/host.d.ts

@@ -0,0 +1,14 @@
+import { Connection, Guest, Schema } from './types';
+/**
+ * Perform a handshake with the target iframe, when the handshake is confirmed
+ * resolve the connection object containing RPCs and properties
+ *
+ * @param guest
+ * @param schema
+ * @returns Promise
+ */
+declare function connect(guest: Guest, schema?: Schema): Promise<Connection>;
+declare const _default: {
+    connect: typeof connect;
+};
+export default _default;

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+import { default as guest } from './guest';
+import { default as host } from './host';
+import { withTransferable } from './rpc';
+export * from './types';
+export { guest, host, withTransferable };

package/lib/rpc.d.ts

@@ -0,0 +1,76 @@
+import { Environment, RimlessEvent, Schema, Target } from './types';
+/** Private symbol to which we will assign transferable objects */
+declare const SYM_TRANSFERABLES: unique symbol;
+/**
+ * for each function in methods
+ * 1. subscribe to an event that the remote can call
+ * 2. listen for calls from the remote. When called execute the function and emit the results.
+ *
+ * @param methods an object of method ids : methods from the local schema
+ * @param rpcConnectionID
+ * @param listenTo Environment to listen for incoming messages
+ * @param sendTo Target to send outgoing messages
+ * @param remote The remote API object for the current connection
+ * @return a function to cancel all subscriptions
+ */
+export declare function registerLocalMethods(methods: Record<string, (...args: any[]) => any> | undefined, rpcConnectionID: string, listenTo: Environment, sendTo: Target, remote: Schema): () => void;
+/**
+ * Create a function that will make an RPC request to the remote with some arguments.
+ * Listen to an event that returns the results from the remote.
+ *
+ * @param rpcCallName
+ * @param rpcConnectionID
+ * @param event
+ * @param listeners
+ * @param guest
+ *
+ * @returns a promise with the result of the RPC
+ */
+export declare function createRPC(rpcCallName: string, rpcConnectionID: string, event: RimlessEvent, listeners: Array<() => void> | undefined, listenTo: Environment, sendTo: Target): (...args: any[]) => Promise<unknown>;
+/**
+ * create an object based on the remote schema's methods. Functions in that object will
+ * emit an event that will trigger the RPC on the remote.
+ *
+ * @param schema
+ * @param methods
+ * @param connectionID
+ * @param event
+ * @param guest
+ */
+export declare function registerRemoteMethods(schema: Schema | undefined, methodNames: Iterable<string> | undefined, connectionID: string, event: RimlessEvent, listenTo: Environment, sendTo: Target): {
+    remote: {
+        [x: string]: any;
+    };
+    unregisterRemote: () => void;
+};
+/**
+ * This function is used by API schema declarations and remote function calls alike to
+ * indicate which variables should be declared as transferable over `postMessage` calls.
+ *
+ * @param cb a function that takes a transfer function as an argument and returns an object
+ *           (in the loose, `typeof foo === "object"` sense)
+ * @return result the callback's return value, with an extra array of transferable objects
+ *                assigned to rimless' private symbol `SYM_TRANSFERABLES`
+ *
+ * The `transfer(...)` function is called with an object to transfer; if there
+ * are many objects to transfer, you may call it multiple times. It will always
+ * return the input object. Calling `transfer` only modifies the callback
+ * result, not the transferred object itself (or objects themselves).
+ *
+ * @example
+ * host.connect({
+ *   foo: (...args) => {
+ *     const foo = new ArrayBuffer(8);
+ *     return withTransferable((transfer) => transfer(foo));
+ *   }),
+ * });
+ *
+ * @example
+ * host.remote.foo(withTransferable((transfer) => ({
+ *   stream: transfer(new ReadableStream()),
+ * })));
+ */
+export declare const withTransferable: <Transferable, Result extends object>(cb: (transfer: <T extends Transferable>(transferable: T) => T) => Result) => Result & {
+    [SYM_TRANSFERABLES]: Transferable[];
+};
+export {};

package/lib/types.d.ts

@@ -0,0 +1,62 @@
+export interface NodeWorker {
+    on(event: string, handler: any): void;
+    off(event: string, handler: any): void;
+    postMessage(message: any): void;
+    terminate(): void;
+}
+export type WorkerLike = Worker | NodeWorker;
+export declare enum events {
+    MESSAGE = "message"
+}
+export declare enum actions {
+    HANDSHAKE_REQUEST = "RIMLESS/HANDSHAKE_REQUEST",
+    HANDSHAKE_REPLY = "RIMLESS/HANDSHAKE_REPLY",
+    RPC_REQUEST = "RIMLESS/RPC_REQUEST",
+    RPC_RESOLVE = "RIMLESS/RPC_RESOLVE",
+    RPC_REJECT = "RIMLESS/RPC_REJECT"
+}
+export type Schema = Record<string, any>;
+export interface Connection {
+    id: string;
+    remote: Schema;
+    close: () => void;
+}
+export type Connections = Record<string, Connection>;
+export interface RimlessEvent extends EventListener {
+    source?: Window;
+    origin?: string;
+    data: HandshakeRequestPayload | HandshakeConfirmationPayload | RPCRequestPayload | RPCResolvePayload;
+}
+export interface HandshakeRequestPayload {
+    action: actions.HANDSHAKE_REQUEST;
+    connectionID: string;
+    methodNames: string[];
+    schema: Schema;
+}
+export interface HandshakeConfirmationPayload {
+    action: actions.HANDSHAKE_REPLY;
+    connectionID: string;
+    methodNames: string[];
+    schema: Schema;
+}
+export interface RPCRequestPayload {
+    action: actions.RPC_REQUEST;
+    args: any[];
+    callID: string;
+    callName: string;
+    connectionID: string;
+}
+export interface RPCResolvePayload {
+    action: actions.RPC_RESOLVE | actions.RPC_REJECT;
+    result?: any | null;
+    error?: Error | null;
+    callID: string;
+    callName: string;
+    connectionID: string;
+}
+export interface EventHandlers {
+    onConnectionSetup: (remote: Schema) => Promise<void>;
+}
+export type Guest = WorkerLike | HTMLIFrameElement;
+export type Target = Window | WorkerLike;
+export type Environment = Window | WorkerLike;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rimless",
   "author": "Aurélien Franky",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "license": "MIT",
   "homepage": "https://github.com/au-re/rimless",
   "description": "event base communication made easy with a promise-based API wrapping `postMessage`",