@shipworthy/openapi-parser 0.0.0-stage → 0.0.1

package/dist/run.d.ts

@@ -0,0 +1,17 @@
+import { Effect, FileSystem } from "effect";
+import type { HttpClient } from "effect/http";
+import { type TaggedFailure } from "./errors.ts";
+import { Options } from "./plugins.ts";
+interface RunResult {
+    schema: unknown;
+    documents: Map<string, unknown>;
+}
+type RunMode = "parse" | "bundle" | "dereference";
+interface RunRequest {
+    readonly path: string;
+    readonly schema?: unknown;
+    readonly options?: Options;
+    readonly mode?: RunMode;
+}
+export declare const runEffect: (args: RunRequest) => Effect.Effect<RunResult, TaggedFailure, FileSystem.FileSystem | HttpClient.HttpClient>;
+export {};

package/dist/run.js

@@ -0,0 +1,313 @@
+import { Array, Cache, Effect, Predicate, Ref, Schema } from "effect";
+import { ParserFailure, groupFailure, isLeafFailure, missingPointerFailure, syncFailure, } from "./errors.js";
+import { hoistExternalRefs } from "./hoist.js";
+import { loadDocument, makeContext } from "./loader.js";
+import { Options } from "./plugins.js";
+import { cloneData, joinPointer, parsePointer } from "./pointer.js";
+import { inlineRemaining, runSchemaPipeline } from "./pipeline.js";
+import { isOpenApi3, upgradeOpenApi3_0 } from "./upgraders/3.0-to-3.1.js";
+import { getHash, isHttp, normalizeRef, resolveAgainst, stripHash } from "./url.js";
+const loadConcurrency = 8;
+export const runEffect = Effect.fn("openapi-parser.run")(function* (args) {
+    const mode = args.mode ?? "bundle";
+    const options = yield* Schema.decodeEffect(Options)(args.options ?? {}).pipe(Effect.mapError((cause) => new ParserFailure({ message: cause.message, source: args.path, cause })));
+    const rootUrl = yield* normalizeRef(args.path);
+    const context = makeContext(rootUrl, options);
+    const failures = yield* Ref.make([]);
+    const recorded = new Set();
+    const cache = yield* Cache.make({
+        capacity: 10_000,
+        lookup: (url) => loadDocument(url, context).pipe(Effect.withSpan("openapi-parser.load", { attributes: { url } })),
+    });
+    const documents = new Map();
+    const rootKey = stripHash(rootUrl);
+    const root = args.schema === undefined
+        ? yield* loadCaught(cache, rootKey, options, failures, recorded)
+        : cloneData(args.schema);
+    if (root === undefined)
+        return yield* failCollected(rootUrl, failures);
+    documents.set(rootKey, root);
+    if (mode === "parse")
+        return { schema: root, documents };
+    const kept = new Set();
+    const ids = new Map();
+    const keep = (ref) => Boolean(options.keepUrlRefs && isHttp(ref));
+    if (typeof root === "object" && root !== null)
+        absolutize(root, rootUrl, ids, keep, kept);
+    yield* loadClosure(root, cache, documents, ids, keep, kept, options, failures, recorded);
+    const collected = yield* Ref.get(failures);
+    if (collected.length > 0 && options.continueOnError)
+        return yield* failCollected(rootUrl, failures);
+    if (typeof root !== "object" || root === null || Array.isArray(root))
+        return { schema: root, documents };
+    const record = root;
+    yield* Effect.try({
+        try: () => {
+            const placed = hoistExternalRefs(record, (url) => documents.get(stripHash(url)), options.bundle, (ref) => kept.has(ref) || ids.has(stripHash(ref)));
+            rewriteIdRefs(record, ids);
+            rewriteMappings(record, placed, ids);
+            if (isOpenApi3(record)) {
+                upgradeOpenApi3_0(record);
+                runSchemaPipeline(record, mode === "dereference" ? "dereference" : "bundle", options.dereference);
+            }
+            else if (mode === "dereference") {
+                inlineRemaining(record, new Set(), options.dereference);
+            }
+        },
+        catch: syncFailure,
+    });
+    yield* inlineExternalValues(record, cache, keep, kept, options, failures, recorded);
+    if ((yield* Ref.get(failures)).length > 0)
+        return yield* failCollected(rootUrl, failures);
+    return { schema: root, documents };
+});
+const failCollected = Effect.fnUntraced(function* (source, failures) {
+    return yield* Ref.get(failures).pipe(Effect.flatMap((errors) => Effect.fail(groupFailure(source, errors))));
+});
+const loadCaught = Effect.fnUntraced(function* (cache, url, options, failures, recorded) {
+    return yield* Cache.get(cache, url).pipe(Effect.catch((error) => {
+        if (!options.continueOnError || !isLeafFailure(error))
+            return Effect.fail(error);
+        if (recorded.has(url))
+            return Effect.void;
+        recorded.add(url);
+        return Ref.update(failures, (list) => [...list, error]).pipe(Effect.asVoid);
+    }));
+});
+const loadClosure = Effect.fnUntraced(function* (root, cache, documents, ids, keep, kept, options, failures, recorded) {
+    const pending = new Set();
+    let pass = 0;
+    let remaining = true;
+    yield* Effect.whileLoop({
+        while: () => pass < 1000 && remaining,
+        body: () => Effect.gen(function* () {
+            pending.clear();
+            Array.forEach([root, ...documents.values()], (document) => {
+                Array.forEach(Array.fromIterable(externalRefs(document, kept)), (ref) => {
+                    const url = stripHash(ref);
+                    if (!ids.has(url) && !documents.has(url) && !kept.has(ref) && !recorded.has(url))
+                        pending.add(url);
+                });
+            });
+            if (pending.size === 0)
+                return false;
+            yield* Effect.forEach(pending, Effect.fnUntraced(function* (url) {
+                const loaded = yield* loadCaught(cache, url, options, failures, recorded);
+                if (loaded === undefined)
+                    return;
+                absolutize(loaded, url, ids, keep, kept);
+                documents.set(url, loaded);
+            }), { concurrency: loadConcurrency, discard: true });
+            return true;
+        }),
+        step: (more) => {
+            remaining = more;
+            pass++;
+        },
+    });
+});
+const referenceKeys = new Set(["$ref", "summary", "description"]);
+/** HTTP `$ref` fields inside example payloads are data, not OpenAPI references. */
+function isBundledRef(record) {
+    const ref = record.$ref;
+    if (typeof ref !== "string" || !isHttp(ref))
+        return true;
+    return Object.keys(record).every((key) => referenceKeys.has(key));
+}
+function* externalRefs(node, kept) {
+    const seen = new Set();
+    const stack = [node];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (typeof current !== "object" || current === null || seen.has(current))
+            continue;
+        seen.add(current);
+        if (Array.isArray(current)) {
+            stack.push(...current);
+            continue;
+        }
+        const record = current;
+        if (typeof record.$ref === "string" &&
+            !record.$ref.startsWith("#") &&
+            !kept.has(record.$ref) &&
+            isBundledRef(record)) {
+            yield record.$ref;
+        }
+        if (typeof record.externalValue === "string" && !kept.has(record.externalValue))
+            yield record.externalValue;
+        stack.push(...Object.values(record));
+    }
+}
+function absolutize(node, base, ids, keep, kept, seen = new Set()) {
+    if (typeof node !== "object" || node === null || seen.has(node))
+        return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+        for (const item of node)
+            absolutize(item, base, ids, keep, kept, seen);
+        return;
+    }
+    const record = node;
+    let next = base;
+    if (typeof record.$id === "string") {
+        next = resolveAgainst(base, record.$id);
+        ids.set(stripHash(next), record);
+    }
+    if (typeof record.$ref === "string" && !record.$ref.startsWith("#")) {
+        if (keep(record.$ref))
+            kept.add(record.$ref);
+        else
+            record.$ref = resolveAgainst(base, record.$ref);
+    }
+    const discriminator = record.discriminator;
+    const mapping = Predicate.isObject(discriminator) && Predicate.isObject(discriminator.mapping)
+        ? discriminator.mapping
+        : undefined;
+    if (mapping) {
+        for (const [key, value] of Object.entries(mapping)) {
+            if (typeof value !== "string" || value.startsWith("#"))
+                continue;
+            if (keep(value))
+                kept.add(value);
+            else
+                mapping[key] = resolveAgainst(base, value);
+        }
+    }
+    if (typeof record.externalValue === "string") {
+        if (keep(record.externalValue))
+            kept.add(record.externalValue);
+        else
+            record.externalValue = resolveAgainst(base, record.externalValue);
+    }
+    for (const [key, value] of Object.entries(record)) {
+        if (key === "$ref" || key === "$id")
+            continue;
+        absolutize(value, next, ids, keep, kept, seen);
+    }
+}
+function rewriteIdRefs(root, ids) {
+    const pointers = new Map();
+    for (const [url, node] of ids) {
+        const pointer = findPointer(root, node);
+        if (pointer)
+            pointers.set(url, pointer);
+    }
+    walkRecords(root, (record) => {
+        if (typeof record.$ref !== "string" || record.$ref.startsWith("#"))
+            return;
+        const url = stripHash(record.$ref);
+        const pointer = pointers.get(url);
+        if (!pointer)
+            return;
+        const hash = getHash(record.$ref);
+        if (hash === "#") {
+            record.$ref = pointer;
+            return;
+        }
+        const tokens = parsePointer(hash, record.$ref);
+        if (tokens[0] === "$defs" && tokens.length === 2)
+            record.$ref = joinPointer("#/$defs", tokens[1]);
+        else
+            record.$ref = joinPointer(pointer, tokens);
+    });
+}
+function rewriteMappings(root, placed, ids) {
+    const idPointers = new Map();
+    for (const [url, node] of ids) {
+        const pointer = findPointer(root, node);
+        if (pointer)
+            idPointers.set(url, pointer);
+    }
+    walkRecords(root, (record) => {
+        const discriminator = record.discriminator;
+        const mapping = Predicate.isObject(discriminator) && Predicate.isObject(discriminator.mapping)
+            ? discriminator.mapping
+            : undefined;
+        if (!mapping)
+            return;
+        for (const [key, value] of Object.entries(mapping)) {
+            if (typeof value !== "string" || value.startsWith("#"))
+                continue;
+            const url = stripHash(value);
+            const hash = getHash(value);
+            const target = placed.get(`${url}${hash}`) ?? idPointers.get(url);
+            if (target)
+                mapping[key] =
+                    hash === "#" || placed.has(`${url}${hash}`)
+                        ? target
+                        : joinPointer(target, parsePointer(hash));
+        }
+    });
+}
+function findPointer(root, target, pointer = "#", seen = new Set()) {
+    if (root === target)
+        return pointer;
+    if (typeof root !== "object" || root === null || seen.has(root))
+        return undefined;
+    seen.add(root);
+    if (Array.isArray(root)) {
+        for (let index = 0; index < root.length; index++) {
+            const found = findPointer(root[index], target, joinPointer(pointer, String(index)), seen);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    for (const [key, value] of Object.entries(root)) {
+        const found = findPointer(value, target, joinPointer(pointer, key), seen);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+function walkRecords(node, visit, seen = new Set()) {
+    if (typeof node !== "object" || node === null || seen.has(node))
+        return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+        for (const item of node)
+            walkRecords(item, visit, seen);
+        return;
+    }
+    const record = node;
+    visit(record);
+    for (const value of Object.values(record))
+        walkRecords(value, visit, seen);
+}
+const inlineExternalValues = Effect.fnUntraced(function* (root, cache, keep, kept, options, failures, recorded) {
+    const pending = [];
+    walkRecords(root, (record) => {
+        if (typeof record.externalValue === "string" && record.value === undefined)
+            pending.push(record);
+    });
+    yield* Effect.forEach(pending, (record) => Effect.gen(function* () {
+        const externalValue = record.externalValue;
+        if (typeof externalValue !== "string")
+            return;
+        if (kept.has(externalValue) || keep(externalValue))
+            return;
+        const loaded = yield* loadCaught(cache, stripHash(externalValue), options, failures, recorded);
+        if (loaded === undefined)
+            return;
+        const hash = getHash(externalValue);
+        const resolved = yield* Effect.try({
+            try: () => ({ value: hash === "#" ? loaded : valueAt(loaded, hash) }),
+            catch: syncFailure,
+        }).pipe(Effect.catchIf((error) => options.continueOnError === true && isLeafFailure(error), (error) => Ref.update(failures, (list) => [...list, error]).pipe(Effect.asVoid)));
+        if (!resolved)
+            return;
+        record.value = resolved.value;
+        delete record.externalValue;
+    }), { concurrency: loadConcurrency, discard: true });
+});
+function valueAt(document, hash) {
+    const tokens = parsePointer(hash);
+    let current = document;
+    for (const token of tokens) {
+        if (typeof current !== "object" || current === null || !Object.hasOwn(current, token)) {
+            throw missingPointerFailure(token, hash);
+        }
+        current = current[token];
+    }
+    return current;
+}

package/dist/schemas/3.1/callback.d.ts

@@ -0,0 +1,205 @@
+import { Schema } from "effect";
+export declare const OpenApiCallback: Schema.StructWithRest<Schema.$Record<Schema.String, Schema.suspend<Schema.Codec<{
+    readonly [x: string]: unknown;
+    readonly $ref?: string | undefined;
+    readonly summary?: string | undefined;
+    readonly description?: string | undefined;
+    readonly get?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly put?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly post?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly delete?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly options?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly head?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly patch?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly trace?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly servers?: readonly {
+        readonly [x: string]: unknown;
+        readonly url: string;
+        readonly description?: string | undefined;
+        readonly variables?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+                readonly default: string;
+                readonly enum?: readonly [string, ...string[]] | undefined;
+                readonly description?: string | undefined;
+            };
+        } | undefined;
+    }[] | undefined;
+    readonly parameters?: readonly ({
+        readonly [x: string]: unknown;
+        readonly $ref: string;
+        readonly summary?: string | undefined;
+        readonly description?: string | undefined;
+    } | {
+        readonly [x: string]: unknown;
+        readonly description?: string | undefined;
+        readonly required?: boolean | undefined;
+        readonly deprecated?: boolean | undefined;
+        readonly explode?: boolean | undefined;
+        readonly schema?: boolean | {
+            readonly [x: string]: unknown;
+        } | undefined;
+        readonly content?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+                readonly schema?: boolean | {
+                    readonly [x: string]: unknown;
+                } | undefined;
+                readonly example?: unknown;
+                readonly examples?: {
+                    readonly [x: string]: {
+                        readonly [x: string]: unknown;
+                        readonly summary?: string | undefined;
+                        readonly description?: string | undefined;
+                        readonly value?: unknown;
+                        readonly externalValue?: string | undefined;
+                    } | {
+                        readonly [x: string]: unknown;
+                        readonly $ref: string;
+                        readonly summary?: string | undefined;
+                        readonly description?: string | undefined;
+                    };
+                } | undefined;
+                readonly encoding?: {
+                    readonly [x: string]: {
+                        readonly [x: string]: unknown;
+                        readonly contentType?: string | undefined;
+                        readonly headers?: {
+                            readonly [x: string]: import("./header.ts").OpenApiHeader | {
+                                readonly [x: string]: unknown;
+                                readonly $ref: string;
+                                readonly summary?: string | undefined;
+                                readonly description?: string | undefined;
+                            };
+                        } | undefined;
+                        readonly style?: "deepObject" | "form" | "pipeDelimited" | "spaceDelimited" | undefined;
+                        readonly explode?: boolean | undefined;
+                        readonly allowReserved?: boolean | undefined;
+                    };
+                } | undefined;
+            };
+        } | undefined;
+        readonly example?: unknown;
+        readonly examples?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+                readonly summary?: string | undefined;
+                readonly description?: string | undefined;
+                readonly value?: unknown;
+                readonly externalValue?: string | undefined;
+            } | {
+                readonly [x: string]: unknown;
+                readonly $ref: string;
+                readonly summary?: string | undefined;
+                readonly description?: string | undefined;
+            };
+        } | undefined;
+        readonly name: string;
+        readonly in: "cookie" | "header" | "path" | "query";
+        readonly style?: "deepObject" | "form" | "label" | "matrix" | "pipeDelimited" | "simple" | "spaceDelimited" | undefined;
+        readonly allowEmptyValue?: boolean | undefined;
+        readonly allowReserved?: boolean | undefined;
+    })[] | undefined;
+}, {
+    readonly [x: string]: unknown;
+    readonly $ref?: string | undefined;
+    readonly summary?: string | undefined;
+    readonly description?: string | undefined;
+    readonly get?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly put?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly post?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly delete?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly options?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly head?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly patch?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly trace?: import("./operation.ts").OpenApiOperation | undefined;
+    readonly servers?: readonly {
+        readonly [x: string]: unknown;
+        readonly url: string;
+        readonly description?: string | undefined;
+        readonly variables?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+                readonly default: string;
+                readonly enum?: readonly [string, ...string[]] | undefined;
+                readonly description?: string | undefined;
+            };
+        } | undefined;
+    }[] | undefined;
+    readonly parameters?: readonly ({
+        readonly [x: string]: unknown;
+        readonly $ref: string;
+        readonly summary?: string | undefined;
+        readonly description?: string | undefined;
+    } | {
+        readonly [x: string]: unknown;
+        readonly description?: string | undefined;
+        readonly required?: boolean | undefined;
+        readonly deprecated?: boolean | undefined;
+        readonly explode?: boolean | undefined;
+        readonly schema?: boolean | {
+            readonly [x: string]: unknown;
+        } | undefined;
+        readonly content?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+                readonly schema?: boolean | {
+                    readonly [x: string]: unknown;
+                } | undefined;
+                readonly example?: unknown;
+                readonly examples?: {
+                    readonly [x: string]: {
+                        readonly [x: string]: unknown;
+                        readonly summary?: string | undefined;
+                        readonly description?: string | undefined;
+                        readonly value?: unknown;
+                        readonly externalValue?: string | undefined;
+                    } | {
+                        readonly [x: string]: unknown;
+                        readonly $ref: string;
+                        readonly summary?: string | undefined;
+                        readonly description?: string | undefined;
+                    };
+                } | undefined;
+                readonly encoding?: {
+                    readonly [x: string]: {
+                        readonly [x: string]: unknown;
+                        readonly contentType?: string | undefined;
+                        readonly headers?: {
+                            readonly [x: string]: import("./header.ts").OpenApiHeader | {
+                                readonly [x: string]: unknown;
+                                readonly $ref: string;
+                                readonly summary?: string | undefined;
+                                readonly description?: string | undefined;
+                            };
+                        } | undefined;
+                        readonly style?: "deepObject" | "form" | "pipeDelimited" | "spaceDelimited" | undefined;
+                        readonly explode?: boolean | undefined;
+                        readonly allowReserved?: boolean | undefined;
+                    };
+                } | undefined;
+            };
+        } | undefined;
+        readonly example?: unknown;
+        readonly examples?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+                readonly summary?: string | undefined;
+                readonly description?: string | undefined;
+                readonly value?: unknown;
+                readonly externalValue?: string | undefined;
+            } | {
+                readonly [x: string]: unknown;
+                readonly $ref: string;
+                readonly summary?: string | undefined;
+                readonly description?: string | undefined;
+            };
+        } | undefined;
+        readonly name: string;
+        readonly in: "cookie" | "header" | "path" | "query";
+        readonly style?: "deepObject" | "form" | "label" | "matrix" | "pipeDelimited" | "simple" | "spaceDelimited" | undefined;
+        readonly allowEmptyValue?: boolean | undefined;
+        readonly allowReserved?: boolean | undefined;
+    })[] | undefined;
+}, never, never>>>, readonly [Schema.$Record<Schema.String, Schema.Unknown>]>;
+export type OpenApiCallback = typeof OpenApiCallback.Type;

package/dist/schemas/3.1/callback.js

@@ -0,0 +1,4 @@
+import { Schema } from "effect";
+import { openApiMap } from "./object.js";
+import { OpenApiPathItem } from "./path-item.js";
+export const OpenApiCallback = openApiMap(Schema.String.check(Schema.makeFilter((key) => !key.startsWith("x-"))), Schema.suspend(() => OpenApiPathItem));