diff --git a/index.ts b/index.ts index 8190154..abfbd65 100644 --- a/index.ts +++ b/index.ts @@ -4,48 +4,25 @@ import { type TemplateInput, Typebars } from "./src"; const tp = new Typebars(); const params = { - names: '{{#if hasUsers}}{{map users "name"}}{{else}}{{defaultNames}}{{/if}}', + accountIds: ["{{default accountDepartmentId accountId}}"], }; -const coerceSchema = {} as JSONSchema7; - const inputSchema = { type: "object", properties: { - defaultNames: { - type: "array", - items: { - type: "string", - }, - }, - hasUsers: { - type: "boolean", + accountId: { + type: "string", }, - users: { - type: "array", - items: { - type: "object", - properties: { - name: { - type: "string", - }, - }, - }, + accountDepartmentId: { + type: "string", }, }, + required: ["accountId"], // accountDepartmentId is not required, so is optional } as JSONSchema7; -const result = tp.analyzeAndExecute( - params as TemplateInput, - inputSchema, - { - hasUsers: false, - defaultNames: ["alice", "bob"], - users: [], - }, - { - coerceSchema, - }, -); +const result = tp.analyzeAndExecute(params as TemplateInput, inputSchema, { + accountDepartmentId: null, + accountId: "salut", +}); console.log(JSON.stringify(result, null, 2)); diff --git a/src/analyzer.ts b/src/analyzer.ts index a51cf1b..7e7bc53 100644 --- a/src/analyzer.ts +++ b/src/analyzer.ts @@ -466,7 +466,38 @@ function processMustache( } // ── Simple expression ──────────────────────────────────────────────────── - return resolveExpressionWithDiagnostics(stmt.path, ctx, stmt) ?? {}; + const resolved = resolveExpressionWithDiagnostics(stmt.path, ctx, stmt) ?? {}; + + // When the expression points to an optional property (not in `required`), + // the output can be null at runtime. Wrap the resolved schema with null + // so the output schema accurately reflects this. + // $root returns the entire context — optionality does not apply. + if (stmt.path.type === "PathExpression") { + const segments = extractPathSegments(stmt.path); + if (segments.length > 0) { + const { cleanSegments, identifier } = + extractExpressionIdentifier(segments); + if (!isRootSegments(cleanSegments)) { + let targetSchema = + identifier !== null + ? ctx.identifierSchemas?.[identifier] + : ctx.current; + // For aggregated identifiers (array schema), check optionality + // within the items schema, not the array itself. + if (targetSchema && identifier !== null) { + const itemSchema = resolveArrayItems(targetSchema, ctx.root); + if (itemSchema !== undefined) { + targetSchema = itemSchema; + } + } + if (targetSchema && !isPathFullyRequired(targetSchema, cleanSegments)) { + return withNullType(resolved); + } + } + } + } + + return resolved; } // ─── map helper — special-case analysis ────────────────────────────────────── @@ -1438,6 +1469,51 @@ function resolveWithIdentifier( return resolved; } +// ─── Nullable Schema Wrapping ──────────────────────────────────────────────── + +/** + * Wraps a JSON Schema with `null` to indicate the value can be nullish. + * + * - If the schema already includes `null`, it is returned as-is. + * - For schemas with a simple `type` string, the type becomes an array + * (e.g. `{ type: "string" }` → `{ type: ["string", "null"] }`). + * - For schemas with a type array, `"null"` is appended. + * - For complex schemas (oneOf, anyOf, etc.), a `oneOf` wrapper is used. + */ +function withNullType(schema: JSONSchema7): JSONSchema7 { + if (schema.type === "null") return schema; + + if (typeof schema.type === "string") { + return { ...schema, type: [schema.type, "null"] }; + } + + if (Array.isArray(schema.type)) { + if (schema.type.includes("null")) return schema; + return { ...schema, type: [...schema.type, "null"] }; + } + + // Complex schema (oneOf, anyOf, allOf, etc.) — wrap with oneOf + return simplifySchema({ oneOf: [schema, { type: "null" }] }); +} + +/** + * Checks whether EVERY segment along a property path is required. + * + * Unlike `isPropertyRequired` (which only checks the last segment), + * this function verifies that no intermediate segment is optional. + * If any segment along the path is optional, the entire expression + * can produce `null`/`undefined` at runtime. + * + * Example: for path `["user", "name"]`, checks both that `user` is + * required in the root schema AND that `name` is required in `user`. + */ +function isPathFullyRequired(schema: JSONSchema7, segments: string[]): boolean { + for (let i = 1; i <= segments.length; i++) { + if (!isPropertyRequired(schema, segments.slice(0, i))) return false; + } + return true; +} + // ─── Utilities ─────────────────────────────────────────────────────────────── /** diff --git a/test-optional.ts b/test-optional.ts new file mode 100644 index 0000000..c455ea0 --- /dev/null +++ b/test-optional.ts @@ -0,0 +1,28 @@ +import type { JSONSchema7 } from "json-schema"; +import { type TemplateInput, Typebars } from "./src"; + +const tp = new Typebars(); + +const params = { + accountIds: ["{{accountDepartmentId}}"], +}; + +const inputSchema = { + type: "object", + properties: { + accountId: { + type: "string", + }, + accountDepartmentId: { + type: "string", + }, + }, + required: ["accountId"], // accountDepartmentId is not required, so is optional +} as JSONSchema7; + +const result = tp.analyzeAndExecute(params as TemplateInput, inputSchema, { + accountDepartmentId: null, // optional property not provided + accountId: "salut", +}); + +console.log(JSON.stringify(result, null, 2)); diff --git a/test-trace.ts b/test-trace.ts new file mode 100644 index 0000000..1aca37e --- /dev/null +++ b/test-trace.ts @@ -0,0 +1,26 @@ +import type { JSONSchema7 } from "json-schema"; +import { analyze } from "./src/analyzer.ts"; + +const inputSchema = { + type: "object", + properties: { + accountId: { type: "string" }, + accountDepartmentId: { type: "string" }, + }, + required: ["accountId"], +} as JSONSchema7; + +// Test case: array with optional property reference +const result = analyze(["{{accountDepartmentId}}"], inputSchema); + +console.log("=== Array with optional property ==="); +console.log("Output schema:", JSON.stringify(result.outputSchema, null, 2)); +console.log( + "Expected: items should include null type since property is optional", +); + +// For comparison, test with required property +const result2 = analyze(["{{accountId}}"], inputSchema); + +console.log("\n=== Array with required property ==="); +console.log("Output schema:", JSON.stringify(result2.outputSchema, null, 2)); diff --git a/tests/aggregated-identifiers.spec.ts b/tests/aggregated-identifiers.spec.ts index 16e5ae9..4c0671e 100644 --- a/tests/aggregated-identifiers.spec.ts +++ b/tests/aggregated-identifiers.spec.ts @@ -43,6 +43,7 @@ const aggregatedSchema: JSONSchema7 = { amount: { type: "number" }, active: { type: "boolean" }, }, + required: ["accountId", "amount", "active"], }, }; @@ -53,6 +54,7 @@ const scalarSchema: JSONSchema7 = { seqOutput: { type: "string" }, count: { type: "number" }, }, + required: ["seqOutput", "count"], }; // ═════════════════════════════════════════════════════════════════════════════ @@ -455,8 +457,10 @@ describe("Aggregated identifiers — analyze()", () => { properties: { city: { type: "string" }, }, + required: ["city"], }, }, + required: ["info"], }, }; @@ -488,18 +492,11 @@ describe("Aggregated identifiers — analyze()", () => { properties: { accountId: { type: "string" }, }, + required: ["accountId"], }, }, }; - // For $ref resolution, the root schema used by the analyzer - // is the inputSchema (ctx.root). Since identifierSchemas are - // independent, we place the definitions where the resolver can - // find them. The analyzer's ctx.root is the inputSchema — but - // resolveSchemaPath in resolveWithIdentifier uses idSchema itself, - // so the $ref must be resolvable within the idSchema. - // resolveSchemaPath calls resolveRef which needs root — which is - // the inputSchema. So we pass the definitions in the inputSchema. const inputSchema: JSONSchema7 = { type: "object", definitions: { @@ -508,6 +505,7 @@ describe("Aggregated identifiers — analyze()", () => { properties: { accountId: { type: "string" }, }, + required: ["accountId"], }, }, }; @@ -947,6 +945,7 @@ describe("Aggregated identifiers — backward compatibility", () => { 1: { type: "object", properties: { meetingId: { type: "string" } }, + required: ["meetingId"], }, }, }, @@ -1042,6 +1041,7 @@ describe("Aggregated identifiers — workflow merge scenario", () => { 2: { type: "object", properties: { seqOutput: { type: "string" } }, + required: ["seqOutput"], }, 4: { type: "array", @@ -1051,6 +1051,7 @@ describe("Aggregated identifiers — workflow merge scenario", () => { accountId: { type: "string" }, processedId: { type: "string" }, }, + required: ["accountId", "processedId"], }, }, }; @@ -1107,6 +1108,7 @@ describe("Aggregated identifiers — workflow merge scenario", () => { accountId: { type: "string" }, amount: { type: "number" }, }, + required: ["accountId", "amount"], }, }, }; diff --git a/tests/analyzer.spec.ts b/tests/analyzer.spec.ts index ed05fdd..fd4c772 100644 --- a/tests/analyzer.spec.ts +++ b/tests/analyzer.spec.ts @@ -17,23 +17,23 @@ describe("analyzer", () => { expect(result.outputSchema).toEqual({ type: "number" }); }); - test("single boolean expression → { type: 'boolean' }", () => { + test("single boolean expression (optional) → { type: ['boolean', 'null'] }", () => { const result = analyze("{{active}}", userSchema); expect(result.valid).toBe(true); - expect(result.outputSchema).toEqual({ type: "boolean" }); + expect(result.outputSchema).toEqual({ type: ["boolean", "null"] }); }); - test("single integer expression → { type: 'integer' }", () => { + test("single integer expression (optional) → { type: ['integer', 'null'] }", () => { const result = analyze("{{score}}", userSchema); expect(result.valid).toBe(true); - expect(result.outputSchema).toEqual({ type: "integer" }); + expect(result.outputSchema).toEqual({ type: ["integer", "null"] }); }); - test("single object expression → full object schema", () => { + test("single object expression (optional) → full object schema with null", () => { const result = analyze("{{address}}", userSchema); expect(result.valid).toBe(true); expect(result.outputSchema).toEqual({ - type: "object", + type: ["object", "null"], properties: { city: { type: "string" }, zip: { type: "string" }, @@ -41,26 +41,26 @@ describe("analyzer", () => { }); }); - test("single array expression → array schema", () => { + test("single array expression (optional) → array schema with null", () => { const result = analyze("{{tags}}", userSchema); expect(result.valid).toBe(true); expect(result.outputSchema).toEqual({ - type: "array", + type: ["array", "null"], items: { type: "string" }, }); }); - test("single expression with dot notation → leaf type", () => { + test("single expression with dot notation (optional parent) → leaf type with null", () => { const result = analyze("{{address.city}}", userSchema); expect(result.valid).toBe(true); - expect(result.outputSchema).toEqual({ type: "string" }); + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); }); - test("single expression with enum → preserves enum", () => { + test("single expression with enum (optional parent) → preserves enum with null", () => { const result = analyze("{{metadata.role}}", userSchema); expect(result.valid).toBe(true); expect(result.outputSchema).toEqual({ - type: "string", + type: ["string", "null"], enum: ["admin", "user", "guest"], }); }); @@ -89,10 +89,11 @@ describe("analyzer", () => { expect(result.outputSchema).toEqual({ type: "string" }); }); - test("template with #with block → { type: 'string' }", () => { + test("template with #with block (optional inner prop) → { type: ['string', 'null'] }", () => { const result = analyze("{{#with address}}{{city}}{{/with}}", userSchema); expect(result.valid).toBe(true); - expect(result.outputSchema).toEqual({ type: "string" }); + // city has no `required` in address schema → nullable + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); }); test("plain text without expression → { type: 'string' }", () => { @@ -164,19 +165,22 @@ describe("analyzer", () => { userSchema, ); expect(result.valid).toBe(true); - // age is number, score is integer → oneOf + // age is required (number), score is optional (integer|null) → oneOf expect(result.outputSchema).toEqual({ - oneOf: [{ type: "number" }, { type: "integer" }], + oneOf: [{ type: "number" }, { type: ["integer", "null"] }], }); }); - test("#if with same expression type in both branches → single type", () => { + test("#if with same expression type in both branches (one optional) → oneOf", () => { const result = analyze( "{{#if active}}{{name}}{{else}}{{address.city}}{{/if}}", userSchema, ); expect(result.valid).toBe(true); - expect(result.outputSchema).toEqual({ type: "string" }); + // name is required (string), address.city is optional (string|null) + expect(result.outputSchema).toEqual({ + oneOf: [{ type: "string" }, { type: ["string", "null"] }], + }); }); test("#if with single expression and surrounding whitespace → expression type", () => { @@ -186,14 +190,14 @@ describe("analyzer", () => { ); expect(result.valid).toBe(true); expect(result.outputSchema).toEqual({ - oneOf: [{ type: "number" }, { type: "integer" }], + oneOf: [{ type: "number" }, { type: ["integer", "null"] }], }); }); - test("#with as single block → body type", () => { + test("#with as single block → body type (optional inner prop)", () => { const result = analyze("{{#with address}}{{city}}{{/with}}", userSchema); expect(result.valid).toBe(true); - expect(result.outputSchema).toEqual({ type: "string" }); + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); }); test("#each as single block → always string", () => { @@ -460,10 +464,11 @@ describe("analyzer", () => { }, }; - test("resolves a property access via $ref", () => { + test("resolves a property access via $ref (optional) → nullable", () => { const result = analyze("{{home.city}}", schemaWithRef); expect(result.valid).toBe(true); - expect(result.outputSchema).toEqual({ type: "string" }); + // home is optional (no required) → nullable + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); }); test("mixed template with multiple $ref accesses", () => { @@ -478,18 +483,19 @@ describe("analyzer", () => { }); describe("validation — intrinsic array properties", () => { - test(".length access on an array is valid", () => { + test(".length access on an array is valid (optional parent)", () => { const result = analyze("{{tags.length}}", userSchema); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); - expect(result.outputSchema).toEqual({ type: "integer" }); + // tags is optional → nullable + expect(result.outputSchema).toEqual({ type: ["integer", "null"] }); }); - test(".length access on an array of objects is valid", () => { + test(".length access on an array of objects is valid (optional parent)", () => { const result = analyze("{{orders.length}}", userSchema); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); - expect(result.outputSchema).toEqual({ type: "integer" }); + expect(result.outputSchema).toEqual({ type: ["integer", "null"] }); }); test(".length access in a mixed template → string", () => { @@ -526,26 +532,26 @@ describe("analyzer", () => { }); describe("validation — numeric array index access", () => { - test("[0] on a string array is valid → { type: 'string' }", () => { + test("[0] on a string array is valid (optional parent) → nullable", () => { const result = analyze("{{tags.[0]}}", userSchema); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); - expect(result.outputSchema).toEqual({ type: "string" }); + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); }); - test("[1] on a string array is valid → { type: 'string' }", () => { + test("[1] on a string array is valid (optional parent) → nullable", () => { const result = analyze("{{tags.[1]}}", userSchema); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); - expect(result.outputSchema).toEqual({ type: "string" }); + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); }); - test("[0] on an array of objects → object schema", () => { + test("[0] on an array of objects (optional parent) → nullable object schema", () => { const result = analyze("{{orders.[0]}}", userSchema); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); expect(result.outputSchema).toEqual({ - type: "object", + type: ["object", "null"], properties: { id: { type: "number" }, product: { type: "string" }, @@ -554,18 +560,18 @@ describe("analyzer", () => { }); }); - test("nested property after index: orders.[0].product → { type: 'string' }", () => { + test("nested property after index: orders.[0].product (optional parent) → nullable", () => { const result = analyze("{{orders.[0].product}}", userSchema); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); - expect(result.outputSchema).toEqual({ type: "string" }); + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); }); - test("nested property after index: orders.[0].quantity → { type: 'integer' }", () => { + test("nested property after index: orders.[0].quantity (optional parent) → nullable", () => { const result = analyze("{{orders.[0].quantity}}", userSchema); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); - expect(result.outputSchema).toEqual({ type: "integer" }); + expect(result.outputSchema).toEqual({ type: ["integer", "null"] }); }); test("[0] in mixed template → string output", () => { @@ -591,17 +597,18 @@ describe("analyzer", () => { expect(result.diagnostics[0]?.code).toBe("UNKNOWN_PROPERTY"); }); - test("nested [0] via #with on metadata.permissions", () => { + test("nested [0] via #with on metadata.permissions (optional)", () => { const result = analyze( "{{#with metadata}}{{permissions.[0]}}{{/with}}", userSchema, ); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); - expect(result.outputSchema).toEqual({ type: "string" }); + // permissions is optional in metadata schema → nullable + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); }); - test("[0] with custom schema — array with $ref items", () => { + test("[0] with custom schema — array with $ref items (optional)", () => { const schema: JSONSchema7 = { type: "object", definitions: { @@ -617,10 +624,11 @@ describe("analyzer", () => { const result = analyze("{{tags.[0]}}", schema); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); - expect(result.outputSchema).toEqual({ type: "string" }); + // tags is optional → nullable + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); }); - test("[0] with tuple items schema — resolves correct index type", () => { + test("[0] with tuple items schema (optional) → resolves correct index type with null", () => { const schema: JSONSchema7 = { type: "object", properties: { @@ -632,11 +640,12 @@ describe("analyzer", () => { }; const r0 = analyze("{{pair.[0]}}", schema); expect(r0.valid).toBe(true); - expect(r0.outputSchema).toEqual({ type: "string" }); + // pair is optional → nullable + expect(r0.outputSchema).toEqual({ type: ["string", "null"] }); const r1 = analyze("{{pair.[1]}}", schema); expect(r1.valid).toBe(true); - expect(r1.outputSchema).toEqual({ type: "number" }); + expect(r1.outputSchema).toEqual({ type: ["number", "null"] }); }); }); @@ -652,13 +661,16 @@ describe("analyzer", () => { }); }); - test("two #if blocks with same type → single type", () => { + test("two #if blocks — required string and optional string → oneOf", () => { const result = analyze( "{{#if active}}{{name}}{{/if}}\n{{#if active}}{{address.city}}{{/if}}", userSchema, ); expect(result.valid).toBe(true); - expect(result.outputSchema).toEqual({ type: "string" }); + // name is required (string), address.city is optional (string|null) → distinct + expect(result.outputSchema).toEqual({ + oneOf: [{ type: "string" }, { type: ["string", "null"] }], + }); }); test("two #if blocks with surrounding whitespace → oneOf", () => { @@ -672,26 +684,35 @@ describe("analyzer", () => { }); }); - test("three #if blocks with three different types → oneOf with all types", () => { + test("three #if blocks with three different types (some optional) → oneOf with all types", () => { const result = analyze( "{{#if active}}{{name}}{{/if}}\n{{#if active}}{{age}}{{/if}}\n{{#if active}}{{active}}{{/if}}", userSchema, ); expect(result.valid).toBe(true); + // active is optional → boolean|null expect(result.outputSchema).toEqual({ - oneOf: [{ type: "string" }, { type: "number" }, { type: "boolean" }], + oneOf: [ + { type: "string" }, + { type: "number" }, + { type: ["boolean", "null"] }, + ], }); }); - test("three #if blocks with duplicate types → deduplicated oneOf", () => { + test("three #if blocks with duplicate types (one optional) → oneOf", () => { const result = analyze( "{{#if active}}{{name}}{{/if}}\n{{#if active}}{{age}}{{/if}}\n{{#if active}}{{address.city}}{{/if}}", userSchema, ); expect(result.valid).toBe(true); - // name and address.city are both string → deduplicated + // name is string, address.city is string|null → distinct, not deduplicated expect(result.outputSchema).toEqual({ - oneOf: [{ type: "string" }, { type: "number" }], + oneOf: [ + { type: "string" }, + { type: "number" }, + { type: ["string", "null"] }, + ], }); }); @@ -721,10 +742,10 @@ describe("analyzer", () => { userSchema, ); expect(result.valid).toBe(true); - // first block: oneOf(number, integer), second block: string + // first block: oneOf(number, integer|null), second block: string expect(result.outputSchema).toEqual({ oneOf: [ - { oneOf: [{ type: "number" }, { type: "integer" }] }, + { oneOf: [{ type: "number" }, { type: ["integer", "null"] }] }, { type: "string" }, ], }); @@ -741,6 +762,368 @@ describe("analyzer", () => { }); }); + // ─── Optional property → nullable output schema ────────────────────────── + describe("nullable output schema for optional properties", () => { + const schemaWithRequired: JSONSchema7 = { + type: "object", + properties: { + reqStr: { type: "string" }, + optStr: { type: "string" }, + optNum: { type: "number" }, + nested: { + type: "object", + properties: { + inner: { type: "string" }, + }, + required: ["inner"], + }, + }, + required: ["reqStr", "nested"], + }; + + test("required property → no null in output schema", () => { + const result = analyze("{{reqStr}}", schemaWithRequired); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: "string" }); + }); + + test("optional property → null added to output schema", () => { + const result = analyze("{{optStr}}", schemaWithRequired); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); + }); + + test("optional number property → nullable number", () => { + const result = analyze("{{optNum}}", schemaWithRequired); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: ["number", "null"] }); + }); + + test("required nested path (all segments required) → no null", () => { + const result = analyze("{{nested.inner}}", schemaWithRequired); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: "string" }); + }); + + test("path with optional intermediate segment → nullable", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + user: { + type: "object", + properties: { + name: { type: "string" }, + }, + required: ["name"], + }, + }, + // user is NOT required + }; + const result = analyze("{{user.name}}", schema); + expect(result.valid).toBe(true); + // user is optional → entire path is nullable + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); + }); + + test("mixed template with optional property → always string (no null)", () => { + const result = analyze("Hello {{optStr}}", schemaWithRequired); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: "string" }); + }); + + test("$root → never nullable", () => { + const result = analyze("{{$root}}", { type: "string" }); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: "string" }); + }); + + test("array element with optional property → nullable items", () => { + const result = analyze(["{{optStr}}"], schemaWithRequired); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: ["string", "null"] }, + minItems: 1, + maxItems: 1, + }); + }); + + test("object property with optional expression → nullable value", () => { + const result = analyze({ key: "{{optStr}}" }, schemaWithRequired); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "object", + properties: { + key: { type: ["string", "null"] }, + }, + required: ["key"], + }); + }); + + // ── Deeply nested paths ────────────────────────────────────────── + + test("deeply nested path — first segment optional → nullable", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + a: { + type: "object", + properties: { + b: { + type: "object", + properties: { + c: { + type: "object", + properties: { d: { type: "string" } }, + required: ["d"], + }, + }, + required: ["c"], + }, + }, + required: ["b"], + }, + }, + // a is NOT required + }; + const result = analyze("{{a.b.c.d}}", schema); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); + }); + + test("deeply nested path — all segments required → no null", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + a: { + type: "object", + properties: { + b: { + type: "object", + properties: { + c: { + type: "object", + properties: { d: { type: "string" } }, + required: ["d"], + }, + }, + required: ["c"], + }, + }, + required: ["b"], + }, + }, + required: ["a"], + }; + const result = analyze("{{a.b.c.d}}", schema); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: "string" }); + }); + + test("deeply nested path — middle segment optional → nullable", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + a: { + type: "object", + properties: { + b: { + type: "object", + properties: { + c: { + type: "object", + properties: { d: { type: "string" } }, + required: ["d"], + }, + }, + // c is NOT required in b + }, + }, + required: ["b"], + }, + }, + required: ["a"], + }; + const result = analyze("{{a.b.c.d}}", schema); + expect(result.valid).toBe(true); + // c is optional → entire path is nullable + expect(result.outputSchema).toEqual({ type: ["string", "null"] }); + }); + + test("5 levels deep — only leaf optional → nullable", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + l1: { + type: "object", + properties: { + l2: { + type: "object", + properties: { + l3: { + type: "object", + properties: { + l4: { + type: "object", + properties: { + value: { type: "number" }, + }, + // value NOT required + }, + }, + required: ["l4"], + }, + }, + required: ["l3"], + }, + }, + required: ["l2"], + }, + }, + required: ["l1"], + }; + const result = analyze("{{l1.l2.l3.l4.value}}", schema); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: ["number", "null"] }); + }); + + // ── Deeply nested template inputs ──────────────────────────────── + + test("nested object template — optional and required at each level", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + reqStr: { type: "string" }, + optStr: { type: "string" }, + }, + required: ["reqStr"], + }; + const result = analyze( + { + level1: { + level2: { + opt: "{{optStr}}", + req: "{{reqStr}}", + }, + }, + }, + schema, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "object", + properties: { + level1: { + type: "object", + properties: { + level2: { + type: "object", + properties: { + opt: { type: ["string", "null"] }, + req: { type: "string" }, + }, + required: ["opt", "req"], + }, + }, + required: ["level2"], + }, + }, + required: ["level1"], + }); + }); + + test("array inside nested object template — optional items", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + reqStr: { type: "string" }, + optStr: { type: "string" }, + }, + required: ["reqStr"], + }; + const result = analyze( + { + data: { + ids: ["{{optStr}}", "{{reqStr}}"], + }, + }, + schema, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "object", + properties: { + data: { + type: "object", + properties: { + ids: { + type: "array", + items: { + oneOf: [{ type: ["string", "null"] }, { type: "string" }], + }, + minItems: 2, + maxItems: 2, + }, + }, + required: ["ids"], + }, + }, + required: ["data"], + }); + }); + + test("triple nested template — all expressions optional → all nullable", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + a: { type: "string" }, + b: { type: "number" }, + }, + // nothing required + }; + const result = analyze( + { + l1: { + l2: { + l3: { + strVal: "{{a}}", + numVal: "{{b}}", + }, + }, + }, + }, + schema, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "object", + properties: { + l1: { + type: "object", + properties: { + l2: { + type: "object", + properties: { + l3: { + type: "object", + properties: { + strVal: { type: ["string", "null"] }, + numVal: { type: ["number", "null"] }, + }, + required: ["strVal", "numVal"], + }, + }, + required: ["l3"], + }, + }, + required: ["l2"], + }, + }, + required: ["l1"], + }); + }); + }); + describe("diagnostics include a position (loc)", () => { test("error includes position in the source", () => { const result = analyze("Hello {{badProp}}", userSchema); diff --git a/tests/array-bounds.spec.ts b/tests/array-bounds.spec.ts index f7e9ef5..511135c 100644 --- a/tests/array-bounds.spec.ts +++ b/tests/array-bounds.spec.ts @@ -214,19 +214,30 @@ describe("array bounds (minItems / maxItems)", () => { expect(branch2).toHaveProperty("maxItems", 2); }); - test("identical nested arrays → deduplicated with bounds", () => { + test("nested arrays (one optional) → oneOf with bounds", () => { const result = engine.analyze( [["{{name}}"], ["{{address.city}}"]], userSchema, ); expect(result.valid).toBe(true); + // name is required, address.city is optional → distinct nested arrays expect(result.outputSchema).toEqual({ type: "array", items: { - type: "array", - items: { type: "string" }, - minItems: 1, - maxItems: 1, + oneOf: [ + { + type: "array", + items: { type: "string" }, + minItems: 1, + maxItems: 1, + }, + { + type: "array", + items: { type: ["string", "null"] }, + minItems: 1, + maxItems: 1, + }, + ], }, minItems: 2, maxItems: 2, @@ -237,18 +248,21 @@ describe("array bounds (minItems / maxItems)", () => { // ─── Array inside object ───────────────────────────────────────────────── describe("array inside object", () => { - test("array property in object template → bounds on inner array", () => { + test("array property in object template (one optional) → oneOf items with bounds", () => { const result = engine.analyze( { ids: ["{{name}}", "{{address.city}}"] }, userSchema, ); expect(result.valid).toBe(true); + // name is required (string), address.city is optional (string|null) expect(result.outputSchema).toEqual({ type: "object", properties: { ids: { type: "array", - items: { type: "string" }, + items: { + oneOf: [{ type: "string" }, { type: ["string", "null"] }], + }, minItems: 2, maxItems: 2, }, diff --git a/tests/default-helpers.spec.ts b/tests/default-helpers.spec.ts index de1280a..9e442c4 100644 --- a/tests/default-helpers.spec.ts +++ b/tests/default-helpers.spec.ts @@ -350,3 +350,94 @@ describe("default helper — mixed templates", () => { expect(result).toBe("Hello stranger!"); }); }); + +// ─── default helper resolves nullable to non-nullable ──────────────────────── + +describe("default helper — nullable output schema resolution", () => { + const schemaWithOptional: JSONSchema7 = { + type: "object", + properties: { + accountId: { type: "string" }, + accountDepartmentId: { type: "string" }, + }, + required: ["accountId"], + }; + + test("optional prop alone → nullable output", () => { + const result = engine.analyze( + ["{{accountDepartmentId}}"], + schemaWithOptional, + ); + expect(result.valid).toBe(true); + // Without default helper, optional prop is nullable + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: ["string", "null"] }, + minItems: 1, + maxItems: 1, + }); + }); + + test("default with required fallback → non-nullable string output", () => { + const result = engine.analyze( + ["{{default accountDepartmentId accountId}}"], + schemaWithOptional, + ); + expect(result.valid).toBe(true); + // default helper guarantees a value (accountId is required) → no null + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + minItems: 1, + maxItems: 1, + }); + }); + + test("default with literal fallback → non-nullable string output", () => { + const result = engine.analyze( + ['{{default accountDepartmentId "N/A"}}'], + schemaWithOptional, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + minItems: 1, + maxItems: 1, + }); + }); + + test("default helper execution — optional null falls back to required", () => { + const { analysis, value } = engine.analyzeAndExecute( + { accountIds: ["{{default accountDepartmentId accountId}}"] }, + schemaWithOptional, + { accountDepartmentId: null, accountId: "salut" }, + ); + expect(analysis.valid).toBe(true); + // Schema says string (not null) + expect(analysis.outputSchema).toEqual({ + type: "object", + properties: { + accountIds: { + type: "array", + items: { type: "string" }, + minItems: 1, + maxItems: 1, + }, + }, + required: ["accountIds"], + }); + // Value falls back to accountId + expect(value).toEqual({ accountIds: ["salut"] }); + }); + + test("default helper execution — optional present uses first value", () => { + const { analysis, value } = engine.analyzeAndExecute( + { accountIds: ["{{default accountDepartmentId accountId}}"] }, + schemaWithOptional, + { accountDepartmentId: "dept-42", accountId: "salut" }, + ); + expect(analysis.valid).toBe(true); + expect(value).toEqual({ accountIds: ["dept-42"] }); + }); +}); diff --git a/tests/engine.spec.ts b/tests/engine.spec.ts index 2b10233..faffeea 100644 --- a/tests/engine.spec.ts +++ b/tests/engine.spec.ts @@ -510,7 +510,7 @@ describe("object template input (TemplateInputObject)", () => { meta: { type: "object", properties: { - active: { type: "boolean" }, + active: { type: ["boolean", "null"] }, }, required: ["active"], }, @@ -554,7 +554,7 @@ describe("object template input (TemplateInputObject)", () => { nested: { type: "object", properties: { - city: { type: "string" }, + city: { type: ["string", "null"] }, fixed: { type: "integer" }, }, required: ["city", "fixed"], @@ -1244,30 +1244,38 @@ describe("array template input (TemplateInputArray)", () => { }); }); - test("array with multiple same-type templates → single items schema", () => { + test("array with multiple same-type templates (one optional) → oneOf items", () => { const result = engine.analyze( ["{{name}}", "{{address.city}}"], userSchema, ); expect(result.valid).toBe(true); + // name is required (string), address.city is optional (string|null) expect(result.outputSchema).toEqual({ type: "array", - items: { type: "string" }, + items: { + oneOf: [{ type: "string" }, { type: ["string", "null"] }], + }, minItems: 2, maxItems: 2, }); }); - test("array with different-type templates → oneOf items schema", () => { + test("array with different-type templates (some optional) → oneOf items schema", () => { const result = engine.analyze( ["{{name}}", "{{age}}", "{{active}}"], userSchema, ); expect(result.valid).toBe(true); + // active is optional → boolean|null expect(result.outputSchema).toEqual({ type: "array", items: { - oneOf: [{ type: "string" }, { type: "number" }, { type: "boolean" }], + oneOf: [ + { type: "string" }, + { type: "number" }, + { type: ["boolean", "null"] }, + ], }, minItems: 3, maxItems: 3, @@ -1381,19 +1389,30 @@ describe("array template input (TemplateInputArray)", () => { }); }); - test("array with identical nested arrays → deduplicated items schema", () => { + test("array with nested arrays (one optional) → oneOf items", () => { const result = engine.analyze( [["{{name}}"], ["{{address.city}}"]], userSchema, ); expect(result.valid).toBe(true); + // name is required (string), address.city is optional (string|null) → distinct expect(result.outputSchema).toEqual({ type: "array", items: { - type: "array", - items: { type: "string" }, - minItems: 1, - maxItems: 1, + oneOf: [ + { + type: "array", + items: { type: "string" }, + minItems: 1, + maxItems: 1, + }, + { + type: "array", + items: { type: ["string", "null"] }, + minItems: 1, + maxItems: 1, + }, + ], }, minItems: 2, maxItems: 2, diff --git a/tests/migration-interop.spec.ts b/tests/migration-interop.spec.ts index cb8dd94..8c4eb36 100644 --- a/tests/migration-interop.spec.ts +++ b/tests/migration-interop.spec.ts @@ -513,6 +513,7 @@ describe("Migration: compare → analyze() outputSchema inference", () => { properties: { accountId: { type: "string" }, }, + required: ["accountId"], }; const result = analyze("{{accountId}}", schema); @@ -526,6 +527,7 @@ describe("Migration: compare → analyze() outputSchema inference", () => { properties: { age: { type: "number" }, }, + required: ["age"], }; const result = analyze("{{age}}", schema); @@ -539,6 +541,7 @@ describe("Migration: compare → analyze() outputSchema inference", () => { properties: { active: { type: "boolean" }, }, + required: ["active"], }; const result = analyze("{{active}}", schema); @@ -569,6 +572,7 @@ describe("Migration: compare → analyze() outputSchema inference", () => { items: { type: "number" }, }, }, + required: ["items"], }; const result = analyze("{{items}}", schema); @@ -585,6 +589,7 @@ describe("Migration: compare → analyze() outputSchema inference", () => { properties: { role: { type: "string", enum: ["admin", "user", "guest"] }, }, + required: ["role"], }; const result = analyze("{{role}}", schema); @@ -749,14 +754,17 @@ describe("Migration: findTemplateSchemaFromPrevSchemas → JSON Schema resolutio properties: { someKey: { type: "string" }, }, + required: ["someKey"], }, node_2: { type: "object", properties: { someKey: { type: "boolean" }, }, + required: ["someKey"], }, }, + required: ["node_1", "node_2"], }; { @@ -961,6 +969,7 @@ describe("Bonus: New features not available in old system", () => { properties: { age: { type: "number" }, }, + required: ["age"], }; const result = analyze("{{age}}", schema); @@ -976,11 +985,13 @@ describe("Bonus: New features not available in old system", () => { properties: { city: { type: "string" }, }, + required: ["city"], }, }, properties: { home: { $ref: "#/definitions/Address" }, }, + required: ["home"], }; const result = analyze("{{home.city}}", schema); diff --git a/tests/schema-type-coercion.spec.ts b/tests/schema-type-coercion.spec.ts index 9a1a6c7..3b6bfc4 100644 --- a/tests/schema-type-coercion.spec.ts +++ b/tests/schema-type-coercion.spec.ts @@ -77,9 +77,20 @@ const complexSchema: JSONSchema7 = { role: { type: "string" }, level: { type: "number" }, }, + required: ["role", "level"], }, }, - required: ["name", "age"], + required: [ + "name", + "age", + "active", + "score", + "accountId", + "balance", + "config", + "items", + "metadata", + ], }; const complexData: Record = { @@ -1643,6 +1654,7 @@ describe("schema-driven type coercion via coerceSchema", () => { userName: { type: "string" }, userAge: { type: "number" }, }, + required: ["userName", "userAge"], }; const coerceSchema: JSONSchema7 = { type: "object", @@ -1676,6 +1688,7 @@ describe("schema-driven type coercion via coerceSchema", () => { properties: { name: { type: "string" }, }, + required: ["name"], }; const coerceSchema: JSONSchema7 = { type: "object", diff --git a/tests/sub-expression.spec.ts b/tests/sub-expression.spec.ts index 0a402ec..412f00b 100644 --- a/tests/sub-expression.spec.ts +++ b/tests/sub-expression.spec.ts @@ -818,15 +818,16 @@ describe("SubExpression resolution", () => { // ─── Type inference — structured types (object, array) in branches ─── describe("type inference — structured types in branches with sub-expression conditions", () => { - it("#if (lt ...) → {{account}} → object schema", () => { + it("#if (lt ...) → {{account}} → object schema (optional → nullable)", () => { const result = engine.analyze( "{{#if (lt count 10)}}{{account}}{{/if}}", schema, ); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); + // account is optional → nullable expect(result.outputSchema).toEqual({ - type: "object", + type: ["object", "null"], properties: { id: { type: "string" }, balance: { type: "number" }, @@ -835,20 +836,21 @@ describe("SubExpression resolution", () => { }); }); - it("#if (gt ...) → {{tags}} → array schema", () => { + it("#if (gt ...) → {{tags}} → array schema (optional → nullable)", () => { const result = engine.analyze( "{{#if (gt score 50)}}{{tags}}{{/if}}", schema, ); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); + // tags is optional → nullable expect(result.outputSchema).toEqual({ - type: "array", + type: ["array", "null"], items: { type: "string" }, }); }); - it("#if (eq ...) → {{account}} else {{name}} → oneOf [object, string]", () => { + it("#if (eq ...) → {{account}} else {{name}} → oneOf [object|null, string]", () => { const result = engine.analyze( '{{#if (eq role "admin")}}{{account}}{{else}}{{name}}{{/if}}', schema, @@ -859,10 +861,10 @@ describe("SubExpression resolution", () => { expect(outputSchema).toHaveProperty("oneOf"); const oneOf = (outputSchema as { oneOf: unknown[] }).oneOf; expect(oneOf).toHaveLength(2); - // One should be the object schema, the other string + // account is optional (object|null), name is required (string) expect(oneOf).toContainEqual({ type: "string" }); expect(oneOf).toContainEqual({ - type: "object", + type: ["object", "null"], properties: { id: { type: "string" }, balance: { type: "number" }, @@ -939,8 +941,11 @@ describe("SubExpression resolution", () => { ); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); - // Both branches are number → single number, not boolean - expect(result.outputSchema).toEqual({ type: "number" }); + // account is optional → account.balance is nullable number + // count is required → number + expect(result.outputSchema).toEqual({ + oneOf: [{ type: ["number", "null"] }, { type: "number" }], + }); }); it("(not ...) returns boolean but single branch determines output", () => { @@ -950,9 +955,9 @@ describe("SubExpression resolution", () => { ); expect(result.valid).toBe(true); expect(result.diagnostics).toHaveLength(0); - // Output should be the object schema, not boolean + // account is optional → nullable object expect(result.outputSchema).toEqual({ - type: "object", + type: ["object", "null"], properties: { id: { type: "string" }, balance: { type: "number" }, diff --git a/tests/template-identifiers.spec.ts b/tests/template-identifiers.spec.ts index a4f8964..8e627e1 100644 --- a/tests/template-identifiers.spec.ts +++ b/tests/template-identifiers.spec.ts @@ -586,6 +586,7 @@ describe("analyze() with identifierSchemas", () => { 1: { type: "object", properties: { meetingId: { type: "string" } }, + required: ["meetingId"], }, }; @@ -602,6 +603,7 @@ describe("analyze() with identifierSchemas", () => { 1: { type: "object", properties: { age: { type: "number" } }, + required: ["age"], }, }; @@ -618,6 +620,7 @@ describe("analyze() with identifierSchemas", () => { 1: { type: "object", properties: { active: { type: "boolean" } }, + required: ["active"], }, }; @@ -636,6 +639,7 @@ describe("analyze() with identifierSchemas", () => { properties: { ids: { type: "array", items: { type: "number" } }, }, + required: ["ids"], }, }; @@ -657,6 +661,7 @@ describe("analyze() with identifierSchemas", () => { properties: { role: { type: "string", enum: ["admin", "user"] }, }, + required: ["role"], }, }; @@ -697,10 +702,12 @@ describe("analyze() with identifierSchemas", () => { 1: { type: "object", properties: { someKey: { type: "string" } }, + required: ["someKey"], }, 2: { type: "object", properties: { someKey: { type: "boolean" } }, + required: ["someKey"], }, }; @@ -863,6 +870,7 @@ describe("Typebars with identifiers", () => { 1: { type: "object", properties: { meetingId: { type: "string" } }, + required: ["meetingId"], }, }; @@ -996,6 +1004,7 @@ describe("Typebars with identifiers", () => { 1: { type: "object", properties: { meetingId: { type: "number" } }, + required: ["meetingId"], }, }; @@ -1236,6 +1245,7 @@ describe("Exact migration of old findTemplateSchemaFromPrevSchemas behavior", () 1: { type: "object", properties: { someKey: { type: "string" } }, + required: ["someKey"], }, }; @@ -1285,10 +1295,12 @@ describe("Exact migration of old findTemplateSchemaFromPrevSchemas behavior", () 1: { type: "object", properties: { someKey: { type: "string" } }, + required: ["someKey"], }, 2: { type: "object", properties: { someKey: { type: "boolean" } }, + required: ["someKey"], }, }; @@ -1317,11 +1329,13 @@ describe("Exact migration of old findTemplateSchemaFromPrevSchemas behavior", () const schema: JSONSchema7 = { type: "object", properties: { someKey: { type: "number" } }, + required: ["someKey"], }; const idSchemas: Record = { 1: { type: "object", properties: { someKey: { type: "string" } }, + required: ["someKey"], }, }; @@ -1571,6 +1585,7 @@ describe("Negative identifiers — analyze()", () => { properties: { meetingId: { type: "string" }, }, + required: ["meetingId"], }, }; const result = analyze("{{meetingId:-1}}", schema, { @@ -1588,6 +1603,7 @@ describe("Negative identifiers — analyze()", () => { properties: { count: { type: "number" }, }, + required: ["count"], }, }; const result = analyze("{{count:-1}}", schema, { @@ -1714,6 +1730,7 @@ describe("Negative identifiers — Typebars engine", () => { properties: { meetingId: { type: "string" }, }, + required: ["meetingId"], }, }; const result = engine.analyze("{{meetingId:-1}}", schema, {