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

package/src/types/DocumentRef.ts

@@ -25,35 +25,227 @@ 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;
 
+  /**
+   * 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/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,9 @@ 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;
@@ -47,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;
 }

package/src/types/PresenceEvent.ts

@@ -27,20 +27,53 @@ export const PresenceEventDataType = {
 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;
@@ -53,6 +86,16 @@ export type PresenceEventData =
   | 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/src/types/RecordCollectionRef.ts

@@ -22,27 +22,81 @@ export const RecordCollectionRefBrand: unique symbol = Symbol(
   "pack:RecordCollectionRef",
 );
 
+/**
+ * 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/src/types/RecordRef.ts

@@ -23,14 +23,88 @@ export type RecordId = Flavored<"RecordId">;
 
 export const RecordRefBrand: unique symbol = Symbol("pack:RecordRef");
 
+/**
+ * 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/src/types/Unsubscribe.ts

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

package/src/types/UserRef.ts

@@ -20,6 +20,11 @@ export type UserId = Flavored<"pack:UserId">;
 
 export const UserRefBrand: unique symbol = Symbol("pack:UserRef");
 
+/**
+ * A reference providing an API to interact with a user.
+ *
+ * @experimental
+ */
 export interface UserRef {
   readonly userId: UserId;
   readonly [UserRefBrand]: typeof UserRefBrand;