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

package/src/types/RecordCollectionRefImpl.ts

@@ -0,0 +1,124 @@
+/*
+ * 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 {
+  DocumentRef,
+  Model,
+  ModelData,
+  RecordCollectionRef,
+  RecordId,
+  RecordRef,
+  Unsubscribe,
+} from "@palantir/pack.document-schema.model-types";
+import { RecordCollectionRefBrand } from "@palantir/pack.document-schema.model-types";
+import { invalidDocRef } from "./DocumentRefImpl.js";
+import type { DocumentService } from "./DocumentService.js";
+
+const INVALID_RECORD_COLLECTION_REF: RecordCollectionRef = Object.freeze(
+  {
+    docRef: invalidDocRef(),
+    model: {} as Model,
+    [RecordCollectionRefBrand]: RecordCollectionRefBrand,
+    get: () => undefined,
+    has: () => false,
+    set: () => Promise.reject(new Error("Invalid record collection reference")),
+    delete: () => Promise.reject(new Error("Invalid record collection reference")),
+    size: 0,
+    [Symbol.iterator]: () => ({
+      next: () => ({ done: true as const, value: undefined as never }),
+    }),
+    onItemsAdded: () => () => {},
+    onItemsChanged: () => () => {},
+    onItemsDeleted: () => () => {},
+  } as const,
+);
+
+export const createRecordCollectionRef = <const M extends Model>(
+  documentService: DocumentService,
+  docRef: DocumentRef,
+  model: M,
+): RecordCollectionRef<M> => {
+  return new RecordCollectionRefImpl(documentService, docRef, model);
+};
+
+export function invalidRecordCollectionRef<M extends Model = Model>(): RecordCollectionRef<M> {
+  return INVALID_RECORD_COLLECTION_REF as RecordCollectionRef<M>;
+}
+
+export function isValidRecordCollectionRef<M extends Model = Model>(
+  collectionRef: RecordCollectionRef<M>,
+): collectionRef is RecordCollectionRef<M> {
+  return collectionRef !== INVALID_RECORD_COLLECTION_REF;
+}
+
+class RecordCollectionRefImpl<M extends Model> implements RecordCollectionRef<M> {
+  readonly docRef: DocumentRef;
+  readonly model: M;
+  declare readonly [RecordCollectionRefBrand]: typeof RecordCollectionRefBrand;
+  readonly #documentService: DocumentService;
+
+  constructor(documentService: DocumentService, docRef: DocumentRef, model: M) {
+    this.docRef = docRef;
+    this.model = model;
+    this.#documentService = documentService;
+  }
+
+  get(id: RecordId): RecordRef<M> | undefined {
+    return this.#documentService.getRecord(this, id);
+  }
+
+  has(id: RecordId): boolean {
+    return this.#documentService.hasRecord(this, id);
+  }
+
+  async set(id: RecordId, state: ModelData<M>): Promise<void> {
+    return this.#documentService.setCollectionRecord(this, id, state);
+  }
+
+  delete(id: RecordId): Promise<void> {
+    const recordRefInstance = this.#documentService.getRecord(this, id);
+    if (recordRefInstance) {
+      return this.#documentService.deleteRecord(recordRefInstance);
+    }
+    return Promise.reject(new Error(`Unknown record`));
+  }
+
+  get size(): number {
+    return this.#documentService.getCollectionSize(this);
+  }
+
+  [Symbol.iterator](): Iterator<RecordRef<M>> {
+    return this.#documentService.getCollectionRecords(this)[Symbol.iterator]();
+  }
+
+  readonly onItemsAdded = (
+    callback: (items: readonly RecordRef<M>[]) => void,
+  ): Unsubscribe => {
+    return this.#documentService.onCollectionItemsAdded(this, callback);
+  };
+
+  readonly onItemsChanged = (
+    callback: (items: readonly RecordRef<M>[]) => void,
+  ): Unsubscribe => {
+    return this.#documentService.onCollectionItemsChanged(this, callback);
+  };
+
+  readonly onItemsDeleted = (
+    callback: (items: readonly RecordRef<M>[]) => void,
+  ): Unsubscribe => {
+    return this.#documentService.onCollectionItemsDeleted(this, callback);
+  };
+}

package/src/types/RecordRefImpl.ts

@@ -0,0 +1,106 @@
+/*
+ * 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 {
+  DocumentRef,
+  Model,
+  ModelData,
+  RecordId,
+  RecordRef,
+  Unsubscribe,
+} from "@palantir/pack.document-schema.model-types";
+import { RecordRefBrand } from "@palantir/pack.document-schema.model-types";
+import { invalidDocRef } from "./DocumentRefImpl.js";
+import type { DocumentService } from "./DocumentService.js";
+
+const INVALID_RECORD_ID: RecordId = "INVALID_RECORD_REF";
+const INVALID_RECORD_REF: RecordRef = Object.freeze(
+  {
+    docRef: invalidDocRef(),
+    id: INVALID_RECORD_ID,
+    model: {} as Model,
+    [RecordRefBrand]: RecordRefBrand,
+    getSnapshot: () => Promise.reject(new Error("Invalid record reference")),
+    set: () => Promise.reject(new Error("Invalid record reference")),
+    onChange: () => () => {},
+    onDeleted: () => () => {},
+  } as const,
+);
+
+export const createRecordRef = <const M extends Model>(
+  documentService: DocumentService,
+  docRef: DocumentRef,
+  id: RecordId,
+  model: M,
+): RecordRef<M> => {
+  return new RecordRefImpl(documentService, docRef, id, model);
+};
+
+export function invalidRecordRef<M extends Model = Model>(): RecordRef<M> {
+  return INVALID_RECORD_REF as RecordRef<M>;
+}
+
+export function isValidRecordRef<M extends Model = Model>(
+  recordRef: RecordRef<M>,
+): recordRef is RecordRef<M> {
+  return recordRef.id !== INVALID_RECORD_ID;
+}
+
+class RecordRefImpl<M extends Model> implements RecordRef<M> {
+  readonly docRef: DocumentRef;
+  readonly id: RecordId;
+  readonly model: M;
+  declare readonly [RecordRefBrand]: typeof RecordRefBrand;
+  readonly #documentService: DocumentService;
+
+  constructor(
+    documentService: DocumentService,
+    docRef: DocumentRef,
+    id: RecordId,
+    model: M,
+  ) {
+    this.#documentService = documentService;
+    this.docRef = docRef;
+    this.id = id;
+    this.model = model;
+  }
+
+  async getSnapshot(): Promise<ModelData<M>> {
+    return this.#documentService.getRecordSnapshot(this);
+  }
+
+  onChange(
+    callback: (snapshot: ModelData<M>, recordRef: RecordRef<M>) => void,
+  ): Unsubscribe {
+    return this.#documentService.onRecordChanged(this, callback);
+  }
+
+  onDeleted(callback: (recordRef: RecordRef<M>) => void): Unsubscribe {
+    return this.#documentService.onRecordDeleted(this, callback);
+  }
+
+  delete(): Promise<void> {
+    return this.#documentService.deleteRecord(this);
+  }
+
+  set(record: ModelData<M>): Promise<void> {
+    return this.#documentService.setRecord(this, record);
+  }
+
+  update(partialRecord: Partial<ModelData<M>>): Promise<void> {
+    return this.#documentService.updateRecord(this, partialRecord);
+  }
+}

package/src/types/StateModule.ts

@@ -0,0 +1,329 @@
+/*
+ * 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 {
+  assertIsAppInternal,
+  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 { DOCUMENT_SERVICE_MODULE_KEY } from "../DocumentServiceModule.js";
+import type {
+  DocumentService,
+  RecordChangeCallback,
+  RecordCollectionChangeCallback,
+  RecordDeleteCallback,
+} from "./DocumentService.js";
+
+// Ensure state module is accessible on PackApp instances.
+export const STATE_MODULE_ACCESSOR = "state";
+export const STATE_MODULE_KEY: ModuleKey<StateModuleImpl> = {
+  appMemberName: STATE_MODULE_ACCESSOR,
+  key: Symbol.for("pack.state"),
+  initModule: (app: PackAppInternal) => {
+    const documentService = app.getModule(DOCUMENT_SERVICE_MODULE_KEY);
+    return new StateModuleImpl(documentService);
+  },
+};
+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>;
+
+  // Status methods
+  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 class StateModuleImpl implements StateModule {
+  constructor(
+    private readonly documentService: DocumentService,
+  ) {}
+
+  createDocRef<const T extends DocumentSchema>(
+    id: DocumentId,
+    schema: T,
+  ): DocumentRef<T> {
+    return this.documentService.createDocRef(id, schema);
+  }
+
+  createRecordRef<const M extends Model>(
+    docRef: DocumentRef,
+    id: RecordId,
+    model: M,
+  ): RecordRef<M> {
+    return this.documentService.getCreateRecordRef(docRef, id, model);
+  }
+
+  async createDocument<T extends DocumentSchema>(
+    metadata: DocumentMetadata,
+    schema: T,
+  ): Promise<DocumentRef<T>> {
+    return this.documentService.createDocument(metadata, schema);
+  }
+
+  async getDocumentSnapshot<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+  ): Promise<DocumentState<T>> {
+    return this.documentService.getDocumentSnapshot(docRef);
+  }
+
+  onMetadataChange<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    cb: (doc: DocumentRef<T>, metadata: DocumentMetadata) => void,
+  ): Unsubscribe {
+    return this.documentService.onMetadataChange(docRef, cb);
+  }
+
+  onStateChange<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    cb: (docRef: DocumentRef<T>) => void,
+  ): Unsubscribe {
+    return this.documentService.onStateChange(docRef, cb);
+  }
+
+  async getRecordSnapshot<R extends Model>(
+    recordRef: RecordRef<R>,
+  ): Promise<ModelData<R>> {
+    return this.documentService.getRecordSnapshot(recordRef);
+  }
+
+  async setRecord<R extends Model>(
+    recordRef: RecordRef<R>,
+    state: ModelData<R>,
+  ): Promise<void> {
+    return this.documentService.setRecord(recordRef, state);
+  }
+
+  async updateRecord<R extends Model>(
+    recordRef: RecordRef<R>,
+    partialState: Partial<ModelData<R>>,
+  ): Promise<void> {
+    return this.documentService.updateRecord(recordRef, partialState);
+  }
+
+  // Collection methods
+  getCreateRecordCollectionRef<M extends Model>(
+    docRef: DocumentRef,
+    model: M,
+  ): RecordCollectionRef<M> {
+    return this.documentService.getCreateRecordCollectionRef(docRef, model);
+  }
+
+  // FIXME: confusing vs createRecordRef
+  getRecord<M extends Model>(
+    collection: RecordCollectionRef<M>,
+    id: RecordId,
+  ): RecordRef<M> | undefined {
+    return this.documentService.getRecord(collection, id);
+  }
+
+  hasRecord<M extends Model>(
+    collection: RecordCollectionRef<M>,
+    id: RecordId,
+  ): boolean {
+    return this.documentService.hasRecord(collection, id);
+  }
+
+  async setCollectionRecord<M extends Model>(
+    collection: RecordCollectionRef<M>,
+    id: RecordId,
+    state: ModelData<M>,
+  ): Promise<void> {
+    return this.documentService.setCollectionRecord(collection, id, state);
+  }
+
+  getCollectionSize<M extends Model>(
+    collection: RecordCollectionRef<M>,
+  ): number {
+    return this.documentService.getCollectionSize(collection);
+  }
+
+  getCollectionRecords<M extends Model>(
+    collection: RecordCollectionRef<M>,
+  ): RecordRef<M>[] {
+    return this.documentService.getCollectionRecords(collection);
+  }
+
+  onRecordChanged<M extends Model>(
+    record: RecordRef<M>,
+    callback: RecordChangeCallback<M>,
+  ): Unsubscribe {
+    return this.documentService.onRecordChanged(record, callback);
+  }
+
+  onRecordDeleted<M extends Model>(
+    record: RecordRef<M>,
+    callback: RecordDeleteCallback<M>,
+  ): Unsubscribe {
+    return this.documentService.onRecordDeleted(record, callback);
+  }
+
+  onCollectionItemsAdded<M extends Model>(
+    collection: RecordCollectionRef<M>,
+    callback: RecordCollectionChangeCallback<M>,
+  ): Unsubscribe {
+    return this.documentService.onCollectionItemsAdded(collection, callback);
+  }
+
+  onCollectionItemsChanged<M extends Model>(
+    collection: RecordCollectionRef<M>,
+    callback: RecordCollectionChangeCallback<M>,
+  ): Unsubscribe {
+    return this.documentService.onCollectionItemsChanged(collection, callback);
+  }
+
+  onCollectionItemsDeleted<M extends Model>(
+    collection: RecordCollectionRef<M>,
+    callback: RecordCollectionChangeCallback<M>,
+  ): Unsubscribe {
+    return this.documentService.onCollectionItemsDeleted(collection, callback);
+  }
+
+  // Status methods implementation
+  getDocumentStatus<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+  ): ReturnType<DocumentService["getDocumentStatus"]> {
+    return this.documentService.getDocumentStatus(docRef);
+  }
+
+  onStatusChange<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+    callback: Parameters<DocumentService["onStatusChange"]>[1],
+  ): Unsubscribe {
+    return this.documentService.onStatusChange(docRef, callback);
+  }
+
+  async waitForMetadataLoad<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+  ): Promise<void> {
+    return this.documentService.waitForMetadataLoad(docRef);
+  }
+
+  async waitForDataLoad<T extends DocumentSchema>(
+    docRef: DocumentRef<T>,
+  ): Promise<void> {
+    return this.documentService.waitForDataLoad(docRef);
+  }
+
+  async deleteRecord<M extends Model>(
+    record: RecordRef<M>,
+  ): Promise<void> {
+    return this.documentService.deleteRecord(record);
+  }
+}
+
+export function getStateModule(app: PackAppInternal): StateModule {
+  assertIsAppInternal(app);
+  return app.getModule(STATE_MODULE_KEY);
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": "@palantir/pack.monorepo.tsconfig/base.json",
+  "compilerOptions": {
+    "outDir": "./build/esm",
+    "rootDir": "./src",
+    "declarationDir": "./build/types",
+    "tsBuildInfoFile": "./build/tsconfig.tsbuildinfo"
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "build",
+    "dist",
+    "node_modules",
+    "test-output",
+    "**/__tests__/**/__snapshots__",
+    "**/__tests__/**/fixtures"
+  ],
+  "references": []
+}

package/vitest.config.mjs

@@ -0,0 +1,26 @@
+import { coverageConfigDefaults, defaultExclude, defineProject } from "vitest/config";
+
+export default defineProject({
+  test: {
+    exclude: [...defaultExclude, "**/build/**", "**/test-output/**"],
+    coverage: {
+      provider: "v8",
+      all: true,
+      enabled: true,
+      pool: "forks",
+      include: ["src/**/*.{ts,tsx}"],
+      exclude: [
+        ...coverageConfigDefaults.exclude,
+        "**/*.test.{ts,tsx}",
+        "**/__tests__",
+        "build",
+        "coverage",
+        "dist",
+        "node_modules",
+        "src/index.ts",
+        "test-output",
+        "vitest.config.*",
+      ],
+    },
+  },
+});