@takeshape/schema 9.80.3 → 9.81.0

package/es/refs.js

@@ -10,6 +10,16 @@ import isString from 'lodash/isString';
 import { isScalar } from './scalars';
 import { NotFoundError } from '@takeshape/errors';
 
+/**
+ * This interface describes a parsed `@ref` or `$ref`.
+ * The intended usage is to convert a schema with a ref to a RefItem which can then
+ * be passed to the various rich utilities in this file.
+ */
+
+/**
+ * Adds a schema path, needed when visiting a whole schema to report errors.
+ */
+
 /**
  * Guard for RefItemWithPath. Tests for presence of all required props.
  */
@@ -20,17 +30,14 @@ const templateShapeRegex = /^(\w+)<([\w:-]+)>$/;
 /**
  * Parse a template like `PaginatedList<Post>` and return both the template and the shape name.
  */
-
 export function parseTemplateShape(shapeExpression) {
   const matches = templateShapeRegex.exec(shapeExpression);
-
   if (matches) {
     return {
       shapeName: matches[2],
       template: matches[1]
     };
   }
-
   return {
     shapeName: shapeExpression,
     template: undefined
@@ -40,28 +47,23 @@ export function parseReturnShape(projectSchema, shape) {
   if (typeof shape === 'object') {
     if (isRefSchema(shape.items)) {
       const ref = getRef(projectSchema, shape.items);
-
       if (!ref) {
         throw new Error(`Could not parse ${JSON.stringify(shape.items)}: invalid ref`);
       }
-
       return {
         isArray: true,
         ref,
         shapeName: refItemToShapeName(ref)
       };
     }
-
     if (typeof shape.items.type !== 'string') {
       throw new Error(`Could not parse ${JSON.stringify(shape.items)}: invalid type`);
     }
-
     return {
       isArray: true,
       shapeName: shape.items.type
     };
   }
-
   const ref = refExpressionToRefItem(projectSchema, shape);
   const shapeName = refItemToShapeName(ref);
   return {
@@ -71,10 +73,10 @@ export function parseReturnShape(projectSchema, shape) {
     template: ref.template
   };
 }
+
 /**
  * Convert Query.shape to a PropertySchema
  */
-
 export function returnShapeToSchema(projectSchema, returnShape) {
   if (typeof returnShape === 'string') {
     if (isScalar(returnShape) || returnShape === 'object') {
@@ -82,59 +84,51 @@ export function returnShapeToSchema(projectSchema, returnShape) {
         type: returnShape
       };
     }
-
     return {
       '@ref': refItemToAtRef(refExpressionToRefItem(projectSchema, returnShape))
     };
   }
-
   return returnShape;
 }
+
 /**
  * Create a template string like `PaginatedList<Post>` from a template and shape name.
  */
-
 export function createTemplateShapeName(template, shapeName) {
   return `${template}<${shapeName}>`;
 }
+
 /**
  * If the string is a template like `PaginatedList<Post>`, return the shape name,
  * in this case `Post`. Otherwise return the input.
  */
-
 export const untemplate = input => {
   return parseTemplateShape(input).shapeName;
 };
 export function getFlattenedTemplateShapeName(shapeName, template) {
   return `${shapeName}${template ?? ''}`;
 }
-
 function $refToPath(ref) {
   return ref.substr(2).split('/');
 }
-
 function $refToShapeName(ref) {
   return $refToPath(ref)[1];
 }
-
 export function $refToAtRef($ref, service, namespace) {
   const shapeName = $refToShapeName($ref);
-
   if (service === 'local') {
     return `local:${shapeName}`;
   }
-
   return `${service}:${namespace === undefined ? shapeName : shapeName.replace(`${namespace}_`, '')}`;
 }
 export function refSchemaToPath(context, refSchema) {
   const refItem = getRef(context, refSchema);
-
   if (refItem === undefined) {
     throw new Error('Invalid ref in refSchemaToPath');
   }
-
   return refItemToShapePath(refItem);
 }
+
 /**
  * Safely turn a "template" shape reference (`@args`, `args`, `shape`) into a `RefItem`
  *
@@ -143,26 +137,24 @@ export function refSchemaToPath(context, refSchema) {
  * A ref expression might include "template" name and refer to a local or remote
  * shape, `Foo` or `CreateArgs<Foo>` or `CreateArgs<remote:Foo>`.*
  */
-
 export function refExpressionToRefItem(context, refExpression) {
   const {
     shapeName,
     template
   } = parseTemplateShape(refExpression);
-
   if (shapeName.includes(':')) {
     return atRefToRefItem(context, shapeName, template);
   }
-
   return refToRefItem(context, `#/shapes/${shapeName}/schema`, template);
 }
+
 /**
  * Converts a list of ref expressions into a list of ref items.
  */
-
 export function refExpressionListToRefItemList(context, refExpressionList) {
   return refExpressionList.map(ref => refExpressionToRefItem(context, ref));
 }
+
 /**
  * Sugar for converting a `refExpression` directly into a shape, without the
  * intermediate `refItem`.
@@ -172,10 +164,10 @@ export function refExpressionListToRefItemList(context, refExpressionList) {
  * A ref expression might include "template" name and refer to a local or remote
  * shape, `Foo` or `CreateArgs<Foo>` or `CreateArgs<remote:Foo>`.
  */
-
 export function refExpressionToShape(context, refExpression) {
   return refItemToShape(context, refExpressionToRefItem(context, refExpression));
 }
+
 /**
  * Provided a service name and a referenced type. Supports 2 or 3 part
  * references, e.g., `shopify:my-store:ProductInput` or `my-store:ProductInput`.
@@ -183,24 +175,22 @@ export function refExpressionToShape(context, refExpression) {
  * @returns
  * A 2 member array, where 0 is the service name, 1 is the referenced type.
  */
-
 export function splitAtRef(atRef) {
   const refParts = atRef.split(':');
   const serviceKey = refParts.length === 2 ? refParts[0] : `${refParts[0]}:${refParts[1]}`;
   const referencedType = refParts.length === 2 ? refParts[1] : refParts[2];
   return [serviceKey, referencedType];
 }
+
 /**
  * Parses and returns a typeName, serviceKey, and potentially a namespace for
  * the type.
  */
-
 export function atRefToRefItem(context, atRef, template) {
   var _context$services;
-
-  const [serviceKey, typeName] = splitAtRef(atRef); // It's possible the service doesn't have a namespace, or is local and has
+  const [serviceKey, typeName] = splitAtRef(atRef);
+  // It's possible the service doesn't have a namespace, or is local and has
   // no service config.
-
   const serviceConfig = (_context$services = context.services) === null || _context$services === void 0 ? void 0 : _context$services[serviceKey];
   const serviceNamespace = serviceConfig === null || serviceConfig === void 0 ? void 0 : serviceConfig.namespace;
   return {
@@ -214,7 +204,6 @@ export function atRefToRefItem(context, atRef, template) {
 export function refToRefItem(context, $ref, template) {
   return shapeNameToRefItem(context, $refToShapeName($ref), template);
 }
-
 /**
  * Parse a name (query, shape, etc) that might have a namespace and find the corresponding service layer id
  */
@@ -222,18 +211,15 @@ export function parseName(context, name) {
   const shapeNameParts = name.split('_');
   let serviceId;
   let namespace;
-
   if (shapeNameParts.length > 1) {
     const namespaces = getServiceNamespaces(context);
     const maybeNamespace = shapeNameParts[0];
     serviceId = namespaces.get(maybeNamespace);
-
     if (serviceId) {
       name = shapeNameParts.slice(1).join('_');
       namespace = maybeNamespace;
     }
   }
-
   return {
     name,
     serviceId: serviceId ?? 'local',
@@ -253,11 +239,11 @@ export function shapeNameToRefItem(context, shapeName, template) {
 export function shapeToRefItem(context, shape) {
   return shapeNameToRefItem(context, shape.name);
 }
+
 /**
  * Given a property schema and project schema, finds a `@ref` or `$ref` and
  * returns a `RefItem` suitable for loading a referenced schema...
  */
-
 export function getRef(context, refSchema) {
   if (refSchema['@ref']) {
     // @ref: my-service:ShapeName
@@ -267,7 +253,6 @@ export function getRef(context, refSchema) {
     } = parseTemplateShape(refSchema['@ref']);
     return atRefToRefItem(context, shapeName, template);
   }
-
   if (refSchema.$ref) {
     // $ref: #/shapes/[ShapeName OR Namespace_TypeName]/schema
     return refToRefItem(context, refSchema.$ref);
@@ -275,50 +260,48 @@ export function getRef(context, refSchema) {
 }
 export function getRefWithPath(context, refSchema, schemaPath = []) {
   const refItem = getRef(context, refSchema);
-
   if (refItem) {
     const refType = getRefType(refSchema);
-    return { ...refItem,
+    return {
+      ...refItem,
       path: schemaPath.concat([refType])
     };
   }
 }
+
 /**
  * Tests for a `@ref` or `$ref` property directly on the passed schema.
  *
  * @param schema Any schema that might could have a ref property.
  */
-
 export function hasRefProperty(schema) {
   return Boolean(schema['@ref'] ?? schema.$ref);
 }
+
 /**
  * From a schema with a ref, will return the top-level ref, and potentially
  * a ref item from a nested `items` property.
  */
-
 export function getRefOrItemsRef(context, refSchema, schemaPath = []) {
   const refItem = getRefWithPath(context, refSchema, schemaPath);
-
   if (refItem) {
     return refItem;
   }
-
   if (refSchema.items) {
     return getRefOrItemsRef(context, refSchema.items, schemaPath.concat(['items']));
   }
 }
+
 /**
  * Turns a `RefItem` into an `@ref`.
  */
-
 export function refItemToAtRef(refItem) {
   return `${refItem.serviceKey}:${refItem.typeName}`;
 }
+
 /**
  * Turns a `RefItem` into a standard shape name, namespacing if present.
  */
-
 export function refItemToShapeName(refItem) {
   const {
     serviceNamespace,
@@ -326,32 +309,32 @@ export function refItemToShapeName(refItem) {
   } = refItem;
   return serviceNamespace ? `${serviceNamespace}_${typeName}` : typeName;
 }
+
 /**
  * Turns a `RefItem` into a path suitable for `lodash.get`.
  */
-
 export function refItemToShapePath(refItem) {
   return ['shapes', refItemToShapeName(refItem)];
 }
+
 /**
  * Get a Shape referenced by a `RefItem`.
  */
-
 export function refItemToShape(context, refItem) {
   const shapePath = refItemToShapePath(refItem);
   return get(context, shapePath);
 }
+
 /**
  * Get all shapes referenced by a RefItem array.
  */
-
 export function refItemListToShapeList(context, refItems) {
   return refItems.map(ref => refItemToShape(context, ref)).filter(isDefined);
 }
+
 /**
  * Get a shape referenced by a `RefItem`, also returning the path to the new shape.
  */
-
 export function refItemToShapeWithPath(context, refItem) {
   const shapePath = refItemToShapePath(refItem);
   const shape = get(context, shapePath);
@@ -360,100 +343,90 @@ export function refItemToShapeWithPath(context, refItem) {
     path: shapePath
   } : undefined;
 }
+
 /**
  * Get a Shape schema referenced by a `RefItem`.
  */
-
 export function refItemToShapeSchema(context, refItem) {
   const shapePath = refItemToShapePath(refItem);
   return get(context, [...shapePath, 'schema']);
 }
+
 /**
  * Sugar, for when you really just need a string...
  */
-
 export function getRefShapeName(context, refSchema) {
   const refItem = getRef(context, refSchema);
   return refItem ? refItemToShapeName(refItem) : undefined;
 }
+
 /**
  * Sugar, for when you really just need a path...
  */
-
 export function anyRefToShapeSchemaPath(context, refSchema) {
   const refItem = getRef(context, refSchema);
   return refItem ? [...refItemToShapePath(refItem), 'schema'] : undefined;
 }
+
 /**
  * Helper fn to omit `ref` props from the target schema, and then extend it with the source schema.
  */
-
 export const omitRefAndExtend = (targetSchema, sourceSchema) => assign(omit(['@ref', '$ref'], targetSchema), sourceSchema);
+
 /**
  * If there is a $ref, this will insert a property schema from the top level
  * in place of the reference.
  */
-
 export function followRef(context, schema, ref) {
   const refItem = ref ?? getRef(context, schema);
-
   if (refItem) {
     const referencedSchema = refItemToShapeSchema(context, refItem);
-
     if (referencedSchema) {
       return omitRefAndExtend(schema, referencedSchema);
     }
   }
-
   return schema;
 }
+
 /**
  * Returns whether a schema has refs.
  */
-
 export function hasRef(schema) {
   if (isRefSchema(schema) || isRefSchemaLegacy(schema)) {
     return true;
   }
-
   if (isAllOfSchema(schema)) {
     return Boolean(schema.allOf.find(hasRef));
   }
-
   if (isOneOfSchema(schema)) {
     return Boolean(schema.oneOf.find(hasRef));
   }
-
   return false;
 }
+
 /**
  * Returns whether a schema has refs which can be followed.
  */
-
 export function hasResolvableRef(context, schema) {
   if (isRefSchema(schema) || isRefSchemaLegacy(schema)) {
     return Boolean(refItemToShapeSchema(context, getRef(context, schema)));
   }
-
   if (isAllOfSchema(schema)) {
     return Boolean(schema.allOf.find(s => hasResolvableRef(context, s)));
   }
-
   if (isOneOfSchema(schema)) {
     return Boolean(schema.oneOf.find(s => hasResolvableRef(context, s)));
   }
-
   return false;
 }
-
 function isSelfReferential(path, shapeName) {
   if (path[0] !== 'shapes' || path[1] !== shapeName) {
     return false;
   }
-
   const index = path.findIndex(part => part === 'allOf' || part === 'extends');
   return index !== -1 && isIntegerLike(path[index + 1]);
 }
+
 /**
  * Given a schema, will resolve any `allOf` or `ref` objects. This function has
  * to fully resolve all refs, because attempting to extend an object schema with
@@ -462,28 +435,21 @@ function isSelfReferential(path, shapeName) {
  *
  * If it can't create a valid schema it returns the input.
  */
-
-
 export function dereferenceSchema(context, shapeOrFieldSchema, schemaPath = []) {
   const resolveAll = (propertySchema, resolvePath) => {
     try {
       if (isAllOfSchema(propertySchema)) {
         return merge(propertySchema.allOf, 'allOf', resolvePath);
       }
-
       if (isExtendsSchema(propertySchema)) {
         return merge(propertySchema.extends, 'extends', resolvePath);
       }
-
       if (isRefSchema(propertySchema)) {
         const refItem = getRefWithPath(context, propertySchema);
-
         if (!refItem) {
           throw new Error('ref could not be parsed');
         }
-
         const shapeWithPath = refItemToShapeWithPath(context, refItem);
-
         if (shapeWithPath && !isSelfReferential(resolvePath, shapeWithPath.shape.name)) {
           /**
            * Pass the new shape's path rather than the parent's path, which
@@ -491,16 +457,13 @@ export function dereferenceSchema(context, shapeOrFieldSchema, schemaPath = [])
            */
           return resolveAll(omitRefAndExtend(propertySchema, shapeWithPath.shape.schema), shapeWithPath.path);
         }
-
         return;
       }
-
       return propertySchema;
     } catch (err) {
       throw new Error(`error at '${resolvePath.join('.')}', ${err.message}`);
     }
   };
-
   const merge = (schemas, propName, path) => {
     const mergedSchema = schemas.map((schema, index) => {
       const resolved = resolveAll(schema, [...path, propName, index]);
@@ -511,22 +474,18 @@ export function dereferenceSchema(context, shapeOrFieldSchema, schemaPath = [])
     });
     return assign(omit(propName, resolveSchema), mergedSchema);
   };
-
   return resolveAll(shapeOrFieldSchema, schemaPath) ?? shapeOrFieldSchema;
 }
 export function dereferenceObjectSchema(context, shapeOrFieldSchema, schemaPath = []) {
   const schema = dereferenceSchema(context, shapeOrFieldSchema, schemaPath);
-
   if (!isObjectSchema(schema)) {
     throw new Error(`provided schema at '${schemaPath.join('.')}' could not be resolved to an object schema`);
   }
-
   return schema;
 }
 export function createGetNamespace(context) {
   return serviceId => {
     var _context$services2, _context$services2$se;
-
     return (_context$services2 = context.services) === null || _context$services2 === void 0 ? void 0 : (_context$services2$se = _context$services2[serviceId]) === null || _context$services2$se === void 0 ? void 0 : _context$services2$se.namespace;
   };
 }
@@ -535,7 +494,6 @@ export function parsePropertyRef(refStr) {
   const serviceId = index === -1 ? 'local' : refStr.substring(0, index);
   const coordinate = index === -1 ? refStr : refStr.substring(index + 1);
   const coordinateParts = coordinate.split('.');
-
   if (coordinateParts.length === 1) {
     return {
       serviceId,
@@ -543,7 +501,6 @@ export function parsePropertyRef(refStr) {
       propertyName: coordinateParts[0]
     };
   }
-
   if (coordinateParts.length === 2) {
     return {
       serviceId,
@@ -557,11 +514,9 @@ export function serializePropertyRef(propertyRef) {
 }
 export function propertyRefToShapeRef(propertyRef) {
   const parsed = parsePropertyRef(propertyRef);
-
   if (!parsed) {
     throw new Error(`Invalid property ref "${propertyRef}`);
   }
-
   return formatShapeRef(parsed.serviceId, parsed.shapeName);
 }
 export function formatShapeRef(serviceId, shapeName) {
@@ -584,11 +539,9 @@ export function propertyRefItemToLocalName(getNamespace, item) {
     serviceId,
     propertyName
   } = item;
-
   if (shapeName === 'Query' || shapeName === 'Mutation') {
     return applyNamespace(getNamespace(serviceId), propertyName);
   }
-
   return propertyName;
 }
 export function propertyRefItemToPath(getNamespace, item) {
@@ -598,25 +551,22 @@ export function propertyRefItemToPath(getNamespace, item) {
     propertyName
   } = item;
   const namespace = getNamespace(serviceId);
-
   if (shapeName === 'Query' || shapeName === 'Mutation') {
     return [shapeName === 'Query' ? 'queries' : 'mutations', applyNamespace(namespace, propertyName)];
   }
-
   return ['shapes', applyNamespace(namespace, shapeName), 'schema', 'properties', propertyName];
 }
 export function propertyRefToArgs(projectSchema, ref) {
   const parsed = typeof ref === 'object' ? ref : parsePropertyRef(ref);
-
   if (parsed) {
     const path = propertyRefItemToArgsPath(createGetNamespace(projectSchema), parsed);
     return get(projectSchema, path);
   }
 }
+
 /**
  * Get a ref to the given shape.
  */
-
 export function shapeNameToRef(context, shapeName) {
   return refItemToAtRef(shapeNameToRefItem(context, shapeName));
 }
@@ -627,10 +577,8 @@ export function getAllPropertyRefs(projectSchema) {
   const result = [];
   visit(projectSchema, ['to'], (value, path) => {
     const parent = get(projectSchema, path.slice(0, -1));
-
     if (isString(value) && isRecord(parent) && parent.name === 'delegate') {
       const parsed = parsePropertyRef(value);
-
       if (parsed) {
         result.push(parsed);
       }
@@ -640,11 +588,9 @@ export function getAllPropertyRefs(projectSchema) {
 }
 export function getQuery(projectSchema, queryRef) {
   const propertyRef = parsePropertyRef(queryRef);
-
   if (!propertyRef || propertyRef.shapeName !== 'Query' && propertyRef.shapeName !== 'Mutation') {
     throw new Error(`Invalid query ref "${queryRef}"`);
   }
-
   const path = propertyRefItemToPath(createGetNamespace(projectSchema), propertyRef);
   const query = get(projectSchema, path);
   return query ? {
@@ -655,10 +601,8 @@ export function getQuery(projectSchema, queryRef) {
 }
 export function ensureQuery(projectSchema, queryRef) {
   const query = getQuery(projectSchema, queryRef);
-
   if (!query) {
     throw new NotFoundError(`Query "${query}" not found`);
   }
-
   return query;
 }