Update examples (#68)

Author: timostamm

packages/example/README.md

@@ -1,18 +1,10 @@
-# protovalidate example
+# Protovalidate examples
 
-This directory contains an example that uses protovalidate to validate a money
-transfer. 
+This package contains examples for using `@bufbuild/protovalidate`.
 
-The transfer is defined as a Protobuf message in [money_transfer.proto](./proto/banking/v1/money_transfer.proto). It uses annotations to set up protovalidate rules on the message.
+### Requirements
 
-After generating code for the Protobuf message, it can be validated with 
-`createValidator()` from `@bufbuild/protovalidate`. [src/index.ts](./src/index.ts)
-creates a money transfer, validates it, and prints the results on the terminal.
-
-
-### Run the example
-
-You need [Node](https://nodejs.org/en/download/) version 20 or later installed. Download the example project
+You need [Node.js](https://nodejs.org/en/download/) version 20 or later installed. Download the example project
 and install its dependencies:
 
 ```shell
@@ -23,6 +15,10 @@ cd protovalidate-es-main/packages/example
 npm install
 ```
 
+### Basic example
+
+This example shows basic usage. We're validating a money transfer, defined as a Protobuf message in [money_transfer.proto](./proto/banking/v1/money_transfer.proto).
+
 Run the example:
 
 ```shell
@@ -33,20 +29,27 @@ This prints the following result:
 
 > Transfer is valid!
 
-Modify the transfer in [src/index.ts](./src/index.ts) and re-run the example to see different results.
-
-
-### Generate code
-
-If you want to use the [Buf CLI](https://github.com/bufbuild/buf) to generate the code,
-simply run `npx buf generate` in this directory. [`buf.gen.yaml`](./buf.gen.yaml)
-contains the plugin configuration.
+Modify the transfer in [src/basic.ts](./src/index.ts) and re-run the example to see different results.
 
 
 ### Valid types
 
 Protovalidate rules can modify TypeScript types. A message field annotated with protovalidate's [`required` rule](https://buf.build/docs/reference/protovalidate/rules/field_rules/#required) becomes a required property.
 
 See [order.proto](./proto/store/v1/order.proto) and [src/valid-types.ts](./src/valid-types.ts) for an example,
-and take a look at the [Valid types](https://github.com/bufbuild/protobuf-es/blob/v2.5.0/MANUAL.md#valid-types)
+and take a look at the [Valid types](https://github.com/bufbuild/protobuf-es/blob/v2.6.1/MANUAL.md#valid-types)
 section in the Protobuf-ES manual.
+
+
+### Standard Schema v1
+
+Protovalidate-ES supports [Standard Schema v1](https://github.com/standard-schema/standard-schema). See [src/standard-schema](./src/standard-schema.ts) for an example.
+
+
+### Generate code
+
+If you modify the rules of one of the Protobuf messages, make sure to re-generate the code. 
+
+With the [Buf CLI](https://github.com/bufbuild/buf), simply run `npx buf generate` in this directory. [`buf.gen.yaml`](./buf.gen.yaml)
+contains the plugin configuration.
+

packages/example/buf.lock

@@ -2,5 +2,5 @@
 version: v2
 deps:
   - name: buf.build/bufbuild/protovalidate
-    commit: 8976f5be98c146529b1cc15cd2012b60
-    digest: b5:5d513af91a439d9e78cacac0c9455c7cb885a8737d30405d0b91974fe05276d19c07a876a51a107213a3d01b83ecc912996cdad4cddf7231f91379079cf7488d
+    commit: 6c6e0d3c608e4549802254a2eee81bc8
+    digest: b5:a7ca081f38656fc0f5aaa685cc111d3342876723851b47ca6b80cbb810cbb2380f8c444115c495ada58fa1f85eff44e68dc54a445761c195acdb5e8d9af675b6

packages/example/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "license": "Apache-2.0",
   "scripts": {
-    "start": "tsx src/index.ts",
+    "start": "tsx src/basic.ts",
     "generate": "buf generate",
     "postgenerate": "license-header src/gen",
     "build": "tsc --project tsconfig.json --outDir ./dist/esm",

packages/example/src/index.ts renamed to packages/example/src/basic.ts

@@ -14,53 +14,41 @@
 
 import { create } from "@bufbuild/protobuf";
 import { createStandardSchema } from "@bufbuild/protovalidate";
-import {
-  OrderSchema,
-  type OrderValid,
-  type User,
-} from "./gen/store/v1/order_pb.js";
+import { OrderSchema, type OrderValid } from "./gen/store/v1/order_pb.js";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 
-async function standardValidate<T extends StandardSchemaV1>(
-  schema: T,
-  input: StandardSchemaV1.InferInput<T>,
-): Promise<StandardSchemaV1.Result<StandardSchemaV1.InferOutput<T>>> {
-  const result = schema["~standard"].validate(input);
-  // Handle both sync and async results
-  return Promise.resolve(result);
-}
-
-const order = create(OrderSchema, {
-  id: "ed1cb800-75cb-4e4c-95ab-e093a7f23e55",
-  user: {
-    // This field is required. Once validation passes, it will always be defined.
-    name: "John Doe",
-  },
-});
-
 async function main() {
+  const order = create(OrderSchema, {
+    id: "ed1cb800-75cb-4e4c-95ab-e093a7f23e55",
+    // The field `user` is required. Once validation passes, it will always be defined.
+    // user: {
+    //   name: "John Doe",
+    // },
+  });
+
   const schema = createStandardSchema(OrderSchema);
   const result = await standardValidate(schema, order);
 
   if (result.issues !== undefined) {
-    console.log(`invalid order ${result.issues}`);
-    return;
+    console.error(`invalid order: ${result.issues[0].message}`);
+    process.exit(1);
   }
 
   // If there are no issues, the result is valid.
-  processOrder(result.value);
-}
-
-main();
-
-function processOrder(order: OrderValid) {
-  console.log(`processing order ${order.id}`);
+  const validOrder: OrderValid = result.value;
   // On the Valid type, the `user` property isn't optional, because
   // the field is annotated with the protovalidate required rule.
-  setUserActive(order.user);
-  return true;
+  console.log(`user ${validOrder.user.name} has ordered something`);
 }
 
-function setUserActive(user: User) {
-  console.log(`user ${user.name} has ordered something`);
+void main();
+
+// Placeholder for any framework that support the standard schema.
+async function standardValidate<T extends StandardSchemaV1>(
+  schema: T,
+  input: StandardSchemaV1.InferInput<T>,
+): Promise<StandardSchemaV1.Result<StandardSchemaV1.InferOutput<T>>> {
+  const result = schema["~standard"].validate(input);
+  // Handle both sync and async results
+  return Promise.resolve(result);
 }

packages/example/src/gen/buf/validate/validate_pb.ts

@@ -14,19 +14,16 @@
 
 import { create } from "@bufbuild/protobuf";
 import { createValidator } from "@bufbuild/protovalidate";
-import {
-  OrderSchema,
-  type OrderValid,
-  type User,
-} from "./gen/store/v1/order_pb";
+import { OrderSchema, type OrderValid } from "./gen/store/v1/order_pb";
 
 const validator = createValidator({
-  // This option enabled validation of the proto2 `required` label.
+  // This option enables validation of the proto2 `required` label.
   legacyRequired: true,
 });
 
 const order = create(OrderSchema, {
   id: "ed1cb800-75cb-4e4c-95ab-e093a7f23e55",
+  // The field `user` is required. Once validation passes, it will always be defined.
   user: {
     name: "John Doe",
   },
@@ -36,20 +33,11 @@ const result = validator.validate(OrderSchema, order);
 
 switch (result.kind) {
   case "valid":
-    processOrder(result.message);
+    const validOrder: OrderValid = result.message;
+    // On the Valid type, the `user` property isn't optional, because
+    // the field is annotated with the protovalidate required rule.
+    console.log(`user ${validOrder.user.name} has ordered something`);
     break;
   default:
     throw result.error;
 }
-
-function processOrder(order: OrderValid) {
-  console.log(`processing order ${order.id}`);
-  // On the Valid type, the `user` property isn't optional, because
-  // the field is annotated with the protovalidate required rule.
-  setUserActive(order.user);
-  return true;
-}
-
-function setUserActive(user: User) {
-  console.log(`user ${user.name} has ordered something`);
-}