@takeshape/schema 11.40.0 → 11.41.0

package/es/refs.js

@@ -1,690 +0,0 @@
-import { isIntegerLike, isDefined, visit, isRecord } from '@takeshape/util';
-import get from 'lodash/get';
-import assign from 'lodash/fp/assign';
-import omit from 'lodash/fp/omit';
-import isString from 'lodash/isString';
-import { NotFoundError } from '@takeshape/errors';
-import compact from 'lodash/compact';
-import { getServiceNamespaces } from './services';
-import { mergeDeepObjectSchemas, mergeObjectSchemas } from './util/merge';
-import { isScalar } from './scalars';
-import { getRefType, isAllOfSchema, isExtendsSchema, isObjectSchema, isOneOfSchema, isRefSchema, isRefSchemaLegacy } from './types';
-import { getToolRef } from './util';
-
-/**
- * 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.
- */
-export function isRefItemWithPath(ref) {
-  return Boolean(ref.typeName && ref.serviceKey && ref.path && isDefined(ref.isForeign));
-}
-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
-  };
-}
-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: refItemToNamespacedShapeName(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 = refItemToNamespacedShapeName(ref);
-  return {
-    isArray: false,
-    shapeName,
-    ref,
-    template: ref.template
-  };
-}
-
-/**
- * Convert Query.shape to a PropertySchema
- */
-export function returnShapeToSchema(projectSchema, returnShape) {
-  if (typeof returnShape === 'string') {
-    if (isScalar(returnShape) || returnShape === 'object') {
-      return {
-        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`
- *
- * @param context A partial project schema
- * @param refExpression
- * 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 shapeNameToRefItem(context, shapeName, 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`.
- *
- * @param context A partial project schema
- * @param refExpression
- * 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`.
- *
- * @returns
- * A 2 member array, where 0 is the service name, 1 is the referenced type.
- */
-export function splitAtRef(atRef) {
-  const index = atRef.lastIndexOf(':');
-  const serviceKey = index === -1 ? 'local' : atRef.substring(0, index);
-  const referencedType = index === -1 ? atRef : atRef.substring(index + 1);
-  return [serviceKey, referencedType];
-}
-function isValidServiceId(context, serviceId) {
-  return serviceId === 'local' || Boolean(context.services?.[serviceId]);
-}
-
-/**
- * Parses and returns a typeName, serviceKey, and potentially a namespace for
- * the type.
- */
-export function atRefToRefItem(context, atRef, template) {
-  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?.[serviceKey];
-  const serviceNamespace = serviceConfig?.namespace;
-  return {
-    typeName,
-    serviceKey,
-    serviceNamespace,
-    template,
-    isForeign: Boolean(serviceConfig),
-    isValidService: isValidServiceId(context, serviceKey)
-  };
-}
-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
- */
-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',
-    namespace
-  };
-}
-function shapeNameToRefItem(context, shapeName, template) {
-  const parsed = parseName(context, shapeName);
-  return {
-    typeName: parsed.name,
-    serviceKey: parsed.serviceId,
-    serviceNamespace: parsed.namespace,
-    template,
-    isForeign: parsed.serviceId !== 'local',
-    isValidService: isValidServiceId(context, parsed.serviceId)
-  };
-}
-export function shapeToRefItem(context, shape) {
-  return shapeNameToRefItem(context, shape.name);
-}
-export function shapeToRefString(context, shape) {
-  return refItemToAtRef(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
-    const {
-      shapeName,
-      template
-    } = parseTemplateShape(refSchema['@ref']);
-    return atRefToRefItem(context, shapeName, template);
-  }
-  if (refSchema.$ref) {
-    // $ref: #/shapes/[ShapeName OR Namespace_TypeName]/schema
-    return refToRefItem(context, refSchema.$ref);
-  }
-}
-export function getRefWithPath(context, refSchema, schemaPath = [], isInterfaceRef = false) {
-  const refItem = getRef(context, refSchema);
-  if (refItem) {
-    const refType = getRefType(refSchema);
-    return {
-      ...refItem,
-      path: schemaPath.concat([refType]),
-      isInterfaceRef
-    };
-  }
-}
-
-/**
- * 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 property that has oneOf or items with oneOf, get all refs
- */
-export function getOneOfRefs(context, propertySchema, schemaPath = []) {
-  const oneOf = propertySchema.oneOf ?? propertySchema.items?.oneOf;
-  const path = propertySchema.oneOf ? schemaPath : [...schemaPath, 'items'];
-  if (oneOf) {
-    return compact(oneOf.map(one => {
-      return getRefWithPath(context, one, path);
-    }));
-  }
-  return [];
-}
-
-/**
- * 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) {
-  const shapeRef = `${refItem.serviceKey}:${refItem.typeName}`;
-  return refItem.template ? createTemplateShapeName(refItem.template, shapeRef) : shapeRef;
-}
-
-/**
- * Turns a `RefItem` into a standard shape name, namespacing if present.
- */
-export function refItemToNamespacedShapeName(refItem) {
-  const {
-    serviceNamespace,
-    typeName
-  } = refItem;
-  return serviceNamespace ? `${serviceNamespace}_${typeName}` : typeName;
-}
-
-/**
- * Turns a `RefItem` into a path suitable for `lodash.get`.
- */
-export function refItemToShapePath(refItem) {
-  return ['shapes', refItemToNamespacedShapeName(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);
-  return shape ? {
-    shape,
-    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 ? refItemToNamespacedShapeName(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
- * a ref property would create an invalid schema, potentially containing both
- * a ref and properties.
- *
- * 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
-           * will have been truncated to something opaque, like `@ref`.
-           */
-          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 resolvedSchemas = schemas.map((schema, index) => {
-      const resolved = resolveAll(schema, [...path, propName, index]);
-      return resolved && isObjectSchema(resolved) ? resolved : undefined;
-    });
-    return (propName === 'allOf' ? mergeDeepObjectSchemas : mergeObjectSchemas)(...resolvedSchemas);
-  };
-  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 => context.services?.[serviceId]?.namespace;
-}
-export function parsePropertyRef(refStr) {
-  const [serviceId, coordinate] = splitAtRef(refStr);
-  const coordinateParts = coordinate.split('.');
-  if (coordinateParts.length === 1) {
-    return {
-      serviceId,
-      shapeName: 'Query',
-      propertyName: coordinateParts[0]
-    };
-  }
-  if (coordinateParts.length === 2) {
-    return {
-      serviceId,
-      shapeName: coordinateParts[0],
-      propertyName: coordinateParts[1]
-    };
-  }
-}
-export function serializePropertyRef({
-  shapeName,
-  propertyName,
-  serviceId
-}) {
-  const coordinate = `${shapeName}.${propertyName}`;
-  return serviceId === 'local' ? coordinate : `${serviceId}:${coordinate}`;
-}
-export function normalizePropertyRef(refStr) {
-  const parsed = parsePropertyRef(refStr);
-  return parsed ? serializePropertyRef(parsed) : refStr;
-}
-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) {
-  return `${serviceId}:${shapeName}`;
-}
-export function applyNamespace(namespace, name) {
-  return namespace ? `${namespace}_${name}` : name;
-}
-export function propertyRefItemToResolverPath(getNamespace, item) {
-  const path = propertyRefItemToPath(getNamespace, item);
-  return path.concat(path[0] === 'shapes' ? '@resolver' : 'resolver');
-}
-export function propertyRefItemToArgsPath(getNamespace, item) {
-  const path = propertyRefItemToPath(getNamespace, item);
-  return path.concat(path[0] === 'shapes' ? '@args' : 'args');
-}
-export function propertyRefItemToLocalName(getNamespace, item) {
-  const {
-    shapeName,
-    serviceId,
-    propertyName
-  } = item;
-  if (shapeName === 'Query' || shapeName === 'Mutation') {
-    const namespaced = applyNamespace(getNamespace(serviceId), propertyName);
-    return `${shapeName}.${namespaced}`;
-  }
-  return propertyName;
-}
-export function queryRefToLocalName(context, queryRef) {
-  const parsedQueryRef = parsePropertyRef(queryRef);
-  if (parsedQueryRef) {
-    return parsedQueryRef.serviceId === 'local' ? parsedQueryRef.propertyName : propertyRefItemToLocalName(createGetNamespace(context), parsedQueryRef);
-  }
-}
-export function propertyRefItemToPath(getNamespace, item) {
-  const {
-    shapeName,
-    serviceId,
-    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 normalizeRefExpression(context, refExpression) {
-  return refItemToAtRef(refExpressionToRefItem(context, refExpression));
-}
-export function normalizeLocalRefString(ref) {
-  return ref.startsWith('local:') ? ref.substring(6) : ref;
-}
-export function getAllPropertyRefs(projectSchema) {
-  const result = [];
-  const parentIsResolver = (path, resolverName) => {
-    const parent = get(projectSchema, path.slice(0, -1));
-    return isRecord(parent) && (Array.isArray(resolverName) ? resolverName.some(name => name === parent.name) : parent.name === resolverName);
-  };
-  const parentIsGenerateState = path => {
-    if (path[0] !== 'ai-experimental' || path[path.length - 2] !== 'execution') {
-      return false;
-    }
-    const parent = get(projectSchema, path.slice(0, -1));
-    return isRecord(parent) && parent.type === 'generate';
-  };
-  const pushRef = refStr => {
-    const parsed = parsePropertyRef(refStr);
-    if (parsed) {
-      result.push(parsed);
-    }
-  };
-  visit(projectSchema, ['to', 'tools'], (value, path) => {
-    const propName = path[path.length - 1];
-    if (propName === 'to' && isString(value) && parentIsResolver(path, 'delegate')) {
-      pushRef(value);
-    } else if (propName === 'tools' && Array.isArray(value) && (parentIsGenerateState(path) || parentIsResolver(path, ['ai:generateText', 'ai:chat']))) {
-      const tools = value;
-      for (const tool of tools) {
-        pushRef(getToolRef(tool));
-      }
-    }
-  });
-  return result;
-}
-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 ? {
-    name: path[path.length - 1],
-    query,
-    ref: propertyRef
-  } : undefined;
-}
-export function ensureQuery(projectSchema, queryRef) {
-  const query = getQuery(projectSchema, queryRef);
-  if (!query) {
-    throw new NotFoundError(`Query "${queryRef}" not found`);
-  }
-  return query;
-}
-export function normalizeRefs(projectSchema, property) {
-  let updatedProperty = {
-    ...property
-  };
-
-  // Array items
-  if (property.items) {
-    return {
-      ...updatedProperty,
-      items: normalizeRefs(projectSchema, property.items)
-    };
-  }
-
-  // Unions
-  if (property.oneOf) {
-    return {
-      ...updatedProperty,
-      oneOf: property.oneOf.map(item => normalizeRefs(projectSchema, item))
-    };
-  }
-
-  // Convert $ref to @ref
-  const refItem = getRef(projectSchema, updatedProperty);
-  if (refItem && updatedProperty.$ref) {
-    updatedProperty = {
-      ...omit(['$ref'], updatedProperty),
-      '@ref': refItemToAtRef(refItem)
-    };
-  }
-  return updatedProperty;
-}