@palantir/pack.schema 0.7.0 → 0.8.0

package/src/defineMigration.ts

@@ -117,9 +117,10 @@ export interface RecordBuilder<T extends Record<string, Type>> {
     type: V,
     options?: FieldOptions,
   ): RecordBuilder<T & { [k in K]: V }>;
-  removeField<K extends keyof T & string>(
+  deprecateField<K extends keyof T & string>(
     name: K,
-  ): RecordBuilder<Omit<T, K>>;
+    message?: string,
+  ): RecordBuilder<T>;
   build(): RecordDef<T>;
 }
 
@@ -174,14 +175,29 @@ class UnionBuilderImpl<S extends UnionVariants> implements UnionBuilder<S> {
  */
 const UPGRADE_OPTIONS_CARRIER = "__pack_upgrade_options__";
 
+/**
+ * Non-enumerable carrier property attached to a `RecordDef` by
+ * `RecordBuilderImpl.build()` when the builder has collected one or more
+ * `deprecateField` calls. `applyMigration` reads this and then deletes the
+ * property, so the returned `RecordDef` is structurally clean. Maps field name
+ * → its deprecation info.
+ */
+const DEPRECATED_FIELDS_CARRIER = "__pack_deprecated_fields__";
+
+export interface FieldDeprecation {
+  readonly message?: string;
+}
+
 class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
   private readonly name: string;
   private readonly fields: T;
   private readonly upgradeOptions: ReadonlyMap<string, FieldOptions>;
+  private readonly deprecatedFields: ReadonlyMap<string, FieldDeprecation>;
 
   constructor(
     initialRecordDef: RecordDef<T>,
     upgradeOptions?: ReadonlyMap<string, FieldOptions>,
+    deprecatedFields?: ReadonlyMap<string, FieldDeprecation>,
   ) {
     this.name = initialRecordDef.name;
     this.fields = { ...initialRecordDef.fields };
@@ -189,6 +205,7 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
     // 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 ?? []);
+    this.deprecatedFields = new Map<string, FieldDeprecation>(deprecatedFields ?? []);
   }
 
   // TODO: resolve field value from arg instead
@@ -212,24 +229,26 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
         docs: "",
       },
       next,
+      this.deprecatedFields,
     );
   }
 
-  removeField<K extends keyof T & string>(
+  deprecateField<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);
+    message?: string,
+  ): RecordBuilder<T> {
+    const next = new Map(this.deprecatedFields);
+    next.set(name, { message });
     return new RecordBuilderImpl(
       {
         type: ModelDefType.RECORD,
         name: this.name,
-        fields: rest as RecordFields,
+        fields: { ...this.fields },
         docs: "",
       },
+      this.upgradeOptions,
       next,
-    ) as unknown as RecordBuilder<Omit<T, K>>;
+    );
   }
 
   build(): RecordDef<T> {
@@ -247,6 +266,14 @@ class RecordBuilderImpl<T extends RecordFields> implements RecordBuilder<T> {
         writable: false,
       });
     }
+    if (this.deprecatedFields.size > 0) {
+      Object.defineProperty(result, DEPRECATED_FIELDS_CARRIER, {
+        value: this.deprecatedFields,
+        enumerable: false,
+        configurable: true,
+        writable: false,
+      });
+    }
     return result;
   }
 }
@@ -270,22 +297,29 @@ export type FieldUpgrades = Record<
   Record<string, UpgradeFieldOptions<Record<string, unknown>>>
 >;
 
+export type FieldDeprecations = Record<
+  string,
+  Record<string, FieldDeprecation>
+>;
+
 export interface MigrationResult<M extends ModelDefs> {
   readonly models: M;
   readonly upgrades?: FieldUpgrades;
+  readonly deprecations?: FieldDeprecations;
 }
 
 /**
- * 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.
+ * Lower-level entry point that returns the merged models plus the per-field
+ * metadata collected during the migration callback: `UpgradeFieldOptions` from
+ * `addField(name, type, options)` and deprecations from `deprecateField(name)`.
+ * Used by `addSchemaUpdate` to fold sugar-form upgrades into a
+ * `VersionedSchema`'s migrations map and deprecations into its deprecations 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.
+ * Each `RecordBuilderImpl.build()` attaches its collected upgrade options and
+ * deprecations to the produced `RecordDef` via two non-enumerable carrier
+ * properties; this function walks the merged result, extracts both keyed by the
+ * user's chosen output key (so renames are handled), and strips the carriers so
+ * the returned `RecordDef`s are structurally clean.
  */
 export function applyMigration<
   const T extends ModelDefs,
@@ -298,35 +332,53 @@ export function applyMigration<
   const merged = { ...models, ...migration(builders) } as T & S;
 
   const upgrades: FieldUpgrades = {};
+  const deprecations: FieldDeprecations = {};
   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 (opts != null) {
+      // 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;
       }
     }
-    if (Object.keys(fieldEntries).length > 0) {
-      upgrades[modelKey] = fieldEntries;
+
+    const deprecated = carrier[DEPRECATED_FIELDS_CARRIER] as
+      | ReadonlyMap<string, FieldDeprecation>
+      | undefined;
+    if (deprecated != null) {
+      // Strip the carrier so the returned RecordDef is structurally clean.
+      delete carrier[DEPRECATED_FIELDS_CARRIER];
+      const fieldEntries: Record<string, FieldDeprecation> = {};
+      for (const [fieldName, info] of deprecated) {
+        fieldEntries[fieldName] = info;
+      }
+      if (Object.keys(fieldEntries).length > 0) {
+        deprecations[modelKey] = fieldEntries;
+      }
     }
   }
 
   return {
     models: merged,
     upgrades: Object.keys(upgrades).length > 0 ? upgrades : undefined,
+    deprecations: Object.keys(deprecations).length > 0 ? deprecations : undefined,
   };
 }
 

package/src/defineSchemaUpdate.ts

@@ -14,9 +14,10 @@
  * limitations under the License.
  */
 
-import type { SchemaBuilder } from "./defineMigration.js";
+import type { FieldDeprecation, SchemaBuilder } from "./defineMigration.js";
 import { applyMigration } from "./defineMigration.js";
 import type { ModelDefs } from "./defs.js";
+import { isRecordDef } from "./utils.js";
 
 export interface InitialSchema<T extends ModelDefs = ModelDefs> {
   readonly type: "initial";
@@ -30,12 +31,19 @@ export interface FieldMigration {
 
 export type VersionMigrations = Record<string, Record<string, FieldMigration>>;
 
+export interface FieldDeprecationInfo {
+  readonly fromVersion: number;
+  readonly message?: string;
+}
+export type VersionDeprecations = Record<string, Record<string, FieldDeprecationInfo>>;
+
 export interface VersionedSchema<T extends ModelDefs = ModelDefs> {
   readonly type: "versioned";
   readonly models: T;
   readonly version: number;
   readonly previous: SchemaDefinition;
   readonly migrations?: VersionMigrations;
+  readonly deprecations?: VersionDeprecations;
 }
 
 export type SchemaDefinition<T extends ModelDefs = ModelDefs> =
@@ -67,18 +75,18 @@ export interface SchemaVersionBuilder<T extends ModelDefs> {
 }
 
 /**
- * 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.
+ * Shallow-merge two `[modelKey][fieldName]` maps; `override` wins per field.
+ * Used for both migrations (so `withMigrations` supplements `addField` sugar)
+ * and deprecations (so each version's deprecations accumulate forward). The
+ * maps are combined at both the model and field level.
  */
-function mergeMigrations(
-  base: VersionMigrations | undefined,
-  override: VersionMigrations | undefined,
-): VersionMigrations | undefined {
+function mergeByModelField<V>(
+  base: Record<string, Record<string, V>> | undefined,
+  override: Record<string, Record<string, V>> | undefined,
+): Record<string, Record<string, V>> | undefined {
   if (base == null) return override;
   if (override == null) return base;
-  const result: VersionMigrations = { ...base };
+  const result: Record<string, Record<string, V>> = { ...base };
   for (const [modelKey, fields] of Object.entries(override)) {
     result[modelKey] = { ...result[modelKey], ...fields };
   }
@@ -87,7 +95,7 @@ function mergeMigrations(
 
 /**
  * Drop migration entries that no longer correspond to a field on a record in
- * `models`. Required because `mergeMigrations` is monotonic — a later
+ * `models`. Required because `mergeByModelField` 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,
@@ -102,7 +110,7 @@ function pruneMigrations(
   const result: VersionMigrations = {};
   for (const [modelKey, fields] of Object.entries(migrations)) {
     const def = models[modelKey];
-    if (def == null || def.type !== "record") continue;
+    if (!isRecordDef(def)) continue;
     const recordFields = def.fields;
     const kept: Record<string, FieldMigration> = {};
     for (const [fieldName, migration] of Object.entries(fields)) {
@@ -117,44 +125,82 @@ function pruneMigrations(
   return Object.keys(result).length > 0 ? result : undefined;
 }
 
+/**
+ * Convert the version-agnostic `FieldDeprecations` collected by `applyMigration`
+ * (just `{ message? }`) into `VersionDeprecations` by stamping `fromVersion`.
+ */
+function stampDeprecationVersions(
+  deprecations: Record<string, Record<string, FieldDeprecation>> | undefined,
+  version: number,
+): VersionDeprecations | undefined {
+  if (deprecations == null) return undefined;
+  const result: VersionDeprecations = {};
+  for (const [modelKey, fields] of Object.entries(deprecations)) {
+    const out: Record<string, FieldDeprecationInfo> = {};
+    for (const [fieldName, info] of Object.entries(fields)) {
+      out[fieldName] = { fromVersion: version, ...info };
+    }
+    result[modelKey] = out;
+  }
+  return result;
+}
+
 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;
+  private readonly _deprecations: VersionDeprecations | undefined;
 
   constructor(
     models: T,
     version: number,
     previous: SchemaDefinition,
-    migrations?: VersionMigrations,
+    migrations: VersionMigrations | undefined,
+    deprecations?: VersionDeprecations,
   ) {
     this.models = models;
     this.version = version;
     this.previous = previous;
     this._migrations = migrations;
+    this._deprecations = deprecations;
   }
 
   addSchemaUpdate<S extends ModelDefs>(
     update: SchemaUpdate<T, S>,
   ): SchemaVersionBuilder<T & S> {
-    // 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(
+    // applyMigration returns the merged models, any sugar-form upgrades from
+    // `addField(name, type, { derivedFrom })`, and any `deprecateField` calls.
+    const { models, upgrades, deprecations } = applyMigration(this.models, update.migration);
+    const merged = mergeByModelField(
       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.
+    // Reconcile against the new models: a later update that 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);
+    // Attach this version to each freshly-deprecated field, then merge forward.
+    const thisVersionDeprecations = stampDeprecationVersions(deprecations, this.version);
+    const mergedDeprecations = mergeByModelField(this._deprecations, thisVersionDeprecations);
+    return new SchemaVersionBuilderImpl(
+      models,
+      this.version,
+      this.previous,
+      pruned,
+      mergedDeprecations,
+    );
   }
 
   withMigrations(migrations: VersionMigrations): SchemaVersionBuilder<T> {
-    const merged = mergeMigrations(this._migrations, migrations);
+    const merged = mergeByModelField(this._migrations, migrations);
     const pruned = pruneMigrations(merged, this.models);
-    return new SchemaVersionBuilderImpl(this.models, this.version, this.previous, pruned);
+    return new SchemaVersionBuilderImpl(
+      this.models,
+      this.version,
+      this.previous,
+      pruned,
+      this._deprecations,
+    );
   }
 
   build(): VersionedSchema<T> {
@@ -164,6 +210,7 @@ class SchemaVersionBuilderImpl<T extends ModelDefs> implements SchemaVersionBuil
       version: this.version,
       previous: this.previous,
       ...(this._migrations != null ? { migrations: this._migrations } : {}),
+      ...(this._deprecations != null ? { deprecations: this._deprecations } : {}),
     };
   }
 }
@@ -171,5 +218,13 @@ class SchemaVersionBuilderImpl<T extends ModelDefs> implements SchemaVersionBuil
 export function nextSchema<T extends ModelDefs>(
   previous: SchemaDefinition<T>,
 ): SchemaVersionBuilder<T> {
-  return new SchemaVersionBuilderImpl(previous.models, previous.version + 1, previous);
+  const version = previous.version + 1;
+  const deprecations = "deprecations" in previous ? previous.deprecations : undefined;
+  return new SchemaVersionBuilderImpl(
+    previous.models,
+    version,
+    previous,
+    undefined,
+    deprecations,
+  );
 }