diff --git a/src/analyzer.ts b/src/analyzer.ts index 03642aa..28e321d 100644 --- a/src/analyzer.ts +++ b/src/analyzer.ts @@ -537,6 +537,20 @@ function processMapHelper( const innerItems = resolveArrayItems(effectiveItemSchema, ctx.root); if (innerItems) { effectiveItemSchema = innerItems; + // Emit an informational warning so consumers know the flatten happened + addDiagnostic( + ctx, + "MAP_IMPLICIT_FLATTEN", + "warning", + `The "${helperName}" helper will automatically flatten the input array one level before mapping. ` + + `The item type "${Array.isArray(itemType) ? itemType.join(" | ") : itemType}" was unwrapped to its inner items schema.`, + stmt, + { + helperName, + expected: "object", + actual: schemaTypeLabel(effectiveItemSchema), + }, + ); } } diff --git a/src/helpers/map-helpers.ts b/src/helpers/map-helpers.ts index 7ebe926..ae932db 100644 --- a/src/helpers/map-helpers.ts +++ b/src/helpers/map-helpers.ts @@ -31,7 +31,17 @@ import { HelperFactory } from "./helper-factory.ts"; /** * Extracts a property from each element of an array. * - * @param array - The array of objects + * **Note:** The input array is automatically flattened one level (`flat(1)`) + * before mapping. This is designed to support multi-node outputs and chained + * map calls which produce arrays of arrays. If your data is already flat, + * this has no effect. + * + * @example + * // Input: [[{name:"a"},{name:"b"}],[{name:"c"}]] + * // After flat(1): [{name:"a"},{name:"b"},{name:"c"}] + * // Result: ["a","b","c"] + * + * @param array - The array of objects (will be flattened one level) * @param property - The property name to extract from each element * @returns A new array containing the extracted property values */ @@ -46,7 +56,12 @@ function mapProperty(array: unknown, property: unknown): unknown[] { // where the inner map returns an array of arrays. const flattened = array.flat(1); return flattened.map((item: unknown) => { - if (item !== null && item !== undefined && typeof item === "object") { + if ( + item !== null && + item !== undefined && + typeof item === "object" && + !Array.isArray(item) + ) { return (item as Record)[prop]; } return undefined; diff --git a/src/schema-resolver.ts b/src/schema-resolver.ts index 2a6ebd3..85a8b9d 100644 --- a/src/schema-resolver.ts +++ b/src/schema-resolver.ts @@ -502,7 +502,8 @@ export function resolveArrayItems( * allocations). */ export function simplifySchema(schema: JSONSchema7): JSONSchema7 { - // oneOf / anyOf with a single element → unwrap + // ── Phase 1 : Unwrap single-branch combinators ────────────────────── + for (const key of ["oneOf", "anyOf"] as const) { const arr = schema[key]; if (arr && arr.length === 1) { @@ -512,16 +513,18 @@ export function simplifySchema(schema: JSONSchema7): JSONSchema7 { } } - // allOf with a single element → unwrap if (schema.allOf && schema.allOf.length === 1) { const first = schema.allOf[0]; if (first !== undefined && typeof first !== "boolean") return simplifySchema(first); } - // Deduplicate identical entries in oneOf/anyOf + // ── Phase 2 : Deduplicate multi-branch oneOf/anyOf ────────────────── + + let result: JSONSchema7 = schema; + for (const key of ["oneOf", "anyOf"] as const) { - const arr = schema[key]; + const arr = result[key]; if (arr && arr.length > 1) { const unique: JSONSchema7[] = []; for (const entry of arr) { @@ -529,17 +532,85 @@ export function simplifySchema(schema: JSONSchema7): JSONSchema7 { // Use deepEqual instead of JSON.stringify for structural // comparison — more robust (key order independent) and // more performant (no string allocations). + const simplified = simplifySchema(entry); const isDuplicate = unique.some((existing) => - deepEqual(existing, entry), + deepEqual(existing, simplified), ); if (!isDuplicate) { - unique.push(simplifySchema(entry)); + unique.push(simplified); } } if (unique.length === 1) return unique[0] as JSONSchema7; - return { ...schema, [key]: unique }; + result = { ...result, [key]: unique }; + } + } + + // ── Phase 3 : Recurse into allOf branches (multi-branch) ──────────── + + if (result.allOf && result.allOf.length > 1) { + const simplifiedBranches = result.allOf.map((branch) => { + if (typeof branch === "boolean" || branch === undefined) return branch; + return simplifySchema(branch); + }); + result = { ...result, allOf: simplifiedBranches }; + } + + // ── Phase 4 : Recurse into properties ─────────────────────────────── + + if (result.properties) { + const simplifiedProps: Record = {}; + let changed = false; + for (const [key, prop] of Object.entries(result.properties)) { + if (prop && typeof prop !== "boolean") { + const simplified = simplifySchema(prop); + simplifiedProps[key] = simplified; + if (simplified !== prop) changed = true; + } else { + simplifiedProps[key] = prop as unknown as JSONSchema7; + } + } + if (changed) { + result = { ...result, properties: simplifiedProps }; + } + } + + // ── Phase 5 : Recurse into items ──────────────────────────────────── + + if (result.items) { + if (Array.isArray(result.items)) { + // Tuple items + let itemsChanged = false; + const simplifiedItems = result.items.map((item) => { + if (item && typeof item !== "boolean") { + const simplified = simplifySchema(item); + if (simplified !== item) itemsChanged = true; + return simplified; + } + return item; + }); + if (itemsChanged) { + result = { ...result, items: simplifiedItems }; + } + } else if (typeof result.items !== "boolean") { + // Single items schema + const simplified = simplifySchema(result.items); + if (simplified !== result.items) { + result = { ...result, items: simplified }; + } + } + } + + // ── Phase 6 : Recurse into additionalProperties ───────────────────── + + if ( + result.additionalProperties && + typeof result.additionalProperties === "object" + ) { + const simplified = simplifySchema(result.additionalProperties); + if (simplified !== result.additionalProperties) { + result = { ...result, additionalProperties: simplified }; } } - return schema; + return result; } diff --git a/src/types.ts b/src/types.ts index 8bee81f..8109434 100644 --- a/src/types.ts +++ b/src/types.ts @@ -166,7 +166,9 @@ export type DiagnosticCode = /** The $root token is used with path traversal (e.g. $root.name) */ | "ROOT_PATH_TRAVERSAL" /** Unsupported JSON Schema feature (e.g. if/then/else conditional schemas) */ - | "UNSUPPORTED_SCHEMA"; + | "UNSUPPORTED_SCHEMA" + /** The map helper implicitly flattens the input array one level before mapping */ + | "MAP_IMPLICIT_FLATTEN"; // ─── Diagnostic Details ────────────────────────────────────────────────────── // Supplementary information to understand the exact cause of the error. diff --git a/tests/map-helpers.spec.ts b/tests/map-helpers.spec.ts index d91468f..264e21c 100644 --- a/tests/map-helpers.spec.ts +++ b/tests/map-helpers.spec.ts @@ -758,7 +758,10 @@ describe("map helper", () => { nestedData, ); expect(analysis.valid).toBe(true); - expect(analysis.diagnostics).toHaveLength(0); + // The outer map emits a MAP_IMPLICIT_FLATTEN warning because the + // inner map returns an array-of-arrays that gets flattened. + const errors = analysis.diagnostics.filter((d) => d.severity === "error"); + expect(errors).toHaveLength(0); expect(value).toEqual(["p1", "p2", "p3"]); }); @@ -780,7 +783,9 @@ describe("map helper", () => { nestedSchema, ); expect(result.valid).toBe(true); - expect(result.diagnostics).toHaveLength(0); + // The outer map emits a MAP_IMPLICIT_FLATTEN warning (not an error) + const errors = result.diagnostics.filter((d) => d.severity === "error"); + expect(errors).toHaveLength(0); expect(result.outputSchema).toEqual({ type: "array", items: { type: "string" }, @@ -794,7 +799,9 @@ describe("map helper", () => { nestedSchema, ); expect(result.valid).toBe(true); - expect(result.diagnostics).toHaveLength(0); + // The outer map emits a MAP_IMPLICIT_FLATTEN warning (not an error) + const errors = result.diagnostics.filter((d) => d.severity === "error"); + expect(errors).toHaveLength(0); expect(result.outputSchema).toEqual({ type: "array", items: { type: "number" }, @@ -856,4 +863,116 @@ describe("map helper", () => { expect(error).toBeDefined(); }); }); + + // ─── flat(1) behavior documentation ────────────────────────────────────── + + describe("map helper — flat(1) behavior", () => { + test("should map properties from flat array of objects", () => { + const tp = new Typebars(); + const result = tp.execute('{{map users "name"}}', { + users: [{ name: "Alice" }, { name: "Bob" }], + }); + expect(result).toEqual(["Alice", "Bob"]); + }); + + test("should flatten one level before mapping (current behavior)", () => { + const tp = new Typebars(); + const result = tp.execute('{{map groups "name"}}', { + groups: [[{ name: "Alice" }, { name: "Bob" }], [{ name: "Charlie" }]], + }); + // flat(1) produces [{name:"Alice"},{name:"Bob"},{name:"Charlie"}] + expect(result).toEqual(["Alice", "Bob", "Charlie"]); + }); + + test("should NOT flatten more than one level", () => { + const tp = new Typebars(); + const result = tp.execute('{{map deepNested "name"}}', { + deepNested: [[[{ name: "Alice" }]]], + }); + // flat(1) produces [[{name:"Alice"}]] + // The inner array is not a plain object → undefined + expect(result).toEqual([undefined]); + }); + + test("should return undefined for non-object items after flatten", () => { + const tp = new Typebars(); + const result = tp.execute('{{map mixed "name"}}', { + mixed: [{ name: "Alice" }, "not-an-object", null, { name: "Bob" }], + }); + expect(result).toEqual(["Alice", undefined, undefined, "Bob"]); + }); + + test("should return undefined for array items (not treated as objects)", () => { + const tp = new Typebars(); + const result = tp.execute('{{map items "name"}}', { + items: [{ name: "Alice" }, [1, 2, 3], { name: "Bob" }], + }); + // [1,2,3] is an array, not a plain object → after flat(1) it becomes 1, 2, 3 + // 1, 2, 3 are not objects → undefined + expect(result).toEqual(["Alice", undefined, undefined, undefined, "Bob"]); + }); + }); + + // ─── MAP_IMPLICIT_FLATTEN diagnostic ───────────────────────────────────── + + describe("map helper — MAP_IMPLICIT_FLATTEN diagnostic", () => { + test("should emit MAP_IMPLICIT_FLATTEN warning when items are arrays", () => { + const tp = new Typebars(); + const schema: JSONSchema7 = { + type: "object", + properties: { + groups: { + type: "array", + items: { + type: "array", + items: { + type: "object", + properties: { + name: { type: "string" }, + }, + required: ["name"], + }, + }, + }, + }, + required: ["groups"], + }; + const result = tp.analyze('{{map groups "name"}}', schema); + // Analysis should still succeed (the flatten is valid) + expect(result.valid).toBe(true); + // But a MAP_IMPLICIT_FLATTEN warning should be emitted + const warning = result.diagnostics.find( + (d) => d.code === "MAP_IMPLICIT_FLATTEN", + ); + expect(warning).toBeDefined(); + expect(warning?.severity).toBe("warning"); + expect(warning?.message).toContain("automatically flatten"); + }); + + test("should NOT emit MAP_IMPLICIT_FLATTEN for flat array of objects", () => { + const tp = new Typebars(); + const schema: JSONSchema7 = { + type: "object", + properties: { + users: { + type: "array", + items: { + type: "object", + properties: { + name: { type: "string" }, + }, + required: ["name"], + }, + }, + }, + required: ["users"], + }; + const result = tp.analyze('{{map users "name"}}', schema); + expect(result.valid).toBe(true); + const warning = result.diagnostics.find( + (d) => d.code === "MAP_IMPLICIT_FLATTEN", + ); + expect(warning).toBeUndefined(); + }); + }); }); diff --git a/tests/schema-resolver.spec.ts b/tests/schema-resolver.spec.ts index 102a496..11b875f 100644 --- a/tests/schema-resolver.spec.ts +++ b/tests/schema-resolver.spec.ts @@ -763,5 +763,168 @@ describe("schema-resolver", () => { const schema: JSONSchema7 = { type: "string" }; expect(simplifySchema(schema)).toEqual(schema); }); + + // ── Nested recursion tests ─────────────────────────────────────── + + test("should simplify single-branch oneOf inside properties", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + value: { oneOf: [{ type: "string" }] }, + }, + }; + expect(simplifySchema(schema)).toEqual({ + type: "object", + properties: { + value: { type: "string" }, + }, + }); + }); + + test("should deduplicate oneOf inside properties", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + value: { + oneOf: [{ type: "string" }, { type: "string" }], + }, + }, + }; + expect(simplifySchema(schema)).toEqual({ + type: "object", + properties: { + value: { type: "string" }, + }, + }); + }); + + test("should simplify schemas inside allOf branches (multi-branch)", () => { + const schema: JSONSchema7 = { + allOf: [ + { + type: "object", + properties: { + x: { anyOf: [{ type: "string" }] }, + }, + }, + { + type: "object", + properties: { + y: { type: "number" }, + }, + }, + ], + }; + const result = simplifySchema(schema); + expect((result.allOf?.[0] as JSONSchema7).properties?.x).toEqual({ + type: "string", + }); + }); + + test("should simplify schemas inside array items (single schema)", () => { + const schema: JSONSchema7 = { + type: "array", + items: { + anyOf: [{ type: "number" }, { type: "number" }], + }, + }; + expect(simplifySchema(schema)).toEqual({ + type: "array", + items: { type: "number" }, + }); + }); + + test("should simplify schemas inside tuple items", () => { + const schema: JSONSchema7 = { + type: "array", + items: [{ oneOf: [{ type: "string" }] }, { type: "number" }], + }; + expect(simplifySchema(schema)).toEqual({ + type: "array", + items: [{ type: "string" }, { type: "number" }], + }); + }); + + test("should simplify schemas inside additionalProperties", () => { + const schema: JSONSchema7 = { + type: "object", + additionalProperties: { + oneOf: [{ type: "string" }], + }, + }; + expect(simplifySchema(schema)).toEqual({ + type: "object", + additionalProperties: { type: "string" }, + }); + }); + + test("should handle deeply nested simplification", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + user: { + type: "object", + properties: { + tags: { + type: "array", + items: { + oneOf: [{ type: "string" }], + }, + }, + }, + }, + }, + }; + const result = simplifySchema(schema); + expect( + ( + (result.properties?.user as JSONSchema7).properties + ?.tags as JSONSchema7 + ).items, + ).toEqual({ + type: "string", + }); + }); + + test("should be idempotent", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + x: { + oneOf: [{ type: "string" }, { type: "string" }], + }, + y: { allOf: [{ type: "number" }] }, + }, + }; + const once = simplifySchema(schema); + const twice = simplifySchema(once); + expect(twice).toEqual(once); + }); + + test("should not change properties when nothing is simplifiable", () => { + const schema: JSONSchema7 = { + type: "object", + properties: { + name: { type: "string" }, + age: { type: "number" }, + }, + }; + expect(simplifySchema(schema)).toEqual(schema); + }); + + test("should deduplicate anyOf inside items", () => { + const schema: JSONSchema7 = { + type: "array", + items: { + anyOf: [{ type: "string" }, { type: "number" }, { type: "string" }], + }, + }; + expect(simplifySchema(schema)).toEqual({ + type: "array", + items: { + anyOf: [{ type: "string" }, { type: "number" }], + }, + }); + }); }); });