@unito/integration-api 8.0.9 → 8.2.0

package/dist/src/fieldHelpers.d.ts

@@ -1,4 +1,4 @@
-import { FieldSchema, FieldValues, Semantic } from './types.js';
+import { FieldSchema, FieldValues, ResolveItem, Semantic } from './types.js';
 declare const ValidFieldValueEntryBrand: unique symbol;
 /**
  * A single field value that has been validated against its FieldSchema.
@@ -33,19 +33,21 @@ export declare function getUnsafeValue<T = unknown>(field: FieldSchema, values:
 export declare function getSafeValue<T = unknown>(field: FieldSchema, values: FieldValues): ReturnType<typeof getUnsafeValue<T>> | undefined;
 /**
  * Returns a field value by its name, traversing dotted paths through OBJECT and REFERENCE fields.
+ *
+ * Pass options.resolveItem to resolve any RelationPointer crossed along the path by fetching the pointed item.
  */
-export declare function findValueByName<T = unknown>(fields: FieldSchema[], values: FieldValues, fieldName: string): ReturnType<typeof getSafeValue<T>>;
-interface InheritedFieldProperties {
-    isArray?: boolean | undefined;
-    canSetOnCreate?: boolean | undefined;
-    canSetOnUpdate?: boolean | undefined;
-    nullable?: boolean | undefined;
-}
+export declare function findValueByName<T = unknown>(fields: FieldSchema[], values: FieldValues, fieldName: string, options?: {
+    resolveItem?: ResolveItem;
+}): Promise<ReturnType<typeof getSafeValue<T>>>;
 /**
  * Returns a field schema by its name, traversing dotted paths through OBJECT and REFERENCE fields.
  * Also accepts `semantic:` prefixed names and sanitized names (see sanitizeFieldName).
+ *
+ * Pass options.resolveItem to resolve any RelationPointer crossed along the path by fetching the pointed item.
  */
-export declare function findFieldByName(fields: FieldSchema[], fieldName: string, inheritedProperties?: InheritedFieldProperties): FieldSchema | undefined;
+export declare function findFieldByName(fields: FieldSchema[], fieldName: string, options?: {
+    resolveItem?: ResolveItem;
+}): Promise<FieldSchema | undefined>;
 /**
  * Returns a field schema by its semantic.
  *

package/dist/src/fieldHelpers.js

@@ -1,4 +1,4 @@
-import { FieldValueTypes, Semantics } from './types.js';
+import { FieldValueTypes, Semantics, } from './types.js';
 import { isItemSummary, isObject, isRelationPointer } from './guards.js';
 /**
  * Escapes characters that would otherwise break dotted field name path parsing.
@@ -168,20 +168,40 @@ export function getSafeValue(field, values) {
         return undefined;
     }
 }
+/**
+ * Returns the field schemas behind a REFERENCE field, resolving a RelationPointer through options.resolveItem.
+ * Returns undefined when the pointer cannot be resolved.
+ *
+ * @throws Error if the reference is an unpopulated RelationPointer and no resolveItem is provided.
+ */
+async function resolveReferenceFields(field, fields, options) {
+    if (isRelationPointer(field.reference)) {
+        if (!options.resolveItem) {
+            throw new Error(`Reference field "${field.name}" is a relation pointer that was not populated`);
+        }
+        const { itemPath, relationName } = field.reference;
+        const item = await options.resolveItem(itemPath);
+        const relation = item?.relations.find(relation => relation.name === relationName);
+        return relation?.schema.fields;
+    }
+    return field.reference.schema === '__self' ? fields : field.reference.schema.fields;
+}
 /**
  * Returns a field value by its name, traversing dotted paths through OBJECT and REFERENCE fields.
+ *
+ * Pass options.resolveItem to resolve any RelationPointer crossed along the path by fetching the pointed item.
  */
-export function findValueByName(fields, values, fieldName) {
+export async function findValueByName(fields, values, fieldName, options = {}) {
     const [baseFieldName, ...subFieldNames] = fieldName.split('.');
     if (baseFieldName === undefined) {
         return undefined;
     }
-    const baseField = findFieldByName(fields, baseFieldName);
+    const baseField = await findFieldByName(fields, baseFieldName, options);
     if (!baseField) {
         if (subFieldNames.length === 0) {
             return undefined;
         }
-        const literalField = findFieldByName(fields, fieldName);
+        const literalField = await findFieldByName(fields, fieldName, options);
         return literalField ? getSafeValue(literalField, values) : undefined;
     }
     const baseFieldValue = getSafeValue(baseField, values);
@@ -191,30 +211,30 @@ export function findValueByName(fields, values, fieldName) {
     if (baseField.type === FieldValueTypes.OBJECT) {
         const subFieldName = subFieldNames.join('.');
         if (isObject(baseFieldValue)) {
-            return findValueByName(baseField.fields, baseFieldValue, subFieldName);
+            return findValueByName(baseField.fields, baseFieldValue, subFieldName, options);
         }
         if (Array.isArray(baseFieldValue)) {
-            return baseFieldValue
-                .map(value => (isObject(value) ? findValueByName(baseField.fields, value, subFieldName) : undefined))
-                .filter(value => value !== undefined);
+            const resolved = await Promise.all(baseFieldValue.map(value => isObject(value) ? findValueByName(baseField.fields, value, subFieldName, options) : undefined));
+            return resolved.filter(value => value !== undefined);
         }
     }
     if (baseField.type === FieldValueTypes.REFERENCE) {
-        if (isRelationPointer(baseField.reference)) {
-            throw new Error(`Reference field "${baseField.name}" is a relation pointer that was not populated`);
+        const referenceFields = await resolveReferenceFields(baseField, fields, options);
+        if (!referenceFields) {
+            return undefined;
         }
         if (subFieldNames[0] === 'fields' && subFieldNames.length > 1) {
             subFieldNames.shift();
         }
         const subFieldName = subFieldNames.join('.');
-        const referenceFields = baseField.reference.schema === '__self' ? fields : baseField.reference.schema.fields;
         if (isItemSummary(baseFieldValue)) {
-            return findValueByName(referenceFields, baseFieldValue.fields ?? {}, subFieldName);
+            return findValueByName(referenceFields, baseFieldValue.fields ?? {}, subFieldName, options);
         }
         if (Array.isArray(baseFieldValue)) {
-            return baseFieldValue
-                .map(value => isItemSummary(value) ? findValueByName(referenceFields, value.fields ?? {}, subFieldName) : undefined)
-                .filter(value => value !== undefined);
+            const resolved = await Promise.all(baseFieldValue.map(value => isItemSummary(value)
+                ? findValueByName(referenceFields, value.fields ?? {}, subFieldName, options)
+                : undefined));
+            return resolved.filter(value => value !== undefined);
         }
     }
     return undefined;
@@ -246,8 +266,13 @@ function mergeInheritedProperties(field, inherited) {
 /**
  * Returns a field schema by its name, traversing dotted paths through OBJECT and REFERENCE fields.
  * Also accepts `semantic:` prefixed names and sanitized names (see sanitizeFieldName).
+ *
+ * Pass options.resolveItem to resolve any RelationPointer crossed along the path by fetching the pointed item.
  */
-export function findFieldByName(fields, fieldName, inheritedProperties = {}) {
+export function findFieldByName(fields, fieldName, options = {}) {
+    return baseFindFieldByName(fields, fieldName, {}, options);
+}
+async function baseFindFieldByName(fields, fieldName, inheritedProperties, options) {
     const [baseFieldName, ...subFieldNames] = fieldName.split('.');
     if (baseFieldName === undefined) {
         return undefined;
@@ -266,26 +291,27 @@ export function findFieldByName(fields, fieldName, inheritedProperties = {}) {
             return baseField;
         }
         if (baseField.type === FieldValueTypes.OBJECT) {
-            return findFieldByName(baseField.fields, subFieldNames.join('.'), {
+            return baseFindFieldByName(baseField.fields, subFieldNames.join('.'), {
                 isArray: baseField.isArray,
                 canSetOnCreate: baseField.canSetOnCreate,
                 canSetOnUpdate: baseField.canSetOnUpdate,
                 nullable: baseField.nullable,
-            });
+            }, options);
         }
         if (baseField.type === FieldValueTypes.REFERENCE) {
-            if (isRelationPointer(baseField.reference)) {
-                throw new Error(`Reference field "${baseField.name}" is a relation pointer that was not populated`);
+            const referenceFields = await resolveReferenceFields(baseField, fields, options);
+            if (!referenceFields) {
+                return undefined;
             }
             if (subFieldNames[0] === 'fields' && subFieldNames.length > 1) {
                 subFieldNames.shift();
             }
-            return findFieldByName(baseField.reference.schema === '__self' ? fields : baseField.reference.schema.fields, subFieldNames.join('.'), {
+            return baseFindFieldByName(referenceFields, subFieldNames.join('.'), {
                 isArray: baseField.isArray,
                 canSetOnCreate: baseField.canSetOnCreate,
                 canSetOnUpdate: baseField.canSetOnUpdate,
                 nullable: baseField.nullable,
-            });
+            }, options);
         }
         return undefined;
     }

package/dist/src/index.cjs

@@ -874,20 +874,40 @@ function getSafeValue(field, values) {
         return undefined;
     }
 }
+/**
+ * Returns the field schemas behind a REFERENCE field, resolving a RelationPointer through options.resolveItem.
+ * Returns undefined when the pointer cannot be resolved.
+ *
+ * @throws Error if the reference is an unpopulated RelationPointer and no resolveItem is provided.
+ */
+async function resolveReferenceFields(field, fields, options) {
+    if (isRelationPointer(field.reference)) {
+        if (!options.resolveItem) {
+            throw new Error(`Reference field "${field.name}" is a relation pointer that was not populated`);
+        }
+        const { itemPath, relationName } = field.reference;
+        const item = await options.resolveItem(itemPath);
+        const relation = item?.relations.find(relation => relation.name === relationName);
+        return relation?.schema.fields;
+    }
+    return field.reference.schema === '__self' ? fields : field.reference.schema.fields;
+}
 /**
  * Returns a field value by its name, traversing dotted paths through OBJECT and REFERENCE fields.
+ *
+ * Pass options.resolveItem to resolve any RelationPointer crossed along the path by fetching the pointed item.
  */
-function findValueByName(fields, values, fieldName) {
+async function findValueByName(fields, values, fieldName, options = {}) {
     const [baseFieldName, ...subFieldNames] = fieldName.split('.');
     if (baseFieldName === undefined) {
         return undefined;
     }
-    const baseField = findFieldByName(fields, baseFieldName);
+    const baseField = await findFieldByName(fields, baseFieldName, options);
     if (!baseField) {
         if (subFieldNames.length === 0) {
             return undefined;
         }
-        const literalField = findFieldByName(fields, fieldName);
+        const literalField = await findFieldByName(fields, fieldName, options);
         return literalField ? getSafeValue(literalField, values) : undefined;
     }
     const baseFieldValue = getSafeValue(baseField, values);
@@ -897,30 +917,30 @@ function findValueByName(fields, values, fieldName) {
     if (baseField.type === FieldValueTypes.OBJECT) {
         const subFieldName = subFieldNames.join('.');
         if (isObject(baseFieldValue)) {
-            return findValueByName(baseField.fields, baseFieldValue, subFieldName);
+            return findValueByName(baseField.fields, baseFieldValue, subFieldName, options);
         }
         if (Array.isArray(baseFieldValue)) {
-            return baseFieldValue
-                .map(value => (isObject(value) ? findValueByName(baseField.fields, value, subFieldName) : undefined))
-                .filter(value => value !== undefined);
+            const resolved = await Promise.all(baseFieldValue.map(value => isObject(value) ? findValueByName(baseField.fields, value, subFieldName, options) : undefined));
+            return resolved.filter(value => value !== undefined);
         }
     }
     if (baseField.type === FieldValueTypes.REFERENCE) {
-        if (isRelationPointer(baseField.reference)) {
-            throw new Error(`Reference field "${baseField.name}" is a relation pointer that was not populated`);
+        const referenceFields = await resolveReferenceFields(baseField, fields, options);
+        if (!referenceFields) {
+            return undefined;
         }
         if (subFieldNames[0] === 'fields' && subFieldNames.length > 1) {
             subFieldNames.shift();
         }
         const subFieldName = subFieldNames.join('.');
-        const referenceFields = baseField.reference.schema === '__self' ? fields : baseField.reference.schema.fields;
         if (isItemSummary(baseFieldValue)) {
-            return findValueByName(referenceFields, baseFieldValue.fields ?? {}, subFieldName);
+            return findValueByName(referenceFields, baseFieldValue.fields ?? {}, subFieldName, options);
         }
         if (Array.isArray(baseFieldValue)) {
-            return baseFieldValue
-                .map(value => isItemSummary(value) ? findValueByName(referenceFields, value.fields ?? {}, subFieldName) : undefined)
-                .filter(value => value !== undefined);
+            const resolved = await Promise.all(baseFieldValue.map(value => isItemSummary(value)
+                ? findValueByName(referenceFields, value.fields ?? {}, subFieldName, options)
+                : undefined));
+            return resolved.filter(value => value !== undefined);
         }
     }
     return undefined;
@@ -952,8 +972,13 @@ function mergeInheritedProperties(field, inherited) {
 /**
  * Returns a field schema by its name, traversing dotted paths through OBJECT and REFERENCE fields.
  * Also accepts `semantic:` prefixed names and sanitized names (see sanitizeFieldName).
+ *
+ * Pass options.resolveItem to resolve any RelationPointer crossed along the path by fetching the pointed item.
  */
-function findFieldByName(fields, fieldName, inheritedProperties = {}) {
+function findFieldByName(fields, fieldName, options = {}) {
+    return baseFindFieldByName(fields, fieldName, {}, options);
+}
+async function baseFindFieldByName(fields, fieldName, inheritedProperties, options) {
     const [baseFieldName, ...subFieldNames] = fieldName.split('.');
     if (baseFieldName === undefined) {
         return undefined;
@@ -972,26 +997,27 @@ function findFieldByName(fields, fieldName, inheritedProperties = {}) {
             return baseField;
         }
         if (baseField.type === FieldValueTypes.OBJECT) {
-            return findFieldByName(baseField.fields, subFieldNames.join('.'), {
+            return baseFindFieldByName(baseField.fields, subFieldNames.join('.'), {
                 isArray: baseField.isArray,
                 canSetOnCreate: baseField.canSetOnCreate,
                 canSetOnUpdate: baseField.canSetOnUpdate,
                 nullable: baseField.nullable,
-            });
+            }, options);
         }
         if (baseField.type === FieldValueTypes.REFERENCE) {
-            if (isRelationPointer(baseField.reference)) {
-                throw new Error(`Reference field "${baseField.name}" is a relation pointer that was not populated`);
+            const referenceFields = await resolveReferenceFields(baseField, fields, options);
+            if (!referenceFields) {
+                return undefined;
             }
             if (subFieldNames[0] === 'fields' && subFieldNames.length > 1) {
                 subFieldNames.shift();
             }
-            return findFieldByName(baseField.reference.schema === '__self' ? fields : baseField.reference.schema.fields, subFieldNames.join('.'), {
+            return baseFindFieldByName(referenceFields, subFieldNames.join('.'), {
                 isArray: baseField.isArray,
                 canSetOnCreate: baseField.canSetOnCreate,
                 canSetOnUpdate: baseField.canSetOnUpdate,
                 nullable: baseField.nullable,
-            });
+            }, options);
         }
         return undefined;
     }
@@ -1016,7 +1042,7 @@ function findFieldBySemantic(fields, semantic) {
 /**
  * JSONPath parser that returns a relation that is guaranteed to have its schema populated.
  */
-function findRelationByJSONPath(item, query) {
+async function findRelationByJSONPath(item, query, options = {}) {
     const tokens = parseJSONPath(query);
     const schemas = [];
     let current = item;
@@ -1033,6 +1059,16 @@ function findRelationByJSONPath(item, query) {
             schemas.push(result['schema']);
         }
         current = result;
+        if (isRelationPointer(current) && options.resolveItem) {
+            const { itemPath, relationName } = current;
+            const item = await options.resolveItem(itemPath);
+            if (item) {
+                current = item.relations.find(relation => relation.name === relationName);
+            }
+            else {
+                return undefined;
+            }
+        }
     }
     if (isRelation(current, { strict: false })) {
         return current;

package/dist/src/jsonPathHelpers.d.ts

@@ -2,4 +2,6 @@ import * as Api from './types.js';
 /**
  * JSONPath parser that returns a relation that is guaranteed to have its schema populated.
  */
-export declare function findRelationByJSONPath(item: Api.Item, query: string): Api.Relation | Api.RelationWithPopulatedSchema<Api.RelationSummary> | Api.RelationWithPopulatedSchema<Api.ReferenceRelation> | undefined;
+export declare function findRelationByJSONPath(item: Api.Item, query: string, options?: {
+    resolveItem?: Api.ResolveItem;
+}): Promise<Api.Relation | Api.RelationWithPopulatedSchema<Api.RelationSummary> | Api.RelationWithPopulatedSchema<Api.ReferenceRelation> | undefined>;

package/dist/src/jsonPathHelpers.js

@@ -2,7 +2,7 @@ import * as Guards from './guards.js';
 /**
  * JSONPath parser that returns a relation that is guaranteed to have its schema populated.
  */
-export function findRelationByJSONPath(item, query) {
+export async function findRelationByJSONPath(item, query, options = {}) {
     const tokens = parseJSONPath(query);
     const schemas = [];
     let current = item;
@@ -19,6 +19,16 @@ export function findRelationByJSONPath(item, query) {
             schemas.push(result['schema']);
         }
         current = result;
+        if (Guards.isRelationPointer(current) && options.resolveItem) {
+            const { itemPath, relationName } = current;
+            const item = await options.resolveItem(itemPath);
+            if (item) {
+                current = item.relations.find(relation => relation.name === relationName);
+            }
+            else {
+                return undefined;
+            }
+        }
     }
     if (Guards.isRelation(current, { strict: false })) {
         return current;

package/dist/src/types.d.ts

@@ -365,6 +365,12 @@ export interface Item<T extends RelationSchema | undefined = undefined> {
      */
     canonicalPath: string;
 }
+/**
+ * Resolves a RelationPointer crossed by a schema-traversing helper (findRelationByJSONPath, findFieldByName,
+ * findValueByName) by fetching the pointed item. Each helper declares its own options object reusing this type,
+ * so a function-specific option can be added without touching the others.
+ */
+export type ResolveItem = (itemPath: string) => Promise<Item | undefined>;
 /**
  * An ItemSummary is a constituent of a collection.
  * It links to an item, and can contain additional item information upon request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unito/integration-api",
-  "version": "8.0.9",
+  "version": "8.2.0",
   "description": "The Unito Integration API",
   "type": "module",
   "types": "./dist/src/index.d.ts",