@xentobias/worker-rpc 1.0.15 → 1.0.16

package/dist/broadcast.d.ts

@@ -34,10 +34,6 @@ export declare class BroadcastEndpoint extends Endpoint {
      * @returns Promise that resolves with a BroadcastResult containing results and errors
      */
     call(path: MethodPath, args: unknown[]): Promise<BroadcastResult>;
-    /**
-     * Send a broadcast message and set up multi-response handling
-     */
-    private sendBroadcast;
     /**
      * Handle timeout for a broadcast call
      */

package/dist/endpoint.d.ts

@@ -1,4 +1,5 @@
 import { type RpcMessage, type CallMessage, type ResultMessage, type ErrorMessage, type MethodPath, type PendingCall, type CallbackRegistration, type MessageTarget, type TransferableValue } from './types';
+import { type Transformer } from './transformer';
 /** Unique identifier for tracking RPC calls */
 export type CallId = `c:${string}`;
 /** Unique identifier for callback functions */
@@ -19,6 +20,32 @@ export interface EndpointOptions {
     onError?: (error: Error) => void;
     /** Callback invoked when the remote endpoint is released */
     onRelease?: () => void;
+    /**
+     * Codecs for non-cloneable values. Checked in order; first match wins.
+     * The scanning depth into plain objects is controlled by `transformDepth`.
+     *
+     * @example
+     * ```typescript
+     * import { responseTransformer } from '@xentobias/worker-rpc/transformers';
+     *
+     * const endpoint = createEndpoint(worker, {
+     *   transformers: [responseTransformer],
+     * });
+     * ```
+     */
+    transformers?: Transformer[];
+    /**
+     * How many levels deep to scan plain-object properties for transformer-
+     * matched values.
+     *
+     * - `1` (default) — only first-level properties are scanned (backward-compatible).
+     * - `2` — scans two levels deep (e.g. `{ a: { req: new Request(...) } }`).
+     * - `Infinity` — recurse without limit.
+     *
+     * The top-level value itself is always checked regardless of this setting.
+     * Function extraction in return values is unaffected and remains first-level only.
+     */
+    transformDepth?: number;
 }
 /** Configuration for exposing an API */
 export interface ExposeOptions {
@@ -41,10 +68,6 @@ export interface ShutdownResult {
  * RPC Endpoint - handles bidirectional communication with a worker
  */
 export declare class Endpoint {
-    /**
-     * Generate a random ID string for use as a default endpoint ID.
-     * @returns A random 6-character alphanumeric string
-     */
     private static generateRandomId;
     /**
      * Extract the endpoint ID from a call ID.
@@ -63,7 +86,9 @@ export declare class Endpoint {
      */
     static extractEndpointId(callId: CallId): string;
     protected target: MessageTarget;
-    protected options: Required<EndpointOptions>;
+    protected options: Required<Omit<EndpointOptions, 'transformers'>> & {
+        transformers: Transformer[];
+    };
     private exposedApi;
     private exposeOptions;
     /** Unique identifier for this endpoint */
@@ -87,136 +112,77 @@ export declare class Endpoint {
     /** Release handlers from returned objects with [CALLBACK_RELEASE] */
     protected releaseHandlers: Set<() => void>;
     constructor(target: MessageTarget, options?: EndpointOptions);
-    /**
-     * Generate a unique call ID for this endpoint
-     */
     protected generateCallId(): CallId;
-    /**
-     * Generate a unique callback ID for this endpoint
-     */
     protected generateCallbackId(): CallbackId;
-    /**
-     * Attach the message listener to the target
-     */
     private attachListener;
-    /**
-     * Detach the message listener from the target
-     */
     private detachListener;
-    /**
-     * Handle target close/error events (worker death or port disconnection).
-     * This triggers the same cleanup as receiving an EndpointRelease message,
-     * but is invoked by transport-level events when the remote side dies
-     * without sending a proper release message.
-     */
+    /** Handles worker death / port close — rejects pending calls and cleans up without sending messages. */
     private handleTargetClose;
-    /**
-     * Log a debug message
-     */
     protected debug(...args: unknown[]): void;
-    /**
-     * Expose an API object for remote invocation
-     */
     expose(api: object, options?: ExposeOptions): void;
-    /**
-     * Handle incoming messages
-     */
     private handleMessage;
-    /**
-     * Handle a method call request
-     */
     private handleCall;
-    /**
-     * Resolve a method from the exposed API by path
-     */
     private resolveMethod;
-    /**
-     * Handle a successful result
-     */
+    protected resolveResult(value: unknown, callbackMap?: Record<string, CallbackId>): Promise<unknown>;
     protected handleResult(message: ResultMessage): void;
-    /**
-     * Handle an error result
-     */
     protected handleError(message: ErrorMessage): void;
-    /**
-     * Handle a callback invocation
-     */
     private handleCallback;
-    /**
-     * Handle release of callbacks
-     */
     private handleCallbackRelease;
-    /**
-     * Handle notification that the remote endpoint has been released
-     */
     private handleEndpointRelease;
-    /**
-     * Register a local callback function
-     */
     protected registerCallback(fn: Function, remaining?: number): CallbackId;
-    /**
-     * Create a proxy function for a remote callback
-     */
     protected createRemoteCallback(callbackId: CallbackId): Function;
+    private invokeCallback;
     /**
-     * Invoke a remote callback
+     * Encode a single value through transformers, recursively scanning plain-
+     * object properties up to `depth` levels deep.
+     * This is the symmetric counterpart of `decodeValue`.
+     *
+     * @param value - The value to encode.
+     * @param depth - Remaining levels of plain-object recursion. The top-level
+     *   transformer match is always attempted regardless of this value.
      */
-    private invokeCallback;
+    private encodeValue;
     /**
-     * Process arguments for a call - separates functions into callbacks and collects transferables
+     * Decode a single value through transformers, recursively scanning plain-
+     * object properties up to `depth` levels deep.
+     * This is the symmetric counterpart of `encodeValue`.
+     *
+     * @param value - The value to decode.
+     * @param depth - Remaining levels of plain-object recursion. Encoded
+     *   envelopes are always decoded regardless of this value.
      */
-    protected processArgs(args: unknown[]): {
+    private decodeValue;
+    /** Extracts functions and MessagePorts from args. Used as the no-transformer fast path. */
+    protected processArgsSync(args: unknown[]): {
         rawArgs: unknown[];
         callbackMap: Record<number, CallbackId>;
         transferables: TransferableValue[];
     };
+    /** Like `processArgsSync`, but also encodes values through transformers. */
+    protected processArgs(args: unknown[]): Promise<{
+        rawArgs: unknown[];
+        callbackMap: Record<number, CallbackId>;
+        transferables: TransferableValue[];
+    }>;
     /**
-     * Process a return value - extracts functions from first-level object properties.
-     * For performance, only scans the first level of plain objects.
+     * Extracts first-level functions into the callback map and encodes
+     * non-cloneable values through transformers.
      */
-    protected processResult(value: unknown): {
+    protected processResult(value: unknown): Promise<{
         rawValue: unknown;
         callbackMap: Record<string, CallbackId>;
-    };
-    /**
-     * Reconstruct a result value by merging data with callback proxies.
-     */
-    protected reconstructResult(value: unknown, callbackMap: Record<string, CallbackId>): unknown;
-    /**
-     * Build a call message
-     */
+        transferables: TransferableValue[];
+    }>;
+    protected reconstructResult(value: unknown, callbackMap: Record<string, CallbackId>): Promise<unknown>;
     protected buildCallMessage(id: CallId, path: MethodPath, rawArgs: unknown[], callbackMap: Record<number, CallbackId>): CallMessage;
     /**
      * Call a remote method
      */
     call(path: MethodPath, args: unknown[]): Promise<unknown>;
-    /**
-     * Send a message to the target
-     */
     protected send(message: RpcMessage, transferables?: TransferableValue[]): void;
-    /**
-     * Get the number of pending calls
-     */
     getPendingCallCount(): number;
-    /**
-     * Check if there are any pending calls
-     */
     hasPendingCalls(): boolean;
-    /**
-     * Gracefully shut down the endpoint, waiting for pending calls to complete
-     *
-     * @param options - Shutdown options
-     * @returns Promise that resolves with the shutdown result
-     *
-     * @example
-     * ```typescript
-     * // Wait up to 5 seconds for pending calls to complete
-     * const result = await endpoint.shutdown({ timeout: 5000 });
-     * if (result.timedOut) {
-     *   console.log(`${result.terminatedCalls} calls were forcefully terminated`);
-     * }
-     * ```
-     */
+    /** Waits for pending calls to finish, then releases. Resolves with `{ timeout: true }` if they don't finish in time. */
     shutdown(options?: ShutdownOptions): Promise<ShutdownResult>;
     /**
      * Release this endpoint and clean up resources
@@ -227,20 +193,8 @@ export declare class Endpoint {
     release(options?: {
         silent?: boolean;
     }): void;
-    /**
-     * Get the underlying message target
-     */
     getTarget(): MessageTarget;
 }
-/**
- * Check if a value is a function
- */
 export declare function isFunction(value: unknown): value is Function;
-/**
- * Check if a value is a MessagePort
- */
 export declare function isMessagePort(value: unknown): value is MessagePort;
-/**
- * Create an endpoint for a worker or message port
- */
 export declare function createEndpoint(target: MessageTarget, options?: EndpointOptions): Endpoint;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from "./error";
 export * from "./endpoint";
 export * from "./proxy";
 export * from "./broadcast";
+export * from "./transformer";
 /**
  * Expose an API object for remote invocation
  * Call this in the worker to expose methods to the parent

package/dist/index.js

@@ -1,2 +1,2 @@
 // @bun
-var B;(($)=>{$[$.Call=0]="Call";$[$.Result=1]="Result";$[$.Error=2]="Error";$[$.Callback=3]="Callback";$[$.CallbackRelease=4]="CallbackRelease";$[$.EndpointRelease=5]="EndpointRelease"})(B||={});var E=new Set(["message","name","stack","cause"]);function Y(q){let G={e:q.message,n:q.name,s:q.stack},Q={};for(let Z of Object.keys(q))if(!E.has(Z))Q[Z]=q[Z];if(Object.keys(Q).length>0)G.d=Q;if(q.cause instanceof Error)G.c=Y(q.cause);else if(q.cause!==void 0)G.c={e:String(q.cause),d:{cause:q.cause}};return G}function z(q){let G=q.c?{cause:z(q.c)}:void 0,Q=Error(q.e,G);if(q.n)Q.name=q.n;if(q.s)Q.stack=q.s;if(q.d)Object.assign(Q,q.d);return Q}var H=Symbol("rpc:path"),F=Symbol("rpc:proxy-endpoint"),_=Symbol.for("rpc:remote-proxy"),C=Symbol.for("rpc:endpoint"),N=Symbol.for("rpc:release"),x=Symbol.for("rpc:callback-release"),T={get(q,G){if(G===_)return!0;if(G===C)return q[F];if(G===N)return()=>{q[F].release()};if(G==="then"){if(q[H].length===0)return;let Q=q[F],Z=q[H],J=Q.call(Z,[]);return J.then.bind(J)}if(G==="toJSON")return;if(G===Symbol.toStringTag||G===Symbol.iterator||G===Symbol.asyncIterator||G==="constructor"||G==="prototype")return;if(typeof G==="string"){let Q=q[F],J=[...q[H],G];return P(Q,J)}},apply(q,G,Q){let Z=q[F],J=q[H];return Z.call(J,Q)},set(){throw Error("Cannot set properties on a remote proxy")},deleteProperty(){throw Error("Cannot delete properties on a remote proxy")},getPrototypeOf(){return Function.prototype},has(q,G){return G===_||G===C||G===N}};function P(q,G){let Q=function(){};return Q[F]=q,Q[H]=G,new Proxy(Q,T)}function w(q){return P(q,[])}function A(q){if(q===null||q===void 0)return!1;try{return q[_]===!0}catch{return!1}}function M(q){if(A(q))return q[C]}function b(q){if(A(q))q[N]()}var I=30000;class S{static generateRandomId(){return Math.random().toString(36).slice(2,8)}static extractEndpointId(q){return q.split(":")[1]??""}target;options;exposedApi=null;exposeOptions={};id;callCounter=0;callbackCounter=0;pendingCalls=new Map;callbacks=new Map;remoteCallbacks=new Map;boundMessageHandler;boundCloseHandler;released=!1;releaseHandlers=new Set;constructor(q,G={}){this.target=q,this.id=G.id??S.generateRandomId(),this.options={id:this.id,timeout:G.timeout??I,onError:G.onError??console.error,debug:G.debug??!1,onRelease:G.onRelease??(()=>{})},this.boundMessageHandler=this.handleMessage.bind(this),this.boundCloseHandler=this.handleTargetClose.bind(this),this.attachListener()}generateCallId(){return`c:${this.id}:${++this.callCounter}`}generateCallbackId(){return`cb:${this.id}:${++this.callbackCounter}`}attachListener(){if(this.target.addEventListener)this.target.addEventListener("message",this.boundMessageHandler),this.target.addEventListener("close",this.boundCloseHandler),this.target.addEventListener("error",this.boundCloseHandler);else if(this.target.onmessage!==void 0)this.target.onmessage=this.boundMessageHandler}detachListener(){if(this.target.removeEventListener)this.target.removeEventListener("message",this.boundMessageHandler),this.target.removeEventListener("close",this.boundCloseHandler),this.target.removeEventListener("error",this.boundCloseHandler);else if(this.target.onmessage!==void 0)this.target.onmessage=null}handleTargetClose(){if(this.released)return;this.debug("Target closed or errored (remote endpoint likely died)");for(let[q,G]of this.pendingCalls){if(G.timer)clearTimeout(G.timer);G.reject(Error("Remote endpoint disconnected"))}this.pendingCalls.clear();for(let q of this.releaseHandlers)try{q()}catch{}this.releaseHandlers.clear(),this.options.onRelease(),this.released=!0,this.remoteCallbacks.clear(),this.callbacks.clear(),this.detachListener()}debug(...q){if(this.options.debug)console.log("[worker-rpc]",...q)}expose(q,G={}){this.exposedApi=q,this.exposeOptions={maxDepth:G.maxDepth??10}}handleMessage(q){let G=q.data;if(typeof G!=="object"||G===null||!("t"in G))return;switch(this.debug("received",B[G.t],G),G.t){case 0:this.handleCall(G);break;case 1:this.handleResult(G);break;case 2:this.handleError(G);break;case 3:this.handleCallback(G);break;case 4:this.handleCallbackRelease(G);break;case 5:this.handleEndpointRelease();break}}async handleCall(q){let{id:G,p:Q,a:Z,c:J}=q;try{let{method:K,thisArg:$}=this.resolveMethod(Q);if(typeof K!=="function")throw Error(`Method not found: ${Q.join(".")}`);let W=Z.map((D,X)=>{let O=J?.[X];if(O)return this.createRemoteCallback(O);return D}),V=await K.apply($,W),{rawValue:U,callbackMap:L}=this.processResult(V);this.send({t:1,id:G,v:U,...Object.keys(L).length>0&&{cm:L}})}catch(K){let $=K instanceof Error?K:Error(String(K));this.send({t:2,id:G,...Y($)})}}resolveMethod(q){if(!this.exposedApi)throw Error("No API exposed");let G=this.exposedApi,Q=null;for(let Z=0;Z<q.length;Z++){let J=q[Z];if(G===null||G===void 0)throw Error(`Cannot access property '${J}' of ${G}`);if(J===void 0)throw Error(`Invalid path at index ${Z}`);if(Q=G,G=G[J],Z>=(this.exposeOptions.maxDepth??10))throw Error("Maximum nesting depth exceeded")}return{target:this.exposedApi,method:G,thisArg:Q}}handleResult(q){let G=this.pendingCalls.get(q.id);if(!G){this.debug("Received result for unknown call:",q.id);return}if(this.pendingCalls.delete(q.id),G.timer)clearTimeout(G.timer);if(q.cm&&Object.keys(q.cm).length>0)G.resolve(this.reconstructResult(q.v,q.cm));else G.resolve(q.v)}handleError(q){let G=this.pendingCalls.get(q.id);if(!G){this.debug("Received error for unknown call:",q.id);return}if(this.pendingCalls.delete(q.id),G.timer)clearTimeout(G.timer);G.reject(z(q))}async handleCallback(q){let{id:G,c:Q,a:Z,cb:J}=q,K=this.callbacks.get(Q);if(!K){this.send({t:2,id:G,e:`Callback not found: ${Q}`});return}try{let $=Z.map((L,D)=>{let X=J?.[D];if(X)return this.createRemoteCallback(X);return L}),W=await K.fn(...$);if(K.remaining>0){if(K.remaining--,K.remaining===0)this.callbacks.delete(Q)}let{rawValue:V,callbackMap:U}=this.processResult(W);this.send({t:1,id:G,v:V,...Object.keys(U).length>0&&{cm:U}})}catch($){let W=$ instanceof Error?$:Error(String($));this.send({t:2,id:G,...Y(W)})}}handleCallbackRelease(q){for(let G of q.c)this.callbacks.delete(G)}handleEndpointRelease(){this.debug("Remote endpoint released");for(let q of this.releaseHandlers)try{q()}catch{}this.releaseHandlers.clear(),this.options.onRelease(),this.release({silent:!0})}registerCallback(q,G=-1){let Q=this.generateCallbackId();return this.callbacks.set(Q,{fn:q,remaining:G}),Q}createRemoteCallback(q){let G=this.remoteCallbacks.get(q);if(G)return G;return G=async(...Q)=>{return this.invokeCallback(q,Q)},this.remoteCallbacks.set(q,G),G}async invokeCallback(q,G){let Q=this.generateCallId(),Z=[],J={},K=[];for(let $=0;$<G.length;$++){let W=G[$];if(j(W))J[$]=this.registerCallback(W),Z.push(null);else if(R(W))K.push(W),Z.push(W);else Z.push(W)}return new Promise(($,W)=>{let V=setTimeout(()=>{this.pendingCalls.delete(Q),W(Error(`Callback invocation timed out: ${q}`))},this.options.timeout);this.pendingCalls.set(Q,{resolve:$,reject:W,timer:V});let U={t:3,id:Q,c:q,a:Z,...Object.keys(J).length>0&&{cb:J}};this.send(U,K)})}processArgs(q){let G=[],Q={},Z=[];for(let J=0;J<q.length;J++){let K=q[J];if(j(K))Q[J]=this.registerCallback(K),G.push(null);else if(R(K))Z.push(K),G.push(K);else G.push(K)}return{rawArgs:G,callbackMap:Q,transferables:Z}}processResult(q){if(j(q))return{rawValue:null,callbackMap:{"":this.registerCallback(q)}};if(q!==null&&typeof q==="object"&&!Array.isArray(q)&&!R(q)&&!(q instanceof ArrayBuffer)){let G={},Q={};for(let J in q){let K=q[J];if(j(K))G[J]=this.registerCallback(K);else Q[J]=K}let Z=q[x];if(typeof Z==="function")this.releaseHandlers.add(Z);if(Object.keys(G).length>0)return{rawValue:Q,callbackMap:G}}return{rawValue:q,callbackMap:{}}}reconstructResult(q,G){if(""in G)return this.createRemoteCallback(G[""]);let Q=q&&typeof q==="object"?{...q}:{};for(let Z in G){let J=G[Z];if(J)Q[Z]=this.createRemoteCallback(J)}return Q}buildCallMessage(q,G,Q,Z){return{t:0,id:q,p:G,a:Q,...Object.keys(Z).length>0&&{c:Z}}}call(q,G){if(this.released)return Promise.reject(Error("Endpoint has been released"));let{rawArgs:Q,callbackMap:Z,transferables:J}=this.processArgs(G),K=this.generateCallId(),$=this.buildCallMessage(K,q,Q,Z);return new Promise((W,V)=>{let U=setTimeout(()=>{this.pendingCalls.delete(K),V(Error(`Call timed out: ${q.join(".")}`))},this.options.timeout);this.pendingCalls.set(K,{resolve:W,reject:V,timer:U}),this.send($,J)})}send(q,G=[]){this.debug("sending",B[q.t],q),this.target.postMessage(q,G)}getPendingCallCount(){return this.pendingCalls.size}hasPendingCalls(){return this.pendingCalls.size>0}async shutdown(q={}){let{timeout:G=I}=q;if(this.released)return{success:!0,timeout:!1};if(!this.hasPendingCalls())return this.release(),{success:!0,timeout:!1};return new Promise((Q)=>{let Z=!1,J=($)=>{if(Z)return;if(Z=!0,clearTimeout(K),!this.released)this.release();Q($)},K=setTimeout(()=>{J({success:!1,timeout:!0})},G);for(let[,$]of this.pendingCalls){let{resolve:W,reject:V}=$;$.resolve=(U)=>{if(W(U),!this.hasPendingCalls())J({success:!0,timeout:!1})},$.reject=(U)=>{if(V(U),!this.hasPendingCalls())J({success:!0,timeout:!1})}}})}release(q={}){if(this.released)return;this.released=!0;for(let[,Q]of this.pendingCalls){if(Q.timer)clearTimeout(Q.timer);Q.reject(Error("Endpoint released"))}this.pendingCalls.clear();let{silent:G=!1}=q;if(!G){if(this.remoteCallbacks.size>0){let Q=[...this.remoteCallbacks.keys()];this.send({t:4,id:this.generateCallId(),c:Q})}this.send({t:5,id:this.generateCallId()})}this.remoteCallbacks.clear(),this.callbacks.clear(),this.releaseHandlers.clear(),this.detachListener()}getTarget(){return this.target}}function j(q){return typeof q==="function"}function R(q){return typeof MessagePort<"u"&&q instanceof MessagePort}function f(q,G){return new S(q,G)}class h extends S{pendingBroadcastCalls=new Map;get broadcastTarget(){return this.target}call(q,G){if(this.released)return Promise.reject(Error("Endpoint has been released"));let{rawArgs:Q,callbackMap:Z,transferables:J}=this.processArgs(G),K=this.generateCallId(),$=this.buildCallMessage(K,q,Q,Z);return this.sendBroadcast(K,$,J,q)}sendBroadcast(q,G,Q,Z){return this.debug("sending broadcast",B[G.t],G),new Promise((J,K)=>{let $={resolve:J,reject:K,timer:setTimeout(()=>this.handleTimeout(q,Z),this.options.timeout),expectedCount:1/0,results:[],errors:[]};this.pendingBroadcastCalls.set(q,$),Promise.resolve(this.broadcastTarget.postMessage(G,Q)).then((W)=>this.handleSubscriberCount(q,W))})}handleTimeout(q,G){let Q=this.pendingBroadcastCalls.get(q);if(!Q)return;this.pendingBroadcastCalls.delete(q);let Z=Q.results.length+Q.errors.length,J=Q.expectedCount===1/0?0:Q.expectedCount-Z;if(J>0){let K=Error(`Broadcast timed out: ${G.join(".")}`);K.name="TimeoutError";for(let $=0;$<J;$++)Q.errors.push(K)}if(this.debug(`Broadcast timed out with ${Q.results.length} results, ${Q.errors.length} errors (${J} timed out)`),Q.results.length>0||Q.errors.length>0)Q.resolve({results:Q.results,errors:Q.errors});else Q.reject(Error(`Broadcast timed out: ${G.join(".")}`))}handleSubscriberCount(q,G){let Q=this.pendingBroadcastCalls.get(q);if(!Q)return;if(G===0){this.completeBroadcast(q,Q);return}Q.expectedCount=G,this.checkCompletion(q,Q)}checkCompletion(q,G){if(G.results.length+G.errors.length>=G.expectedCount)this.completeBroadcast(q,G)}completeBroadcast(q,G){this.pendingBroadcastCalls.delete(q),clearTimeout(G.timer),G.resolve({results:G.results,errors:G.errors})}handleResult(q){let G=this.pendingBroadcastCalls.get(q.id);if(!G){super.handleResult(q);return}if(q.cm&&Object.keys(q.cm).length>0)G.results.push(this.reconstructResult(q.v,q.cm));else G.results.push(q.v);this.debug(`Broadcast received ${G.results.length}/${G.expectedCount} responses`),this.checkCompletion(q.id,G)}handleError(q){let G=this.pendingBroadcastCalls.get(q.id);if(!G){super.handleError(q);return}G.errors.push(z(q)),this.debug(`Broadcast received error (${G.results.length} results, ${G.errors.length} errors / ${G.expectedCount} expected)`),this.checkCompletion(q.id,G)}getPendingCallCount(){return super.getPendingCallCount()+this.pendingBroadcastCalls.size}hasPendingCalls(){return super.hasPendingCalls()||this.pendingBroadcastCalls.size>0}release(q={}){for(let[,G]of this.pendingBroadcastCalls)clearTimeout(G.timer),G.reject(Error("Endpoint released"));this.pendingBroadcastCalls.clear(),super.release(q)}}function g(q,G){return new h(q,G)}function r(q,G){let Z=f(globalThis,G);return Z.expose(q),Z}function a(q,G){let Q=f(q,G);return w(Q)}export{w as wrap,Y as serializeError,a as remote,b as releaseProxy,A as isProxy,R as isMessagePort,j as isFunction,M as getEndpoint,r as expose,z as deserializeError,f as createEndpoint,g as createBroadcastEndpoint,_ as REMOTE_PROXY,N as RELEASE,F as PROXY_ENDPOINT,H as PATH,B as MessageType,S as Endpoint,C as ENDPOINT,x as CALLBACK_RELEASE,h as BroadcastEndpoint};
+var z;((J)=>{J[J.Call=0]="Call";J[J.Result=1]="Result";J[J.Error=2]="Error";J[J.Callback=3]="Callback";J[J.CallbackRelease=4]="CallbackRelease";J[J.EndpointRelease=5]="EndpointRelease"})(z||={});var y=new Set(["message","name","stack","cause"]);function D(q){let G={e:q.message,n:q.name,s:q.stack},Q={};for(let Z of Object.keys(q))if(!y.has(Z))Q[Z]=q[Z];if(Object.keys(Q).length>0)G.d=Q;if(q.cause instanceof Error)G.c=D(q.cause);else if(q.cause!==void 0)G.c={e:String(q.cause),d:{cause:q.cause}};return G}function S(q){let G=q.c?{cause:S(q.c)}:void 0,Q=Error(q.e,G);if(q.n)Q.name=q.n;if(q.s)Q.stack=q.s;if(q.d)Object.assign(Q,q.d);return Q}var X=Symbol("rpc:path"),V=Symbol("rpc:proxy-endpoint"),C=Symbol.for("rpc:remote-proxy"),_=Symbol.for("rpc:endpoint"),N=Symbol.for("rpc:release"),A=Symbol.for("rpc:callback-release"),b={get(q,G){if(G===C)return!0;if(G===_)return q[V];if(G===N)return()=>{q[V].release()};if(G==="then"){if(q[X].length===0)return;let Q=q[V],Z=q[X],$=Q.call(Z,[]);return $.then.bind($)}if(G==="toJSON")return;if(G===Symbol.toStringTag||G===Symbol.iterator||G===Symbol.asyncIterator||G==="constructor"||G==="prototype")return;if(typeof G==="string"){let Q=q[V],$=[...q[X],G];return w(Q,$)}},apply(q,G,Q){let Z=q[V],$=q[X];return Z.call($,Q)},set(){throw Error("Cannot set properties on a remote proxy")},deleteProperty(){throw Error("Cannot delete properties on a remote proxy")},getPrototypeOf(){return Function.prototype},has(q,G){return G===C||G===_||G===N}};function w(q,G){let Q=function(){};return Q[V]=q,Q[X]=G,new Proxy(Q,b)}function h(q){return w(q,[])}function T(q){if(q===null||q===void 0)return!1;try{return q[C]===!0}catch{return!1}}function u(q){if(T(q))return q[_]}function c(q){if(T(q))q[N]()}function O(q){return q!==null&&typeof q==="object"&&typeof q.__rpc_type==="string"}async function x(q,G){for(let Q of G)if(Q.canHandle(q)){let{transferables:Z=[],payload:$}=await Q.encode(q);return{transferables:Z,value:{__rpc_type:Q.type,...$}}}return{value:q,transferables:[]}}async function f(q,G){if(!O(q))return q;let{__rpc_type:Q,...Z}=q;for(let $ of G)if($.type===Q)return $.decode(Z);return q}var E=30000;class Y{static generateRandomId(){return Math.random().toString(36).slice(2,8)}static extractEndpointId(q){return q.split(":")[1]??""}target;options;exposedApi=null;exposeOptions={};id;callCounter=0;callbackCounter=0;pendingCalls=new Map;callbacks=new Map;remoteCallbacks=new Map;boundMessageHandler;boundCloseHandler;released=!1;releaseHandlers=new Set;constructor(q,G={}){this.target=q,this.id=G.id??Y.generateRandomId(),this.options={id:this.id,timeout:G.timeout??E,onError:G.onError??console.error,debug:G.debug??!1,onRelease:G.onRelease??(()=>{}),transformers:G.transformers??[],transformDepth:G.transformDepth??1},this.boundMessageHandler=this.handleMessage.bind(this),this.boundCloseHandler=this.handleTargetClose.bind(this),this.attachListener()}generateCallId(){return`c:${this.id}:${++this.callCounter}`}generateCallbackId(){return`cb:${this.id}:${++this.callbackCounter}`}attachListener(){if(this.target.addEventListener)this.target.addEventListener("message",this.boundMessageHandler),this.target.addEventListener("close",this.boundCloseHandler),this.target.addEventListener("error",this.boundCloseHandler);else if(this.target.onmessage!==void 0)this.target.onmessage=this.boundMessageHandler}detachListener(){if(this.target.removeEventListener)this.target.removeEventListener("message",this.boundMessageHandler),this.target.removeEventListener("close",this.boundCloseHandler),this.target.removeEventListener("error",this.boundCloseHandler);else if(this.target.onmessage!==void 0)this.target.onmessage=null}handleTargetClose(){if(this.released)return;this.debug("Target closed or errored (remote endpoint likely died)");for(let[q,G]of this.pendingCalls){if(G.timer)clearTimeout(G.timer);G.reject(Error("Remote endpoint disconnected"))}this.pendingCalls.clear();for(let q of this.releaseHandlers)try{q()}catch{}this.releaseHandlers.clear(),this.options.onRelease(),this.released=!0,this.remoteCallbacks.clear(),this.callbacks.clear(),this.detachListener()}debug(...q){if(this.options.debug)console.log("[worker-rpc]",...q)}expose(q,G={}){this.exposedApi=q,this.exposeOptions={maxDepth:G.maxDepth??10}}handleMessage(q){let G=q.data;if(typeof G!=="object"||G===null||!("t"in G))return;switch(this.debug("received",z[G.t],G),G.t){case 0:this.handleCall(G);break;case 1:this.handleResult(G);break;case 2:this.handleError(G);break;case 3:this.handleCallback(G);break;case 4:this.handleCallbackRelease(G);break;case 5:this.handleEndpointRelease();break}}async handleCall(q){let{id:G,p:Q,a:Z,c:$}=q;try{let{method:K,thisArg:J}=this.resolveMethod(Q);if(typeof K!=="function")throw Error(`Method not found: ${Q.join(".")}`);let F=await Promise.all(Z.map(async(L,j)=>{let I=$?.[j];if(I)return this.createRemoteCallback(I);return this.decodeValue(L)})),U=await K.apply(J,F),{rawValue:W,callbackMap:B,transferables:H}=await this.processResult(U);this.send({t:1,id:G,v:W,...Object.keys(B).length>0&&{cm:B}},H)}catch(K){let J=K instanceof Error?K:Error(String(K));this.send({t:2,id:G,...D(J)})}}resolveMethod(q){if(!this.exposedApi)throw Error("No API exposed");let G=this.exposedApi,Q=null;for(let Z=0;Z<q.length;Z++){let $=q[Z];if(G===null||G===void 0)throw Error(`Cannot access property '${$}' of ${G}`);if($===void 0)throw Error(`Invalid path at index ${Z}`);if(Q=G,G=G[$],Z>=(this.exposeOptions.maxDepth??10))throw Error("Maximum nesting depth exceeded")}return{target:this.exposedApi,method:G,thisArg:Q}}resolveResult(q,G){return G&&Object.keys(G).length>0?this.reconstructResult(q,G):this.decodeValue(q)}handleResult(q){let G=this.pendingCalls.get(q.id);if(!G){this.debug("Received result for unknown call:",q.id);return}if(this.pendingCalls.delete(q.id),G.timer)clearTimeout(G.timer);this.resolveResult(q.v,q.cm).then(G.resolve,G.reject)}handleError(q){let G=this.pendingCalls.get(q.id);if(!G){this.debug("Received error for unknown call:",q.id);return}if(this.pendingCalls.delete(q.id),G.timer)clearTimeout(G.timer);G.reject(S(q))}async handleCallback(q){let{id:G,c:Q,a:Z,cb:$}=q,K=this.callbacks.get(Q);if(!K){this.send({t:2,id:G,e:`Callback not found: ${Q}`});return}try{let J=await Promise.all(Z.map(async(H,L)=>{let j=$?.[L];if(j)return this.createRemoteCallback(j);return this.decodeValue(H)})),F=await K.fn(...J);if(K.remaining>0){if(K.remaining--,K.remaining===0)this.callbacks.delete(Q)}let{rawValue:U,callbackMap:W,transferables:B}=await this.processResult(F);this.send({t:1,id:G,v:U,...Object.keys(W).length>0&&{cm:W}},B)}catch(J){let F=J instanceof Error?J:Error(String(J));this.send({t:2,id:G,...D(F)})}}handleCallbackRelease(q){for(let G of q.c)this.callbacks.delete(G)}handleEndpointRelease(){this.debug("Remote endpoint released");for(let q of this.releaseHandlers)try{q()}catch{}this.releaseHandlers.clear(),this.options.onRelease(),this.release({silent:!0})}registerCallback(q,G=-1){let Q=this.generateCallbackId();return this.callbacks.set(Q,{fn:q,remaining:G}),Q}createRemoteCallback(q){let G=this.remoteCallbacks.get(q);if(G)return G;return G=async(...Q)=>this.invokeCallback(q,Q),this.remoteCallbacks.set(q,G),G}invokeCallback(q,G){let Q=this.generateCallId();return new Promise((Z,$)=>{let K=setTimeout(()=>{this.pendingCalls.delete(Q),$(Error(`Callback invocation timed out: ${q}`))},this.options.timeout);this.pendingCalls.set(Q,{resolve:Z,reject:$,timer:K});let J=({rawArgs:U,callbackMap:W,transferables:B})=>{if(!this.released)this.send({t:3,id:Q,c:q,a:U,...Object.keys(W).length>0&&{cb:W}},B)},F=(U)=>{let W=this.pendingCalls.get(Q);if(W)this.pendingCalls.delete(Q),clearTimeout(W.timer),W.reject(U instanceof Error?U:Error(String(U)))};if(this.options.transformers.length===0)J(this.processArgsSync(G));else this.processArgs(G).then(J,F)})}async encodeValue(q,G=this.options.transformDepth){let{value:Q,transferables:Z}=await x(q,this.options.transformers);if(Q!==q)return{encoded:Q,transferables:Z};if(G>0&&q!==null&&typeof q==="object"&&Object.getPrototypeOf(q)===Object.prototype){let $={},K=[];for(let J in q){let F=q[J],{encoded:U,transferables:W}=await this.encodeValue(F,G-1);$[J]=U,K.push(...W)}return{encoded:$,transferables:K}}return{encoded:q,transferables:[]}}async decodeValue(q,G=this.options.transformDepth){if(O(q))return f(q,this.options.transformers);if(G>0&&q!==null&&typeof q==="object"&&Object.getPrototypeOf(q)===Object.prototype){let Q={...q};for(let Z of Object.keys(Q))Q[Z]=await this.decodeValue(Q[Z],G-1);return Q}return q}processArgsSync(q){let G=[],Q={},Z=[];for(let $=0;$<q.length;$++){let K=q[$];if(R(K))Q[$]=this.registerCallback(K),G.push(null);else if(M(K))Z.push(K),G.push(K);else G.push(K)}return{rawArgs:G,callbackMap:Q,transferables:Z}}async processArgs(q){let{rawArgs:G,callbackMap:Q,transferables:Z}=this.processArgsSync(q);for(let $=0;$<G.length;$++){if(G[$]===null&&Q[$]!==void 0)continue;let{encoded:K,transferables:J}=await this.encodeValue(G[$]);G[$]=K,Z.push(...J)}return{rawArgs:G,callbackMap:Q,transferables:Z}}async processResult(q){let G=[];if(R(q))return{rawValue:null,callbackMap:{"":this.registerCallback(q)},transferables:G};if(q!==null&&typeof q==="object"&&!Array.isArray(q)&&!M(q)&&!(q instanceof ArrayBuffer)){let{value:$,transferables:K}=await x(q,this.options.transformers);if($!==q)return G.push(...K),{rawValue:$,callbackMap:{},transferables:G};let J={},F={};for(let W in q){let B=q[W];if(R(B))J[W]=this.registerCallback(B);else{let{encoded:H,transferables:L}=await this.encodeValue(B);F[W]=H,G.push(...L)}}let U=q[A];if(typeof U==="function")this.releaseHandlers.add(U);if(Object.keys(J).length>0)return{rawValue:F,callbackMap:J,transferables:G};return{rawValue:F,callbackMap:{},transferables:G}}let{encoded:Q,transferables:Z}=await this.encodeValue(q);return G.push(...Z),{rawValue:Q,callbackMap:{},transferables:G}}async reconstructResult(q,G){if(""in G)return this.createRemoteCallback(G[""]);let Q=q&&typeof q==="object"?{...q}:{};for(let Z of Object.keys(Q))Q[Z]=await this.decodeValue(Q[Z]);for(let Z in G){let $=G[Z];if($)Q[Z]=this.createRemoteCallback($)}return Q}buildCallMessage(q,G,Q,Z){return{t:0,id:q,p:G,a:Q,...Object.keys(Z).length>0&&{c:Z}}}call(q,G){if(this.released)return Promise.reject(Error("Endpoint has been released"));let Q=this.generateCallId();return new Promise((Z,$)=>{let K=setTimeout(()=>{this.pendingCalls.delete(Q),$(Error(`Call timed out: ${q.join(".")}`))},this.options.timeout);this.pendingCalls.set(Q,{resolve:Z,reject:$,timer:K});let J=({rawArgs:U,callbackMap:W,transferables:B})=>{if(!this.released)this.send(this.buildCallMessage(Q,q,U,W),B)},F=(U)=>{let W=this.pendingCalls.get(Q);if(W)this.pendingCalls.delete(Q),clearTimeout(W.timer),W.reject(U instanceof Error?U:Error(String(U)))};if(this.options.transformers.length===0)J(this.processArgsSync(G));else this.processArgs(G).then(J,F)})}send(q,G=[]){this.debug("sending",z[q.t],q),this.target.postMessage(q,G)}getPendingCallCount(){return this.pendingCalls.size}hasPendingCalls(){return this.pendingCalls.size>0}async shutdown(q={}){let{timeout:G=E}=q;if(this.released)return{success:!0,timeout:!1};if(!this.hasPendingCalls())return this.release(),{success:!0,timeout:!1};return new Promise((Q)=>{let Z=!1,$=(J)=>{if(Z)return;if(Z=!0,clearTimeout(K),!this.released)this.release();Q(J)},K=setTimeout(()=>{$({success:!1,timeout:!0})},G);for(let[,J]of this.pendingCalls){let{resolve:F,reject:U}=J;J.resolve=(W)=>{if(F(W),!this.hasPendingCalls())$({success:!0,timeout:!1})},J.reject=(W)=>{if(U(W),!this.hasPendingCalls())$({success:!0,timeout:!1})}}})}release(q={}){if(this.released)return;this.released=!0;for(let[,Q]of this.pendingCalls){if(Q.timer)clearTimeout(Q.timer);Q.reject(Error("Endpoint released"))}this.pendingCalls.clear();let{silent:G=!1}=q;if(!G){if(this.remoteCallbacks.size>0){let Q=[...this.remoteCallbacks.keys()];this.send({t:4,id:this.generateCallId(),c:Q})}this.send({t:5,id:this.generateCallId()})}this.remoteCallbacks.clear(),this.callbacks.clear(),this.releaseHandlers.clear(),this.detachListener()}getTarget(){return this.target}}function R(q){return typeof q==="function"}function M(q){return typeof MessagePort<"u"&&q instanceof MessagePort}function P(q,G){return new Y(q,G)}class k extends Y{pendingBroadcastCalls=new Map;get broadcastTarget(){return this.target}call(q,G){if(this.released)return Promise.reject(Error("Endpoint has been released"));let Q=this.generateCallId(),Z=($,K,J)=>{let F=this.buildCallMessage(Q,q,$,K);this.debug("sending broadcast",z[F.t],F),Promise.resolve(this.broadcastTarget.postMessage(F,J)).then((U)=>this.handleSubscriberCount(Q,U))};return new Promise(($,K)=>{let J={resolve:$,reject:K,timer:setTimeout(()=>this.handleTimeout(Q,q),this.options.timeout),expectedCount:1/0,results:[],errors:[]};if(this.pendingBroadcastCalls.set(Q,J),this.options.transformers.length===0){let{rawArgs:F,callbackMap:U,transferables:W}=this.processArgsSync(G);Z(F,U,W)}else this.processArgs(G).then(({rawArgs:F,callbackMap:U,transferables:W})=>{if(this.released)return;Z(F,U,W)},(F)=>{let U=this.pendingBroadcastCalls.get(Q);if(U)this.pendingBroadcastCalls.delete(Q),clearTimeout(U.timer),U.reject(F instanceof Error?F:Error(String(F)))})})}handleTimeout(q,G){let Q=this.pendingBroadcastCalls.get(q);if(!Q)return;this.pendingBroadcastCalls.delete(q);let Z=Q.results.length+Q.errors.length,$=Q.expectedCount===1/0?0:Q.expectedCount-Z;if($>0){let K=Error(`Broadcast timed out: ${G.join(".")}`);K.name="TimeoutError";for(let J=0;J<$;J++)Q.errors.push(K)}if(this.debug(`Broadcast timed out with ${Q.results.length} results, ${Q.errors.length} errors (${$} timed out)`),Q.results.length>0||Q.errors.length>0)Q.resolve({results:Q.results,errors:Q.errors});else Q.reject(Error(`Broadcast timed out: ${G.join(".")}`))}handleSubscriberCount(q,G){let Q=this.pendingBroadcastCalls.get(q);if(!Q)return;if(G===0){this.completeBroadcast(q,Q);return}Q.expectedCount=G,this.checkCompletion(q,Q)}checkCompletion(q,G){if(G.results.length+G.errors.length>=G.expectedCount)this.completeBroadcast(q,G)}completeBroadcast(q,G){this.pendingBroadcastCalls.delete(q),clearTimeout(G.timer),G.resolve({results:G.results,errors:G.errors})}handleResult(q){let G=this.pendingBroadcastCalls.get(q.id);if(!G){super.handleResult(q);return}this.resolveResult(q.v,q.cm).then((Q)=>{G.results.push(Q),this.debug(`Broadcast received ${G.results.length}/${G.expectedCount} responses`),this.checkCompletion(q.id,G)},(Q)=>{G.errors.push(Q instanceof Error?Q:Error(String(Q))),this.checkCompletion(q.id,G)})}handleError(q){let G=this.pendingBroadcastCalls.get(q.id);if(!G){super.handleError(q);return}G.errors.push(S(q)),this.debug(`Broadcast received error (${G.results.length} results, ${G.errors.length} errors / ${G.expectedCount} expected)`),this.checkCompletion(q.id,G)}getPendingCallCount(){return super.getPendingCallCount()+this.pendingBroadcastCalls.size}hasPendingCalls(){return super.hasPendingCalls()||this.pendingBroadcastCalls.size>0}release(q={}){for(let[,G]of this.pendingBroadcastCalls)clearTimeout(G.timer),G.reject(Error("Endpoint released"));this.pendingBroadcastCalls.clear(),super.release(q)}}function a(q,G){return new k(q,G)}function Zq(q,G){let Z=P(globalThis,G);return Z.expose(q),Z}function $q(q,G){let Q=P(q,G);return h(Q)}export{h as wrap,D as serializeError,$q as remote,c as releaseProxy,T as isProxy,M as isMessagePort,R as isFunction,O as isEncodedValue,u as getEndpoint,Zq as expose,S as deserializeError,P as createEndpoint,a as createBroadcastEndpoint,x as applyEncoders,f as applyDecoders,C as REMOTE_PROXY,N as RELEASE,V as PROXY_ENDPOINT,X as PATH,z as MessageType,Y as Endpoint,_ as ENDPOINT,A as CALLBACK_RELEASE,k as BroadcastEndpoint};

package/dist/transformer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Marker interface for types that cross the worker boundary via a transformer.
+ * A return type that extends (or intersects) `Transferred` is passed through
+ * `RemoteReturnValue` unchanged — the transformer handles encoding/decoding at
+ * runtime, so the remote type stays identical to the local type.
+ *
+ * The built-in `Response` and `Request` globals extend this automatically.
+ * For custom transformer-managed types, intersect at the return site:
+ *
+ * ```typescript
+ * interface WorkerApi {
+ *   build(): MyClass & Transferred;
+ * }
+ * ```
+ */
+export interface Transferred {
+}
+/**
+ * Wire envelope written by the library before sending and read after receiving.
+ * `__rpc_type` is injected by `applyEncoders` and stripped by `applyDecoders` —
+ * transformer implementations never touch this field.
+ */
+export interface EncodedValue {
+    __rpc_type: string;
+    [key: string]: unknown;
+}
+/**
+ * Return value of `encode`: the plain data payload plus optional transferables.
+ *
+ * @template P - Shape of the payload (default: `Record<string, unknown>`).
+ */
+export interface EncodeResult<P extends Record<string, unknown> = Record<string, unknown>> {
+    /** Structured-clone-safe payload. */
+    payload: P;
+    /** Transferables to zero-copy transfer via postMessage. */
+    transferables?: Transferable[];
+}
+/**
+ * Encodes a non-cloneable value into a structured-clone-safe payload before
+ * sending, and decodes it back on the receiving side.
+ *
+ * The library injects/strips `__rpc_type` automatically, so `encode` returns
+ * plain data and `decode` receives plain data.
+ *
+ * @template T - The type this transformer handles.
+ * @template P - Shape of the encoded payload. Typing this removes casts in `decode`.
+ *
+ * @example
+ * ```typescript
+ * interface MyPayload extends Record<string, unknown> { data: string }
+ *
+ * const myTransformer: Transformer<MyClass, MyPayload> = {
+ *   type: 'MyClass',
+ *   canHandle: (value): value is MyClass => value instanceof MyClass,
+ *   async encode(value) {
+ *     return { payload: { data: value.serialize() } };
+ *   },
+ *   decode(payload) {
+ *     return MyClass.deserialize(payload.data);
+ *   },
+ * };
+ * ```
+ */
+export interface Transformer<T = unknown, P extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Unique wire tag. The library sets `__rpc_type` to this value when encoding
+     * and uses it to route incoming envelopes to the correct decoder.
+     */
+    type: string;
+    /** Return true if this transformer can handle the given value. */
+    canHandle(value: unknown): value is T;
+    /**
+     * Encode a value into a structured-clone-safe payload.
+     */
+    encode(value: T): Promise<EncodeResult<P>>;
+    /**
+     * Decode a payload back into the original type.
+     */
+    decode(payload: P): T | Promise<T>;
+}
+/** Returns true if `value` is a transformer-encoded wire envelope. */
+export declare function isEncodedValue(value: unknown): value is EncodedValue;
+/**
+ * Run the first matching transformer's encoder on `value`.
+ * Injects `__rpc_type` automatically. Returns the value unchanged if no transformer matches.
+ */
+export declare function applyEncoders(value: unknown, transformers: Transformer[]): Promise<{
+    value: unknown;
+    transferables: Transferable[];
+}>;
+/**
+ * Run the first matching transformer's decoder on a wire envelope.
+ * Strips `__rpc_type` before calling `decode`. Returns the value unchanged
+ * if it is not an encoded envelope or no transformer matches.
+ */
+export declare function applyDecoders(value: unknown, transformers: Transformer[]): Promise<unknown>;

package/dist/transformers/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Built-in transformers for non-cloneable Web API types.
+ *
+ * @example
+ * ```typescript
+ * import { createEndpoint } from '@xentobias/worker-rpc';
+ * import { responseTransformer, requestTransformer } from '@xentobias/worker-rpc/transformers';
+ *
+ * const endpoint = createEndpoint(worker, {
+ *   transformers: [responseTransformer, requestTransformer],
+ * });
+ * ```
+ */
+export { responseTransformer } from './response';
+export { requestTransformer } from './request';
+export { headersToTuples } from './utils';
+export type { ResponsePayload } from './response';
+export type { RequestPayload } from './request';
+export type { Transformer, EncodedValue, EncodeResult, Transferred } from '../transformer';

package/dist/transformers/index.js

@@ -0,0 +1,2 @@
+// @bun
+function T(g){let x=[];return g.forEach((m,H)=>x.push([H,m])),x}var j={type:"Response",canHandle(g){return typeof Response<"u"&&g instanceof Response},async encode(g){let x=g.bodyUsed?null:await g.arrayBuffer();return{transferables:x!==null?[x]:[],payload:{body:x,status:g.status,statusText:g.statusText,headers:T(g.headers)}}},decode(g){return new Response(g.body,{status:g.status,statusText:g.statusText,headers:new Headers(g.headers)})}};var E={type:"Request",canHandle(g){return typeof Request<"u"&&g instanceof Request},async encode(g){let x=g.bodyUsed?null:await g.arrayBuffer();return{transferables:x!==null?[x]:[],payload:{url:g.url,method:g.method,headers:T(g.headers),body:x,mode:g.mode,credentials:g.credentials,cache:g.cache,redirect:g.redirect,referrer:g.referrer,integrity:g.integrity}}},decode(g){return new Request(g.url,{method:g.method,headers:new Headers(g.headers),body:g.body,mode:g.mode,credentials:g.credentials,cache:g.cache,redirect:g.redirect,referrer:g.referrer,integrity:g.integrity})}};export{j as responseTransformer,E as requestTransformer,T as headersToTuples};

package/dist/transformers/request.d.ts

@@ -0,0 +1,36 @@
+import type { Transformer, Transferred } from '../transformer';
+declare global {
+    interface Request extends Transferred {
+    }
+}
+/** Wire-safe payload for a `Request`. */
+export interface RequestPayload extends Record<string, unknown> {
+    url: string;
+    method: string;
+    headers: [string, string][];
+    body: ArrayBuffer | null;
+    mode: RequestMode;
+    credentials: RequestCredentials;
+    cache: RequestCache;
+    redirect: RequestRedirect;
+    referrer: string;
+    integrity: string;
+}
+/**
+ * Built-in transformer for the Web `Request` API.
+ * Buffers the body into an `ArrayBuffer` and zero-copy transfers it.
+ *
+ * Note: if `request.bodyUsed` is `true` when encoding, the decoded
+ * `Request` will have a `null` body. Read the body only after the RPC call returns.
+ *
+ * @example
+ * ```typescript
+ * import { createEndpoint } from '@xentobias/worker-rpc';
+ * import { requestTransformer } from '@xentobias/worker-rpc/transformers';
+ *
+ * const endpoint = createEndpoint(worker, {
+ *   transformers: [requestTransformer],
+ * });
+ * ```
+ */
+export declare const requestTransformer: Transformer<Request, RequestPayload>;

package/dist/transformers/response.d.ts

@@ -0,0 +1,30 @@
+import type { Transformer, Transferred } from '../transformer';
+declare global {
+    interface Response extends Transferred {
+    }
+}
+/** Wire-safe payload for a `Response`. */
+export interface ResponsePayload extends Record<string, unknown> {
+    body: ArrayBuffer | null;
+    status: number;
+    statusText: string;
+    headers: [string, string][];
+}
+/**
+ * Built-in transformer for the Web `Response` API.
+ * Buffers the body into an `ArrayBuffer` and zero-copy transfers it.
+ *
+ * Note: if `response.bodyUsed` is `true` when encoding, the decoded
+ * `Response` will have a `null` body. Read the body only after the RPC call returns.
+ *
+ * @example
+ * ```typescript
+ * import { createEndpoint } from '@xentobias/worker-rpc';
+ * import { responseTransformer } from '@xentobias/worker-rpc/transformers';
+ *
+ * const endpoint = createEndpoint(worker, {
+ *   transformers: [responseTransformer],
+ * });
+ * ```
+ */
+export declare const responseTransformer: Transformer<Response, ResponsePayload>;

package/dist/transformers/utils.d.ts

@@ -0,0 +1,2 @@
+/** Converts a `Headers` object to an array of `[name, value]` tuples for structured-clone transfer. */
+export declare function headersToTuples(headers: Headers): [string, string][];

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { CallbackId, CallId } from './endpoint';
+import type { Transferred } from './transformer';
 /** Path to a nested method (e.g., ['db', 'users', 'find']) */
 export type MethodPath = string[];
 /** Message types for the RPC protocol */
@@ -83,10 +84,10 @@ export type RpcMessage = CallMessage | ResultMessage | ErrorMessage | CallbackMe
 export type Unpromise<T> = T extends Promise<infer U> ? U : T;
 /**
  * Transform first-level functions in a return value to async versions.
- * This matches the runtime behavior where only first-level object properties
- * are scanned for functions (for performance reasons).
+ * Types that extend `Transferred` (e.g. `Response`, `Request`) are passed
+ * through unchanged — their transformer handles encoding/decoding at runtime.
  */
-export type RemoteReturnValue<T> = T extends (...args: infer A) => infer R ? (...args: A) => Promise<Unpromise<R>> : T extends object ? {
+export type RemoteReturnValue<T> = T extends Transferred ? T : T extends (...args: infer A) => infer R ? (...args: A) => Promise<Unpromise<R>> : T extends object ? {
     [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<Unpromise<R>> : T[K];
 } : T;
 /** Helper to convert a single property to its remote version */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xentobias/worker-rpc",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "description": "High-performance, type-safe RPC for Workers",
   "module": "src/index.ts",
   "main": "dist/index.js",
@@ -13,10 +13,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./transformers": {
+      "types": "./dist/transformers/index.d.ts",
+      "import": "./dist/transformers/index.js"
     }
   },
   "scripts": {
-    "build": "bun build ./src/index.ts --minify --outdir ./dist --target bun && tsc --declaration",
+    "build": "bun build ./src/index.ts --minify --outdir ./dist --target bun && bun build ./src/transformers/index.ts --minify --outdir ./dist/transformers --target bun && tsc --declaration",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "prepublishOnly": "bun run build",