@palantir/pack.schema 0.0.1-beta.1

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@palantir/pack.schema",
+  "version": "0.0.1-beta.1",
+  "description": "API package for PACK schema functionality",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/palantir/pack.git"
+  },
+  "exports": {
+    ".": {
+      "browser": "./build/browser/index.js",
+      "import": {
+        "types": "./build/types/index.d.ts",
+        "default": "./build/esm/index.js"
+      },
+      "require": "./build/cjs/index.js",
+      "default": "./build/browser/index.js"
+    },
+    "./*": {
+      "browser": "./build/browser/public/*.js",
+      "import": {
+        "types": "./build/types/public/*.d.ts",
+        "default": "./build/js/public/*.js"
+      },
+      "require": "./build/cjs/public/*.js",
+      "default": "./build/browser/public/*.js"
+    }
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.2",
+    "@palantir/pack.monorepo.tsconfig": "~0.4.0-beta.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./build/cjs/index.js",
+  "module": "./build/esm/index.js",
+  "types": "./build/cjs/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "clean": "rimraf .turbo build dist lib test-output *.tgz tsconfig.tsbuildinfo",
+    "lint": "eslint ./src ; dprint check --config $(find-up dprint.json) --allow-no-files",
+    "lint:fix": "eslint ./src --fix ; dprint fmt --config $(find-up dprint.json) --allow-no-files",
+    "test": "vitest run --passWithNoTests -u",
+    "test:watch": "vitest --passWithNoTests",
+    "transpileBrowser": "monorepo-transpile -f esm -m bundle -t browser",
+    "transpileCjs": "monorepo-transpile -f cjs -m bundle -t node",
+    "transpileEsm": "monorepo-transpile -f esm -m bundle -t node",
+    "transpileTypes": "monorepo-transpile -f esm -m types -t node",
+    "typecheck": "tsc --noEmit --emitDeclarationOnly false"
+  }
+}

package/src/__tests__/defineMigration.test.ts

@@ -0,0 +1,265 @@
+/*
+ * 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";
+import { assertExactKeys, assertHasKeys, assertTypeEquals } from "./testTypeUtils.js";
+
+describe("defineMigration", () => {
+  it("should create a new schema by extending record fields", () => {
+    const v1Schema = {
+      Person: defineRecord("Person", {
+        docs: "A person",
+        fields: {
+          name: P.String,
+        },
+      }),
+    };
+
+    const v2Schema = defineMigration(v1Schema, schema => ({
+      EnhancedPerson: schema.Person.addField("age", P.Double).build(),
+    }));
+
+    expect(v2Schema.Person).toBe(v1Schema.Person);
+    expect(v2Schema.EnhancedPerson.name).toBe("Person");
+    expect(v2Schema.EnhancedPerson.fields.name).toEqual({ type: "string" });
+    expect(v2Schema.EnhancedPerson.fields.age).toEqual({ type: "double" });
+
+    assertHasKeys<typeof v2Schema, "Person" | "EnhancedPerson">();
+    assertExactKeys<typeof v2Schema.EnhancedPerson.fields, "name" | "age">();
+    assertTypeEquals<typeof v2Schema.EnhancedPerson.fields.name, P.String>();
+    assertTypeEquals<typeof v2Schema.EnhancedPerson.fields.age, P.Double>();
+  });
+
+  it("should handle multiple field additions", () => {
+    const v1Schema = {
+      User: defineRecord("User", {
+        docs: "A user",
+        fields: {
+          username: P.String,
+        },
+      }),
+    };
+
+    const v2Schema = defineMigration(v1Schema, schema => ({
+      ExtendedUser: schema.User.addField("email", P.String)
+        .addField("age", P.Optional(P.Double))
+        .build(),
+    }));
+
+    expect(v2Schema.ExtendedUser.fields.username).toEqual({ type: "string" });
+    expect(v2Schema.ExtendedUser.fields.email).toEqual({ type: "string" });
+    expect(v2Schema.ExtendedUser.fields.age).toEqual({
+      type: "optional",
+      item: { type: "double" },
+    });
+
+    assertExactKeys<typeof v2Schema.ExtendedUser.fields, "username" | "email" | "age">();
+    assertTypeEquals<typeof v2Schema.ExtendedUser.fields.username, P.String>();
+    assertTypeEquals<typeof v2Schema.ExtendedUser.fields.email, P.String>();
+    assertTypeEquals<typeof v2Schema.ExtendedUser.fields.age, P.Optional<P.Double>>();
+  });
+
+  it("should extend union 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 v1Schema = {
+      Shape: defineUnion("Shape", {
+        docs: "A shape",
+        variants: {
+          circle: CircleRecord,
+        },
+      }),
+    };
+
+    const v2Schema = defineMigration(v1Schema, schema => ({
+      ExtendedShape: schema.Shape.addVariant("rectangle", RectangleRecord).build(),
+    }));
+
+    expect(v2Schema.ExtendedShape.variants.circle).toEqual({
+      type: "ref",
+      name: "Circle",
+      refType: "record",
+    });
+    expect(v2Schema.ExtendedShape.variants.rectangle).toEqual({
+      type: "ref",
+      name: "Rectangle",
+      refType: "record",
+    });
+
+    assertExactKeys<typeof v2Schema.ExtendedShape.variants, "circle" | "rectangle">();
+  });
+
+  it("should handle multiple union member additions", () => {
+    const TextRecord = defineRecord("Text", {
+      docs: "Text value",
+      fields: { value: P.String },
+    });
+
+    const NumberRecord = defineRecord("Number", {
+      docs: "Number value",
+      fields: { value: P.Double },
+    });
+
+    const OptionalTextRecord = defineRecord("OptionalText", {
+      docs: "Optional text value",
+      fields: { value: P.Optional(P.String) },
+    });
+
+    const v1Schema = {
+      Value: defineUnion("Value", {
+        docs: "A value",
+        variants: {
+          text: TextRecord,
+        },
+      }),
+    };
+
+    const v2Schema = defineMigration(v1Schema, schema => ({
+      ExtendedValue: schema.Value.addVariant("number", NumberRecord)
+        .addVariant("optional_text", OptionalTextRecord)
+        .build(),
+    }));
+
+    expect(v2Schema.ExtendedValue.variants.text).toEqual({
+      type: "ref",
+      name: "Text",
+      refType: "record",
+    });
+    expect(v2Schema.ExtendedValue.variants.number).toEqual({
+      type: "ref",
+      name: "Number",
+      refType: "record",
+    });
+    expect(v2Schema.ExtendedValue.variants.optional_text).toEqual({
+      type: "ref",
+      name: "OptionalText",
+      refType: "record",
+    });
+
+    assertExactKeys<typeof v2Schema.ExtendedValue.variants, "text" | "number" | "optional_text">();
+  });
+
+  it("should preserve original schema alongside new definitions", () => {
+    const originalRecord = defineRecord("Original", {
+      docs: "Original record",
+      fields: {
+        value: P.String,
+      },
+    });
+
+    const v1Schema = {
+      Original: originalRecord,
+    };
+
+    const v2Schema = defineMigration(v1Schema, schema => ({
+      Modified: schema.Original.addField("extra", P.Double).build(),
+    }));
+
+    expect(v2Schema.Original).toBe(originalRecord);
+    expect(v2Schema.Modified.fields.value).toEqual({ type: "string" });
+    expect(v2Schema.Modified.fields.extra).toEqual({ type: "double" });
+
+    assertHasKeys<typeof v2Schema, "Original" | "Modified">();
+    assertExactKeys<typeof v2Schema.Modified.fields, "value" | "extra">();
+    assertTypeEquals<typeof v2Schema.Modified.fields.value, P.String>();
+    assertTypeEquals<typeof v2Schema.Modified.fields.extra, P.Double>();
+  });
+
+  it("should handle mixed record and union migrations", () => {
+    const PersonRecord = defineRecord("Person", {
+      docs: "A person",
+      fields: {
+        name: P.String,
+      },
+    });
+
+    const OrganizationRecord = defineRecord("Organization", {
+      docs: "An organization",
+      fields: {
+        orgName: P.String,
+      },
+    });
+
+    const v1Schema = {
+      Person: PersonRecord,
+      Entity: defineUnion("Entity", {
+        docs: "An entity",
+        variants: {
+          person: PersonRecord,
+        },
+      }),
+    };
+
+    const v2Schema = defineMigration(v1Schema, schema => ({
+      ExtendedPerson: schema.Person.addField("age", P.Double).build(),
+      ExtendedEntity: schema.Entity.addVariant("organization", OrganizationRecord).build(),
+    }));
+
+    expect(v2Schema.ExtendedPerson.fields.name).toEqual({ type: "string" });
+    expect(v2Schema.ExtendedPerson.fields.age).toEqual({ type: "double" });
+    expect(v2Schema.ExtendedEntity.variants.person).toEqual({
+      type: "ref",
+      name: "Person",
+      refType: "record",
+    });
+    expect(v2Schema.ExtendedEntity.variants.organization).toEqual({
+      type: "ref",
+      name: "Organization",
+      refType: "record",
+    });
+
+    assertHasKeys<typeof v2Schema, "Person" | "Entity" | "ExtendedPerson" | "ExtendedEntity">();
+    assertExactKeys<typeof v2Schema.ExtendedPerson.fields, "name" | "age">();
+    assertExactKeys<typeof v2Schema.ExtendedEntity.variants, "person" | "organization">();
+  });
+
+  it("should maintain correct references and names", () => {
+    const v1Schema = {
+      TestRecord: defineRecord("TestRecord", {
+        docs: "Test record",
+        fields: {
+          field1: P.String,
+        },
+      }),
+    };
+
+    const v2Schema = defineMigration(v1Schema, schema => ({
+      ModifiedRecord: schema.TestRecord.addField("field2", P.Double).build(),
+    }));
+
+    expect(v2Schema.ModifiedRecord.name).toBe("TestRecord");
+    expect(v2Schema.ModifiedRecord.type).toBe("record");
+    expect(v2Schema.ModifiedRecord.fields.field1).toEqual({ type: "string" });
+    expect(v2Schema.ModifiedRecord.fields.field2).toEqual({ type: "double" });
+  });
+});

package/src/__tests__/defineRecord.test.ts

@@ -0,0 +1,167 @@
+/*
+ * 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 type { Array, Double, Optional, String } from "../primitives.js";
+import * as P from "../primitives.js";
+import { assertExactKeys, assertTypeEquals } from "./testTypeUtils.js";
+
+describe("defineRecord", () => {
+  it("should create a basic record definition", () => {
+    const PersonRecord = defineRecord("Person", {
+      docs: "A person record",
+      fields: {
+        name: P.String,
+        age: P.Double,
+      },
+    });
+
+    expect(PersonRecord.type).toBe("record");
+    expect(PersonRecord.name).toBe("Person");
+    expect(PersonRecord.docs).toBe("A person record");
+    expect(PersonRecord.fields.name).toEqual({ type: "string" });
+    expect(PersonRecord.fields.age).toEqual({ type: "double" });
+
+    assertExactKeys<typeof PersonRecord.fields, "name" | "age">();
+    assertTypeEquals<typeof PersonRecord.fields.name, String>();
+    assertTypeEquals<typeof PersonRecord.fields.age, Double>();
+  });
+
+  it("should handle optional fields", () => {
+    const UserRecord = defineRecord("User", {
+      docs: "A user record",
+      fields: {
+        username: P.String,
+        email: P.Optional(P.String),
+        age: P.Optional(P.Double),
+      },
+    });
+
+    expect(UserRecord.fields.username).toEqual({ type: "string" });
+    expect(UserRecord.fields.email).toEqual({
+      type: "optional",
+      item: { type: "string" },
+    });
+    expect(UserRecord.fields.age).toEqual({
+      type: "optional",
+      item: { type: "double" },
+    });
+
+    assertExactKeys<typeof UserRecord.fields, "username" | "email" | "age">();
+    assertTypeEquals<typeof UserRecord.fields.username, String>();
+    assertTypeEquals<typeof UserRecord.fields.email, Optional<String>>();
+    assertTypeEquals<typeof UserRecord.fields.age, Optional<Double>>();
+  });
+
+  it("should handle array fields", () => {
+    const TodoListRecord = defineRecord("TodoList", {
+      docs: "A todo list",
+      fields: {
+        title: P.String,
+        items: P.Array(P.String),
+        priorities: P.Array(P.Double),
+      },
+    });
+
+    expect(TodoListRecord.fields.items).toEqual({
+      type: "array",
+      items: { type: "string" },
+    });
+    expect(TodoListRecord.fields.priorities).toEqual({
+      type: "array",
+      items: { type: "double" },
+    });
+
+    assertExactKeys<typeof TodoListRecord.fields, "title" | "items" | "priorities">();
+    assertTypeEquals<typeof TodoListRecord.fields.title, String>();
+    assertTypeEquals<typeof TodoListRecord.fields.items, Array<String>>();
+    assertTypeEquals<typeof TodoListRecord.fields.priorities, Array<Double>>();
+  });
+
+  it("should handle nested optional arrays", () => {
+    const ComplexRecord = defineRecord("Complex", {
+      docs: "A complex record",
+      fields: {
+        optionalStringArray: P.Optional(P.Array(P.String)),
+        arrayOfOptionalStrings: P.Array(P.Optional(P.String)),
+      },
+    });
+
+    expect(ComplexRecord.fields.optionalStringArray).toEqual({
+      type: "optional",
+      item: {
+        type: "array",
+        items: { type: "string" },
+      },
+    });
+    expect(ComplexRecord.fields.arrayOfOptionalStrings).toEqual({
+      type: "array",
+      items: {
+        type: "optional",
+        item: { type: "string" },
+      },
+    });
+
+    assertExactKeys<
+      typeof ComplexRecord.fields,
+      "optionalStringArray" | "arrayOfOptionalStrings"
+    >();
+    assertTypeEquals<
+      typeof ComplexRecord.fields.optionalStringArray,
+      P.Optional<P.Array<P.String>>
+    >();
+    assertTypeEquals<
+      typeof ComplexRecord.fields.arrayOfOptionalStrings,
+      P.Array<P.Optional<P.String>>
+    >();
+  });
+
+  it("should handle record references", () => {
+    const AuthorRecord = defineRecord("Author", {
+      docs: "An author",
+      fields: {
+        name: P.String,
+      },
+    });
+
+    const BookRecord = defineRecord("Book", {
+      docs: "A book",
+      fields: {
+        title: P.String,
+        author: AuthorRecord,
+      },
+    });
+
+    expect(BookRecord.fields.author).toEqual({
+      type: "ref",
+      refType: "record",
+      name: "Author",
+    });
+  });
+
+  it("should support function references for self-referencing structures", () => {
+    const NodeRecord = defineRecord("Node", {
+      docs: "A node in a graph",
+      fields: {
+        value: P.String,
+      },
+    });
+
+    expect(NodeRecord.name).toBe("Node");
+    expect(NodeRecord.fields.value).toEqual({ type: "string" });
+  });
+});