From 16a73b1d37f73b3383b08abcbab4055a18a3206b Mon Sep 17 00:00:00 2001 From: dqn Date: Wed, 13 May 2026 16:39:21 +0900 Subject: [PATCH] docs(sdk): clarify hook value nullability in tailordb examples The Hook type signature on the configure layer types value as T | null for both create and update hooks, but every example in the docs sidesteps value or simply passes it through. AI codegen tools (and humans) regularly miss this nullability and write value.toLowerCase() / value.length on a possibly null input, producing TypeErrors at runtime. - Tighten the value bullet to state the T | null type explicitly and call out that update hooks do NOT auto-inject the existing value. - Replace the trivial passthrough example with a transform that uses the documented value ?? "" fallback pattern. - Add a sibling example that derives from user, so the prior intent of showing both forms is preserved. --- packages/sdk/docs/services/tailordb.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/sdk/docs/services/tailordb.md b/packages/sdk/docs/services/tailordb.md index 5d464fe4c..1887cbd34 100644 --- a/packages/sdk/docs/services/tailordb.md +++ b/packages/sdk/docs/services/tailordb.md @@ -258,7 +258,7 @@ type User { Add hooks to execute functions during data creation or update. Hooks receive three arguments: -- `value`: User input if provided, otherwise existing value on update or null on create +- `value`: Field input value, **typed as `T | null`**. It is `null` when the user omitted the field on create; on update, it is `null` when the user did not include the field in the mutation input (existing values are not auto-injected). Always handle the `null` case (e.g. `value ?? ""`) before calling string/number methods on it. - `data`: Entire record data (for accessing other field values) - `user`: User performing the operation @@ -268,8 +268,14 @@ Set hooks directly on individual fields: ```typescript db.string().hooks({ + // `value` is `string | null`, so fall back to "" before calling string methods. + create: ({ value }) => (value ?? "").toLowerCase(), + update: ({ value }) => (value ?? "").toLowerCase(), +}); + +// Hooks can also derive a value from other inputs and ignore `value` entirely. +db.uuid().hooks({ create: ({ user }) => user.id, - update: ({ value }) => value, }); ```