@palantir/pack.schema 0.0.1-beta.1

package/src/__tests__/defineUnion.test.ts

@@ -0,0 +1,231 @@
+/*
+ * Copyright 2025 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 { defineRecord } from "../defineRecord.js";
+import { defineUnion } from "../defineUnion.js";
+import * as P from "../primitives.js";
+import { assertExactKeys, assertTypeEquals } from "./testTypeUtils.js";
+
+describe("defineUnion", () => {
+  it("should create a basic union definition with record types", () => {
+    const TextRecord = defineRecord("Text", {
+      docs: "A text value",
+      fields: {
+        value: P.String,
+      },
+    });
+
+    const NumberRecord = defineRecord("Number", {
+      docs: "A number value",
+      fields: {
+        value: P.Double,
+      },
+    });
+
+    const ValueUnion = defineUnion("Value", {
+      docs: "A value union",
+      variants: {
+        text: TextRecord,
+        number: NumberRecord,
+      },
+    });
+
+    expect(ValueUnion.type).toBe("union");
+    expect(ValueUnion.name).toBe("Value");
+    expect(ValueUnion.discriminant).toBe("type");
+    expect(ValueUnion.variants.text).toEqual({
+      type: "ref",
+      name: "Text",
+      refType: "record",
+    });
+    expect(ValueUnion.variants.number).toEqual({
+      type: "ref",
+      name: "Number",
+      refType: "record",
+    });
+
+    assertExactKeys<typeof ValueUnion.variants, "text" | "number">();
+    assertTypeEquals<typeof ValueUnion.variants.text, P.Ref>();
+    assertTypeEquals<typeof ValueUnion.variants.number, P.Ref>();
+  });
+
+  it("should create a union definition with record types", () => {
+    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 ShapeUnion = defineUnion("Shape", {
+      docs: "A shape union",
+      variants: {
+        circle: CircleRecord,
+        rectangle: RectangleRecord,
+      },
+    });
+
+    expect(ShapeUnion.type).toBe("union");
+    expect(ShapeUnion.variants.circle).toEqual({
+      type: "ref",
+      name: "Circle",
+      refType: "record",
+    });
+    expect(ShapeUnion.variants.rectangle).toEqual({
+      type: "ref",
+      name: "Rectangle",
+      refType: "record",
+    });
+
+    assertExactKeys<typeof ShapeUnion.variants, "circle" | "rectangle">();
+    assertTypeEquals<typeof ShapeUnion.variants.circle, P.Ref>();
+    assertTypeEquals<typeof ShapeUnion.variants.rectangle, P.Ref>();
+  });
+
+  it("should create a union with nested unions", () => {
+    const PersonRecord = defineRecord("Person", {
+      docs: "A person",
+      fields: {
+        name: P.String,
+        age: P.Double,
+      },
+    });
+
+    const AnimalRecord = defineRecord("Animal", {
+      docs: "An animal",
+      fields: {
+        species: P.String,
+      },
+    });
+
+    const LivingBeingUnion = defineUnion("LivingBeing", {
+      docs: "A living being",
+      variants: {
+        person: PersonRecord,
+        animal: AnimalRecord,
+      },
+    });
+
+    const MachineRecord = defineRecord("Machine", {
+      docs: "A machine",
+      fields: {
+        model: P.String,
+      },
+    });
+
+    const EntityUnion = defineUnion("Entity", {
+      docs: "An entity union",
+      variants: {
+        livingBeing: LivingBeingUnion,
+        machine: MachineRecord,
+      },
+    });
+
+    expect(EntityUnion.variants.livingBeing).toEqual({
+      type: "ref",
+      name: "LivingBeing",
+      refType: "union",
+    });
+    expect(EntityUnion.variants.machine).toEqual({
+      type: "ref",
+      name: "Machine",
+      refType: "record",
+    });
+
+    assertExactKeys<typeof EntityUnion.variants, "livingBeing" | "machine">();
+    assertTypeEquals<typeof EntityUnion.variants.livingBeing, P.Ref>();
+    assertTypeEquals<typeof EntityUnion.variants.machine, P.Ref>();
+  });
+
+  it("should have correct union name", () => {
+    const Option1Record = defineRecord("Option1", {
+      docs: "Option 1",
+      fields: {
+        value: P.String,
+      },
+    });
+
+    const Option2Record = defineRecord("Option2", {
+      docs: "Option 2",
+      fields: {
+        value: P.Double,
+      },
+    });
+
+    const TestUnion = defineUnion("TestUnion", {
+      docs: "A test union",
+      variants: {
+        option1: Option1Record,
+        option2: Option2Record,
+      },
+    });
+
+    expect(TestUnion.name).toBe("TestUnion");
+  });
+
+  it("should preserve all item keys", () => {
+    const FirstRecord = defineRecord("First", {
+      docs: "First option",
+      fields: { value: P.String },
+    });
+
+    const SecondRecord = defineRecord("Second", {
+      docs: "Second option",
+      fields: { value: P.Double },
+    });
+
+    const ThirdRecord = defineRecord("Third", {
+      docs: "Third option",
+      fields: { value: P.String },
+    });
+
+    const FourthRecord = defineRecord("Fourth", {
+      docs: "Fourth option",
+      fields: { value: P.Double },
+    });
+
+    const MultiOptionUnion = defineUnion("MultiOption", {
+      docs: "A multi-option union",
+      variants: {
+        first: FirstRecord,
+        second: SecondRecord,
+        third: ThirdRecord,
+        fourth: FourthRecord,
+      },
+    });
+
+    expect(Object.keys(MultiOptionUnion.variants)).toEqual([
+      "first",
+      "second",
+      "third",
+      "fourth",
+    ]);
+
+    assertExactKeys<
+      typeof MultiOptionUnion.variants,
+      "first" | "second" | "third" | "fourth"
+    >();
+  });
+});

package/src/__tests__/integration.test.ts

@@ -0,0 +1,126 @@
+/*
+ * Copyright 2025 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 { defineMigration } from "../defineMigration.js";
+import { defineRecord } from "../defineRecord.js";
+import { defineUnion } from "../defineUnion.js";
+import * as P from "../primitives.js";
+
+describe("Integration Tests", () => {
+  describe("Basic record relationships", () => {
+    it("should create records with direct references", () => {
+      const AuthorRecord = defineRecord("Author", {
+        docs: "An author",
+        fields: {
+          name: P.String,
+          email: P.String,
+        },
+      });
+
+      const BookRecord = defineRecord("Book", {
+        docs: "A book",
+        fields: {
+          title: P.String,
+          author: AuthorRecord,
+        },
+      });
+
+      expect(BookRecord.fields.author).toEqual({
+        type: "ref",
+        name: "Author",
+        refType: "record",
+      });
+
+      expect(BookRecord.fields.title).toEqual({
+        type: "string",
+      });
+    });
+
+    it("should create unions with record references", () => {
+      const PersonRecord = defineRecord("Person", {
+        docs: "A person entity",
+        fields: {
+          name: P.String,
+          age: P.Double,
+        },
+      });
+
+      const OrganizationRecord = defineRecord("Organization", {
+        docs: "An organization entity",
+        fields: {
+          name: P.String,
+          industry: P.String,
+        },
+      });
+
+      const EntityUnion = defineUnion("Entity", {
+        docs: "An entity",
+        variants: {
+          person: PersonRecord,
+          organization: OrganizationRecord,
+        },
+      });
+
+      expect(EntityUnion.variants.person).toEqual({
+        type: "ref",
+        name: "Person",
+        refType: "record",
+      });
+
+      expect(EntityUnion.variants.organization).toEqual({
+        type: "ref",
+        name: "Organization",
+        refType: "record",
+      });
+    });
+  });
+
+  describe("Schema evolution with migrations", () => {
+    it("should evolve a schema through multiple versions", () => {
+      // Version 1: Basic user schema
+      const v1Schema = {
+        User: defineRecord("User", {
+          docs: "User account",
+          fields: {
+            username: P.String,
+            email: P.String,
+          },
+        }),
+      };
+
+      // Version 2: Add profile information
+      const v2Schema = defineMigration(v1Schema, schema => ({
+        UserWithProfile: schema.User.addField("firstName", P.String)
+          .addField("lastName", P.String)
+          .addField("age", P.Optional(P.Double))
+          .build(),
+      }));
+
+      expect(v2Schema.User).toBe(v1Schema.User);
+      expect(v2Schema.UserWithProfile.fields.username).toEqual({
+        type: "string",
+      });
+      expect(v2Schema.UserWithProfile.fields.firstName).toEqual({
+        type: "string",
+      });
+      expect(v2Schema.UserWithProfile.fields.age).toEqual({
+        type: "optional",
+        item: { type: "double" },
+      });
+    });
+  });
+});

package/src/__tests__/primitives.test.ts

@@ -0,0 +1,153 @@
+/*
+ * Copyright 2025 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 * as P from "../primitives.js";
+
+describe("primitives", () => {
+  describe("String", () => {
+    it("should create a string type", () => {
+      expect(P.String).toEqual({ type: "string" });
+    });
+
+    it("should have correct type property", () => {
+      expect(P.String.type).toBe("string");
+    });
+  });
+
+  describe("Double", () => {
+    it("should create a double type", () => {
+      expect(P.Double).toEqual({ type: "double" });
+    });
+
+    it("should have correct type property", () => {
+      expect(P.Double.type).toBe("double");
+    });
+  });
+
+  describe("Array", () => {
+    it("should create an array of strings", () => {
+      const stringArray = P.Array(P.String);
+      expect(stringArray).toEqual({
+        type: "array",
+        items: { type: "string" },
+      });
+    });
+
+    it("should create an array of doubles", () => {
+      const doubleArray = P.Array(P.Double);
+      expect(doubleArray).toEqual({
+        type: "array",
+        items: { type: "double" },
+      });
+    });
+
+    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 create arrays of optional types", () => {
+      const optionalStringArray = P.Array(P.Optional(P.String));
+      expect(optionalStringArray).toEqual({
+        type: "array",
+        items: {
+          type: "optional",
+          item: { type: "string" },
+        },
+      });
+    });
+  });
+
+  describe("Optional", () => {
+    it("should create an optional string", () => {
+      const optionalString = P.Optional(P.String);
+      expect(optionalString).toEqual({
+        type: "optional",
+        item: { type: "string" },
+      });
+    });
+
+    it("should create an optional double", () => {
+      const optionalDouble = P.Optional(P.Double);
+      expect(optionalDouble).toEqual({
+        type: "optional",
+        item: { type: "double" },
+      });
+    });
+
+    it("should create optional arrays", () => {
+      const optionalArray = P.Optional(P.Array(P.String));
+      expect(optionalArray).toEqual({
+        type: "optional",
+        item: {
+          type: "array",
+          items: { type: "string" },
+        },
+      });
+    });
+
+    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" },
+        },
+      });
+    });
+  });
+
+  describe("Type combinations", () => {
+    it("should create complex nested structures", () => {
+      const complexType = P.Optional(P.Array(P.Optional(P.Array(P.String))));
+      expect(complexType).toEqual({
+        type: "optional",
+        item: {
+          type: "array",
+          items: {
+            type: "optional",
+            item: {
+              type: "array",
+              items: { type: "string" },
+            },
+          },
+        },
+      });
+    });
+
+    it("should maintain immutability of primitive types", () => {
+      const string1 = P.String;
+      const string2 = P.String;
+      expect(string1).toBe(string2);
+      expect(string1 === string2).toBe(true);
+    });
+
+    it("should create new instances for constructed types", () => {
+      const array1 = P.Array(P.String);
+      const array2 = P.Array(P.String);
+      expect(array1).toEqual(array2);
+      expect(array1 === array2).toBe(false);
+    });
+  });
+});

package/src/__tests__/testTypeUtils.ts

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2025 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.
+ */
+
+/**
+ * Checks if two types are exactly equal
+ */
+
+export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2)
+  ? true
+  : false;
+
+/**
+ * Asserts that two types are exactly equal. Causes a compile error if not.
+ *
+ * @example
+ * // This will compile only if PersonRecord.fields.name is exactly String
+ * assertTypeEquals<typeof PersonRecord.fields.name, String>();
+ */
+export function assertTypeEquals<T, U>(
+  _witness?: Equals<T, U> extends true ? unknown : never,
+): void {}
+
+/**
+ * Checks if T extends U
+ */
+export type Extends<T, U> = T extends U ? true : false;
+
+/**
+ * Asserts that T extends U. Causes a compile error if not.
+ *
+ * @example
+ * // This will compile only if T extends Record<string, unknown>
+ * assertTypeExtends<T, Record<string, unknown>>();
+ */
+export function assertTypeExtends<T, U>(
+  _witness?: Extends<T, U> extends true ? unknown : never,
+): void {}
+
+/**
+ * Asserts that a type has the specified keys. Causes a compile error if not.
+ *
+ * @example
+ * // This will compile only if PersonRecord.fields has exactly keys 'name' and 'age'
+ * assertExactKeys<typeof PersonRecord.fields, 'name' | 'age'>();
+ */
+export function assertExactKeys<T, K extends string>(
+  _witness?: Equals<keyof T, K> extends true ? unknown : never,
+): void {}
+
+/**
+ * Asserts that a type has at least the specified keys. Causes a compile error if not.
+ *
+ * @example
+ * // This will compile only if PersonRecord.fields has at least keys 'name' and 'age'
+ * assertHasKeys<typeof PersonRecord.fields, 'name' | 'age'>();
+ */
+
+export function assertHasKeys<T, K extends string>(
+  _witness?: K extends keyof T ? unknown : never,
+): void {}
+
+/**
+ * Assert that a value is never. Useful for exhaustiveness checks.
+ *
+ * @example
+ * function handleShape(shape: Shape) {
+ *   if (shape.type === 'circle') {
+ *     // handle circle
+ *   } else if (shape.type === 'rectangle') {
+ *     // handle rectangle
+ *   } else {
+ *     // This will cause a compile error if we forget to handle a shape type
+ *     assertNever(shape);
+ *   }
+ * }
+ */
+export function assertNever(_value: never): never {
+  throw new Error("Should be unreachable");
+}