nullable-new-params

# Nullable new params Use this skill when a change added a new parameter or type member as optional. In internal Remotion code, new inputs must be required and nullable so every caller makes an explicit choice. ## Rule - Internal contracts: write `name: T | null`, not `name?: T`. - Call sites must pass `null` explicitly when no value exists. - Implementation checks should prefer `value === null` / `value !== null` when null is the absence sentinel. - Do not use `undefined` as the absence sentinel for new internal APIs unless the surrounding local contract already standardizes on `undefined`. - The anti-pattern includes redundant shapes such as `frozenFrame?: number | null`; make it `frozenFrame: number | null`. Public APIs are the exception. If the changed signature, props type, or options object is exported from a package public entrypoint or documented in `packages/docs/docs`, making the new field/argument required is a breaking change. Keep it optional or add a backwards-compatible overload/options path, then document/default it as appropriate. ## Workflow 1. Inspect the diff for newly added optional members or parameters: ```sh bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts ``` Useful variants: ```sh bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts origin/main...HEAD bun .agents/skills/nullable-new-params/scripts/find-new-optional-params.ts --cached ``` 2. For each candidate, classify whether it is public: - Public: exported from a package entrypoint, included in package `exports`, or documented in `packages/docs/docs`. - Internal: local helpers, internal component props, cross-file monorepo helpers, test utilities, internal context data, and types not exposed through package entrypoints. - If unsure, grep package entrypoints and docs before changing API shape. 3. For internal candidates, refactor the type from optional to required nullable: ```ts type Before = { readonly frame?: number; }; type After = { readonly frame: number | null; }; ``` For function parameters: ```ts const before = (frame?: number) => {}; const after = (frame: number | null) => {}; ``` 4. Update every caller/object literal to pass the value explicitly: - Use `field: null` when absent. - Preserve existing values with `field: maybeValue ?? null` only when `undefined` can still enter from surrounding code. - Avoid hiding the required choice behind defaults in destructuring. 5. Update implementation logic: - Replace truthy checks when `0`, `''`, or `false` are valid values. - Prefer `value !== null` over `value` for nullable numbers/strings/booleans. - When updating existing tests or fixtures, keep them explicit; do not make large fixtures `Partial<T>` only to dodge the new field. 6. For public candidates, preserve backwards compatibility: - Keep the new field optional in the public type. - Resolve a concrete internal value at the boundary, usually with `const internal = publicValue ?? null`. - Keep internal downstream types required nullable. 7. Verify: - Run the scanner again until only intentional public API exceptions remain. - Run focused tests or package builds for touched packages, for example `bunx turbo run make --filter='<package-name>'`. - If docs changed, follow the `writing-docs` skill. ## Review checklist - No new internal `?:` member or `param?:` parameter remains. - Every internal caller passes either a real value or `null`. - Public APIs remain backwards-compatible. - Nullable checks do not treat valid falsy values as absent. - Verify an explicit `null` path with existing checks or manual verification when behavior depends on absence.