@project-ajax/sdk 0.0.71 → 0.0.74

package/dist/builder.d.ts

@@ -1,5 +1,5 @@
 import type { NoticonName } from "./icon-names.js";
-import type { Icon, NoticonColor, PeopleValue, PlaceValue, TextValue } from "./types.js";
+import type { Icon, NoticonColor, PeopleValue, PlaceValue, RelationReference, TextValue } from "./types.js";
 /**
  * Creates a rich text value.
  */
@@ -83,6 +83,21 @@ export declare function people(...emails: string[]): PeopleValue;
  * @param value - The place value with lat/lon coordinates and optional name/address
  */
 export declare function place(value: PlaceValue): PlaceValue;
+/**
+ * Creates a relation reference from a primary key of a related record.
+ * Use an array of relation references as the property value.
+ *
+ * @param primaryKey - The primary key of the related record
+ * @example
+ * ```typescript
+ * // Single relation
+ * { Project: [Builder.relation("project-123")] }
+ *
+ * // Multiple relations
+ * { Projects: [Builder.relation("project-123"), Builder.relation("project-456")] }
+ * ```
+ */
+export declare function relation(primaryKey: string): RelationReference;
 /**
  * Creates an emoji icon.
  * @param emoji - An emoji string (e.g., "🎯", "✨", "🚀")

package/dist/builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAEX,IAAI,EACJ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,SAAS,EACT,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAEnD;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAE1C;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAEhD;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAE/C;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAE9C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAEpD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAElE;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAK/C;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CASlD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAYjE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAWvE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC5B,SAAS,EAAE,IAAI,EACf,OAAO,EAAE,IAAI,EACb,QAAQ,CAAC,EAAE,MAAM,GACf,SAAS,CAcX;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAEhE;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAE/C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAK1D;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAE/C;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,WAAW,CAEvD;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAKnD;AA4CD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAK7C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,WAAW,EACjB,KAAK,GAAE,YAAqB,GAC1B,IAAI,CAMN;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAK3C"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAEX,IAAI,EACJ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,SAAS,EACT,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAEnD;AAED;;GAEG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAE1C;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAEhD;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAE/C;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAE9C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAEpD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAElE;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAK/C;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CASlD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAYjE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAWvE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC5B,SAAS,EAAE,IAAI,EACf,OAAO,EAAE,IAAI,EACb,QAAQ,CAAC,EAAE,MAAM,GACf,SAAS,CAcX;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAEhE;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAE/C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAK1D;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAE/C;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,WAAW,CAEvD;AAED;;;GAGG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAKnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAE9D;AA4CD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAK7C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,WAAW,EACjB,KAAK,GAAE,YAAqB,GAC1B,IAAI,CAMN;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAK3C"}

package/dist/builder.js

@@ -94,6 +94,9 @@ function place(value) {
   }
   return value;
 }
+function relation(primaryKey) {
+  return { type: "primaryKey", value: primaryKey };
+}
 function validateDateString(dateString) {
   if (!/^\d{4}-\d{2}-\d{2}$/.test(dateString)) {
     throw new Error(
@@ -155,6 +158,7 @@ export {
   people,
   phoneNumber,
   place,
+  relation,
   richText,
   select,
   status,

package/dist/capabilities/sync.d.ts

@@ -1,5 +1,5 @@
 import type { PropertyConfiguration, PropertySchema, Schema } from "../schema.js";
-import type { Icon, PeopleValue, PlaceValue, Schedule, SyncSchedule, TextValue } from "../types.js";
+import type { Icon, PeopleValue, PlaceValue, RelationValue, Schedule, SyncSchedule, TextValue } from "../types.js";
 /**
  * Maps a property configuration to its corresponding value type.
  */
@@ -7,7 +7,9 @@ type PropertyValueType<T extends PropertyConfiguration> = T extends {
     type: "people";
 } ? PeopleValue : T extends {
     type: "place";
-} ? PlaceValue : TextValue;
+} ? PlaceValue : T extends {
+    type: "relation";
+} ? RelationValue : TextValue;
 /**
  * Sync mode determines how the sync handles data lifecycle.
  */
@@ -148,6 +150,13 @@ export type SyncHandlerResult<PK extends string, Context = unknown> = {
     mode?: SyncMode;
 };
 export type SyncCapability = ReturnType<typeof createSyncCapability>;
+/**
+ * Context object passed from the runtime to sync capability handlers.
+ */
+type RuntimeContext<UserContext = unknown> = {
+    /** The user-defined/-controlled context (cursor, pagination state, etc.) */
+    userContext?: UserContext;
+};
 /**
  * Creates a special handler for syncing third-party data to a collection.
  *
@@ -164,10 +173,10 @@ export declare function createSyncCapability<PK extends string, S extends Schema
         mode: SyncMode | undefined;
         schedule: SyncSchedule;
     };
-    handler(context?: Context): Promise<{
+    handler(runtimeContext?: RuntimeContext<Context>): Promise<{
         changes: SyncChange<PK, PropertySchema<PK>>[];
         hasMore: boolean;
-        nextContext: Context | undefined;
+        nextUserContext: Context | undefined;
     }>;
 };
 export {};

package/dist/capabilities/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/capabilities/sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/capabilities/sync.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/sync.js

@@ -9,14 +9,15 @@ function createSyncCapability(key, syncConfiguration) {
       mode: syncConfiguration.mode,
       schedule: parseSchedule(syncConfiguration.schedule)
     },
-    async handler(context) {
-      const executionResult = await syncConfiguration.execute(context).catch((err) => {
+    async handler(runtimeContext) {
+      const userContext = runtimeContext?.userContext;
+      const executionResult = await syncConfiguration.execute(userContext).catch((err) => {
         throw new ExecutionError(err);
       });
       const result = {
         changes: executionResult.changes,
         hasMore: executionResult.hasMore,
-        nextContext: executionResult.nextContext
+        nextUserContext: executionResult.nextContext
       };
       process.stdout.write(`
 <output>${JSON.stringify(result)}</output>

package/dist/capabilities/sync.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sync.test.d.ts.map

package/dist/capabilities/sync.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.test.d.ts","sourceRoot":"","sources":["../../src/capabilities/sync.test.ts"],"names":[],"mappings":""}

package/dist/schema.d.ts

@@ -45,6 +45,13 @@ export type PropertyConfiguration = {
     type: "people";
 } | {
     type: "place";
+} | {
+    type: "relation";
+    /**
+     * The export name of the sync capability that defines the related collection.
+     * This must match the export name used when defining the related sync capability.
+     */
+    relatedSyncKey: string;
 };
 export type Schema<PK extends string> = {
     /**
@@ -128,4 +135,25 @@ export declare function people(): PropertyConfiguration;
  * Creates a place property definition for storing geographic locations.
  */
 export declare function place(): PropertyConfiguration;
+/**
+ * Creates a relation property definition that references another sync capability.
+ * The related collection must be defined by a sync capability in the same worker.
+ *
+ * @param relatedSyncKey - The export name of the sync capability that defines the related collection.
+ * @example
+ * ```typescript
+ * export const projectsSync = sync({...});
+ *
+ * export const tasksSync = sync({
+ *   schema: {
+ *     properties: {
+ *       "Task Title": Schema.title(),
+ *       "Project": Schema.relation("projectsSync"),
+ *     },
+ *   },
+ *   ...
+ * });
+ * ```
+ */
+export declare function relation(relatedSyncKey: string): PropertyConfiguration;
 //# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema.js

@@ -40,6 +40,9 @@ function people() {
 function place() {
   return { type: "place" };
 }
+function relation(relatedSyncKey) {
+  return { type: "relation", relatedSyncKey };
+}
 export {
   checkbox,
   date,
@@ -50,6 +53,7 @@ export {
   people,
   phoneNumber,
   place,
+  relation,
   richText,
   select,
   status,

package/dist/types.d.ts

@@ -162,6 +162,18 @@ export interface PlaceValue {
      */
     googlePlaceId?: string;
 }
+/**
+ * A reference to a related record by its primary key.
+ */
+export type RelationReference = {
+    type: "primaryKey";
+    value: string;
+};
+/**
+ * Relation value representing references to related records.
+ * Each reference identifies a record in the target collection.
+ */
+export type RelationValue = RelationReference[];
 /**
  * Time units for schedule intervals.
  * - "m": minutes

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/sdk",
-	"version": "0.0.71",
+	"version": "0.0.74",
 	"description": "An SDK for building workers for the Project Ajax platform",
 	"license": "UNLICENSED",
 	"type": "module",

package/src/builder.ts

@@ -5,6 +5,7 @@ import type {
 	NoticonColor,
 	PeopleValue,
 	PlaceValue,
+	RelationReference,
 	TextValue,
 } from "./types.js";
 
@@ -199,6 +200,24 @@ export function place(value: PlaceValue): PlaceValue {
 	return value;
 }
 
+/**
+ * Creates a relation reference from a primary key of a related record.
+ * Use an array of relation references as the property value.
+ *
+ * @param primaryKey - The primary key of the related record
+ * @example
+ * ```typescript
+ * // Single relation
+ * { Project: [Builder.relation("project-123")] }
+ *
+ * // Multiple relations
+ * { Projects: [Builder.relation("project-123"), Builder.relation("project-456")] }
+ * ```
+ */
+export function relation(primaryKey: string): RelationReference {
+	return { type: "primaryKey", value: primaryKey };
+}
+
 /**
  * Validates a date string is in YYYY-MM-DD format and represents a valid date.
  */

package/src/capabilities/sync.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import * as Builder from "../builder.js";
+import * as Schema from "../schema.js";
+import { createSyncCapability } from "./sync.js";
+
+describe("Worker.sync", () => {
+	describe("Schema.relation", () => {
+		it("creates a relation property configuration", () => {
+			const relationProp = Schema.relation("projectsSync");
+
+			expect(relationProp).toEqual({
+				type: "relation",
+				relatedSyncKey: "projectsSync",
+			});
+		});
+
+		it("can be used in a schema definition", () => {
+			const capability = createSyncCapability("tasksSync", {
+				primaryKeyProperty: "Task ID",
+				schema: {
+					defaultName: "Tasks",
+					properties: {
+						"Task ID": Schema.title(),
+						Project: Schema.relation("projectsSync"),
+					},
+				},
+				execute: async () => ({
+					changes: [],
+					hasMore: false,
+				}),
+			});
+
+			expect(capability.config.schema.properties.Project).toEqual({
+				type: "relation",
+				relatedSyncKey: "projectsSync",
+			});
+		});
+	});
+
+	describe("Builder.relation", () => {
+		it("creates a relation reference from a primary key", () => {
+			const value = Builder.relation("project-123");
+
+			expect(value).toEqual({ type: "primaryKey", value: "project-123" });
+		});
+
+		it("can be used to build relation arrays", () => {
+			const value = [
+				Builder.relation("project-123"),
+				Builder.relation("project-456"),
+			];
+
+			expect(value).toEqual([
+				{ type: "primaryKey", value: "project-123" },
+				{ type: "primaryKey", value: "project-456" },
+			]);
+		});
+	});
+
+	describe("SyncedObject with relation properties", () => {
+		it("allows relation values in synced objects", async () => {
+			const capability = createSyncCapability("tasksSync", {
+				primaryKeyProperty: "Task ID",
+				schema: {
+					defaultName: "Tasks",
+					properties: {
+						"Task ID": Schema.title(),
+						Project: Schema.relation("projectsSync"),
+					},
+				},
+				execute: async () => ({
+					changes: [
+						{
+							type: "upsert",
+							key: "task-1",
+							properties: {
+								"Task ID": Builder.title("TASK-001"),
+								Project: [Builder.relation("project-123")],
+							},
+						},
+						{
+							type: "upsert",
+							key: "task-2",
+							properties: {
+								"Task ID": Builder.title("TASK-002"),
+								Project: [
+									Builder.relation("project-123"),
+									Builder.relation("project-456"),
+								],
+							},
+						},
+					],
+					hasMore: false,
+				}),
+			});
+
+			// Verify the capability is properly configured
+			expect(capability._tag).toBe("sync");
+			expect(capability.config.primaryKeyProperty).toBe("Task ID");
+		});
+	});
+});

package/src/capabilities/sync.ts

@@ -8,6 +8,7 @@ import type {
 	Icon,
 	PeopleValue,
 	PlaceValue,
+	RelationValue,
 	Schedule,
 	SyncSchedule,
 	TextValue,
@@ -23,7 +24,9 @@ type PropertyValueType<T extends PropertyConfiguration> = T extends {
 	? PeopleValue
 	: T extends { type: "place" }
 		? PlaceValue
-		: TextValue;
+		: T extends { type: "relation" }
+			? RelationValue
+			: TextValue;
 
 /**
  * Sync mode determines how the sync handles data lifecycle.
@@ -188,6 +191,14 @@ export type SyncHandlerResult<PK extends string, Context = unknown> = {
 
 export type SyncCapability = ReturnType<typeof createSyncCapability>;
 
+/**
+ * Context object passed from the runtime to sync capability handlers.
+ */
+type RuntimeContext<UserContext = unknown> = {
+	/** The user-defined/-controlled context (cursor, pagination state, etc.) */
+	userContext?: UserContext;
+};
+
 /**
  * Creates a special handler for syncing third-party data to a collection.
  *
@@ -209,9 +220,10 @@ export function createSyncCapability<
 			mode: syncConfiguration.mode,
 			schedule: parseSchedule(syncConfiguration.schedule),
 		},
-		async handler(context?: Context) {
+		async handler(runtimeContext?: RuntimeContext<Context>) {
+			const userContext = runtimeContext?.userContext;
 			const executionResult = await syncConfiguration
-				.execute(context)
+				.execute(userContext)
 				.catch((err) => {
 					throw new ExecutionError(err);
 				});
@@ -219,7 +231,7 @@ export function createSyncCapability<
 			const result = {
 				changes: executionResult.changes,
 				hasMore: executionResult.hasMore,
-				nextContext: executionResult.nextContext,
+				nextUserContext: executionResult.nextContext,
 			};
 
 			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);

package/src/schema.ts

@@ -64,7 +64,15 @@ export type PropertyConfiguration =
 			groups: StatusGroup[];
 	  }
 	| { type: "people" }
-	| { type: "place" };
+	| { type: "place" }
+	| {
+			type: "relation";
+			/**
+			 * The export name of the sync capability that defines the related collection.
+			 * This must match the export name used when defining the related sync capability.
+			 */
+			relatedSyncKey: string;
+	  };
 
 export type Schema<PK extends string> = {
 	/**
@@ -191,3 +199,27 @@ export function people(): PropertyConfiguration {
 export function place(): PropertyConfiguration {
 	return { type: "place" };
 }
+
+/**
+ * Creates a relation property definition that references another sync capability.
+ * The related collection must be defined by a sync capability in the same worker.
+ *
+ * @param relatedSyncKey - The export name of the sync capability that defines the related collection.
+ * @example
+ * ```typescript
+ * export const projectsSync = sync({...});
+ *
+ * export const tasksSync = sync({
+ *   schema: {
+ *     properties: {
+ *       "Task Title": Schema.title(),
+ *       "Project": Schema.relation("projectsSync"),
+ *     },
+ *   },
+ *   ...
+ * });
+ * ```
+ */
+export function relation(relatedSyncKey: string): PropertyConfiguration {
+	return { type: "relation", relatedSyncKey };
+}

package/src/types.ts

@@ -226,6 +226,20 @@ export interface PlaceValue {
 	googlePlaceId?: string;
 }
 
+/**
+ * A reference to a related record by its primary key.
+ */
+export type RelationReference = {
+	type: "primaryKey";
+	value: string;
+};
+
+/**
+ * Relation value representing references to related records.
+ * Each reference identifies a record in the target collection.
+ */
+export type RelationValue = RelationReference[];
+
 /**
  * Time units for schedule intervals.
  * - "m": minutes