@shapio/schema 0.5.7 → 0.5.9

package/dist/index.d.ts

@@ -284,6 +284,11 @@ export declare const ModelDefinitionInputSchema: Type.TObject<{
   localized: Type.TOptional<Type.TBoolean>;
   /** Entries have separate draft and published states. Default true. */
   draftAndPublish: Type.TOptional<Type.TBoolean>;
+  /**
+   * Collections only: the stable ID of the collection this one extends (its parent). The model inherits
+   * the parent's fields, locked, and adds its own (plan polymorphic-types).
+   */
+  extends: Type.TOptional<Type.TString>;
   display: Type.TOptional<Type.TObject<{
     /** How entries open: `document` (default) or `form`. See `ENTRY_LAYOUTS`. */
     layout: Type.TOptional<Type.TEnum<["document", "form"]>>;
@@ -402,6 +407,11 @@ export declare const DefinitionInputSchema: Type.TUnion<[Type.TObject<{
   localized: Type.TOptional<Type.TBoolean>;
   /** Entries have separate draft and published states. Default true. */
   draftAndPublish: Type.TOptional<Type.TBoolean>;
+  /**
+   * Collections only: the stable ID of the collection this one extends (its parent). The model inherits
+   * the parent's fields, locked, and adds its own (plan polymorphic-types).
+   */
+  extends: Type.TOptional<Type.TString>;
   display: Type.TOptional<Type.TObject<{
     /** How entries open: `document` (default) or `form`. See `ENTRY_LAYOUTS`. */
     layout: Type.TOptional<Type.TEnum<["document", "form"]>>;
@@ -575,9 +585,28 @@ export type ModelDefinition = {
   description?: string;
   localized: boolean;
   draftAndPublish: boolean;
+  /**
+   * The stable ID of the collection this one extends. The stored definition holds its own fields only;
+   * `resolveModelDefinition` adds the inherited ones (ancestors' first).
+   */
+  extends?: string;
   fields: FieldDefinition[];
   display: ModelDisplay;
 };
+/** A field as a model sees it after inheritance: `inheritedFrom` names the declaring ancestor's ID. */
+export type ResolvedField = FieldDefinition & {
+  inheritedFrom?: string;
+};
+/**
+ * A model with its effective fields: every ancestor's fields (root first), then its own, and its display
+ * merged with its ancestors' (`resolveModelDefinition`). `ancestorIds` is required so code that needs
+ * effective fields can demand this type; a stored definition does not satisfy it.
+ */
+export type ResolvedModelDefinition = Omit<ModelDefinition, 'fields'> & {
+  fields: ResolvedField[];
+  /** Ancestors' stable IDs, root first; empty for a model that extends nothing. */
+  ancestorIds: readonly string[];
+};
 export type ComponentDefinition = {
   id: string;
   kind: 'component';
@@ -771,6 +800,87 @@ export declare const PLURAL_FALLBACK_SUFFIX = "Items";
  */
 export declare const suggestPlural: (apiKey: string) => string;
 //#endregion
+//#region src/naming/routePath.d.ts
+/** A route key: one to MAX_INHERITANCE_DEPTH API IDs joined by `/` (`products/digital`). */
+export declare const ROUTE_KEY_PATTERN: RegExp;
+/** Longest route key: every level at the longest API ID, plus the separators. */
+export declare const MAX_ROUTE_KEY_LENGTH: number;
+/** The route key of a model under its ancestors (root first): `products/digital`. A root's is `routeKeyOf`. */
+export declare const routePathOf: (definition: ModelDefinition, ancestors: readonly ModelDefinition[]) => string;
+/**
+ * Splits the path segments after a content prefix (`/api/content/`) into the route key and the rest: the
+ * leading segments that are API IDs (at most MAX_INHERITANCE_DEPTH) form the key; the first one that is not
+ * (an entry ID is a UUID, which always has a hyphen) starts the rest. A single segment that already holds a
+ * whole route key (`products%2Fdigital`, decoded) is taken as it is. Undefined when no segment is a key.
+ * Purely syntactic: shared by the server's URL rewrite and the in-process delivery matcher.
+ */
+export declare const splitRoutePath: (segments: readonly string[]) => {
+  routeKey: string;
+  rest: string[];
+} | undefined;
+//#endregion
+//#region src/inheritance/resolve.d.ts
+/**
+ * Model inheritance (plan polymorphic-types). A collection may extend another (`extends`, the parent's stable
+ * ID). Stored definitions hold their own fields only; the effective definition is resolved at read time:
+ * every ancestor's fields (root first, each marked `inheritedFrom`), then the model's own, and the display
+ * merged down the chain. Nothing is copied into children, so a parent edit changes one definition.
+ */
+/** Most levels a family may have, root included (`Products > Physical > Apparel` is three). */
+export declare const MAX_INHERITANCE_DEPTH = 8;
+export type DefinitionLookup = (id: string) => SchemaDefinition | undefined;
+/** Why an ancestor chain stops early. `invalid`: the parent is a component, a singleton or the model itself. */
+export type AncestorProblem = 'missing' | 'invalid' | 'cycle' | 'tooDeep';
+export type AncestorChain = {
+  /** The ancestors that resolve, root first (the parent last). */
+  ids: string[];
+  problem?: AncestorProblem;
+  /** The definition whose `extends` is the problem (the model itself or one of its ancestors). */
+  problemAt?: string;
+};
+/**
+ * The ancestors of a definition, root first, walking `extends` up. Stops at the first problem (missing,
+ * invalid or cyclic parent, or more than MAX_INHERITANCE_DEPTH levels) and returns what resolved so far.
+ */
+export declare const ancestorChain: (definition: SchemaDefinition, lookup: DefinitionLookup) => AncestorChain;
+/**
+ * A child's display over its parent's (already merged) one. Scalars and `listFieldIds` take the child's value
+ * when set, else the parent's. Groups are the parent's, then the child's. Canvas and strip take the child's
+ * list when set; else the parent's list (when set) with the child's own fields appended where the automatic
+ * rule would put them: canvas-eligible fields to the canvas, the other fields (not the cover) to the strip.
+ */
+export declare const mergeDisplay: (parent: ModelDisplay, child: ModelDisplay, ownFields: readonly FieldDefinition[]) => ModelDisplay;
+/**
+ * The effective definition of a model: ancestors' fields first (root first, `inheritedFrom` set, otherwise the
+ * same field objects' values and IDs), then its own fields; display merged root → model. A broken chain
+ * (see `ancestorChain`) resolves over the part that resolved; the validator reports the problem.
+ */
+export declare const resolveModelDefinition: (definition: ModelDefinition, lookup: DefinitionLookup) => ResolvedModelDefinition;
+/** The fields a resolved model declares itself (not inherited). */
+export declare const ownFields: (resolved: ResolvedModelDefinition) => FieldDefinition[];
+/** Definitions whose parent is `id`, in the given order. */
+export declare const findChildDefinitions: (definitions: readonly SchemaDefinition[], id: string) => ModelDefinition[];
+/**
+ * Inheritance lookups over one set of definitions (the active schema, a proposed one, a site's view), each
+ * memoised. Unknown IDs give empty answers; components and singletons are never resolved.
+ */
+export type DefinitionIndex = {
+  get: (id: string) => SchemaDefinition | undefined;
+  /** The effective definition of a collection or singleton; undefined for components and unknown IDs. */
+  resolve: (id: string) => ResolvedModelDefinition | undefined;
+  /** Ancestors' IDs, root first; [] for a root or an unknown ID. */
+  ancestors: (id: string) => readonly string[];
+  /** Direct children's IDs, in definition order. */
+  childrenOf: (id: string) => readonly string[];
+  /** Every descendant's ID (children, then their children, depth first), not the model itself. */
+  descendants: (id: string) => readonly string[];
+  /** The model and its descendants, the model first. */
+  family: (id: string) => readonly string[];
+  /** The family's root (the model itself when it extends nothing). */
+  rootOf: (id: string) => string;
+};
+export declare const createDefinitionIndex: (definitions: readonly SchemaDefinition[]) => DefinitionIndex;
+//#endregion
 //#region src/normalize.d.ts
 /** Input whose IDs have been assigned (see `assignIds`). */
 type WithIds<T extends {
@@ -807,7 +917,7 @@ export type ValidationIssue = {
   /** Set by cross-definition checks so a multi-definition apply can say which file is wrong. */
   definitionId?: string;
 };
-export type IssueCode = 'INVALID_STRUCTURE' | 'INVALID_TEXT' | 'INVALID_ID' | 'DUPLICATE_ID' | 'API_KEY_INVALID' | 'API_KEY_TOO_LONG' | 'API_KEY_RESERVED_PREFIX' | 'API_KEY_RESERVED' | 'API_KEY_COLLISION' | 'PLURAL_API_KEY_SAME_AS_SINGULAR' | 'GENERATED_NAME_COLLISION' | 'INVALID_SETTINGS' | 'INVALID_RANGE' | 'INVALID_PATTERN' | 'DUPLICATE_ENUM_VALUE' | 'INVALID_ENUM_VALUE' | 'UNSUPPORTED_FLAG' | 'INVALID_DEFAULT_VALUE' | 'UNKNOWN_EDITOR' | 'INCOMPATIBLE_EDITOR' | 'INVALID_EDITOR_OPTIONS' | 'UNKNOWN_FIELD_REFERENCE' | 'INVALID_FIELD_REFERENCE' | 'DUPLICATE_GROUP' | 'UNKNOWN_REFERENCE' | 'INVALID_REFERENCE_TARGET' | 'COMPONENT_CYCLE' | 'COMPONENT_TOO_DEEP' | 'REFERENCED_DEFINITION';
+export type IssueCode = 'INVALID_STRUCTURE' | 'INVALID_TEXT' | 'INVALID_ID' | 'DUPLICATE_ID' | 'API_KEY_INVALID' | 'API_KEY_TOO_LONG' | 'API_KEY_RESERVED_PREFIX' | 'API_KEY_RESERVED' | 'API_KEY_COLLISION' | 'PLURAL_API_KEY_SAME_AS_SINGULAR' | 'GENERATED_NAME_COLLISION' | 'INVALID_SETTINGS' | 'INVALID_RANGE' | 'INVALID_PATTERN' | 'DUPLICATE_ENUM_VALUE' | 'INVALID_ENUM_VALUE' | 'UNSUPPORTED_FLAG' | 'INVALID_DEFAULT_VALUE' | 'UNKNOWN_EDITOR' | 'INCOMPATIBLE_EDITOR' | 'INVALID_EDITOR_OPTIONS' | 'UNKNOWN_FIELD_REFERENCE' | 'INVALID_FIELD_REFERENCE' | 'DUPLICATE_GROUP' | 'UNKNOWN_REFERENCE' | 'INVALID_REFERENCE_TARGET' | 'COMPONENT_CYCLE' | 'COMPONENT_TOO_DEEP' | 'REFERENCED_DEFINITION' | 'UNKNOWN_PARENT' | 'INVALID_PARENT' | 'INHERITANCE_CYCLE' | 'INHERITANCE_TOO_DEEP' | 'INHERITED_FIELD_COLLISION' | 'INHERITED_FLAG_MISMATCH' | 'HAS_CHILDREN';
 export declare class SchemaValidationError extends Error {
   readonly issues: readonly ValidationIssue[];
   constructor(issues: readonly ValidationIssue[]);
@@ -842,9 +952,18 @@ export declare const foldApiKey: (key: string) => string;
 export declare const checkDefaultValue: (field: FieldDefinition) => string | null;
 //#endregion
 //#region src/validators/definition.d.ts
+/**
+ * The display's references to fields. Also run by the inheritance check on a child's resolved definition,
+ * whose display may name inherited fields.
+ */
+export declare const checkDisplay: (definition: SchemaDefinition) => ValidationIssue[];
 /** All problems with one definition, in document order. Empty means valid on its own. */
 export declare const validateDefinition: (definition: SchemaDefinition) => ValidationIssue[];
 //#endregion
+//#region src/validators/inheritance.d.ts
+/** Every inheritance problem of a schema (see the module comment). */
+export declare const checkInheritance: (definitions: readonly SchemaDefinition[], index?: DefinitionIndex) => ValidationIssue[];
+//#endregion
 //#region src/validators/naming.d.ts
 /**
  * The names GraphQL (package J) and other generated contracts derive from API keys. Defined here, with the
@@ -855,6 +974,11 @@ export declare const toTypeName: (apiKey: string) => string;
 /** Suffixes of the types generated for each model (`Page`, `PageFilter`, `PageInput`...). */
 export declare const MODEL_TYPE_SUFFIXES: readonly ["", "Filter", "Input", "Connection", "Edge", "Localizations", "Sort"];
 export declare const COMPONENT_TYPE_SUFFIXES: readonly ["", "Input"];
+/**
+ * Suffix of the GraphQL interface a model with children gets (`ProductInterface`, plan polymorphic-types).
+ * Claimed only by models that have children, so existing schemas keep validating.
+ */
+export declare const INTERFACE_TYPE_SUFFIX = "Interface";
 export declare const MUTATION_PREFIXES: readonly ["create", "update", "delete", "publish", "unpublish"];
 /**
  * The key a model is addressed by in the delivery API (`/api/content/:routeKey`, preview routes): the
@@ -902,8 +1026,14 @@ export type GeneratedName = {
   /** The definition property the name comes from, when not `apiKey` (for the issue path). */
   property?: 'pluralApiKey';
 };
-/** Every name a definition contributes to the GraphQL schema. */
-export declare const generatedNames: (definition: SchemaDefinition) => GeneratedName[];
+/**
+ * Every name a definition contributes to the GraphQL schema. Fields are its own: a model that extends another
+ * reuses the enum and zone types of inherited fields, which belong to the declaring model. `hasChildren` adds
+ * the interface name of a model other models extend.
+ */
+export declare const generatedNames: (definition: SchemaDefinition, options?: {
+  hasChildren?: boolean;
+}) => GeneratedName[];
 //#endregion
 //#region src/validators/parse.d.ts
 export type ParseDefinitionResult = {
@@ -937,15 +1067,16 @@ export declare const MAX_COMPONENT_DEPTH = 5;
 export declare const embeddedComponentIds: (definition: SchemaDefinition) => string[];
 /**
  * Cross-definition checks over a whole schema (every active definition with the proposed change applied):
- * unique IDs and API keys, GraphQL name collisions, relation and component targets, component cycles and
- * nesting depth. Each definition must already pass `validateDefinition`.
+ * unique IDs and API keys, model inheritance, GraphQL name collisions, relation and component targets,
+ * component cycles and nesting depth. Each definition must already pass `validateDefinition`.
  */
 export declare const validateSchema: (definitions: readonly SchemaDefinition[]) => ValidationIssue[];
 /** Definitions that reference `id` (relations, components, dynamic zones). Used to block deletions. */
 export declare const findReferencingDefinitions: (definitions: readonly SchemaDefinition[], id: string) => SchemaDefinition[];
 /**
- * Models that embed a component directly or through other components, i.e. whose entries change shape
- * when the component does (brief §5: "editing a shared component must account for all dependent models").
+ * Models that embed a component directly, through other components or through an inherited field, i.e.
+ * whose entries change shape when the component does (brief §5: "editing a shared component must account for
+ * all dependent models").
  */
 export declare const findDependentModels: (definitions: readonly SchemaDefinition[], componentId: string) => SchemaDefinition[];
 //#endregion
@@ -965,7 +1096,7 @@ export declare const isValidText: (text: string) => boolean;
 export declare const findInvalidText: (value: unknown, path?: string) => string | undefined;
 //#endregion
 //#region src/diff/types.d.ts
-export declare const CHANGE_KINDS: readonly ["definition.added", "definition.removed", "definition.apiKey", "definition.pluralApiKey", "definition.metadata", "model.kind", "model.localized", "model.draftAndPublish", "field.added", "field.removed", "field.order", "field.apiKey", "field.metadata", "field.editor", "field.type", "field.required", "field.localized", "field.public", "field.deprecated", "field.unique", "field.filterable", "field.sortable", "field.settings"];
+export declare const CHANGE_KINDS: readonly ["definition.added", "definition.removed", "definition.apiKey", "definition.pluralApiKey", "definition.metadata", "model.kind", "model.localized", "model.draftAndPublish", "model.extends", "field.added", "field.removed", "field.order", "field.apiKey", "field.metadata", "field.editor", "field.type", "field.required", "field.localized", "field.public", "field.deprecated", "field.unique", "field.filterable", "field.sortable", "field.settings"];
 export type ChangeKind = (typeof CHANGE_KINDS)[number];
 /**
  * One difference between two versions of a definition. `property` names the changed property for
@@ -1045,7 +1176,11 @@ export declare const typeChangeDropsValues: (from: StoredFieldShape, to: StoredF
 export type PlannedChange = SchemaChange & {
   dropsValues?: boolean;
 };
-/** Whether a (classified) change drops every stored value of its field; false for plans without the flag. */
+/**
+ * Whether a (classified) change drops every stored value of its field; false for plans without the flag. A
+ * type change Shapio cannot convert, or an inherited field a model loses when it moves to another parent
+ * (`field.removed` marked by the planner, plan polymorphic-types decision 6).
+ */
 export declare const changeDropsValues: (change: PlannedChange) => boolean;
 /** Classifies one change in the context of the definitions it was diffed from. */
 export declare const classifyChange: (change: SchemaChange, context: ClassifyContext) => ClassifiedChange;