@palantir/pack.state.core 0.0.1-beta.1

package/build/types/types/RecordCollectionRefImpl.d.ts

@@ -0,0 +1,5 @@
+import type { DocumentRef, Model, RecordCollectionRef } from "@palantir/pack.document-schema.model-types";
+import type { DocumentService } from "./DocumentService.js";
+export declare const createRecordCollectionRef: <const M extends Model>(documentService: DocumentService, docRef: DocumentRef, model: M) => RecordCollectionRef<M>;
+export declare function invalidRecordCollectionRef<M extends Model = Model>(): RecordCollectionRef<M>;
+export declare function isValidRecordCollectionRef<M extends Model = Model>(collectionRef: RecordCollectionRef<M>): collectionRef is RecordCollectionRef<M>;

package/build/types/types/RecordCollectionRefImpl.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAgBA,cACE,aACA,OAEA,2BAIK;AAGP,cAAc,uBAAuB;AAqBrC,OAAO,cAAM,kCAAmC,UAAU,OACxD,iBAAiB,iBACjB,QAAQ,aACR,OAAO,MACN,oBAAoB;AAIvB,OAAO,iBAAS,2BAA2B,UAAU,QAAQ,UAAU,oBAAoB;AAI3F,OAAO,iBAAS,2BAA2B,UAAU,QAAQ,OAC3D,eAAe,oBAAoB,KAClC,iBAAiB,oBAAoB","names":[],"sources":["../../../src/types/RecordCollectionRefImpl.ts"],"version":3,"file":"RecordCollectionRefImpl.d.ts"}

package/build/types/types/RecordRefImpl.d.ts

@@ -0,0 +1,5 @@
+import type { DocumentRef, Model, RecordId, RecordRef } from "@palantir/pack.document-schema.model-types";
+import type { DocumentService } from "./DocumentService.js";
+export declare const createRecordRef: <const M extends Model>(documentService: DocumentService, docRef: DocumentRef, id: RecordId, model: M) => RecordRef<M>;
+export declare function invalidRecordRef<M extends Model = Model>(): RecordRef<M>;
+export declare function isValidRecordRef<M extends Model = Model>(recordRef: RecordRef<M>): recordRef is RecordRef<M>;

package/build/types/types/RecordRefImpl.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAgBA,cACE,aACA,OAEA,UACA,iBAEK;AAGP,cAAc,uBAAuB;AAgBrC,OAAO,cAAM,wBAAyB,UAAU,OAC9C,iBAAiB,iBACjB,QAAQ,aACR,IAAI,UACJ,OAAO,MACN,UAAU;AAIb,OAAO,iBAAS,iBAAiB,UAAU,QAAQ,UAAU,UAAU;AAIvE,OAAO,iBAAS,iBAAiB,UAAU,QAAQ,OACjD,WAAW,UAAU,KACpB,aAAa,UAAU","names":[],"sources":["../../../src/types/RecordRefImpl.ts"],"version":3,"file":"RecordRefImpl.d.ts"}

package/build/types/types/StateModule.d.ts

@@ -0,0 +1,59 @@
+import { type ModuleKey, type PackAppInternal, type Unsubscribe } from "@palantir/pack.core";
+import type { DocumentId, DocumentMetadata, DocumentRef, DocumentSchema, DocumentState, Model, ModelData, RecordCollectionRef, RecordId, RecordRef } from "@palantir/pack.document-schema.model-types";
+import type { DocumentService, RecordChangeCallback, RecordCollectionChangeCallback, RecordDeleteCallback } from "./DocumentService.js";
+export declare const STATE_MODULE_ACCESSOR = "state";
+export declare const STATE_MODULE_KEY: ModuleKey<StateModuleImpl>;
+export type WithStateModule<T> = T & {
+	readonly [STATE_MODULE_ACCESSOR]: StateModule;
+};
+export 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 getDocumentSnapshot: <T extends DocumentSchema>(docRef: DocumentRef<T>) => Promise<DocumentState<T>>;
+	readonly onMetadataChange: <T extends DocumentSchema>(docRef: DocumentRef<T>, cb: (docRef: DocumentRef<T>, metadata: DocumentMetadata) => void) => Unsubscribe;
+	readonly onStateChange: <T extends DocumentSchema>(docRef: DocumentRef<T>, cb: (docRef: DocumentRef<T>) => void) => Unsubscribe;
+	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 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>;
+	readonly getDocumentStatus: <T extends DocumentSchema>(docRef: DocumentRef<T>) => ReturnType<DocumentService["getDocumentStatus"]>;
+	readonly onStatusChange: <T extends DocumentSchema>(docRef: DocumentRef<T>, callback: Parameters<DocumentService["onStatusChange"]>[1]) => Unsubscribe;
+	readonly waitForMetadataLoad: <T extends DocumentSchema>(docRef: DocumentRef<T>) => Promise<void>;
+	readonly waitForDataLoad: <T extends DocumentSchema>(docRef: DocumentRef<T>) => Promise<void>;
+}
+export declare class StateModuleImpl implements StateModule {
+	private readonly documentService;
+	constructor(documentService: DocumentService);
+	createDocRef<const T extends DocumentSchema>(id: DocumentId, schema: T): DocumentRef<T>;
+	createRecordRef<const M extends Model>(docRef: DocumentRef, id: RecordId, model: M): RecordRef<M>;
+	createDocument<T extends DocumentSchema>(metadata: DocumentMetadata, schema: T): Promise<DocumentRef<T>>;
+	getDocumentSnapshot<T extends DocumentSchema>(docRef: DocumentRef<T>): Promise<DocumentState<T>>;
+	onMetadataChange<T extends DocumentSchema>(docRef: DocumentRef<T>, cb: (doc: DocumentRef<T>, metadata: DocumentMetadata) => void): Unsubscribe;
+	onStateChange<T extends DocumentSchema>(docRef: DocumentRef<T>, cb: (docRef: DocumentRef<T>) => void): Unsubscribe;
+	getRecordSnapshot<R extends Model>(recordRef: RecordRef<R>): Promise<ModelData<R>>;
+	setRecord<R extends Model>(recordRef: RecordRef<R>, state: ModelData<R>): Promise<void>;
+	updateRecord<R extends Model>(recordRef: RecordRef<R>, partialState: Partial<ModelData<R>>): Promise<void>;
+	getCreateRecordCollectionRef<M extends Model>(docRef: DocumentRef, model: M): RecordCollectionRef<M>;
+	getRecord<M extends Model>(collection: RecordCollectionRef<M>, id: RecordId): RecordRef<M> | undefined;
+	hasRecord<M extends Model>(collection: RecordCollectionRef<M>, id: RecordId): boolean;
+	setCollectionRecord<M extends Model>(collection: RecordCollectionRef<M>, id: RecordId, state: ModelData<M>): Promise<void>;
+	getCollectionSize<M extends Model>(collection: RecordCollectionRef<M>): number;
+	getCollectionRecords<M extends Model>(collection: RecordCollectionRef<M>): RecordRef<M>[];
+	onRecordChanged<M extends Model>(record: RecordRef<M>, callback: RecordChangeCallback<M>): Unsubscribe;
+	onRecordDeleted<M extends Model>(record: RecordRef<M>, callback: RecordDeleteCallback<M>): Unsubscribe;
+	onCollectionItemsAdded<M extends Model>(collection: RecordCollectionRef<M>, callback: RecordCollectionChangeCallback<M>): Unsubscribe;
+	onCollectionItemsChanged<M extends Model>(collection: RecordCollectionRef<M>, callback: RecordCollectionChangeCallback<M>): Unsubscribe;
+	onCollectionItemsDeleted<M extends Model>(collection: RecordCollectionRef<M>, callback: RecordCollectionChangeCallback<M>): Unsubscribe;
+	getDocumentStatus<T extends DocumentSchema>(docRef: DocumentRef<T>): ReturnType<DocumentService["getDocumentStatus"]>;
+	onStatusChange<T extends DocumentSchema>(docRef: DocumentRef<T>, callback: Parameters<DocumentService["onStatusChange"]>[1]): Unsubscribe;
+	waitForMetadataLoad<T extends DocumentSchema>(docRef: DocumentRef<T>): Promise<void>;
+	waitForDataLoad<T extends DocumentSchema>(docRef: DocumentRef<T>): Promise<void>;
+	deleteRecord<M extends Model>(record: RecordRef<M>): Promise<void>;
+}
+export declare function getStateModule(app: PackAppInternal): StateModule;

package/build/types/types/StateModule.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"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","names":["STATE_MODULE_KEY: ModuleKey<StateModuleImpl>","documentService: DocumentService"],"sources":["../../../src/types/StateModule.ts"],"version":3,"file":"StateModule.d.ts"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@palantir/pack.state.core",
+  "version": "0.0.1-beta.1",
+  "description": "PACK State logic and utilities",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/palantir/pack.git"
+  },
+  "exports": {
+    ".": {
+      "browser": "./build/browser/index.js",
+      "import": {
+        "types": "./build/types/index.d.ts",
+        "default": "./build/esm/index.js"
+      },
+      "require": "./build/cjs/index.js",
+      "default": "./build/browser/index.js"
+    },
+    "./*": {
+      "browser": "./build/browser/public/*.js",
+      "import": {
+        "types": "./build/types/public/*.d.ts",
+        "default": "./build/js/public/*.js"
+      },
+      "require": "./build/cjs/public/*.js",
+      "default": "./build/browser/public/*.js"
+    }
+  },
+  "dependencies": {
+    "@osdk/api": "~2.4.2",
+    "remeda": "^2.32.0",
+    "tiny-invariant": "^1.3.3",
+    "yjs": "^13.6.27",
+    "@palantir/pack.document-schema.model-types": "0.1.0-beta.2",
+    "@palantir/pack.core": "0.0.1-beta.1"
+  },
+  "peerDependencies": {
+    "zod": "^4.1.0"
+  },
+  "devDependencies": {
+    "@osdk/client": "~2.4.2",
+    "rimraf": "^6.0.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.2",
+    "vitest-mock-extended": "^3.1.0",
+    "@palantir/pack.monorepo.tsconfig": "~0.4.0-beta.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pack"
+  ],
+  "main": "./build/cjs/index.js",
+  "module": "./build/esm/index.js",
+  "types": "./build/cjs/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "clean": "rimraf .turbo build dist lib test-output *.tgz tsconfig.tsbuildinfo",
+    "lint": "eslint ./src ; dprint check --config $(find-up dprint.json) --allow-no-files",
+    "lint:fix": "eslint ./src --fix ; dprint fmt --config $(find-up dprint.json) --allow-no-files",
+    "test": "vitest run --passWithNoTests -u",
+    "test:watch": "vitest --passWithNoTests",
+    "transpileBrowser": "monorepo-transpile -f esm -m bundle -t browser",
+    "transpileCjs": "monorepo-transpile -f cjs -m bundle -t node",
+    "transpileEsm": "monorepo-transpile -f esm -m bundle -t node",
+    "transpileTypes": "monorepo-transpile -f esm -m types -t node",
+    "typecheck": "tsc --noEmit --emitDeclarationOnly false"
+  }
+}

package/src/DocumentServiceModule.ts

@@ -0,0 +1,53 @@
+/*
+ * 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 { ModuleConfigTuple, ModuleKey, PackAppInternal } from "@palantir/pack.core";
+import type { DocumentService } from "./types/DocumentService.js";
+import type { WithDocumentServiceInit } from "./types/DocumentServiceConfig.js";
+
+export const DOCUMENT_SERVICE_MODULE_KEY: ModuleKey<
+  DocumentService,
+  WithDocumentServiceInit
+> = {
+  key: Symbol("DocumentService"),
+  initModule: initDocumentService,
+};
+
+export function getDocumentService(app: PackAppInternal): DocumentService {
+  return app.getModule(DOCUMENT_SERVICE_MODULE_KEY);
+}
+
+export function createDocumentServiceConfig<T>(
+  init: (app: PackAppInternal, config: T) => DocumentService,
+  config: T,
+): ModuleConfigTuple<DocumentService> {
+  return [DOCUMENT_SERVICE_MODULE_KEY as ModuleKey<DocumentService>, {
+    ...config,
+    init,
+  } as WithDocumentServiceInit] as const;
+}
+
+function initDocumentService(
+  app: PackAppInternal,
+  config?: WithDocumentServiceInit,
+): DocumentService {
+  if (config == null) {
+    throw new Error(
+      "DocumentServiceConfig is required to initialize DocumentService",
+    );
+  }
+  return config.init(app, config);
+}

package/src/__tests__/DocumentStatusTracking.test.ts

@@ -0,0 +1,229 @@
+/*
+ * 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 { DocumentId, DocumentSchema } from "@palantir/pack.document-schema.model-types";
+import { Metadata } from "@palantir/pack.document-schema.model-types";
+import { describe, expect, it } from "vitest";
+import { internalCreateInMemoryDocumentService } from "../service/InMemoryDocumentService.js";
+import { createDocRef } from "../types/DocumentRefImpl.js";
+import type { DocumentStatus } from "../types/DocumentService.js";
+import { DocumentLiveStatus, DocumentLoadStatus } from "../types/DocumentService.js";
+import { createTestApp } from "./testUtils.js";
+
+const DOCUMENT_ID = "test-doc" as DocumentId;
+
+const testSchema = {
+  [Metadata]: {
+    version: 1,
+  },
+} as const satisfies DocumentSchema;
+
+describe("Document Status Tracking", () => {
+  it("should initialize with correct default status", () => {
+    const mockApp = createTestApp();
+    const service = internalCreateInMemoryDocumentService(mockApp, { autoCreateDocuments: true });
+    const docRef = createDocRef(mockApp, DOCUMENT_ID, testSchema);
+
+    const status = service.getDocumentStatus(docRef);
+
+    expect(status.metadata.load).toBe(DocumentLoadStatus.UNLOADED);
+    expect(status.metadata.live).toBe(DocumentLiveStatus.DISCONNECTED);
+    expect(status.data.load).toBe(DocumentLoadStatus.UNLOADED);
+    expect(status.data.live).toBe(DocumentLiveStatus.DISCONNECTED);
+    expect(status.metadataError).toBeUndefined();
+    expect(status.dataError).toBeUndefined();
+  });
+
+  it("should trigger metadata loading on first metadata subscription", async () => {
+    const mockApp = createTestApp();
+    const service = internalCreateInMemoryDocumentService(mockApp, { autoCreateDocuments: true });
+    const docRef = createDocRef(mockApp, DOCUMENT_ID, testSchema);
+
+    const statusUpdates: DocumentStatus[] = [];
+
+    // Subscribe to metadata changes first (triggers loading)
+    const unsubscribeMetadata = service.onMetadataChange(docRef, () => {});
+
+    // Then subscribe to status changes (might already be loaded)
+    const unsubscribeStatus = service.onStatusChange(docRef, (_, status) => {
+      statusUpdates.push(status);
+    });
+
+    // Wait for async loading to complete
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    // The first status we receive should be loaded (since InMemory + autoCreate loads immediately)
+    expect(statusUpdates.length).toBeGreaterThanOrEqual(1);
+    const finalStatus = statusUpdates.at(-1);
+    expect(finalStatus?.metadata.load).toBe(DocumentLoadStatus.LOADED);
+
+    unsubscribeStatus();
+    unsubscribeMetadata();
+  });
+
+  it("should trigger data loading on first data subscription", async () => {
+    const mockApp = createTestApp();
+    const service = internalCreateInMemoryDocumentService(mockApp, { autoCreateDocuments: true });
+    const docRef = createDocRef(mockApp, DOCUMENT_ID, testSchema);
+
+    const statusUpdates: DocumentStatus[] = [];
+
+    // Subscribe to state changes first (triggers data loading)
+    const unsubscribeState = service.onStateChange(docRef, () => {});
+
+    // Then subscribe to status changes (might already be loaded)
+    const unsubscribeStatus = service.onStatusChange(docRef, (_, status) => {
+      statusUpdates.push(status);
+    });
+
+    // Wait for async loading to complete
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    // The first status we receive should be loaded (since InMemory + autoCreate loads immediately)
+    expect(statusUpdates.length).toBeGreaterThanOrEqual(1);
+    const finalStatus = statusUpdates.at(-1);
+    expect(finalStatus?.data.load).toBe(DocumentLoadStatus.LOADED);
+
+    unsubscribeStatus();
+    unsubscribeState();
+  });
+
+  it("should not reload if already loaded", async () => {
+    const mockApp = createTestApp();
+    const service = internalCreateInMemoryDocumentService(mockApp, { autoCreateDocuments: true });
+    const docRef = createDocRef(mockApp, DOCUMENT_ID, testSchema);
+
+    // First subscription
+    const unsubscribe1 = service.onMetadataChange(docRef, () => {});
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    const statusUpdates: DocumentStatus[] = [];
+
+    // Subscribe to status changes after first load
+    const unsubscribeStatus = service.onStatusChange(docRef, (_, status) => {
+      statusUpdates.push(status);
+    });
+
+    // Second subscription should not trigger another load
+    const unsubscribe2 = service.onMetadataChange(docRef, () => {});
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    // Should only get the initial status (already loaded)
+    expect(statusUpdates).toHaveLength(1);
+    expect(statusUpdates[0]?.metadata.load).toBe(DocumentLoadStatus.LOADED);
+
+    unsubscribe1();
+    unsubscribe2();
+    unsubscribeStatus();
+  });
+
+  it("should handle subscription lifecycle correctly", async () => {
+    const mockApp = createTestApp();
+    const service = internalCreateInMemoryDocumentService(mockApp, { autoCreateDocuments: true });
+    const docRef = createDocRef(mockApp, DOCUMENT_ID, testSchema);
+
+    // First subscription
+    const unsubscribe1 = service.onMetadataChange(docRef, () => {});
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    // Second subscription
+    const unsubscribe2 = service.onMetadataChange(docRef, () => {});
+
+    // Unsubscribe first (should not close subscription)
+    unsubscribe1();
+
+    const status1 = service.getDocumentStatus(docRef);
+    expect(status1.metadata.load).toBe(DocumentLoadStatus.LOADED);
+
+    // Unsubscribe last (should close subscription but keep loaded state)
+    unsubscribe2();
+
+    const status2 = service.getDocumentStatus(docRef);
+    expect(status2.metadata.load).toBe(DocumentLoadStatus.LOADED);
+  });
+
+  it("should wait for metadata load", async () => {
+    const mockApp = createTestApp();
+    const service = internalCreateInMemoryDocumentService(mockApp, { autoCreateDocuments: true });
+    const docRef = createDocRef(mockApp, DOCUMENT_ID, testSchema);
+
+    // Start metadata subscription in background
+    const unsubscribe = service.onMetadataChange(docRef, () => {});
+
+    // Wait for load should resolve
+    await expect(service.waitForMetadataLoad(docRef)).resolves.toBeUndefined();
+
+    unsubscribe();
+  });
+
+  it("should wait for data load", async () => {
+    const mockApp = createTestApp();
+    const service = internalCreateInMemoryDocumentService(mockApp, { autoCreateDocuments: true });
+    const docRef = createDocRef(mockApp, DOCUMENT_ID, testSchema);
+
+    // Start data subscription in background
+    const unsubscribe = service.onStateChange(docRef, () => {});
+
+    // Wait for load should resolve
+    await expect(service.waitForDataLoad(docRef)).resolves.toBeUndefined();
+
+    unsubscribe();
+  });
+
+  it("should handle multiple subscription types for data loading", async () => {
+    const mockApp = createTestApp();
+    const service = internalCreateInMemoryDocumentService(mockApp, { autoCreateDocuments: true });
+    const docRef = createDocRef(mockApp, DOCUMENT_ID, testSchema);
+
+    // First state subscription
+    const unsubscribeState1 = service.onStateChange(docRef, () => {});
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    const statusUpdates: DocumentStatus[] = [];
+    const unsubscribeStatus = service.onStatusChange(docRef, (_, status) => {
+      statusUpdates.push(status);
+    });
+
+    // Second state subscription should not trigger another load
+    const unsubscribeState2 = service.onStateChange(docRef, () => {});
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    // Since the document was already loaded before status subscription, we should only see loaded state
+    expect(statusUpdates.length).toBeGreaterThanOrEqual(1);
+    const allLoadedStatuses = statusUpdates.every(s => s.data.load === DocumentLoadStatus.LOADED);
+    expect(allLoadedStatuses).toBe(true);
+
+    unsubscribeState1();
+    unsubscribeState2();
+    unsubscribeStatus();
+  });
+
+  it("should provide immediate status to new subscribers", () => {
+    const mockApp = createTestApp();
+    const service = internalCreateInMemoryDocumentService(mockApp, { autoCreateDocuments: true });
+    const docRef = createDocRef(mockApp, DOCUMENT_ID, testSchema);
+
+    let immediateStatus: DocumentStatus | null = null;
+
+    service.onStatusChange(docRef, (_, status) => {
+      immediateStatus = status;
+    });
+
+    expect(immediateStatus).toBeTruthy();
+    expect(immediateStatus!.metadata.load).toBe(DocumentLoadStatus.UNLOADED);
+    expect(immediateStatus!.data.load).toBe(DocumentLoadStatus.UNLOADED);
+  });
+});