@palantir/pack.document-schema.model-types 0.11.0 → 0.13.0

package/src/types/Model.ts

@@ -52,6 +52,7 @@ export type ModelData<M extends Model> = M["__type"];
 export interface EditDescription<M extends Model = Model> {
   readonly data: ModelData<M>;
   readonly model: M;
+  readonly schemaVersion?: number;
 }
 
 export const ExternalRefType = {

package/src/types/PresenceEvent.ts

@@ -64,6 +64,7 @@ export interface PresenceEventDataCustom<M extends Model = Model> {
   readonly type: typeof PresenceEventDataType.CUSTOM_EVENT;
   readonly eventData: ModelData<M>;
   readonly model: M;
+  readonly schemaVersion?: number;
 }
 
 /**

package/src/types/RecordCollectionRef.ts

@@ -15,7 +15,7 @@
  */
 
 import type { DocumentRef } from "./DocumentRef.js";
-import type { Model, ModelData } from "./Model.js";
+import type { Model } from "./Model.js";
 import type { RecordId, RecordRef } from "./RecordRef.js";
 
 export const RecordCollectionRefBrand: unique symbol = Symbol(
@@ -33,6 +33,9 @@ export interface RecordCollectionRef<M extends Model = Model> {
   /**
    * Delete a record from the collection (and the document).
    *
+   * Version-agnostic: deletion needs only the record's identity, not its
+   * payload shape, so this is safe to call without narrowing to a version.
+   *
    * @param id - The ID of the record to delete.
    * @returns A promise that resolves when the record is deleted.
    */
@@ -53,20 +56,6 @@ export interface RecordCollectionRef<M extends Model = Model> {
    * @returns True if the record exists, false otherwise.
    */
   has(id: RecordId): boolean;
-  /**
-   * Set the data for a record in the collection (creating it if it doesn't exist).
-   *
-   * @param id - The ID of the record to set.
-   * @param state - The data to set for the record.
-   * @returns A promise that resolves when the record is set.
-   *
-   * @example
-   * ```ts
-   * const recordCollection = docRef.getRecords(MyModel);
-   * await recordCollection.set("record-id", { field: "value" });
-   * ```
-   */
-  set(id: RecordId, state: ModelData<M>): Promise<void>;
   readonly size: number;
 
   [Symbol.iterator](): Iterator<RecordRef<M>>;

package/src/types/RecordRef.ts

@@ -39,9 +39,10 @@ export const RecordRefBrand: unique symbol = Symbol("pack:RecordRef");
  *
  * const docRef = app.getDocRef<DocumentSchema>(someDocumentId);
  *
- * const recordRef = docRef.getRecords(MyModel).set("my-record-id", { myFieldName: "some value", foo: 42 });
+ * // Create a record via the version-narrowed setRecord on DocumentRef.
+ * await docRef.setRecord(MyModel, "my-record-id", { myFieldName: "some value", foo: 42 });
  *
- * // Or get a specific record.
+ * // Then get the ref back.
  * const recordRef = docRef.getRecords(MyModel).get("my-record-id");
  */
 export interface RecordRef<M extends Model = Model> {
@@ -69,8 +70,8 @@ export interface RecordRef<M extends Model = Model> {
    *   console.log("Record changed:", newSnapshot);
    * });
    *
-   * // Submit a change
-   * recordRef.set({ myFieldName: "new value" });
+   * // Submit a change via the version-narrowed updateRecord on DocumentRef.
+   * await docRef.updateRecord(recordRef, { myFieldName: "new value" });
    * ```
    */
   onChange(callback: (snapshot: ModelData<M>, recordRef: RecordRef<M>) => void): Unsubscribe;
@@ -96,6 +97,9 @@ export interface RecordRef<M extends Model = Model> {
   /**
    * Delete the record from the document.
    *
+   * Version-agnostic: deletion needs only the record's identity, not its
+   * payload shape, so this is safe to call without narrowing to a version.
+   *
    * @returns An ignorable promise that resolves when the record is deleted.
    *
    * @example
@@ -104,34 +108,4 @@ export interface RecordRef<M extends Model = Model> {
    * ```
    */
   delete(): Promise<void>;
-
-  /**
-   * Set the data for the record (creating it if it doesn't exist).
-   *
-   * @see {onChange} to subscribe to changes to the record.
-   *
-   * @param record - The plain object data to set for the record, corresponding to the model's schema.
-   * @returns An ignorable promise that resolves when the record is published.
-   *
-   * @example
-   * ```ts
-   * await recordRef.set({ field: "value" });
-   * ```
-   */
-  set(record: ModelData<M>): Promise<void>;
-
-  /**
-   * Update specific fields of the record.
-   *
-   * @see {onChange} to subscribe to changes to the record.
-   *
-   * @param partialRecord - A partial plain object with the fields to update.
-   * @returns An ignorable promise that resolves when the record is published.
-   *
-   * @example
-   * ```ts
-   * await recordRef.update({ field: "new value" });
-   * ```
-   */
-  update(record: Partial<ModelData<M>>): Promise<void>;
 }

package/src/types/UpgradeLens.ts

@@ -14,8 +14,6 @@
  * limitations under the License.
  */
 
-import type { JsonValue } from "./JsonValue.js";
-
 /** Type descriptor for a field, enabling recursive lens application. */
 export type FieldTypeDescriptor =
   | { kind: "primitive" }
@@ -26,17 +24,17 @@ export type FieldTypeDescriptor =
 
 export interface FieldLensDef {
   /**
-   * Source field names. When empty, the field is additive — only `default` applies and no
-   * forward function is invoked.
+   * Source field names. When empty, the field is additive — the upgrade fn
+   * receives `{}` and returns a value of the field's type. Either way, the
+   * runtime looks up an entry in `UpgradeFns` at this `(modelName, version,
+   * fieldName)` and calls it.
    */
   derivedFrom: string[];
-  /** Literal JSON only — validated at schema build time. Used when no source data exists. */
-  default?: JsonValue;
 }
 
 export interface FieldDef {
   type: FieldTypeDescriptor;
-  default?: unknown;
+  addedInVersion?: number;
 }
 
 export interface UpgradeStepDef {

package/src/utils/ActivityEvents.ts

@@ -20,7 +20,7 @@ import type {
   ActivityEventDataUnknown,
 } from "../types/ActivityEvent.js";
 import { ActivityEventDataType } from "../types/ActivityEvent.js";
-import type { EditDescription, Model, ModelData } from "../types/Model.js";
+import type { EditDescription, Model } from "../types/Model.js";
 
 /**
  * Creates an edit description to describe an edit for activity purposes, for use with docRef.withTransaction.
@@ -39,7 +39,11 @@ import type { EditDescription, Model, ModelData } from "../types/Model.js";
  * }));
  * ```
  */
-export function describeEdit<M extends Model>(model: M, data: ModelData<M>): EditDescription<M> {
+/**
+ * @deprecated Narrow the document ref by version and use
+ * `doc.describeEdit(model, data)` instead.
+ */
+export function describeEdit<M extends Model>(model: M, data: never): EditDescription<M> {
   return {
     data,
     model,

package/build/types/types/JsonValue.d.ts

@@ -1,8 +0,0 @@
-/**
-* Any value losslessly representable as JSON. Used to constrain literal defaults
-* declared in the schema/IR — anything not expressible as JSON (functions,
-* `Date`, `RegExp`, class instances, `undefined`) is rejected at the type level.
-*/
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
-	[key: string]: JsonValue;
-};

package/build/types/types/JsonValue.d.ts.map

@@ -1 +0,0 @@
-{"mappings":";;;;;AAqBA,YAAY,+CAKR,cACA;gBAAiB","names":[],"sources":["../../../src/types/JsonValue.ts"],"version":3,"file":"JsonValue.d.ts"}

package/src/types/JsonValue.ts

@@ -1,28 +0,0 @@
-/*
- * Copyright 2026 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.
- */
-
-/**
- * Any value losslessly representable as JSON. Used to constrain literal defaults
- * declared in the schema/IR — anything not expressible as JSON (functions,
- * `Date`, `RegExp`, class instances, `undefined`) is rejected at the type level.
- */
-export type JsonValue =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonValue[]
-  | { [key: string]: JsonValue };