@palantir/pack.schema 0.0.1-beta.1

package/src/defineMigration.ts

@@ -0,0 +1,159 @@
+/*
+ * 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 type { UnionVariantArg } from "./defineUnion.js";
+import { resolveUnionVariantArg } from "./defineUnion.js";
+import type { 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>;
+
+export type Schema<T extends ReturnedSchema> = T;
+
+export type SchemaBuilder<T extends ReturnedSchema> = {
+  [k in keyof T]: T[k] extends UnionDef<infer R> ? UnionBuilder<R>
+    : T[k] extends RecordDef<infer R> ? RecordBuilder<R>
+    : never;
+};
+
+export interface RecordBuilder<T extends Record<string, Type>> {
+  // TODO: builders should support arg types and resolveModels to refs
+  addField<const K extends string, V extends Type>(
+    name: K,
+    type: V,
+  ): RecordBuilder<T & { [k in K]: V }>;
+  build(): RecordDef<T>;
+}
+
+export interface UnionBuilder<S extends UnionVariants> {
+  // TODO: builders should support arg types and resolveModels to refs
+  addVariant<const K extends string>(
+    name: K,
+    modelDefOrRef: UnionVariantArg,
+  ): UnionBuilder<S & { [k in K]: Ref }>;
+  build(): UnionDef<S>;
+}
+
+class UnionBuilderImpl<S extends UnionVariants> implements UnionBuilder<S> {
+  private readonly name: string;
+  private readonly docs: string | undefined;
+  private readonly variants: S;
+  constructor({ name, docs, variants }: UnionDef<S>) {
+    this.name = name;
+    this.docs = docs;
+    this.variants = { ...variants };
+  }
+  addVariant<const K extends string>(
+    variantName: K,
+    modelDefOrRef: UnionVariantArg,
+  ): UnionBuilder<S & Record<K, Ref>> {
+    const ref: Ref = resolveUnionVariantArg(modelDefOrRef);
+    const newVariants = { ...this.variants, [variantName]: ref };
+
+    return new UnionBuilderImpl({
+      type: ModelDefType.UNION,
+      name: this.name,
+      variants: newVariants,
+      discriminant: "type",
+    });
+  }
+  build(): UnionDef<S> {
+    return {
+      type: ModelDefType.UNION,
+      variants: this.variants,
+      discriminant: "type",
+      name: this.name,
+    };
+  }
+}
+
+class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
+  private readonly name: string;
+  private readonly fields: T;
+
+  constructor(initialRecordDef: RecordDef<T>) {
+    this.name = initialRecordDef.name;
+    this.fields = { ...initialRecordDef.fields };
+  }
+
+  // TODO: resolve field value from arg instead
+  addField<const K extends string, const V extends Type>(
+    name: K,
+    value: V,
+  ): RecordBuilder<T & Record<K, V>> {
+    return new RecordBuilderImpl({
+      type: ModelDefType.RECORD,
+      name: this.name,
+      fields: { ...this.fields, [name]: value },
+      docs: "",
+    });
+  }
+  build(): RecordDef<T> {
+    return {
+      type: ModelDefType.RECORD,
+      name: this.name,
+      fields: this.fields,
+      docs: "",
+    };
+  }
+}
+
+export function defineMigration<
+  const T extends ReturnedSchema,
+  const S extends ReturnedSchema,
+>(
+  previous: Schema<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
+   */
+  const builders = {} as SchemaBuilder<T>;
+
+  for (const key in previous) {
+    const v = previous[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,
+    ...migration(builders),
+  };
+}

package/src/defineRecord.ts

@@ -0,0 +1,83 @@
+/*
+ * 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 type { RecordDef, UnionDef } from "./defs.js";
+import { ModelDefType } from "./defs.js";
+import type { Ref, Type } from "./primitives.js";
+import { isRecordDef, isUnionDef, modelToRef } from "./utils.js";
+
+export type FieldArgExplicit =
+  | Type
+  | RecordDef
+  | UnionDef;
+
+export type FieldArg =
+  | FieldArgExplicit
+  | (() => FieldArgExplicit);
+
+export type FieldArgExplicitOf<T extends FieldArg> = T extends () => infer R ? R
+  : T;
+
+export type FieldArgs = Record<string, FieldArg>;
+
+export type ResolvedFieldArgExplicit<T extends FieldArgExplicit> = T extends RecordDef | UnionDef
+  ? Ref
+  : T;
+
+export type ResolvedFieldArg<T extends FieldArg> = ResolvedFieldArgExplicit<FieldArgExplicitOf<T>>;
+
+export type ResolvedFields<T extends FieldArgs> = {
+  readonly [K in keyof T]: ResolvedFieldArg<T[K]>;
+};
+
+export type RecordArgs<T extends FieldArgs> = {
+  readonly docs: string;
+  readonly fields: T;
+};
+
+/**
+ * Helper function to resolve a field value, handling functions and transforming
+ * types as needed.
+ */
+function resolveFieldArg<T extends FieldArg>(value: T): ResolvedFieldArg<T> {
+  // Handle function values
+  const resolved = typeof value === "function" ? value() : value;
+
+  if (isRecordDef(resolved) || isUnionDef(resolved)) {
+    return modelToRef(resolved) as ResolvedFieldArg<T>;
+  }
+
+  // For primitive types and other Types
+  return resolved as ResolvedFieldArg<T>;
+}
+
+export function defineRecord<const T extends FieldArgs>(
+  name: string,
+  record: RecordArgs<T>,
+): RecordDef<ResolvedFields<T>> {
+  const entries = Object.entries(record.fields).map(
+    ([key, value]) => [key, resolveFieldArg(value)] as const,
+  );
+
+  const fields = Object.fromEntries(entries) as ResolvedFields<T>;
+
+  return {
+    type: ModelDefType.RECORD,
+    name: name,
+    docs: record.docs,
+    fields,
+  };
+}

package/src/defineUnion.ts

@@ -0,0 +1,58 @@
+/*
+ * 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 type { ModelDef, UnionDef } from "./defs.js";
+import { ModelDefType } from "./defs.js";
+import type { Ref } from "./primitives.js";
+import { TypeKind } from "./primitives.js";
+import { modelToRef } from "./utils.js";
+
+export type UnionVariantArgExplicit = Ref | ModelDef;
+export type UnionVariantArg = UnionVariantArgExplicit | (() => UnionVariantArgExplicit);
+export type UnionVariantArgs = Record<string, UnionVariantArg>;
+
+export type ResolvedUnionVariants<T extends UnionVariantArgs> = {
+  readonly [K in keyof T]: Ref;
+};
+
+export type UnionArgs<T extends UnionVariantArgs> = {
+  readonly docs: string;
+  readonly variants: T;
+};
+
+export function defineUnion<const TVariants extends UnionVariantArgs>(
+  name: string,
+  union: UnionArgs<TVariants>,
+): UnionDef<ResolvedUnionVariants<TVariants>> {
+  const entries = Object.entries(union.variants).map(
+    ([key, value]) => [key, resolveUnionVariantArg(value)] as const,
+  );
+
+  const variants = Object.fromEntries(entries) as ResolvedUnionVariants<TVariants>;
+
+  return {
+    type: ModelDefType.UNION,
+    discriminant: "type",
+    name: name,
+    docs: union.docs,
+    variants,
+  };
+}
+
+export function resolveUnionVariantArg(arg: UnionVariantArg): Ref {
+  const resolved = typeof arg === "function" ? arg() : arg;
+  return resolved.type === TypeKind.REF ? resolved : modelToRef(resolved);
+}

package/src/defs.ts

@@ -0,0 +1,46 @@
+/*
+ * 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 type { Ref, Type } from "./primitives.js";
+
+export const ModelDefType = {
+  RECORD: "record",
+  UNION: "union",
+} as const;
+
+export type ModelDefType = typeof ModelDefType[keyof typeof ModelDefType];
+
+interface ModelDefBase {
+  readonly type: ModelDefType;
+  readonly name: string;
+  readonly docs?: string;
+}
+
+export type RecordFields = Record<string, Type>;
+export type UnionVariants = Record<string, Ref>;
+
+export interface UnionDef<TVariants extends UnionVariants = UnionVariants> extends ModelDefBase {
+  readonly type: typeof ModelDefType.UNION;
+  readonly variants: TVariants;
+  readonly discriminant: string;
+}
+
+export interface RecordDef<TFields extends RecordFields = RecordFields> extends ModelDefBase {
+  readonly type: typeof ModelDefType.RECORD;
+  readonly fields: TFields;
+}
+
+export type ModelDef = RecordDef | UnionDef;

package/src/index.ts

@@ -0,0 +1,22 @@
+/*
+ * 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.
+ */
+
+export * from "./defineMigration.js";
+export * from "./defineRecord.js";
+export * from "./defineUnion.js";
+export * from "./defs.js";
+export * from "./primitives.js";
+export * from "./utils.js";

package/src/primitives.ts

@@ -0,0 +1,80 @@
+/*
+ * 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.
+ */
+
+export const TypeKind = {
+  ARRAY: "array",
+  DOUBLE: "double",
+  OPTIONAL: "optional",
+  REF: "ref",
+  STRING: "string",
+  UNKNOWN: "unknown",
+} as const;
+
+export type TypeKind = typeof TypeKind[keyof typeof TypeKind];
+
+export type String = {
+  readonly type: typeof TypeKind.STRING;
+};
+
+export type Double = {
+  readonly type: typeof TypeKind.DOUBLE;
+};
+
+// Forward declaration to avoid circular reference
+interface TypeBase {
+  readonly type: TypeKind;
+}
+
+export type Array<T extends TypeBase = TypeBase> = {
+  readonly type: typeof TypeKind.ARRAY;
+  readonly items: T;
+};
+
+// A reference to a record or a union type
+export type Ref = {
+  readonly type: typeof TypeKind.REF;
+  readonly refType: "record" | "union"; // TODO: do we care?
+  readonly name: string;
+};
+
+export type Optional<T extends TypeBase = TypeBase> = {
+  readonly type: typeof TypeKind.OPTIONAL;
+  readonly item: T;
+};
+
+export type Unknown = {
+  readonly type: typeof TypeKind.UNKNOWN;
+};
+
+export type Type =
+  | String
+  | Double
+  | Array
+  | Ref
+  | Optional
+  | Unknown;
+
+export const String: String = { type: TypeKind.STRING };
+export const Double: Double = { type: TypeKind.DOUBLE };
+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,
+});

package/src/utils.ts

@@ -0,0 +1,62 @@
+/*
+ * 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 type { ModelDef, RecordDef, UnionDef } from "./defs.js";
+import { ModelDefType } from "./defs.js";
+import type { Ref } from "./primitives.js";
+import { TypeKind } from "./primitives.js";
+
+/**
+ * Helper function to safely transform a record definition to a reference.
+ * This function helps TypeScript track type transformations better.
+ */
+export function modelToRef(model: ModelDef): Ref {
+  return createRef(model.name, model.type);
+}
+
+/**
+ * Helper function to create a reference with proper typing.
+ * This avoids type assertions in multiple places.
+ */
+export function createRef(name: string, refType: "record" | "union"): Ref {
+  return {
+    type: TypeKind.REF,
+    name,
+    refType,
+  };
+}
+
+/**
+ * Type guard to check if a value is a RecordDef
+ */
+export function isRecordDef(value: unknown): value is RecordDef {
+  return value != null
+    && typeof value === "object"
+    && "type" in value
+    && value.type === ModelDefType.RECORD
+    && "fields" in value;
+}
+
+/**
+ * Type guard to check if a value is a UnionDef
+ */
+export function isUnionDef(value: unknown): value is UnionDef {
+  return value != null
+    && typeof value === "object"
+    && "type" in value
+    && value.type === ModelDefType.UNION
+    && "variants" in value;
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": "@palantir/pack.monorepo.tsconfig/base.json",
+  "compilerOptions": {
+    "outDir": "./build/esm",
+    "rootDir": "./src",
+    "declarationDir": "./build/types",
+    "tsBuildInfoFile": "./build/tsconfig.tsbuildinfo"
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "build",
+    "dist",
+    "node_modules",
+    "test-output",
+    "**/__tests__/**/__snapshots__",
+    "**/__tests__/**/fixtures"
+  ],
+  "references": []
+}

package/vitest.config.mjs

@@ -0,0 +1,26 @@
+import { coverageConfigDefaults, defaultExclude, defineProject } from "vitest/config";
+
+export default defineProject({
+  test: {
+    exclude: [...defaultExclude, "**/build/**", "**/test-output/**"],
+    coverage: {
+      provider: "v8",
+      all: true,
+      enabled: true,
+      pool: "forks",
+      include: ["src/**/*.{ts,tsx}"],
+      exclude: [
+        ...coverageConfigDefaults.exclude,
+        "**/*.test.{ts,tsx}",
+        "**/__tests__",
+        "build",
+        "coverage",
+        "dist",
+        "node_modules",
+        "src/index.ts",
+        "test-output",
+        "vitest.config.*",
+      ],
+    },
+  },
+});