@unito/integration-api 4.2.0 → 4.2.2

package/dist/src/guards.d.ts

@@ -1,4 +1,22 @@
 import * as Api from './types.js';
+/**
+ * Checks if the input is a record<unknown, unknown>
+ * @param potentialObject - The value to check.
+ * @returns True if the value is a record, false otherwise.
+ */
+export declare function isObject(potentialObject: unknown): potentialObject is Record<string, unknown>;
+/**
+ * Checks if the input is a string.
+ * @param potentialString - The value to check.
+ * @returns True if the value is a string, false otherwise.
+ */
+export declare function isString(potentialString: unknown): potentialString is string;
+/**
+ * Checks if the input is undefined.
+ * @param potentialUndefined - The value to check.
+ * @returns True if the value is undefined, false otherwise.
+ */
+export declare function isUndefined(potentialUndefined: unknown): potentialUndefined is undefined;
 /**
  * Checks if the input is an Api.ItemSummary object.
  * @param potentialItemSummary - The value to check.

package/dist/src/guards.js

@@ -4,7 +4,7 @@ import * as Api from './types.js';
  * @param potentialObject - The value to check.
  * @returns True if the value is a record, false otherwise.
  */
-function isObject(potentialObject) {
+export function isObject(potentialObject) {
     return typeof potentialObject === 'object' && potentialObject !== null && !Array.isArray(potentialObject);
 }
 /**
@@ -12,7 +12,7 @@ function isObject(potentialObject) {
  * @param potentialString - The value to check.
  * @returns True if the value is a string, false otherwise.
  */
-function isString(potentialString) {
+export function isString(potentialString) {
     return typeof potentialString === 'string';
 }
 /**
@@ -20,7 +20,7 @@ function isString(potentialString) {
  * @param potentialUndefined - The value to check.
  * @returns True if the value is undefined, false otherwise.
  */
-function isUndefined(potentialUndefined) {
+export function isUndefined(potentialUndefined) {
     return potentialUndefined === undefined;
 }
 /**

package/dist/src/index.cjs

@@ -563,19 +563,189 @@ const fieldTypeCompatibilityMatrix = {
     },
 };
 
+/**
+ * JSONPath parser that returns a relation that is guaranteed to have its schema populated.
+ */
+function findRelationByJSONPath(item, query) {
+    const tokens = parseJSONPath(query);
+    const schemas = [];
+    let current = item;
+    for (const token of tokens) {
+        if (current === '__self') {
+            const previousSchema = schemas[schemas.length - 1];
+            if (!previousSchema) {
+                throw new Error(`Invalid use of __self`);
+            }
+            current = previousSchema;
+        }
+        const result = applyToken(current, token);
+        if (isObject(result) && isRelationSchema(result['schema'])) {
+            schemas.push(result['schema']);
+        }
+        current = result;
+    }
+    if (isRelation(current)) {
+        return current;
+    }
+    if (isReferenceRelation(current) || isRelationSummary(current)) {
+        const latestSchema = schemas[schemas.length - 1];
+        if (latestSchema === undefined) {
+            throw new Error(`No schema found for relation ${current.label}`);
+        }
+        return { ...current, schema: latestSchema };
+    }
+    return undefined;
+}
+/**
+ * Parse JSONPath expression into tokens
+ */
+function parseJSONPath(query) {
+    const tokens = [];
+    let remaining = query;
+    // Remove root $ if present
+    if (remaining.startsWith('$')) {
+        remaining = remaining.substring(1);
+    }
+    while (remaining.length > 0) {
+        // Skip leading dots
+        if (remaining.startsWith('.')) {
+            remaining = remaining.substring(1);
+            continue;
+        }
+        // Parse bracket notation [...]
+        if (remaining.startsWith('[')) {
+            const bracketMatch = remaining.match(/^\[([^\]]*)\]/);
+            if (!bracketMatch) {
+                throw new Error(`Unclosed bracket in JSONPath: ${query}`);
+            }
+            remaining = remaining.substring(bracketMatch[0].length);
+            tokens.push(parseBracketExpression(String(bracketMatch[1])));
+            continue;
+        }
+        // Parse property name (until . or [ or end)
+        const propertyMatch = remaining.match(/^([^.[]+)/);
+        if (propertyMatch) {
+            const propertyName = String(propertyMatch[1]);
+            remaining = remaining.substring(propertyName.length);
+            tokens.push({ type: 'property', name: propertyName });
+        }
+    }
+    return tokens;
+}
+/**
+ * Parse bracket expression into a token
+ */
+function parseBracketExpression(content) {
+    // Filter expression: ?(@.property == 'value')
+    if (content.startsWith('?(')) {
+        const filterExpr = content.substring(2, content.length - 1);
+        return { type: 'filter', expression: parseFilterExpression(filterExpr) };
+    }
+    // Array index: 0, 1, 2, etc.
+    const index = parseInt(content, 10);
+    if (!isNaN(index)) {
+        return { type: 'index', value: index };
+    }
+    throw new Error(`Unsupported bracket expression: ${content}`);
+}
+/**
+ * Parse filter expression like @.name == 'value'
+ */
+function parseFilterExpression(expr) {
+    const opIndex = expr.indexOf('==');
+    if (opIndex === -1) {
+        throw new Error(`Filter expression must use == operator: ${expr}`);
+    }
+    const left = expr.substring(0, opIndex).trim();
+    const right = expr.substring(opIndex + 2).trim();
+    // Parse left side (should be @.property)
+    if (!left.startsWith('@.')) {
+        throw new Error(`Filter expression must start with @.: ${expr}`);
+    }
+    const property = left.substring(2);
+    // Parse right side (value) using regex to extract quoted strings
+    const quotedMatch = right.match(/^(?<quote>['"])(?<content>.*?)\k<quote>$/);
+    if (!quotedMatch) {
+        throw new Error(`Filter expression value must be a quoted string: ${expr}`);
+    }
+    return { property, value: quotedMatch.groups['content'] };
+}
+/**
+ * Apply a single token to the current value
+ */
+function applyToken(current, token) {
+    switch (token.type) {
+        case 'property':
+            return applyProperty(current, token.name);
+        case 'index':
+            return applyIndex(current, token.value);
+        case 'filter':
+            return applyFilter(current, token.expression);
+        default:
+            throw new Error(`Unsupported token type: ${token.type}`);
+    }
+}
+/**
+ * Apply property access
+ */
+function applyProperty(current, property) {
+    if (!isObject(current) || !(property in current)) {
+        return undefined;
+    }
+    return current[property];
+}
+/**
+ * Apply array index access
+ */
+function applyIndex(current, index) {
+    if (!Array.isArray(current) || index < 0 || index >= current.length) {
+        return undefined;
+    }
+    return current[index];
+}
+/**
+ * Apply filter expression
+ *
+ * This function returns the first item that matches the filter expression.
+ */
+function applyFilter(current, filter) {
+    if (!Array.isArray(current)) {
+        return undefined;
+    }
+    for (const item of current) {
+        if (isObject(item) && matchesFilter(item, filter)) {
+            return item;
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if an item matches a filter expression
+ */
+function matchesFilter(item, filter) {
+    if (!(filter.property in item)) {
+        return false;
+    }
+    return item[filter.property] === filter.value;
+}
+
 exports.FieldValueTypes = FieldValueTypes;
 exports.OperatorTypes = OperatorTypes;
 exports.RelationSemantics = RelationSemantics;
 exports.Semantics = Semantics;
 exports.StatusCodes = StatusCodes;
 exports.fieldTypeCompatibilityMatrix = fieldTypeCompatibilityMatrix;
+exports.findRelationByJSONPath = findRelationByJSONPath;
 exports.isFieldSchema = isFieldSchema;
 exports.isFieldValueType = isFieldValueType;
 exports.isItem = isItem;
 exports.isItemSummary = isItemSummary;
+exports.isObject = isObject;
 exports.isReferenceRelation = isReferenceRelation;
 exports.isRelation = isRelation;
 exports.isRelationSchema = isRelationSchema;
 exports.isRelationSchemaOrSelf = isRelationSchemaOrSelf;
 exports.isRelationSummary = isRelationSummary;
 exports.isSemantic = isSemantic;
+exports.isString = isString;
+exports.isUndefined = isUndefined;

package/dist/src/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types.js';
 export * from './guards.js';
 export * from './compatibilities.js';
+export * from './jsonPathHelpers.js';

package/dist/src/index.js

@@ -1,3 +1,4 @@
 export * from './types.js';
 export * from './guards.js';
 export * from './compatibilities.js';
+export * from './jsonPathHelpers.js';

package/dist/src/jsonPathHelpers.d.ts

@@ -0,0 +1,5 @@
+import * as Api from './index.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;

package/dist/src/jsonPathHelpers.js

@@ -0,0 +1,166 @@
+import * as Api from './index.js';
+/**
+ * JSONPath parser that returns a relation that is guaranteed to have its schema populated.
+ */
+export function findRelationByJSONPath(item, query) {
+    const tokens = parseJSONPath(query);
+    const schemas = [];
+    let current = item;
+    for (const token of tokens) {
+        if (current === '__self') {
+            const previousSchema = schemas[schemas.length - 1];
+            if (!previousSchema) {
+                throw new Error(`Invalid use of __self`);
+            }
+            current = previousSchema;
+        }
+        const result = applyToken(current, token);
+        if (Api.isObject(result) && Api.isRelationSchema(result['schema'])) {
+            schemas.push(result['schema']);
+        }
+        current = result;
+    }
+    if (Api.isRelation(current)) {
+        return current;
+    }
+    if (Api.isReferenceRelation(current) || Api.isRelationSummary(current)) {
+        const latestSchema = schemas[schemas.length - 1];
+        if (latestSchema === undefined) {
+            throw new Error(`No schema found for relation ${current.label}`);
+        }
+        return { ...current, schema: latestSchema };
+    }
+    return undefined;
+}
+/**
+ * Parse JSONPath expression into tokens
+ */
+function parseJSONPath(query) {
+    const tokens = [];
+    let remaining = query;
+    // Remove root $ if present
+    if (remaining.startsWith('$')) {
+        remaining = remaining.substring(1);
+    }
+    while (remaining.length > 0) {
+        // Skip leading dots
+        if (remaining.startsWith('.')) {
+            remaining = remaining.substring(1);
+            continue;
+        }
+        // Parse bracket notation [...]
+        if (remaining.startsWith('[')) {
+            const bracketMatch = remaining.match(/^\[([^\]]*)\]/);
+            if (!bracketMatch) {
+                throw new Error(`Unclosed bracket in JSONPath: ${query}`);
+            }
+            remaining = remaining.substring(bracketMatch[0].length);
+            tokens.push(parseBracketExpression(String(bracketMatch[1])));
+            continue;
+        }
+        // Parse property name (until . or [ or end)
+        const propertyMatch = remaining.match(/^([^.[]+)/);
+        if (propertyMatch) {
+            const propertyName = String(propertyMatch[1]);
+            remaining = remaining.substring(propertyName.length);
+            tokens.push({ type: 'property', name: propertyName });
+        }
+    }
+    return tokens;
+}
+/**
+ * Parse bracket expression into a token
+ */
+function parseBracketExpression(content) {
+    // Filter expression: ?(@.property == 'value')
+    if (content.startsWith('?(')) {
+        const filterExpr = content.substring(2, content.length - 1);
+        return { type: 'filter', expression: parseFilterExpression(filterExpr) };
+    }
+    // Array index: 0, 1, 2, etc.
+    const index = parseInt(content, 10);
+    if (!isNaN(index)) {
+        return { type: 'index', value: index };
+    }
+    throw new Error(`Unsupported bracket expression: ${content}`);
+}
+/**
+ * Parse filter expression like @.name == 'value'
+ */
+function parseFilterExpression(expr) {
+    const opIndex = expr.indexOf('==');
+    if (opIndex === -1) {
+        throw new Error(`Filter expression must use == operator: ${expr}`);
+    }
+    const left = expr.substring(0, opIndex).trim();
+    const right = expr.substring(opIndex + 2).trim();
+    // Parse left side (should be @.property)
+    if (!left.startsWith('@.')) {
+        throw new Error(`Filter expression must start with @.: ${expr}`);
+    }
+    const property = left.substring(2);
+    // Parse right side (value) using regex to extract quoted strings
+    const quotedMatch = right.match(/^(?<quote>['"])(?<content>.*?)\k<quote>$/);
+    if (!quotedMatch) {
+        throw new Error(`Filter expression value must be a quoted string: ${expr}`);
+    }
+    return { property, value: quotedMatch.groups['content'] };
+}
+/**
+ * Apply a single token to the current value
+ */
+function applyToken(current, token) {
+    switch (token.type) {
+        case 'property':
+            return applyProperty(current, token.name);
+        case 'index':
+            return applyIndex(current, token.value);
+        case 'filter':
+            return applyFilter(current, token.expression);
+        default:
+            throw new Error(`Unsupported token type: ${token.type}`);
+    }
+}
+/**
+ * Apply property access
+ */
+function applyProperty(current, property) {
+    if (!Api.isObject(current) || !(property in current)) {
+        return undefined;
+    }
+    return current[property];
+}
+/**
+ * Apply array index access
+ */
+function applyIndex(current, index) {
+    if (!Array.isArray(current) || index < 0 || index >= current.length) {
+        return undefined;
+    }
+    return current[index];
+}
+/**
+ * Apply filter expression
+ *
+ * This function returns the first item that matches the filter expression.
+ */
+function applyFilter(current, filter) {
+    if (!Array.isArray(current)) {
+        return undefined;
+    }
+    for (const item of current) {
+        if (Api.isObject(item) && matchesFilter(item, filter)) {
+            return item;
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if an item matches a filter expression
+ */
+function matchesFilter(item, filter) {
+    if (!(filter.property in item)) {
+        return false;
+    }
+    return item[filter.property] === filter.value;
+}

package/dist/src/types.d.ts

@@ -413,6 +413,12 @@ export interface RelationSchema {
      */
     relations?: RelationSummary[];
 }
+/**
+ * A type that guarantees the presence of a populated schema by preventing the use of __self.
+ */
+export type RelationWithPopulatedSchema<T extends RelationSummary | ReferenceRelation> = Omit<T, 'schema'> & {
+    schema: Exclude<RelationSchema, '__self'>;
+};
 /**
  * A CreateItemRequestPayload describes the shape of a request on an item creation endpoint.
  */

package/package.json

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