@palantir/pack.document-schema.model-types 0.14.0 → 0.24.0

package/src/types/ChannelError.ts

@@ -0,0 +1,75 @@
+/*
+ * 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.
+ */
+
+/**
+ * Reason a document channel subscription (data, presence, activity) failed.
+ * UI can branch on this to decide how to react.
+ */
+export const ChannelErrorCode = {
+  /** Client's max supported schema version is below the document's operational version. */
+  CLIENT_VERSION_TOO_LOW: "clientVersionTooLow",
+  /** Client's base revision is too far behind to sync. */
+  REVISION_TOO_OLD: "revisionTooOld",
+  /** Document's operational version was bumped; client must re-subscribe. */
+  OPERATIONAL_VERSION_BUMPED: "operationalVersionBumped",
+  /** Server-side internal error. */
+  INTERNAL_ERROR: "internalError",
+  /** Any other failure (transport error, or an unrecognized server code). */
+  UNKNOWN: "unknown",
+} as const;
+export type ChannelErrorCode = typeof ChannelErrorCode[keyof typeof ChannelErrorCode];
+
+/**
+ * A typed error describing why a channel subscription failed.
+ */
+export interface ChannelError {
+  readonly code: ChannelErrorCode;
+  /** Server-assigned id for correlating this error with backend logs. Empty for client-side errors. */
+  readonly errorInstanceId: string;
+  /** Optional human-readable detail (e.g. for UNKNOWN/client-side errors). */
+  readonly message?: string;
+}
+
+/**
+ * Wraps an arbitrary thrown value (transport failure, client-side error) as a
+ * ChannelError with code UNKNOWN.
+ */
+export function toUnknownChannelError(cause: unknown): ChannelError {
+  return {
+    code: ChannelErrorCode.UNKNOWN,
+    errorInstanceId: "",
+    message: cause instanceof Error ? cause.message : String(cause),
+  };
+}
+
+// Server (platform) error code strings → domain ChannelErrorCode.
+const SERVER_ERROR_CODE_MAP: Record<string, ChannelErrorCode> = {
+  CLIENT_VERSION_TOO_LOW: ChannelErrorCode.CLIENT_VERSION_TOO_LOW,
+  REVISION_TOO_OLD: ChannelErrorCode.REVISION_TOO_OLD,
+  DOCUMENT_TYPE_OPERATIONAL_VERSION_BUMPED: ChannelErrorCode.OPERATIONAL_VERSION_BUMPED,
+  INTERNAL_ERROR: ChannelErrorCode.INTERNAL_ERROR,
+};
+
+/**
+ * Maps a platform channel error (raw server code + instance id) to a domain
+ * ChannelError. Unrecognized server codes collapse to ChannelErrorCode.UNKNOWN.
+ */
+export function toChannelError(serverCode: string, errorInstanceId: string): ChannelError {
+  return {
+    code: SERVER_ERROR_CODE_MAP[serverCode] ?? ChannelErrorCode.UNKNOWN,
+    errorInstanceId,
+  };
+}

package/src/types/Model.ts

@@ -59,6 +59,7 @@ export const ExternalRefType = {
   DOC_REF: "docRef",
   MEDIA_REF: "mediaRef",
   OBJECT_REF: "objectRef",
+  RESOURCE_REF: "resourceRef",
   USER_REF: "userRef",
 } as const;
 
@@ -67,8 +68,9 @@ export type ExternalRefType = typeof ExternalRefType[keyof typeof ExternalRefTyp
 export interface RecordModelMetadata<T = unknown> {
   /**
    * Which fields in the model are external references (e.g. UserRef, DocumentRef, etc).
+   * Partial — only ref fields are listed, not every field in the model.
    */
-  readonly externalRefFieldTypes?: Readonly<Record<keyof T, ExternalRefType>>;
+  readonly externalRefFieldTypes?: Readonly<Partial<Record<keyof T, ExternalRefType>>>;
   /**
    * The name of the model (should match the typescript symbol).
    */

package/src/types/RecordRef.ts

@@ -17,6 +17,7 @@
 import type { Flavored } from "@palantir/pack.core";
 import type { DocumentRef } from "./DocumentRef.js";
 import type { Model, ModelData } from "./Model.js";
+import type { RecordValidationError } from "./RecordValidation.js";
 import type { Unsubscribe } from "./Unsubscribe.js";
 
 export type RecordId = Flavored<"RecordId">;
@@ -76,6 +77,33 @@ export interface RecordRef<M extends Model = Model> {
    */
   onChange(callback: (snapshot: ModelData<M>, recordRef: RecordRef<M>) => void): Unsubscribe;
 
+  /**
+   * Subscribe to schema-validation failures for the record.
+   *
+   * If the record's stored data cannot be validated against the model's
+   * schema (for example, after a partial write left the document in a
+   * corrupted state), `onChange` subscribers are NOT called with the invalid
+   * data; instead, callbacks registered here receive a
+   * {@link RecordValidationError} describing the failure. If the record is
+   * later repaired by a subsequent update, `onChange` resumes firing.
+   *
+   * If the record is already invalid at subscription time, the callback is
+   * invoked immediately.
+   *
+   * @param callback The callback to invoke when the record fails validation.
+   * @returns An unsubscribe function.
+   *
+   * @example
+   * ```ts
+   * recordRef.onInvalid((error, recordRef) => {
+   *   console.warn("Record failed validation:", error.issues);
+   * });
+   * ```
+   */
+  onInvalid(
+    callback: (error: RecordValidationError, recordRef: RecordRef<M>) => void,
+  ): Unsubscribe;
+
   /**
    * Subscribe to deletion of the record.
    * @param callback The callback to invoke when the record is deleted.

package/src/types/RecordValidation.ts

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2026 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 { RecordId } from "./RecordRef.js";
+
+/**
+ * A single schema-validation failure within a record snapshot.
+ */
+export interface RecordValidationIssue {
+  /** Path of the failing field within the record (empty for record-level issues). */
+  readonly path: ReadonlyArray<string | number>;
+  /** Human-readable description of the failure. */
+  readonly message: string;
+}
+
+/**
+ * Describes why a record's stored data failed schema validation against its
+ * model.
+ *
+ * Delivered to {@link RecordRef.onInvalid} subscribers and queryable per
+ * document via `getInvalidRecords`. A record can become invalid when the
+ * document's persisted state does not match what the model's schema promises
+ * (for example, after a partial write left the document corrupted).
+ */
+export interface RecordValidationError {
+  /** Name of the model the record was expected to conform to. */
+  readonly modelName: string;
+  /** Id of the failing record. */
+  readonly recordId: RecordId;
+  /** Individual field-level failures. */
+  readonly issues: readonly RecordValidationIssue[];
+  /** Summary message suitable for logging. */
+  readonly message: string;
+}
+
+/**
+ * Error used to reject promise-based snapshot reads (e.g.
+ * {@link RecordRef.getSnapshot}) when the record exists but its data fails
+ * schema validation.
+ */
+export class RecordInvalidError extends Error {
+  readonly validation: RecordValidationError;
+
+  constructor(validation: RecordValidationError) {
+    super(validation.message);
+    this.name = "RecordInvalidError";
+    this.validation = validation;
+  }
+}

package/src/types/ResourceRid.ts

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2026 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 { Flavored } from "@palantir/pack.core";
+
+/** Identifies an arbitrary platform resource by RID. */
+export type ResourceRid = Flavored<"ResourceRid">;