@palantir/pack.schema 0.27.0 → 0.29.0

package/build/types/primitives.d.ts

@@ -13,31 +13,38 @@ export declare const TypeKind: {
 	readonly USER_REF: "userRef";
 };
 export type TypeKind = typeof TypeKind[keyof typeof TypeKind];
+/** A UTF-8 string field. */
 export type String = {
 	readonly type: typeof TypeKind.STRING;
 };
+/** A double-precision floating point number field. */
 export type Double = {
 	readonly type: typeof TypeKind.DOUBLE;
 };
+/** A boolean field. */
 export type Boolean = {
 	readonly type: typeof TypeKind.BOOLEAN;
 };
 interface TypeBase {
 	readonly type: TypeKind;
 }
+/** A list of `T`. Nested arrays are not supported — wrap the inner array in a record. */
 export type Array<T extends TypeBase = TypeBase> = {
 	readonly type: typeof TypeKind.ARRAY;
 	readonly items: T;
 };
+/** A reference to another record or union in the same schema. */
 export type Ref = {
 	readonly type: typeof TypeKind.REF;
 	readonly refType: "record" | "union";
 	readonly name: string;
 };
+/** A `T` that may be absent. Nested optionals are not supported. */
 export type Optional<T extends TypeBase = TypeBase> = {
 	readonly type: typeof TypeKind.OPTIONAL;
 	readonly item: T;
 };
+/** An opaque, arbitrary JSON value. */
 export type Unknown = {
 	readonly type: typeof TypeKind.UNKNOWN;
 };
@@ -56,12 +63,20 @@ export type ResourceRef = {
 export type UserRef = {
 	readonly type: typeof TypeKind.USER_REF;
 };
+/** Any valid field type: a primitive, a composite (`Array`/`Optional`), or a `Ref`. */
 export type Type = Array | Boolean | DocRef | Double | MediaRef | ObjectRef | ResourceRef | Optional | Ref | String | Unknown | UserRef;
+/** A UTF-8 string field. */
 export declare const String: String;
+/** A double-precision floating point number field. */
 export declare const Double: Double;
+/** A boolean field. */
 export declare const Boolean: Boolean;
+/** An opaque, arbitrary JSON value. */
 export declare const Unknown: Unknown;
+/** A reference to a Foundry resource. */
 export declare const ResourceRef: ResourceRef;
+/** Build an array field whose elements are `item`. */
 export declare const Array: <T extends TypeBase>(item: T) => Array<T>;
+/** Build an optional field wrapping `item`, marking it as possibly absent. */
 export declare const Optional: <T extends TypeBase>(item: T) => Optional<T>;
 export {};

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

@@ -1 +1 @@
-{"mappings":"AAgBA,OAAO,cAAM;UACX,OAAO;UACP,SAAS;UACT,SAAS;UACT,QAAQ;UACR,WAAW;UACX,YAAY;UACZ,UAAU;UACV,KAAK;UACL,cAAc;UACd,QAAQ;UACR,SAAS;UACT,UAAU;;AAGZ,YAAY,kBAAkB,sBAAsB;AAEpD,YAAY,SAAS;UACV,aAAa,SAAS;;AAGjC,YAAY,SAAS;UACV,aAAa,SAAS;;AAGjC,YAAY,UAAU;UACX,aAAa,SAAS;;UAIvB,SAAS;UACR,MAAM;;AAGjB,YAAY,MAAM,UAAU,WAAW,YAAY;UACxC,aAAa,SAAS;UACtB,OAAO;;AAIlB,YAAY,MAAM;UACP,aAAa,SAAS;UACtB,SAAS,WAAW;UACpB;;AAGX,YAAY,SAAS,UAAU,WAAW,YAAY;UAC3C,aAAa,SAAS;UACtB,MAAM;;AAGjB,YAAY,UAAU;UACX,aAAa,SAAS;;AAGjC,YAAY,SAAS;UACV,aAAa,SAAS;;AAGjC,YAAY,WAAW;UACZ,aAAa,SAAS;;AAGjC,YAAY,YAAY;UACb,aAAa,SAAS;;AAGjC,YAAY,cAAc;UACf,aAAa,SAAS;;AAGjC,YAAY,UAAU;UACX,aAAa,SAAS;;AAGjC,YAAY,OACR,QACA,UACA,SACA,SACA,WACA,YACA,cACA,WACA,MACA,SACA,UACA;AAEJ,OAAO,cAAMA,QAAQ;AACrB,OAAO,cAAMC,QAAQ;AACrB,OAAO,cAAMC,SAAS;AACtB,OAAO,cAAMC,SAAS;AACtB,OAAO,cAAMC,aAAa;AAK1B,OAAO,cAAM,QAAS,UAAU,UAAU,MAAM,MAAI,MAAM;AAS1D,OAAO,cAAM,WAAY,UAAU,UAAU,MAAM,MAAI,SAAS","names":["String: String","Double: Double","Boolean: Boolean","Unknown: Unknown","ResourceRef: ResourceRef"],"sources":["../../src/primitives.ts"],"version":3,"file":"primitives.d.ts"}
+{"mappings":"AAgBA,OAAO,cAAM;UACX,OAAO;UACP,SAAS;UACT,SAAS;UACT,QAAQ;UACR,WAAW;UACX,YAAY;UACZ,UAAU;UACV,KAAK;UACL,cAAc;UACd,QAAQ;UACR,SAAS;UACT,UAAU;;AAGZ,YAAY,kBAAkB,sBAAsB;;AAGpD,YAAY,SAAS;UACV,aAAa,SAAS;;;AAIjC,YAAY,SAAS;UACV,aAAa,SAAS;;;AAIjC,YAAY,UAAU;UACX,aAAa,SAAS;;UAIvB,SAAS;UACR,MAAM;;;AAIjB,YAAY,MAAM,UAAU,WAAW,YAAY;UACxC,aAAa,SAAS;UACtB,OAAO;;;AAIlB,YAAY,MAAM;UACP,aAAa,SAAS;UACtB,SAAS,WAAW;UACpB;;;AAIX,YAAY,SAAS,UAAU,WAAW,YAAY;UAC3C,aAAa,SAAS;UACtB,MAAM;;;AAIjB,YAAY,UAAU;UACX,aAAa,SAAS;;AAGjC,YAAY,SAAS;UACV,aAAa,SAAS;;AAGjC,YAAY,WAAW;UACZ,aAAa,SAAS;;AAGjC,YAAY,YAAY;UACb,aAAa,SAAS;;AAGjC,YAAY,cAAc;UACf,aAAa,SAAS;;AAGjC,YAAY,UAAU;UACX,aAAa,SAAS;;;AAIjC,YAAY,OACR,QACA,UACA,SACA,SACA,WACA,YACA,cACA,WACA,MACA,SACA,UACA;;AAGJ,OAAO,cAAMA,QAAQ;;AAErB,OAAO,cAAMC,QAAQ;;AAErB,OAAO,cAAMC,SAAS;;AAEtB,OAAO,cAAMC,SAAS;;AAEtB,OAAO,cAAMC,aAAa;;AAM1B,OAAO,cAAM,QAAS,UAAU,UAAU,MAAM,MAAI,MAAM;;AAU1D,OAAO,cAAM,WAAY,UAAU,UAAU,MAAM,MAAI,SAAS","names":["String: String","Double: Double","Boolean: Boolean","Unknown: Unknown","ResourceRef: ResourceRef"],"sources":["../../src/primitives.ts"],"version":3,"file":"primitives.d.ts"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palantir/pack.schema",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "API package for PACK schema functionality",
   "license": "Apache-2.0",
   "repository": {

package/src/defineMigration.ts

@@ -27,6 +27,11 @@ export type ReturnedSchema = ModelDefs;
 /** Soon to be deprecated - use `ModelDefs` instead. */
 export type Schema<T extends ModelDefs> = T;
 
+/**
+ * The set of builders handed to a {@link SchemaUpdate} callback — one
+ * {@link RecordBuilder} or {@link UnionBuilder} per existing model, keyed by
+ * model name. Mutate the ones you're changing and return the results.
+ */
 export type SchemaBuilder<T extends ModelDefs> = {
   [k in keyof T]: T[k] extends UnionDef<infer R> ? UnionBuilder<R>
     : T[k] extends RecordDef<infer R> ? RecordBuilder<R>
@@ -43,31 +48,47 @@ export type SchemaBuilder<T extends ModelDefs> = {
  * parameter.
  */
 export interface UpgradeFieldOptions<TOld extends Record<string, unknown>> {
+  /**
+   * The existing fields this new field is derived from. The runtime read lens
+   * uses this to know when to back-fill the field for records written by an
+   * older version; the app supplies the actual upgrade function at boot.
+   */
   readonly derivedFrom: ReadonlyArray<keyof TOld & string>;
 }
 
+/** Options passed as the third argument to {@link RecordBuilder.addField}. */
 export type FieldOptions = UpgradeFieldOptions<Record<string, unknown>>;
 
+/** Evolves a record within a {@link SchemaUpdate}. Obtain one from the {@link SchemaBuilder} and finish with `build()`. */
 export interface RecordBuilder<T extends Record<string, Type>> {
   // TODO: builders should support arg types and resolveModels to refs
+  /**
+   * Add a field. Pass `{ derivedFrom }` so the SDK can back-fill it when
+   * reading records written before this field existed.
+   */
   addField<const K extends string, V extends Type>(
     name: K,
     type: V,
     options?: FieldOptions,
   ): RecordBuilder<T & { [k in K]: V }>;
+  /** Mark a field deprecated, with an optional message pointing at its replacement. */
   deprecateField<K extends keyof T & string>(
     name: K,
     message?: string,
   ): RecordBuilder<T>;
+  /** Produce the updated {@link RecordDef}. */
   build(): RecordDef<T>;
 }
 
+/** Evolves a union within a {@link SchemaUpdate}. Obtain one from the {@link SchemaBuilder} and finish with `build()`. */
 export interface UnionBuilder<S extends UnionVariants> {
   // TODO: builders should support arg types and resolveModels to refs
+  /** Add a variant, referencing a record (or a `Ref` to one). */
   addVariant<const K extends string>(
     name: K,
     modelDefOrRef: UnionVariantArg,
   ): UnionBuilder<S & { [k in K]: Ref }>;
+  /** Produce the updated {@link UnionDef}. */
   build(): UnionDef<S>;
 }
 
@@ -312,6 +333,14 @@ export function applyMigration<
   };
 }
 
+/**
+ * Lower-level alternative to the {@link nextSchema}/{@link defineSchemaUpdate}
+ * chain: apply a migration callback and return only the merged models, dropping
+ * the per-field upgrade and deprecation metadata.
+ *
+ * @deprecated Use the {@link nextSchema}/{@link defineSchemaUpdate} chain to
+ * build versioned schemas. This function will be removed in a future version.
+ */
 export function defineMigration<
   const T extends ModelDefs,
   const S extends ModelDefs,

package/src/defineRecord.ts

@@ -64,6 +64,22 @@ function resolveFieldArg<T extends FieldArg>(value: T): ResolvedFieldArg<T> {
   return resolved as ResolvedFieldArg<T>;
 }
 
+/**
+ * Define a **record**: a named set of typed fields, the basic building block of
+ * a schema.
+ *
+ * Each field's type is a primitive ({@link String}, {@link Double}, …), a
+ * composite ({@link Optional}, {@link Array}), or a reference to another record
+ * or union — passed directly, or as `() => Model` for forward references.
+ *
+ * @example
+ * ```ts
+ * const ShapeBox = defineRecord("ShapeBox", {
+ *   docs: "A box.",
+ *   fields: { top: Double, left: Double, color: Optional(String) },
+ * });
+ * ```
+ */
 export function defineRecord<const T extends FieldArgs>(
   name: string,
   record: RecordArgs<T>,

package/src/defineSchemaUpdate.ts

@@ -19,6 +19,7 @@ import { applyMigration } from "./defineMigration.js";
 import type { ModelDefs } from "./defs.js";
 import { isRecordDef } from "./utils.js";
 
+/** Version 1 of a schema, produced by {@link defineSchema}. */
 export interface InitialSchema<T extends ModelDefs = ModelDefs> {
   readonly type: "initial";
   readonly version: 1;
@@ -37,6 +38,7 @@ export interface FieldDeprecationInfo {
 }
 export type VersionDeprecations = Record<string, Record<string, FieldDeprecationInfo>>;
 
+/** Version 2 or later of a schema, produced by {@link nextSchema}. Links back to the `previous` version. */
 export interface VersionedSchema<T extends ModelDefs = ModelDefs> {
   readonly type: "versioned";
   readonly models: T;
@@ -46,19 +48,48 @@ export interface VersionedSchema<T extends ModelDefs = ModelDefs> {
   readonly deprecations?: VersionDeprecations;
 }
 
+/** Any version of a schema: the {@link InitialSchema} (v1) or a {@link VersionedSchema} (v2+). */
 export type SchemaDefinition<T extends ModelDefs = ModelDefs> =
   | InitialSchema<T>
   | VersionedSchema<T>;
 
+/**
+ * Define version 1 of a schema from its initial set of models (records and
+ * unions). Later versions extend it via {@link nextSchema} and
+ * {@link defineSchemaUpdate}.
+ *
+ * @example
+ * ```ts
+ * const schemaV1 = defineSchema({ ShapeBox, NodeShape });
+ * ```
+ */
 export function defineSchema<T extends ModelDefs>(models: T): InitialSchema<T> {
   return { type: "initial", version: 1, models };
 }
 
+/** A named schema change created by {@link defineSchemaUpdate} and applied with {@link SchemaVersionBuilder.addSchemaUpdate}. */
 export interface SchemaUpdate<T extends ModelDefs, S extends ModelDefs> {
   readonly name: string;
   readonly migration: (schema: SchemaBuilder<T>) => S;
 }
 
+/**
+ * Define a named, reusable schema change. The callback receives a
+ * {@link SchemaBuilder} — one builder per existing model — and returns the
+ * records and unions it changed or added.
+ *
+ * @param name - A stable identifier for this change, used to track the migration.
+ * @example
+ * ```ts
+ * const splitColor = defineSchemaUpdate("splitColor", schema => {
+ *   const ShapeBox = schema.ShapeBox
+ *     .addField("fillColor", Optional(String), { derivedFrom: ["color"] })
+ *     .deprecateField("color", "Use fillColor instead.")
+ *     .build();
+ *   return { ShapeBox };
+ * });
+ * ```
+ */
 export function defineSchemaUpdate<T extends ModelDefs, S extends ModelDefs>(
   name: string,
   migration: (schema: SchemaBuilder<T>) => S,
@@ -66,11 +97,15 @@ export function defineSchemaUpdate<T extends ModelDefs, S extends ModelDefs>(
   return { name, migration };
 }
 
+/** Accumulates {@link SchemaUpdate}s onto the previous version. Create one with {@link nextSchema} and finish with `build()`. */
 export interface SchemaVersionBuilder<T extends ModelDefs> {
+  /** Apply a named change from {@link defineSchemaUpdate} to this version. */
   addSchemaUpdate<S extends ModelDefs>(
     update: SchemaUpdate<T, S>,
   ): SchemaVersionBuilder<T & S>;
+  /** Attach explicit field migrations, supplementing the `derivedFrom` sugar on `addField`. */
   withMigrations(migrations: VersionMigrations): SchemaVersionBuilder<T>;
+  /** Produce the finished {@link VersionedSchema}. */
   build(): VersionedSchema<T>;
 }
 
@@ -215,6 +250,15 @@ class SchemaVersionBuilderImpl<T extends ModelDefs> implements SchemaVersionBuil
   }
 }
 
+/**
+ * Start building the next version of a schema. Chain {@link SchemaVersionBuilder.addSchemaUpdate}
+ * calls and finish with `build()`; the new version is the previous one's plus one.
+ *
+ * @example
+ * ```ts
+ * const schemaV2 = nextSchema(schemaV1).addSchemaUpdate(splitColor).build();
+ * ```
+ */
 export function nextSchema<T extends ModelDefs>(
   previous: SchemaDefinition<T>,
 ): SchemaVersionBuilder<T> {

package/src/defineUnion.ts

@@ -39,6 +39,20 @@ export type UnionArgs<T extends UnionVariantArgs> = {
   readonly variants: T;
 };
 
+/**
+ * Define a **union**: a discriminated choice between several record variants. A
+ * value of the union is exactly one of its variants, tagged by the
+ * `discriminant` field (default `"type"`).
+ *
+ * @example
+ * ```ts
+ * const NodeShape = defineUnion("NodeShape", {
+ *   discriminant: "shapeType",
+ *   docs: "The shape of a node.",
+ *   variants: { box: ShapeBox, circle: ShapeCircle },
+ * });
+ * ```
+ */
 export function defineUnion<const TVariants extends UnionVariantArgs>(
   name: string,
   {

package/src/primitives.ts

@@ -31,14 +31,17 @@ export const TypeKind = {
 
 export type TypeKind = typeof TypeKind[keyof typeof TypeKind];
 
+/** A UTF-8 string field. */
 export type String = {
   readonly type: typeof TypeKind.STRING;
 };
 
+/** A double-precision floating point number field. */
 export type Double = {
   readonly type: typeof TypeKind.DOUBLE;
 };
 
+/** A boolean field. */
 export type Boolean = {
   readonly type: typeof TypeKind.BOOLEAN;
 };
@@ -48,23 +51,26 @@ interface TypeBase {
   readonly type: TypeKind;
 }
 
+/** A list of `T`. Nested arrays are not supported — wrap the inner array in a record. */
 export type Array<T extends TypeBase = TypeBase> = {
   readonly type: typeof TypeKind.ARRAY;
   readonly items: T;
 };
 
-// A reference to a record or a union type
+/** A reference to another record or union in the same schema. */
 export type Ref = {
   readonly type: typeof TypeKind.REF;
   readonly refType: "record" | "union"; // TODO: do we care?
   readonly name: string;
 };
 
+/** A `T` that may be absent. Nested optionals are not supported. */
 export type Optional<T extends TypeBase = TypeBase> = {
   readonly type: typeof TypeKind.OPTIONAL;
   readonly item: T;
 };
 
+/** An opaque, arbitrary JSON value. */
 export type Unknown = {
   readonly type: typeof TypeKind.UNKNOWN;
 };
@@ -89,6 +95,7 @@ export type UserRef = {
   readonly type: typeof TypeKind.USER_REF;
 };
 
+/** Any valid field type: a primitive, a composite (`Array`/`Optional`), or a `Ref`. */
 export type Type =
   | Array
   | Boolean
@@ -103,15 +110,21 @@ export type Type =
   | Unknown
   | UserRef;
 
+/** A UTF-8 string field. */
 export const String: String = { type: TypeKind.STRING };
+/** A double-precision floating point number field. */
 export const Double: Double = { type: TypeKind.DOUBLE };
+/** A boolean field. */
 export const Boolean: Boolean = { type: TypeKind.BOOLEAN };
+/** An opaque, arbitrary JSON value. */
 export const Unknown: Unknown = { type: TypeKind.UNKNOWN };
+/** A reference to a Foundry resource. */
 export const ResourceRef: ResourceRef = { type: TypeKind.RESOURCE_REF };
 function unwrapOneOptional(t: TypeBase): TypeBase {
   return t.type === TypeKind.OPTIONAL && "item" in t ? (t as { item: TypeBase }).item : t;
 }
 
+/** Build an array field whose elements are `item`. */
 export const Array = <T extends TypeBase>(item: T): Array<T> => {
   if (unwrapOneOptional(item).type === TypeKind.ARRAY) {
     throw new Error(
@@ -121,6 +134,7 @@ export const Array = <T extends TypeBase>(item: T): Array<T> => {
   }
   return { type: TypeKind.ARRAY, items: item };
 };
+/** Build an optional field wrapping `item`, marking it as possibly absent. */
 export const Optional = <T extends TypeBase>(item: T): Optional<T> => {
   if (item.type === TypeKind.OPTIONAL) {
     throw new Error("Nested optionals (Optional(Optional(...))) are not supported.");