peta-docs 0.3.0

package/dist/spec-Bobwv7gP.mjs

@@ -0,0 +1,281 @@
+//#region src/spec/schema.ts
+function isArkType(value) {
+	return typeof value === "function" && "toJsonSchema" in value;
+}
+function toOpenAPISchema(schema) {
+	if (schema === null || schema === void 0) return {};
+	if (isArkType(schema)) try {
+		return schema.toJsonSchema();
+	} catch {
+		try {
+			const inner = schema.in;
+			if (inner?.toJsonSchema) return inner.toJsonSchema();
+		} catch {}
+		return {};
+	}
+	if (typeof schema === "function") {
+		const isDev = typeof process !== "undefined" && process.env.NODE_ENV === "development";
+		const msg = "[peta-docs] A non-ArkType function was passed where a schema is expected. OpenAPI spec generation only supports ArkType types and plain JSON Schema objects. Either use an ArkType type, or pre-convert your schema to a JSON Schema object.";
+		console.warn(msg);
+		if (isDev) throw new TypeError(msg);
+		return {};
+	}
+	if (typeof schema === "object" && !Array.isArray(schema)) return schema;
+	return {};
+}
+function mapContentSchemas(content, convert) {
+	const result = {};
+	for (const [mediaType, { schema }] of Object.entries(content)) result[mediaType] = { schema: convert(schema) };
+	return result;
+}
+const STATUS_DESCRIPTIONS = {
+	"200": "OK",
+	"201": "Created",
+	"202": "Accepted",
+	"204": "No Content",
+	"301": "Moved Permanently",
+	"304": "Not Modified",
+	"400": "Bad Request",
+	"401": "Unauthorized",
+	"403": "Forbidden",
+	"404": "Not Found",
+	"405": "Method Not Allowed",
+	"409": "Conflict",
+	"422": "Unprocessable Entity",
+	"429": "Too Many Requests",
+	"500": "Internal Server Error",
+	"502": "Bad Gateway",
+	"503": "Service Unavailable"
+};
+function normalizeResponse(status, value) {
+	if (typeof value === "string") return { description: value };
+	if (isArkType(value)) return {
+		description: STATUS_DESCRIPTIONS[status] ?? status,
+		content: { "application/json": { schema: value } }
+	};
+	const obj = value;
+	return {
+		description: obj.description ?? STATUS_DESCRIPTIONS[status] ?? status,
+		...obj.content ? { content: obj.content } : {}
+	};
+}
+function normalizeRequestBody(value) {
+	if (value === null || value === void 0) return void 0;
+	if (isArkType(value)) return {
+		required: true,
+		content: { "application/json": { schema: value } }
+	};
+	return value;
+}
+//#endregion
+//#region src/spec/builder.ts
+function honoPathToOpenAPI(path) {
+	return path.replace(/:(\w+)/g, "{$1}");
+}
+function parsePathParams(path) {
+	const params = [];
+	const regex = /{(\w+)}/g;
+	let match = regex.exec(path);
+	while (match !== null) {
+		params.push(match[1]);
+		match = regex.exec(path);
+	}
+	return params;
+}
+function extractProperties(schema) {
+	const props = schema.properties;
+	if (!props) return [];
+	const requiredSet = new Set(Array.isArray(schema.required) ? schema.required : []);
+	return Object.entries(props).map(([name, propSchema]) => ({
+		name,
+		schema: propSchema,
+		required: requiredSet.has(name)
+	}));
+}
+function autoOperationId(method, path) {
+	const segments = path.replace(/{(\w+)}/g, (_m, name) => `By${name[0].toUpperCase() + name.slice(1)}`).replace(/:(\w+)/g, (_m, name) => `By${name[0].toUpperCase() + name.slice(1)}`).replace(/\/+/g, "/").replace(/^\//, "").split("/").filter(Boolean);
+	return method.toLowerCase() + segments.map((s) => s[0].toUpperCase() + s.slice(1)).join("");
+}
+function autoTags(path, basePath) {
+	const segment = (basePath && path.startsWith(basePath) ? path.slice(basePath.length) : path).replace(/^\//, "").split("/").filter(Boolean)[0];
+	if (!segment || segment.startsWith(":") || segment.startsWith("{")) return [];
+	return [segment];
+}
+const METHOD_ORDER = {
+	get: 0,
+	post: 1,
+	put: 2,
+	delete: 3,
+	patch: 4
+};
+function buildOpenAPISpec(routes, info, options) {
+	const basePath = options?.basePath ?? "/api";
+	const s = (schema) => toOpenAPISchema(schema);
+	const paths = {};
+	const tagged = routes.map((r) => ({
+		...r,
+		tag: (r.config.tags ?? autoTags(r.path, basePath))[0] ?? "__untagged"
+	})).sort((a, b) => {
+		if (a.tag !== b.tag) return a.tag < b.tag ? -1 : 1;
+		if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+		return (METHOD_ORDER[a.method.toLowerCase()] ?? 99) - (METHOD_ORDER[b.method.toLowerCase()] ?? 99);
+	});
+	for (const { path: rawPath, method, config } of tagged) {
+		const path = honoPathToOpenAPI(rawPath);
+		paths[path] ??= {};
+		const pathItem = paths[path];
+		const parameters = [];
+		const pathParams = parsePathParams(path);
+		if (pathParams.length > 0 && config.params) {
+			const paramDefs = extractProperties(s(config.params));
+			for (const param of pathParams) {
+				const def = paramDefs.find((p) => p.name === param);
+				parameters.push({
+					name: param,
+					in: "path",
+					required: true,
+					schema: def?.schema ?? { type: "string" }
+				});
+			}
+		}
+		if (config.query) {
+			const querySchema = s(config.query);
+			for (const param of extractProperties(querySchema)) parameters.push({
+				name: param.name,
+				in: "query",
+				required: param.required,
+				schema: param.schema
+			});
+		}
+		if (config.pagination) parameters.push({
+			name: "page",
+			in: "query",
+			required: false,
+			schema: {
+				type: "integer",
+				minimum: 1,
+				default: 1,
+				description: "Page number"
+			}
+		}, {
+			name: "limit",
+			in: "query",
+			required: false,
+			schema: {
+				type: "integer",
+				minimum: 1,
+				maximum: config.pagination.maxLimit,
+				default: config.pagination.defaultLimit,
+				description: "Items per page"
+			}
+		});
+		if (config.filters) for (const filter of config.filters) for (const op of filter.operators) {
+			const paramName = op === "eq" ? filter.name : `${filter.name}__${op}`;
+			const schemaObj = s(filter.schema);
+			if (op === "in") schemaObj["x-operator"] = "in";
+			parameters.push({
+				name: paramName,
+				in: "query",
+				required: false,
+				schema: schemaObj
+			});
+		}
+		if (config.sort) {
+			const enumValues = config.sort.flatMap((f) => [f, `-${f}`]);
+			parameters.push({
+				name: "sort",
+				in: "query",
+				required: false,
+				schema: {
+					type: "string",
+					enum: enumValues,
+					description: "Comma-separated sort fields. Prefix with - for descending."
+				}
+			});
+		}
+		if (config.include) parameters.push({
+			name: "include",
+			in: "query",
+			required: false,
+			schema: {
+				type: "string",
+				enum: config.include,
+				description: "Comma-separated related resources to sideload."
+			}
+		});
+		if (config.fieldsets) for (const resource of config.fieldsets) parameters.push({
+			name: `fields[${resource}]`,
+			in: "query",
+			required: false,
+			schema: {
+				type: "string",
+				description: `Fields to return for ${resource}.`
+			}
+		});
+		if (config.headers) {
+			const headersSchema = s(config.headers);
+			for (const param of extractProperties(headersSchema)) parameters.push({
+				name: param.name,
+				in: "header",
+				required: param.required,
+				schema: param.schema
+			});
+		}
+		const operation = { operationId: config.operationId ?? autoOperationId(method, path) };
+		if (config.summary) operation.summary = config.summary;
+		if (config.description) operation.description = config.description;
+		if (config.tags) operation.tags = config.tags;
+		else operation.tags = autoTags(path, basePath);
+		if (config.security) operation.security = [{ ...Object.fromEntries(config.security.map((s) => [s, []])) }];
+		if (parameters.length > 0) operation.parameters = parameters;
+		if (config.requestBody) {
+			const normalized = normalizeRequestBody(config.requestBody);
+			if (normalized) operation.requestBody = {
+				description: normalized.description,
+				required: normalized.required,
+				content: mapContentSchemas(normalized.content, s)
+			};
+		}
+		const responses = {};
+		for (const [status, rawResponse] of Object.entries(config.responses)) {
+			const normalized = normalizeResponse(status, rawResponse);
+			const resp = { description: normalized.description };
+			if (normalized.content) resp.content = mapContentSchemas(normalized.content, s);
+			responses[status] = resp;
+		}
+		operation.responses = responses;
+		const methodLower = method.toLowerCase();
+		const key = [
+			"get",
+			"post",
+			"put",
+			"delete",
+			"patch"
+		].includes(methodLower) ? methodLower : void 0;
+		if (key) pathItem[key] = operation;
+	}
+	const spec = {
+		openapi: "3.1.0",
+		info,
+		paths
+	};
+	if (options?.components) spec.components = options.components;
+	return spec;
+}
+//#endregion
+//#region src/spec.ts
+let _defaultScanner = null;
+/**
+* Register a default scanner for `getOpenAPISpec`.
+* Called automatically by framework adapter modules (e.g., `peta-docs/hono`).
+*/
+function setDefaultScanner(scanner) {
+	_defaultScanner = scanner;
+}
+function getOpenAPISpec(app, info, scanner, options) {
+	const active = scanner ?? _defaultScanner;
+	if (!active) throw new Error("No RouteScanner provided. Pass one explicitly or import from 'peta-docs/hono' which registers a default scanner.");
+	return buildOpenAPISpec(active.scan(app), info, options);
+}
+//#endregion
+export { toOpenAPISchema as i, setDefaultScanner as n, buildOpenAPISpec as r, getOpenAPISpec as t };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "peta-docs",
+  "version": "0.3.0",
+  "private": false,
+  "type": "module",
+  "description": "OpenAPI + Scalar docs for Hono (and more), powered by Standard Schema",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zfadhli/peta-stack.git"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./hono": {
+      "types": "./dist/hono/index.d.mts",
+      "import": "./dist/hono/index.mjs",
+      "default": "./dist/hono/index.mjs"
+    }
+  },
+  "dependencies": {
+    "hono": "^4"
+  },
+  "optionalDependencies": {
+    "arktype": "^2"
+  },
+  "peerDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "biome check src/ test/ examples/",
+    "format": "biome check --write src/ test/ examples/",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@types/bun": "^1.3.14",
+    "tsdown": "^0.22.1"
+  }
+}