@palantir/pack.schema 0.3.1 → 0.5.0

package/src/__tests__/defineSchemaUpdate.test.ts

@@ -0,0 +1,365 @@
+/*
+ * Copyright 2026 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { SchemaBuilder } from "../defineMigration.js";
+import { defineRecord } from "../defineRecord.js";
+import { defineSchema, defineSchemaUpdate, nextSchema } from "../defineSchemaUpdate.js";
+import { defineUnion } from "../defineUnion.js";
+import * as P from "../primitives.js";
+import { assertExactKeys, assertHasKeys, assertTypeEquals } from "./testTypeUtils.js";
+
+describe("defineSchemaUpdate", () => {
+  it("should create a schema update and apply it via nextSchema", () => {
+    const schemaV1 = defineSchema({
+      Person: defineRecord("Person", {
+        docs: "A person",
+        fields: {
+          name: P.String,
+        },
+      }),
+    });
+
+    const addAge = defineSchemaUpdate(
+      "addAge",
+      (schema: SchemaBuilder<typeof schemaV1.models>) => ({
+        PersonV2: schema.Person.addField("age", P.Double).build(),
+      }),
+    );
+
+    const schemaV2 = nextSchema(schemaV1).addSchemaUpdate(addAge).build();
+
+    expect(schemaV2.models.Person).toBe(schemaV1.models.Person);
+    expect(schemaV2.models.PersonV2.fields.name).toEqual({ type: "string" });
+    expect(schemaV2.models.PersonV2.fields.age).toEqual({ type: "double" });
+    expect(schemaV2.version).toBe(2);
+
+    assertHasKeys<typeof schemaV2.models, "Person" | "PersonV2">();
+    assertExactKeys<typeof schemaV2.models.PersonV2.fields, "name" | "age">();
+    assertTypeEquals<typeof schemaV2.models.PersonV2.fields.name, P.String>();
+    assertTypeEquals<typeof schemaV2.models.PersonV2.fields.age, P.Double>();
+  });
+
+  it("should compose multiple schema updates in one version", () => {
+    const schemaV1 = defineSchema({
+      ShapeBox: defineRecord("ShapeBox", {
+        docs: "A box shape",
+        fields: {
+          left: P.Double,
+          right: P.Double,
+          color: P.Optional(P.String),
+        },
+      }),
+      ShapeCircle: defineRecord("ShapeCircle", {
+        docs: "A circle shape",
+        fields: {
+          cx: P.Double,
+          radius: P.Double,
+          color: P.Optional(P.String),
+        },
+      }),
+    });
+
+    const addFillColor = defineSchemaUpdate(
+      "addFillColor",
+      (schema: SchemaBuilder<typeof schemaV1.models>) => ({
+        ShapeBox: schema.ShapeBox
+          .addField("fillColor", P.Optional(P.String))
+          .build(),
+        ShapeCircle: schema.ShapeCircle
+          .addField("fillColor", P.Optional(P.String))
+          .build(),
+      }),
+    );
+
+    const addOpacity = defineSchemaUpdate(
+      "addOpacity",
+      (schema: SchemaBuilder<typeof schemaV1.models>) => ({
+        ShapeBox: schema.ShapeBox
+          .addField("opacity", P.Optional(P.Double))
+          .build(),
+        ShapeCircle: schema.ShapeCircle
+          .addField("opacity", P.Optional(P.Double))
+          .build(),
+      }),
+    );
+
+    const schemaV2 = nextSchema(schemaV1)
+      .addSchemaUpdate(addFillColor)
+      .addSchemaUpdate(addOpacity)
+      .build();
+
+    expect(schemaV2.models.ShapeBox.fields.fillColor).toEqual({
+      type: "optional",
+      item: { type: "string" },
+    });
+    expect(schemaV2.models.ShapeBox.fields.opacity).toEqual({
+      type: "optional",
+      item: { type: "double" },
+    });
+    expect(schemaV2.models.ShapeBox.fields.left).toEqual({ type: "double" });
+    expect(schemaV2.models.ShapeCircle.fields.fillColor).toEqual({
+      type: "optional",
+      item: { type: "string" },
+    });
+    expect(schemaV2.models.ShapeCircle.fields.opacity).toEqual({
+      type: "optional",
+      item: { type: "double" },
+    });
+    expect(schemaV2.version).toBe(2);
+  });
+
+  it("should track version advancement across multiple nextSchema calls", () => {
+    const schemaV1 = defineSchema({
+      Item: defineRecord("Item", {
+        docs: "An item",
+        fields: {
+          name: P.String,
+        },
+      }),
+    });
+
+    const addDescription = defineSchemaUpdate(
+      "addDescription",
+      (schema: SchemaBuilder<typeof schemaV1.models>) => ({
+        Item: schema.Item.addField("description", P.Optional(P.String)).build(),
+      }),
+    );
+
+    const schemaV2 = nextSchema(schemaV1).addSchemaUpdate(addDescription).build();
+
+    expect(schemaV2.version).toBe(2);
+
+    const addTags = defineSchemaUpdate(
+      "addTags",
+      (schema: SchemaBuilder<typeof schemaV2.models>) => ({
+        Item: schema.Item.addField("tags", P.Optional(P.String)).build(),
+      }),
+    );
+
+    const schemaV3 = nextSchema(schemaV2).addSchemaUpdate(addTags).build();
+
+    expect(schemaV3.version).toBe(3);
+    expect(schemaV3.models.Item.fields.name).toEqual({ type: "string" });
+    expect(schemaV3.models.Item.fields.description).toEqual({
+      type: "optional",
+      item: { type: "string" },
+    });
+    expect(schemaV3.models.Item.fields.tags).toEqual({
+      type: "optional",
+      item: { type: "string" },
+    });
+  });
+
+  it("should build a walkable version chain via .previous", () => {
+    const schemaV1 = defineSchema({
+      Node: defineRecord("Node", {
+        docs: "A node",
+        fields: {
+          label: P.String,
+        },
+      }),
+    });
+
+    const addWeight = defineSchemaUpdate(
+      "addWeight",
+      (schema: SchemaBuilder<typeof schemaV1.models>) => ({
+        Node: schema.Node.addField("weight", P.Double).build(),
+      }),
+    );
+
+    const schemaV2 = nextSchema(schemaV1).addSchemaUpdate(addWeight).build();
+
+    // v2 points back to the v1 InitialSchema
+    expect(schemaV2.previous).toBe(schemaV1);
+    expect(schemaV2.previous.type).toBe("initial");
+    expect(schemaV2.version).toBe(2);
+  });
+
+  it("should build a multi-step version chain", () => {
+    const schemaV1 = defineSchema({
+      Item: defineRecord("Item", {
+        docs: "An item",
+        fields: { name: P.String },
+      }),
+    });
+
+    const schemaV2 = nextSchema(schemaV1)
+      .addSchemaUpdate(
+        defineSchemaUpdate(
+          "addPrice",
+          schema => ({
+            Item: schema.Item.addField("price", P.Double).build(),
+          }),
+        ),
+      )
+      .build();
+
+    const schemaV3 = nextSchema(schemaV2)
+      .addSchemaUpdate(
+        defineSchemaUpdate(
+          "addTags",
+          schema => ({
+            Item: schema.Item.addField("tags", P.Optional(P.String)).build(),
+          }),
+        ),
+      )
+      .build();
+
+    // Walk the chain: v3 (versioned) -> v2 (versioned) -> v1 (initial)
+    expect(schemaV3.version).toBe(3);
+    expect(schemaV3.previous).toBe(schemaV2);
+    expect(schemaV3.previous.type).toBe("versioned");
+    if (schemaV3.previous.type === "versioned") {
+      expect(schemaV3.previous.previous).toBe(schemaV1);
+      expect(schemaV3.previous.previous.type).toBe("initial");
+    }
+  });
+
+  it("should discriminate via type field on built schemas", () => {
+    const schemaV1 = defineSchema({
+      Item: defineRecord("Item", {
+        docs: "An item",
+        fields: { name: P.String },
+      }),
+    });
+
+    const schemaV2 = nextSchema(schemaV1)
+      .addSchemaUpdate(
+        defineSchemaUpdate(
+          "addPrice",
+          schema => ({
+            Item: schema.Item.addField("price", P.Double).build(),
+          }),
+        ),
+      )
+      .build();
+
+    expect(schemaV2.type).toBe("versioned");
+    expect(schemaV2.previous.type).toBe("initial");
+  });
+
+  it("should work with union schema updates", () => {
+    const CircleRecord = defineRecord("Circle", {
+      docs: "A circle",
+      fields: { radius: P.Double },
+    });
+
+    const RectangleRecord = defineRecord("Rectangle", {
+      docs: "A rectangle",
+      fields: { width: P.Double, height: P.Double },
+    });
+
+    const TriangleRecord = defineRecord("Triangle", {
+      docs: "A triangle",
+      fields: { base: P.Double, height: P.Double },
+    });
+
+    const schemaV1 = defineSchema({
+      Shape: defineUnion("Shape", {
+        docs: "A shape",
+        variants: {
+          circle: CircleRecord,
+          rectangle: RectangleRecord,
+        },
+      }),
+    });
+
+    const addTriangle = defineSchemaUpdate(
+      "addTriangle",
+      (schema: SchemaBuilder<typeof schemaV1.models>) => ({
+        Shape: schema.Shape.addVariant("triangle", TriangleRecord).build(),
+      }),
+    );
+
+    const schemaV2 = nextSchema(schemaV1).addSchemaUpdate(addTriangle).build();
+
+    expect(schemaV2.models.Shape.variants.circle).toEqual({
+      type: "ref",
+      name: "Circle",
+      refType: "record",
+    });
+    expect(schemaV2.models.Shape.variants.triangle).toEqual({
+      type: "ref",
+      name: "Triangle",
+      refType: "record",
+    });
+    expect(schemaV2.version).toBe(2);
+
+    assertExactKeys<
+      typeof schemaV2.models.Shape.variants,
+      "circle" | "rectangle" | "triangle"
+    >();
+  });
+
+  it("should handle mixed record and union updates in one version", () => {
+    const PersonRecord = defineRecord("Person", {
+      docs: "A person",
+      fields: { name: P.String },
+    });
+
+    const OrganizationRecord = defineRecord("Organization", {
+      docs: "An organization",
+      fields: { orgName: P.String },
+    });
+
+    const schemaV1 = defineSchema({
+      Person: PersonRecord,
+      Entity: defineUnion("Entity", {
+        docs: "An entity",
+        variants: {
+          person: PersonRecord,
+        },
+      }),
+    });
+
+    const addAge = defineSchemaUpdate(
+      "addAge",
+      (schema: SchemaBuilder<typeof schemaV1.models>) => ({
+        PersonV2: schema.Person.addField("age", P.Double).build(),
+      }),
+    );
+
+    const addOrgVariant = defineSchemaUpdate(
+      "addOrgVariant",
+      (schema: SchemaBuilder<typeof schemaV1.models>) => ({
+        Entity: schema.Entity.addVariant("organization", OrganizationRecord).build(),
+      }),
+    );
+
+    const schemaV2 = nextSchema(schemaV1)
+      .addSchemaUpdate(addAge)
+      .addSchemaUpdate(addOrgVariant)
+      .build();
+
+    expect(schemaV2.models.PersonV2.fields.name).toEqual({ type: "string" });
+    expect(schemaV2.models.PersonV2.fields.age).toEqual({ type: "double" });
+    expect(schemaV2.models.Entity.variants.person).toEqual({
+      type: "ref",
+      name: "Person",
+      refType: "record",
+    });
+    expect(schemaV2.models.Entity.variants.organization).toEqual({
+      type: "ref",
+      name: "Organization",
+      refType: "record",
+    });
+
+    assertHasKeys<typeof schemaV2.models, "Person" | "PersonV2" | "Entity">();
+    assertExactKeys<typeof schemaV2.models.PersonV2.fields, "name" | "age">();
+    assertExactKeys<typeof schemaV2.models.Entity.variants, "person" | "organization">();
+  });
+});

package/src/__tests__/primitives.test.ts

@@ -65,15 +65,8 @@ describe("primitives", () => {
       });
     });
 
-    it("should create nested arrays", () => {
-      const nestedArray = P.Array(P.Array(P.String));
-      expect(nestedArray).toEqual({
-        type: "array",
-        items: {
-          type: "array",
-          items: { type: "string" },
-        },
-      });
+    it("should reject nested arrays", () => {
+      expect(() => P.Array(P.Array(P.String))).toThrow(/Nested arrays/);
     });
 
     it("should create arrays of optional types", () => {
@@ -124,15 +117,8 @@ describe("primitives", () => {
       });
     });
 
-    it("should handle nested optional types", () => {
-      const doubleOptional = P.Optional(P.Optional(P.String));
-      expect(doubleOptional).toEqual({
-        type: "optional",
-        item: {
-          type: "optional",
-          item: { type: "string" },
-        },
-      });
+    it("should reject nested optionals", () => {
+      expect(() => P.Optional(P.Optional(P.String))).toThrow(/Nested optionals/);
     });
 
     it("should create an optional boolean", () => {
@@ -167,23 +153,24 @@ describe("primitives", () => {
   });
 
   describe("Type combinations", () => {
-    it("should create complex nested structures", () => {
-      const complexType = P.Optional(P.Array(P.Optional(P.Array(P.String))));
+    it("should create optional array of optional strings", () => {
+      const complexType = P.Optional(P.Array(P.Optional(P.String)));
       expect(complexType).toEqual({
         type: "optional",
         item: {
           type: "array",
           items: {
             type: "optional",
-            item: {
-              type: "array",
-              items: { type: "string" },
-            },
+            item: { type: "string" },
           },
         },
       });
     });
 
+    it("should reject nested arrays even when inner array is wrapped in optional", () => {
+      expect(() => P.Array(P.Optional(P.Array(P.String)))).toThrow(/Nested arrays/);
+    });
+
     it("should maintain immutability of primitive types", () => {
       const string1 = P.String;
       const string2 = P.String;

package/src/defineMigration.ts

@@ -16,16 +16,18 @@
 
 import type { UnionVariantArg } from "./defineUnion.js";
 import { resolveUnionVariantArg } from "./defineUnion.js";
-import type { RecordDef, RecordFields, UnionDef, UnionVariants } from "./defs.js";
+import type { ModelDefs, RecordDef, RecordFields, UnionDef, UnionVariants } from "./defs.js";
 import { ModelDefType } from "./defs.js";
 import type { Ref, Type } from "./primitives.js";
 import { isRecordDef, isUnionDef } from "./utils.js";
 
-export type ReturnedSchema = Record<string, RecordDef | UnionDef>;
+/** Soon to be deprecated - Use `ModelDefs` instead. */
+export type ReturnedSchema = ModelDefs;
 
-export type Schema<T extends ReturnedSchema> = T;
+/** Soon to be deprecated - use `ModelDefs` instead. */
+export type Schema<T extends ModelDefs> = T;
 
-export type SchemaBuilder<T extends ReturnedSchema> = {
+export type SchemaBuilder<T extends ModelDefs> = {
   [k in keyof T]: T[k] extends UnionDef<infer R> ? UnionBuilder<R>
     : T[k] extends RecordDef<infer R> ? RecordBuilder<R>
     : never;
@@ -114,46 +116,28 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
 }
 
 export function defineMigration<
-  const T extends ReturnedSchema,
-  const S extends ReturnedSchema,
+  const T extends ModelDefs,
+  const S extends ModelDefs,
 >(
-  previous: Schema<T>,
+  models: T,
   migration: (schema: SchemaBuilder<T>) => S,
-): Schema<T & S> {
-  /**
-   * Create a map of builders for the schema.
-   *
-   * Note about type assertions:
-   * We use a type assertion here (SchemaBuilder<T>) because TypeScript cannot
-   * track the relationship between the keys in the original schema and the
-   * corresponding builder types. This is a fundamental limitation of TypeScript's
-   * type system when dealing with dynamically constructed objects.
-   *
-   * The assertion is safe because:
-   * 1. We're only adding keys that exist in the original schema
-   * 2. For each key, we're creating a builder of the correct type
-   * 3. The resulting object exactly matches the SchemaBuilder<T> type
-   */
+): T & S {
   const builders = {} as SchemaBuilder<T>;
 
-  for (const key in previous) {
-    const v = previous[key];
+  for (const key in models) {
+    const v = models[key];
 
-    // Use our type guards for safer type narrowing
     if (isRecordDef(v)) {
-      // This assertion is necessary because TypeScript can't track the field types
-      // through the dynamic property access and object construction
       const recordBuilder = new RecordBuilderImpl(v);
       builders[key] = recordBuilder as unknown as SchemaBuilder<T>[typeof key];
     } else if (isUnionDef(v)) {
-      // Similar assertion needed for union builders
       const unionBuilder = new UnionBuilderImpl(v);
       builders[key] = unionBuilder as unknown as SchemaBuilder<T>[typeof key];
     }
   }
 
   return {
-    ...previous,
+    ...models,
     ...migration(builders),
   };
 }

package/src/defineSchemaUpdate.ts

@@ -0,0 +1,114 @@
+/*
+ * Copyright 2026 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { SchemaBuilder } from "./defineMigration.js";
+import { defineMigration } from "./defineMigration.js";
+import type { ModelDefs } from "./defs.js";
+
+export interface InitialSchema<T extends ModelDefs = ModelDefs> {
+  readonly type: "initial";
+  readonly version: 1;
+  readonly models: T;
+}
+
+export interface FieldMigration {
+  readonly derivedFrom: readonly string[];
+  readonly forward: (oldFields: Record<string, unknown>) => unknown;
+}
+
+export type VersionMigrations = Record<string, Record<string, FieldMigration>>;
+
+export interface VersionedSchema<T extends ModelDefs = ModelDefs> {
+  readonly type: "versioned";
+  readonly models: T;
+  readonly version: number;
+  readonly previous: SchemaDefinition;
+  readonly migrations?: VersionMigrations;
+}
+
+export type SchemaDefinition<T extends ModelDefs = ModelDefs> =
+  | InitialSchema<T>
+  | VersionedSchema<T>;
+
+export function defineSchema<T extends ModelDefs>(models: T): InitialSchema<T> {
+  return { type: "initial", version: 1, models };
+}
+
+export interface SchemaUpdate<T extends ModelDefs, S extends ModelDefs> {
+  readonly name: string;
+  readonly migration: (schema: SchemaBuilder<T>) => S;
+}
+
+export function defineSchemaUpdate<T extends ModelDefs, S extends ModelDefs>(
+  name: string,
+  migration: (schema: SchemaBuilder<T>) => S,
+): SchemaUpdate<T, S> {
+  return { name, migration };
+}
+
+export interface SchemaVersionBuilder<T extends ModelDefs> {
+  addSchemaUpdate<S extends ModelDefs>(
+    update: SchemaUpdate<T, S>,
+  ): SchemaVersionBuilder<T & S>;
+  withMigrations(migrations: VersionMigrations): SchemaVersionBuilder<T>;
+  build(): VersionedSchema<T>;
+}
+
+class SchemaVersionBuilderImpl<T extends ModelDefs> implements SchemaVersionBuilder<T> {
+  private readonly models: T;
+  private readonly version: number;
+  private readonly previous: SchemaDefinition;
+  private readonly _migrations: VersionMigrations | undefined;
+
+  constructor(
+    models: T,
+    version: number,
+    previous: SchemaDefinition,
+    migrations?: VersionMigrations,
+  ) {
+    this.models = models;
+    this.version = version;
+    this.previous = previous;
+    this._migrations = migrations;
+  }
+
+  addSchemaUpdate<S extends ModelDefs>(
+    update: SchemaUpdate<T, S>,
+  ): SchemaVersionBuilder<T & S> {
+    const merged = defineMigration(this.models, update.migration);
+    return new SchemaVersionBuilderImpl(merged, this.version, this.previous, this._migrations);
+  }
+
+  withMigrations(migrations: VersionMigrations): SchemaVersionBuilder<T> {
+    return new SchemaVersionBuilderImpl(this.models, this.version, this.previous, migrations);
+  }
+
+  build(): VersionedSchema<T> {
+    return {
+      type: "versioned",
+      models: { ...this.models },
+      version: this.version,
+      previous: this.previous,
+      ...(this._migrations != null ? { migrations: this._migrations } : {}),
+    };
+  }
+}
+
+export function nextSchema<T extends ModelDefs>(
+  previous: SchemaDefinition<T>,
+): SchemaVersionBuilder<T> {
+  return new SchemaVersionBuilderImpl(previous.models, previous.version + 1, previous);
+}

package/src/defs.ts

@@ -44,3 +44,4 @@ export interface RecordDef<TFields extends RecordFields = RecordFields> extends
 }
 
 export type ModelDef = RecordDef | UnionDef;
+export type ModelDefs = Record<string, ModelDef>;

package/src/index.ts

@@ -16,6 +16,7 @@
 
 export * from "./defineMigration.js";
 export * from "./defineRecord.js";
+export * from "./defineSchemaUpdate.js";
 export * from "./defineUnion.js";
 export * from "./defs.js";
 export * from "./primitives.js";

package/src/primitives.ts

@@ -101,11 +101,22 @@ export const String: String = { type: TypeKind.STRING };
 export const Double: Double = { type: TypeKind.DOUBLE };
 export const Boolean: Boolean = { type: TypeKind.BOOLEAN };
 export const Unknown: Unknown = { type: TypeKind.UNKNOWN };
-export const Array = <T extends TypeBase>(item: T): Array<T> => ({
-  type: TypeKind.ARRAY,
-  items: item,
-});
-export const Optional = <T extends TypeBase>(item: T): Optional<T> => ({
-  type: TypeKind.OPTIONAL,
-  item,
-});
+function unwrapOneOptional(t: TypeBase): TypeBase {
+  return t.type === TypeKind.OPTIONAL && "item" in t ? (t as { item: TypeBase }).item : t;
+}
+
+export const Array = <T extends TypeBase>(item: T): Array<T> => {
+  if (unwrapOneOptional(item).type === TypeKind.ARRAY) {
+    throw new Error(
+      "Nested arrays (Array(Array(...)) or Array(Optional(Array(...)))) are not supported. "
+        + "Wrap the inner array in a record instead.",
+    );
+  }
+  return { type: TypeKind.ARRAY, items: item };
+};
+export const Optional = <T extends TypeBase>(item: T): Optional<T> => {
+  if (item.type === TypeKind.OPTIONAL) {
+    throw new Error("Nested optionals (Optional(Optional(...))) are not supported.");
+  }
+  return { type: TypeKind.OPTIONAL, item };
+};