create-validated-function

name	create-validated-function
description	Scaffold one function using the validated-function pattern — a factory that injects dependencies and wraps an inner fn with Zod validation + structured error handling, plus its sinon test. Use when adding a service/data function to an existing repo, or runs /ps:create-validated-function.
license	MIT
metadata	{"author":"psanders","version":"1.0"}

Create validated function — scaffold one the right way

Add a single unit of business logic using the validated-function pattern: a factory that injects dependencies and wraps a typed inner fn with withErrorHandlingAndValidation(fn, schema), so invalid input throws a structured ValidationError before the operation runs and tests inject stubs with zero mocking machinery. One function, one file, one test.

This is the on-demand counterpart to /ps:bootstrap (which stands up a whole repo). The canonical shapes live in bootstrap's templates — reuse them, don't reinvent:

• ../bootstrap/references/templates/widget.schema.ts — the schema shape
• ../bootstrap/references/templates/createCreateWidget.ts — the function shape
• ../bootstrap/references/templates/createCreateWidget.test.ts — the test shape
• ../bootstrap/references/conventions.md § "THE validated-function pattern" — the rationale

When to use

Adding an input-validating operation (DB write, service call, business logic) to an existing repo. Skip for trivial pure helpers or framework glue — the pattern earns its keep only when there's external input to validate.

Detect the repo's conventions first

Don't hardcode paths — read them from the repo:

• Shared package + scope: find the common workspace and its package name (e.g. @acme/common) from the root package.json workspaces and CLAUDE.md. Schemas, types, errors, and the withErrorHandlingAndValidation util live there.
• Domain home: where service functions live (e.g. src/api/<domain>/ or mods/<service>/src/...). Match the surrounding layout.
• Spine present?: confirm withErrorHandlingAndValidation and ValidationError already exist in the shared package. If not, copy them from ../bootstrap/references/templates/{withErrorHandlingAndValidation,ValidationError}.ts first.

Steps

1. Schema — in the shared package's schemas/. Use zod/v4; give every field a message; .transform() to normalize at the edge (trim, E.164, canonical forms). Derive the type with z.infer — never hand-write it. Add a separate update*Schema exposing only mutable fields if the operation needs one. Re-export from the schemas barrel.

2. Client interface — reuse an existing one from the shared package's types/; add a new minimal interface there only if needed. The factory depends on this interface, not a concrete client, so tests can stub it.

3. Function — create<Name>.ts in the domain dir. Factory takes the injected client; inner typed fn (params: <Name>Input) does the work with verbose entry/exit logging (ids and safe fields only — never secrets/PII); return withErrorHandlingAndValidation(fn, <name>Schema). Re-export from the domain barrel index.ts.

4. Transport (if applicable) — if the repo exposes this over tRPC, add a thin procedure that picks the auth level, .input(theSameSchema), and delegates to create<Name>. No business logic in the router.

5. Test — create<Name>.test.ts, one per function. Inject a sinon-stubbed client; Arrange/Act/Assert; sinon.restore() in afterEach. Always include a validation-failure case asserting ValidationError is thrown and the side effect never fired.

Finish

• Follow the repo's own conventions (CLAUDE.md) for ESM .js import specifiers, copyright headers, and i18n — defer to them, don't restate.
• Run the repo's typecheck + test; the new test must pass. Report results honestly.

Rules

• One function per file, create<Name>.ts — greppable, small blast radius.
• Factory + DI — no module-level singletons; the client is always injected.
• Schema is the single source of truth for the input type (z.infer).
• Every function ships with its test, including the validation-failure path.