@f3liz/rescript-autogen-openapi 0.1.6 → 0.2.0

package/README.md

@@ -9,12 +9,25 @@ Generate ReScript code with [Sury](https://github.com/DZakh/rescript-schema) sch
 *   **Multi-Fork Support**: Intelligently handles multiple API forks (like Misskey, Cherrypick, Firefish) by extracting shared code and generating fork-specific extensions.
 *   **Unified IR Pipeline**: Advanced type inference with a unified intermediate representation that generates both types and schemas.
 *   **Diff & Merge**: Compare specs, generate diff reports, and optimize code reuse across variants.
-*   **TypeScript Support**: Generates `.d.ts` files and TypeScript wrappers for idiomatic use in JS/TS projects.
+*   **TypeScript Support**: First-class TypeScript support via `genType`. Exported functions and types are idiomatic and fully typed for use in TypeScript projects.
 
 ## 📦 Installation
 
 ```bash
-npm install @f3liz/rescript-autogen-openapi sury @readme/openapi-parser
+npm install @f3liz/rescript-autogen-openapi sury
+```
+
+**Important**: This library has a peer dependency on `sury` (ReScript Schema). You must install it in your project because the generated code directly depends on it for runtime validation.
+
+### Configure `rescript.json`
+
+Add `sury` to your project dependencies:
+
+```json
+{
+  "name": "my-project",
+  "dependencies": ["sury"]
+}
 ```
 
 Ensure you have `rescript` (^12.0.0) installed.

package/lib/es6/src/Codegen.d.ts

@@ -0,0 +1,28 @@
+import type { codegenError as Types_codegenError } from './Types';
+import type { forkSpec as Types_forkSpec } from './Types';
+import type { generationConfig as Types_generationConfig } from './Types';
+import type { generationResult as Types_generationResult } from './Types';
+import type { openAPISpec as Types_openAPISpec } from './Types';
+import type { specDiff as Types_specDiff } from './Types';
+import type { t as Pipeline_t } from './core/Pipeline';
+export declare const generateSingleSpecPure: (spec: Types_openAPISpec, config: Types_generationConfig) => {
+    TAG: "Ok";
+    _0: Pipeline_t;
+} | {
+    TAG: "Error";
+    _0: Types_codegenError;
+};
+export declare const generateSingleSpec: (spec: Types_openAPISpec, config: Types_generationConfig) => Promise<Types_generationResult>;
+export declare const generateMultiSpecPure: (baseSpec: Types_openAPISpec, forkSpecs: Types_forkSpec[], config: Types_generationConfig) => {
+    TAG: "Ok";
+    _0: Pipeline_t;
+} | {
+    TAG: "Error";
+    _0: Types_codegenError;
+};
+export declare const generateMultiSpec: (baseSpec: Types_openAPISpec, forkSpecs: Types_forkSpec[], config: Types_generationConfig) => Promise<Types_generationResult>;
+export declare const compareSpecs: (baseSpec: Types_openAPISpec, forkSpec: Types_openAPISpec, baseName: (undefined | string), forkName: (undefined | string), outputPath: (undefined | string)) => Promise<Types_specDiff>;
+export declare const generate: (config: Types_generationConfig) => Promise<Types_generationResult>;
+export declare const createDefaultConfig: (url: string, outputDir: string) => Types_generationConfig;
+export declare const generateFromUrl: (url: string, outputDir: string, config: (undefined | Types_generationConfig)) => Promise<Types_generationResult>;
+export declare const generateFromFile: (filePath: string, outputDir: string, config: (undefined | Types_generationConfig)) => Promise<Types_generationResult>;

package/lib/es6/src/Types.d.ts

@@ -0,0 +1,286 @@
+import type { t as Config_t } from './types/Config';
+export type jsonSchemaType = "String" | "Number" | "Integer" | "Boolean" | "Object" | "Null" | "Unknown" | {
+    TAG: "Array";
+    _0: jsonSchemaType;
+};
+export type jsonSchema = {
+    readonly type: (undefined | jsonSchemaType);
+    readonly properties: (undefined | {
+        [id: string]: jsonSchema;
+    });
+    readonly items: (undefined | jsonSchema);
+    readonly required: (undefined | string[]);
+    readonly enum: (undefined | unknown[]);
+    readonly "$ref": (undefined | string);
+    readonly allOf: (undefined | jsonSchema[]);
+    readonly oneOf: (undefined | jsonSchema[]);
+    readonly anyOf: (undefined | jsonSchema[]);
+    readonly description: (undefined | string);
+    readonly format: (undefined | string);
+    readonly minLength: (undefined | number);
+    readonly maxLength: (undefined | number);
+    readonly minimum: (undefined | number);
+    readonly maximum: (undefined | number);
+    readonly pattern: (undefined | string);
+    readonly nullable: (undefined | boolean);
+};
+export type httpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+export type mediaType = {
+    readonly schema: (undefined | jsonSchema);
+    readonly example: (undefined | unknown);
+    readonly examples: (undefined | {
+        [id: string]: unknown;
+    });
+};
+export type requestBody = {
+    readonly description: (undefined | string);
+    readonly content: {
+        [id: string]: mediaType;
+    };
+    readonly required: (undefined | boolean);
+};
+export type response = {
+    readonly description: string;
+    readonly content: (undefined | {
+        [id: string]: mediaType;
+    });
+};
+export type parameter = {
+    readonly name: string;
+    readonly in: string;
+    readonly description: (undefined | string);
+    readonly required: (undefined | boolean);
+    readonly schema: (undefined | jsonSchema);
+};
+export type operation = {
+    readonly operationId: (undefined | string);
+    readonly summary: (undefined | string);
+    readonly description: (undefined | string);
+    readonly tags: (undefined | string[]);
+    readonly requestBody: (undefined | requestBody);
+    readonly responses: {
+        [id: string]: response;
+    };
+    readonly parameters: (undefined | parameter[]);
+};
+export type endpoint = {
+    readonly path: string;
+    readonly method: string;
+    readonly operationId: (undefined | string);
+    readonly summary: (undefined | string);
+    readonly description: (undefined | string);
+    readonly tags: (undefined | string[]);
+    readonly requestBody: (undefined | requestBody);
+    readonly responses: {
+        [id: string]: response;
+    };
+    readonly parameters: (undefined | parameter[]);
+};
+export type pathItem = {
+    readonly get: (undefined | operation);
+    readonly post: (undefined | operation);
+    readonly put: (undefined | operation);
+    readonly patch: (undefined | operation);
+    readonly delete: (undefined | operation);
+    readonly head: (undefined | operation);
+    readonly options: (undefined | operation);
+    readonly parameters: (undefined | parameter[]);
+};
+export type components = {
+    readonly schemas: (undefined | {
+        [id: string]: jsonSchema;
+    });
+};
+export type info = {
+    readonly title: string;
+    readonly version: string;
+    readonly description: (undefined | string);
+};
+export type openAPISpec = {
+    readonly openapi: string;
+    readonly info: info;
+    readonly paths: {
+        [id: string]: pathItem;
+    };
+    readonly components: (undefined | components);
+};
+export type generationStrategy = "Separate" | "SharedBase";
+export type breakingChangeHandling = "Error" | "Warn" | "Ignore";
+export type forkSpecConfig = {
+    readonly name: string;
+    readonly specPath: string;
+};
+export type generationTargets = {
+    readonly rescriptApi: boolean;
+    readonly rescriptWrapper: boolean;
+    readonly typescriptDts: boolean;
+    readonly typescriptWrapper: boolean;
+};
+export type generationConfig = Config_t;
+export type forkSpec = {
+    readonly name: string;
+    readonly spec: openAPISpec;
+};
+export type errorContext = {
+    readonly path: string;
+    readonly operation: string;
+    readonly schema: (undefined | unknown);
+};
+export type codegenError = {
+    TAG: "SpecResolutionError";
+    readonly url: string;
+    readonly message: string;
+} | {
+    TAG: "SchemaParseError";
+    readonly context: errorContext;
+    readonly reason: string;
+} | {
+    TAG: "ReferenceError";
+    readonly ref: string;
+    readonly context: errorContext;
+} | {
+    TAG: "ValidationError";
+    readonly schema: string;
+    readonly input: unknown;
+    readonly issues: string[];
+} | {
+    TAG: "CircularSchemaError";
+    readonly ref: string;
+    readonly depth: number;
+    readonly path: string;
+} | {
+    TAG: "FileWriteError";
+    readonly filePath: string;
+    readonly message: string;
+} | {
+    TAG: "InvalidConfigError";
+    readonly field: string;
+    readonly message: string;
+} | {
+    TAG: "UnknownError";
+    readonly message: string;
+    readonly context: (undefined | errorContext);
+};
+export type warning = {
+    TAG: "FallbackToJson";
+    readonly reason: string;
+    readonly context: errorContext;
+} | {
+    TAG: "UnsupportedFeature";
+    readonly feature: string;
+    readonly fallback: string;
+    readonly location: string;
+} | {
+    TAG: "DepthLimitReached";
+    readonly depth: number;
+    readonly path: string;
+} | {
+    TAG: "MissingSchema";
+    readonly ref: string;
+    readonly location: string;
+} | {
+    TAG: "IntersectionNotFullySupported";
+    readonly location: string;
+    readonly note: string;
+} | {
+    TAG: "ComplexUnionSimplified";
+    readonly location: string;
+    readonly types: string;
+};
+export type endpointDiff = {
+    readonly path: string;
+    readonly method: string;
+    readonly requestBodyChanged: boolean;
+    readonly responseChanged: boolean;
+    readonly breakingChange: boolean;
+};
+export type schemaDiff = {
+    readonly name: string;
+    readonly breakingChange: boolean;
+};
+export type specDiff = {
+    readonly addedEndpoints: endpoint[];
+    readonly removedEndpoints: endpoint[];
+    readonly modifiedEndpoints: endpointDiff[];
+    readonly addedSchemas: string[];
+    readonly removedSchemas: string[];
+    readonly modifiedSchemas: schemaDiff[];
+};
+export type generationSuccess = {
+    readonly generatedFiles: string[];
+    readonly diff: (undefined | specDiff);
+    readonly warnings: warning[];
+};
+export type generationResult = {
+    TAG: "Ok";
+    _0: generationSuccess;
+} | {
+    TAG: "Error";
+    _0: codegenError;
+};
+export type CodegenError_context = {
+    readonly path: string;
+    readonly operation: string;
+    readonly schema: (undefined | unknown);
+};
+export type CodegenError_t = {
+    TAG: "SpecResolutionError";
+    readonly url: string;
+    readonly message: string;
+} | {
+    TAG: "SchemaParseError";
+    readonly context: CodegenError_context;
+    readonly reason: string;
+} | {
+    TAG: "ReferenceError";
+    readonly ref: string;
+    readonly context: CodegenError_context;
+} | {
+    TAG: "ValidationError";
+    readonly schema: string;
+    readonly input: unknown;
+    readonly issues: string[];
+} | {
+    TAG: "CircularSchemaError";
+    readonly ref: string;
+    readonly depth: number;
+    readonly path: string;
+} | {
+    TAG: "FileWriteError";
+    readonly filePath: string;
+    readonly message: string;
+} | {
+    TAG: "InvalidConfigError";
+    readonly field: string;
+    readonly message: string;
+} | {
+    TAG: "UnknownError";
+    readonly message: string;
+    readonly context: (undefined | CodegenError_context);
+};
+export type Warning_t = {
+    TAG: "FallbackToJson";
+    readonly reason: string;
+    readonly context: CodegenError_context;
+} | {
+    TAG: "UnsupportedFeature";
+    readonly feature: string;
+    readonly fallback: string;
+    readonly location: string;
+} | {
+    TAG: "DepthLimitReached";
+    readonly depth: number;
+    readonly path: string;
+} | {
+    TAG: "MissingSchema";
+    readonly ref: string;
+    readonly location: string;
+} | {
+    TAG: "IntersectionNotFullySupported";
+    readonly location: string;
+    readonly note: string;
+} | {
+    TAG: "ComplexUnionSimplified";
+    readonly location: string;
+    readonly types: string;
+};

package/lib/es6/src/core/FileSystem.d.ts

@@ -0,0 +1,4 @@
+export type fileToWrite = {
+    readonly path: string;
+    readonly content: string;
+};

package/lib/es6/src/core/Pipeline.d.ts

@@ -0,0 +1,6 @@
+import type { fileToWrite as FileSystem_fileToWrite } from './FileSystem';
+import type { warning as Types_warning } from '../../src/Types';
+export type t = {
+    readonly files: FileSystem_fileToWrite[];
+    readonly warnings: Types_warning[];
+};

package/lib/es6/src/generators/IRToSuryGenerator.mjs

@@ -97,7 +97,22 @@ function generateSchemaWithContext(ctx, depthOpt, irType) {
         }
       case "Union" :
         let types = irType._0;
-        let match = Stdlib_Array.reduce(types, [
+        let nonNullTypes = types.filter(t => {
+          if (typeof t !== "object") {
+            return t !== "Null";
+          }
+          if (t.TAG !== "Literal") {
+            return true;
+          }
+          let tmp = t._0;
+          return typeof tmp === "object";
+        });
+        let hasNull = nonNullTypes.length < types.length;
+        if (hasNull && nonNullTypes.length === 1) {
+          return `S.nullableAsOption(` + recurse(nonNullTypes[0]) + `)`;
+        }
+        let effectiveTypes = hasNull ? nonNullTypes : types;
+        let match = Stdlib_Array.reduce(effectiveTypes, [
           false,
           false,
           undefined,
@@ -122,39 +137,97 @@ function generateSchemaWithContext(ctx, depthOpt, irType) {
           }
         });
         let arrayItemType = match[2];
-        if (match[0] && match[1] && SchemaIR.equals(Stdlib_Option.getOr(arrayItemType, "Unknown"), Stdlib_Option.getOr(match[3], "Unknown"))) {
-          return `S.array(` + recurse(Stdlib_Option.getOr(arrayItemType, "Unknown")) + `)`;
-        } else if (types.every(t => {
+        let result = match[0] && match[1] && effectiveTypes.length === 2 && SchemaIR.equals(Stdlib_Option.getOr(arrayItemType, "Unknown"), Stdlib_Option.getOr(match[3], "Unknown")) ? `S.array(` + recurse(Stdlib_Option.getOr(arrayItemType, "Unknown")) + `)` : (
+            effectiveTypes.every(t => {
+              if (typeof t !== "object") {
+                return false;
+              }
+              if (t.TAG !== "Literal") {
+                return false;
+              }
+              let tmp = t._0;
+              if (typeof tmp !== "object") {
+                return false;
+              } else {
+                return tmp.TAG === "StringLiteral";
+              }
+            }) && effectiveTypes.length !== 0 && effectiveTypes.length <= 50 ? `S.union([` + effectiveTypes.map(recurse).join(", ") + `])` : (
+                effectiveTypes.length !== 0 ? `S.union([` + effectiveTypes.map(recurse).join(", ") + `])` : "S.json"
+              )
+          );
+        if (hasNull) {
+          return `S.nullableAsOption(` + result + `)`;
+        } else {
+          return result;
+        }
+      case "Intersection" :
+        let types$1 = irType._0;
+        if (types$1.every(t => {
             if (typeof t !== "object") {
               return false;
+            } else {
+              return t.TAG === "Reference";
             }
-            if (t.TAG !== "Literal") {
-              return false;
+          }) && types$1.length !== 0) {
+          return recurse(Stdlib_Option.getOr(types$1[types$1.length - 1 | 0], "Unknown"));
+        }
+        let match$1 = Stdlib_Array.reduce(types$1, [
+          [],
+          []
+        ], (param, t) => {
+          let nonObj = param[1];
+          let props = param[0];
+          if (typeof t !== "object") {
+            return [
+              props,
+              nonObj.concat([t])
+            ];
+          } else if (t.TAG === "Object") {
+            return [
+              props.concat(t.properties),
+              nonObj
+            ];
+          } else {
+            return [
+              props,
+              nonObj.concat([t])
+            ];
+          }
+        });
+        let nonObjectTypes = match$1[1];
+        let objectProps = match$1[0];
+        if (objectProps.length !== 0 && nonObjectTypes.length === 0) {
+          let fields$1 = objectProps.map(param => {
+            let name = param[0];
+            let schemaCode = recurse(param[1]);
+            let camelName = CodegenUtils.escapeKeyword(JsConvertCase.toCamelCase(name));
+            if (param[2]) {
+              return `    ` + camelName + `: s.field("` + name + `", ` + schemaCode + `),`;
+            } else {
+              return `    ` + camelName + `: s.fieldOr("` + name + `", S.nullableAsOption(` + schemaCode + `), None),`;
             }
-            let tmp = t._0;
-            return typeof tmp !== "object" ? false : tmp.TAG === "StringLiteral";
-          }) && types.length !== 0 && types.length <= 50) {
-          return `S.union([` + types.map(recurse).join(", ") + `])`;
-        } else {
-          GenerationContext.addWarning(ctx, {
-            TAG: "ComplexUnionSimplified",
-            location: ctx.path,
-            types: types.map(SchemaIR.toString).join(" | ")
-          });
-          return "S.json";
+          }).join("\n");
+          return `S.object(s => {\n` + fields$1 + `\n  })`;
         }
-      case "Intersection" :
-        let types$1 = irType._0;
-        if (types$1.every(t => typeof t !== "object" ? false : t.TAG === "Reference") && types$1.length !== 0) {
+        if (nonObjectTypes.length !== 0 && objectProps.length === 0) {
           return recurse(Stdlib_Option.getOr(types$1[types$1.length - 1 | 0], "Unknown"));
-        } else {
-          GenerationContext.addWarning(ctx, {
-            TAG: "IntersectionNotFullySupported",
-            location: ctx.path,
-            note: "Complex intersection"
-          });
-          return "S.json";
         }
+        GenerationContext.addWarning(ctx, {
+          TAG: "IntersectionNotFullySupported",
+          location: ctx.path,
+          note: "Mixed object/non-object intersection"
+        });
+        let fields$2 = objectProps.map(param => {
+          let name = param[0];
+          let schemaCode = recurse(param[1]);
+          let camelName = CodegenUtils.escapeKeyword(JsConvertCase.toCamelCase(name));
+          if (param[2]) {
+            return `    ` + camelName + `: s.field("` + name + `", ` + schemaCode + `),`;
+          } else {
+            return `    ` + camelName + `: s.fieldOr("` + name + `", S.nullableAsOption(` + schemaCode + `), None),`;
+          }
+        }).join("\n");
+        return `S.object(s => {\n` + fields$2 + `\n  })`;
       case "Reference" :
         let ref = irType._0;
         let available = ctx.availableSchemas;