@palantir/pack.document-schema.model-types 0.1.0-beta.3 → 0.1.1

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-beta.3",
+  "version": "0.1.1",
   "description": "Minimal types supporting generated PACK schemas",
   "license": "Apache-2.0",
   "repository": {
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@palantir/pack.core": "~0.1.0-beta.2"
+    "@palantir/pack.core": "~0.1.1"
   },
   "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-beta.1"
+    "@palantir/pack.monorepo.tsconfig": "~0.4.3"
   },
   "publishConfig": {
     "access": "public"
@@ -48,8 +48,8 @@
   "type": "module",
   "scripts": {
     "clean": "rimraf .turbo build dist lib test-output *.tgz tsconfig.tsbuildinfo",
-    "lint": "eslint ./src ; dprint check --config $(find-up dprint.json) --allow-no-files",
-    "lint:fix": "eslint ./src --fix ; dprint fmt --config $(find-up dprint.json) --allow-no-files",
+    "lint": "eslint ./src && dprint check --config $(find-up dprint.json) --allow-no-files",
+    "lint:fix": "eslint ./src --fix && dprint fmt --config $(find-up dprint.json) --allow-no-files",
     "test": "vitest run --passWithNoTests -u",
     "test:watch": "vitest --passWithNoTests",
     "transpileBrowser": "monorepo-transpile -f esm -m bundle -t browser",

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/index.ts

@@ -14,6 +14,14 @@
  * limitations under the License.
  */
 
+export { ActivityEventDataType } from "./types/ActivityEvent.js";
+export type {
+  ActivityEvent,
+  ActivityEventData,
+  ActivityEventDataCustom,
+  ActivityEventDataUnknown,
+  ActivityEventId,
+} from "./types/ActivityEvent.js";
 export type {
   DiscretionaryPrincipal,
   DiscretionaryPrincipal_All,
@@ -22,7 +30,7 @@ export type {
   DocumentMetadata,
 } from "./types/DocumentMetadata.js";
 export { DocumentRefBrand } from "./types/DocumentRef.js";
-export type { DocumentId, DocumentRef } from "./types/DocumentRef.js";
+export type { DocumentId, DocumentRef, PresenceSubscriptionOptions } from "./types/DocumentRef.js";
 export type {
   DocumentSchema,
   DocumentSchemaMetadata,
@@ -33,9 +41,18 @@ export type { MediaId, MediaRef } from "./types/MediaRef.js";
 export { getMetadata, Metadata } from "./types/Metadata.js";
 export type { WithMetadata } from "./types/Metadata.js";
 export { ExternalRefType } from "./types/Model.js";
-export type { Model, ModelData, ModelMetadata } from "./types/Model.js";
+export type { EditDescription, Model, ModelData, ModelMetadata } from "./types/Model.js";
 export { ObjectRefBrand } from "./types/ObjectRef.js";
 export type { ObjectId, ObjectRef } from "./types/ObjectRef.js";
+export { PresenceEventDataType } from "./types/PresenceEvent.js";
+export type {
+  PresenceEvent,
+  PresenceEventData,
+  PresenceEventDataArrived,
+  PresenceEventDataCustom,
+  PresenceEventDataDeparted,
+  PresenceEventUnknown,
+} from "./types/PresenceEvent.js";
 export { RecordCollectionRefBrand } from "./types/RecordCollectionRef.js";
 export type { RecordCollectionRef } from "./types/RecordCollectionRef.js";
 export { RecordRefBrand } from "./types/RecordRef.js";

package/src/types/ActivityEvent.ts

@@ -0,0 +1,88 @@
+/*
+ * 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 { Flavored } from "@palantir/pack.core";
+import type { Model, ModelData } from "./Model.js";
+import type { UserId } from "./UserRef.js";
+
+export type ActivityEventId = Flavored<"pack:EventId">;
+
+export const ActivityEventDataType = {
+  CUSTOM_EVENT: "customEvent",
+  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;
+  readonly eventData: ModelData<M>;
+}
+
+// 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;
+  readonly rawData: unknown;
+}
+
+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;
+  readonly eventData: ActivityEventData;
+  readonly eventId: ActivityEventId;
+  readonly isRead: boolean;
+}

package/src/types/DocumentRef.ts

@@ -15,27 +15,237 @@
  */
 
 import type { Flavored } from "@palantir/pack.core";
+import type { ActivityEvent } from "./ActivityEvent.js";
 import type { DocumentMetadata } from "./DocumentMetadata.js";
 import type { DocumentSchema, DocumentState } from "./DocumentSchema.js";
-import type { Model } from "./Model.js";
+import type { EditDescription, Model, ModelData } from "./Model.js";
+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 const DocumentRefBrand: unique symbol = Symbol("pack:DocumentRef");
 
+/**
+ * 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;
 
-  readonly getDocSnapshot: () => Promise<DocumentState<D>>;
-  readonly getRecords: <R extends Model>(model: R) => RecordCollectionRef<R>;
-  readonly onMetadataChange: (
-    callback: (docId: DocumentRef<D>, metadata: DocumentMetadata) => void,
-  ) => Unsubscribe;
-  readonly onStateChange: (
+  /**
+   * 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;
+  ): 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/src/types/DocumentSchema.ts

@@ -17,10 +17,16 @@
 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/src/types/Metadata.ts

@@ -21,10 +21,25 @@ export interface WithMetadata<T> {
 }
 
 export function getMetadata<T>(obj: WithMetadata<T>): T {
-  // TS always treats symbol keys as optional
-  const metadata = obj[Metadata];
-  if (metadata == null) {
-    throw new Error("Object does not have metadata");
+  // First try the direct symbol access
+  const directMetadata = obj[Metadata];
+  if (directMetadata != null) {
+    return directMetadata;
   }
-  return metadata;
+
+  // Fallback: search for a symbol with matching string representation
+  // If the different copies of this package are used, the symbol references will not match directly
+  const metadataString = Metadata.toString();
+  const symbolKeys = Object.getOwnPropertySymbols(obj);
+
+  for (const symbolKey of symbolKeys) {
+    if (symbolKey.toString() === metadataString) {
+      const fallbackMetadata = (obj as any)[symbolKey];
+      if (fallbackMetadata != null) {
+        return fallbackMetadata;
+      }
+    }
+  }
+
+  throw new Error("Object does not have metadata");
 }

package/src/types/Model.ts

@@ -32,6 +32,14 @@ export interface Model<T = unknown, Z extends ZodType<T> = ZodType<T>>
 
 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;
+}
+
 export const ExternalRefType = {
   DOC_REF: "docRef",
   MEDIA_REF: "mediaRef",
@@ -42,6 +50,12 @@ export 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;
 }