docs(sdk): clarify hook value nullability in tailordb examples

[dqn]

Docs-only fix surfaced by the llm-challenge benchmark: TailorDB hook examples were silently bypassing the value argument, leading agents that read docs to omit null fallbacks even though the type defines value as T | null.

Why

packages/sdk/src/configure/services/tailordb/types.ts:9-20 defines hook inputs as HookFn<TReturn | null, TData, TReturn>. The runtime injects null for value when the user omits the field on create, or on update when the field is absent from the mutation input.

Docs prose mentioned this nullability on one bullet line, but every code example sidestepped value:

• create: ({ user }) => user.id (ignored value)
• update: ({ value }) => value (passthrough, doesn't transform)
• create/update: ({ data }) => ... (used data, not value)

No example demonstrated value ?? "" or any explicit null handling. Agents that read docs internalize the bypass pattern and write value.toLowerCase(), which fails at runtime (and at typecheck if strictNullChecks is on).

Evidence

A/B experiment via pnpm challenge:experiment on m05-db-type-hooks-create (a problem that asks for a lowercase-normalizing create hook):

Metric	Baseline (main)	Candidate (this branch)	Delta
iteration passRate	1/3 (33.3%)	3/3 (100%)	+66.7 pp
cost per pass	$0.1275	$0.0714	-40%
turns median	15	11	-4
readDocs median	1	1	0 (still reads, but now learns correct pattern)

All three iterations on the candidate converged on the reference solution shape:

create: ({ value }) => (value ?? "").toLowerCase();

Baseline iterations wrote two value.toLowerCase() (typecheck fail) and one value!.toLowerCase() (non-null assertion workaround).

What changed

• Sharpened the value bullet in the hook input contract to explicitly note T | null and the value ?? "" idiom.
• Updated the first hook example to demonstrate transforming value with the null fallback ((value ?? "").toLowerCase()).
• Split the second example to keep the "derive from user" pattern visible while clarifying that it explicitly ignores value.

No source code or type changes. The types already encoded the contract; the examples now reinforce what the types say.

Notes

Validated only against m05 because that was the problem whose full-package iteration passRate diverged from types-only in the benchmark. A follow-up sweep should grep for the same anti-pattern in other SDK docs (resolver / executor argument handling) that transform nullable inputs.

llm-challenge benchmark harness lives in PR #1148.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 16a73b1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

⚡ pkg.pr.new

@tailor-platform/sdk

pnpm add https://pkg.pr.new/@tailor-platform/sdk@16a73b1

pnpm dlx https://pkg.pr.new/@tailor-platform/sdk@16a73b1 --help

@tailor-platform/create-sdk

pnpm add https://pkg.pr.new/@tailor-platform/create-sdk@16a73b1

pnpm dlx https://pkg.pr.new/@tailor-platform/create-sdk@16a73b1 my-app

commit: 16a73b1

[github-actions]

Code Metrics Report (packages/sdk)

	main (6c3a2cb)	#1167 (903307e)	+/-
Coverage	61.9%	61.9%	0.0%
Code to Test Ratio	1:0.4	1:0.4	0.0

Details

  |                    | main (6c3a2cb) | #1167 (903307e) | +/-  |
  |--------------------|----------------|-----------------|------|
  | Coverage           |          61.9% |           61.9% | 0.0% |
  |   Files            |            363 |             363 |    0 |
  |   Lines            |          12636 |           12636 |    0 |
  |   Covered          |           7827 |            7827 |    0 |
  | Code to Test Ratio |          1:0.4 |           1:0.4 |  0.0 |
  |   Code             |          82628 |           82628 |    0 |
  |   Test             |          34422 |           34422 |    0 |

SDK Configure Bundle Size

	main (6c3a2cb)	#1167 (903307e)	+/-
configure-index-size	17.84KB	17.84KB	0KB
dependency-chunks-size	33.56KB	33.56KB	0KB
total-bundle-size	51.39KB	51.39KB	0KB

Runtime Performance

	main (6c3a2cb)	#1167 (903307e)	+/-
Generate Median	2,406ms	2,565ms	159ms
Generate Max	2,483ms	2,731ms	248ms
Apply Build Median	2,434ms	2,604ms	170ms
Apply Build Max	2,469ms	2,630ms	161ms

Type Performance (instantiations)

	main (6c3a2cb)	#1167 (903307e)	+/-
tailordb-basic	35,130	35,130	0
tailordb-optional	3,841	3,841	0
tailordb-relation	7,428	7,428	0
tailordb-validate	2,566	2,566	0
tailordb-hooks	5,767	5,767	0
tailordb-object	12,136	12,136	0
tailordb-enum	2,462	2,462	0
resolver-basic	9,424	9,424	0
resolver-nested	26,111	26,111	0
resolver-array	18,187	18,187	0
executor-schedule	4,234	4,234	0
executor-webhook	873	873	0
executor-record	8,166	8,166	0
executor-resolver	4,369	4,369	0
executor-operation-function	869	869	0
executor-operation-gql	869	869	0
executor-operation-webhook	888	888	0
executor-operation-workflow	1,714	1,714	0

---

Reported by octocov