@graphty/graph-io 0.3.47 → 0.3.49

package/dist/src/sources/sparql/query.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The SPARQL the source sends: the caller's CONSTRUCT or DESCRIBE with the paging the source
+ * adds (`ORDER BY` the template's variables, `LIMIT` and `OFFSET`), and the generated queries of
+ * "all", "neighborhood" and expand (`VALUES ?s { ... }`).
+ */
+/** The query forms, as the first keyword after the prologue. */
+type QueryForm = "construct" | "describe" | "select" | "ask" | null;
+/** What paging the caller's query takes. */
+interface UserQuery {
+    /** Its form. */
+    readonly form: QueryForm;
+    /** Whether it sets its own LIMIT or OFFSET, so the source sends it as written. */
+    readonly ownLimit: boolean;
+    /** Whether it orders its solutions itself. */
+    readonly ordered: boolean;
+    /** The variables of a CONSTRUCT template, in order, for ORDER BY. */
+    readonly templateVars: readonly string[];
+}
+/**
+ * Read what paging a caller's query takes.
+ * @param query - the query
+ * @returns its form, its own modifiers and its template variables
+ */
+export declare function readQuery(query: string): UserQuery;
+/**
+ * The caller's query with one page's modifiers added.
+ * @param query - the query
+ * @param shape - what readQuery found
+ * @param limit - solutions per page
+ * @param offset - solutions to skip
+ * @returns the query to send
+ */
+export declare function pagedQuery(query: string, shape: UserQuery, limit: number, offset: number): string;
+/**
+ * An IRI as a SPARQL term, or null when it cannot be one.
+ * @param id - the id
+ * @returns `<iri>`, or null
+ */
+export declare function iriTerm(id: unknown): string | null;
+/** What generated queries keep: literals in a language, edges along some predicates. */
+interface TripleFilter {
+    /** Keep literals tagged with this language or untagged; "" keeps every literal. */
+    readonly language: string;
+    /** Keep edges whose predicate starts with one of these IRIs; empty keeps every edge. */
+    readonly predicates: readonly string[];
+}
+/**
+ * Whether a language tag may go into a FILTER.
+ * @param language - the tag
+ * @returns whether it is well formed
+ */
+export declare function validLanguage(language: string): boolean;
+/**
+ * Mode "all": every triple, ordered so pages are stable.
+ * @param filter - what to keep
+ * @param limit - solutions per page
+ * @param offset - solutions to skip
+ * @returns the query
+ */
+export declare function allQuery(filter: TripleFilter, limit: number, offset: number): string;
+/**
+ * The triples around some IRIs: out (`VALUES ?s`), in (`VALUES ?o`) or both.
+ * @param iris - the IRIs as terms
+ * @param direction - which triples
+ * @param filter - what to keep
+ * @param limit - solutions per page
+ * @param offset - solutions to skip
+ * @returns the query
+ */
+export declare function aroundQuery(iris: readonly string[], direction: "out" | "in" | "both", filter: TripleFilter, limit: number, offset: number): string;
+export {};
+//# sourceMappingURL=query.d.ts.map

package/dist/src/sources/sparql/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../../src/sources/sparql/query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,gEAAgE;AAChE,KAAK,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,KAAK,GAAG,IAAI,CAAC;AAEpE,4CAA4C;AAC5C,UAAU,SAAS;IACf,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAcD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAgBlD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIjG;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGlD;AAED,wFAAwF;AACxF,UAAU,YAAY;IAClB,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAeD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAOpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACvB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,SAAS,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,EAChC,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACf,MAAM,CAcR"}

package/dist/src/sources/sparql/query.js

@@ -0,0 +1,113 @@
+/**
+ * The SPARQL the source sends: the caller's CONSTRUCT or DESCRIBE with the paging the source
+ * adds (`ORDER BY` the template's variables, `LIMIT` and `OFFSET`), and the generated queries of
+ * "all", "neighborhood" and expand (`VALUES ?s { ... }`).
+ */
+/** Characters an IRIREF may not hold. */
+const NOT_IRI = /[\s<>"{}|^`\\]/;
+/** A language tag a filter may name. */
+const LANGUAGE = /^[a-z]{1,8}(-[a-z\d]{1,8})*$/i;
+/**
+ * The query with IRIs, strings and comments blanked out, so keywords and braces can be found.
+ * @param query - the query
+ * @returns the bare text
+ */
+function bare(query) {
+    return query
+        .replaceAll(/<[^<>\s]*>/g, "<>")
+        .replaceAll(/"""[\s\S]*?"""|'''[\s\S]*?'''|"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/g, '""')
+        .replaceAll(/#[^\n]*/g, "");
+}
+/**
+ * Read what paging a caller's query takes.
+ * @param query - the query
+ * @returns its form, its own modifiers and its template variables
+ */
+export function readQuery(query) {
+    const text = bare(query);
+    const form = /\b(CONSTRUCT|DESCRIBE|SELECT|ASK)\b/i.exec(text)?.[1]?.toLowerCase() ?? null;
+    // the solution modifiers follow the last closing brace (a trailing VALUES block is not handled)
+    const tail = text.slice(text.lastIndexOf("}") + 1);
+    let templateVars = [];
+    if (form === "construct") {
+        const template = /\bCONSTRUCT\s*\{([^}]*)\}/i.exec(text)?.[1] ?? "";
+        templateVars = [...new Set(template.match(/[?$]\w+/g) ?? [])].map((v) => `?${v.slice(1)}`);
+    }
+    return {
+        form: form,
+        ownLimit: /\b(LIMIT|OFFSET)\b/i.test(tail),
+        ordered: /\bORDER\s+BY\b/i.test(tail),
+        templateVars,
+    };
+}
+/**
+ * The caller's query with one page's modifiers added.
+ * @param query - the query
+ * @param shape - what readQuery found
+ * @param limit - solutions per page
+ * @param offset - solutions to skip
+ * @returns the query to send
+ */
+export function pagedQuery(query, shape, limit, offset) {
+    const order = shape.ordered || shape.templateVars.length === 0 ? "" : `\nORDER BY ${shape.templateVars.join(" ")}`;
+    const skip = offset > 0 ? ` OFFSET ${String(offset)}` : "";
+    return `${query.trimEnd()}${order}\nLIMIT ${String(limit)}${skip}`;
+}
+/**
+ * An IRI as a SPARQL term, or null when it cannot be one.
+ * @param id - the id
+ * @returns `<iri>`, or null
+ */
+export function iriTerm(id) {
+    const text = String(id);
+    return /^[a-z][\w+.-]*:/i.test(text) && !NOT_IRI.test(text) ? `<${text}>` : null;
+}
+/**
+ * The FILTERs of generated queries, or "" for none. Both values are checked by the caller.
+ * @param filter - the language and the predicate prefixes
+ * @returns the FILTER clauses
+ */
+function filters(filter) {
+    const { language, predicates } = filter;
+    const lang = language === "" ? "" : ` FILTER(!isLiteral(?o) || lang(?o) = "" || langMatches(lang(?o), "${language}"))`;
+    const along = predicates.map((p) => `STRSTARTS(STR(?p), "${p}")`).join(" || ");
+    return predicates.length === 0 ? lang : `${lang} FILTER(isLiteral(?o) || ${along})`;
+}
+/**
+ * Whether a language tag may go into a FILTER.
+ * @param language - the tag
+ * @returns whether it is well formed
+ */
+export function validLanguage(language) {
+    return LANGUAGE.test(language);
+}
+/**
+ * Mode "all": every triple, ordered so pages are stable.
+ * @param filter - what to keep
+ * @param limit - solutions per page
+ * @param offset - solutions to skip
+ * @returns the query
+ */
+export function allQuery(filter, limit, offset) {
+    return pagedQuery(`CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o .${filters(filter)} }`, { form: "construct", ownLimit: false, ordered: false, templateVars: ["?s", "?p", "?o"] }, limit, offset);
+}
+/**
+ * The triples around some IRIs: out (`VALUES ?s`), in (`VALUES ?o`) or both.
+ * @param iris - the IRIs as terms
+ * @param direction - which triples
+ * @param filter - what to keep
+ * @param limit - solutions per page
+ * @param offset - solutions to skip
+ * @returns the query
+ */
+export function aroundQuery(iris, direction, filter, limit, offset) {
+    const values = iris.join(" ");
+    const out = `{ VALUES ?s { ${values} } ?s ?p ?o .${filters(filter)} }`;
+    const inward = `{ VALUES ?o { ${values} } ?s ?p ?o .${filters({ ...filter, language: "" })} }`;
+    let where = `${out} UNION ${inward}`;
+    if (direction !== "both") {
+        where = direction === "out" ? out : inward;
+    }
+    return pagedQuery(`CONSTRUCT { ?s ?p ?o } WHERE { ${where} }`, { form: "construct", ownLimit: false, ordered: false, templateVars: ["?s", "?p", "?o"] }, limit, offset);
+}
+//# sourceMappingURL=query.js.map

package/dist/src/sources/sparql/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../../src/sources/sparql/query.ts"],"names":[],"mappings":"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"}

package/dist/src/sources/testing.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Testing a source without a network: `replayFetch` answers requests from recorded responses and
+ * refuses any request it has no recording for. Browser-safe (no file system), so a graphty-element
+ * story and a third party's tests use it the same way.
+ */
+/**
+ * One recorded exchange. Experimental.
+ * @category Network sources
+ */
+export interface Recording {
+    /** The request method. @defaultValue "GET" */
+    readonly method?: string | undefined;
+    /** The request URL. Query parameters match in any order. */
+    readonly url: string;
+    /** The request body, when it must match (JSON bodies compare as JSON). */
+    readonly requestBody?: string | undefined;
+    /**
+     * true: the request must carry a credential; false: it must not. Absent: either. A credential
+     * is an Authorization header, or a header or query parameter named in `secretHeaders` /
+     * `secretQuery`; its value is never compared.
+     */
+    readonly credential?: boolean | undefined;
+    /** The response status. @defaultValue 200 */
+    readonly status?: number | undefined;
+    /** The response headers. */
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    /** The response body: text, or a value sent as JSON. */
+    readonly body?: unknown;
+}
+/**
+ * The options of `replayFetch`. Experimental.
+ * @category Network sources
+ */
+export interface ReplayOptions {
+    /** What an unrecorded request does: "throw" (the only choice; the test fails). @defaultValue "throw" */
+    readonly onUnrecorded?: "throw" | undefined;
+    /** Query parameters that hold a credential: ignored when matching, counted as a credential. */
+    readonly secretQuery?: readonly string[] | undefined;
+    /** Request headers that hold a credential, beside Authorization. */
+    readonly secretHeaders?: readonly string[] | undefined;
+}
+/**
+ * One request `replayFetch` answered. Experimental.
+ * @category Network sources
+ */
+export interface ReplayCall {
+    /** The method. */
+    readonly method: string;
+    /** The URL, origin and path only. */
+    readonly url: string;
+    /** Whether a credential was sent. */
+    readonly credential: boolean;
+}
+/**
+ * A fetch that answers from recordings, plus the requests it answered. Experimental.
+ * @category Network sources
+ */
+export type ReplayFetch = typeof fetch & {
+    /** The requests answered, in order. */
+    readonly calls: readonly ReplayCall[];
+};
+/**
+ * A fetch that answers every request from recordings: the first unused recording that matches
+ * (method, URL with its query in any order, body when recorded, and whether a credential was
+ * sent), else the last one that matched, so a recording answers every repeat. A request with no
+ * matching recording rejects with an Error naming its method and URL, which a source never
+ * retries. Like fetch, a request whose signal is already aborted rejects with the signal's
+ * reason. Pass it as the `fetch` option. Experimental.
+ * @param recordings - the recorded exchanges
+ * @param options - which headers and query parameters hold a credential
+ * @returns the fetch
+ * @example
+ * ```ts
+ * const fetch = replayFetch([{ url: "https://example.com/api/people.json?team=core", body: [{ id: "ana", knows: [] }] }]);
+ * await loadFromSource("people", { team: "core" }, { endpoint: "https://example.com", fetch });
+ * ```
+ * @category Network sources
+ */
+export declare function replayFetch(recordings: readonly Recording[], options?: ReplayOptions): ReplayFetch;
+/**
+ * A recording made from a real exchange, without its credential: the request's headers are never
+ * kept, query parameters named in `secretQuery` are removed from the URL, and of the response only
+ * the status, the Content-Type and the headers named in `keepHeaders` are kept. Experimental.
+ * @param request - the request sent
+ * @param response - its response (read; pass a clone to keep using it)
+ * @param options - what to keep and drop
+ * @param options.keepHeaders - response headers to keep beside Content-Type
+ * @param options.secretQuery - query parameters removed from the URL
+ * @returns the recording
+ * @category Network sources
+ */
+export declare function recordingFrom(request: Request, response: Response, options?: {
+    readonly keepHeaders?: readonly string[];
+    readonly secretQuery?: readonly string[];
+}): Promise<Recording>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/src/sources/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../src/sources/testing.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,WAAW,SAAS;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAChE,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC1B,wGAAwG;IACxG,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,+FAA+F;IAC/F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACrD,oEAAoE;IACpE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAC1D;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACvB,kBAAkB;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,KAAK,GAAG;IACrC,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACzC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,WAAW,CAkDtG;AAsCD;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAC/B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GACrG,OAAO,CAAC,SAAS,CAAC,CAsBpB"}

package/dist/src/sources/testing.js

@@ -0,0 +1,138 @@
+/**
+ * Testing a source without a network: `replayFetch` answers requests from recorded responses and
+ * refuses any request it has no recording for. Browser-safe (no file system), so a graphty-element
+ * story and a third party's tests use it the same way.
+ */
+/**
+ * A fetch that answers every request from recordings: the first unused recording that matches
+ * (method, URL with its query in any order, body when recorded, and whether a credential was
+ * sent), else the last one that matched, so a recording answers every repeat. A request with no
+ * matching recording rejects with an Error naming its method and URL, which a source never
+ * retries. Like fetch, a request whose signal is already aborted rejects with the signal's
+ * reason. Pass it as the `fetch` option. Experimental.
+ * @param recordings - the recorded exchanges
+ * @param options - which headers and query parameters hold a credential
+ * @returns the fetch
+ * @example
+ * ```ts
+ * const fetch = replayFetch([{ url: "https://example.com/api/people.json?team=core", body: [{ id: "ana", knows: [] }] }]);
+ * await loadFromSource("people", { team: "core" }, { endpoint: "https://example.com", fetch });
+ * ```
+ * @category Network sources
+ */
+export function replayFetch(recordings, options = {}) {
+    const secretQuery = new Set(options.secretQuery ?? []);
+    const secretHeaders = ["authorization", ...(options.secretHeaders ?? []).map((h) => h.toLowerCase())];
+    const used = new Set();
+    const calls = [];
+    const key = (url) => {
+        const params = [...url.searchParams].filter(([k]) => !secretQuery.has(k)).sort(compare);
+        return `${url.origin}${url.pathname}?${new URLSearchParams(params).toString()}`;
+    };
+    const replay = async (input, init) => {
+        const request = new Request(input, init);
+        // like fetch: an aborted signal rejects with its reason before anything is answered
+        request.signal.throwIfAborted();
+        const url = new URL(request.url);
+        const method = request.method.toUpperCase();
+        const body = method === "GET" || method === "HEAD" ? "" : await request.clone().text();
+        const credential = secretHeaders.some((h) => request.headers.has(h)) ||
+            [...url.searchParams.keys()].some((k) => secretQuery.has(k));
+        const wanted = key(url);
+        const matches = [];
+        recordings.forEach((r, i) => {
+            if ((r.method ?? "GET").toUpperCase() === method &&
+                key(new URL(r.url)) === wanted &&
+                (r.credential === undefined || r.credential === credential) &&
+                (r.requestBody === undefined || sameBody(r.requestBody, body))) {
+                matches.push(i);
+            }
+        });
+        const index = matches.find((i) => !used.has(i)) ?? matches.at(-1);
+        if (index === undefined) {
+            throw new Error(`replayFetch: no recording for ${method} ${url.origin}${url.pathname}`);
+        }
+        used.add(index);
+        calls.push({ method, url: `${url.origin}${url.pathname}`, credential });
+        const r = recordings[index];
+        const status = r.status ?? 200;
+        const text = bodyText(r.body);
+        const headers = new Headers(r.headers);
+        if (text !== null && typeof r.body !== "string" && !headers.has("content-type")) {
+            headers.set("content-type", "application/json");
+        }
+        const nullBody = status === 204 || status === 304 || (status >= 300 && status < 400 && text === null);
+        return new Response(nullBody ? null : text, { status, headers });
+    };
+    return Object.assign(replay, { calls });
+}
+/**
+ * A recorded body as response text.
+ * @param body - the recorded body
+ * @returns the text, or null for no body
+ */
+function bodyText(body) {
+    if (body === undefined || body === null) {
+        return null;
+    }
+    return typeof body === "string" ? body : JSON.stringify(body);
+}
+/**
+ * Compare two query entries by key, then value.
+ * @param a - one entry
+ * @param b - another
+ * @returns the order
+ */
+function compare(a, b) {
+    return a[0] === b[0] ? a[1].localeCompare(b[1]) : a[0].localeCompare(b[0]);
+}
+/**
+ * Whether two bodies are the same, as JSON when both parse.
+ * @param recorded - the recorded body
+ * @param sent - the sent body
+ * @returns true when they match
+ */
+function sameBody(recorded, sent) {
+    try {
+        return JSON.stringify(JSON.parse(recorded)) === JSON.stringify(JSON.parse(sent));
+    }
+    catch {
+        return recorded === sent;
+    }
+}
+/**
+ * A recording made from a real exchange, without its credential: the request's headers are never
+ * kept, query parameters named in `secretQuery` are removed from the URL, and of the response only
+ * the status, the Content-Type and the headers named in `keepHeaders` are kept. Experimental.
+ * @param request - the request sent
+ * @param response - its response (read; pass a clone to keep using it)
+ * @param options - what to keep and drop
+ * @param options.keepHeaders - response headers to keep beside Content-Type
+ * @param options.secretQuery - query parameters removed from the URL
+ * @returns the recording
+ * @category Network sources
+ */
+export async function recordingFrom(request, response, options = {}) {
+    const headers = {};
+    for (const name of ["content-type", ...(options.keepHeaders ?? [])]) {
+        const value = response.headers.get(name);
+        if (value !== null) {
+            headers[name.toLowerCase()] = value;
+        }
+    }
+    const url = new URL(request.url);
+    for (const name of options.secretQuery ?? []) {
+        url.searchParams.delete(name);
+    }
+    const method = request.method.toUpperCase();
+    const requestBody = method === "GET" || method === "HEAD" ? undefined : await request.clone().text();
+    return {
+        method,
+        url: url.toString(),
+        ...(requestBody === undefined || requestBody === "" ? {} : { requestBody }),
+        status: response.status,
+        headers,
+        body: await response.text(),
+    };
+}
+//# sourceMappingURL=testing.js.map

package/dist/src/sources/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../../src/sources/testing.ts"],"names":[],"mappings":"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"}