@palantir/pack.state.core 0.1.0-beta.2 → 0.1.1

package/src/service/BaseYjsDocumentService.ts

@@ -19,14 +19,17 @@
 import type { Logger } from "@osdk/api";
 import type { PackAppInternal, Unsubscribe } from "@palantir/pack.core";
 import {
+  type ActivityEvent,
   type DocumentId,
   type DocumentMetadata,
   type DocumentRef,
   type DocumentSchema,
   type DocumentState,
+  type EditDescription,
   getMetadata,
   type Model,
   type ModelData,
+  type PresenceEvent,
   type RecordCollectionRef,
   type RecordId,
   type RecordRef,
@@ -124,6 +127,14 @@ export abstract class BaseYjsDocumentService<TDoc extends InternalYjsDoc = Inter
     metadata: DocumentMetadata,
     schema: T,
   ) => Promise<DocumentRef<T>>;
+  abstract readonly searchDocuments: <T extends DocumentSchema>(
+    documentTypeName: string,
+    schema: T,
+    options?: {
+      documentName?: string;
+      limit?: number;
+    },
+  ) => Promise<ReadonlyArray<DocumentMetadata & { readonly id: DocumentId }>>;
 
   readonly createDocRef = <const T extends DocumentSchema>(
     id: DocumentId,
@@ -486,6 +497,20 @@ export abstract class BaseYjsDocumentService<TDoc extends InternalYjsDoc = Inter
     return Promise.resolve();
   };
 
+  readonly withTransaction = (
+    docRef: DocumentRef,
+    fn: () => void,
+    description?: EditDescription,
+  ): void => {
+    const internalDoc = this.documents.get(docRef.id);
+    invariant(
+      internalDoc != null,
+      `Cannot start transaction as document not found: ${docRef.id}`,
+    );
+
+    internalDoc.yDoc.transact(fn, description);
+  };
+
   onMetadataChange<T extends DocumentSchema>(
     docRef: DocumentRef<T>,
     callback: DocumentMetadataChangeCallback<T>,
@@ -520,6 +545,22 @@ export abstract class BaseYjsDocumentService<TDoc extends InternalYjsDoc = Inter
     };
   }
 
+  abstract onActivity<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    callback: (docRef: DocumentRef<T>, event: ActivityEvent) => void,
+  ): Unsubscribe;
+
+  abstract onPresence<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    callback: (docRef: DocumentRef<T>, event: PresenceEvent) => void,
+  ): Unsubscribe;
+
+  abstract updateCustomPresence<M extends Model>(
+    docRef: DocumentRef,
+    model: M,
+    eventData: ModelData<M>,
+  ): void;
+
   readonly onStateChange = <T extends DocumentSchema>(
     docRef: DocumentRef<T>,
     callback: DocumentStateChangeCallback<T>,

package/src/service/InMemoryDocumentService.ts

@@ -14,13 +14,18 @@
  * limitations under the License.
  */
 
-import type { ModuleConfigTuple, PackAppInternal } from "@palantir/pack.core";
+import type { ModuleConfigTuple, PackAppInternal, Unsubscribe } from "@palantir/pack.core";
 import { generateId } from "@palantir/pack.core";
 import type {
+  ActivityEvent,
   DocumentId,
   DocumentMetadata,
   DocumentRef,
   DocumentSchema,
+  Model,
+  ModelData,
+  PresenceEvent,
+  PresenceSubscriptionOptions,
 } from "@palantir/pack.document-schema.model-types";
 import type * as Y from "yjs";
 import { createDocumentServiceConfig } from "../DocumentServiceModule.js";
@@ -99,6 +104,36 @@ class InMemoryDocumentService extends BaseYjsDocumentService {
     return Promise.resolve(docRef);
   };
 
+  readonly searchDocuments = <T extends DocumentSchema>(
+    documentTypeName: string,
+    schema: T,
+    options?: {
+      documentName?: string;
+      limit?: number;
+    },
+  ): Promise<ReadonlyArray<DocumentMetadata & { readonly id: DocumentId }>> => {
+    const results: Array<DocumentMetadata & { readonly id: DocumentId }> = [];
+    const { documentName, limit } = options ?? {};
+
+    for (const [docId, internalDoc] of this.documents.entries()) {
+      if (internalDoc.metadata?.documentTypeName === documentTypeName) {
+        if (documentName && !internalDoc.metadata.name.includes(documentName)) {
+          continue;
+        }
+        results.push({
+          ...internalDoc.metadata,
+          id: docId as DocumentId,
+        });
+
+        if (limit && results.length >= limit) {
+          break;
+        }
+      }
+    }
+
+    return Promise.resolve(results);
+  };
+
   // Lifecycle method implementations
   protected onMetadataSubscriptionOpened(
     internalDoc: InternalYjsDoc,
@@ -155,6 +190,28 @@ class InMemoryDocumentService extends BaseYjsDocumentService {
   ): void {
     // No cleanup needed for in-memory service
   }
+
+  onActivity<T extends DocumentSchema>(
+    _docRef: DocumentRef<T>,
+    _callback: (docRef: DocumentRef<T>, event: ActivityEvent) => void,
+  ): Unsubscribe {
+    return () => {};
+  }
+
+  onPresence<T extends DocumentSchema>(
+    _docRef: DocumentRef<T>,
+    _callback: (docRef: DocumentRef<T>, event: PresenceEvent) => void,
+    _options?: PresenceSubscriptionOptions,
+  ): Unsubscribe {
+    return () => {};
+  }
+
+  updateCustomPresence<M extends Model>(
+    _docRef: DocumentRef,
+    _model: M,
+    _eventData: ModelData<M>,
+  ): void {
+  }
 }
 
 function generateDocumentId(): DocumentId {

package/src/types/DocumentRefImpl.ts

@@ -16,12 +16,17 @@
 
 import type { PackAppInternal } from "@palantir/pack.core";
 import type {
+  ActivityEvent,
   DocumentId,
   DocumentMetadata,
   DocumentRef,
   DocumentSchema,
   DocumentState,
+  EditDescription,
   Model,
+  ModelData,
+  PresenceEvent,
+  PresenceSubscriptionOptions,
   RecordCollectionRef,
   Unsubscribe,
 } from "@palantir/pack.document-schema.model-types";
@@ -39,8 +44,14 @@ const INVALID_DOC_REF: DocumentRef = Object.freeze(
     getRecords: () => {
       throw new Error("Invalid document reference");
     },
+    onActivity: () => () => {},
     onMetadataChange: () => () => {},
+    onPresence: () => () => {},
     onStateChange: () => () => {},
+    updateCustomPresence: () => {},
+    withTransaction: () => {
+      throw new Error("Invalid document reference");
+    },
   } as const,
 );
 
@@ -52,10 +63,30 @@ export const createDocRef = <const D extends DocumentSchema>(
   return new DocumentRefImpl(app, id, schema);
 };
 
+/**
+ * Get an invalid document reference. This is a stable reference that can be
+ * used to represent a non-existent or invalid document.
+ *
+ * Not to be confused with a valid reference to a non-existent document, an
+ * invalid reference is one that is not properly initialized. For example, code
+ * that initializes with an undefined or empty documentId might produce an
+ * invalid document reference rather than propagate nullish types.
+ *
+ * Most operations on an invalid reference are no-ops. For the rest, it is
+ * recommended to check for validity using {@link isValidDocRef} before
+ * performing operations.
+ */
 export function invalidDocRef<D extends DocumentSchema = DocumentSchema>(): DocumentRef<D> {
   return INVALID_DOC_REF as DocumentRef<D>;
 }
 
+/**
+ * Check if a document reference is an invalid reference.
+ * Not to be confused with a valid reference to a non-existent document, an invalid reference is one that is not properly initialized.
+ * For example, code that initializes with an undefined or empty documentId might produce an invalid document reference rather than
+ * propagate nullish types, as most operations on an invalid reference are no-ops. For the rest, it is recommended to check for
+ * validity using this function before performing operations.
+ */
 export function isValidDocRef<D extends DocumentSchema = DocumentSchema>(
   docRef: DocumentRef<D>,
 ): docRef is DocumentRef<D> {
@@ -84,15 +115,42 @@ class DocumentRefImpl<T extends DocumentSchema> implements DocumentRef<T> {
     return this.#stateModule.getCreateRecordCollectionRef(this, model);
   }
 
+  onActivity(
+    callback: (docRef: DocumentRef<T>, event: ActivityEvent) => void,
+  ): Unsubscribe {
+    return this.#stateModule.onActivity(this, callback);
+  }
+
   onMetadataChange(
     cb: (docRef: DocumentRef<T>, metadata: DocumentMetadata) => void,
   ): Unsubscribe {
     return this.#stateModule.onMetadataChange(this, cb);
   }
 
+  onPresence(
+    callback: (docRef: DocumentRef<T>, event: PresenceEvent) => void,
+    options?: PresenceSubscriptionOptions,
+  ): Unsubscribe {
+    return this.#stateModule.onPresence(this, callback, options);
+  }
+
   onStateChange(
     callback: (docRef: DocumentRef<T>) => void,
   ): Unsubscribe {
     return this.#stateModule.onStateChange(this, callback);
   }
+
+  updateCustomPresence<M extends Model = Model>(
+    model: M,
+    eventData: ModelData<M>,
+  ): void {
+    this.#stateModule.updateCustomPresence(this, model, eventData);
+  }
+
+  withTransaction(
+    fn: () => void,
+    description?: EditDescription,
+  ): void {
+    this.#stateModule.withTransaction(this, fn, description);
+  }
 }

package/src/types/DocumentService.ts

@@ -16,13 +16,17 @@
 
 import type { Unsubscribe } from "@palantir/pack.core";
 import type {
+  ActivityEvent,
   DocumentId,
   DocumentMetadata,
   DocumentRef,
   DocumentSchema,
   DocumentState,
+  EditDescription,
   Model,
   ModelData,
+  PresenceEvent,
+  PresenceSubscriptionOptions,
   RecordCollectionRef,
   RecordId,
   RecordRef,
@@ -83,6 +87,13 @@ export type RecordDeleteCallback<M extends Model = Model> = (
   record: RecordRef<M>,
 ) => void;
 
+/**
+ * Base interface for specific document service implementations.
+ * The DocumentService is responsible for persisting document state,
+ * metadata, and providing methods to subscribe and interact with documents.
+ *
+ * The main implementation communicates with the Foundry platform (see @palantir/pack.state.foundry).
+ */
 export interface DocumentService {
   readonly hasMetadataSubscriptions: boolean;
   readonly hasStateSubscriptions: boolean;
@@ -92,6 +103,15 @@ export interface DocumentService {
     schema: T,
   ) => Promise<DocumentRef<T>>;
 
+  readonly searchDocuments: <T extends DocumentSchema>(
+    documentTypeName: string,
+    schema: T,
+    options?: {
+      documentName?: string;
+      limit?: number;
+    },
+  ) => Promise<ReadonlyArray<DocumentMetadata & { readonly id: DocumentId }>>;
+
   readonly createDocRef: <const T extends DocumentSchema>(
     id: DocumentId,
     schema: T,
@@ -126,6 +146,12 @@ export interface DocumentService {
     partialState: Partial<ModelData<R>>,
   ) => Promise<void>;
 
+  readonly withTransaction: (
+    docRef: DocumentRef,
+    fn: () => void,
+    description?: EditDescription,
+  ) => void;
+
   // Collection methods
   readonly getRecord: <M extends Model>(
     collection: RecordCollectionRef<M>,
@@ -170,16 +196,33 @@ export interface DocumentService {
     callback: RecordCollectionChangeCallback<M>,
   ) => Unsubscribe;
 
+  readonly onActivity: <T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    callback: (docRef: DocumentRef<T>, event: ActivityEvent) => void,
+  ) => Unsubscribe;
+
   readonly onMetadataChange: <T extends DocumentSchema>(
     docRef: DocumentRef<T>,
     callback: DocumentMetadataChangeCallback<T>,
   ) => Unsubscribe;
 
+  readonly onPresence: <T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    callback: (docRef: DocumentRef<T>, event: PresenceEvent) => void,
+    options?: PresenceSubscriptionOptions,
+  ) => Unsubscribe;
+
   readonly onStateChange: <T extends DocumentSchema>(
     docRef: DocumentRef<T>,
     callback: DocumentStateChangeCallback<T>,
   ) => Unsubscribe;
 
+  readonly updateCustomPresence: <M extends Model>(
+    docRef: DocumentRef,
+    model: M,
+    eventData: ModelData<M>,
+  ) => void;
+
   readonly onRecordChanged: <M extends Model>(
     record: RecordRef<M>,
     callback: RecordChangeCallback<M>,

package/src/types/RecordCollectionRefImpl.ts

@@ -54,10 +54,33 @@ export const createRecordCollectionRef = <const M extends Model>(
   return new RecordCollectionRefImpl(documentService, docRef, model);
 };
 
+/**
+ * Get an invalid record collection reference. This is a stable reference that
+ * can be used to represent an invalid record collection.
+ *
+ * Not to be confused with a valid reference to a non-existent record
+ * collection, an invalid reference is one that is not properly initialized. For
+ * example, code that initializes with an undefined or empty model might produce
+ * an invalid record collection reference rather than propagate nullish types.
+ *
+ * Most operations on an invalid reference are no-ops. For the rest, it is
+ * recommended to check for validity using {@link isValidRecordCollectionRef}
+ * before performing operations.
+ */
 export function invalidRecordCollectionRef<M extends Model = Model>(): RecordCollectionRef<M> {
   return INVALID_RECORD_COLLECTION_REF as RecordCollectionRef<M>;
 }
 
+/**
+ * Check if a record collection reference is a valid reference.
+ *
+ * Not to be confused with a valid reference to a non-existent record
+ * collection, an invalid reference is one that is not properly initialized.
+ *
+ * Most operations on an invalid reference are no-ops. For the rest, it is
+ * recommended to check for validity using this function before performing
+ * operations.
+ */
 export function isValidRecordCollectionRef<M extends Model = Model>(
   collectionRef: RecordCollectionRef<M>,
 ): collectionRef is RecordCollectionRef<M> {

package/src/types/RecordRefImpl.ts

@@ -49,10 +49,35 @@ export const createRecordRef = <const M extends Model>(
   return new RecordRefImpl(documentService, docRef, id, model);
 };
 
+/**
+ * Get an invalid record reference. This is a stable reference that can be used
+ * to represent an invalid record.
+ *
+ * Not to be confused with a valid reference to a non-existent record, an
+ * invalid reference is one that is not properly initialized. For example, code
+ * that initializes with an undefined or empty recordId might produce an
+ * invalid record reference rather than propagate nullish types.
+ *
+ * Most operations on an invalid reference are no-ops. For the rest, it is
+ * recommended to check for validity using {@link isValidRecordRef} before
+ * performing operations.
+ */
 export function invalidRecordRef<M extends Model = Model>(): RecordRef<M> {
   return INVALID_RECORD_REF as RecordRef<M>;
 }
 
+/**
+ * Check if a record reference is a valid reference.
+ *
+ * Not to be confused with a valid reference to a non-existent record, an
+ * invalid reference is one that is not properly initialized.
+ *
+ * For example, code that initializes with an undefined or empty recordId might
+ * produce an invalid record reference rather than propagate nullish types, as
+ * most operations on an invalid reference are no-ops. For the rest, it is
+ * recommended to check for validity using this function before performing
+ * operations.
+ */
 export function isValidRecordRef<M extends Model = Model>(
   recordRef: RecordRef<M>,
 ): recordRef is RecordRef<M> {

package/src/types/StateModule.ts

@@ -21,13 +21,17 @@ import {
   type Unsubscribe,
 } from "@palantir/pack.core";
 import type {
+  ActivityEvent,
   DocumentId,
   DocumentMetadata,
   DocumentRef,
   DocumentSchema,
   DocumentState,
+  EditDescription,
   Model,
   ModelData,
+  PresenceEvent,
+  PresenceSubscriptionOptions,
   RecordCollectionRef,
   RecordId,
   RecordRef,
@@ -69,20 +73,46 @@ export interface StateModule {
     schema: T,
   ) => Promise<DocumentRef<T>>;
 
+  readonly searchDocuments: <T extends DocumentSchema>(
+    documentTypeName: string,
+    schema: T,
+    options?: {
+      documentName?: string;
+      limit?: number;
+    },
+  ) => Promise<ReadonlyArray<DocumentMetadata & { readonly id: DocumentId }>>;
+
   readonly getDocumentSnapshot: <T extends DocumentSchema>(
     docRef: DocumentRef<T>,
   ) => Promise<DocumentState<T>>;
 
+  readonly onActivity: <T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    callback: (docRef: DocumentRef<T>, event: ActivityEvent) => void,
+  ) => Unsubscribe;
+
   readonly onMetadataChange: <T extends DocumentSchema>(
     docRef: DocumentRef<T>,
     cb: (docRef: DocumentRef<T>, metadata: DocumentMetadata) => void,
   ) => Unsubscribe;
 
+  readonly onPresence: <T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    callback: (docRef: DocumentRef<T>, event: PresenceEvent) => void,
+    options?: PresenceSubscriptionOptions,
+  ) => Unsubscribe;
+
   readonly onStateChange: <T extends DocumentSchema>(
     docRef: DocumentRef<T>,
     cb: (docRef: DocumentRef<T>) => void,
   ) => Unsubscribe;
 
+  readonly updateCustomPresence: <M extends Model>(
+    docRef: DocumentRef,
+    model: M,
+    eventData: ModelData<M>,
+  ) => void;
+
   readonly getRecordSnapshot: <R extends Model>(
     recordRef: RecordRef<R>,
   ) => Promise<ModelData<R>>;
@@ -112,6 +142,12 @@ export interface StateModule {
     partialState: Partial<ModelData<R>>,
   ) => Promise<void>;
 
+  readonly withTransaction: (
+    docRef: DocumentRef,
+    fn: () => void,
+    description?: EditDescription,
+  ) => void;
+
   readonly onRecordChanged: <M extends Model>(
     record: RecordRef<M>,
     callback: RecordChangeCallback<M>,
@@ -172,12 +208,30 @@ export class StateModuleImpl implements StateModule {
     return this.documentService.createDocument(metadata, schema);
   }
 
+  async searchDocuments<T extends DocumentSchema>(
+    documentTypeName: string,
+    schema: T,
+    options?: {
+      documentName?: string;
+      limit?: number;
+    },
+  ): Promise<ReadonlyArray<DocumentMetadata & { readonly id: DocumentId }>> {
+    return this.documentService.searchDocuments(documentTypeName, schema, options);
+  }
+
   async getDocumentSnapshot<T extends DocumentSchema>(
     docRef: DocumentRef<T>,
   ): Promise<DocumentState<T>> {
     return this.documentService.getDocumentSnapshot(docRef);
   }
 
+  onActivity<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    callback: (docRef: DocumentRef<T>, event: ActivityEvent) => void,
+  ): Unsubscribe {
+    return this.documentService.onActivity(docRef, callback);
+  }
+
   onMetadataChange<T extends DocumentSchema>(
     docRef: DocumentRef<T>,
     cb: (doc: DocumentRef<T>, metadata: DocumentMetadata) => void,
@@ -185,6 +239,14 @@ export class StateModuleImpl implements StateModule {
     return this.documentService.onMetadataChange(docRef, cb);
   }
 
+  onPresence<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    callback: (docRef: DocumentRef<T>, event: PresenceEvent) => void,
+    options?: PresenceSubscriptionOptions,
+  ): Unsubscribe {
+    return this.documentService.onPresence(docRef, callback, options);
+  }
+
   onStateChange<T extends DocumentSchema>(
     docRef: DocumentRef<T>,
     cb: (docRef: DocumentRef<T>) => void,
@@ -192,6 +254,14 @@ export class StateModuleImpl implements StateModule {
     return this.documentService.onStateChange(docRef, cb);
   }
 
+  updateCustomPresence<M extends Model>(
+    docRef: DocumentRef,
+    model: M,
+    eventData: ModelData<M>,
+  ): void {
+    this.documentService.updateCustomPresence(docRef, model, eventData);
+  }
+
   async getRecordSnapshot<R extends Model>(
     recordRef: RecordRef<R>,
   ): Promise<ModelData<R>> {
@@ -212,6 +282,14 @@ export class StateModuleImpl implements StateModule {
     return this.documentService.updateRecord(recordRef, partialState);
   }
 
+  withTransaction(
+    docRef: DocumentRef,
+    fn: () => void,
+    description?: EditDescription,
+  ): void {
+    this.documentService.withTransaction(docRef, fn, description);
+  }
+
   // Collection methods
   getCreateRecordCollectionRef<M extends Model>(
     docRef: DocumentRef,