@palantir/pack.state.core 0.2.2 → 0.3.0

package/build/cjs/index.d.cts

@@ -1,8 +1,14 @@
-import { Unsubscribe, PackAppInternal, ModuleConfigTuple } from '@palantir/pack.core';
-import { DocumentSchema, DocumentMetadata, DocumentRef, DocumentId, Model, RecordCollectionRef, RecordId, RecordRef, DocumentState, ModelData, EditDescription, ActivityEvent, PresenceEvent, PresenceSubscriptionOptions } from '@palantir/pack.document-schema.model-types';
+import { Unsubscribe, PackAppInternal, ModuleConfigTuple, PackApp } from '@palantir/pack.core';
+import { DocumentSecurity, DocumentSchema, DocumentRef, DocumentMetadata, 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';
 
+interface CreateDocumentMetadata {
+    readonly name: string;
+    readonly documentTypeName: string;
+    readonly security?: DocumentSecurity;
+}
+
 declare const DocumentLoadStatus: {
     readonly UNLOADED: "unloaded";
     readonly LOADING: "loading";
@@ -19,6 +25,11 @@ declare const DocumentLiveStatus: {
 type DocumentLiveStatus = typeof DocumentLiveStatus[keyof typeof DocumentLiveStatus];
 type DocumentSyncStatus = {
     readonly error?: unknown;
+    /**
+     * When true, indicates this is a demo/test service not connected to real Foundry.
+     * UI can use this to display a badge or indicator that data is local-only.
+     */
+    readonly isDemo?: boolean;
     readonly live: DocumentLiveStatus;
     readonly load: DocumentLoadStatus;
 };
@@ -34,6 +45,15 @@ 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;
+/**
+ * Result of a document search operation, including pagination information.
+ */
+interface SearchDocumentsResult {
+    readonly data: ReadonlyArray<DocumentMetadata & {
+        readonly id: DocumentId;
+    }>;
+    readonly nextPageToken?: string;
+}
 /**
  * Base interface for specific document service implementations.
  * The DocumentService is responsible for persisting document state,
@@ -44,13 +64,12 @@ type RecordDeleteCallback<M extends Model = Model> = (record: RecordRef<M>) => v
 interface DocumentService {
     readonly hasMetadataSubscriptions: boolean;
     readonly hasStateSubscriptions: boolean;
-    readonly createDocument: <T extends DocumentSchema>(metadata: DocumentMetadata, schema: T) => Promise<DocumentRef<T>>;
+    readonly createDocument: <T extends DocumentSchema>(metadata: CreateDocumentMetadata, 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;
-    }>>;
+        pageSize?: number;
+        pageToken?: string;
+    }) => Promise<SearchDocumentsResult>;
     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>;
@@ -126,6 +145,9 @@ interface InternalYjsDoc {
     readonly statusSubscribers: Set<DocumentStatusChangeCallback>;
     readonly yjsCollectionHandlers: Map<string, () => void>;
 }
+interface BaseYjsDocumentServiceOptions {
+    readonly isDemo?: boolean;
+}
 /**
  * Base class for document services that use Y.js for local state management.
  * Provides common Y.js operations for both in-memory and backend services.
@@ -136,20 +158,20 @@ declare abstract class BaseYjsDocumentService<TDoc extends InternalYjsDoc = Inte
     protected readonly app: PackAppInternal;
     protected readonly logger: Logger;
     protected readonly documents: Map<DocumentId, TDoc>;
-    constructor(app: PackAppInternal, logger: Logger);
+    protected readonly isDemo?: boolean;
+    constructor(app: PackAppInternal, logger: Logger, options?: BaseYjsDocumentServiceOptions);
     abstract get hasMetadataSubscriptions(): boolean;
     abstract get hasStateSubscriptions(): boolean;
-    abstract readonly createDocument: <T extends DocumentSchema>(metadata: DocumentMetadata, schema: T) => Promise<DocumentRef<T>>;
+    abstract readonly createDocument: <T extends DocumentSchema>(metadata: CreateDocumentMetadata, 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;
-    }>>;
+        pageSize?: number;
+        pageToken?: string;
+    }) => Promise<SearchDocumentsResult>;
     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>;
-    protected abstract createInternalDoc(ref: DocumentRef, metadata?: DocumentMetadata, yDoc?: Y.Doc): TDoc;
+    protected abstract createInternalDoc(ref: DocumentRef, metadata?: CreateDocumentMetadata, yDoc?: Y.Doc): TDoc;
     /**
      * Called when the first metadata subscription is opened for a document.
      * Implementation must:
@@ -203,7 +225,7 @@ declare abstract class BaseYjsDocumentService<TDoc extends InternalYjsDoc = Inte
     /**
      * Get existing internal doc or create one with placeholder metadata for lazy initialization
      */
-    protected getCreateInternalDoc<T extends DocumentSchema>(ref: DocumentRef<T>, metadata?: DocumentMetadata, initialYDoc?: Y.Doc): {
+    protected getCreateInternalDoc<T extends DocumentSchema>(ref: DocumentRef<T>, metadata?: CreateDocumentMetadata, initialYDoc?: Y.Doc): {
         internalDocRef: DocumentRef<T>;
         internalDoc: TDoc;
         wasExisting: boolean;
@@ -344,13 +366,12 @@ type WithStateModule<T> = T & {
 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 createDocument: <T extends DocumentSchema>(metadata: CreateDocumentMetadata, 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;
-    }>>;
+        pageSize?: number;
+        pageToken?: string;
+    }) => Promise<SearchDocumentsResult>;
     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;
@@ -372,6 +393,6 @@ interface StateModule {
     readonly waitForMetadataLoad: <T extends DocumentSchema>(docRef: DocumentRef<T>) => Promise<void>;
     readonly waitForDataLoad: <T extends DocumentSchema>(docRef: DocumentRef<T>) => Promise<void>;
 }
-declare function getStateModule(app: PackAppInternal): StateModule;
+declare function getStateModule(app: PackApp | PackAppInternal): StateModule;
 
-export { BaseYjsDocumentService, DocumentLiveStatus, DocumentLoadStatus, type DocumentMetadataChangeCallback, type DocumentService, type DocumentStateChangeCallback, type DocumentStatus, type DocumentStatusChangeCallback, type DocumentSyncStatus, type InternalYjsDoc, STATE_MODULE_ACCESSOR, type StateModule, type WithDocumentServiceInit, type WithStateModule, createDocRef, createDocumentServiceConfig, createInMemoryDocumentServiceConfig, createRecordCollectionRef, createRecordRef, getDocumentService, getStateModule, invalidDocRef, invalidRecordCollectionRef, invalidRecordRef, isValidDocRef, isValidRecordCollectionRef, isValidRecordRef };
+export { BaseYjsDocumentService, type BaseYjsDocumentServiceOptions, type CreateDocumentMetadata, DocumentLiveStatus, DocumentLoadStatus, type DocumentMetadataChangeCallback, type DocumentService, type DocumentStateChangeCallback, type DocumentStatus, type DocumentStatusChangeCallback, type DocumentSyncStatus, type InternalYjsDoc, STATE_MODULE_ACCESSOR, type SearchDocumentsResult, type StateModule, type WithDocumentServiceInit, type WithStateModule, createDocRef, createDocumentServiceConfig, createInMemoryDocumentServiceConfig, createRecordCollectionRef, createRecordRef, getDocumentService, getStateModule, invalidDocRef, invalidRecordCollectionRef, invalidRecordRef, isValidDocRef, isValidRecordCollectionRef, isValidRecordRef };

package/build/esm/index.js

@@ -466,9 +466,11 @@ function yMapToState(yMap) {
 // src/service/BaseYjsDocumentService.ts
 var BaseYjsDocumentService = class {
   documents = /* @__PURE__ */ new Map();
-  constructor(app, logger) {
+  isDemo;
+  constructor(app, logger, options) {
     this.app = app;
     this.logger = logger;
+    this.isDemo = options?.isDemo;
   }
   createDocRef = (id, schema) => {
     const temporaryRef = createDocRef(this.app, id, schema);
@@ -588,6 +590,7 @@ var BaseYjsDocumentService = class {
   updateMetadataStatus(internalDoc, docRef, update) {
     if (update.load != null || update.live != null) {
       internalDoc.metadataStatus = {
+        isDemo: this.isDemo,
         load: update.load ?? internalDoc.metadataStatus.load,
         live: update.live ?? internalDoc.metadataStatus.live
       };
@@ -602,6 +605,7 @@ var BaseYjsDocumentService = class {
   updateDataStatus(internalDoc, docRef, update) {
     if (update.load != null || update.live != null) {
       internalDoc.dataStatus = {
+        isDemo: this.isDemo,
         load: update.load ?? internalDoc.dataStatus.load,
         live: update.live ?? internalDoc.dataStatus.live
       };
@@ -1259,7 +1263,7 @@ var InMemoryDocumentService = class extends BaseYjsDocumentService {
     const results = [];
     const {
       documentName,
-      limit
+      pageSize
     } = options ?? {};
     for (const [docId, internalDoc] of this.documents.entries()) {
       if (internalDoc.metadata?.documentTypeName === documentTypeName) {
@@ -1270,12 +1274,15 @@ var InMemoryDocumentService = class extends BaseYjsDocumentService {
           ...internalDoc.metadata,
           id: docId
         });
-        if (limit && results.length >= limit) {
+        if (pageSize && results.length >= pageSize) {
           break;
         }
       }
     }
-    return Promise.resolve(results);
+    return Promise.resolve({
+      data: results,
+      nextPageToken: void 0
+    });
   };
   // Lifecycle method implementations
   onMetadataSubscriptionOpened(internalDoc, docRef) {