@shipworthy/openapi-parser 0.0.0-stage → 0.0.1

package/dist/load.js

@@ -0,0 +1,128 @@
+// oxlint-disable-next-line effecttsgo/node-builtin-import -- Detect the public Node Readable input before adapting it with NodeStream.
+import { Readable } from "node:stream";
+import * as NodeStream from "@effect/platform-node/NodeStream";
+import { Effect, Path, Predicate, Schema, Stream } from "effect";
+import { decodeDocument } from "./document.js";
+import { EmptySource, InvalidSource, ParseError } from "./errors.js";
+import { loadDocument as loadResolvedDocument, makeContext } from "./loader.js";
+import { parseText } from "./parsers.js";
+const loadOptions = Schema.Struct({
+    cwd: Schema.optional(Schema.Union([Schema.String, Schema.URL])),
+});
+const emptyPath = "Empty schema. Please specify a URL or file path";
+const emptySchema = "Can’t parse empty schema";
+export const loadDocument = Effect.fn("loadDocument")(function* (source, options) {
+    const decoded = yield* Schema.decodeEffect(loadOptions)(options ?? {}).pipe(Effect.mapError(parseFailure));
+    const path = yield* Path.Path;
+    const cwd = yield* resolveCwd(path, decoded.cwd);
+    if (source == null || source === "")
+        return yield* new EmptySource({ message: emptyPath });
+    const loaded = yield* parseSource(source, cwd);
+    const document = yield* Effect.fromResult(decodeDocument(loaded.document));
+    return { ...loaded, document };
+});
+const parseSource = Effect.fnUntraced(function* (source, absoluteRef) {
+    if (source == null || source === "")
+        return yield* new EmptySource({ message: emptySchema });
+    if (source instanceof URL) {
+        const ref = source.protocol === "file:" ? yield* filePath(source) : source.href;
+        const parsed = yield* loadResolvedDocument(source.href, makeContext(source.href, {}, "root")).pipe(Effect.mapError(parseFailure));
+        const document = yield* requireDocument(parsed);
+        return { document, absoluteRef: ref };
+    }
+    if (source instanceof Readable) {
+        const contents = yield* readReadable(source);
+        return yield* parseSource(contents, absoluteRef);
+    }
+    if (source instanceof Buffer)
+        return yield* parseSource(source.toString("utf8"), absoluteRef);
+    if (typeof source === "string") {
+        if (source.startsWith("http://") ||
+            source.startsWith("https://") ||
+            source.startsWith("file://")) {
+            const url = yield* Effect.try({
+                try: () => new URL(source),
+                catch: (cause) => new InvalidSource({
+                    message: Predicate.isError(cause) ? cause.message : `Expected a valid URL`,
+                }),
+            });
+            return yield* parseSource(url, absoluteRef);
+        }
+        if (isFilePath(source, yield* Path.Path))
+            return yield* parseSource(yield* fileUrl(source, absoluteRef), absoluteRef);
+        const parsed = yield* parseText(source);
+        const document = yield* requireDocument(parsed);
+        return { document, absoluteRef };
+    }
+    const document = yield* Schema.decodeUnknownEffect(documentObject)(source).pipe(Effect.mapError(() => new InvalidSource({
+        message: `Expected string, object, or Buffer. Got ${valueKind(source)}`,
+    })));
+    return { document, absoluteRef };
+});
+/**
+ * A single-line string is a filesystem path when it is platform-absolute or starts with
+ * `./`, `../`, `.\`, or `..\`. Otherwise, it needs a `.json`, `.yaml`, or `.yml` extension,
+ * no `: `, and no leading `{` or `[`. No inline OpenAPI document
+ * matches: one-line YAML needs `key: value` or `{...}`, and JSON starts with `{`.
+ */
+function isFilePath(source, path) {
+    const value = source.trim();
+    if (value === "" || /[\r\n]/.test(value))
+        return false;
+    if (path.isAbsolute(value) ||
+        value.startsWith("./") ||
+        value.startsWith("../") ||
+        value.startsWith(".\\") ||
+        value.startsWith("..\\"))
+        return true;
+    return ([".json", ".yaml", ".yml"].includes(path.extname(value).toLowerCase()) &&
+        !value.includes(": ") &&
+        !value.startsWith("{") &&
+        !value.startsWith("["));
+}
+/** Resolve a path string against the `cwd` directory URL. */
+const fileUrl = Effect.fnUntraced(function* (source, cwd) {
+    const path = yield* Path.Path;
+    const value = source.trim();
+    if (!path.isAbsolute(value) && !cwd.startsWith("file:")) {
+        return yield* Effect.try({ try: () => new URL(value, cwd), catch: parseFailure });
+    }
+    const directory = path.isAbsolute(value) ? "" : yield* filePath(new URL(cwd));
+    return yield* path.toFileUrl(path.resolve(directory, value)).pipe(Effect.mapError(parseFailure));
+});
+const resolveCwd = Effect.fnUntraced(function* (path, cwd) {
+    if (cwd instanceof URL) {
+        return cwd.href;
+    }
+    const directory = typeof cwd === "string" ? path.resolve(cwd) : path.resolve(".");
+    return yield* path.toFileUrl(directory).pipe(Effect.map((url) => (url.href.endsWith("/") ? url.href : `${url.href}/`)), Effect.mapError(parseFailure));
+});
+const filePath = Effect.fnUntraced(function* (url) {
+    const path = yield* Path.Path;
+    return yield* path.fromFileUrl(url).pipe(Effect.mapError(parseFailure));
+});
+const readReadable = Effect.fnUntraced(function* (source) {
+    return yield* NodeStream.fromReadable({
+        evaluate: () => source,
+        onError: parseFailure,
+    }).pipe(Stream.decodeText, Stream.mkString, Effect.map((text) => text.trim()));
+});
+const documentObject = Schema.Record(Schema.String, Schema.Unknown);
+const requireDocument = Effect.fnUntraced(function* (value) {
+    return yield* Schema.decodeUnknownEffect(documentObject)(value).pipe(Effect.mapError(() => new InvalidSource({
+        message: `Expected an OpenAPI document object. Got ${valueKind(value)}`,
+    })));
+});
+function parseFailure(cause) {
+    return new ParseError({
+        message: Predicate.isError(cause) ? cause.message : String(cause),
+        cause,
+    });
+}
+function valueKind(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "Array";
+    return typeof value;
+}

package/dist/loader.d.ts

@@ -0,0 +1,11 @@
+import { Effect, FileSystem } from "effect";
+import type { HttpClient } from "effect/http";
+import { type TaggedFailure } from "./errors.ts";
+import type { EffectPlugin, Options } from "./plugins.ts";
+export interface LoadContext {
+    policy: "root" | "reference";
+    resolvers: EffectPlugin<Uint8Array>[];
+    parsers: EffectPlugin<unknown>[];
+}
+export declare function makeContext(rootUrl: string, options: Options, policy?: LoadContext["policy"]): LoadContext;
+export declare const loadDocument: (url: string, context: LoadContext) => Effect.Effect<unknown, TaggedFailure, FileSystem.FileSystem | HttpClient.HttpClient>;

package/dist/loader.js

@@ -0,0 +1,89 @@
+import { Effect, FileSystem } from "effect";
+import { ParserFailure, ResolverFailure, UnmatchedParserFailure, UnmatchedResolverFailure, nodeErrorCode, } from "./errors.js";
+import { httpResolver } from "./http.js";
+import { parserPlugins, parseText } from "./parsers.js";
+import { promisePlugin } from "./plugins.js";
+import { extensionOf, isFileSystemPath, stripHash, toFileSystemPath } from "./url.js";
+export function makeContext(rootUrl, options, policy = "reference") {
+    return {
+        policy,
+        resolvers: resolversFor(rootUrl, options, policy),
+        parsers: parserPlugins(options),
+    };
+}
+export const loadDocument = Effect.fnUntraced(function* (url, context) {
+    const file = fileInfo(url);
+    const resolvers = context.resolvers.filter((plugin) => plugin.can(file));
+    if (resolvers.length === 0) {
+        return yield* new UnmatchedResolverFailure({
+            message: `Could not find resolver for "${url}"`,
+            source: url,
+        });
+    }
+    const bytes = yield* Effect.firstSuccessOf(resolvers.map((plugin) => plugin.run(file)));
+    if (context.policy === "root") {
+        return yield* parseText(bytes).pipe(Effect.mapError((cause) => new ParserFailure({ message: cause.message, source: url, cause })));
+    }
+    const parsedFile = { ...file, data: bytes };
+    const parsers = context.parsers.filter((plugin) => plugin.can(parsedFile));
+    const selected = parsers.length > 0 ? parsers : context.parsers;
+    if (selected.length === 0) {
+        return yield* new UnmatchedParserFailure({
+            message: `Could not find parser for "${url}"`,
+            source: url,
+        });
+    }
+    const parsed = yield* Effect.firstSuccessOf(selected.map((plugin) => plugin.run(parsedFile)));
+    return parsed;
+});
+function resolversFor(rootUrl, options, policy) {
+    const plugins = [];
+    if (options.resolve?.file !== false)
+        plugins.push(fileResolver());
+    const http = httpResolver(rootUrl, options, policy);
+    if (http)
+        plugins.push(http);
+    for (const [index, plugin] of (options.resolvers ?? []).entries())
+        plugins.push(customResolver(plugin, index));
+    return plugins.sort((left, right) => left.order - right.order);
+}
+const readResolvedFile = Effect.fnUntraced(function* (file) {
+    const fs = yield* FileSystem.FileSystem;
+    let filePath = toFileSystemPath(file.url);
+    if (filePath.endsWith("/") || filePath.endsWith("\\"))
+        filePath = filePath.slice(0, -1);
+    return yield* fs.readFile(filePath).pipe(Effect.mapError((error) => new ResolverFailure({
+        message: `Error opening file ${filePath}: ${error.message}`,
+        source: filePath,
+        cause: error,
+        ...ioCode(error),
+    })));
+});
+function fileResolver() {
+    return {
+        order: 100,
+        can: (file) => isFileSystemPath(file.url),
+        run: readResolvedFile,
+    };
+}
+function customResolver(plugin, index) {
+    const wrapped = promisePlugin(plugin.order ?? 300 + index, (file) => plugin.canRead(file), (file) => plugin.read(file), (cause, file) => new ResolverFailure({
+        message: cause instanceof Error ? cause.message : `Error reading file "${file.url}"`,
+        source: file.url,
+        cause,
+        ...ioCode(cause),
+    }));
+    return {
+        ...wrapped,
+        run: (file) => wrapped
+            .run(file)
+            .pipe(Effect.map((data) => (typeof data === "string" ? new TextEncoder().encode(data) : data))),
+    };
+}
+function fileInfo(url) {
+    return { url: stripHash(url), extension: extensionOf(url) };
+}
+function ioCode(cause) {
+    const ioErrorCode = nodeErrorCode(cause);
+    return ioErrorCode ? { ioErrorCode } : undefined;
+}

package/dist/parsers.d.ts

@@ -0,0 +1,5 @@
+import { Effect } from "effect";
+import { ParseError } from "./errors.ts";
+import type { EffectPlugin, Options } from "./plugins.ts";
+export declare const parseText: (source: string | Uint8Array<ArrayBufferLike>) => Effect.Effect<unknown, ParseError, never>;
+export declare function parserPlugins(options: Options): EffectPlugin<unknown>[];

package/dist/parsers.js

@@ -0,0 +1,90 @@
+import { Effect, Predicate } from "effect";
+import { ParseError, ParserFailure } from "./errors.js";
+import { promisePlugin } from "./plugins.js";
+import { extensionOf } from "./url.js";
+import { parseYamlDocument } from "./yaml.js";
+function decodeData(data) {
+    if (data === undefined)
+        return "";
+    const text = typeof data === "string" ? data : new TextDecoder().decode(data);
+    return text.replace(/^\uFEFF/, "");
+}
+function parseJsonText(text) {
+    if (text.trim().length === 0)
+        return null;
+    return JSON.parse(text);
+}
+export const parseText = Effect.fnUntraced(function* (source) {
+    const text = decodeData(source);
+    const first = text.trimStart()[0];
+    const yaml = () => Effect.try({ try: () => parseYamlDocument(text), catch: parseFailure });
+    if (first === "{" || first === "[") {
+        return yield* Effect.try({ try: () => parseJsonText(text), catch: parseFailure }).pipe(Effect.catch(yaml));
+    }
+    return yield* yaml();
+});
+function parseFailure(cause) {
+    return new ParseError({
+        message: Predicate.isError(cause) ? cause.message : String(cause),
+        cause,
+    });
+}
+export function parserPlugins(options) {
+    const plugins = [];
+    if (options.parse?.json !== false)
+        plugins.push(jsonParser());
+    if (options.parse?.yaml !== false)
+        plugins.push(yamlParser());
+    for (const [index, plugin] of (options.parsers ?? []).entries()) {
+        plugins.push(customParser(plugin, index));
+    }
+    return plugins;
+}
+function jsonParser() {
+    return {
+        order: 100,
+        can: (file) => extensionOf(file.url) === ".json" || extensionOf(file.url) === "",
+        run(file) {
+            return Effect.try({
+                try: () => parseJson(file),
+                catch: (cause) => new ParserFailure({
+                    message: cause instanceof Error ? cause.message : "Parser Error",
+                    source: file.url,
+                    cause,
+                }),
+            });
+        },
+    };
+}
+function parseJson(file) {
+    return parseJsonText(decodeData(file.data));
+}
+function yamlParser() {
+    return {
+        order: 200,
+        can: (file) => {
+            const extension = extensionOf(file.url);
+            return (extension === ".yaml" || extension === ".yml" || extension === ".json" || extension === "");
+        },
+        run(file) {
+            return Effect.try({
+                try: () => parseYaml(file),
+                catch: (cause) => new ParserFailure({
+                    message: cause instanceof Error ? cause.message : "Parser Error",
+                    source: file.url,
+                    cause,
+                }),
+            });
+        },
+    };
+}
+function parseYaml(file) {
+    return parseYamlDocument(decodeData(file.data));
+}
+function customParser(plugin, index) {
+    return promisePlugin(plugin.order ?? 300 + index, (file) => plugin.canParse(file), (file) => plugin.parse(file), (cause, file) => new ParserFailure({
+        message: cause instanceof Error ? cause.message : "Parser Error",
+        source: file.url,
+        cause,
+    }));
+}

package/dist/pipeline.d.ts

@@ -0,0 +1,3 @@
+import type { DereferenceHooks } from "./plugins.ts";
+export declare function runSchemaPipeline(document: Record<string, unknown>, mode: "bundle" | "dereference", hooks: DereferenceHooks | undefined): void;
+export declare function inlineRemaining(document: Record<string, unknown>, recursive: Set<string>, hooks: DereferenceHooks | undefined): void;