feat(cli): add basic addQuery and addMutation operations

Author: freakyfelt

README.md

@@ -215,19 +215,16 @@ builder.mutation('modifyWidget', {
   path: '/v1/users/{userId}/widgets/{widgetId}',
 
   request: {
-    schema: builder.schemas.ref('ModifyWidgetInput'),
+    schema: 'ModifyWidgetInput',
     parameters: {
       userId: { in: 'path', description: 'ID of the owning user of the widget' },
       widgetId: { in: 'path' },
     }
   }
   response: {
-    schema: builder.schema.ref('Widget'),
+    schema: 'Widget',
   },
-  errors: [
-    builder.components.ref({ responses: 'BadRequest' }),
-    builder.components.ref({ responses: 'NotFound' }),
-  ]
+  errors: ['BadRequest', 'NotFound'],
 })
 ```
 
@@ -249,7 +246,7 @@ paths:
       requestBody:
         application/json:
           // note the `Body` label appended to the end
-          spec: { $ref: '#/components/schemas/ModifyWidgetInputBody' }
+          schema: { $ref: '#/components/schemas/ModifyWidgetInputBody' }
 ```
 
 > **Note**

package-lock.json

@@ -14,8 +14,10 @@
     "packages/*"
   ],
   "devDependencies": {
+    "@sinclair/typebox": "^0.28.11",
     "@typescript-eslint/eslint-plugin": "^5.59.6",
     "@typescript-eslint/parser": "^5.59.6",
-    "eslint": "^8.40.0"
+    "eslint": "^8.40.0",
+    "openapi-types": "^12.1.0"
   }
 }

package.json

@@ -36,7 +36,7 @@
     "lint": "npm run lint:code",
     "lint:code": "eslint . --cache --fix --ext .ts",
     "pretest": "npm run lint && tsc --noEmit",
-    "test": "node --loader ts-node/esm --test src/index.test.ts",
+    "test": "node --loader ts-node/esm --test src/*.test.ts",
     "posttest": "npm run format"
   },
   "devDependencies": {

packages/cli/package.json

@@ -0,0 +1 @@
+export * from "./service-builder.js";

packages/cli/src/builder/index.ts

@@ -0,0 +1,119 @@
+import { Type } from "@sinclair/typebox";
+import assert from "node:assert";
+import test from "node:test";
+import { ResponseDefinition } from "../types/operations.js";
+import { YARPCServiceBuilder } from "./service-builder.js";
+
+const schemas = {
+	GetWidgetInput: Type.Object({
+		userId: Type.String(),
+		widgetId: Type.String(),
+	}),
+	Widget: Type.Object({
+		widgetId: Type.String(),
+		name: Type.String(),
+	}),
+	Error: Type.Object({
+		code: Type.String(),
+		message: Type.String(),
+		details: Type.Optional(Type.Any()),
+	}),
+};
+
+const errors: Record<string, ResponseDefinition<keyof typeof schemas>> = {
+	NotFound: {
+		description: "The entity was not found",
+		schema: "Error",
+	},
+};
+
+const exampleQuery = {
+	description: "getWidget",
+	path: "/users/{userId}/widgets",
+	request: {
+		schema: "GetWidgetInput",
+		parameters: {
+			userId: { in: "path" },
+		},
+	},
+	response: {
+		schema: "Widget",
+	},
+} as const;
+
+const exampleMutation = {
+	description: "createWidget",
+	request: {
+		schema: "CreateWidgetInput",
+	},
+	response: {
+		schema: "Widget",
+	},
+} as const;
+
+test("addQuery", (t) => {
+	const builder = new YARPCServiceBuilder({
+		info: {
+			title: "Test",
+			version: "1.0.0",
+		},
+		components: {
+			errors,
+			schemas,
+		},
+		oas: {
+			"x-service-name": "test",
+		},
+	});
+
+	t.test("adds a query", () => {
+		builder.addQuery("foo", exampleQuery);
+		assert.equal(builder.operations.foo, {
+			type: "query",
+			operationId: "foo",
+			...exampleQuery,
+		});
+	});
+
+	t.test("throws if operationId already exists", () => {
+		builder.addQuery("foo", exampleQuery);
+		assert.throws(() => builder.addQuery("foo", exampleQuery), {
+			message: `Operation with id "foo" already exists`,
+		});
+	});
+});
+
+test("addMutation", (t) => {
+	const builder = new YARPCServiceBuilder({
+		info: {
+			title: "Test",
+			version: "1.0.0",
+		},
+		components: {
+			schemas: {
+				CreateWidgetInput: Type.Object({
+					id: Type.Integer(),
+				}),
+				Widget: Type.Object({
+					id: Type.Integer(),
+				}),
+			},
+		},
+	});
+
+	t.test("adds a query", () => {
+		builder.addMutation("foo", exampleMutation);
+		assert.equal(builder.operations.foo, {
+			type: "query",
+			operationId: "foo",
+			...exampleMutation,
+		});
+	});
+
+	t.test("throws if operationId already exists", () => {
+		builder.addMutation("foo", exampleMutation);
+		assert.throws(() => builder.addMutation("foo", exampleMutation), {
+			message: `Operation with id "foo" already exists`,
+		});
+	});
+});

packages/cli/src/builder/service-builder.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert";
+import {
+	OperationDefinition,
+	ServiceComponentsObject,
+	ServiceDefinition,
+} from "../types/index.js";
+import {
+	AddMutationDefinition,
+	AddQueryDefinition,
+	withMutationDefaults,
+	withQueryDefaults,
+} from "./utils.js";
+
+export class YARPCServiceBuilder<
+	TBase extends ServiceDefinition<ServiceComponentsObject>
+> {
+	#service: ServiceDefinition<TBase["components"]>;
+	#operations: Map<string, OperationDefinition<TBase["components"]>> =
+		new Map();
+
+	constructor(config: ServiceDefinition<TBase["components"]>) {
+		this.#service = config;
+	}
+
+	get operations(): Record<string, OperationDefinition<TBase["components"]>> {
+		return Object.fromEntries(this.#operations.entries());
+	}
+
+	addQuery(
+		operationId: string,
+		operation: AddQueryDefinition<TBase["components"]>
+	) {
+		assert(
+			!this.#operations.has(operationId),
+			`Operation with id "${operationId}" already exists`
+		);
+
+		this.#operations.set(
+			operationId,
+			Object.freeze(withQueryDefaults(operationId, operation))
+		);
+	}
+
+	addMutation(
+		operationId: string,
+		operation: AddMutationDefinition<TBase["components"]>
+	) {
+		assert(
+			!this.#operations.has(operationId),
+			`Operation with id "${operationId}" already exists`
+		);
+
+		this.#operations.set(
+			operationId,
+			Object.freeze(withMutationDefaults(operationId, operation))
+		);
+	}
+}

packages/cli/src/builder/service-builder.ts

@@ -0,0 +1,44 @@
+import { ComponentsObject } from "../types/oas";
+import {
+	MutationDefinition,
+	OperationDefinition,
+	QueryDefinition,
+} from "../types/operations";
+
+export type AddQueryDefinition<TComponents extends ComponentsObject> = Omit<
+	QueryDefinition<TComponents>,
+	"operationId" | "type"
+>;
+
+export const withQueryDefaults = <TComponents extends ComponentsObject>(
+	operationId: string,
+	def: AddQueryDefinition<TComponents>
+): OperationDefinition<TComponents> => ({
+	type: "query",
+	operationId,
+	method: "get",
+	path: "/queries/" + operationId,
+	response: {
+		statusCode: 200,
+		...def.response,
+	},
+});
+
+export type AddMutationDefinition<TComponents extends ComponentsObject> = Omit<
+	MutationDefinition<TComponents>,
+	"operationId" | "type"
+>;
+
+export const withMutationDefaults = <TComponents extends ComponentsObject>(
+	operationId: string,
+	def: AddMutationDefinition<TComponents>
+): OperationDefinition<TComponents> => ({
+	type: "mutation",
+	operationId,
+	method: "post",
+	path: "/mutations/" + operationId,
+	response: {
+		statusCode: 200,
+		...def.response,
+	},
+});

packages/cli/src/builder/utils.ts

@@ -1 +1,2 @@
-export const hello = "world";
+export * from "./builder/index.js";
+export * from "./types/index.js";

packages/cli/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./oas.js";
+export * from "./operations.js";
+export * from "./service.js";

packages/cli/src/types/index.ts

@@ -0,0 +1,25 @@
+import type {} from "node:http";
+import type { OpenAPIV3_1 } from "openapi-types";
+
+export type HttpMethod =
+	| "get"
+	| "post"
+	| "put"
+	| "delete"
+	| "patch"
+	| "head"
+	| "options";
+
+export type ReferenceObject = OpenAPIV3_1.ReferenceObject;
+export type SchemaObject = OpenAPIV3_1.SchemaObject;
+
+export interface OASDocument<
+	TComponents extends ComponentsObject = ComponentsObject
+> extends Omit<OpenAPIV3_1.Document, "components"> {
+	components: TComponents;
+}
+
+export interface ComponentsObject
+	extends Omit<OpenAPIV3_1.ComponentsObject, "schemas"> {
+	schemas: Record<string, OpenAPIV3_1.SchemaObject>;
+}