ensloppify 1.0.0-beta.1

package/dist/types/data.d.ts

@@ -0,0 +1,73 @@
+import * as acorn from "acorn";
+import { SourceDownloadCallback } from "./patcher";
+export type SourceType = "module" | "script" | "commonjs";
+export type SourcePatchScriptDataKey = string | HTMLScriptElement;
+export declare class SourcePatchScriptData {
+    private static CLEAN_SOURCE_AST_CACHE;
+    private _key;
+    private _source;
+    private _sourceType;
+    private _sourceOriginCanonicalUrl;
+    private _isSourceClean;
+    private _ast;
+    private _isAstOutdated;
+    /**
+     * A key that can identify a {@link SourcePatchScriptData} by the unique script it refers to.
+     *
+     * This must compare equal in two {@link SourcePatchScriptData} instances that point to the same script.
+     */
+    get key(): SourcePatchScriptDataKey;
+    /**
+     * The source code of this script. Patcher functions should apply their changes here.
+     *
+     * NOTE: To avoid unnecessary string comparison, setting this value will mark the source dirty ({@link isSourceClean} == `false`)
+     * and the AST outdated ({@link isAstOutdated}), regardless of whether the value actually changed at all.
+     */
+    get source(): string;
+    get sourceType(): SourceType;
+    /**
+     * The canonical/absolute URL from where this script originates from.
+     * This value should correspond to that of `import.meta.url` as called from this script.
+     *
+     * In the case of a script whose source is embedded into a HTML document, this refers to the URL of the HTML document;
+     * As such, this must not be used distinguishing scripts from each other, as there may be ambiquity across scripts;
+     * Use {@link key} instead, as that can distinguish between scripts embedded into the same document.
+     */
+    get sourceOriginCanonicalUrl(): string;
+    /**
+     * Whether {@link source} has not had any mutations after this {@link SourcePatchScriptData} was constructed.
+     */
+    get isSourceClean(): boolean;
+    /**
+     * The AST of this script as parsed by {@link acorn} or {@link acorn_loose} when {@link parseAstIfOutdated} was last called, or `null` if never parsed.
+     */
+    get ast(): acorn.Program | null;
+    /**
+     * Whether {@link source} has been mutated since {@link ast} was last parsed by {@link parseAstIfOutdated}.
+     */
+    get isAstOutdated(): boolean;
+    set source(value: string);
+    /**
+     * Enables caching AST parsed from clean sources, for when a new {@link SourcePatchScriptData} is instantiated with the same script origin.
+     *
+     * NOTE: This caching behavior assumes that a script origin will always resolve to the same script content.
+     * This assumption may not hold in some cases (unit tests, undeterministic server, etc), which is why caching is disabled by default.
+     */
+    static enableAstCache(): void;
+    /**
+     * Clears and disables the clean source AST cache. See {@link enableAstCache} for more information.
+     */
+    static disableAstCache(): void;
+    static ofModuleSource(source: string, sourceOriginCanonicalUrl: string): SourcePatchScriptData;
+    static ofScriptElement(scriptElement: HTMLScriptElement, srcDownloadCallback: SourceDownloadCallback): Promise<SourcePatchScriptData>;
+    constructor(key: SourcePatchScriptDataKey, source: string, sourceType: SourceType, sourceOriginCanonicalUrl: string);
+    /**
+     * Parses an AST of {@link source} using {@link acorn} or {@link acorn_loose} if {@link ast} is outdated (including `null`).
+     *
+     * The AST can later on be accessed as {@link ast} without reparsing, though you will then have to check {@link isAstOutdated} manually,
+     * if you want to make sure that the AST is consistent with the current {@link source}.
+     *
+     * @returns the parsed AST, or the previously parsed value in {@link ast} if not outdated.
+     */
+    parseAstIfOutdated(): acorn.Program;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { SourcePatchScriptData, SourcePatchScriptDataKey, SourceType } from "./data";
+export { SourcePatcher, SourcePatchCondition, SourcePatchFunction, SourcePatchImplementation, SourceDownloadCallback } from "./patcher";
+export { patchModuleImportsRecursively } from "./patchers/module";

package/dist/types/patcher.d.ts

@@ -0,0 +1,22 @@
+import { SourcePatchScriptData } from "./data";
+export type SourcePatchCondition = string | RegExp | ((scriptData: SourcePatchScriptData, sourcePatcher: SourcePatcher) => boolean | Promise<boolean>);
+export type SourcePatchFunction = (scriptData: SourcePatchScriptData, sourcePatcher: SourcePatcher) => void | Promise<void>;
+export type SourcePatchImplementation = [SourcePatchCondition, SourcePatchFunction];
+export type SourceDownloadCallback = (sourceOriginUrl: string) => string | Promise<string>;
+export declare class SourcePatcher {
+    private patchImplementations;
+    private patchedBlobUrls;
+    private matchingPatchFunctionsCache;
+    constructor(patchImplementations: SourcePatchImplementation[]);
+    patchScriptElementToBlobUrl(scriptElement: HTMLScriptElement, srcDownloadCallback: SourceDownloadCallback): Promise<URL | null>;
+    patchDataToBlobUrl(scriptData: SourcePatchScriptData): Promise<URL | null>;
+    revokePatchedBlobUrls(): void;
+    needsPatching(scriptData: SourcePatchScriptData, options?: {
+        exceptPatchFunctions: SourcePatchFunction[];
+    }): Promise<boolean>;
+    getMatchingPatchFunctions(scriptData: SourcePatchScriptData, options?: {
+        exceptPatchFunctions: SourcePatchFunction[];
+    }): Promise<SourcePatchFunction[]>;
+    private getAllMatchingPatchFunctions;
+    private getPatchedSource;
+}

package/dist/types/patchers/module.d.ts

@@ -0,0 +1,2 @@
+import { SourceDownloadCallback, SourcePatchCondition, SourcePatchFunction } from "../patcher";
+export declare function patchModuleImportsRecursively(importedSourceDownloadCallback: SourceDownloadCallback): [SourcePatchCondition, SourcePatchFunction];

package/dist/types/patchers/module.internal.d.ts

@@ -0,0 +1,11 @@
+import { SourcePatchScriptData } from "../data";
+import { SourceDownloadCallback } from "../patcher";
+export type FoundImport = {
+    resolvedSourceUrl: string;
+    sourceValue: string;
+    sourceValueStartIndex: number;
+    sourceValueEndIndex: number;
+};
+export declare function findImportsRecursive(scriptData: SourcePatchScriptData, importedSourceDownloadCallback: SourceDownloadCallback, dontRecurseIntoUrls?: string[]): Promise<FoundImport[]>;
+export declare function findImports(scriptData: SourcePatchScriptData): FoundImport[];
+export declare function resolveImportSourceUrl(importSourceValue: string, importerScriptData: SourcePatchScriptData): string | null;

package/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "ensloppify",
+    "version": "1.0.0-beta.1",
+    "type": "module",
+    "files": [
+        "./LICENSE",
+        "./dist/esm",
+        "./dist/types"
+    ],
+    "module": "./dist/esm/index.mjs",
+    "types": "./dist/types/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/esm/index.mjs",
+            "types": "./dist/types/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "node build.mts && tsc --project tsconfig.build.json",
+        "test": "vitest --ui"
+    },
+    "dependencies": {
+        "acorn": "^8.18.0",
+        "acorn-loose": "^8.5.2",
+        "acorn-walk": "^8.3.5",
+        "eval-estree-expression": "^4.0.0"
+    },
+    "devDependencies": {
+        "typescript": "^7.0.0",
+        "@types/node": "^26.4.1",
+        "@vitest/browser-playwright": "^4.1.11",
+        "@vitest/ui": "^4.1.11",
+        "esbuild": "^0.28.2",
+        "vitest": "^4.1.11"
+    }
+}