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

package/build/types/utils/ActivityEvents.d.ts

@@ -0,0 +1,59 @@
+import type { ActivityEventData, ActivityEventDataCustom, ActivityEventDataUnknown } from "../types/ActivityEvent.js";
+import type { EditDescription, Model, ModelData } from "../types/Model.js";
+/**
+* Creates an edit description to describe an edit for activity purposes, for use with docRef.withTransaction.
+*
+* @param model The model to edit.
+* @param data The data to apply to the model.
+* @returns An edit description for the model.
+*
+* @example
+* ```ts
+* docRef.withTransaction(() => {
+*   // make some edits to the document here
+* }, ActivityEvents.describeEdit(MyEventModel, {
+*   myEventDataField: "some value",
+*   foo: 42,
+* }));
+* ```
+*/
+export declare function describeEdit<M extends Model>(model: M, data: ModelData<M>): EditDescription<M>;
+/**
+* Type guard for custom event data.
+*
+* @param eventData The event data to check.
+* @returns true if the event data is a custom event, false otherwise.
+*/
+export declare function isCustom(eventData: ActivityEventData): eventData is ActivityEventDataCustom;
+/**
+* Type guard for custom event data for a specific model.
+*
+* @param eventData The event data from a {@link ActivityEvent} to check.
+* @param model The model to check for.
+* @returns true if the event data is a custom event for the given model, false otherwise.
+*
+* @example
+* ```ts
+* docRef.onActivity((docRef, event) => {
+*   if (!ActivityEvents.isEdit(event.eventData, MyEventModel)) {
+*     return;
+*   }
+*
+*   console.log("Got event", event.eventData.eventData.myField);
+* });
+* ```
+*/
+export declare function isEdit<M extends Model>(eventData: ActivityEventData, model: M): eventData is ActivityEventDataCustom<M>;
+/**
+* Type guard for unknown activity event data. These are fired when a user
+* performs an action that is not recognized by this client.
+*
+* This may be due to application version mismatch, or new platform features for
+* example, and should generally be ignorable.
+*
+* @experimental
+*
+* @param eventData The event data to check.
+* @returns true if the event data is an unknown event, false otherwise.
+*/
+export declare function isUnknown(eventData: ActivityEventData): eventData is ActivityEventDataUnknown;

package/build/types/utils/ActivityEvents.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAgBA,cACE,mBACA,yBACA,gCACK;AAEP,cAAc,iBAAiB,OAAO,iBAAiB;;;;;;;;;;;;;;;;;;AAmBvD,OAAO,iBAAS,aAAa,UAAU,OAAO,OAAO,GAAG,MAAM,UAAU,KAAK,gBAAgB;;;;;;;AAa7F,OAAO,iBAAS,SACd,WAAW,oBACV,aAAa;;;;;;;;;;;;;;;;;;;AAsBhB,OAAO,iBAAS,OAAO,UAAU,OAC/B,WAAW,mBACX,OAAO,IACN,aAAa,wBAAwB;;;;;;;;;;;;;AAmBxC,OAAO,iBAAS,UACd,WAAW,oBACV,aAAa","names":[],"sources":["../../../src/utils/ActivityEvents.ts"],"version":3,"file":"ActivityEvents.d.ts"}

package/build/types/utils/PresenceEvents.d.ts

@@ -0,0 +1,66 @@
+import type { Model } from "../types/Model.js";
+import type { PresenceEventData, PresenceEventDataArrived, PresenceEventDataCustom, PresenceEventDataDeparted, PresenceEventDataUnknown } from "../types/PresenceEvent.js";
+/**
+* Type guard for Arrived presence events. These are fired when a user comes online on a document.
+* @param eventData The event data from a {@link PresenceEvent} to check.
+*
+* @example
+* ```ts
+* if (PresenceEvents.isArrived(event.eventData)) {
+*   console.log(`User ${event.userId} has arrived on the document.`);
+* }
+* ```
+*/
+export declare function isArrived(eventData: PresenceEventData): eventData is PresenceEventDataArrived;
+/**
+* Type guard for custom presence events.
+* @param eventData The event data from a {@link PresenceEvent} to check.
+* @param model The model to check for.
+* @returns true if the event data is a custom event for the given model, false otherwise.
+*
+* @example
+* ```ts
+* if (PresenceEvents.isCustom(event.eventData, MyEventModel)) {
+*   console.log("Got event", event.eventData.data.myField);
+* }
+* ```
+*/
+export declare function isCustom<M extends Model>(eventData: PresenceEventData, model: M): eventData is PresenceEventDataCustom<M>;
+/**
+* Type guard for custom presence events.
+* @param eventData The event data from a {@link PresenceEvent} to check.
+* @returns true if the event data is a custom event of some type, false otherwise.
+*
+* @example
+* ```ts
+* if (PresenceEvents.isCustom(event.eventData)) {
+*   console.log("Got a custom event:", event.eventData.model);
+* }
+* ```
+*/
+export declare function isCustom(eventData: PresenceEventData): eventData is PresenceEventDataCustom;
+/**
+* Type guard for Departed presence events. These are fired when a user goes offline from a document.
+* @param eventData The event data from a {@link PresenceEvent} to check.
+* @returns true if the event data is a departed event, false otherwise.
+*
+* @example
+* ```ts
+* if (PresenceEvents.isDeparted(event.eventData)) {
+*   console.log(`User ${event.userId} has departed from the document.`);
+* }
+* ```
+*/
+export declare function isDeparted(eventData: PresenceEventData): eventData is PresenceEventDataDeparted;
+/**
+* Type guard for unknown presence events. These are fired when a user performs an action that is not
+* recognized.
+* This may be due to application version mismatch, or new platform features for example, and should
+* generally be ignorable.
+*
+* @experimental
+*
+* @param eventData The event data from a {@link PresenceEvent} to check.
+* @returns true if the event data is an unknown event, false otherwise.
+*/
+export declare function isUnknown(eventData: PresenceEventData): eventData is PresenceEventDataUnknown;

package/build/types/utils/PresenceEvents.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAgBA,cAAc,aAAa;AAC3B,cACE,mBACA,0BACA,yBACA,2BACA,gCACK;;;;;;;;;;;;AAcP,OAAO,iBAAS,UAAU,WAAW,oBAAoB,aAAa;;;;;;;;;;;;;;AAiBtE,OAAO,iBAAS,SAAS,UAAU,OACjC,WAAW,mBACX,OAAO,IACN,aAAa,wBAAwB;;;;;;;;;;;;;AAaxC,OAAO,iBAAS,SAAS,WAAW,oBAAoB,aAAa;;;;;;;;;;;;;AAuBrE,OAAO,iBAAS,WAAW,WAAW,oBAAoB,aAAa;;;;;;;;;;;;AAevE,OAAO,iBAAS,UACd,WAAW,oBACV,aAAa","names":[],"sources":["../../../src/utils/PresenceEvents.ts"],"version":3,"file":"PresenceEvents.d.ts"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palantir/pack.document-schema.model-types",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Minimal types supporting generated PACK schemas",
   "license": "Apache-2.0",
   "repository": {

package/src/index.ts

@@ -38,7 +38,7 @@ export type {
 } from "./types/DocumentSchema.js";
 export { MediaRefBrand } from "./types/MediaRef.js";
 export type { MediaId, MediaRef } from "./types/MediaRef.js";
-export { getMetadata, Metadata } from "./types/Metadata.js";
+export { getMetadata, hasMetadata, Metadata } from "./types/Metadata.js";
 export type { WithMetadata } from "./types/Metadata.js";
 export { ExternalRefType } from "./types/Model.js";
 export type { EditDescription, Model, ModelData, ModelMetadata } from "./types/Model.js";
@@ -51,7 +51,7 @@ export type {
   PresenceEventDataArrived,
   PresenceEventDataCustom,
   PresenceEventDataDeparted,
-  PresenceEventUnknown,
+  PresenceEventDataUnknown,
 } from "./types/PresenceEvent.js";
 export { RecordCollectionRefBrand } from "./types/RecordCollectionRef.js";
 export type { RecordCollectionRef } from "./types/RecordCollectionRef.js";
@@ -60,3 +60,5 @@ export type { RecordId, RecordRef } from "./types/RecordRef.js";
 export type { Unsubscribe } from "./types/Unsubscribe.js";
 export { UserRefBrand } from "./types/UserRef.js";
 export type { UserId, UserRef } from "./types/UserRef.js";
+export * as ActivityEvents from "./utils/ActivityEvents.js";
+export * as PresenceEvents from "./utils/PresenceEvents.js";

package/src/types/ActivityEvent.ts

@@ -63,7 +63,7 @@ export interface ActivityEventDataCustom<M extends Model = Model> {
  * applications.
  */
 export interface ActivityEventDataUnknown {
-  readonly type: "unknown";
+  readonly type: typeof ActivityEventDataType.UNKNOWN;
   readonly rawType: string;
   readonly rawData: unknown;
 }

package/src/types/DocumentRef.ts

@@ -239,12 +239,9 @@ export interface DocumentRef<D extends DocumentSchema = DocumentSchema> {
    *   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",
-   *   },
-   * });
+   * }, ActivityEvents.describeEdit(MyEditEventModel, {
+   *   summary: "Updated record-1 and deleted record-2",
+   * }));
    * ```
    */
   withTransaction(fn: () => void, description?: EditDescription): void;

package/src/types/Metadata.ts

@@ -14,13 +14,17 @@
  * limitations under the License.
  */
 
+import { justOnce } from "@palantir/pack.core";
+
 export const Metadata: symbol = Symbol("@palantir/pack.document-schema/metadata");
 
 export interface WithMetadata<T> {
   readonly [Metadata]: T;
 }
 
-export function getMetadata<T>(obj: WithMetadata<T>): T {
+export function getMetadata<T>(obj: WithMetadata<T>, throwIfMissing?: true): T;
+export function getMetadata<T>(obj: WithMetadata<T>, throwIfMissing: false): T | undefined;
+export function getMetadata<T>(obj: WithMetadata<T>, throwIfMissing = true): T | undefined {
   // First try the direct symbol access
   const directMetadata = obj[Metadata];
   if (directMetadata != null) {
@@ -36,10 +40,27 @@ export function getMetadata<T>(obj: WithMetadata<T>): T {
     if (symbolKey.toString() === metadataString) {
       const fallbackMetadata = (obj as any)[symbolKey];
       if (fallbackMetadata != null) {
+        justOnce("getMetadata-fallback-warning", () => {
+          // eslint-disable-next-line no-console
+          console.warn(
+            "Warning: Retrieved metadata using fallback symbol lookup. "
+              + "This may indicate that multiple copies of the @palantir/pack.document-schema.model-types package are in use. "
+              + "Consider deduplicating your dependencies and checking bundle configurations to ensure proper behavior.",
+          );
+        });
         return fallbackMetadata;
       }
     }
   }
 
-  throw new Error("Object does not have metadata");
+  if (throwIfMissing) {
+    throw new Error("Object does not have metadata");
+  }
+}
+
+export function hasMetadata(obj: unknown): obj is WithMetadata<unknown> {
+  if (obj == null || typeof obj !== "object") {
+    return false;
+  }
+  return getMetadata(obj as WithMetadata<unknown>, false) != null;
 }

package/src/types/PresenceEvent.ts

@@ -74,8 +74,8 @@ export interface PresenceEventDataCustom<M extends Model = Model> {
  * in a future release of pack libraries and can be safely ignored by
  * applications.
  */
-export interface PresenceEventUnknown {
-  readonly type: "unknown";
+export interface PresenceEventDataUnknown {
+  readonly type: typeof PresenceEventDataType.UNKNOWN;
   readonly rawType: string;
   readonly rawData: unknown;
 }
@@ -84,7 +84,7 @@ export type PresenceEventData =
   | PresenceEventDataArrived
   | PresenceEventDataDeparted
   | PresenceEventDataCustom
-  | PresenceEventUnknown;
+  | PresenceEventDataUnknown;
 
 /**
  * An event representing a transient awareness or presence change for a user on this document.

package/src/types/RecordRef.ts

@@ -88,11 +88,23 @@ export interface RecordRef<M extends Model = Model> {
    * });
    *
    * // Trigger the deletion
-   * docRef.getRecords(MyModel).delete(recordRef.id);
+   * recordRef.delete();
    * ```
    */
   onDeleted(callback: (recordRef: RecordRef<M>) => void): Unsubscribe;
 
+  /**
+   * Delete the record from the document.
+   *
+   * @returns An ignorable promise that resolves when the record is deleted.
+   *
+   * @example
+   * ```ts
+   * await recordRef.delete();
+   * ```
+   */
+  delete(): Promise<void>;
+
   /**
    * Set the data for the record (creating it if it doesn't exist).
    *
@@ -107,4 +119,19 @@ export interface RecordRef<M extends Model = Model> {
    * ```
    */
   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/utils/ActivityEvents.ts

@@ -0,0 +1,105 @@
+/*
+ * 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 {
+  ActivityEventData,
+  ActivityEventDataCustom,
+  ActivityEventDataUnknown,
+} from "../types/ActivityEvent.js";
+import { ActivityEventDataType } from "../types/ActivityEvent.js";
+import type { EditDescription, Model, ModelData } from "../types/Model.js";
+
+/**
+ * Creates an edit description to describe an edit for activity purposes, for use with docRef.withTransaction.
+ *
+ * @param model The model to edit.
+ * @param data The data to apply to the model.
+ * @returns An edit description for the model.
+ *
+ * @example
+ * ```ts
+ * docRef.withTransaction(() => {
+ *   // make some edits to the document here
+ * }, ActivityEvents.describeEdit(MyEventModel, {
+ *   myEventDataField: "some value",
+ *   foo: 42,
+ * }));
+ * ```
+ */
+export function describeEdit<M extends Model>(model: M, data: ModelData<M>): EditDescription<M> {
+  return {
+    data,
+    model,
+  };
+}
+
+/**
+ * Type guard for custom event data.
+ *
+ * @param eventData The event data to check.
+ * @returns true if the event data is a custom event, false otherwise.
+ */
+export function isCustom(
+  eventData: ActivityEventData,
+): eventData is ActivityEventDataCustom {
+  return eventData.type === ActivityEventDataType.CUSTOM_EVENT;
+}
+
+/**
+ * Type guard for custom event data for a specific model.
+ *
+ * @param eventData The event data from a {@link ActivityEvent} to check.
+ * @param model The model to check for.
+ * @returns true if the event data is a custom event for the given model, false otherwise.
+ *
+ * @example
+ * ```ts
+ * docRef.onActivity((docRef, event) => {
+ *   if (!ActivityEvents.isEdit(event.eventData, MyEventModel)) {
+ *     return;
+ *   }
+ *
+ *   console.log("Got event", event.eventData.eventData.myField);
+ * });
+ * ```
+ */
+export function isEdit<M extends Model>(
+  eventData: ActivityEventData,
+  model: M,
+): eventData is ActivityEventDataCustom<M> {
+  return (
+    eventData.type === ActivityEventDataType.CUSTOM_EVENT
+    && eventData.model === model
+  );
+}
+
+/**
+ * Type guard for unknown activity event data. These are fired when a user
+ * performs an action that is not recognized by this client.
+ *
+ * This may be due to application version mismatch, or new platform features for
+ * example, and should generally be ignorable.
+ *
+ * @experimental
+ *
+ * @param eventData The event data to check.
+ * @returns true if the event data is an unknown event, false otherwise.
+ */
+export function isUnknown(
+  eventData: ActivityEventData,
+): eventData is ActivityEventDataUnknown {
+  return eventData.type === ActivityEventDataType.UNKNOWN;
+}

package/src/utils/PresenceEvents.ts

@@ -0,0 +1,113 @@
+/*
+ * 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 } from "../types/Model.js";
+import type {
+  PresenceEventData,
+  PresenceEventDataArrived,
+  PresenceEventDataCustom,
+  PresenceEventDataDeparted,
+  PresenceEventDataUnknown,
+} from "../types/PresenceEvent.js";
+import { PresenceEventDataType } from "../types/PresenceEvent.js";
+
+/**
+ * Type guard for Arrived presence events. These are fired when a user comes online on a document.
+ * @param eventData The event data from a {@link PresenceEvent} to check.
+ *
+ * @example
+ * ```ts
+ * if (PresenceEvents.isArrived(event.eventData)) {
+ *   console.log(`User ${event.userId} has arrived on the document.`);
+ * }
+ * ```
+ */
+export function isArrived(eventData: PresenceEventData): eventData is PresenceEventDataArrived {
+  return eventData.type === PresenceEventDataType.ARRIVED;
+}
+
+/**
+ * Type guard for custom presence events.
+ * @param eventData The event data from a {@link PresenceEvent} to check.
+ * @param model The model to check for.
+ * @returns true if the event data is a custom event for the given model, false otherwise.
+ *
+ * @example
+ * ```ts
+ * if (PresenceEvents.isCustom(event.eventData, MyEventModel)) {
+ *   console.log("Got event", event.eventData.data.myField);
+ * }
+ * ```
+ */
+export function isCustom<M extends Model>(
+  eventData: PresenceEventData,
+  model: M,
+): eventData is PresenceEventDataCustom<M>;
+/**
+ * Type guard for custom presence events.
+ * @param eventData The event data from a {@link PresenceEvent} to check.
+ * @returns true if the event data is a custom event of some type, false otherwise.
+ *
+ * @example
+ * ```ts
+ * if (PresenceEvents.isCustom(event.eventData)) {
+ *   console.log("Got a custom event:", event.eventData.model);
+ * }
+ * ```
+ */
+export function isCustom(eventData: PresenceEventData): eventData is PresenceEventDataCustom;
+export function isCustom<M extends Model>(
+  eventData: PresenceEventData,
+  model?: M,
+): eventData is PresenceEventDataCustom<M> {
+  return (
+    eventData.type === PresenceEventDataType.CUSTOM_EVENT
+    && (model == null || eventData.model === model)
+  );
+}
+
+/**
+ * Type guard for Departed presence events. These are fired when a user goes offline from a document.
+ * @param eventData The event data from a {@link PresenceEvent} to check.
+ * @returns true if the event data is a departed event, false otherwise.
+ *
+ * @example
+ * ```ts
+ * if (PresenceEvents.isDeparted(event.eventData)) {
+ *   console.log(`User ${event.userId} has departed from the document.`);
+ * }
+ * ```
+ */
+export function isDeparted(eventData: PresenceEventData): eventData is PresenceEventDataDeparted {
+  return eventData.type === PresenceEventDataType.DEPARTED;
+}
+
+/**
+ * Type guard for unknown presence events. These are fired when a user performs an action that is not
+ * recognized.
+ * This may be due to application version mismatch, or new platform features for example, and should
+ * generally be ignorable.
+ *
+ * @experimental
+ *
+ * @param eventData The event data from a {@link PresenceEvent} to check.
+ * @returns true if the event data is an unknown event, false otherwise.
+ */
+export function isUnknown(
+  eventData: PresenceEventData,
+): eventData is PresenceEventDataUnknown {
+  return eventData.type === PresenceEventDataType.UNKNOWN;
+}