@takeshape/schema 11.52.0 → 11.55.0

package/dist/project-schema/migrate.js

@@ -0,0 +1,194 @@
+import { migrateTo } from "../migration/index.js";
+import { isProjectSchemaJSONV1_0_0, isProjectSchemaJSONV3_0_0, isProjectSchemaJSONV3_1_0, isProjectSchemaJSONV3_2_0, isProjectSchemaJSONV3_3_0, isProjectSchemaJSONV3_4_0, isProjectSchemaJSONV3_5_0, isProjectSchemaJSONV3_5_1, isProjectSchemaJSONV3_6_0, isProjectSchemaJSONV3_7_0, isProjectSchemaJSONV3_8_0, isProjectSchemaJSONV3_9_0, isProjectSchemaJSONV3_10_0, isProjectSchemaJSONV3_11_0, isProjectSchemaJSONV3_12_0, isProjectSchemaJSONV3_12_1, isProjectSchemaJSONV3_12_2, isProjectSchemaJSONV3_12_3, isProjectSchemaJSONV3_13_0, isProjectSchemaJSONV3_14_0, isProjectSchemaJSONV3_15_0, isProjectSchemaJSONV3_16_0, isProjectSchemaJSONV3_17_0, isProjectSchemaJSONV3_17_1, isProjectSchemaJSONV3_18_0, isProjectSchemaJSONV3_18_1, isProjectSchemaJSONV3_18_2, isProjectSchemaJSONV3_19_0, isProjectSchemaJSONV3_20_0, isProjectSchemaJSONV3_21_0, isProjectSchemaJSONV3_22_0, isProjectSchemaJSONV3_23_0, isProjectSchemaJSONV3_24_0, isProjectSchemaJSONV3_25_0, isProjectSchemaJSONV3_26_0, isProjectSchemaJSONV3_27_0, isProjectSchemaJSONV3_28_0, isProjectSchemaJSONV3_29_0, isProjectSchemaJSONV3_30_0, isProjectSchemaJSONV3_31_0, isProjectSchemaJSONV3_32_0, isProjectSchemaJSONV3_33_0, isProjectSchemaJSONV3_34_0, isProjectSchemaJSONV3_35_0, isProjectSchemaJSONV3_36_0, isProjectSchemaJSONV3_37_0, isProjectSchemaJSONV3_38_0, isProjectSchemaJSONV3_39_0, isProjectSchemaJSONV3_40_0, isProjectSchemaJSONV3_41_0, isProjectSchemaJSONV3_42_0, isProjectSchemaJSONV3_43_0, isProjectSchemaJSONV3_44_0, isProjectSchemaJSONV3_45_0, isProjectSchemaJSONV3_46_0, isProjectSchemaJSONV3_47_0, isProjectSchemaJSONV3_48_0, isProjectSchemaJSONV3_49_0, isProjectSchemaJSONV3_50_0, isProjectSchemaJSONV4_0_0, isLatestProjectSchemaJSON } from "./index.js";
+export async function migrateToLatestProjectSchema(context, projectSchema) {
+    if (isLatestProjectSchemaJSON(projectSchema)) {
+        return projectSchema;
+    }
+    if (isProjectSchemaJSONV1_0_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.0.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_0_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.1.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_1_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.2.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_2_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.3.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_3_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.4.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_4_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.5.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_5_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.5.1'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_5_1(projectSchema)) {
+        projectSchema = await migrateTo['v3.6.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_6_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.7.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_7_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.8.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_8_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.9.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_9_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.10.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_10_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.11.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_11_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.12.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_12_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.12.1'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_12_1(projectSchema)) {
+        projectSchema = await migrateTo['v3.12.2'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_12_2(projectSchema)) {
+        projectSchema = await migrateTo['v3.12.3'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_12_3(projectSchema)) {
+        projectSchema = await migrateTo['v3.13.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_13_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.14.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_14_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.15.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_15_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.16.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_16_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.17.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_17_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.17.1'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_17_1(projectSchema)) {
+        projectSchema = await migrateTo['v3.18.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_18_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.18.1'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_18_1(projectSchema)) {
+        projectSchema = await migrateTo['v3.18.2'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_18_2(projectSchema)) {
+        projectSchema = await migrateTo['v3.19.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_19_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.20.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_20_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.21.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_21_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.22.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_22_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.23.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_23_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.24.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_24_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.25.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_25_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.26.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_26_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.27.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_27_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.28.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_28_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.29.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_29_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.30.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_30_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.31.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_31_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.32.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_32_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.33.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_33_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.34.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_34_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.35.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_35_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.36.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_36_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.37.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_37_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.38.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_38_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.39.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_39_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.40.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_40_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.41.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_41_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.42.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_42_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.43.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_43_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.44.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_44_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.45.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_45_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.46.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_46_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.47.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_47_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.48.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_48_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.49.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_49_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.50.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV3_50_0(projectSchema)) {
+        projectSchema = await migrateTo['v3.51.0'](context, projectSchema);
+    }
+    if (isProjectSchemaJSONV4_0_0(projectSchema)) {
+        throw new Error('You are using an unreleased schema version. Migration is not possible');
+    }
+    return projectSchema;
+}
+export async function ensureLatest(context, schema) {
+    if (!schema || isLatestProjectSchemaJSON(schema)) {
+        return schema;
+    }
+    return migrateToLatestProjectSchema(context, schema);
+}

package/dist/refs.d.ts

@@ -0,0 +1,226 @@
+import { type Maybe } from '@takeshape/util';
+import type { Args, ObjectSchema, ProjectSchemaJSON, PropertySchema, QueryJSON, Ref, ReturnShape, ShapeJSON, ShapeSchema } from './project-schema/index.ts';
+import type { SchemaPath, SchemaWithRef } from './types/index.ts';
+export type ServicesContext = Pick<ProjectSchemaJSON, 'services'>;
+export type ServicesShapesContext = Pick<ProjectSchemaJSON, 'services' | 'shapes'>;
+/**
+ * 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.
+ */
+export type RefItem = {
+    typeName: string;
+    serviceKey: string;
+    serviceNamespace?: string;
+    template?: string;
+    isForeign: boolean;
+    isValidService: boolean;
+} & Record<string, unknown>;
+/**
+ * Adds a schema path, needed when visiting a whole schema to report errors.
+ */
+export type RefItemWithPath = {
+    path: SchemaPath;
+} & RefItem;
+/**
+ * Guard for RefItemWithPath. Tests for presence of all required props.
+ */
+export declare function isRefItemWithPath(ref: Record<string, unknown>): ref is RefItemWithPath;
+/**
+ * Parse a template like `PaginatedList<Post>` and return both the template and the shape name.
+ */
+export declare function parseTemplateShape(shapeExpression: string): {
+    template: string | undefined;
+    shapeName: string;
+};
+export type ParsedReturnShape = {
+    isArray: boolean;
+    template?: string;
+    shapeName: string;
+    ref?: RefItem;
+};
+export declare function parseReturnShape(projectSchema: ServicesContext, shape: ReturnShape): ParsedReturnShape;
+/**
+ * Convert Query.shape to a PropertySchema
+ */
+export declare function returnShapeToSchema(projectSchema: ServicesContext, returnShape: ReturnShape): PropertySchema;
+/**
+ * Create a template string like `PaginatedList<Post>` from a template and shape name.
+ */
+export declare function createTemplateShapeName(template: string, shapeName: string): string;
+/**
+ * If the string is a template like `PaginatedList<Post>`, return the shape name,
+ * in this case `Post`. Otherwise return the input.
+ */
+export declare const untemplate: (input: string) => string;
+export declare function getFlattenedTemplateShapeName(shapeName: string, template?: string): string;
+export declare function $refToAtRef($ref: string, service: string, namespace?: string): string;
+export declare function refSchemaToPath(context: ServicesContext, refSchema: SchemaWithRef): string[];
+/**
+ * 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 declare function refExpressionToRefItem(context: ServicesContext, refExpression: string): RefItem;
+/**
+ * Converts a list of ref expressions into a list of ref items.
+ */
+export declare function refExpressionListToRefItemList(context: ServicesContext, refExpressionList: Ref[]): RefItem[];
+/**
+ * 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 declare function refExpressionToShape(context: ServicesShapesContext, refExpression: string): Maybe<ShapeJSON>;
+/**
+ * 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 declare function splitAtRef(atRef: string): [string, string];
+/**
+ * Parses and returns a typeName, serviceKey, and potentially a namespace for
+ * the type.
+ */
+export declare function atRefToRefItem(context: ServicesContext, atRef: string, template?: string): RefItem;
+export declare function refToRefItem(context: ServicesContext, $ref: string, template?: string): RefItem;
+export type ParsedName = {
+    namespace?: string;
+    serviceId: string;
+    name: string;
+};
+/**
+ * Parse a name (query, shape, etc) that might have a namespace and find the corresponding service layer id
+ */
+export declare function parseName(context: ServicesContext, name: string): ParsedName;
+export declare function shapeToRefItem(context: ServicesContext, shape: ShapeJSON): RefItem;
+export declare function shapeToRefString(context: ServicesContext, shape: ShapeJSON): string;
+/**
+ * Given a property schema and project schema, finds a `@ref` or `$ref` and
+ * returns a `RefItem` suitable for loading a referenced schema...
+ */
+export declare function getRef(context: ServicesContext, refSchema: SchemaWithRef): Maybe<RefItem>;
+export declare function getRefWithPath(context: ServicesContext, refSchema: SchemaWithRef, schemaPath?: SchemaPath, isInterfaceRef?: boolean): Maybe<RefItemWithPath>;
+/**
+ * Tests for a `@ref` or `$ref` property directly on the passed schema.
+ *
+ * @param schema Any schema that might could have a ref property.
+ */
+export declare function hasRefProperty(schema: SchemaWithRef): boolean;
+/**
+ * From a property that has oneOf or items with oneOf, get all refs
+ */
+export declare function getOneOfRefs(context: ServicesContext, propertySchema: PropertySchema, schemaPath?: SchemaPath): RefItemWithPath[];
+/**
+ * From a schema with a ref, will return the top-level ref, and potentially
+ * a ref item from a nested `items` property.
+ */
+export declare function getRefOrItemsRef(context: ServicesContext, refSchema: SchemaWithRef, schemaPath?: SchemaPath): Maybe<RefItemWithPath>;
+/**
+ * Turns a `RefItem` into an `@ref`.
+ */
+export declare function refItemToAtRef(refItem: RefItem): string;
+/**
+ * Turns a `RefItem` into a standard shape name, namespacing if present.
+ */
+export declare function refItemToNamespacedShapeName(refItem: RefItem): string;
+/**
+ * Turns a `RefItem` into a path suitable for `lodash.get`.
+ */
+export declare function refItemToShapePath(refItem: RefItem): string[];
+/**
+ * Get a Shape referenced by a `RefItem`.
+ */
+export declare function refItemToShape(context: ServicesShapesContext, refItem: RefItem): Maybe<ShapeJSON>;
+/**
+ * Get all shapes referenced by a RefItem array.
+ */
+export declare function refItemListToShapeList(context: ServicesShapesContext, refItems: RefItem[]): ShapeJSON[];
+/**
+ * Get a shape referenced by a `RefItem`, also returning the path to the new shape.
+ */
+export declare function refItemToShapeWithPath(context: ServicesShapesContext, refItem: RefItem): Maybe<{
+    shape: ShapeJSON;
+    path: string[];
+}>;
+/**
+ * Get a Shape schema referenced by a `RefItem`.
+ */
+export declare function refItemToShapeSchema(context: ServicesShapesContext, refItem: RefItem): Maybe<ShapeSchema>;
+/**
+ * Sugar, for when you really just need a string...
+ */
+export declare function getRefShapeName(context: ServicesContext, refSchema: SchemaWithRef): Maybe<string>;
+/**
+ * Sugar, for when you really just need a path...
+ */
+export declare function anyRefToShapeSchemaPath(context: ServicesContext, refSchema: SchemaWithRef): Maybe<string[]>;
+/**
+ * Helper fn to omit `ref` props from the target schema, and then extend it with the source schema.
+ */
+export declare const omitRefAndExtend: (targetSchema: PropertySchema, sourceSchema: PropertySchema) => import("lodash").Omit<PropertySchema, "@ref" | "$ref"> & PropertySchema;
+/**
+ * If there is a $ref, this will insert a property schema from the top level
+ * in place of the reference.
+ */
+export declare function followRef(context: ServicesShapesContext, schema: PropertySchema, ref?: RefItem): PropertySchema;
+/**
+ * Returns whether a schema has refs.
+ */
+export declare function hasRef(schema: PropertySchema): boolean;
+/**
+ * Returns whether a schema has refs which can be followed.
+ */
+export declare function hasResolvableRef(context: ServicesShapesContext, schema: PropertySchema): boolean;
+/**
+ * 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 declare function dereferenceSchema(context: ServicesShapesContext, shapeOrFieldSchema: PropertySchema, schemaPath?: SchemaPath): PropertySchema;
+export declare function dereferenceObjectSchema(context: ServicesShapesContext, shapeOrFieldSchema: PropertySchema, schemaPath?: SchemaPath): ObjectSchema;
+export type GetNamespace = (serviceId: string) => Maybe<string>;
+export declare function createGetNamespace(context: ServicesContext): GetNamespace;
+export type PropertyRefItem = {
+    serviceId: string;
+    shapeName: string;
+    propertyName: string;
+};
+export declare function parsePropertyRef(refStr: string): Maybe<PropertyRefItem>;
+export declare function serializePropertyRef({ shapeName, propertyName, serviceId }: PropertyRefItem): string;
+export declare function normalizePropertyRef(refStr: string): string;
+export declare function propertyRefToShapeRef(propertyRef: string): string;
+export declare function formatShapeRef(serviceId: string, shapeName: string): string;
+export declare function applyNamespace(namespace: string | undefined, name: string): string;
+export declare function propertyRefItemToResolverPath(getNamespace: GetNamespace, item: PropertyRefItem): string[];
+export declare function propertyRefItemToArgsPath(getNamespace: GetNamespace, item: PropertyRefItem): string[];
+export declare function propertyRefItemToLocalName(getNamespace: GetNamespace, item: PropertyRefItem): string;
+export declare function queryRefToLocalName(context: ServicesContext, queryRef: string): string | undefined;
+export declare function propertyRefItemToPath(getNamespace: GetNamespace, item: PropertyRefItem): string[];
+export declare function propertyRefToArgs(projectSchema: ProjectSchemaJSON, ref: string | PropertyRefItem): Maybe<Args>;
+/**
+ * Get a ref to the given shape.
+ */
+export declare function normalizeRefExpression(context: ServicesContext, refExpression: string): string;
+export declare function normalizeLocalRefString(ref: string): string;
+export declare function getAllPropertyRefs(projectSchema: ProjectSchemaJSON): PropertyRefItem[];
+export type QueryEntry = {
+    name: string;
+    query: QueryJSON;
+    ref: PropertyRefItem;
+};
+export declare function getQuery(projectSchema: ProjectSchemaJSON, queryRef: string): Maybe<QueryEntry>;
+export declare function ensureQuery(projectSchema: ProjectSchemaJSON, queryRef: string): QueryEntry;
+export declare function normalizeRefs(projectSchema: ProjectSchemaJSON, property: PropertySchema): PropertySchema;