feat(schema): add optional fallbacks and automatic named references by andrewzolotukhin · Pull Request #230 · cleverbrush/framework

andrewzolotukhin · 2026-09-28T20:23:49Z

Original request

Implement Framework schema-composition improvements against development, with JSDoc, documentation, unit/type tests and minor changesets. Keep optional fallback values and named definitions with local annotations; explicit input/output typing remains removed.

Following review, use automatic references through ordinary modifiers instead of schemaRef. In the latest review cleanup, remove the standalone guide and declaration-inspection test, and consolidate the new website page into existing documentation.

Xpenser and the temporary consumer-experience document are not modified.

What changed

Optional/nullable-aware .catch(...) and preprocessor return types accept undefined/null when the schema permits them.
Ordinary presence, nullability, annotation and type-only modifiers retain the original canonical named definition. Concrete builder types, fluent methods and extensions remain available.
Shape/rule edits, callbacks, defaults, fallbacks, clear methods and extension changes discard inherited names and canonical associations. Explicit schemaName creates a fresh independent definition.
JSON Schema Draft 07/2020-12, OpenAPI and AsyncAPI preserve local annotations/nullability and reuse canonical components, including recursion. Independent definitions sharing a name still fail.
Removed the proposed wrapper API and its implementation. No explicit input/output APIs or directional components remain.
Consolidated fallback/preprocessing and naming guidance into existing README sections and the modifier reference page; API-export guidance lives in existing JSON Schema and OpenAPI/AsyncAPI documentation.
Removed BOUNDARIES.md, the unmerged “Schemas Across Boundaries” website page, its route/navigation entries and incoming links. No replacement documentation file or redirect was added.
Removed boundaries-docs.test.ts without relocating its emitted-declaration parsing assertions. JSDoc and all behavioral/type/API-document regression tests remain.
The latest follow-up changes documentation and removes that one documentation-only test; runtime source and functional tests are unchanged from cbc2f14a.
Existing minor changesets cover schema, schema-json and server-openapi. No package version, dependency or lockfile changes.

Consumer example

const User = object({ name: string() }).schemaName('User');
const History = object({
    current: User,
    previous: User.optional().nullable().describe('Previous user')
});

const PatchUser = User.partial(); // unnamed, changed shape
const PublicUser = User.addProp('id', number()).schemaName('PublicUser');

Reasoning

Ordinary immutable builders provide the desired consumer experience without an extra wrapper. Canonical-reference metadata supports exporters without changing runtime validation.

Naming intentionally changes for shape/rule edits: apply schemaName after those edits when the result needs a stable component name. Use-site modifiers retain canonical identity; independently named definitions still conflict.

Legacy optional schemas continue accepting null at runtime even when inference excludes it. Existing documentation now explains why .optional().catch(undefined) leaves null unchanged and how to normalize explicitly.

Documentation belongs alongside the corresponding APIs rather than in a duplicate guide/page. The declaration-inspection test only asserted JSDoc presence, not feature behavior; it is removed while retaining JSDoc, runtime/type coverage and normal TypeDoc generation.

Blog post

Skipped: library/API review and documentation cleanup, not an application-facing feature.

Screenshots / preview evidence

No Framework PR preview environment is configured, so preview screenshots/browser QA are unavailable. Both existing documentation sites were typechecked; moved examples were exercised against built packages, and guidance placement and links were checked locally. TypeDoc HTML was generated into temporary output without modifying tracked snapshots.

Validation

Retained regression coverage

Canonical identity across all concrete builders; direct reuse and chained modifiers; explicit renaming and strict independent-name conflicts; structural/rule/extension detachment; optional fallbacks and legacy null behavior; defaults and async callbacks; nested selectors/errors and type inference; JSON Schema/OpenAPI/AsyncAPI annotations, mixed inline/named graphs and recursion.

andrewzolotukhin · 2026-09-29T08:41:52Z

    "files": [
-        "dist"
+        "dist",
+        "BOUNDARIES.md"


why did we add this? remove it from here

Addressed in cbc2f14. Removed BOUNDARIES.md from files; the package ships dist as before. The guide remains in the repository, and published README links now point to that repository copy. Verified with npm pack --dry-run that the guide is excluded.

andrewzolotukhin · 2026-09-29T08:53:41Z

+        const user = object({ address: schemaRef(address) }).schemaName('User');
+        const root = object({ user: schemaRef(user) });


If we don't apply modifiers (like .optional(), etc) there is no need to use schemaRef wrapping. We should be able to use a plain schema in this case. Ideally I would not have schemaRef at all, but I don't know if it's possible.

Addressed in cbc2f14 using the agreed automatic-reference approach. schemaRef and ReferenceSchemaBuilder are removed completely. Use the plain constant directly, or ordinary calls such as User.optional().nullable().describe(...); these preserve its canonical definition without changing the concrete builder. Property/constraint/callback/default/fallback/extension changes discard the inherited name and canonical association, and .schemaName('NewName') establishes a new independent definition. Docs, JSDoc and regression tests cover the policy, name conflicts, JSON Schema/OpenAPI/AsyncAPI and recursion. Local gates pass (4,348 tests); GitHub checks are running.

andrewzolotukhin · 2026-09-29T10:33:56Z

+`InferType<S>` continues to mean validated output;
+existing builder generic arguments and legacy preprocessors keep their meaning.
+
+## Optional fallbacks
+
+Before, consumers needed a separate safeParse helper for each optional scalar.
+Now a fallback can use the optional or nullable schema's full output type:
+
+```ts
+import { boolean, object, string } from '@cleverbrush/schema';
+
+const optionalText = string().optional().catch(undefined);
+const ExternalRecord = object({
+    name: optionalText,
+    enabled: boolean().optional().catch(() => undefined)
+});
+ExternalRecord.parse({ name: 42, enabled: 'unknown' });
+// { name: undefined, enabled: undefined }
+```
+
+Fallbacks are opt-in. A malformed required root object still fails. Arrays do
+not silently discard invalid elements. A fallback factory runs only on failure.
+
+**Compatibility limitation:** legacy optional schemas also accept `null` at
+runtime, even though their inferred type does not include it. This release does
+not change that behavior. Consequently, `.optional().catch(undefined)` leaves
+`null` unchanged. Normalize it explicitly when the application requires this:
+
+```ts
+const normalizedText = string().optional()
+    .addPreprocessor(value => value == null ? undefined : value)


I don't think we need this file at all, just update corresponding documents/readme/etc instead of creation of a new file.

Addressed in 89abbf5. Removed BOUNDARIES.md and moved its guidance into the existing README fallback/schemaName/API-export sections. Following the agreed cleanup, also removed the new “Schemas Across Boundaries” website page and its route/navigation entries; the content now lives in the existing modifier, JSON Schema and OpenAPI reference pages. All links point to existing sections, with no replacement guide file.

andrewzolotukhin · 2026-09-29T10:41:00Z

I don't think we need these tests at all, they look weird, or if we absolutely need them, let's add them to existing test files.

Addressed in 89abbf5. Removed boundaries-docs.test.ts entirely instead of moving the generated-declaration/JSDoc inspection assertions elsewhere. JSDoc and every behavioral, type-inference and API-document regression test remain unchanged. Local validation passes: 4,347 tests in 188 files, build, lint, both site typechecks, and TypeDoc generation (zero errors). GitHub checks are running on the follow-up commit.

andrewzolotukhin added 3 commits September 28, 2026 20:23

feat(schema): compose typed schemas across boundaries

f9b1f56

fix(schema-json): honor final boundary output presence

dc3e024

refactor(schema): drop explicit input and output support from PR

1f0b254

andrewzolotukhin changed the title ~~feat(schema): compose schemas across input and output boundaries~~ feat(schema): add optional-aware fallbacks and named references Sep 28, 2026

andrewzolotukhin commented Sep 29, 2026

View reviewed changes

refactor(schema): make named references automatic

cbc2f14

andrewzolotukhin changed the title ~~feat(schema): add optional-aware fallbacks and named references~~ feat(schema): add optional fallbacks and automatic named references Sep 29, 2026

andrewzolotukhin commented Sep 29, 2026

View reviewed changes

docs(schema): consolidate reference guidance after review

89abbf5

andrewzolotukhin merged commit f9eb11b into development Sep 29, 2026
2 checks passed

Navigation Menu

feat(schema): add optional fallbacks and automatic named references - #230

feat(schema): add optional fallbacks and automatic named references#230
andrewzolotukhin merged 5 commits into
developmentfrom
feat/schema-boundaries

andrewzolotukhin commented Sep 28, 2026 •

edited

Loading

Uh oh!

andrewzolotukhin Sep 29, 2026

Uh oh!

andrewzolotukhin Sep 29, 2026

Uh oh!

andrewzolotukhin Sep 29, 2026

Uh oh!

andrewzolotukhin Sep 29, 2026

Uh oh!

andrewzolotukhin Sep 29, 2026

Uh oh!

andrewzolotukhin Sep 29, 2026

Uh oh!

andrewzolotukhin Sep 29, 2026

Uh oh!

andrewzolotukhin Sep 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		const user = object({ address: schemaRef(address) }).schemaName('User');
		const root = object({ user: schemaRef(user) });

Conversation

andrewzolotukhin commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Original request

What changed

Consumer example

Reasoning

Blog post

Screenshots / preview evidence

Validation

Retained regression coverage

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

andrewzolotukhin commented Sep 28, 2026 •

edited

Loading