fix(client): name the received runtime type in search-attribute errors

Copilot review on #354: typeof reports "object" for arrays, Dates, and
null; a describeRuntimeType helper now spells those out. Also stops
labeling zod a peer dependency in the README and tutorial — the packages
require any Standard Schema validator.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: btravers

README.md

@@ -142,8 +142,11 @@ pnpm add @temporal-contract/contract@beta @temporal-contract/worker@beta \
          @temporal-contract/client@beta
 
 # Peer dependencies (stable releases)
-pnpm add unthrown zod \
+pnpm add unthrown \
   @temporalio/client @temporalio/common @temporalio/worker @temporalio/workflow
+
+# Plus one Standard Schema validator of your choice — zod, valibot, arktype, …
+pnpm add zod
 ```
 
 Requires **Node.js ≥ 22.19**, ESM (`"type": "module"`), and TypeScript `strict`.

docs/tutorial/your-first-workflow.md

@@ -46,7 +46,8 @@ npm install -D typescript @types/node tsx
 temporal-contract 8.0 — the API this tutorial teaches — is currently a
 prerelease published under the `beta` dist-tag. Without `@beta`, npm installs
 the 7.x line, and the code in this tutorial will not match. The peers
-(`unthrown`, `@temporalio/*`, `zod`) are stable releases.
+(`unthrown`, `@temporalio/*`) and `zod` — this tutorial's pick of
+[Standard Schema](https://standardschema.dev/) validator — are stable releases.
 :::
 
 Create a `tsconfig.json`. The two settings that matter are `module: nodenext`

packages/client/src/client.spec.ts

@@ -2369,4 +2369,30 @@ describe("ContractClient — search attribute VALUE validation (runtime)", () =>
     }
     expect(mockWorkflow.start).not.toHaveBeenCalled();
   });
+
+  it('names the received runtime type instead of typeof\'s blanket "object"', async () => {
+    const client = await bindContract(kindContract, {
+      workflow: mockWorkflow,
+      schedule: mockSchedule,
+    } as unknown as Client);
+
+    const cases: Array<{ value: unknown; reported: string }> = [
+      { value: new Date("2026-01-01T00:00:00Z"), reported: "a Date" },
+      { value: ["not", "an", "int"], reported: "an array" },
+      { value: null, reported: "null" },
+    ];
+    for (const { value, reported } of cases) {
+      const result = await client.startWorkflow("kinds", {
+        workflowId: "k-4",
+        args: { id: "a" },
+        searchAttributes: { priority: value as unknown as number },
+      });
+
+      expect(result).toBeDefect();
+      if (result.isDefect()) {
+        expect((result.cause as RuntimeClientError).message).toContain(`received ${reported}.`);
+      }
+    }
+    expect(mockWorkflow.start).not.toHaveBeenCalled();
+  });
 });

packages/client/src/internal.ts

@@ -70,6 +70,18 @@ const searchAttributeValueChecks: Record<
   },
 };
 
+/**
+ * Name a value's runtime type for error messages. `typeof` alone reports
+ * `"object"` for arrays, `Date`s, and `null` — the three shapes search
+ * attributes actually trip over — so spell those out.
+ */
+function describeRuntimeType(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  if (value instanceof Date) return "a Date";
+  return `a ${typeof value}`;
+}
+
 /**
  * Translate the contract's typed `searchAttributes` map (declared
  * name → value) into a Temporal `TypedSearchAttributes` instance, so the
@@ -121,7 +133,7 @@ export function toTypedSearchAttributes(
         "searchAttributes",
         new Error(
           `Search attribute "${name}" on workflow "${workflowName}" is declared as ` +
-            `${def.kind} and must be ${expected}; received ${typeof value}.`,
+            `${def.kind} and must be ${expected}; received ${describeRuntimeType(value)}.`,
         ),
       );
     }