@palantir/pack.schema 0.30.0 → 0.32.0

package/src/__tests__/defineSchemaUpdate.test.ts

@@ -43,6 +43,7 @@ describe("defineSchemaUpdate", () => {
     const schemaV2 = nextSchema(schemaV1).addSchemaUpdate(addAge).build();
 
     expect(schemaV2.models.Person).toBe(schemaV1.models.Person);
+    expect(schemaV2.models.PersonV2.docs).toBe("A person");
     expect(schemaV2.models.PersonV2.fields.name).toEqual({ type: "string" });
     expect(schemaV2.models.PersonV2.fields.age).toEqual({ type: "double" });
     expect(schemaV2.version).toBe(2);
@@ -53,6 +54,50 @@ describe("defineSchemaUpdate", () => {
     assertTypeEquals<typeof schemaV2.models.PersonV2.fields.age, P.Double>();
   });
 
+  it("should preserve record documentation through field additions and deprecations", () => {
+    const schemaV1 = defineSchema({
+      Person: defineRecord("Person", {
+        docs: "A person",
+        fields: { name: P.String },
+      }),
+    });
+
+    const schemaV2 = nextSchema(schemaV1)
+      .addSchemaUpdate(defineSchemaUpdate("addDisplayName", schema => ({
+        Person: schema.Person
+          .addField("displayName", P.String, { derivedFrom: ["name"] })
+          .deprecateField("name", "Use displayName instead.")
+          .build(),
+      })))
+      .build();
+
+    expect(schemaV2.models.Person.docs).toBe("A person");
+    expect(schemaV2.models.Person.fields).toEqual({ name: P.String, displayName: P.String });
+    expect(schemaV2.migrations?.Person?.displayName).toEqual({ derivedFrom: ["name"] });
+    expect(schemaV2.deprecations?.Person?.name).toEqual({
+      fromVersion: 2,
+      message: "Use displayName instead.",
+    });
+    expect(schemaV1.models.Person.fields).toEqual({ name: P.String });
+  });
+
+  it("should preserve a record when building without changing fields", () => {
+    const schemaV1 = defineSchema({
+      Person: defineRecord("Person", {
+        docs: "A person",
+        fields: { name: P.String },
+      }),
+    });
+
+    const schemaV2 = nextSchema(schemaV1)
+      .addSchemaUpdate(defineSchemaUpdate("rebuildPerson", schema => ({
+        Person: schema.Person.build(),
+      })))
+      .build();
+
+    expect(schemaV2.models.Person).toEqual(schemaV1.models.Person);
+  });
+
   it("should compose multiple schema updates in one version", () => {
     const schemaV1 = defineSchema({
       ShapeBox: defineRecord("ShapeBox", {
@@ -153,6 +198,7 @@ describe("defineSchemaUpdate", () => {
     const schemaV3 = nextSchema(schemaV2).addSchemaUpdate(addTags).build();
 
     expect(schemaV3.version).toBe(3);
+    expect(schemaV3.models.Item.docs).toBe("An item");
     expect(schemaV3.models.Item.fields.name).toEqual({ type: "string" });
     expect(schemaV3.models.Item.fields.description).toEqual({
       type: "optional",
@@ -287,6 +333,8 @@ describe("defineSchemaUpdate", () => {
 
     const schemaV2 = nextSchema(schemaV1).addSchemaUpdate(addTriangle).build();
 
+    expect(schemaV2.models.Shape.discriminant).toBe("type");
+    expect(schemaV2.models.Shape.docs).toBe("A shape");
     expect(schemaV2.models.Shape.variants.circle).toEqual({
       type: "ref",
       name: "Circle",
@@ -305,6 +353,115 @@ describe("defineSchemaUpdate", () => {
     >();
   });
 
+  it("should preserve union metadata through chained variant additions", () => {
+    const Circle = defineRecord("Circle", {
+      docs: "A circle",
+      fields: { radius: P.Double },
+    });
+    const Rectangle = defineRecord("Rectangle", {
+      docs: "A rectangle",
+      fields: { width: P.Double, height: P.Double },
+    });
+    const Triangle = defineRecord("Triangle", {
+      docs: "A triangle",
+      fields: { base: P.Double, height: P.Double },
+    });
+    const schemaV1 = defineSchema({
+      Circle,
+      Rectangle,
+      Triangle,
+      Shape: defineUnion("Shape", {
+        discriminant: "kind",
+        docs: "A shape",
+        variants: { circle: Circle },
+      }),
+    });
+
+    const schemaV2 = nextSchema(schemaV1)
+      .addSchemaUpdate(defineSchemaUpdate("addShapes", schema => ({
+        Shape: schema.Shape.addVariant("rectangle", Rectangle)
+          .addVariant("triangle", Triangle)
+          .build(),
+      })))
+      .build();
+
+    expect(schemaV2.models.Shape).toEqual({
+      ...schemaV1.models.Shape,
+      variants: {
+        circle: { type: "ref", name: "Circle", refType: "record" },
+        rectangle: { type: "ref", name: "Rectangle", refType: "record" },
+        triangle: { type: "ref", name: "Triangle", refType: "record" },
+      },
+    });
+    expect(schemaV1.models.Shape.variants).toEqual({
+      circle: { type: "ref", name: "Circle", refType: "record" },
+    });
+
+    const schemaV3 = nextSchema(schemaV2)
+      .addSchemaUpdate(defineSchemaUpdate("rebuildShape", schema => ({
+        Shape: schema.Shape.build(),
+      })))
+      .build();
+
+    expect(schemaV3.models.Shape).toEqual(schemaV2.models.Shape);
+  });
+
+  it("should preserve a union when building without adding variants", () => {
+    const Circle = defineRecord("Circle", {
+      docs: "A circle",
+      fields: { radius: P.Double },
+    });
+    const schemaV1 = defineSchema({
+      Circle,
+      Shape: defineUnion("Shape", {
+        discriminant: "kind",
+        docs: "A shape",
+        variants: { circle: Circle },
+      }),
+    });
+
+    const schemaV2 = nextSchema(schemaV1)
+      .addSchemaUpdate(defineSchemaUpdate("rebuildShape", schema => ({
+        Shape: schema.Shape.build(),
+      })))
+      .build();
+
+    expect(schemaV2.models.Shape).toEqual(schemaV1.models.Shape);
+  });
+
+  it.each(["circle", "rectangle"] as const)("should reject duplicate variant %s", variantName => {
+    const Circle = defineRecord("Circle", {
+      docs: "A circle",
+      fields: { radius: P.Double },
+    });
+    const Rectangle = defineRecord("Rectangle", {
+      docs: "A rectangle",
+      fields: { width: P.Double, height: P.Double },
+    });
+    const schemaV1 = defineSchema({
+      Circle,
+      Rectangle,
+      Shape: defineUnion("Shape", {
+        docs: "A shape",
+        variants: { circle: Circle },
+      }),
+    });
+
+    expect(() =>
+      nextSchema(schemaV1)
+        .addSchemaUpdate(defineSchemaUpdate("addShapes", schema => ({
+          Shape: schema.Shape.addVariant("rectangle", Rectangle)
+            // @ts-expect-error Existing variant names cannot be added again.
+            .addVariant(variantName, Rectangle)
+            .build(),
+        })))
+        .build()
+    ).toThrow(`Variant "${variantName}" already exists in union "Shape".`);
+    expect(schemaV1.models.Shape.variants).toEqual({
+      circle: { type: "ref", name: "Circle", refType: "record" },
+    });
+  });
+
   it("should handle mixed record and union updates in one version", () => {
     const PersonRecord = defineRecord("Person", {
       docs: "A person",

package/src/__tests__/defineUnion.test.ts

@@ -268,3 +268,23 @@ describe("defineUnion", () => {
     });
   });
 });
+
+describe("reserved union variant names", () => {
+  const Circle = defineRecord("Circle", { docs: "A circle", fields: { radius: P.Double } });
+
+  it.each(["unknown", "Unknown", "_unknown"])("should reject a variant named %s", variantName => {
+    expect(() =>
+      defineUnion("Shape", { docs: "A shape", variants: { circle: Circle, [variantName]: Circle } })
+    ).toThrow(`Variant "${variantName}" in union "Shape" uses a reserved name.`);
+  });
+
+  it("should reject rawValue as the discriminant", () => {
+    expect(() =>
+      defineUnion("Shape", {
+        discriminant: "rawValue",
+        docs: "A shape",
+        variants: { circle: Circle },
+      })
+    ).toThrow("Union \"Shape\" can't use \"rawValue\" as its discriminant.");
+  });
+});

package/src/defineMigration.ts

@@ -15,7 +15,7 @@
  */
 
 import type { UnionVariantArg } from "./defineUnion.js";
-import { resolveUnionVariantArg } from "./defineUnion.js";
+import { assertVariantNameAllowed, resolveUnionVariantArg } from "./defineUnion.js";
 import type { ModelDefs, RecordDef, RecordFields, UnionDef, UnionVariants } from "./defs.js";
 import { ModelDefType } from "./defs.js";
 import type { Ref, Type } from "./primitives.js";
@@ -83,9 +83,9 @@ export interface RecordBuilder<T extends Record<string, Type>> {
 /** Evolves a union within a {@link SchemaUpdate}. Obtain one from the {@link SchemaBuilder} and finish with `build()`. */
 export interface UnionBuilder<S extends UnionVariants> {
   // TODO: builders should support arg types and resolveModels to refs
-  /** Add a variant, referencing a record (or a `Ref` to one). */
+  /** Add a new variant, referencing a record (or a `Ref` to one). */
   addVariant<const K extends string>(
-    name: K,
+    name: string extends keyof S ? K : Exclude<K, keyof S>,
     modelDefOrRef: UnionVariantArg,
   ): UnionBuilder<S & { [k in K]: Ref }>;
   /** Produce the updated {@link UnionDef}. */
@@ -95,32 +95,40 @@ export interface UnionBuilder<S extends UnionVariants> {
 class UnionBuilderImpl<S extends UnionVariants> implements UnionBuilder<S> {
   private readonly name: string;
   private readonly docs: string | undefined;
+  private readonly discriminant: string;
   private readonly variants: S;
-  constructor({ name, docs, variants }: UnionDef<S>) {
+  constructor({ name, docs, discriminant, variants }: UnionDef<S>) {
     this.name = name;
     this.docs = docs;
+    this.discriminant = discriminant;
     this.variants = { ...variants };
   }
   addVariant<const K extends string>(
-    variantName: K,
+    variantName: string extends keyof S ? K : Exclude<K, keyof S>,
     modelDefOrRef: UnionVariantArg,
   ): UnionBuilder<S & Record<K, Ref>> {
+    if (Object.hasOwn(this.variants, variantName)) {
+      throw new Error(`Variant "${variantName}" already exists in union "${this.name}".`);
+    }
+    assertVariantNameAllowed(variantName, this.name);
     const ref: Ref = resolveUnionVariantArg(modelDefOrRef);
     const newVariants = { ...this.variants, [variantName]: ref };
 
     return new UnionBuilderImpl({
       type: ModelDefType.UNION,
       name: this.name,
+      docs: this.docs,
       variants: newVariants,
-      discriminant: "type",
+      discriminant: this.discriminant,
     });
   }
   build(): UnionDef<S> {
     return {
       type: ModelDefType.UNION,
       variants: this.variants,
-      discriminant: "type",
+      discriminant: this.discriminant,
       name: this.name,
+      docs: this.docs,
     };
   }
 }
@@ -149,6 +157,7 @@ export interface FieldDeprecation {
 
 class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
   private readonly name: string;
+  private readonly docs: string | undefined;
   private readonly fields: T;
   private readonly upgradeOptions: ReadonlyMap<string, FieldOptions>;
   private readonly deprecatedFields: ReadonlyMap<string, FieldDeprecation>;
@@ -159,6 +168,7 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
     deprecatedFields?: ReadonlyMap<string, FieldDeprecation>,
   ) {
     this.name = initialRecordDef.name;
+    this.docs = initialRecordDef.docs;
     this.fields = { ...initialRecordDef.fields };
     // Upgrade options only flow forward within a single migration callback —
     // they are NOT inherited from the prior version's RecordDef, because each
@@ -182,7 +192,7 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
         type: ModelDefType.RECORD,
         name: this.name,
         fields: { ...this.fields, [name]: value },
-        docs: "",
+        docs: this.docs,
       },
       next,
       this.deprecatedFields,
@@ -200,7 +210,7 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
         type: ModelDefType.RECORD,
         name: this.name,
         fields: { ...this.fields },
-        docs: "",
+        docs: this.docs,
       },
       this.upgradeOptions,
       next,
@@ -212,7 +222,7 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
       type: ModelDefType.RECORD,
       name: this.name,
       fields: this.fields,
-      docs: "",
+      docs: this.docs,
     };
     if (this.upgradeOptions.size > 0) {
       Object.defineProperty(result, UPGRADE_OPTIONS_CARRIER, {

package/src/defineUnion.ts

@@ -61,9 +61,11 @@ export function defineUnion<const TVariants extends UnionVariantArgs>(
     variants,
   }: UnionArgs<TVariants>,
 ): UnionDef<ResolvedUnionVariants<TVariants>> {
-  const entries = Object.entries(variants).map(
-    ([key, value]) => [key, resolveUnionVariantArg(value)] as const,
-  );
+  assertDiscriminantAllowed(discriminant, name);
+  const entries = Object.entries(variants).map(([key, value]) => {
+    assertVariantNameAllowed(key, name);
+    return [key, resolveUnionVariantArg(value)] as const;
+  });
 
   const resolvedVariants = Object.fromEntries(entries) as ResolvedUnionVariants<TVariants>;
 
@@ -80,3 +82,38 @@ export function resolveUnionVariantArg(arg: UnionVariantArg): Ref {
   const resolved = typeof arg === "function" ? arg() : arg;
   return resolved.type === TypeKind.REF ? resolved : modelToRef(resolved);
 }
+
+/**
+ * The name a variant gets in generated code: kebab-case or snake_case to PascalCase,
+ * e.g. "my-box" -> "MyBox", "_unknown" -> "Unknown".
+ */
+export function formatVariantName(variantName: string): string {
+  return variantName
+    .split(/[-_]/)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+/**
+ * Throw if a variant uses a reserved name. Every generated union has an Unknown case for variants
+ * an SDK doesn't know: its discriminant is "unknown" and its generated names end in "Unknown", so
+ * no variant may produce either (e.g. "unknown", "Unknown", "_unknown").
+ */
+export function assertVariantNameAllowed(variantName: string, unionName: string): void {
+  if (formatVariantName(variantName) === "Unknown") {
+    throw new Error(
+      `Variant "${variantName}" in union "${unionName}" uses a reserved name. Every union has a`
+        + " generated Unknown case for variants an SDK doesn't know; choose another name.",
+    );
+  }
+}
+
+/** Throw if a discriminant uses `rawValue`, the field the Unknown case keeps the stored value in. */
+function assertDiscriminantAllowed(discriminant: string, unionName: string): void {
+  if (discriminant === "rawValue") {
+    throw new Error(
+      `Union "${unionName}" can't use "rawValue" as its discriminant. The generated Unknown case`
+        + " stores the original value in rawValue; choose another name.",
+    );
+  }
+}