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

package/build/cjs/index.d.cts

@@ -1,5 +1,5 @@
 import { Unsubscribe, PackAppInternal, ModuleConfigTuple } from '@palantir/pack.core';
-import { DocumentSchema, DocumentMetadata, DocumentRef, DocumentId, Model, RecordCollectionRef, RecordId, RecordRef, DocumentState, ModelData } from '@palantir/pack.document-schema.model-types';
+import { DocumentSchema, DocumentMetadata, DocumentRef, DocumentId, Model, RecordCollectionRef, RecordId, RecordRef, DocumentState, ModelData, EditDescription, ActivityEvent, PresenceEvent, PresenceSubscriptionOptions } from '@palantir/pack.document-schema.model-types';
 import { Logger } from '@osdk/api';
 import * as Y from 'yjs';
 
@@ -34,10 +34,23 @@ type DocumentStateChangeCallback<T extends DocumentSchema = DocumentSchema> = (d
 type RecordCollectionChangeCallback<M extends Model = Model> = (items: readonly RecordRef<M>[]) => void;
 type RecordChangeCallback<M extends Model = Model> = (snapshot: ModelData<M>, record: RecordRef<M>) => void;
 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).
+ */
 interface DocumentService {
     readonly hasMetadataSubscriptions: boolean;
     readonly hasStateSubscriptions: boolean;
     readonly createDocument: <T extends DocumentSchema>(metadata: DocumentMetadata, 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) => DocumentRef<T>;
     readonly getCreateRecordCollectionRef: <const M extends Model>(docRef: DocumentRef, model: M) => RecordCollectionRef<M>;
     readonly getCreateRecordRef: <const M extends Model>(docRef: DocumentRef, id: RecordId, model: M) => RecordRef<M>;
@@ -45,6 +58,7 @@ interface DocumentService {
     readonly getRecordSnapshot: <R extends Model>(record: RecordRef<R>) => Promise<ModelData<R>>;
     readonly setRecord: <R extends Model>(record: RecordRef<R>, state: ModelData<R>) => Promise<void>;
     readonly updateRecord: <R extends Model>(record: RecordRef<R>, partialState: Partial<ModelData<R>>) => Promise<void>;
+    readonly withTransaction: (docRef: DocumentRef, fn: () => void, description?: EditDescription) => void;
     readonly getRecord: <M extends Model>(collection: RecordCollectionRef<M>, id: RecordId) => RecordRef<M> | undefined;
     readonly hasRecord: <M extends Model>(collection: RecordCollectionRef<M>, id: RecordId) => boolean;
     readonly setCollectionRecord: <M extends Model>(collection: RecordCollectionRef<M>, id: RecordId, state: ModelData<M>) => Promise<void>;
@@ -54,8 +68,11 @@ interface DocumentService {
     readonly onCollectionItemsAdded: <M extends Model>(collection: RecordCollectionRef<M>, callback: RecordCollectionChangeCallback<M>) => Unsubscribe;
     readonly onCollectionItemsChanged: <M extends Model>(collection: RecordCollectionRef<M>, callback: RecordCollectionChangeCallback<M>) => Unsubscribe;
     readonly onCollectionItemsDeleted: <M extends Model>(collection: RecordCollectionRef<M>, 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>) => Unsubscribe;
     readonly onRecordDeleted: <M extends Model>(record: RecordRef<M>, callback: RecordDeleteCallback<M>) => Unsubscribe;
     readonly getDocumentStatus: <T extends DocumentSchema>(docRef: DocumentRef<T>) => DocumentStatus;
@@ -123,6 +140,12 @@ declare abstract class BaseYjsDocumentService<TDoc extends InternalYjsDoc = Inte
     abstract get hasMetadataSubscriptions(): boolean;
     abstract get hasStateSubscriptions(): boolean;
     abstract readonly createDocument: <T extends DocumentSchema>(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, schema: T) => DocumentRef<T>;
     readonly getCreateRecordCollectionRef: <const M extends Model>(docRef: DocumentRef, model: M) => RecordCollectionRef<M>;
     readonly getCreateRecordRef: <const M extends Model>(docRef: DocumentRef, id: RecordId, model: M) => RecordRef<M>;
@@ -190,7 +213,11 @@ declare abstract class BaseYjsDocumentService<TDoc extends InternalYjsDoc = Inte
     protected getRecordSnapshotInternal<M extends Model>(internalDoc: TDoc, recordRef: RecordRef<M>): ModelData<M>;
     readonly setRecord: <R extends Model>(recordRef: RecordRef<R>, state: ModelData<R>) => Promise<void>;
     readonly updateRecord: <R extends Model>(recordRef: RecordRef<R>, partialState: Partial<ModelData<R>>) => Promise<void>;
+    readonly withTransaction: (docRef: DocumentRef, fn: () => void, description?: EditDescription) => void;
     onMetadataChange<T extends DocumentSchema>(docRef: DocumentRef<T>, callback: DocumentMetadataChangeCallback<T>): Unsubscribe;
+    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>) => Unsubscribe;
     protected getDocumentRef(docId: DocumentId): DocumentRef | null;
     protected notifyMetadataSubscribers(internalDoc: TDoc, docRef: DocumentRef, metadata: DocumentMetadata): void;
@@ -231,15 +258,83 @@ interface InMemoryDocumentServiceOptions {
 declare function createInMemoryDocumentServiceConfig({ autoCreateDocuments }?: InMemoryDocumentServiceOptions): ModuleConfigTuple<DocumentService>;
 
 declare const createDocRef: <const D extends DocumentSchema>(app: PackAppInternal, id: DocumentId, schema: D) => DocumentRef<D>;
+/**
+ * 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.
+ */
 declare function invalidDocRef<D extends DocumentSchema = DocumentSchema>(): 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.
+ */
 declare function isValidDocRef<D extends DocumentSchema = DocumentSchema>(docRef: DocumentRef<D>): docRef is DocumentRef<D>;
 
 declare const createRecordCollectionRef: <const M extends Model>(documentService: DocumentService, docRef: DocumentRef, model: M) => RecordCollectionRef<M>;
+/**
+ * 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.
+ */
 declare function invalidRecordCollectionRef<M extends Model = Model>(): 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.
+ */
 declare function isValidRecordCollectionRef<M extends Model = Model>(collectionRef: RecordCollectionRef<M>): collectionRef is RecordCollectionRef<M>;
 
 declare const createRecordRef: <const M extends Model>(documentService: DocumentService, docRef: DocumentRef, id: RecordId, model: M) => RecordRef<M>;
+/**
+ * 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.
+ */
 declare function invalidRecordRef<M extends Model = Model>(): 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.
+ */
 declare function isValidRecordRef<M extends Model = Model>(recordRef: RecordRef<M>): recordRef is RecordRef<M>;
 
 declare const STATE_MODULE_ACCESSOR = "state";
@@ -250,15 +345,25 @@ interface StateModule {
     readonly createDocRef: <const T extends DocumentSchema>(id: DocumentId, schema: T) => DocumentRef<T>;
     readonly createRecordRef: <const M extends Model>(docRef: DocumentRef, id: RecordId, model: M) => RecordRef<M>;
     readonly createDocument: <T extends DocumentSchema>(metadata: DocumentMetadata, 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>>;
     readonly onCollectionItemsAdded: <M extends Model>(collection: RecordCollectionRef<M>, callback: RecordCollectionChangeCallback<M>) => Unsubscribe;
     readonly onCollectionItemsChanged: <M extends Model>(collection: RecordCollectionRef<M>, callback: RecordCollectionChangeCallback<M>) => Unsubscribe;
     readonly onCollectionItemsDeleted: <M extends Model>(collection: RecordCollectionRef<M>, callback: RecordCollectionChangeCallback<M>) => Unsubscribe;
     readonly setRecord: <R extends Model>(recordRef: RecordRef<R>, state: ModelData<R>) => Promise<void>;
     readonly updateRecord: <R extends Model>(recordRef: RecordRef<R>, 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>) => Unsubscribe;
     readonly onRecordDeleted: <M extends Model>(record: RecordRef<M>, callback: RecordDeleteCallback<M>) => Unsubscribe;
     readonly deleteRecord: <M extends Model>(record: RecordRef<M>) => Promise<void>;

package/build/esm/index.js

@@ -46,15 +46,27 @@ var StateModuleImpl = class {
   async createDocument(metadata, schema) {
     return this.documentService.createDocument(metadata, schema);
   }
+  async searchDocuments(documentTypeName, schema, options) {
+    return this.documentService.searchDocuments(documentTypeName, schema, options);
+  }
   async getDocumentSnapshot(docRef) {
     return this.documentService.getDocumentSnapshot(docRef);
   }
+  onActivity(docRef, callback) {
+    return this.documentService.onActivity(docRef, callback);
+  }
   onMetadataChange(docRef, cb) {
     return this.documentService.onMetadataChange(docRef, cb);
   }
+  onPresence(docRef, callback, options) {
+    return this.documentService.onPresence(docRef, callback, options);
+  }
   onStateChange(docRef, cb) {
     return this.documentService.onStateChange(docRef, cb);
   }
+  updateCustomPresence(docRef, model, eventData) {
+    this.documentService.updateCustomPresence(docRef, model, eventData);
+  }
   async getRecordSnapshot(recordRef) {
     return this.documentService.getRecordSnapshot(recordRef);
   }
@@ -64,6 +76,9 @@ var StateModuleImpl = class {
   async updateRecord(recordRef, partialState) {
     return this.documentService.updateRecord(recordRef, partialState);
   }
+  withTransaction(docRef, fn, description) {
+    this.documentService.withTransaction(docRef, fn, description);
+  }
   // Collection methods
   getCreateRecordCollectionRef(docRef, model) {
     return this.documentService.getCreateRecordCollectionRef(docRef, model);
@@ -131,9 +146,18 @@ var INVALID_DOC_REF = Object.freeze({
   getRecords: () => {
     throw new Error("Invalid document reference");
   },
+  onActivity: () => () => {
+  },
   onMetadataChange: () => () => {
   },
+  onPresence: () => () => {
+  },
   onStateChange: () => () => {
+  },
+  updateCustomPresence: () => {
+  },
+  withTransaction: () => {
+    throw new Error("Invalid document reference");
   }
 });
 var createDocRef = (app, id, schema) => {
@@ -160,12 +184,24 @@ var DocumentRefImpl = class {
   getRecords(model) {
     return this.#stateModule.getCreateRecordCollectionRef(this, model);
   }
+  onActivity(callback) {
+    return this.#stateModule.onActivity(this, callback);
+  }
   onMetadataChange(cb) {
     return this.#stateModule.onMetadataChange(this, cb);
   }
+  onPresence(callback, options) {
+    return this.#stateModule.onPresence(this, callback, options);
+  }
   onStateChange(callback) {
     return this.#stateModule.onStateChange(this, callback);
   }
+  updateCustomPresence(model, eventData) {
+    this.#stateModule.updateCustomPresence(this, model, eventData);
+  }
+  withTransaction(fn, description) {
+    this.#stateModule.withTransaction(this, fn, description);
+  }
 };
 
 // src/types/DocumentService.ts
@@ -652,6 +688,11 @@ var BaseYjsDocumentService = class {
     this.onRecordSet?.(recordRef, partialState);
     return Promise.resolve();
   };
+  withTransaction = (docRef, fn, description) => {
+    const internalDoc = this.documents.get(docRef.id);
+    !(internalDoc != null) ? process.env.NODE_ENV !== "production" ? invariant(false, `Cannot start transaction as document not found: ${docRef.id}`) : invariant(false) : void 0;
+    internalDoc.yDoc.transact(fn, description);
+  };
   onMetadataChange(docRef, callback) {
     const {
       internalDoc,
@@ -1212,6 +1253,28 @@ var InMemoryDocumentService = class extends BaseYjsDocumentService {
     this.getCreateInternalDoc(docRef, metadata, yDoc);
     return Promise.resolve(docRef);
   };
+  searchDocuments = (documentTypeName, schema, options) => {
+    const results = [];
+    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
+        });
+        if (limit && results.length >= limit) {
+          break;
+        }
+      }
+    }
+    return Promise.resolve(results);
+  };
   // Lifecycle method implementations
   onMetadataSubscriptionOpened(internalDoc, docRef) {
     this.updateMetadataStatus(internalDoc, docRef, {
@@ -1247,6 +1310,16 @@ var InMemoryDocumentService = class extends BaseYjsDocumentService {
   }
   onDataSubscriptionClosed(_internalDoc, _docRef) {
   }
+  onActivity(_docRef, _callback) {
+    return () => {
+    };
+  }
+  onPresence(_docRef, _callback, _options) {
+    return () => {
+    };
+  }
+  updateCustomPresence(_docRef, _model, _eventData) {
+  }
 };
 function generateDocumentId() {
   return generateId();