@trevrpc/protovalidate 0.0.0-stage → 1.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 trev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @trevrpc/protovalidate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[protovalidate](https://github.com/bufbuild/protovalidate) request validation for the TrevRPC browser client, [`@trevrpc/trevrpc-js`](https://www.npmjs.com/package/@trevrpc/trevrpc-js): requests that break their [`buf.validate`](https://buf.build/bufbuild/protovalidate) rules fail before they are sent. It is a separate package so that `@trevrpc/trevrpc-js` itself does not depend on protovalidate or CEL.
+
+> **Compatibility:** every TrevRPC package shares one version, and packages of the same version are compatible
+> with each other: `trevrpc-rust` 1.8.0 works with `trevrpc-go` 1.8.0, `trevrpc-js` 1.8.0, and `trevrpc-kotlin`
+> 1.8.0. Compatibility across different versions isn't guaranteed yet; that's a milestone for 2.0.
+
+```sh
+npm install @trevrpc/protovalidate @trevrpc/trevrpc-js @bufbuild/protobuf @bufbuild/protovalidate
+```
+
+Generate the messages with `protoc-gen-es` as usual, with `buf/validate/validate.proto` on the include path (or a `buf.build/bufbuild/protovalidate` dependency in `buf.yaml`), and pass a request validator to `createClient`:
+
+```ts
+import { createClient } from "@trevrpc/trevrpc-js";
+import { createRequestValidator } from "@trevrpc/protovalidate";
+import { ViolationsSchema } from "@bufbuild/protovalidate/gen/buf/validate/validate_pb.js";
+
+import { Users } from "./gen/users/v1/users_pb.js";
+
+const users = createClient(Users, channel, { validator: createRequestValidator() });
+
+try {
+  await users.create({ name: "", email: "ada@example.com" });
+} catch (error) {
+  // Code.InvalidArgument, whether the client or a validating server rejected it.
+  for (const { violations } of error.findDetails(ViolationsSchema)) {
+    for (const violation of violations) console.log(violation.field, violation.message);
+  }
+}
+```
+
+- A request message that breaks its rules is not sent, and fails with `InvalidArgument` and a `buf.validate.Violations` status detail, as the Go and Rust servers report it, so one error handler serves both. The message names the first violation and counts the rest. The request of a unary or server-streaming call fails the call, after its interceptors ran; a message passed to `send()` of a client-streaming or bidirectional call rejects that send, and the call goes on.
+- A rule that cannot be evaluated for a message fails it with `Internal`.
+- `createClient` compiles the rules of each method's request type, and throws a `TrevRpcError` with `Code.Internal` when one cannot compile.
+- Methods whose request type has no rules, directly or in a message it holds, are not checked and cost nothing.
+- `createRequestValidator(validator?)` takes a protovalidate validator, by default one from `createValidator()`. Pass `createValidator({ registry })`, with a registry that holds their extensions, to enforce predefined rules, or `createValidator({ failFast: true })` to stop at the first violation.
+
+Checking requests on the client saves a round trip and shows the violations at once. It does not replace checking them on the server, with [`protovalidatetrevrpc`](https://trev.zip/llc/TrevRPC/src/branch/main/trevrpc-go/protovalidatetrevrpc) or [`trevrpc-protovalidate`](https://trev.zip/llc/TrevRPC/src/branch/main/trevrpc-rust/crates/trevrpc-protovalidate), since clients can skip it.
+
+See [Request Validation](https://trev.zip/llc/TrevRPC/wiki/JavaScript-Guide#request-validation).
+
+## Development
+
+The package is developed against the trevrpc-js of this checkout, which it links as `file:..`, so install that first:
+
+```sh
+npm ci --prefix ..
+npm ci
+npm run check      # format check, lint, typecheck, tests
+```
+
+The tests run the real client against the in-memory server of trevrpc-js's own tests. `nix build .#trevrpc-js-protovalidate` runs them against the built trevrpc-js, and checks the published files.

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@trevrpc/protovalidate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.8.0",
+  "description": "protovalidate request validation for TrevRPC browser clients",
+  "homepage": "https://trev.zip/llc/TrevRPC",
+  "bugs": {
+    "url": "https://trev.zip/llc/TrevRPC/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://trev.zip/llc/TrevRPC.git",
+    "directory": "trevrpc-js/protovalidate"
+  },
+  "files": [
+    "src/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node test/generate.js",
+    "format": "oxfmt --write",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint --deny-warnings src test",
+    "typecheck": "npm run build && tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.js",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test"
+  },
+  "devDependencies": {
+    "@bufbuild/protobuf": "^2.17.0",
+    "@bufbuild/protoc-gen-es": "^2.17.0",
+    "@bufbuild/protovalidate": "^1.3.0",
+    "@trevrpc/trevrpc-js": "file:..",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "@bufbuild/protobuf": "^2.17.0",
+    "@bufbuild/protovalidate": "^1.3.0",
+    "@trevrpc/trevrpc-js": "^1.8.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "npm@12.2.2"
+}

package/src/index.d.ts

@@ -0,0 +1,19 @@
+import type { Validator } from "@bufbuild/protovalidate";
+import type { RequestValidator } from "@trevrpc/trevrpc-js";
+
+/**
+ * Returns a request validator for the `validator` option of `createClient` in
+ * `@trevrpc/trevrpc-js`, which enforces the `buf.validate` rules of request messages with
+ * `validator`, or with one that protovalidate's `createValidator()` makes when it is undefined.
+ * Pass a validator made with `createValidator({ registry })` to enforce predefined rules.
+ *
+ * A request message that breaks its rules is not sent: it fails with `Code.InvalidArgument` and a
+ * `buf.validate.Violations` detail, which `error.findDetails(ViolationsSchema)` decodes, as TrevRPC
+ * servers report requests that break them. One whose rules cannot be evaluated fails with
+ * `Code.Internal`. Methods whose request type has no rules, directly or in a message it holds,
+ * are not checked and cost nothing.
+ *
+ * `createClient` compiles the rules of each request type that has some, and throws a TrevRpcError
+ * with `Code.Internal` when they cannot compile.
+ */
+export function createRequestValidator(validator?: Validator): RequestValidator;

package/src/index.js

@@ -0,0 +1,97 @@
+import { create, hasOption, toBinary } from "@bufbuild/protobuf";
+import { createValidator, violationsToProto } from "@bufbuild/protovalidate";
+import {
+  ViolationsSchema,
+  field as fieldRules,
+  message as messageRules,
+  oneof as oneofRules,
+} from "@bufbuild/protovalidate/gen/buf/validate/validate_pb.js";
+import { Code, TrevRpcError } from "@trevrpc/trevrpc-js";
+
+/**
+ * Returns a request validator for the `validator` option of `createClient`, which enforces the
+ * `buf.validate` rules of request messages with `validator`, a protovalidate validator, or with
+ * one that `createValidator()` makes when it is undefined.
+ */
+export function createRequestValidator(validator = createValidator()) {
+  return {
+    validateFunc(schema) {
+      if (!hasRules(schema, new Set())) {
+        return undefined;
+      }
+      // Compiles the rules now, through the validator's cache, so a rule that cannot compile fails
+      // createClient instead of the first call.
+      const compiled = validator.validate(schema, create(schema));
+      if (compiled.kind === "error") {
+        throw new TrevRpcError(
+          Code.Internal,
+          `cannot validate ${schema.typeName}: ${compiled.error.message}`,
+          {},
+          { cause: compiled.error },
+        );
+      }
+      return (message) => {
+        const result = validator.validate(schema, message);
+        if (result.kind !== "valid") {
+          throw statusFromResult(result);
+        }
+      };
+    },
+  };
+}
+
+/**
+ * Converts a failed protovalidate result into the error a request fails with: InvalidArgument
+ * with a `buf.validate.Violations` detail for broken rules, as TrevRPC servers report them, and
+ * Internal for rules that could not be evaluated.
+ */
+function statusFromResult(result) {
+  if (result.kind === "error") {
+    return new TrevRpcError(
+      Code.Internal,
+      `request validation failed: ${result.error.message}`,
+      {},
+      { cause: result.error },
+    );
+  }
+  const { violations } = result;
+  if (violations.length === 0) {
+    return new TrevRpcError(Code.InvalidArgument, "validation error", {}, { cause: result.error });
+  }
+  let message = `validation error: ${violations[0]}`;
+  if (violations.length > 1) {
+    message += ` (and ${violations.length - 1} more)`;
+  }
+  const [listed] = violationsToProto(violations);
+  return new TrevRpcError(
+    Code.InvalidArgument,
+    message,
+    {},
+    {
+      cause: result.error,
+      details: [{ type: ViolationsSchema.typeName, value: toBinary(ViolationsSchema, listed) }],
+    },
+  );
+}
+
+/**
+ * Reports whether `schema`, or a message type it holds however deep, carries `buf.validate`
+ * rules. `seen` breaks recursive types.
+ */
+function hasRules(schema, seen) {
+  if (seen.has(schema.typeName)) {
+    return false;
+  }
+  seen.add(schema.typeName);
+  if (hasOption(schema, messageRules)) {
+    return true;
+  }
+  if (schema.oneofs.some((oneof) => hasOption(oneof, oneofRules))) {
+    return true;
+  }
+  return schema.fields.some(
+    (field) =>
+      hasOption(field, fieldRules) ||
+      (field.message !== undefined && hasRules(field.message, seen)),
+  );
+}