@effect/openapi-generator 4.0.0-beta.0

package/dist/OpenApiPatch.d.ts

@@ -0,0 +1,296 @@
+/**
+ * OpenAPI spec patching utilities.
+ *
+ * Handles parsing and applying JSON Patch documents (RFC 6902) to OpenAPI
+ * specs. Supports patches from:
+ * - JSON files (.json)
+ * - YAML files (.yaml, .yml)
+ * - Inline JSON strings
+ *
+ * @module OpenApiPatch
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as JsonPatch from "effect/JsonPatch";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+declare const JsonPatchParseError_base: Schema.ErrorClass<unknown, Schema.Struct<{
+    readonly _tag: Schema.tag<"JsonPatchParseError">;
+    readonly source: Schema.String;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Error thrown when parsing a JSON Patch input fails.
+ *
+ * This error occurs when:
+ * - A patch file cannot be read
+ * - JSON or YAML syntax is invalid
+ * - The file format is unsupported
+ *
+ * @example
+ * ```ts
+ * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
+ *
+ * const error = new OpenApiPatch.JsonPatchParseError({
+ *   source: "./patches/fix.json",
+ *   reason: "Unexpected token at position 42"
+ * })
+ *
+ * console.log(error.message)
+ * // "Failed to parse patch from ./patches/fix.json: Unexpected token at position 42"
+ * ```
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export declare class JsonPatchParseError extends JsonPatchParseError_base {
+    get message(): string;
+}
+declare const JsonPatchValidationError_base: Schema.ErrorClass<unknown, Schema.Struct<{
+    readonly _tag: Schema.tag<"JsonPatchValidationError">;
+    readonly source: Schema.String;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Error thrown when a parsed value does not conform to the JSON Patch schema.
+ *
+ * This error occurs when:
+ * - The patch is not an array
+ * - An operation is missing required fields (op, path)
+ * - An operation has an unsupported op value
+ * - An add/replace operation is missing the value field
+ *
+ * @example
+ * ```ts
+ * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
+ *
+ * const error = new OpenApiPatch.JsonPatchValidationError({
+ *   source: "inline",
+ *   reason: "Expected 'add' | 'remove' | 'replace' at [0].op, got 'copy'"
+ * })
+ *
+ * console.log(error.message)
+ * // "Invalid JSON Patch from inline: Expected 'add' | 'remove' | 'replace' at [0].op, got 'copy'"
+ * ```
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export declare class JsonPatchValidationError extends JsonPatchValidationError_base {
+    get message(): string;
+}
+declare const JsonPatchApplicationError_base: Schema.ErrorClass<unknown, Schema.Struct<{
+    readonly _tag: Schema.tag<"JsonPatchApplicationError">;
+    readonly source: Schema.String;
+    readonly operationIndex: Schema.Number;
+    readonly operation: Schema.String;
+    readonly path: Schema.String;
+    readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Error thrown when applying a JSON Patch operation fails.
+ *
+ * This error occurs when:
+ * - A path does not exist for remove/replace operations
+ * - An array index is out of bounds
+ * - The target location is not a valid container
+ *
+ * @example
+ * ```ts
+ * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
+ *
+ * const error = new OpenApiPatch.JsonPatchApplicationError({
+ *   source: "./patches/fix.json",
+ *   operationIndex: 2,
+ *   operation: "remove",
+ *   path: "/paths/~1users",
+ *   reason: "Property \"users\" does not exist"
+ * })
+ *
+ * console.log(error.message)
+ * // "Failed to apply patch from ./patches/fix.json: operation 2 (remove at /paths/~1users): Property \"users\" does not exist"
+ * ```
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export declare class JsonPatchApplicationError extends JsonPatchApplicationError_base {
+    get message(): string;
+}
+declare const JsonPatchAggregateError_base: Schema.ErrorClass<unknown, Schema.Struct<{
+    readonly _tag: Schema.tag<"JsonPatchAggregateError">;
+    readonly errors: Schema.Array$<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Error thrown when multiple JSON Patch operations fail.
+ *
+ * This error aggregates all application errors so users can see every
+ * failing operation at once instead of fixing them one at a time.
+ *
+ * @example
+ * ```ts
+ * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
+ *
+ * const error = new OpenApiPatch.JsonPatchAggregateError({
+ *   errors: [
+ *     new OpenApiPatch.JsonPatchApplicationError({
+ *       source: "./fix.json",
+ *       operationIndex: 0,
+ *       operation: "replace",
+ *       path: "/info/x",
+ *       reason: "Property does not exist"
+ *     }),
+ *     new OpenApiPatch.JsonPatchApplicationError({
+ *       source: "./fix.json",
+ *       operationIndex: 2,
+ *       operation: "remove",
+ *       path: "/paths/~1users",
+ *       reason: "Property does not exist"
+ *     })
+ *   ]
+ * })
+ *
+ * console.log(error.message)
+ * // "2 patch operations failed:\n  1. ..."
+ * ```
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export declare class JsonPatchAggregateError extends JsonPatchAggregateError_base {
+    get message(): string;
+}
+/**
+ * Schema for a JSON Patch "add" operation.
+ *
+ * @since 1.0.0
+ * @category schemas
+ */
+export declare const JsonPatchAdd: Schema.Codec<Extract<JsonPatch.JsonPatchOperation, {
+    op: "add";
+}>>;
+/**
+ * Schema for a JSON Patch "remove" operation.
+ *
+ * @since 1.0.0
+ * @category schemas
+ */
+export declare const JsonPatchRemove: Schema.Codec<Extract<JsonPatch.JsonPatchOperation, {
+    op: "remove";
+}>>;
+/**
+ * Schema for a JSON Patch "replace" operation.
+ *
+ * @since 1.0.0
+ * @category schemas
+ */
+export declare const JsonPatchReplace: Schema.Codec<Extract<JsonPatch.JsonPatchOperation, {
+    op: "replace";
+}>>;
+/**
+ * Schema for a single JSON Patch operation.
+ *
+ * Supports the subset of RFC 6902 operations that Effect's JsonPatch module
+ * implements: `add`, `remove`, and `replace`.
+ *
+ * @since 1.0.0
+ * @category schemas
+ */
+export declare const JsonPatchOperation: Schema.Codec<JsonPatch.JsonPatchOperation>;
+/**
+ * Schema for a JSON Patch document (array of operations).
+ *
+ * A JSON Patch document is an ordered list of operations to apply to a JSON
+ * document. Operations are applied in sequence, with each operation seeing
+ * the result of previous operations.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
+ *
+ * const patch = Schema.decodeUnknownSync(OpenApiPatch.JsonPatchDocument)([
+ *   { op: "add", path: "/foo", value: "bar" },
+ *   { op: "remove", path: "/baz" },
+ *   { op: "replace", path: "/qux", value: 42 }
+ * ])
+ * ```
+ *
+ * @since 1.0.0
+ * @category schemas
+ */
+export declare const JsonPatchDocument: Schema.Array$<Schema.Codec<JsonPatch.JsonPatchOperation, JsonPatch.JsonPatchOperation, never, never>>;
+/**
+ * Type for a JSON Patch document.
+ *
+ * @since 1.0.0
+ * @category types
+ */
+export type JsonPatchDocument = typeof JsonPatchDocument.Type;
+/**
+ * Parse a JSON Patch from either a file path or inline JSON string.
+ *
+ * The input is first checked as a file path. If the file exists, it is read
+ * and parsed based on its extension (.json, .yaml, .yml). Otherwise, the
+ * input is parsed as inline JSON.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
+ *
+ * // From inline JSON
+ * const fromInline = OpenApiPatch.parsePatchInput(
+ *   '[{"op":"replace","path":"/info/title","value":"My API"}]'
+ * )
+ *
+ * // From file path
+ * const fromFile = OpenApiPatch.parsePatchInput("./patches/fix-api.json")
+ *
+ * const program = Effect.gen(function*() {
+ *   const patch = yield* fromInline
+ *   console.log(patch)
+ *   // [{ op: "replace", path: "/info/title", value: "My API" }]
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category parsing
+ */
+export declare const parsePatchInput: (input: string) => Effect.Effect<readonly JsonPatch.JsonPatchOperation[], JsonPatchParseError | JsonPatchValidationError, Path.Path | FileSystem.FileSystem>;
+/**
+ * Apply a sequence of JSON patches to a document.
+ *
+ * Patches are applied in order, with each patch operating on the result of
+ * the previous one. All operations are attempted, and if any fail, the errors
+ * are accumulated and reported together so users can fix all issues at once.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
+ *
+ * const document = { info: { title: "Old Title" }, paths: {} }
+ * const patches = [
+ *   {
+ *     source: "inline",
+ *     patch: [{ op: "replace" as const, path: "/info/title", value: "New Title" }]
+ *   }
+ * ]
+ *
+ * const program = Effect.gen(function*() {
+ *   const result = yield* OpenApiPatch.applyPatches(patches, document)
+ *   console.log(result)
+ *   // { info: { title: "New Title" }, paths: {} }
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category application
+ */
+export declare const applyPatches: (patches: readonly {
+    readonly source: string;
+    readonly patch: JsonPatchDocument;
+}[], document: Schema.Json) => Effect.Effect<Schema.Json, JsonPatchAggregateError, never>;
+export {};
+//# sourceMappingURL=OpenApiPatch.d.ts.map

package/dist/OpenApiPatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApiPatch.d.ts","sourceRoot":"","sources":["../src/OpenApiPatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAA;AAE/C,OAAO,KAAK,SAAS,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AAEnC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;;;;;;AAOvC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,mBAAoB,SAAQ,wBAIvC;IACA,IAAa,OAAO,WAEnB;CACF;;;;;;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,wBAAyB,SAAQ,6BAI5C;IACA,IAAa,OAAO,WAEnB;CACF;;;;;;;;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,yBAA0B,SAAQ,8BAO7C;IACA,IAAa,OAAO,WAGnB;CACF;;;;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,uBAAwB,SAAQ,4BAG3C;IACA,IAAa,OAAO,WAQnB;CACF;AAMD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,KAAK,CACrC,OAAO,CACL,SAAS,CAAC,kBAAkB,EAC5B;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CACd,CAMD,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,KAAK,CACxC,OAAO,CACL,SAAS,CAAC,kBAAkB,EAC5B;IAAE,EAAE,EAAE,QAAQ,CAAA;CAAE,CACjB,CAKD,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,KAAK,CACzC,OAAO,CACL,SAAS,CAAC,kBAAkB,EAC5B;IAAE,EAAE,EAAE,SAAS,CAAA;CAAE,CAClB,CAMD,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,kBAAkB,CAIxE,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,iBAAiB,uGAAmC,CAAA;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAA;AAsH7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,eAAe,8JAQ1B,CAAA;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,YAAY;qBACmB,MAAM;oBAAkB,iBAAiB;yFAgCnF,CAAA"}