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

package/src/types/PresenceEvent.ts

@@ -0,0 +1,102 @@
+/*
+ * 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 { Model, ModelData } from "./Model.js";
+import type { UserId } from "./UserRef.js";
+
+export const PresenceEventDataType = {
+  ARRIVED: "presenceArrived",
+  DEPARTED: "presenceDeparted",
+  CUSTOM_EVENT: "customEvent",
+  UNKNOWN: "unknown",
+} as const;
+
+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/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;