@trevrpc/trevrpc-js 1.3.1 → 1.4.0

package/src/generator.js

@@ -1,5 +1,7 @@
 import protobuf from "protobufjs";
 
+import { Int64Representations } from "./int64.js";
+
 const DESCRIPTOR_PROTO = String.raw`
 syntax = "proto2";
 
@@ -107,6 +109,12 @@ message TrevrpcMethodOptions {
 }
 
 message FieldOptions {
+  enum JSType {
+    JS_NORMAL = 0;
+    JS_STRING = 1;
+    JS_NUMBER = 2;
+  }
+  optional JSType jstype = 6;
   optional bool debug_redact = 16;
 }
 
@@ -195,6 +203,24 @@ const GeneratedTypeImports = [
   "ResponseStream",
 ];
 
+/**
+ * Well-known types whose declarations the runtime exports, so that generated files share them
+ * instead of declaring their own: the full name and whether it holds 64-bit integers, which the
+ * runtime declares as bigint, so it is shared only when that is the representation.
+ */
+const SharedWellKnownTypes = new Map([
+  ["google.protobuf.Timestamp", { int64: true }],
+  ["google.protobuf.Duration", { int64: true }],
+  ["google.protobuf.Empty", { int64: false }],
+  ["google.protobuf.Struct", { int64: false }],
+  ["google.protobuf.Value", { int64: false }],
+  ["google.protobuf.ListValue", { int64: false }],
+  ["google.protobuf.NullValue", { int64: false }],
+]);
+
+/** FieldOptions.JSType values. */
+const JSType = Object.freeze({ normal: 0, string: 1, number: 2 });
+
 const RESERVED_WORDS = new Set([
   "break",
   "case",
@@ -245,7 +271,6 @@ export function generate(request) {
     const filesToGenerate = new Set(request.fileToGenerate ?? []);
     const protoFiles = request.protoFile ?? [];
     const rootJson = buildProtobufJson(protoFiles);
-    const typeNames = declarationTypeNames(protoFiles);
     const redacted = redactedTypes(protoFiles);
     const files = [];
 
@@ -255,13 +280,14 @@ export function generate(request) {
       }
 
       const fileName = outputFileName(file.name, options.fileSuffix);
+      const model = declarationModel(protoFiles, file, options);
       files.push({
         name: fileName,
-        content: generateFile(file, rootJson, redacted, options),
+        content: generateFile(file, rootJson, model, redacted, options),
       });
       files.push({
         name: declarationFileName(fileName),
-        content: generateDeclarationFile(protoFiles, file, typeNames, redacted, options),
+        content: generateDeclarationFile(file, model, redacted, options),
       });
     }
 
@@ -277,6 +303,7 @@ export function parseOptions(parameter) {
     runtimeImport: "@trevrpc/trevrpc-js",
     runtimeTypeImport: null,
     fileSuffix: ".trevrpc.js",
+    int64: "bigint",
   };
 
   for (const option of parameter.split(",")) {
@@ -301,6 +328,14 @@ export function parseOptions(parameter) {
       case "file_suffix":
         options.fileSuffix = value;
         break;
+      case "int64":
+        if (!Int64Representations.includes(value)) {
+          throw new Error(
+            `invalid trevrpc-js int64 ${JSON.stringify(value)}; expected one of ${Int64Representations.join(", ")}`,
+          );
+        }
+        options.int64 = value;
+        break;
       default:
         throw new Error(`unknown trevrpc-js option ${JSON.stringify(key)}`);
     }
@@ -334,40 +369,63 @@ export function buildProtobufJson(files) {
   return root;
 }
 
-function generateFile(file, rootJson, redacted, options) {
+function generateFile(file, rootJson, model, redacted, options) {
   const services = (file.service ?? []).map((service) =>
     serviceDescriptor(file, service, redacted),
   );
   const serviceExports = services.map((service) => generateService(service)).join("\n");
+  const enumExports = model.enums
+    .filter(({ shared }) => !shared)
+    .map(generateEnum)
+    .join("\n\n");
 
   return `// Code generated by protoc-gen-trevrpc-js. DO NOT EDIT.\n\nimport { createRoot, createServiceClient } from ${JSON.stringify(
     options.runtimeImport,
-  )};\n\nexport const root = createRoot(${JSON.stringify(rootJson, null, 2)});\n\n${serviceExports}`;
+  )};\n\nexport const root = createRoot(${JSON.stringify(rootJson, null, 2)}, { int64: ${JSON.stringify(options.int64)} });\n\n${enumExports === "" ? "" : `${enumExports}\n\n`}${serviceExports}`;
 }
 
-function generateDeclarationFile(protoFiles, file, typeNames, redacted, options) {
-  const messages = collectMessages(protoFiles)
-    .filter(({ message }) => !message.options?.mapEntry)
-    .map((message) => generateMessageDeclaration(message, typeNames))
+/** The runtime value of an enum: a frozen object of its values by name. */
+function generateEnum({ fullName, name, values }) {
+  const entries = values.map(({ key, number }) => `  ${typescriptPropertyName(key)}: ${number},`);
+  return `/** Values of the ${fullName} enum. */\nexport const ${name} = Object.freeze({\n${entries.join("\n")}\n});`;
+}
+
+function generateDeclarationFile(file, model, redacted, options) {
+  const context = { model, runtimeTypes: new Set(), usesLong: false };
+  const enums = model.enums
+    .filter(({ shared }) => !shared)
+    .map(generateEnumDeclaration)
+    .join("\n\n");
+  const messages = model.messages
+    .filter(({ shared }) => !shared)
+    .map((message) => generateMessageDeclarations(message, context))
     .join("\n\n");
   const services = (file.service ?? [])
     .map((service) => serviceDescriptor(file, service, redacted))
-    .map((service) => generateServiceDeclaration(service, typeNames))
+    .map((service) => generateServiceDeclaration(service, context))
     .join("\n\n");
-  const sections = [messages, services].filter(Boolean).join("\n\n");
-  const protobufImports = sections.includes("string | Long") ? "Long, Root" : "Root";
+  const sections = [enums, messages, services].filter(Boolean).join("\n\n");
+  const protobufImports = context.usesLong ? "Long, Root" : "Root";
   const runtimeImports = [
     "CallOptions",
+    "ClientOptions",
     "RpcServiceDescriptor",
     "Transport",
+    ...context.runtimeTypes,
     ...GeneratedTypeImports.filter((name) => sections.includes(`${name}<`)),
-  ].sort();
+  ].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
 
   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`;
 }
 
+/** The declaration of an enum's runtime value and of the type of its values. */
+function generateEnumDeclaration({ fullName, name, values }) {
+  const entries = values.map(({ key, number }) => `${typescriptPropertyName(key)}: ${number}`);
+  return `/** Values of the ${fullName} enum. */\nexport declare const ${name}: Readonly<{ ${entries.join("; ")} }>;\n/** A value of the ${fullName} enum. */\nexport type ${name} = (typeof ${name})[keyof typeof ${name}];`;
+}
+
 function generateService(service) {
   const className = `${pascalIdentifier(service.name)}Client`;
   const factoryName = `create${className}`;
@@ -385,19 +443,20 @@ function generateServiceMethod(jsName, method) {
   return `  /** Calls the ${method.name} RPC. */\n  ${jsName}(request, options = {}) {\n    return this._client.${jsName}(request, options);\n  }`;
 }
 
-function generateServiceDeclaration(service, typeNames) {
+function generateServiceDeclaration(service, context) {
   const className = `${pascalIdentifier(service.name)}Client`;
   const factoryName = `create${className}`;
   const methods = Object.entries(service.methods)
-    .map(([jsName, method]) => generateMethodDeclaration(jsName, method, typeNames))
+    .map(([jsName, method]) => generateMethodDeclaration(jsName, method, context))
     .join("\n");
 
-  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};`;
+  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?: ClientOptions);\n\n${methods}\n}\n\n/** Creates a client for the ${service.name} service. */\nexport declare function ${factoryName}(transport: Transport, options?: ClientOptions): ${className};`;
 }
 
-function generateMethodDeclaration(jsName, method, typeNames) {
-  const inputType = declarationTypeReference(method.inputType, typeNames);
-  const outputType = declarationTypeReference(method.outputType, typeNames);
+function generateMethodDeclaration(jsName, method, context) {
+  // Requests take the input shape; responses are decoded messages.
+  const inputType = messageTypeReference(method.inputType, "input", context);
+  const outputType = messageTypeReference(method.outputType, "output", context);
 
   switch (method.kind) {
     case "unary":
@@ -551,19 +610,122 @@ function redactedTypes(files) {
   return redacted;
 }
 
-function declarationTypeNames(files) {
-  const names = new Map();
+/**
+ * The declarations of a generated file: its own messages and enums and every type they and its
+ * services use, directly or through other messages. `messages` holds each message's `name` (the
+ * decoded shape) and `initName` (the input shape), `enums` each enum's `name` and `values`, and
+ * `names` maps full names to them. Well-known types the runtime declares are `shared`: their names
+ * are reserved first and refer to the runtime's declarations.
+ */
+function declarationModel(files, file, options) {
   const usedNames = new Set();
+  const names = new Map();
+  const isShared = (fullName) => {
+    const shared = SharedWellKnownTypes.get(fullName);
+    return shared !== undefined && (!shared.int64 || options.int64 === "bigint");
+  };
+  const used = usedTypes(files, file);
+  const messages = collectMessages(files)
+    .filter(({ fullName, message }) => used.has(fullName) && !message.options?.mapEntry)
+    .map((entry) => ({ ...entry, shared: isShared(entry.fullName) }));
+  const enums = collectEnums(files)
+    .filter(({ fullName }) => used.has(fullName))
+    .map((entry) => ({ ...entry, shared: isShared(entry.fullName) }));
+  const declared = [...messages, ...enums];
+
+  for (const entry of declared.filter(({ shared }) => shared)) {
+    entry.name = uniqueName(lastTypeSegment(entry.fullName), usedNames);
+  }
+  for (const entry of declared.filter(({ shared }) => !shared)) {
+    entry.name = uniqueName(pascalIdentifier(lastTypeSegment(entry.fullName)), usedNames);
+  }
+  for (const message of messages) {
+    message.initName = message.shared
+      ? `${message.name}Init`
+      : uniqueName(`${message.name}Init`, usedNames);
+  }
+  for (const entry of declared) {
+    names.set(entry.fullName, entry);
+  }
+  for (const enumEntry of enums) {
+    enumEntry.values = enumValues(enumEntry);
+  }
+  return { messages, enums, names, int64: options.int64 };
+}
 
-  for (const { fullName, message } of collectMessages(files)) {
-    if (message.options?.mapEntry) {
+/**
+ * The full names of the types a generated file declares: the messages and enums `file` defines,
+ * the request and response types of its services, and every type their fields use, transitively.
+ */
+function usedTypes(files, file) {
+  const messages = new Map(
+    collectMessages(files).map(({ fullName, message }) => [fullName, message]),
+  );
+  const used = new Set();
+  const pending = [
+    ...collectMessages([file]).map(({ fullName }) => fullName),
+    ...collectEnums([file]).map(({ fullName }) => fullName),
+    ...(file.service ?? []).flatMap((service) =>
+      (service.method ?? []).flatMap((method) =>
+        [method.inputType, method.outputType].map(stripLeadingDot),
+      ),
+    ),
+  ];
+  while (pending.length > 0) {
+    const fullName = pending.pop();
+    if (used.has(fullName)) {
       continue;
     }
-
-    names.set(fullName, uniqueName(pascalIdentifier(lastTypeSegment(fullName)), usedNames));
+    used.add(fullName);
+    for (const field of messages.get(fullName)?.field ?? []) {
+      if (field.typeName != null) {
+        pending.push(stripLeadingDot(field.typeName));
+      }
+    }
   }
+  return used;
+}
+
+/**
+ * The values of an enum, each with the `key` it has in the exported object: its name without the
+ * enum's prefix (`TIME_INTERVAL_HOUR` of `TimeInterval` is `HOUR`) when every value has that prefix
+ * and every key that leaves is a distinct identifier, as protobuf-es does; its full name otherwise.
+ */
+function enumValues({ fullName, enumType }) {
+  const values = (enumType.value ?? []).map((value) => ({
+    name: value.name ?? "",
+    number: value.number ?? 0,
+  }));
+  const prefix = `${upperSnakeCase(lastTypeSegment(fullName))}_`;
+  const stripped = values.map(({ name }) => name.slice(prefix.length));
+  const strip =
+    values.length > 0 &&
+    values.every(({ name }) => name.startsWith(prefix)) &&
+    stripped.every((key) => /^[A-Za-z_][A-Za-z0-9_]*$/u.test(key)) &&
+    new Set(stripped).size === stripped.length;
+  return values.map((value, index) => ({ ...value, key: strip ? stripped[index] : value.name }));
+}
+
+/** Converts a PascalCase or camelCase name to UPPER_SNAKE_CASE. */
+function upperSnakeCase(name) {
+  return name.replace(/([a-z0-9])([A-Z])/gu, "$1_$2").toUpperCase();
+}
 
-  return names;
+/** Every enum of `files`, top-level and nested in messages, with its full name. */
+function collectEnums(files) {
+  const enums = [];
+  for (const file of files) {
+    const scope = file.package ?? "";
+    for (const enumType of file.enumType ?? []) {
+      enums.push({ fullName: joinTypeName(scope, enumType.name), enumType });
+    }
+  }
+  for (const { fullName, message } of collectMessages(files)) {
+    for (const enumType of message.enumType ?? []) {
+      enums.push({ fullName: joinTypeName(fullName, enumType.name), enumType });
+    }
+  }
+  return enums;
 }
 
 function collectMessages(files) {
@@ -592,29 +754,35 @@ function collectMessage(messages, fullName, message) {
   }
 }
 
-function generateMessageDeclaration({ fullName, message }, typeNames) {
-  const name = typeNames.get(fullName);
+/**
+ * The two declarations of a message: the decoded shape that calls return and streams yield, in
+ * which every field reads a value (scalars and enums their default, repeated fields and maps an
+ * empty array and object, message and `optional` fields null when unset), and the input shape that
+ * requests take, in which every field may be left out.
+ */
+function generateMessageDeclarations({ fullName, message, name, initName }, context) {
   const mapEntries = new Map(
     (message.nestedType ?? [])
       .filter((nested) => nested.options?.mapEntry)
       .map((nested) => [nested.name, nested]),
   );
-  const fields = (message.field ?? [])
-    .map((field) => generateFieldDeclaration(field, mapEntries, typeNames, fullName))
-    .join("\n");
+  const fields = (shape) =>
+    (message.field ?? [])
+      .map((field) => generateFieldDeclaration(field, mapEntries, shape, context))
+      .join("\n");
+  const body = (shape) => {
+    const declared = fields(shape);
+    return declared === "" ? "{}" : `{\n${declared}\n}`;
+  };
 
-  return `export interface ${name} {\n${fields}\n}`;
+  return `/** A decoded ${fullName} message. */\nexport interface ${name} ${body("output")}\n\n/** A ${fullName} message to send; every field may be left out. */\nexport interface ${initName} ${body("input")}`;
 }
 
-function generateFieldDeclaration(field, mapEntries, typeNames, currentFullName) {
-  const optional = field.label === FieldLabel.Required ? "" : "?";
+function generateFieldDeclaration(field, mapEntries, shape, context) {
+  const optional = shape === "input" && field.label !== FieldLabel.Required ? "?" : "";
   const nullable = decodesAbsentAsNull(field) ? " | null" : "";
-  return `  ${typescriptPropertyName(fieldJsonName(field))}${optional}: ${fieldTypeScriptType(
-    field,
-    mapEntries,
-    typeNames,
-    currentFullName,
-  )}${nullable};`;
+  const type = fieldTypeScriptType(field, mapEntries, shape, context);
+  return `  ${typescriptPropertyName(fieldJsonName(field))}${optional}: ${type}${nullable};`;
 }
 
 /** Reports whether protobuf.js decodes the field as null when it is absent. */
@@ -629,19 +797,23 @@ function decodesAbsentAsNull(field) {
   );
 }
 
-function fieldTypeScriptType(field, mapEntries, typeNames, currentFullName) {
+function fieldTypeScriptType(field, mapEntries, shape, context) {
   const mapEntry = mapEntryForField(field, mapEntries);
   if (mapEntry != null) {
     const [, valueField] = mapEntry.field ?? [];
-    const valueType = scalarTypeScriptType(valueField, typeNames, currentFullName);
-    return `Record<string, ${valueType}>`;
+    return `Record<string, ${scalarTypeScriptType(valueField, shape, context)}>`;
   }
 
-  const scalarType = scalarTypeScriptType(field, typeNames, currentFullName);
-  return field.label === FieldLabel.Repeated ? `${scalarType}[]` : scalarType;
+  const scalarType = scalarTypeScriptType(field, shape, context);
+  return field.label === FieldLabel.Repeated ? `${arrayElementType(scalarType)}[]` : scalarType;
 }
 
-function scalarTypeScriptType(field, typeNames, currentFullName) {
+/** Parenthesizes a union so that it can be an array's element type. */
+function arrayElementType(type) {
+  return type.includes(" | ") ? `(${type})` : type;
+}
+
+function scalarTypeScriptType(field, shape, context) {
   switch (field?.type) {
     case FieldType.Double:
     case FieldType.Float:
@@ -650,14 +822,15 @@ function scalarTypeScriptType(field, typeNames, currentFullName) {
     case FieldType.Sint32:
     case FieldType.Fixed32:
     case FieldType.Sfixed32:
-    case FieldType.Enum:
       return "number";
+    case FieldType.Enum:
+      return declaredName(field.typeName, "output", context) ?? "number";
     case FieldType.Int64:
     case FieldType.Uint64:
     case FieldType.Sint64:
     case FieldType.Fixed64:
     case FieldType.Sfixed64:
-      return "number | string | Long";
+      return int64TypeScriptType(field, shape, context);
     case FieldType.Bool:
       return "boolean";
     case FieldType.String:
@@ -666,36 +839,63 @@ function scalarTypeScriptType(field, typeNames, currentFullName) {
       return "Uint8Array";
     case FieldType.Group:
     case FieldType.Message:
-      return declarationTypeReference(
-        resolveTypeName(field.typeName, typeNames, currentFullName),
-        typeNames,
-      );
+      return messageTypeReference(field.typeName, shape, context);
     default:
       throw new Error(`unsupported protobuf field type ${field?.type}`);
   }
 }
 
-function declarationTypeReference(typeName, typeNames) {
-  return typeNames.get(stripLeadingDot(typeName)) ?? "Record<string, unknown>";
+/**
+ * The type of a 64-bit field: the representation the decoded shape has (the field's `jstype`, or
+ * the generator's `int64` option), and every representation the encoder accepts in the input.
+ */
+function int64TypeScriptType(field, shape, context) {
+  const representation = int64Representation(field, context.model.int64);
+  if (representation === "long") {
+    context.usesLong = true;
+  }
+  if (shape === "input") {
+    return representation === "long"
+      ? "bigint | number | string | Long"
+      : "bigint | number | string";
+  }
+  return representation === "long" ? "Long" : representation;
 }
 
-function resolveTypeName(typeName, typeNames, currentFullName) {
-  const stripped = stripLeadingDot(typeName);
-  if (typeNames.has(stripped)) {
-    return stripped;
+/** How decoded messages represent a 64-bit field: by its `jstype`, else by the `int64` option. */
+function int64Representation(field, representation) {
+  switch (field.options?.jstype) {
+    case JSType.string:
+      return "string";
+    case JSType.number:
+      return "number";
+    default:
+      return representation;
   }
+}
 
-  const scope = currentFullName.split(".");
-  scope.pop();
-  while (scope.length > 0) {
-    const candidate = `${scope.join(".")}.${stripped}`;
-    if (typeNames.has(candidate)) {
-      return candidate;
-    }
-    scope.pop();
-  }
+/**
+ * The declared name of a message type in `shape`, `"output"` or `"input"`, noting the runtime
+ * declarations it uses.
+ */
+function messageTypeReference(typeName, shape, context) {
+  return declaredName(typeName, shape, context) ?? "Record<string, unknown>";
+}
 
-  return stripped;
+/**
+ * The declared name of a message or enum type in `shape` (enums have one for both), or undefined
+ * for a type without a declaration. A name the runtime declares is noted for import.
+ */
+function declaredName(typeName, shape, context) {
+  const entry = context.model.names.get(stripLeadingDot(typeName));
+  if (entry === undefined) {
+    return undefined;
+  }
+  const name = shape === "input" && entry.initName !== undefined ? entry.initName : entry.name;
+  if (entry.shared) {
+    context.runtimeTypes.add(name);
+  }
+  return name;
 }
 
 function joinTypeName(prefix, name) {
@@ -807,6 +1007,13 @@ function fieldToJson(field, mapEntries) {
     // only when this option marks its synthetic oneof.
     json.options = { ...json.options, proto3_optional: true };
   }
+  // The runtime reads it to decode the field as a string or number instead of the root's int64
+  // representation.
+  if (field.options?.jstype === JSType.string) {
+    json.options = { ...json.options, jstype: "JS_STRING" };
+  } else if (field.options?.jstype === JSType.number) {
+    json.options = { ...json.options, jstype: "JS_NUMBER" };
+  }
 
   return json;
 }