@palantir/pack.document-schema.model-types 0.1.0 → 0.2.0

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

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cAAc,OAAO,iBAAiB;AACtC,cAAc,cAAc;AAE5B,YAAY,kBAAkB,SAAS;AAEvC,OAAO,cAAM;UACX,cAAc;UACd,SAAS;;AAGX,iBAAiB,wBAAwB,UAAU,QAAQ,OAAO;UACvD,aAAa,sBAAsB;UACnC,OAAO;UACP,WAAW,UAAU;;AAKhC,iBAAiB,yBAAyB;UAC/B,MAAM;UACN;UACA;;AAGX,YAAY,oBAAoB,0BAA0B;AAE1D,iBAAiB,cAAc;UACpB;UACA,WAAW;UACX;UACA,WAAW;UACX,SAAS;UACT","names":[],"sources":["../../../src/types/ActivityEvent.ts"],"version":3,"file":"ActivityEvent.d.ts"}
+{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cAAc,OAAO,iBAAiB;AACtC,cAAc,cAAc;AAE5B,YAAY,kBAAkB,SAAS;AAEvC,OAAO,cAAM;UACX,cAAc;UACd,SAAS;;;;;;;;;;;;;;;;;;;;;;;AAwBX,iBAAiB,wBAAwB,UAAU,QAAQ,OAAO;UACvD,aAAa,sBAAsB;UACnC,OAAO;UACP,WAAW,UAAU;;;;;;;;;;AAahC,iBAAiB,yBAAyB;UAC/B,MAAM;UACN;UACA;;AAGX,YAAY,oBAAoB,0BAA0B;;;;;;;;AAS1D,iBAAiB,cAAc;;UAEpB;UACA,WAAW;UACX;UACA,WAAW;UACX,SAAS;UACT","names":[],"sources":["../../../src/types/ActivityEvent.ts"],"version":3,"file":"ActivityEvent.d.ts"}

package/build/types/types/DocumentRef.d.ts

@@ -7,20 +7,205 @@ import type { PresenceEvent } from "./PresenceEvent.js";
 import type { RecordCollectionRef } from "./RecordCollectionRef.js";
 import type { Unsubscribe } from "./Unsubscribe.js";
 export type DocumentId = Flavored<"DocumentId">;
+/**
+* Options for subscribing to presence events on a document.
+*/
 export interface PresenceSubscriptionOptions {
+	/**
+	* If true, presence events originating from the local user will be ignored.
+	*
+	* @default true
+	*/
 	readonly ignoreSelfUpdates?: boolean;
 }
 export declare const DocumentRefBrand: unique symbol;
+/**
+* A reference to a document in the Pack system.
+*
+* A documentRef returned by various interfaces from the pack app instance or
+* utilities such as react hooks from @palantir/pack.state.react provides
+* methods to interact with the document, such as subscribing to & making
+* changes to the document state and also related activity or presence events.
+*
+* A stable documentRef object is guaranteed for the same document id within the
+* same app instance.
+*/
 export interface DocumentRef<D extends DocumentSchema = DocumentSchema> {
 	readonly id: DocumentId;
 	readonly schema: D;
 	readonly [DocumentRefBrand]: typeof DocumentRefBrand;
+	/**
+	* Get a snapshot of the current document state.
+	*
+	* This is largely for debugging and dumps a json view of the whole document state.
+	*
+	* @experimental
+	*/
 	getDocSnapshot(): Promise<DocumentState<D>>;
+	/**
+	* Get or create a ref to the collection of all records for the specified
+	* model in this document.
+	*
+	* @param model The model type from the application's generated schema.
+	* @returns A stable {@link RecordCollectionRef} object providing an interface
+	* to interact with the records of the specified model type in this document.
+	*
+	* @example
+	* ```ts
+	* import { DocumentModel, MyModel } from "@myapp/schema";
+	* import { app } from "./appInstance";
+	*
+	* const docRef = app.state.createDocRef(DocumentModel, someDocumentId);
+	* const myRecordCollection = docRef.getRecords(MyModel);
+	*
+	* myRecordCollection.onItemsAdded((items) => {
+	*   console.log("New records added:", items);
+	* })
+	* ```
+	*/
 	getRecords<R extends Model>(model: R): RecordCollectionRef<R>;
+	/**
+	* Subscribe to activity events for the document.
+	*
+	* Activity is used by applications to describe changes to the document, for
+	* populating activity feeds, change histories, notifications and similar
+	* features.
+	*
+	* @see {withTransaction} for making edits that generate activity events.
+	*
+	* @returns An unsubscribe function.
+	* @example
+	* ```ts
+	* const unsubscribe = docRef.onActivity((docRef, event) => {
+	*   console.log("Activity event:", event);
+	* });
+	*
+	* // Submit an edit with a description to generate an activity event.
+	* docRef.withTransaction(() => {
+	*   // make some edits to the document here
+	* }, {
+	*   model: MyEventModel,
+	*   data: {
+	*     myDataField: "some value",
+	*     foo: 42,
+	*   },
+	* });
+	*
+	* // Later, to unsubscribe:
+	* unsubscribe();
+	* ```
+	*/
 	onActivity(callback: (docRef: DocumentRef<D>, event: ActivityEvent) => void): Unsubscribe;
+	/**
+	* Subscribe to metadata changes for the document.
+	*
+	* @returns An unsubscribe function.
+	* @example
+	* ```ts
+	* const unsubscribe = docRef.onMetadataChange((docRef, metadata) => {
+	*   console.log("Metadata changed:", metadata);
+	* });
+	*
+	* // Later, to unsubscribe:
+	* unsubscribe();
+	* ```
+	*/
 	onMetadataChange(callback: (docRef: DocumentRef<D>, metadata: DocumentMetadata) => void): Unsubscribe;
+	/**
+	* Subscribe to presence events for the document.
+	*
+	* Presence events are a way to broadcast and receive non-persisted awareness
+	* and presence events. For example, a user moving their cursor in a
+	* collaborative editor could be broadcast via custom presence events.
+	*
+	* @see {@link updateCustomPresence} to publish custom presence updates.
+	*
+	* @param callback The callback to invoke on presence events.
+	* @param options Options for the presence subscription.
+	* @returns An unsubscribe function.
+	* @example
+	* ```ts
+	* const unsubscribe = docRef.onPresence((docRef, event) => {
+	*   console.log("Presence event:", event);
+	*   if (event.model === MyPresenceModel) {
+	*     updateCursor((event.eventData as ModelData<MyPresenceModel>).cursorPosition);
+	*   }
+	* }, { ignoreSelfUpdates: true });
+	*
+	* // Broadcast a presence update
+	* docRef.updateCustomPresence(MyPresenceModel, {
+	*  cursorPosition: [42, 7],
+	* });
+	*
+	* // Later, to unsubscribe:
+	* unsubscribe();
+	* ```
+	*/
 	onPresence(callback: (docRef: DocumentRef<D>, event: PresenceEvent) => void, options?: PresenceSubscriptionOptions): Unsubscribe;
+	/**
+	* Subscribe to be notified any time the document state changes.
+	* This is largely for testing purposes.
+	*
+	* @experimental
+	*
+	* @param callback The callback to invoke on state changes.
+	* @returns An unsubscribe function.
+	* @example
+	* ```ts
+	* const unsubscribe = docRef.onStateChange((docRef) => {
+	*   console.log("Document state changed:", docRef);
+	* });
+	*
+	* // Later, to unsubscribe:
+	* unsubscribe();
+	* ```
+	*/
 	onStateChange(callback: (docRef: DocumentRef<D>) => void): Unsubscribe;
+	/**
+	* Broadcasts an update for the specified model as presence data to other
+	* subscribers.
+	*
+	* Presence data is ephemeral and not stored as part of the document state. It
+	* is intended for broadcasting transient user presence and awareness
+	* information. Each different model type used for presence is expected to
+	* update the latest 'presence state' for that model type.
+	*
+	* @see {@link onPresence} to subscribe to presence updates.
+	*
+	* @param model The model type to update presence for.
+	* @param eventData The new presence data for the model.
+	*/
 	updateCustomPresence<M extends Model = Model>(model: M, eventData: ModelData<M>): void;
+	/**
+	* Execute one or more document edits within a transaction, optionally providing
+	* a description of the edit for activity tracking.
+	*
+	* All edits made within the provided function will be treated as a single
+	* atomic edit operation. If a description is provided, an activity event will
+	* be generated for the edit.
+	*
+	* If this is called within an existing transaction, the inner edits will be
+	* included in the outer transaction only, and the inner descriptions will be
+	* discarded.
+	*
+	* @see {@link onActivity} to subscribe to activity events on this document.
+	*
+	* @param fn A lambda including some document edits.
+	* @param description Optional description of the edit for activity tracking.
+	*
+	* @example
+	* ```ts
+	* docRef.withTransaction(() => {
+	*   const myRecords = docRef.getRecords(MyModel);
+	*   myRecords.set("record-1", { field: "new value" });
+	*   myRecords.delete("record-2");
+	* }, {
+	*   model: MyEditEventModel,
+	*   data: {
+	*     summary: "Updated record-1 and deleted record-2",
+	*   },
+	* });
+	* ```
+	*/
 	withTransaction(fn: () => void, description?: EditDescription): void;
 }

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

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cAAc,qBAAqB;AACnC,cAAc,wBAAwB;AACtC,cAAc,gBAAgB,qBAAqB;AACnD,cAAc,iBAAiB,OAAO,iBAAiB;AACvD,cAAc,qBAAqB;AACnC,cAAc,2BAA2B;AACzC,cAAc,mBAAmB;AAEjC,YAAY,aAAa,SAAS;AAElC,iBAAiB,4BAA4B;UAClC;;AAGX,OAAO,cAAMA;AAEb,iBAAiB,YAAY,UAAU,iBAAiB,gBAAgB;UAC7D,IAAI;UACJ,QAAQ;WACP,0BAA0B;CAEpC,kBAAkB,QAAQ,cAAc;CACxC,WAAW,UAAU,OAAO,OAAO,IAAI,oBAAoB;CAC3D,WACE,WAAW,QAAQ,YAAY,IAAI,OAAO,yBACzC;CACH,iBACE,WAAW,QAAQ,YAAY,IAAI,UAAU,4BAC5C;CACH,WACE,WAAW,QAAQ,YAAY,IAAI,OAAO,wBAC1C,UAAU,8BACT;CACH,cACE,WAAW,QAAQ,YAAY,cAC9B;CACH,qBAAqB,UAAU,QAAQ,OACrC,OAAO,GACP,WAAW,UAAU;CAEvB,gBAAgB,gBAAgB,cAAc","names":["DocumentRefBrand: unique symbol"],"sources":["../../../src/types/DocumentRef.ts"],"version":3,"file":"DocumentRef.d.ts"}
+{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cAAc,qBAAqB;AACnC,cAAc,wBAAwB;AACtC,cAAc,gBAAgB,qBAAqB;AACnD,cAAc,iBAAiB,OAAO,iBAAiB;AACvD,cAAc,qBAAqB;AACnC,cAAc,2BAA2B;AACzC,cAAc,mBAAmB;AAEjC,YAAY,aAAa,SAAS;;;;AAKlC,iBAAiB,4BAA4B;;;;;;UAMlC;;AAGX,OAAO,cAAMA;;;;;;;;;;;;AAab,iBAAiB,YAAY,UAAU,iBAAiB,gBAAgB;UAC7D,IAAI;UACJ,QAAQ;WACP,0BAA0B;;;;;;;;CASpC,kBAAkB,QAAQ,cAAc;;;;;;;;;;;;;;;;;;;;;;CAuBxC,WAAW,UAAU,OAAO,OAAO,IAAI,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiC3D,WACE,WAAW,QAAQ,YAAY,IAAI,OAAO,yBACzC;;;;;;;;;;;;;;;CAgBH,iBACE,WAAW,QAAQ,YAAY,IAAI,UAAU,4BAC5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCH,WACE,WAAW,QAAQ,YAAY,IAAI,OAAO,wBAC1C,UAAU,8BACT;;;;;;;;;;;;;;;;;;;CAoBH,cACE,WAAW,QAAQ,YAAY,cAC9B;;;;;;;;;;;;;;;CAgBH,qBAAqB,UAAU,QAAQ,OACrC,OAAO,GACP,WAAW,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCvB,gBAAgB,gBAAgB,cAAc","names":["DocumentRefBrand: unique symbol"],"sources":["../../../src/types/DocumentRef.ts"],"version":3,"file":"DocumentRef.d.ts"}

package/build/types/types/DocumentSchema.d.ts

@@ -1,8 +1,14 @@
 import type { WithMetadata } from "./Metadata.js";
 import type { Model, ModelData } from "./Model.js";
+/**
+* The base type for an application sdk's generated document schema.
+*/
 export interface DocumentSchema extends WithMetadata<DocumentSchemaMetadata> {
 	readonly [modelName: string]: Model;
 }
+/**
+* The plain object representation of the state of a document.
+*/
 export type DocumentState<S extends DocumentSchema> = { readonly [K in Exclude<keyof S, symbol>] : {
 	readonly [key: string]: ModelData<S[K]>;
 } };

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

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,oBAAoB;AAClC,cAAc,OAAO,iBAAiB;AAEtC,iBAAiB,uBAAuB,aAAa,wBAAwB;+BAC7C;;AAGhC,YAAY,cAAc,UAAU,8BACxB,KAAK,cAAc,cAAa;yBAA0B,UAAU,EAAE;;AAGlF,iBAAiB,uBAAuB;UAC7B","names":[],"sources":["../../../src/types/DocumentSchema.ts"],"version":3,"file":"DocumentSchema.d.ts"}
+{"mappings":"AAgBA,cAAc,oBAAoB;AAClC,cAAc,OAAO,iBAAiB;;;;AAKtC,iBAAiB,uBAAuB,aAAa,wBAAwB;+BAC7C;;;;;AAMhC,YAAY,cAAc,UAAU,8BACxB,KAAK,cAAc,cAAa;yBAA0B,UAAU,EAAE;;AAGlF,iBAAiB,uBAAuB;UAC7B","names":[],"sources":["../../../src/types/DocumentSchema.ts"],"version":3,"file":"DocumentSchema.d.ts"}

package/build/types/types/Model.d.ts

@@ -13,6 +13,9 @@ export interface Model<
 	readonly zodSchema: Readonly<Z>;
 }
 export type ModelData<M extends Model> = M["__type"];
+/**
+* Describes an edit made to a document.
+*/
 export interface EditDescription<M extends Model = Model> {
 	readonly data: ModelData<M>;
 	readonly model: M;
@@ -25,6 +28,12 @@ export declare const ExternalRefType: {
 };
 export type ExternalRefType = typeof ExternalRefType[keyof typeof ExternalRefType];
 export interface ModelMetadata<T = unknown> {
+	/**
+	* Which fields in the model are external references (e.g. UserRef, DocumentRef, etc).
+	*/
 	readonly externalRefFieldTypes?: Readonly<Record<keyof T, ExternalRefType>>;
+	/**
+	* The name of the model (should match the typescript symbol).
+	*/
 	readonly name: string;
 }

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

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,eAAe;AAC7B,cAAc,oBAAoB;;;;;;AAQlC,iBAAiB;CAAM;CAAa,UAAU,QAAQ,KAAK,QAAQ;UACzD,aAAa,cAAc,IACrC;UACW,QAAQ;UACR,WAAW,SAAS;;AAG/B,YAAY,UAAU,UAAU,SAAS,EAAE;AAE3C,iBAAiB,gBAAgB,UAAU,QAAQ,OAAO;UAC/C,MAAM,UAAU;UAChB,OAAO;;AAGlB,OAAO,cAAM;UACX,SAAS;UACT,WAAW;UACX,YAAY;UACZ,UAAU;;AAGZ,YAAY,yBAAyB,6BAA6B;AAElE,iBAAiB,cAAc,aAAa;UACjC,wBAAwB,SAAS,aAAa,GAAG;UACjD","names":[],"sources":["../../../src/types/Model.ts"],"version":3,"file":"Model.d.ts"}
+{"mappings":"AAgBA,cAAc,eAAe;AAC7B,cAAc,oBAAoB;;;;;;AAQlC,iBAAiB;CAAM;CAAa,UAAU,QAAQ,KAAK,QAAQ;UACzD,aAAa,cAAc,IACrC;UACW,QAAQ;UACR,WAAW,SAAS;;AAG/B,YAAY,UAAU,UAAU,SAAS,EAAE;;;;AAK3C,iBAAiB,gBAAgB,UAAU,QAAQ,OAAO;UAC/C,MAAM,UAAU;UAChB,OAAO;;AAGlB,OAAO,cAAM;UACX,SAAS;UACT,WAAW;UACX,YAAY;UACZ,UAAU;;AAGZ,YAAY,yBAAyB,6BAA6B;AAElE,iBAAiB,cAAc,aAAa;;;;UAIjC,wBAAwB,SAAS,aAAa,GAAG;;;;UAIjD","names":[],"sources":["../../../src/types/Model.ts"],"version":3,"file":"Model.d.ts"}

package/build/types/types/PresenceEvent.d.ts

@@ -7,23 +7,66 @@ export declare const PresenceEventDataType: {
 	readonly UNKNOWN: "unknown";
 };
 export type PresenceEventDataType = typeof PresenceEventDataType[keyof typeof PresenceEventDataType];
+/**
+* Any client that subscribes to presence events via `DocumentRef.onPresence` will
+* be considered 'present' on the document, and trigger an 'arrived' presence event.
+* When they disconnect or unsubscribe from presence events, a 'departed' presence event
+* will be triggered.
+*/
 export interface PresenceEventDataArrived {
 	readonly type: typeof PresenceEventDataType.ARRIVED;
 }
+/**
+* Any client that subscribes to presence events via `DocumentRef.onPresence` will
+* be considered 'present' on the document, and trigger an 'arrived' presence event.
+* When they disconnect or unsubscribe from presence events, a 'departed' presence event
+* will be triggered.
+*/
 export interface PresenceEventDataDeparted {
 	readonly type: typeof PresenceEventDataType.DEPARTED;
 }
+/**
+* Application specific custom presence event data.
+*
+* Each different model type used for presence is expected to update the latest
+* 'presence state' for that model type.
+*
+* For example, your app may have need to broadcast user cursor positions and
+* selection ranges as presence data. You could define your schema to include a
+* `CursorPosition` and `SelectionRange` record types, and set them
+* independently via `{@link DocumentRef.updateCustomPresence}`. Each model type
+* sent as a custom presence event should be considered a separate 'channel' of
+* presence data on this document.
+*/
 export interface PresenceEventDataCustom<M extends Model = Model> {
 	readonly type: typeof PresenceEventDataType.CUSTOM_EVENT;
 	readonly eventData: ModelData<M>;
 	readonly model: M;
 }
+/**
+* Fallback for unrecognized activity event types.
+*
+* This allows some flexibility with new event types added to the platform.
+* Likely unknown events represent a new platform event type and will be handled
+* in a future release of pack libraries and can be safely ignored by
+* applications.
+*/
 export interface PresenceEventUnknown {
 	readonly type: "unknown";
 	readonly rawType: string;
 	readonly rawData: unknown;
 }
 export type PresenceEventData = PresenceEventDataArrived | PresenceEventDataDeparted | PresenceEventDataCustom | PresenceEventUnknown;
+/**
+* An event representing a transient awareness or presence change for a user on this document.
+* The presence channel is intended for ephemeral data such as user cursors, selections, or
+* other live collaboration indicators.
+*
+* PresenceEvents are not persisted in document history.
+*
+* When a client goes offline, its presence is considered departed and any presence events
+* associated with that user should be considered stale and / or cleared.
+*/
 export interface PresenceEvent {
 	readonly userId: UserId;
 	readonly eventData: PresenceEventData;

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

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,OAAO,iBAAiB;AACtC,cAAc,cAAc;AAE5B,OAAO,cAAM;UACX,SAAS;UACT,UAAU;UACV,cAAc;UACd,SAAS;;AAGX,YAAY,+BACH,mCAAmC;AAE5C,iBAAiB,yBAAyB;UAC/B,aAAa,sBAAsB;;AAG9C,iBAAiB,0BAA0B;UAChC,aAAa,sBAAsB;;AAG9C,iBAAiB,wBAAwB,UAAU,QAAQ,OAAO;UACvD,aAAa,sBAAsB;UACnC,WAAW,UAAU;UACrB,OAAO;;AAGlB,iBAAiB,qBAAqB;UAC3B,MAAM;UACN;UACA;;AAGX,YAAY,oBACR,2BACA,4BACA,0BACA;AAEJ,iBAAiB,cAAc;UACpB,QAAQ;UACR,WAAW","names":[],"sources":["../../../src/types/PresenceEvent.ts"],"version":3,"file":"PresenceEvent.d.ts"}
+{"mappings":"AAgBA,cAAc,OAAO,iBAAiB;AACtC,cAAc,cAAc;AAE5B,OAAO,cAAM;UACX,SAAS;UACT,UAAU;UACV,cAAc;UACd,SAAS;;AAGX,YAAY,+BACH,mCAAmC;;;;;;;AAQ5C,iBAAiB,yBAAyB;UAC/B,aAAa,sBAAsB;;;;;;;;AAS9C,iBAAiB,0BAA0B;UAChC,aAAa,sBAAsB;;;;;;;;;;;;;;;AAgB9C,iBAAiB,wBAAwB,UAAU,QAAQ,OAAO;UACvD,aAAa,sBAAsB;UACnC,WAAW,UAAU;UACrB,OAAO;;;;;;;;;;AAWlB,iBAAiB,qBAAqB;UAC3B,MAAM;UACN;UACA;;AAGX,YAAY,oBACR,2BACA,4BACA,0BACA;;;;;;;;;;;AAYJ,iBAAiB,cAAc;UACpB,QAAQ;UACR,WAAW","names":[],"sources":["../../../src/types/PresenceEvent.ts"],"version":3,"file":"PresenceEvent.d.ts"}

package/build/types/types/RecordCollectionRef.d.ts

@@ -2,17 +2,71 @@ import type { DocumentRef } from "./DocumentRef.js";
 import type { Model, ModelData } from "./Model.js";
 import type { RecordId, RecordRef } from "./RecordRef.js";
 export declare const RecordCollectionRefBrand: unique symbol;
+/**
+* A reference providing an API to interact with a collection of records in a document.
+*/
 export interface RecordCollectionRef<M extends Model = Model> {
 	readonly docRef: DocumentRef;
 	readonly model: M;
 	readonly [RecordCollectionRefBrand]: typeof RecordCollectionRefBrand;
+	/**
+	* Delete a record from the collection (and the document).
+	*
+	* @param id - The ID of the record to delete.
+	* @returns A promise that resolves when the record is deleted.
+	*/
 	delete(id: RecordId): Promise<void>;
+	/**
+	* Get a {@link RecordRef} from the collection. This provides the main API for
+	* accessing and updating individual records in a document.
+	*
+	* @param id - The ID of the record to get.
+	* @returns The record reference, or undefined if it doesn't exist. The
+	* recordRef is a stable object and can be used for reference equality checks.
+	*/
 	get(id: RecordId): RecordRef<M> | undefined;
+	/**
+	* Check if a record exists in the collection.
+	*
+	* @param id - The ID of the record to check.
+	* @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>>;
+	/**
+	* Subscribe to added items in the collection.
+	*
+	* @param callback - The callback to invoke when items are added.
+	* @returns An unsubscribe function.
+	*/
 	readonly onItemsAdded: (callback: (items: readonly RecordRef<M>[]) => void) => () => void;
+	/**
+	* Subscribe to changed items in the collection.
+	*
+	* @param callback - The callback to invoke when items are changed.
+	* @returns An unsubscribe function.
+	*/
 	readonly onItemsChanged: (callback: (items: readonly RecordRef<M>[]) => void) => () => void;
+	/**
+	* Subscribe to deleted items in the collection.
+	*
+	* @param callback - The callback to invoke when items are deleted.
+	* @returns An unsubscribe function.
+	*/
 	readonly onItemsDeleted: (callback: (items: readonly RecordRef<M>[]) => void) => () => void;
 }

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

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,mBAAmB;AACjC,cAAc,OAAO,iBAAiB;AACtC,cAAc,UAAU,iBAAiB;AAEzC,OAAO,cAAMA;AAIb,iBAAiB,oBAAoB,UAAU,QAAQ,OAAO;UACnD,QAAQ;UACR,OAAO;WACN,kCAAkC;CAE5C,OAAO,IAAI,WAAW;CACtB,IAAI,IAAI,WAAW,UAAU;CAC7B,IAAI,IAAI;CACR,IAAI,IAAI,UAAU,OAAO,UAAU,KAAK;UAC/B;EAER,OAAO,aAAa,SAAS,UAAU;UAE/B,eACP,WAAW,gBAAgB,UAAU;UAG9B,iBACP,WAAW,gBAAgB,UAAU;UAG9B,iBACP,WAAW,gBAAgB,UAAU","names":["RecordCollectionRefBrand: unique symbol"],"sources":["../../../src/types/RecordCollectionRef.ts"],"version":3,"file":"RecordCollectionRef.d.ts"}
+{"mappings":"AAgBA,cAAc,mBAAmB;AACjC,cAAc,OAAO,iBAAiB;AACtC,cAAc,UAAU,iBAAiB;AAEzC,OAAO,cAAMA;;;;AAOb,iBAAiB,oBAAoB,UAAU,QAAQ,OAAO;UACnD,QAAQ;UACR,OAAO;WACN,kCAAkC;;;;;;;CAQ5C,OAAO,IAAI,WAAW;;;;;;;;;CAStB,IAAI,IAAI,WAAW,UAAU;;;;;;;CAO7B,IAAI,IAAI;;;;;;;;;;;;;;CAcR,IAAI,IAAI,UAAU,OAAO,UAAU,KAAK;UAC/B;EAER,OAAO,aAAa,SAAS,UAAU;;;;;;;UAQ/B,eACP,WAAW,gBAAgB,UAAU;;;;;;;UAS9B,iBACP,WAAW,gBAAgB,UAAU;;;;;;;UAS9B,iBACP,WAAW,gBAAgB,UAAU","names":["RecordCollectionRefBrand: unique symbol"],"sources":["../../../src/types/RecordCollectionRef.ts"],"version":3,"file":"RecordCollectionRef.d.ts"}

package/build/types/types/RecordRef.d.ts

@@ -4,13 +4,84 @@ import type { Model, ModelData } from "./Model.js";
 import type { Unsubscribe } from "./Unsubscribe.js";
 export type RecordId = Flavored<"RecordId">;
 export declare const RecordRefBrand: unique symbol;
+/**
+* A reference providing an API to interact with a specific record in a
+* document. This is the main interface for accessing and updating individual
+* records.
+*
+* These will be created by docRef or recordCollectionRef APIs for example and
+* should not be created manually. RecordRefs are stable objects that can be
+* used for reference equality checks.
+*
+* @example
+* ```ts
+* import { DocumentRef, DocumentSchema, MyModel } from "@myapp/schema";
+* import { app } from "./appInstance";
+*
+* const docRef = app.getDocRef<DocumentSchema>(someDocumentId);
+*
+* const recordRef = docRef.getRecords(MyModel).set("my-record-id", { myFieldName: "some value", foo: 42 });
+*
+* // Or get a specific record.
+* const recordRef = docRef.getRecords(MyModel).get("my-record-id");
+*/
 export interface RecordRef<M extends Model = Model> {
 	readonly docRef: DocumentRef;
 	readonly id: RecordId;
 	readonly model: M;
 	readonly [RecordRefBrand]: typeof RecordRefBrand;
+	/**
+	* Get the current state of the record in a plain object.
+	* If there is an active subscription to the document this is the current state of the record in memory.
+	* Otherwise, this will fetch the latest state from the server.
+	*/
 	getSnapshot(): Promise<ModelData<M>>;
+	/**
+	* Subscribe to changes in the record.
+	* @param callback The callback to invoke when the record changes.
+	* @returns An unsubscribe function.
+	*
+	* @example
+	* ```ts
+	* // Subscribe to changes
+	* recordRef.onChange((newSnapshot, recordRef) => {
+	*   console.log("Record changed:", newSnapshot);
+	* });
+	*
+	* // Submit a change
+	* recordRef.set({ myFieldName: "new value" });
+	* ```
+	*/
 	onChange(callback: (snapshot: ModelData<M>, recordRef: RecordRef<M>) => void): Unsubscribe;
+	/**
+	* Subscribe to deletion of the record.
+	* @param callback The callback to invoke when the record is deleted.
+	* @returns An unsubscribe function.
+	*
+	* @example
+	* ```ts
+	* // Subscribe to deletion
+	* recordRef.onDeleted((recordRef) => {
+	*   console.log("Record deleted:", recordRef.id);
+	* });
+	*
+	* // Trigger the deletion
+	* docRef.getRecords(MyModel).delete(recordRef.id);
+	* ```
+	*/
 	onDeleted(callback: (recordRef: RecordRef<M>) => void): Unsubscribe;
+	/**
+	* 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>;
 }

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

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cAAc,mBAAmB;AACjC,cAAc,OAAO,iBAAiB;AACtC,cAAc,mBAAmB;AAEjC,YAAY,WAAW,SAAS;AAEhC,OAAO,cAAMA;AAEb,iBAAiB,UAAU,UAAU,QAAQ,OAAO;UACzC,QAAQ;UACR,IAAI;UACJ,OAAO;WACN,wBAAwB;CAElC,eAAe,QAAQ,UAAU;CACjC,SAAS,WAAW,UAAU,UAAU,IAAI,WAAW,UAAU,cAAc;CAC/E,UAAU,WAAW,WAAW,UAAU,cAAc;CACxD,IAAI,QAAQ,UAAU,KAAK","names":["RecordRefBrand: unique symbol"],"sources":["../../../src/types/RecordRef.ts"],"version":3,"file":"RecordRef.d.ts"}
+{"mappings":"AAgBA,cAAc,gBAAgB;AAC9B,cAAc,mBAAmB;AACjC,cAAc,OAAO,iBAAiB;AACtC,cAAc,mBAAmB;AAEjC,YAAY,WAAW,SAAS;AAEhC,OAAO,cAAMA;;;;;;;;;;;;;;;;;;;;;;AAuBb,iBAAiB,UAAU,UAAU,QAAQ,OAAO;UACzC,QAAQ;UACR,IAAI;UACJ,OAAO;WACN,wBAAwB;;;;;;CAOlC,eAAe,QAAQ,UAAU;;;;;;;;;;;;;;;;;CAkBjC,SAAS,WAAW,UAAU,UAAU,IAAI,WAAW,UAAU,cAAc;;;;;;;;;;;;;;;;;CAkB/E,UAAU,WAAW,WAAW,UAAU,cAAc;;;;;;;;;;;;;;CAexD,IAAI,QAAQ,UAAU,KAAK","names":["RecordRefBrand: unique symbol"],"sources":["../../../src/types/RecordRef.ts"],"version":3,"file":"RecordRef.d.ts"}

package/build/types/types/Unsubscribe.d.ts

@@ -1 +1,4 @@
+/**
+* A function that can be called to unsubscribe from a previously subscribed event interface.
+*/
 export type Unsubscribe = () => void;

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

@@ -1 +1 @@
-{"mappings":"AAgBA,YAAY","names":[],"sources":["../../../src/types/Unsubscribe.ts"],"version":3,"file":"Unsubscribe.d.ts"}
+{"mappings":";;;AAmBA,YAAY","names":[],"sources":["../../../src/types/Unsubscribe.ts"],"version":3,"file":"Unsubscribe.d.ts"}

package/build/types/types/UserRef.d.ts

@@ -1,6 +1,11 @@
 import type { Flavored } from "@palantir/pack.core";
 export type UserId = Flavored<"pack:UserId">;
 export declare const UserRefBrand: unique symbol;
+/**
+* A reference providing an API to interact with a user.
+*
+* @experimental
+*/
 export interface UserRef {
 	readonly userId: UserId;
 	readonly [UserRefBrand]: typeof UserRefBrand;

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

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,gBAAgB;AAE9B,YAAY,SAAS,SAAS;AAE9B,OAAO,cAAMA;AAEb,iBAAiB,QAAQ;UACd,QAAQ;WACP,sBAAsB;UACvB,MAAM,oBAAoB","names":["UserRefBrand: unique symbol"],"sources":["../../../src/types/UserRef.ts"],"version":3,"file":"UserRef.d.ts"}
+{"mappings":"AAgBA,cAAc,gBAAgB;AAE9B,YAAY,SAAS,SAAS;AAE9B,OAAO,cAAMA;;;;;;AAOb,iBAAiB,QAAQ;UACd,QAAQ;WACP,sBAAsB;UACvB,MAAM,oBAAoB","names":["UserRefBrand: unique symbol"],"sources":["../../../src/types/UserRef.ts"],"version":3,"file":"UserRef.d.ts"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palantir/pack.document-schema.model-types",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Minimal types supporting generated PACK schemas",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@palantir/pack.core": "~0.1.0"
+    "@palantir/pack.core": "~0.2.0"
   },
   "peerDependencies": {
     "zod": "^4.1.7"
@@ -37,7 +37,7 @@
     "rimraf": "^6.0.1",
     "tslib": "^2.8.1",
     "typescript": "^5.9.2",
-    "@palantir/pack.monorepo.tsconfig": "~0.4.0"
+    "@palantir/pack.monorepo.tsconfig": "~0.4.3"
   },
   "publishConfig": {
     "access": "public"

package/src/__tests__/Metadata.test.ts

@@ -0,0 +1,43 @@
+/*
+ * 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 { getMetadata, Metadata, type WithMetadata } from "../types/Metadata.js";
+
+describe("Metadata Lookup Tests", () => {
+  it("should retrieve metadata using direct symbol access", () => {
+    const obj: WithMetadata<{ name: string }> = {
+      [Metadata]: { name: "TestModel" },
+    };
+
+    const result = getMetadata(obj);
+
+    expect(result).toEqual({ name: "TestModel" });
+  });
+
+  it("should fallback to string-based symbol matching for cross-package scenarios", () => {
+    // Simulate a different copy of the Metadata symbol (as if from a different package instance)
+    const differentMetadataSymbol = Symbol("@palantir/pack.document-schema/metadata");
+
+    const obj = {
+      [differentMetadataSymbol]: { version: 2 },
+    } as WithMetadata<{ version: number }>;
+
+    const result = getMetadata(obj);
+
+    expect(result).toEqual({ version: 2 });
+  });
+});

package/src/types/ActivityEvent.ts

@@ -25,6 +25,27 @@ export const ActivityEventDataType = {
   UNKNOWN: "unknown",
 } as const;
 
+/**
+ * Application specific custom activity event data, as described in a transaction edit,
+ * using an application sdk's generated model types.
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = docRef.onActivity((docRef, event) => {
+ *   console.log("Activity event:", event);
+ * });
+ * // Submit an edit with a description to generate an activity event.
+ * docRef.withTransaction(() => {
+ *   // make some edits to the document here
+ * }, {
+ *   model: MyEventModel,
+ *   data: {
+ *     myDataField: "some value",
+ *     foo: 42,
+ *   },
+ * });
+ * ```
+ */
 export interface ActivityEventDataCustom<M extends Model = Model> {
   readonly type: typeof ActivityEventDataType.CUSTOM_EVENT;
   readonly model: M;
@@ -33,6 +54,14 @@ export interface ActivityEventDataCustom<M extends Model = Model> {
 
 // TODO: add standard document activity events (need to be added to api types)
 
+/**
+ * Fallback for unrecognized activity event types.
+ *
+ * This allows some flexibility with new event types added to the platform.
+ * Likely unknown events represent a new platform event type and will be handled
+ * in a future release of pack libraries and can be safely ignored by
+ * applications.
+ */
 export interface ActivityEventDataUnknown {
   readonly type: "unknown";
   readonly rawType: string;
@@ -41,7 +70,15 @@ export interface ActivityEventDataUnknown {
 
 export type ActivityEventData = ActivityEventDataCustom | ActivityEventDataUnknown;
 
+/**
+ * An event representing an activity that has occurred on a document. This
+ * includes standard document events as well as custom application-specific
+ * events describing document edits.
+ *
+ * ActivityEvents are useful for building activity feeds, or notifications.
+ */
 export interface ActivityEvent {
+  /** Multiple events with the same aggregationKey may be collapsed. */
   readonly aggregationKey: string;
   readonly createdBy: UserId;
   readonly createdInstant: number;