From f1af11f9714958a234fe06912c7875e1a6f26155 Mon Sep 17 00:00:00 2001 From: ivanauth Date: Wed, 8 Jul 2026 20:40:05 -0400 Subject: [PATCH] docs: document optional field and zero-value semantics Signed-off-by: ivanauth --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index 42eecf0..54917af 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,25 @@ client.checkPermission(checkPermissionRequest, (err, response) => { }); ``` +### Optional fields + +Many fields in the API are documented as optional (and are often named `optional*`), but scalar fields are not marked optional in the generated TypeScript types. This is expected: the API's Protobuf definitions do not use proto3 `optional`, following the Protobuf convention of treating absent values and zero values as equivalent, and `protobuf-ts` generates those fields as required. + +Leaving such a field "unset" means setting it to its zero value: `""` for strings, `0` for numbers, `false` for booleans, and `[]` for repeated fields. Message-typed fields are the exception; they are generated as optional properties and can be left `undefined`. + +Rather than spelling out zero values by hand, use the `create` method as shown above: any fields not passed to `create` are filled in with their zero values. + +```js +import { v1 } from "@authzed/authzed-node"; + +// optionalResourceId, optionalResourceIdPrefix and optionalRelation +// default to "", and optionalSubjectFilter to undefined, all of which +// the API treats as unset. +const filter = v1.RelationshipFilter.create({ + resourceType: "blog/post", +}); +``` + ### Promises (async/await) support Each method available in the client has an associated promise-style method in place of callbacks, that can be accessed at the `.promises` property on the client.