@palantir/pack.schema 0.5.0 → 0.7.0

package/src/defineMigration.ts

@@ -33,12 +33,93 @@ export type SchemaBuilder<T extends ModelDefs> = {
     : never;
 };
 
+/**
+ * Recursive literal-JSON type. Constrains schema-time `default` values to
+ * data that JSON-serializes losslessly — no `Date`, `RegExp`, functions, class
+ * instances, or `undefined`. Mirrors the `JsonValue` exported by
+ * `@palantir/pack.document-schema.model-types`; kept local here to avoid a
+ * package dependency from `pack.schema`.
+ */
+type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * Upgrade options for a field whose value is derived from prior-version fields.
+ * Supplied as the third argument to `addField`; surfaced by `applyMigration`
+ * as part of `MigrationResult.upgrades`. Declares the structural dependency
+ * (`derivedFrom`) and an optional literal JSON `default` used when no source
+ * data exists. The runtime forward function is supplied separately via the
+ * generated `DocumentModel(...)` factory's `UpgradeFns` parameter.
+ */
+export interface UpgradeFieldOptions<TOld extends Record<string, unknown>> {
+  readonly derivedFrom: ReadonlyArray<keyof TOld & string>;
+  readonly default?: JsonValue;
+}
+
+/**
+ * Options for a purely additive field. `default` is literal JSON only;
+ * validated at `addField()` call time.
+ */
+export interface AdditiveFieldOptions {
+  readonly default?: JsonValue;
+}
+
+export type FieldOptions =
+  | UpgradeFieldOptions<Record<string, unknown>>
+  | AdditiveFieldOptions;
+
+/**
+ * Recursively assert `value` is representable as literal JSON. Rejects `Date`,
+ * `RegExp`, functions, class instances, symbol-keyed properties, `undefined`
+ * (anywhere — top-level or nested), `symbol`, and `bigint`. Throws on the
+ * first offending value, naming the path for debuggability.
+ */
+function assertJsonDefault(value: unknown, path: string): void {
+  // eslint-disable-next-line eqeqeq -- need to distinguish null (valid JSON) from undefined (not).
+  if (value === null) return;
+  const t = typeof value;
+  if (t === "undefined") {
+    throw new Error(`Invalid JSON default at ${path}: undefined is not valid JSON`);
+  }
+  if (t === "string" || t === "number" || t === "boolean") return;
+  if (t === "function" || t === "symbol" || t === "bigint") {
+    throw new Error(`Invalid JSON default at ${path}: ${t} is not valid JSON`);
+  }
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      assertJsonDefault(value[i], `${path}[${i}]`);
+    }
+    return;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto != null) {
+    const ctorName = (value as { constructor?: { name?: string } }).constructor?.name
+      ?? "non-plain object";
+    throw new Error(`Invalid JSON default at ${path}: ${ctorName} is not valid JSON`);
+  }
+  if (Object.getOwnPropertySymbols(value as object).length > 0) {
+    throw new Error(`Invalid JSON default at ${path}: symbol-keyed properties are not valid JSON`);
+  }
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    assertJsonDefault(v, `${path}.${k}`);
+  }
+}
+
 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,
+    options?: FieldOptions,
   ): RecordBuilder<T & { [k in K]: V }>;
+  removeField<K extends keyof T & string>(
+    name: K,
+  ): RecordBuilder<Omit<T, K>>;
   build(): RecordDef<T>;
 }
 
@@ -84,60 +165,177 @@ class UnionBuilderImpl<S extends UnionVariants> implements UnionBuilder<S> {
   }
 }
 
+/**
+ * Non-enumerable carrier property attached to a `RecordDef` by
+ * `RecordBuilderImpl.build()` when the builder has collected one or more
+ * `FieldOptions`. `applyMigration` reads this and then deletes the property,
+ * so the `RecordDef` it returns is structurally clean (no extra keys, no
+ * symbol-keyed metadata).
+ */
+const UPGRADE_OPTIONS_CARRIER = "__pack_upgrade_options__";
+
 class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
   private readonly name: string;
   private readonly fields: T;
+  private readonly upgradeOptions: ReadonlyMap<string, FieldOptions>;
 
-  constructor(initialRecordDef: RecordDef<T>) {
+  constructor(
+    initialRecordDef: RecordDef<T>,
+    upgradeOptions?: ReadonlyMap<string, FieldOptions>,
+  ) {
     this.name = initialRecordDef.name;
     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
+    // version's upgrades describe a specific version transition.
+    this.upgradeOptions = new Map<string, FieldOptions>(upgradeOptions ?? []);
   }
 
   // TODO: resolve field value from arg instead
   addField<const K extends string, const V extends Type>(
     name: K,
     value: V,
+    options?: FieldOptions,
   ): RecordBuilder<T & Record<K, V>> {
-    return new RecordBuilderImpl({
-      type: ModelDefType.RECORD,
-      name: this.name,
-      fields: { ...this.fields, [name]: value },
-      docs: "",
-    });
+    if (options != null && "default" in options && options.default !== undefined) {
+      assertJsonDefault(options.default, `addField("${name}").default`);
+    }
+    const next = new Map(this.upgradeOptions);
+    if (options != null) {
+      next.set(name, options);
+    }
+    return new RecordBuilderImpl(
+      {
+        type: ModelDefType.RECORD,
+        name: this.name,
+        fields: { ...this.fields, [name]: value },
+        docs: "",
+      },
+      next,
+    );
+  }
+
+  removeField<K extends keyof T & string>(
+    name: K,
+  ): RecordBuilder<Omit<T, K>> {
+    const { [name]: _removed, ...rest } = this.fields;
+    const next = new Map(this.upgradeOptions);
+    next.delete(name);
+    return new RecordBuilderImpl(
+      {
+        type: ModelDefType.RECORD,
+        name: this.name,
+        fields: rest as RecordFields,
+        docs: "",
+      },
+      next,
+    ) as unknown as RecordBuilder<Omit<T, K>>;
   }
+
   build(): RecordDef<T> {
-    return {
+    const result: RecordDef<T> = {
       type: ModelDefType.RECORD,
       name: this.name,
       fields: this.fields,
       docs: "",
     };
+    if (this.upgradeOptions.size > 0) {
+      Object.defineProperty(result, UPGRADE_OPTIONS_CARRIER, {
+        value: this.upgradeOptions,
+        enumerable: false,
+        configurable: true,
+        writable: false,
+      });
+    }
+    return result;
   }
 }
 
-export function defineMigration<
+function makeBuilders<T extends ModelDefs>(models: T): SchemaBuilder<T> {
+  const builders = {} as SchemaBuilder<T>;
+  for (const key in models) {
+    const v = models[key];
+    if (isRecordDef(v)) {
+      builders[key] = new RecordBuilderImpl(v) as unknown as SchemaBuilder<T>[typeof key];
+    } else if (isUnionDef(v)) {
+      builders[key] = new UnionBuilderImpl(v) as unknown as SchemaBuilder<T>[typeof key];
+    }
+  }
+  return builders;
+}
+
+/** Per-model field migrations: `[modelKey][fieldName]` → upgrade options. */
+export type FieldUpgrades = Record<
+  string,
+  Record<string, UpgradeFieldOptions<Record<string, unknown>>>
+>;
+
+export interface MigrationResult<M extends ModelDefs> {
+  readonly models: M;
+  readonly upgrades?: FieldUpgrades;
+}
+
+/**
+ * Lower-level entry point that returns both the merged models AND any
+ * `UpgradeFieldOptions` collected via `addField(name, type, options)` during
+ * the migration callback. Used by `addSchemaUpdate` to fold sugar-form
+ * upgrades into a `VersionedSchema`'s migrations map.
+ *
+ * Each `RecordBuilderImpl.build()` attaches its collected options to the
+ * produced `RecordDef` via a non-enumerable carrier property; this function
+ * walks the merged result, extracts the options keyed by the user's chosen
+ * output key (so renames are handled), and strips the carrier so the returned
+ * `RecordDef`s are structurally clean.
+ */
+export function applyMigration<
   const T extends ModelDefs,
   const S extends ModelDefs,
 >(
   models: T,
   migration: (schema: SchemaBuilder<T>) => S,
-): T & S {
-  const builders = {} as SchemaBuilder<T>;
-
-  for (const key in models) {
-    const v = models[key];
+): MigrationResult<T & S> {
+  const builders = makeBuilders(models);
+  const merged = { ...models, ...migration(builders) } as T & S;
 
-    if (isRecordDef(v)) {
-      const recordBuilder = new RecordBuilderImpl(v);
-      builders[key] = recordBuilder as unknown as SchemaBuilder<T>[typeof key];
-    } else if (isUnionDef(v)) {
-      const unionBuilder = new UnionBuilderImpl(v);
-      builders[key] = unionBuilder as unknown as SchemaBuilder<T>[typeof key];
+  const upgrades: FieldUpgrades = {};
+  for (const [modelKey, def] of Object.entries(merged)) {
+    if (!isRecordDef(def)) continue;
+    const carrier = def as unknown as Record<string, unknown>;
+    const opts = carrier[UPGRADE_OPTIONS_CARRIER] as
+      | ReadonlyMap<string, FieldOptions>
+      | undefined;
+    if (opts == null) continue;
+    // Strip the carrier so the returned RecordDef is structurally clean.
+    delete carrier[UPGRADE_OPTIONS_CARRIER];
+    const fieldEntries: Record<
+      string,
+      UpgradeFieldOptions<Record<string, unknown>>
+    > = {};
+    for (const [fieldName, options] of opts) {
+      // Only `UpgradeFieldOptions` (which declare `derivedFrom`) flow into the
+      // upgrades map; `AdditiveFieldOptions` carry only a literal `default`
+      // and have no read-time lens effect.
+      if ("derivedFrom" in options) {
+        fieldEntries[fieldName] = options;
+      }
+    }
+    if (Object.keys(fieldEntries).length > 0) {
+      upgrades[modelKey] = fieldEntries;
     }
   }
 
   return {
-    ...models,
-    ...migration(builders),
+    models: merged,
+    upgrades: Object.keys(upgrades).length > 0 ? upgrades : undefined,
   };
 }
+
+export function defineMigration<
+  const T extends ModelDefs,
+  const S extends ModelDefs,
+>(
+  models: T,
+  migration: (schema: SchemaBuilder<T>) => S,
+): T & S {
+  return applyMigration(models, migration).models;
+}

package/src/defineSchemaUpdate.ts

@@ -15,7 +15,7 @@
  */
 
 import type { SchemaBuilder } from "./defineMigration.js";
-import { defineMigration } from "./defineMigration.js";
+import { applyMigration } from "./defineMigration.js";
 import type { ModelDefs } from "./defs.js";
 
 export interface InitialSchema<T extends ModelDefs = ModelDefs> {
@@ -26,7 +26,6 @@ export interface InitialSchema<T extends ModelDefs = ModelDefs> {
 
 export interface FieldMigration {
   readonly derivedFrom: readonly string[];
-  readonly forward: (oldFields: Record<string, unknown>) => unknown;
 }
 
 export type VersionMigrations = Record<string, Record<string, FieldMigration>>;
@@ -67,6 +66,57 @@ export interface SchemaVersionBuilder<T extends ModelDefs> {
   build(): VersionedSchema<T>;
 }
 
+/**
+ * Merge two `VersionMigrations` records. Per-model field migrations from
+ * `override` take precedence over `base` for the same field, but the maps are
+ * combined at both the model and field level so explicit `withMigrations`
+ * calls can supplement (not just replace) the sugar from `addField` options.
+ */
+function mergeMigrations(
+  base: VersionMigrations | undefined,
+  override: VersionMigrations | undefined,
+): VersionMigrations | undefined {
+  if (base == null) return override;
+  if (override == null) return base;
+  const result: VersionMigrations = { ...base };
+  for (const [modelKey, fields] of Object.entries(override)) {
+    result[modelKey] = { ...result[modelKey], ...fields };
+  }
+  return result;
+}
+
+/**
+ * Drop migration entries that no longer correspond to a field on a record in
+ * `models`. Required because `mergeMigrations` is monotonic — a later
+ * `addSchemaUpdate` that removes or retypes a field would otherwise leave a
+ * stale entry in the accumulator. Entries are dropped when:
+ *   - the model key is no longer present,
+ *   - the model is no longer a record (e.g. replaced by a union), or
+ *   - the field name is no longer one of the record's fields.
+ */
+function pruneMigrations(
+  migrations: VersionMigrations | undefined,
+  models: ModelDefs,
+): VersionMigrations | undefined {
+  if (migrations == null) return undefined;
+  const result: VersionMigrations = {};
+  for (const [modelKey, fields] of Object.entries(migrations)) {
+    const def = models[modelKey];
+    if (def == null || def.type !== "record") continue;
+    const recordFields = def.fields;
+    const kept: Record<string, FieldMigration> = {};
+    for (const [fieldName, migration] of Object.entries(fields)) {
+      if (fieldName in recordFields) {
+        kept[fieldName] = migration;
+      }
+    }
+    if (Object.keys(kept).length > 0) {
+      result[modelKey] = kept;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
 class SchemaVersionBuilderImpl<T extends ModelDefs> implements SchemaVersionBuilder<T> {
   private readonly models: T;
   private readonly version: number;
@@ -88,12 +138,23 @@ class SchemaVersionBuilderImpl<T extends ModelDefs> implements SchemaVersionBuil
   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);
+    // applyMigration returns both the merged models and any sugar-form
+    // upgrades collected via `addField(name, type, { derivedFrom, forward })`.
+    const { models, upgrades } = applyMigration(this.models, update.migration);
+    const merged = mergeMigrations(
+      this._migrations,
+      upgrades as VersionMigrations | undefined,
+    );
+    // Reconcile against the new models: a later update that removes or
+    // retypes a field must drop the prior step's stale migration entry.
+    const pruned = pruneMigrations(merged, models);
+    return new SchemaVersionBuilderImpl(models, this.version, this.previous, pruned);
   }
 
   withMigrations(migrations: VersionMigrations): SchemaVersionBuilder<T> {
-    return new SchemaVersionBuilderImpl(this.models, this.version, this.previous, migrations);
+    const merged = mergeMigrations(this._migrations, migrations);
+    const pruned = pruneMigrations(merged, this.models);
+    return new SchemaVersionBuilderImpl(this.models, this.version, this.previous, pruned);
   }
 
   build(): VersionedSchema<T> {