@shipworthy/openapi-parser 0.0.0-stage → 0.0.1

package/dist/codec.js

@@ -0,0 +1,42 @@
+import { Effect, Schema, SchemaGetter, SchemaIssue, SchemaTransformation } from "effect";
+import { decodeDocument } from "./document.js";
+import { parseText } from "./parsers.js";
+import { runEffect } from "./run.js";
+import { ParsedOpenApi } from "./schemas/3.1/document.js";
+const parseOptions = Schema.Struct({
+    sourceUrl: Schema.Union([Schema.String, Schema.URL]),
+});
+const sourceDocument = Schema.StructWithRest(Schema.Struct({
+    ...ParsedOpenApi.schema.fields,
+    openapi: Schema.String.check(Schema.isPattern(/^3\.[01]\.\d+(?:[-+].*)?$/)),
+}), ParsedOpenApi.records);
+function prepareDocumentTransformation(options) {
+    // oxlint-disable-next-line effecttsgo/schema-sync -- The public synchronous codec factory validates options before returning a Schema.
+    const { sourceUrl } = Schema.decodeSync(parseOptions)(options);
+    const source = sourceUrl instanceof URL ? sourceUrl.href : sourceUrl;
+    return SchemaTransformation.makeTransformation({
+        decode: SchemaGetter.transformEffect(Effect.fnUntraced(function* (input, options) {
+            const document = yield* Effect.fromResult(decodeDocument(input)).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, input, options)));
+            // Check the source before the bundler can normalize or remove malformed fields.
+            const checked = yield* Schema.decodeUnknownEffect(sourceDocument)(document, options).pipe(Effect.mapError((error) => error.issue));
+            const result = yield* runEffect({ path: source, schema: checked }).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({
+                message: "source" in error ? `${error.source}: ${error.message}` : error.message,
+            }, input, options)));
+            return result.schema;
+        })),
+        encode: SchemaGetter.passthrough(),
+    });
+}
+/** Object input shares the preparation path without a JSON stringify/parse round trip. */
+export function ParsedOpenApiFromDocument(options) {
+    return Schema.Unknown.pipe(Schema.decodeTo(Schema.Unknown, prepareDocumentTransformation(options)), Schema.decodeTo(ParsedOpenApi));
+}
+const documentTransformation = SchemaTransformation.transformEffect({
+    decode: (source, options) => parseText(source).pipe(Effect.mapError((error) => new SchemaIssue.InvalidValue({ message: error.message }, source, options))),
+    encode: (document, options) => Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown, { space: 2 }))(document, options).pipe(Effect.mapError((error) => error.issue)),
+});
+/** Parse JSON/YAML, bundle external references, upgrade 3.0 to 3.1, and validate the document. */
+export function ParsedOpenApiFromString(options) {
+    const transformation = SchemaTransformation.composeTransformation(documentTransformation, prepareDocumentTransformation(options));
+    return Schema.String.pipe(Schema.decodeTo(Schema.Unknown, transformation), Schema.decodeTo(ParsedOpenApi));
+}

package/dist/document.d.ts

@@ -0,0 +1,9 @@
+import { Result, Schema } from "effect";
+import { UnsupportedVersion } from "./errors.ts";
+/** An OpenAPI document: its `openapi` version, with every other field unchecked. */
+export declare const OpenAPIDocument: Schema.StructWithRest<Schema.Struct<{
+    readonly openapi: Schema.String;
+}>, readonly [Schema.$Record<Schema.String, Schema.Unknown>]>;
+export type OpenAPIDocument = typeof OpenAPIDocument.Type;
+/** An OpenAPI 3.x document, as loaded and before bundling. */
+export declare function decodeDocument(document: unknown): Result.Result<OpenAPIDocument, UnsupportedVersion>;

package/dist/document.js

@@ -0,0 +1,28 @@
+import { Predicate, Result, Schema } from "effect";
+import { UnsupportedVersion } from "./errors.js";
+/** An OpenAPI document: its `openapi` version, with every other field unchecked. */
+export const OpenAPIDocument = Schema.StructWithRest(Schema.Struct({ openapi: Schema.String }), [
+    Schema.Record(Schema.String, Schema.Unknown),
+]);
+const unsupportedFormat = "Unsupported schema format, expected `openapi: 3.x`";
+/** Rejects anything but OpenAPI 3.x, with the messages users see. */
+const openApi3 = Schema.Unknown.check(Schema.makeFilter((document) => {
+    if (!Predicate.isObject(document))
+        return unsupportedFormat;
+    if (document.swagger)
+        return "Unsupported Swagger version: 2.x. Use OpenAPI 3.x instead.";
+    const openapi = document.openapi;
+    if (typeof openapi !== "string" || openapi.length === 0)
+        return unsupportedFormat;
+    const version = Number.parseFloat(openapi);
+    if (Number.isNaN(version) || version < 3 || version >= 4) {
+        return `Unsupported OpenAPI version: ${openapi}`;
+    }
+    return undefined;
+}));
+const decodeVersion = Schema.decodeUnknownResult(openApi3);
+const decodeEnvelope = Schema.decodeUnknownResult(OpenAPIDocument);
+/** An OpenAPI 3.x document, as loaded and before bundling. */
+export function decodeDocument(document) {
+    return decodeVersion(document).pipe(Result.flatMap(decodeEnvelope), Result.mapError((issue) => new UnsupportedVersion({ message: issue.message })));
+}

package/dist/errors.d.ts

@@ -0,0 +1,105 @@
+import { Schema } from "effect";
+declare const ParserFailure_base: Schema.Class<ParserFailure, Schema.TaggedStruct<"ParserFailure", {
+    readonly message: Schema.String;
+    readonly source: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class ParserFailure extends ParserFailure_base {
+}
+declare const ResolverFailure_base: Schema.Class<ResolverFailure, Schema.TaggedStruct<"ResolverFailure", {
+    readonly message: Schema.String;
+    readonly source: Schema.String;
+    readonly ioErrorCode: Schema.optionalKey<Schema.String>;
+    readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class ResolverFailure extends ResolverFailure_base {
+}
+declare const UnmatchedParserFailure_base: Schema.Class<UnmatchedParserFailure, Schema.TaggedStruct<"UnmatchedParserFailure", {
+    message: Schema.String;
+    source: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UnmatchedParserFailure extends UnmatchedParserFailure_base {
+}
+declare const UnmatchedResolverFailure_base: Schema.Class<UnmatchedResolverFailure, Schema.TaggedStruct<"UnmatchedResolverFailure", {
+    message: Schema.String;
+    source: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UnmatchedResolverFailure extends UnmatchedResolverFailure_base {
+}
+declare const MissingPointerFailure_base: Schema.Class<MissingPointerFailure, Schema.TaggedStruct<"MissingPointerFailure", {
+    readonly message: Schema.String;
+    readonly source: Schema.String;
+    readonly token: Schema.String;
+    readonly targetRef: Schema.String;
+    readonly targetFound: Schema.String;
+    readonly parentPath: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class MissingPointerFailure extends MissingPointerFailure_base {
+}
+declare const InvalidPointerFailure_base: Schema.Class<InvalidPointerFailure, Schema.TaggedStruct<"InvalidPointerFailure", {
+    readonly message: Schema.String;
+    readonly source: Schema.String;
+    readonly pointer: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class InvalidPointerFailure extends InvalidPointerFailure_base {
+}
+declare const CircularAliasFailure_base: Schema.Class<CircularAliasFailure, Schema.TaggedStruct<"CircularAliasFailure", {
+    readonly message: Schema.String;
+    readonly definition: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class CircularAliasFailure extends CircularAliasFailure_base {
+}
+declare const BundleFailure_base: Schema.Class<BundleFailure, Schema.TaggedStruct<"BundleFailure", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class BundleFailure extends BundleFailure_base {
+}
+declare const TimeoutFailure_base: Schema.Class<TimeoutFailure, Schema.TaggedStruct<"TimeoutFailure", {
+    readonly message: Schema.String;
+    readonly timeout: Schema.Finite;
+}>, import("effect/Cause").YieldableError>;
+export declare class TimeoutFailure extends TimeoutFailure_base {
+}
+declare const leafFailure: Schema.Union<readonly [typeof ParserFailure, typeof ResolverFailure, typeof UnmatchedParserFailure, typeof UnmatchedResolverFailure, typeof MissingPointerFailure, typeof InvalidPointerFailure, typeof CircularAliasFailure, typeof BundleFailure, typeof TimeoutFailure]>;
+declare const GroupFailure_base: Schema.Class<GroupFailure, Schema.TaggedStruct<"GroupFailure", {
+    readonly source: Schema.String;
+    readonly message: Schema.String;
+    readonly errors: Schema.$Array<Schema.Union<readonly [typeof ParserFailure, typeof ResolverFailure, typeof UnmatchedParserFailure, typeof UnmatchedResolverFailure, typeof MissingPointerFailure, typeof InvalidPointerFailure, typeof CircularAliasFailure, typeof BundleFailure, typeof TimeoutFailure]>>;
+}>, import("effect/Cause").YieldableError>;
+export declare class GroupFailure extends GroupFailure_base {
+}
+export type LeafFailure = typeof leafFailure.Type;
+export type TaggedFailure = LeafFailure | GroupFailure;
+export declare const isTaggedFailure: <I>(input: I) => input is I & (BundleFailure | CircularAliasFailure | GroupFailure | InvalidPointerFailure | MissingPointerFailure | ParserFailure | ResolverFailure | TimeoutFailure | UnmatchedParserFailure | UnmatchedResolverFailure);
+export declare function isLeafFailure(cause: TaggedFailure): cause is LeafFailure;
+export declare function nodeErrorCode(cause: unknown): string | undefined;
+export declare function missingPointerFailure(token: string, source: string, targetRef?: string, targetFound?: string, parentPath?: string): MissingPointerFailure;
+export declare function invalidPointerFailure(pointer: string, source?: string): InvalidPointerFailure;
+export declare function circularAliasFailure(definition: string): CircularAliasFailure;
+export declare function bundleFailure(message: string): BundleFailure;
+export declare function timeoutFailure(timeout: number): TimeoutFailure;
+export declare function groupFailure(source: string, errors: ReadonlyArray<LeafFailure>): GroupFailure;
+export declare function syncFailure(cause: unknown): TaggedFailure;
+declare const EmptySource_base: Schema.Class<EmptySource, Schema.TaggedStruct<"EmptySource", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class EmptySource extends EmptySource_base {
+}
+declare const InvalidSource_base: Schema.Class<InvalidSource, Schema.TaggedStruct<"InvalidSource", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class InvalidSource extends InvalidSource_base {
+}
+declare const UnsupportedVersion_base: Schema.Class<UnsupportedVersion, Schema.TaggedStruct<"UnsupportedVersion", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UnsupportedVersion extends UnsupportedVersion_base {
+}
+declare const ParseError_base: Schema.Class<ParseError, Schema.TaggedStruct<"ParseError", {
+    readonly message: Schema.String;
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+export declare class ParseError extends ParseError_base {
+}
+export type LoadError = EmptySource | InvalidSource | UnsupportedVersion | ParseError;
+export {};

package/dist/errors.js

@@ -0,0 +1,162 @@
+import { Schema } from "effect";
+const failureFields = {
+    message: Schema.String,
+    source: Schema.String,
+};
+export class ParserFailure extends Schema.TaggedError()("ParserFailure", {
+    ...failureFields,
+    cause: Schema.optionalKey(Schema.Defect()),
+}) {
+}
+export class ResolverFailure extends Schema.TaggedError()("ResolverFailure", {
+    ...failureFields,
+    ioErrorCode: Schema.optionalKey(Schema.String),
+    cause: Schema.optionalKey(Schema.Defect()),
+}) {
+}
+export class UnmatchedParserFailure extends Schema.TaggedError()("UnmatchedParserFailure", failureFields) {
+}
+export class UnmatchedResolverFailure extends Schema.TaggedError()("UnmatchedResolverFailure", failureFields) {
+}
+export class MissingPointerFailure extends Schema.TaggedError()("MissingPointerFailure", {
+    ...failureFields,
+    token: Schema.String,
+    targetRef: Schema.String,
+    targetFound: Schema.String,
+    parentPath: Schema.String,
+}) {
+}
+export class InvalidPointerFailure extends Schema.TaggedError()("InvalidPointerFailure", {
+    ...failureFields,
+    pointer: Schema.String,
+}) {
+}
+export class CircularAliasFailure extends Schema.TaggedError()("CircularAliasFailure", {
+    message: Schema.String,
+    definition: Schema.String,
+}) {
+}
+export class BundleFailure extends Schema.TaggedError()("BundleFailure", {
+    message: Schema.String,
+}) {
+}
+export class TimeoutFailure extends Schema.TaggedError()("TimeoutFailure", {
+    message: Schema.String,
+    timeout: Schema.Finite,
+}) {
+}
+const leafFailure = Schema.Union([
+    ParserFailure,
+    ResolverFailure,
+    UnmatchedParserFailure,
+    UnmatchedResolverFailure,
+    MissingPointerFailure,
+    InvalidPointerFailure,
+    CircularAliasFailure,
+    BundleFailure,
+    TimeoutFailure,
+]);
+export class GroupFailure extends Schema.TaggedError()("GroupFailure", {
+    source: Schema.String,
+    message: Schema.String,
+    errors: Schema.Array(leafFailure),
+}) {
+}
+const taggedFailures = [
+    ParserFailure,
+    ResolverFailure,
+    UnmatchedParserFailure,
+    UnmatchedResolverFailure,
+    MissingPointerFailure,
+    InvalidPointerFailure,
+    CircularAliasFailure,
+    BundleFailure,
+    TimeoutFailure,
+    GroupFailure,
+];
+export const isTaggedFailure = Schema.is(Schema.Union(taggedFailures));
+export function isLeafFailure(cause) {
+    return cause._tag !== "GroupFailure";
+}
+export function nodeErrorCode(cause) {
+    const code = errorCode(cause);
+    if (code)
+        return code;
+    if (typeof cause === "object" && cause !== null && "cause" in cause)
+        return errorCode(cause.cause);
+    return undefined;
+}
+function errorCode(cause) {
+    if (typeof cause !== "object" || cause === null || !("code" in cause))
+        return undefined;
+    const { code } = cause;
+    if (typeof code === "string")
+        return code.length > 0 ? code : undefined;
+    if (typeof code === "number" && Number.isFinite(code))
+        return String(code);
+    return undefined;
+}
+export function missingPointerFailure(token, source, targetRef = "", targetFound = "", parentPath = "") {
+    const hash = source.includes("#") ? source.slice(source.indexOf("#")) : source;
+    return new MissingPointerFailure({
+        message: `Missing $ref pointer "${hash}". Token "${token}" does not exist.`,
+        source,
+        token,
+        targetRef,
+        targetFound,
+        parentPath,
+    });
+}
+export function invalidPointerFailure(pointer, source = pointer) {
+    return new InvalidPointerFailure({
+        message: `Invalid $ref pointer "${pointer}". Pointers must begin with "#/"`,
+        source,
+        pointer,
+    });
+}
+export function circularAliasFailure(definition) {
+    return new CircularAliasFailure({
+        message: `Definition ${JSON.stringify(definition)} is a circular alias.`,
+        definition,
+    });
+}
+export function bundleFailure(message) {
+    return new BundleFailure({ message });
+}
+export function timeoutFailure(timeout) {
+    return new TimeoutFailure({
+        message: `Dereferencing timeout reached: ${timeout}ms`,
+        timeout,
+    });
+}
+export function groupFailure(source, errors) {
+    return new GroupFailure({
+        source,
+        message: `${errors.length} error${errors.length === 1 ? "" : "s"} occurred while reading '${source}'`,
+        errors: [...errors],
+    });
+}
+export function syncFailure(cause) {
+    if (isTaggedFailure(cause))
+        return cause;
+    return new BundleFailure({
+        message: cause instanceof Error ? cause.message : String(cause),
+    });
+}
+export class EmptySource extends Schema.TaggedError()("EmptySource", {
+    message: Schema.String,
+}) {
+}
+export class InvalidSource extends Schema.TaggedError()("InvalidSource", {
+    message: Schema.String,
+}) {
+}
+export class UnsupportedVersion extends Schema.TaggedError()("UnsupportedVersion", {
+    message: Schema.String,
+}) {
+}
+export class ParseError extends Schema.TaggedError()("ParseError", {
+    message: Schema.String,
+    cause: Schema.Defect(),
+}) {
+}

package/dist/hoist.d.ts

@@ -0,0 +1,10 @@
+import type { BundleHooks } from "./plugins.ts";
+export interface ExternalRef {
+    parent: Record<string, unknown>;
+    key: string;
+    ref: string;
+    pointer: string;
+}
+export declare function findExternalRef(root: unknown, keep: (ref: string) => boolean, abandoned?: ReadonlySet<string>): ExternalRef | undefined;
+export declare function hoistExternalRefs(root: Record<string, unknown>, readValue: (ref: string) => unknown, hooks: BundleHooks | undefined, keep: (ref: string) => boolean): Map<string, string>;
+export declare function oas3DefaultRoot(pathFromRoot: string): string | null;