@trevrpc/trevrpc-js 0.2.3 → 1.1.0

package/src/generator.js

@@ -89,6 +89,18 @@ message MethodDescriptorProto {
   optional string output_type = 3;
   optional bool client_streaming = 5 [default = false];
   optional bool server_streaming = 6 [default = false];
+  optional MethodOptions options = 4;
+}
+
+// Only the trevrpc.method extension is modelled; protobuf.js keeps every other extension out of
+// the decoded message. The numbers are those of proto/trevrpc/options.proto.
+message MethodOptions {
+  optional TrevrpcMethodOptions trevrpc_method = 58247;
+}
+
+message TrevrpcMethodOptions {
+  optional bool unreliable_requests = 1;
+  optional bool unreliable_responses = 2;
 }
 
 message FileOptions {
@@ -166,6 +178,13 @@ const FieldLabel = Object.freeze({
   Repeated: 3,
 });
 
+/** Generic runtime types that generated declarations import only when they use them. */
+const GeneratedTypeImports = [
+  "BidirectionalStreamingCall",
+  "ClientStreamingCall",
+  "ResponseStream",
+];
+
 const RESERVED_WORDS = new Set([
   "break",
   "case",
@@ -225,7 +244,6 @@ export function generate(request) {
       }
 
       const fileName = outputFileName(file.name, options.fileSuffix);
-      const nodeFileName = outputFileName(file.name, `.node${options.fileSuffix}`);
       files.push({
         name: fileName,
         content: generateFile(file, rootJson, options),
@@ -234,14 +252,6 @@ export function generate(request) {
         name: declarationFileName(fileName),
         content: generateDeclarationFile(protoFiles, file, typeNames, options),
       });
-      files.push({
-        name: nodeFileName,
-        content: generateNodeFile(file, fileName, options),
-      });
-      files.push({
-        name: declarationFileName(nodeFileName),
-        content: generateNodeDeclarationFile(file, fileName, typeNames, options),
-      });
     }
 
     return { file: files };
@@ -255,8 +265,6 @@ export function parseOptions(parameter) {
   const options = {
     runtimeImport: "@trevrpc/trevrpc-js",
     runtimeTypeImport: null,
-    nodeRuntimeImport: "@trevrpc/trevrpc-js/node/generated",
-    nodeRuntimeTypeImport: null,
     fileSuffix: ".trevrpc.js",
   };
 
@@ -279,12 +287,6 @@ export function parseOptions(parameter) {
       case "runtime_type_import":
         options.runtimeTypeImport = value;
         break;
-      case "node_runtime_import":
-        options.nodeRuntimeImport = value;
-        break;
-      case "node_runtime_type_import":
-        options.nodeRuntimeTypeImport = value;
-        break;
       case "file_suffix":
         options.fileSuffix = value;
         break;
@@ -293,29 +295,15 @@ export function parseOptions(parameter) {
     }
   }
 
-  options.runtimeTypeImport = resolveTypeImport(
-    "runtime_import",
-    options.runtimeImport,
-    options.runtimeTypeImport,
-  );
-  options.nodeRuntimeTypeImport = resolveTypeImport(
-    "node_runtime_import",
-    options.nodeRuntimeImport,
-    options.nodeRuntimeTypeImport,
-  );
-  return options;
-}
-
-function resolveTypeImport(optionName, runtimeImport, typeImport) {
-  if (typeImport != null) {
-    return typeImport;
-  }
-  if (/^[A-Za-z][A-Za-z0-9+.-]*:/u.test(runtimeImport)) {
-    throw new Error(
-      `${optionName} ${JSON.stringify(runtimeImport)} requires an explicit ${optionName.replace("_import", "_type_import")}`,
-    );
+  if (options.runtimeTypeImport == null) {
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:/u.test(options.runtimeImport)) {
+      throw new Error(
+        `runtime_import ${JSON.stringify(options.runtimeImport)} requires an explicit runtime_type_import`,
+      );
+    }
+    options.runtimeTypeImport = options.runtimeImport;
   }
-  return runtimeImport;
+  return options;
 }
 
 /** Builds a protobuf.js JSON root from protobuf file descriptors. */
@@ -354,36 +342,19 @@ function generateDeclarationFile(protoFiles, file, typeNames, options) {
     .map((service) => generateServiceDeclaration(service, typeNames))
     .join("\n\n");
   const sections = [messages, services].filter(Boolean).join("\n\n");
-
-  return `// Code generated by protoc-gen-trevrpc-js. DO NOT EDIT.\n\nimport type { Long, Root } from "protobufjs";\n\nimport type { BidirectionalStreamingCall, CallOptions, ClientStreamingCall, ResponseAsyncIterable, RpcServiceDescriptor, Transport, UnaryResponse } from ${JSON.stringify(
+  const protobufImports = sections.includes("string | Long") ? "Long, Root" : "Root";
+  const runtimeImports = [
+    "CallOptions",
+    "RpcServiceDescriptor",
+    "Transport",
+    ...GeneratedTypeImports.filter((name) => sections.includes(`${name}<`)),
+  ].sort();
+
+  return `// Code generated by protoc-gen-trevrpc-js. DO NOT EDIT.\n\nimport type { ${protobufImports} } from "protobufjs";\n\nimport type { ${runtimeImports.join(", ")} } from ${JSON.stringify(
     options.runtimeTypeImport,
   )};\n\nexport declare const root: Root;\n\n${sections}\n`;
 }
 
-function generateNodeFile(file, ordinaryFileName, options) {
-  const services = (file.service ?? []).map((service) => serviceDescriptor(file, service));
-  const serviceNames = services.map((service) => service.exportName).join(", ");
-  const registrations = services.map(generateNodeServerRegistration).join("\n");
-  return `// Code generated by protoc-gen-trevrpc-js. DO NOT EDIT.\n\nimport { registerTypedService } from ${JSON.stringify(
-    options.nodeRuntimeImport,
-  )};\nimport { ${serviceNames}, root } from ${JSON.stringify(localModuleSpecifier(ordinaryFileName))};\n\n${registrations}`;
-}
-
-function generateNodeDeclarationFile(file, ordinaryFileName, typeNames, options) {
-  const services = (file.service ?? []).map((service) => serviceDescriptor(file, service));
-  const messageNames = [...new Set(typeNames.values())].join(", ");
-  const messageImport =
-    messageNames === ""
-      ? ""
-      : `import type { ${messageNames} } from ${JSON.stringify(localModuleSpecifier(ordinaryFileName))};\n`;
-  const declarations = services
-    .map((service) => generateNodeServiceDeclaration(service, typeNames))
-    .join("\n\n");
-  return `// Code generated by protoc-gen-trevrpc-js. DO NOT EDIT.\n\nimport type { NodeServer, NodeServerCall, StreamingServerResponse, UnaryServerResponse } from ${JSON.stringify(
-    options.nodeRuntimeTypeImport,
-  )};\n${messageImport}\n${declarations}\n`;
-}
-
 function generateService(service) {
   const className = `${pascalIdentifier(service.name)}Client`;
   const factoryName = `create${className}`;
@@ -398,18 +369,9 @@ function generateServiceMethod(jsName, method) {
     return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(options = {}) {\n    return this._client.${jsName}(options);\n  }`;
   }
 
-  if (method.kind === "unary") {
-    return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request, options = {}) {\n    return this._client.${jsName}(request, options);\n  }\n\n  /** Calls the ${method.name} RPC and returns response metadata. */\n  ${jsName}WithResponse(request, options = {}) {\n    return this._client.${jsName}WithResponse(request, options);\n  }`;
-  }
-
   return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request, options = {}) {\n    return this._client.${jsName}(request, options);\n  }`;
 }
 
-function generateNodeServerRegistration(service) {
-  const registerName = `register${pascalIdentifier(service.name)}Server`;
-  return `/** Registers typed Node handlers for the ${service.name} service. */\nexport function ${registerName}(server, handlers) {\n  return registerTypedService(server, root, ${service.exportName}, handlers);\n}\n`;
-}
-
 function generateServiceDeclaration(service, typeNames) {
   const className = `${pascalIdentifier(service.name)}Client`;
   const factoryName = `create${className}`;
@@ -420,24 +382,15 @@ function generateServiceDeclaration(service, typeNames) {
   return `/** Service descriptor for the ${service.name} service. */\nexport declare const ${service.exportName}: RpcServiceDescriptor;\n\n/** Client for the ${service.name} service. */\nexport declare class ${className} {\n  /** Creates a client for the ${service.name} service. */\n  constructor(transport: Transport, options?: CallOptions);\n\n${methods}\n}\n\n/** Creates a client for the ${service.name} service. */\nexport declare function ${factoryName}(transport: Transport, options?: CallOptions): ${className};`;
 }
 
-function generateNodeServiceDeclaration(service, typeNames) {
-  const handlerName = `${pascalIdentifier(service.name)}Handlers`;
-  const registerName = `register${pascalIdentifier(service.name)}Server`;
-  const handlers = Object.entries(service.methods)
-    .map(([jsName, method]) => generateHandlerDeclaration(jsName, method, typeNames))
-    .join("\n");
-  return `/** Typed Node handlers for the ${service.name} service. */\nexport interface ${handlerName} {\n${handlers}\n}\n\n/** Registers typed Node handlers for the ${service.name} service. */\nexport declare function ${registerName}(server: NodeServer, handlers: ${handlerName}): NodeServer;`;
-}
-
 function generateMethodDeclaration(jsName, method, typeNames) {
   const inputType = declarationTypeReference(method.inputType, typeNames);
   const outputType = declarationTypeReference(method.outputType, typeNames);
 
   switch (method.kind) {
     case "unary":
-      return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request: ${inputType}, options?: CallOptions): Promise<${outputType}>;\n  /** Calls the ${method.name} RPC and returns response metadata. */\n  ${jsName}WithResponse(request: ${inputType}, options?: CallOptions): Promise<UnaryResponse<${outputType}>>;`;
+      return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request: ${inputType}, options?: CallOptions): Promise<${outputType}>;`;
     case "serverStreaming":
-      return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request: ${inputType}, options?: CallOptions): Promise<ResponseAsyncIterable<${outputType}>>;`;
+      return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request: ${inputType}, options?: CallOptions): Promise<ResponseStream<${outputType}>>;`;
     case "clientStreaming":
       return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(options?: CallOptions): Promise<ClientStreamingCall<${inputType}, ${outputType}>>;`;
     case "bidirectionalStreaming":
@@ -447,25 +400,6 @@ function generateMethodDeclaration(jsName, method, typeNames) {
   }
 }
 
-function generateHandlerDeclaration(jsName, method, typeNames) {
-  const inputType = declarationTypeReference(method.inputType, typeNames);
-  const outputType = declarationTypeReference(method.outputType, typeNames);
-  const unaryResult = `${outputType} | UnaryServerResponse<${outputType}>`;
-  const streamingResult = `Iterable<${outputType}> | AsyncIterable<${outputType}> | StreamingServerResponse<${outputType}>`;
-  switch (method.kind) {
-    case "unary":
-      return `  ${jsName}?(request: ${inputType}, call: NodeServerCall): ${unaryResult} | Promise<${unaryResult}>;`;
-    case "serverStreaming":
-      return `  ${jsName}?(request: ${inputType}, call: NodeServerCall): ${streamingResult} | Promise<${streamingResult}>;`;
-    case "clientStreaming":
-      return `  ${jsName}?(requests: AsyncIterable<${inputType}>, call: NodeServerCall): ${unaryResult} | Promise<${unaryResult}>;`;
-    case "bidirectionalStreaming":
-      return `  ${jsName}?(requests: AsyncIterable<${inputType}>, call: NodeServerCall): ${streamingResult} | Promise<${streamingResult}>;`;
-    default:
-      throw new Error(`unsupported generated RPC kind ${JSON.stringify(method.kind)}`);
-  }
-}
-
 function serviceDescriptor(file, service) {
   const fullName =
     file.package === "" || file.package == null ? service.name : `${file.package}.${service.name}`;
@@ -474,11 +408,13 @@ function serviceDescriptor(file, service) {
 
   for (const method of service.method ?? []) {
     const jsName = uniqueName(lowerCamelIdentifier(method.name), usedNames);
+    const kind = methodKind(method);
     methods[jsName] = {
       name: method.name,
-      kind: methodKind(method),
+      kind,
       inputType: stripLeadingDot(method.inputType),
       outputType: stripLeadingDot(method.outputType),
+      ...unreliableDirections(`${fullName}.${method.name}`, kind, method.options?.trevrpcMethod),
     };
   }
 
@@ -490,6 +426,31 @@ function serviceDescriptor(file, service) {
   };
 }
 
+/**
+ * The `(trevrpc.method)` flags of a method as descriptor fields, only for the ones that are set.
+ * A flag on a direction that does not stream is an error.
+ */
+function unreliableDirections(methodName, kind, options) {
+  const directions = {};
+  if (options?.unreliableRequests) {
+    if (kind !== "clientStreaming" && kind !== "bidirectionalStreaming") {
+      throw new Error(
+        `${methodName}: unreliable_requests requires a client-streaming or bidirectional method`,
+      );
+    }
+    directions.unreliableRequests = true;
+  }
+  if (options?.unreliableResponses) {
+    if (kind !== "serverStreaming" && kind !== "bidirectionalStreaming") {
+      throw new Error(
+        `${methodName}: unreliable_responses requires a server-streaming or bidirectional method`,
+      );
+    }
+    directions.unreliableResponses = true;
+  }
+  return directions;
+}
+
 function declarationTypeNames(files) {
   const names = new Map();
   const usedNames = new Set();
@@ -808,10 +769,6 @@ function outputFileName(inputName, suffix) {
   return `${extensionStart === -1 ? inputName : inputName.slice(0, extensionStart)}${suffix}`;
 }
 
-function localModuleSpecifier(fileName) {
-  return `./${fileName.slice(fileName.lastIndexOf("/") + 1)}`;
-}
-
 function declarationFileName(outputName) {
   if (outputName.endsWith(".js")) {
     return `${outputName.slice(0, -3)}.d.ts`;