Scramjet provides type definitions for modules, proxies, and traps used in the interception system.
ScramjetModule Interface for Scramjet modules that hook into browser APIs.
type ScramjetModule = { enabled ?: ( client : ScramjetClient ) => boolean | undefined ; disabled ?: ( client : ScramjetClient , self : typeof globalThis ) => void | undefined ; order ?: number | undefined ; default : ( client : ScramjetClient , self : typeof globalThis ) => void ; };
Properties enabled
(client: ScramjetClient) => boolean | undefined
Optional function that returns whether the module should be enabled for the given client. enabled ( client ) { // Only enable for secure contexts return client . global . isSecureContext ; }
disabled
(client: ScramjetClient, self: typeof globalThis) => void | undefined
Optional function called when the module is disabled.
Optional loading order. Lower numbers load first. Default: 0
default
(client: ScramjetClient, self: typeof globalThis) => void
required
The main module function that applies hooks and modifications.
Example import { ScramjetModule } from "scramjet" ; const fetchModule : ScramjetModule = { order: 1 , enabled ( client ) { return typeof client . global . fetch === "function" ; }, default ( client , self ) { client . Proxy ( "fetch" , { apply ( ctx ) { // Rewrite URL before fetching ctx . args [ 0 ] = rewriteUrl ( ctx . args [ 0 ]); return ctx . call (); } }); } };
Proxy Handler type for proxying functions and constructors.
type Proxy = { construct ? ( ctx : ProxyCtx ) : any ; apply ? ( ctx : ProxyCtx ) : any ; };
Properties Handler for constructor calls (when using new)
Handler for function calls
Example client . Proxy ( "XMLHttpRequest.prototype.open" , { apply ( ctx ) { // ctx.args = [method, url, async, user, password] console . log ( "XHR opening:" , ctx . args [ 1 ]); // Rewrite the URL (second argument) ctx . args [ 1 ] = rewriteUrl ( ctx . args [ 1 ]); // Call the original function return ctx . call (); } }); client . Proxy ( "Worker" , { construct ( ctx ) { // ctx.args = [scriptURL, options] console . log ( "Creating worker:" , ctx . args [ 0 ]); // Rewrite the script URL ctx . args [ 0 ] = rewriteUrl ( ctx . args [ 0 ]); // Call the original constructor return ctx . call (); } });
ProxyCtx Context object passed to proxy handlers.
type ProxyCtx = { fn : Function ; this : any ; args : any []; newTarget : Function ; return : ( r : any ) => void ; call : () => any ; };
Properties The original function or constructor being called
The this context for the call
The arguments array. You can modify this before calling.
The constructor that was originally called (for construct handlers)
Function to return a value early without calling the original apply ( ctx ) { // Return a fake value without calling original ctx . return ( "fake response" ); }
Function to call the original function/constructor with the (possibly modified) arguments apply ( ctx ) { ctx . args [ 0 ] = rewriteUrl ( ctx . args [ 0 ]); return ctx . call (); // Call with modified args }
Trap Handler type for trapping property access.
type Trap < T > = { writable ?: boolean ; value ?: any ; enumerable ?: boolean ; configurable ?: boolean ; get ?: ( ctx : TrapCtx < T >) => T ; set ?: ( ctx : TrapCtx < T >, v : T ) => void ; };
Properties Whether the property is writable
Static value for the property
Whether the property shows up in enumeration
Whether the property descriptor can be changed
Getter function for the property
set
(ctx: TrapCtx<T>, v: T) => void
Setter function for the property
Example client . Trap ( "document.cookie" , { get ( ctx ) { // Return cookies from Scramjet's cookie store return client . cookieStore . getCookies (); }, set ( ctx , value ) { // Store cookie in Scramjet's cookie store client . cookieStore . setCookie ( value ); } }); client . Trap ( "window.origin" , { get ( ctx ) { // Return the proxified origin instead of the real one return client . url . origin ; } });
TrapCtx Context object passed to trap handlers.
type TrapCtx < T > = { this : any ; get : () => T ; set : ( v : T ) => void ; };
Properties The this context for the property access
Function to get the original property value get ( ctx ) { const original = ctx . get (); return rewriteUrl ( original ); }
Function to set the original property value set ( ctx , value ) { const unrewritten = unrewriteUrl ( value ); ctx . set ( unrewritten ); }
Complete example import { ScramjetClient , Proxy , Trap } from "scramjet" ; // Example module that hooks fetch and location.href const exampleModule = { order: 1 , default ( client : ScramjetClient , self : typeof globalThis ) { // Proxy fetch function client . Proxy ( "fetch" , { apply ( ctx ) { const url = ctx . args [ 0 ]; console . log ( "Fetching:" , url ); // Rewrite the URL ctx . args [ 0 ] = rewriteUrl ( url , client . meta ); // Call original fetch return ctx . call (); } }); // Trap location.href property client . Trap ( "location.href" , { get ( ctx ) { // Return proxified URL return client . url . href ; }, set ( ctx , value ) { // Handle navigation client . url = value ; } }); // Proxy Worker constructor client . Proxy ( "Worker" , { construct ( ctx ) { // Rewrite worker script URL ctx . args [ 0 ] = rewriteUrl ( ctx . args [ 0 ], client . meta ); return ctx . call (); } }); } };