Skip to content

zimscraperlib.rewriting.js

JS Rewriting

This modules contains tools to rewrite JS retrieved from an online source so that it can safely operate within a ZIM. It is based on the assumption that wombat.js will be used for proper JS operation, intercepting all HTTP requests and rewriting them as needed. The main purpose of the rewriting is hence simply to properly include and configure wombat.js.

This modules assumes that: - every HTML page in the ZIM have been properly rewriten to include wombat.js and setup it appropriately - a specific JS file (provided in statics folder) for JS modules is included in the ZIM at _zim_static/__wb_module_decl.js

This code is based on https://github.com/webrecorder/wabac.js/blob/main/src/rewrite/jsrewriter.ts Last backport of upstream changes is from wabac.js commit: Feb 20, 2026 - 25061cb53ff113d5cff28f2f1354819f6c41034b

Classes:

  • JsRewriter –

    JsRewriter is in charge of rewriting the js code stored in our zim file.

Functions:

Attributes:

GLOBALS_RX module-attribute 

GLOBALS_RX = compile(
    "("
    + join(
        [
            ("(?:^|[^$.])\\b" + x + "\\b(?:$|[^$])")
            for x in GLOBAL_OVERRIDES
        ]
    )
    + ")"
)

GLOBAL_OVERRIDES module-attribute 

GLOBAL_OVERRIDES = [
    "window",
    "globalThis",
    "self",
    "document",
    "location",
    "top",
    "parent",
    "frames",
    "opener",
]

IMPORT_EXPORT_HTTP_RX module-attribute 

IMPORT_EXPORT_HTTP_RX = compile(
    "((?:im|ex)port(?:['\"\\s]*(?:[\\w*${}\\s,]+from\\s*)?['\"\\s]?['\"\\s]))((?:https?|[./]).*?)(['\"\\s])"
)

IMPORT_EXPORT_MATCH_RX module-attribute 

IMPORT_EXPORT_MATCH_RX = compile(
    "(^|;)\\s*?(?:im|ex)port(?:['\"\\s]*(?:[\\w*${}\\s,]+from\\s*)?['\"\\s]?['\"\\s])(?:.*?)['\"\\s]"
)

REWRITE_JS_RULES module-attribute 

REWRITE_JS_RULES = create_js_rules()

this_rw module-attribute 

this_rw = '_____WB$wombat$check$this$function_____(this)'

JsRewriter 

JsRewriter(
    url_rewriter: ArticleUrlRewriter,
    base_href: str | None,
    notify_js_module: Callable[[ZimPath], None] | None,
)

Bases: RxRewriter

JsRewriter is in charge of rewriting the js code stored in our zim file.

Methods:

  • rewrite –

    Rewrite the js code in text.

Attributes:

Source code in src/zimscraperlib/rewriting/js.py 
234
235
236
237
238
239
240
241
242
243
244
245
def __init__(
    self,
    url_rewriter: ArticleUrlRewriter,
    base_href: str | None,
    notify_js_module: Callable[[ZimPath], None] | None,
):
    super().__init__(None)
    self.first_buff = self._init_local_declaration(GLOBAL_OVERRIDES)
    self.last_buff = "\n}"
    self.url_rewriter = url_rewriter
    self.notify_js_module = notify_js_module
    self.base_href = base_href

base_href instance-attribute 

base_href = base_href

compiled_rule instance-attribute 

compiled_rule: Pattern[str] | None = None

first_buff instance-attribute 

first_buff = _init_local_declaration(GLOBAL_OVERRIDES)

last_buff instance-attribute 

last_buff = '\n}'

notify_js_module instance-attribute 

notify_js_module = notify_js_module

rules instance-attribute 

rules = rules or []

url_rewriter instance-attribute 

url_rewriter = url_rewriter

rewrite 

rewrite(
    text: str | bytes, opts: dict[str, Any] | None = None
) -> str

Rewrite the js code in text.

Source code in src/zimscraperlib/rewriting/js.py 
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
def rewrite(self, text: str | bytes, opts: dict[str, Any] | None = None) -> str:
    """
    Rewrite the js code in `text`.
    """
    if isinstance(text, bytes):
        text = text.decode()

    opts = opts or {}

    is_module = opts.get("isModule", False)

    # Detect and set strict mode
    # Modules are always strict mode
    if is_module:
        opts["isStrict"] = True
    elif "isStrict" not in opts:  # pragma: no branch
        # Detect strict mode from the code itself
        opts["isStrict"] = self._detect_strict_mode(text)

    rules = REWRITE_JS_RULES[:]

    if is_module:
        rules.append(self._get_esm_import_rule())

    self._compile_rules(rules)

    new_text = super().rewrite(text, opts)

    if is_module:
        return self._get_module_decl(GLOBAL_OVERRIDES) + new_text

    if GLOBALS_RX.search(text):
        new_text = self.first_buff + new_text + self.last_buff

    if opts.get("inline", False):
        new_text = new_text.replace("\n", " ")

    return new_text

add_suffix_non_prop 

add_suffix_non_prop(suffix: str) -> TransformationAction

Create a rewrite_function which add a suffix to the match str. The suffix is added only if the match is not preceded by . or $. Applies strict mode transformation to handle 'arguments' keyword.

Source code in src/zimscraperlib/rewriting/js.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def add_suffix_non_prop(suffix: str) -> TransformationAction:
    """
    Create a rewrite_function which add a `suffix` to the match str.
    The suffix is added only if the match is not preceded by `.` or `$`.
    Applies strict mode transformation to handle 'arguments' keyword.
    """

    def f(m_object: re.Match[str], opts: dict[str, Any] | None) -> str:
        offset = m_object.start()
        full_string = m_object.string
        if offset > 0 and full_string[offset - 1] in ".$":
            return m_object[0]
        return m_object[0] + remove_args_if_strict(suffix, opts, offset, full_string)

    return f

create_js_rules 

create_js_rules() -> list[TransformationRule]

This function create all the transformation rules.

A transformation rule is a tuple (Regex, rewrite_function). If the regex match in the rewritten script, the corresponding match object will be passed to rewrite_function. The rewrite_function must all take a opts dictionnary which will be the opts passed to the JsRewriter.rewrite function. This is mostly as if we were calling re.sub(regex, rewrite_function, script_text).

The regex will be combined and will match any non overlaping text. So rule to match will be applyed, potentially preventing futher rules to match.

Source code in src/zimscraperlib/rewriting/js.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
def create_js_rules() -> list[TransformationRule]:
    """
    This function create all the transformation rules.

    A transformation rule is a tuple (Regex, rewrite_function).
    If the regex match in the rewritten script, the corresponding match object will be
    passed to rewrite_function.
    The rewrite_function must all take a `opts` dictionnary which will be the opts
    passed to the `JsRewriter.rewrite` function.
    This is mostly as if we were calling `re.sub(regex, rewrite_function, script_text)`.

    The regex will be combined and will match any non overlaping text.
    So rule to match will be applyed, potentially preventing futher rules to match.
    """

    # This will replace `location = `. This will "see" with wombat and set what have to
    # be set.
    check_loc = (
        "((self.__WB_check_loc && self.__WB_check_loc(location, arguments)) || "
        "{}).maybeHref = "
    )

    # This will replace `eval(...)`.
    eval_str = (
        "WB_wombat_runEval2((_______eval_arg, isGlobal) => { var ge = eval; return "
        "isGlobal ? ge(_______eval_arg) : "
        "eval(_______eval_arg); }).eval(this, (function() { return arguments })(),"
    )

    return [
        # rewriting `eval(...)` - invocation
        (
            re.compile(r"(?<!static)(?<!function)(?<!})(?:^|\s)\beval\s*\("),
            replace_prefix_from(eval_str, "eval"),
        ),
        (re.compile(r"\([\w]+,\s*eval\)\("), m2str(lambda _: f" {eval_str}")),
        # rewriting `x = eval` - no invocation
        (re.compile(r"[=]\s*\beval\b(?![(:.$])"), replace("eval", "self.eval")),
        (re.compile(r"var\s+self"), replace("var", "let")),
        # rewriting `.postMessage` -> `__WB_pmw(self).postMessage`
        (re.compile(r"\.postMessage\b\("), add_prefix(".__WB_pmw(self)")),
        # rewriting `location = ` to custom expression `(...).href =` assignement
        (
            re.compile(r"(?:^|[^$.+*/%^-])\s?\blocation\b\s*[=]\s*(?![\s\d=>])"),
            add_suffix_non_prop(check_loc),
        ),
        # rewriting `return this`
        (re.compile(r"\breturn\s+this\b\s*(?![\s\w.$])"), replace_this()),
        # rewriting `this.` special porperties access on new line, with ; perpended
        # if prev chars is `\n`, or if prev is not `.` or `$`, no semi
        (
            re.compile(
                rf"[^$.]\s?\bthis\b(?=(?:\.(?:{'|'.join(GLOBAL_OVERRIDES)})\b))"
            ),
            replace_this_non_prop(),
        ),
        # rewrite `= this` or `, this`
        (re.compile(r"[=,]\s*\bthis\b\s*(?![\s\w:.$])"), replace_this()),
        # rewrite `})(this_rw)`
        (re.compile(r"\}(?:\s*\))?\s*\(this\)"), replace_this()),
        # rewrite this in && or || expr
        (
            re.compile(r"[^|&][|&]{2}\s*this\b\s*(?![|\s&.$](?:[^|&]|$))"),
            replace_this(),
        ),
        # ignore `async import`.
        # As the rule will match first, it will prevent next rule matching `import` to
        # be apply to `async import`.
        (re.compile(r"async\s+import\s*\("), m2str(lambda x: x)),
        (re.compile(r"[^$.]\bimport\s*\([^)]*\)\s*\{"), m2str(lambda x: x)),
        # esm dynamic import, if found, mark as module
        (
            re.compile(r"[^$.]\bimport\s*\("),
            replace_import("import", "____wb_rewrite_import__"),
        ),
    ]

remove_args_if_strict 

remove_args_if_strict(
    target: str,
    opts: dict[str, Any] | None,
    offset: int,
    full_string: str,
) -> str

Replace 'arguments' with '[]' if the code is in strict mode. In strict mode, the arguments keyword is not allowed.

Source code in src/zimscraperlib/rewriting/js.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def remove_args_if_strict(
    target: str, opts: dict[str, Any] | None, offset: int, full_string: str
) -> str:
    """
    Replace 'arguments' with '[]' if the code is in strict mode.
    In strict mode, the arguments keyword is not allowed.
    """
    opts = opts or {}

    # Detect strict mode if not already set by checking for class declaration
    if "isStrict" not in opts:
        opts["isStrict"] = full_string[:offset].find("class ") >= 0  # pragma: no cover
    if opts.get("isStrict"):
        return target.replace("arguments", "[]")
    return target

replace_import 

replace_import(
    src: str, target: str
) -> TransformationAction

Create a rewrite_function replacing src by target in the matching str.

This "replace" function is intended to be use to replace in import ... as it adds a import.meta.url if we are in a module.

Source code in src/zimscraperlib/rewriting/js.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def replace_import(src: str, target: str) -> TransformationAction:
    """
    Create a rewrite_function replacing `src` by `target` in the matching str.

    This "replace" function is intended to be use to replace in `import ...` as it
    adds a `import.meta.url` if we are in a module.
    """

    def f(m_object: re.Match[str], opts: dict[str, Any] | None) -> str:
        return m_object[0].replace(src, target) + (
            "import.meta.url, " if opts and opts.get("isModule") else '"", '
        )

    return f

replace_this 

replace_this() -> TransformationAction

Create a rewrite_function replacing "this" by this_rw in the matching str.

Source code in src/zimscraperlib/rewriting/js.py 
104
105
106
107
108
def replace_this() -> TransformationAction:
    """
    Create a rewrite_function replacing "this" by `this_rw` in the matching str.
    """
    return replace("this", this_rw)

replace_this_non_prop 

replace_this_non_prop() -> TransformationAction

Create a rewrite_function replacing "this" by this_rw.

Replacement happen only if "this" is not a property of an object.

Source code in src/zimscraperlib/rewriting/js.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def replace_this_non_prop() -> TransformationAction:
    """
    Create a rewrite_function replacing "this" by `this_rw`.

    Replacement happen only if "this" is not a property of an object.
    """

    def f(m_object: re.Match[str], _opts: dict[str, Any] | None) -> str:
        offset = m_object.start()
        prev = m_object.string[offset - 1] if offset > 0 else ""
        if prev == "\n":
            # This detection of new line is probably buggy, plus it is hard to get the
            # intent of this, see https://github.com/openzim/warc2zim/issues/410
            return m_object[0].replace("this", ";" + this_rw)
        if prev not in ".$":
            return m_object[0].replace("this", this_rw)
        return m_object[0]

    return f