@vertz/openapi 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+interface ParsedSpec {
+	version: "3.0" | "3.1";
+	info: {
+		title: string;
+		version: string;
+	};
+	resources: ParsedResource[];
+	schemas: ParsedSchema[];
+}
+interface ParsedResource {
+	name: string;
+	identifier: string;
+	operations: ParsedOperation[];
+}
+interface ParsedOperation {
+	operationId: string;
+	methodName: string;
+	method: HttpMethod;
+	path: string;
+	pathParams: ParsedParameter[];
+	queryParams: ParsedParameter[];
+	requestBody?: ParsedSchema;
+	response?: ParsedSchema;
+	responseStatus: number;
+	tags: string[];
+}
+interface ParsedParameter {
+	name: string;
+	required: boolean;
+	schema: Record<string, unknown>;
+}
+interface ParsedSchema {
+	name?: string;
+	jsonSchema: Record<string, unknown>;
+}
+type GroupByStrategy = "tag" | "path" | "none";
+declare function groupOperations(operations: ParsedOperation[], strategy: GroupByStrategy): ParsedResource[];
+declare function sanitizeIdentifier(name: string): string;
+interface NormalizerConfig {
+	overrides?: Record<string, string>;
+	transform?: (cleaned: string, original: string) => string;
+}
+declare function normalizeOperationId(operationId: string, method: HttpMethod, path: string, config?: NormalizerConfig): string;
+declare function parseOpenAPI(spec: Record<string, unknown>): {
+	operations: ParsedOperation[];
+	schemas: ParsedSchema[];
+	version: "3.0" | "3.1";
+};
+interface ResolveOptions {
+	specVersion: "3.0" | "3.1";
+}
+declare function resolveRef(ref: string, document: Record<string, unknown>, options: ResolveOptions): Record<string, unknown>;
+declare function resolveSchema(schema: Record<string, unknown>, document: Record<string, unknown>, options: ResolveOptions, resolving?: Set<string>): Record<string, unknown>;
+export { sanitizeIdentifier, resolveSchema, resolveRef, parseOpenAPI, normalizeOperationId, groupOperations, ResolveOptions, ParsedSpec, ParsedSchema, ParsedResource, ParsedParameter, ParsedOperation, NormalizerConfig, HttpMethod, GroupByStrategy };

package/dist/index.js

@@ -0,0 +1,420 @@
+// src/adapter/identifier.ts
+function splitWords(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[^A-Za-z0-9]+/g, " ").split(/\s+/).filter(Boolean);
+}
+function sanitizeIdentifier(name) {
+  const words = splitWords(name);
+  if (words.length === 0) {
+    return "_";
+  }
+  const [first, ...rest] = words.map((word) => word.toLowerCase());
+  const camelCase = first + rest.map((word) => word[0]?.toUpperCase() + word.slice(1)).join("");
+  return /^[0-9]/.test(camelCase) ? `_${camelCase}` : camelCase;
+}
+
+// src/adapter/resource-grouper.ts
+function getPathGroupKey(path) {
+  const meaningfulSegments = path.split("/").filter(Boolean).filter((segment) => segment !== "api").filter((segment) => !/^v\d+$/i.test(segment)).filter((segment) => !(segment.startsWith("{") && segment.endsWith("}")));
+  return meaningfulSegments[meaningfulSegments.length - 1] ?? "_ungrouped";
+}
+function toResourceName(identifier) {
+  return identifier === "_ungrouped" ? "Ungrouped" : identifier.charAt(0).toUpperCase() + identifier.slice(1);
+}
+function groupOperations(operations, strategy) {
+  const resources = new Map;
+  for (const operation of operations) {
+    const groupKey = strategy === "tag" ? operation.tags[0] ?? "_ungrouped" : strategy === "none" ? operation.operationId : getPathGroupKey(operation.path);
+    const identifier = groupKey === "_ungrouped" ? "_ungrouped" : sanitizeIdentifier(groupKey);
+    const existing = resources.get(identifier) ?? [];
+    existing.push(operation);
+    resources.set(identifier, existing);
+  }
+  return [...resources.entries()].map(([identifier, resourceOperations]) => ({
+    name: toResourceName(identifier),
+    identifier,
+    operations: resourceOperations
+  }));
+}
+// src/parser/operation-id-normalizer.ts
+var HTTP_METHOD_WORDS = new Set(["get", "post", "put", "delete", "patch"]);
+function isPathParam(segment) {
+  return segment.startsWith("{") && segment.endsWith("}");
+}
+function getPathSegments(path) {
+  return path.split("/").filter(Boolean);
+}
+function splitWords2(input) {
+  return input.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[^A-Za-z0-9]+/g, " ").split(/\s+/).filter(Boolean);
+}
+function toCamelCase(words) {
+  if (words.length === 0) {
+    return "";
+  }
+  const [first = "", ...rest] = words.map((word) => word.toLowerCase());
+  return first + rest.map((word) => word[0]?.toUpperCase() + word.slice(1)).join("");
+}
+function singularize(word) {
+  if (word.endsWith("ies") && word.length > 3) {
+    return `${word.slice(0, -3)}y`;
+  }
+  if (word.endsWith("s") && word.length > 1) {
+    return word.slice(0, -1);
+  }
+  return word;
+}
+function getPrimaryResourceWords(path) {
+  const segments = getPathSegments(path).filter((segment) => !isPathParam(segment));
+  const firstSegment = segments[0];
+  if (!firstSegment) {
+    return [];
+  }
+  return splitWords2(firstSegment).map((word) => word.toLowerCase());
+}
+function autoCleanOperationId(operationId, path) {
+  const withoutControllerPrefix = operationId.replace(/^[A-Za-z0-9]+Controller[_.-]+/, "");
+  const words = splitWords2(withoutControllerPrefix).map((word) => word.toLowerCase());
+  const lastWord = words.at(-1);
+  if (words.length > 1 && lastWord && HTTP_METHOD_WORDS.has(lastWord)) {
+    words.pop();
+  }
+  const resourcePhrase = getPrimaryResourceWords(path);
+  const resourceWords = new Set([...resourcePhrase, ...resourcePhrase.map(singularize)]);
+  if (resourcePhrase.length === 1) {
+    while (words.length > 1 && words[0] && resourceWords.has(words[0])) {
+      words.shift();
+    }
+    while (words.length > 1 && words.at(-1) && resourceWords.has(words.at(-1))) {
+      words.pop();
+    }
+  }
+  return toCamelCase(words);
+}
+function detectCrudMethod(method, path) {
+  const segments = getPathSegments(path);
+  if (segments.length === 1 && method === "GET") {
+    return "list";
+  }
+  if (segments.length === 2 && segments[1] && isPathParam(segments[1])) {
+    if (method === "GET") {
+      return "get";
+    }
+    if (method === "PUT" || method === "PATCH") {
+      return "update";
+    }
+    if (method === "DELETE") {
+      return "delete";
+    }
+  }
+  if (segments.length === 1 && method === "POST") {
+    return "create";
+  }
+  return;
+}
+function normalizeOperationId(operationId, method, path, config) {
+  if (config?.overrides?.[operationId]) {
+    return config.overrides[operationId];
+  }
+  const cleaned = autoCleanOperationId(operationId, path);
+  if (config?.transform) {
+    return config.transform(cleaned, operationId);
+  }
+  return detectCrudMethod(method, path) ?? cleaned;
+}
+// src/parser/ref-resolver.ts
+class OpenAPIParserError extends Error {
+  name = "OpenAPIParserError";
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function getRefSegments(ref) {
+  if (!ref.startsWith("#/")) {
+    throw new OpenAPIParserError(`External $ref values are not supported: ${ref}`);
+  }
+  return ref.slice(2).split("/");
+}
+function getRefName(ref) {
+  const segments = getRefSegments(ref);
+  return segments[segments.length - 1] ?? ref;
+}
+function getRawRefTarget(ref, document) {
+  let current = document;
+  for (const segment of getRefSegments(ref)) {
+    if (!isRecord(current) || !(segment in current)) {
+      throw new OpenAPIParserError(`Could not resolve $ref: ${ref}`);
+    }
+    current = current[segment];
+  }
+  if (!isRecord(current)) {
+    throw new OpenAPIParserError(`Resolved $ref is not an object schema: ${ref}`);
+  }
+  return current;
+}
+function resolveNestedValue(value, document, options, resolving) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => isRecord(entry) ? resolveSchema(entry, document, options, resolving) : entry);
+  }
+  if (isRecord(value)) {
+    return resolveSchema(value, document, options, resolving);
+  }
+  return value;
+}
+function mergeSchemas(left, right) {
+  const merged = { ...left };
+  for (const [key, value] of Object.entries(right)) {
+    if (key === "properties" && isRecord(merged.properties) && isRecord(value)) {
+      merged.properties = { ...merged.properties, ...value };
+      continue;
+    }
+    if (key === "required" && Array.isArray(merged.required) && Array.isArray(value)) {
+      merged.required = [...new Set([...merged.required, ...value])];
+      continue;
+    }
+    if (isRecord(merged[key]) && isRecord(value)) {
+      merged[key] = mergeSchemas(merged[key], value);
+      continue;
+    }
+    merged[key] = value;
+  }
+  return merged;
+}
+function resolveRef(ref, document, options) {
+  const target = getRawRefTarget(ref, document);
+  if (typeof target.$ref === "string") {
+    return resolveRef(target.$ref, document, options);
+  }
+  return resolveSchema(target, document, options);
+}
+function resolveSchema(schema, document, options, resolving = new Set) {
+  let workingSchema = { ...schema };
+  if (typeof workingSchema.$ref === "string") {
+    const ref = workingSchema.$ref;
+    if (resolving.has(ref)) {
+      return { $circular: getRefName(ref) };
+    }
+    const nextResolving = new Set(resolving);
+    nextResolving.add(ref);
+    const resolvedTarget = resolveSchema(getRawRefTarget(ref, document), document, options, nextResolving);
+    const siblingEntries = Object.entries(workingSchema).filter(([key]) => key !== "$ref");
+    if (options.specVersion === "3.0" || siblingEntries.length === 0) {
+      workingSchema = resolvedTarget;
+    } else {
+      const siblings = Object.fromEntries(siblingEntries);
+      workingSchema = mergeSchemas(resolvedTarget, resolveSchema(siblings, document, options, nextResolving));
+    }
+  }
+  if (Array.isArray(workingSchema.allOf)) {
+    const flattened = workingSchema.allOf.reduce((accumulator, member) => {
+      if (!isRecord(member)) {
+        return accumulator;
+      }
+      return mergeSchemas(accumulator, resolveSchema(member, document, options, new Set(resolving)));
+    }, {});
+    const { allOf: _allOf, ...rest } = workingSchema;
+    return mergeSchemas(flattened, resolveSchema(rest, document, options, resolving));
+  }
+  const resolved = {};
+  for (const [key, value] of Object.entries(workingSchema)) {
+    if (key === "properties" && isRecord(value)) {
+      resolved.properties = Object.fromEntries(Object.entries(value).map(([propertyName, propertySchema]) => [
+        propertyName,
+        isRecord(propertySchema) ? resolveSchema(propertySchema, document, options, new Set(resolving)) : propertySchema
+      ]));
+      continue;
+    }
+    resolved[key] = resolveNestedValue(value, document, options, new Set(resolving));
+  }
+  return resolved;
+}
+
+// src/parser/openapi-parser.ts
+class OpenAPIParserError2 extends Error {
+  name = "OpenAPIParserError";
+}
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function getVersion(spec) {
+  const version = spec.openapi;
+  if (typeof version !== "string") {
+    throw new OpenAPIParserError2("OpenAPI spec is missing required field: openapi");
+  }
+  if (version.startsWith("3.0")) {
+    return "3.0";
+  }
+  if (version.startsWith("3.1")) {
+    return "3.1";
+  }
+  throw new OpenAPIParserError2(`Unsupported OpenAPI version: ${version}`);
+}
+function getRefTarget(ref, spec) {
+  if (!ref.startsWith("#/")) {
+    throw new OpenAPIParserError2(`External $ref values are not supported: ${ref}`);
+  }
+  let current = spec;
+  for (const segment of ref.slice(2).split("/")) {
+    if (!isRecord2(current) || !(segment in current)) {
+      throw new OpenAPIParserError2(`Could not resolve $ref: ${ref}`);
+    }
+    current = current[segment];
+  }
+  if (!isRecord2(current)) {
+    throw new OpenAPIParserError2(`Resolved $ref is not an object: ${ref}`);
+  }
+  return current;
+}
+function resolveOpenAPIObject(value, spec) {
+  if (!isRecord2(value)) {
+    return;
+  }
+  if (typeof value.$ref === "string") {
+    return resolveOpenAPIObject(getRefTarget(value.$ref, spec), spec);
+  }
+  return value;
+}
+function normalizeNullableSchema(schema, version) {
+  if (Array.isArray(schema)) {
+    return schema.map((entry) => normalizeNullableSchema(entry, version));
+  }
+  if (!isRecord2(schema)) {
+    return schema;
+  }
+  const normalized = Object.fromEntries(Object.entries(schema).map(([key, value]) => [key, normalizeNullableSchema(value, version)]));
+  if (version !== "3.0" || normalized.nullable !== true) {
+    return normalized;
+  }
+  const type = normalized.type;
+  if (typeof type === "string") {
+    normalized.type = [type, "null"];
+  } else if (Array.isArray(type) && !type.includes("null")) {
+    normalized.type = [...type, "null"];
+  }
+  delete normalized.nullable;
+  return normalized;
+}
+function getJsonContentSchema(value) {
+  if (!isRecord2(value) || !isRecord2(value.content)) {
+    return;
+  }
+  const mediaType = value.content["application/json"];
+  if (!isRecord2(mediaType) || !isRecord2(mediaType.schema)) {
+    return;
+  }
+  return mediaType.schema;
+}
+function resolveSchemaForOutput(schema, spec, version) {
+  return {
+    jsonSchema: normalizeNullableSchema(resolveSchema(schema, spec, { specVersion: version }), version)
+  };
+}
+function getOperationResponses(operation) {
+  if (!isRecord2(operation.responses)) {
+    return {};
+  }
+  return operation.responses;
+}
+function pickSuccessResponse(operation, spec) {
+  const entries = Object.entries(getOperationResponses(operation)).map(([status, response]) => ({ status: Number(status), response })).filter(({ status }) => Number.isInteger(status) && status >= 200 && status < 300).sort((left, right) => left.status - right.status);
+  const first = entries[0];
+  if (!first) {
+    return { status: 200 };
+  }
+  const resolvedResponse = resolveOpenAPIObject(first.response, spec);
+  return {
+    status: first.status,
+    schema: getJsonContentSchema(resolvedResponse)
+  };
+}
+function getCombinedParameters(pathItem, operation, spec) {
+  const collect = (value) => Array.isArray(value) ? value.map((entry) => resolveOpenAPIObject(entry, spec)).filter((entry) => Boolean(entry)) : [];
+  return [...collect(pathItem.parameters), ...collect(operation.parameters)];
+}
+function getPathParameterNames(path) {
+  return [...path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]).filter((name) => Boolean(name));
+}
+function toParsedParameter(parameter, name, spec, version, requiredFallback) {
+  const resolvedSchema = isRecord2(parameter?.schema) ? normalizeNullableSchema(resolveSchema(parameter.schema, spec, { specVersion: version }), version) : {};
+  return {
+    name,
+    required: typeof parameter?.required === "boolean" ? parameter.required : requiredFallback,
+    schema: resolvedSchema
+  };
+}
+function extractParameters(path, pathItem, operation, spec, version) {
+  const combined = getCombinedParameters(pathItem, operation, spec);
+  const pathParameters = new Map;
+  const queryParameters = [];
+  for (const parameter of combined) {
+    if (parameter.in === "path" && typeof parameter.name === "string") {
+      pathParameters.set(parameter.name, parameter);
+    }
+    if (parameter.in === "query" && typeof parameter.name === "string") {
+      queryParameters.push(toParsedParameter(parameter, parameter.name, spec, version, false));
+    }
+  }
+  const pathNames = [...new Set([...getPathParameterNames(path), ...pathParameters.keys()])];
+  return {
+    pathParams: pathNames.map((name) => toParsedParameter(pathParameters.get(name), name, spec, version, true)),
+    queryParams: queryParameters
+  };
+}
+function extractRequestBody(operation, spec, version) {
+  const requestBody = resolveOpenAPIObject(operation.requestBody, spec);
+  const schema = getJsonContentSchema(requestBody);
+  return schema ? resolveSchemaForOutput(schema, spec, version) : undefined;
+}
+function collectComponentSchemas(spec, version) {
+  const schemas = isRecord2(spec.components) && isRecord2(spec.components.schemas) ? spec.components.schemas : undefined;
+  if (!schemas) {
+    return [];
+  }
+  return Object.entries(schemas).filter((entry) => isRecord2(entry[1])).map(([name, schema]) => ({
+    name,
+    ...resolveSchemaForOutput(schema, spec, version)
+  }));
+}
+function parseOpenAPI(spec) {
+  const version = getVersion(spec);
+  if (!isRecord2(spec.info)) {
+    throw new OpenAPIParserError2("OpenAPI spec is missing required field: info");
+  }
+  if (!isRecord2(spec.paths)) {
+    throw new OpenAPIParserError2("OpenAPI spec is missing required field: paths");
+  }
+  const operations = [];
+  for (const [path, pathItem] of Object.entries(spec.paths)) {
+    if (!isRecord2(pathItem)) {
+      continue;
+    }
+    for (const method of ["get", "post", "put", "delete", "patch"]) {
+      const operation = pathItem[method];
+      if (!isRecord2(operation)) {
+        continue;
+      }
+      const operationId = typeof operation.operationId === "string" ? operation.operationId : `${method}_${path}`;
+      const { pathParams, queryParams } = extractParameters(path, pathItem, operation, spec, version);
+      const successResponse = pickSuccessResponse(operation, spec);
+      operations.push({
+        operationId,
+        methodName: normalizeOperationId(operationId, method.toUpperCase(), path),
+        method: method.toUpperCase(),
+        path,
+        pathParams,
+        queryParams,
+        requestBody: extractRequestBody(operation, spec, version),
+        response: successResponse.schema ? resolveSchemaForOutput(successResponse.schema, spec, version) : undefined,
+        responseStatus: successResponse.status,
+        tags: Array.isArray(operation.tags) ? operation.tags.filter((tag) => typeof tag === "string") : []
+      });
+    }
+  }
+  return { operations, schemas: collectComponentSchemas(spec, version), version };
+}
+export {
+  sanitizeIdentifier,
+  resolveSchema,
+  resolveRef,
+  parseOpenAPI,
+  normalizeOperationId,
+  groupOperations
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@vertz/openapi",
+  "version": "0.1.0",
+  "description": "OpenAPI 3.x parser and TypeScript SDK generator for Vertz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vertz-dev/vertz.git",
+    "directory": "packages/openapi"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "bunup",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.10",
+    "bunup": "^0.16.31",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}