Class: ShadowApplicationService

Defined in: application/services/core/ShadowService.ts:120

Schema-aware operations on the editing shadow of a document, bound to one profile schema and type library. Wraps the shadow model functions (normalize, patch, schema lookup) and adds helpers that editors use to render unions, arrays, identifiers and agents.

Example

const shadow = new ShadowApplicationService(profile.schema, typeLibrary);
const view = shadow.normalize(doc.data, { seedEmpty: true });
const next = shadow.applyPatch(doc.data, path, newValue);
const label = shadow.deriveDocumentLabel(next);

Constructors

Constructor

new ShadowApplicationService(profileSchema, typeLibrary?): ShadowApplicationService;

Defined in: application/services/core/ShadowService.ts:127

Parameters

Parameter	Type	Description
profileSchema	any	JSON Schema of the document profile.
typeLibrary?	any	Type library schema used to resolve $refs into its $defs.

Returns

ShadowApplicationService

Methods

applyPatch()

applyPatch(
   documentData, 
   path, 
   value
): DocumentData;

Defined in: application/services/core/ShadowService.ts:154

Returns a normalized copy of the data with value written at path, coerced to the schema type there.

Parameters

Parameter	Type
documentData	DocumentData
path	PathSegment[]
value	any

Returns

DocumentData

---

buildSeedValueFromSchema()

buildSeedValueFromSchema(fieldSchema, text?): any;

Defined in: application/services/core/ShadowService.ts:833

Builds an initial value for a field from plain text: a one-item Literal list for text-object array fields, the text itself for string fields, otherwise null.

Parameters

Parameter	Type
fieldSchema	any
text?	string

Returns

any

---

createEmptyFromSchema()

createEmptyFromSchema(schemaNode, options?): any;

Defined in: application/services/core/ShadowService.ts:179

Creates an empty value for a schema node. See the options of the shadow model's createEmptyFromSchema.

Parameters

Parameter	Type
schemaNode	any
options?	{ includeRequired?: boolean; seedArrayItem?: boolean; }
options.includeRequired?	boolean
options.seedArrayItem?	boolean

Returns

any

---

createSeedForAddedField()

createSeedForAddedField(fieldSchema): any;

Defined in: application/services/core/ShadowService.ts:702

Creates the initial value for a field the user has just added. Arrays get one empty item ([''] for Date items); unions use their first array branch when they have one.

Parameters

Parameter	Type
fieldSchema	any

Returns

any

---

createShadow()

createShadow(documentData): DocumentData;

Defined in: application/services/core/ShadowService.ts:132

Builds the full editing shadow: normalized data merged into a template generated from the schema.

Parameters

Parameter	Type
documentData	DocumentData

Returns

DocumentData

---

deriveDocumentLabel()

deriveDocumentLabel(documentData, options?): string;

Defined in: application/services/core/ShadowService.ts:849

Derives a display label for a document from its preferred seed field, then from the first other field with a plain string or a string text entry. Falls back to fallbackId, defaultLabel or Untitled.

Parameters

Parameter	Type
documentData	DocumentData | undefined
options?	{ defaultLabel?: string; fallbackId?: string; profileSchema?: any; }
options.defaultLabel?	string
options.fallbackId?	string
options.profileSchema?	any

Returns

string

---

getAllowedSchemas()

getAllowedSchemas(schemaNode): IdentifierScheme[] | null;

Defined in: application/services/core/ShadowService.ts:579

Returns the identifier schemes listed in x-sidedoc.allowedSchemas of a schema node, or null if there are none. Known scheme names (such as ORCID, ROR or DOI) are expanded to their resolver URI, pattern and example; object entries inherit the pattern and example of a known scheme with the same URI.

Parameters

Parameter	Type
schemaNode	any

Returns

IdentifierScheme[] | null

---

getArrayPatterns()

getArrayPatterns(input): object;

Defined in: application/services/core/ShadowService.ts:617

Derives how an array field should be edited: whether it is a translation list, nested language array or single multilingual value, its item limits, and whether more items can be added.

Parameters

Parameter	Type
input	{ arraySchema: any; itemSchema: any; list: any[]; resolvedItemSchema: any; }
input.arraySchema	any
input.itemSchema	any
input.list	any[]
input.resolvedItemSchema	any

Returns

object

canAddMore

canAddMore: boolean;

hasItemUnion

hasItemUnion: boolean;

isNestedLangArray

isNestedLangArray: boolean;

isSingleMultilang

isSingleMultilang: boolean;

isTranslationArray

isTranslationArray: boolean;

maxAllowed

maxAllowed: number;

minAllowed

minAllowed: number;

showAddButton

showAddButton: boolean;

---

getFieldDisplayLabel()

getFieldDisplayLabel(fieldSchema, fallbackKey): string;

Defined in: application/services/core/ShadowService.ts:744

Display label for a field from x-sidedoc (labelSingularEn, labelSingular or label), falling back to a humanized form of fallbackKey.

Parameters

Parameter	Type
fieldSchema	any
fallbackKey	string

Returns

string

---

getMaxOccurrences()

getMaxOccurrences(schemaNode): number;

Defined in: application/services/core/ShadowService.ts:174

Maximum number of items allowed by a schema node (Infinity when unbounded).

Parameters

Parameter	Type
schemaNode	any

Returns

number

---

getMinOccurrences()

getMinOccurrences(schemaNode): number;

Defined in: application/services/core/ShadowService.ts:169

Minimum number of items allowed by a schema node (0 when unspecified).

Parameters

Parameter	Type
schemaNode	any

Returns

number

---

getPreferredSeedField()

getPreferredSeedField(profileSchema?): object;

Defined in: application/services/core/ShadowService.ts:803

Picks the root field to seed from a title: title if present, then the first array field of text objects, then the first string field, then the first property.

Parameters

Parameter	Type
profileSchema?	any

Returns

object

fieldName

fieldName: string | null;

fieldSchema

fieldSchema: any;

---

getSchemaForPath()

getSchemaForPath(path): object;

Defined in: application/services/core/ShadowService.ts:159

Resolves the schema node and type name at path. Returns a null node when the path is not in the schema.

Parameters

Parameter	Type
path	PathSegment[]

Returns

object

node

node: any;

refName

refName: string | null;

---

getUnionLabel()

getUnionLabel(schemaNode, index): string;

Defined in: application/services/core/ShadowService.ts:370

Display label for a union option: the type name, title, constant type value or JSON type, falling back to Option N.

Parameters

Parameter	Type
schemaNode	any
index	number

Returns

string

---

getUnionList()

getUnionList(schemaNode): any[] | null;

Defined in: application/services/core/ShadowService.ts:283

Returns the alternatives of a union schema node (oneOf/anyOf, before or after resolving $ref), or null when the node is not a union. An array whose items are a union is expanded into one array option per item type. Branches that only add constraints (no type or shape of their own) do not count as a union.

Parameters

Parameter	Type
schemaNode	any

Returns

any[] | null

---

hasMeaningfulContent()

hasMeaningfulContent(value): boolean;

Defined in: application/services/core/ShadowService.ts:265

True when a value contains any non-blank string, number or boolean, ignoring type and lang keys.

Parameters

Parameter	Type
value	any

Returns

boolean

---

isAgentLikeItem()

isAgentLikeItem(schemaNode): boolean;

Defined in: application/services/core/ShadowService.ts:539

True when an object schema has string name, agentType and type properties, like an Agent value.

Parameters

Parameter	Type
schemaNode	any

Returns

boolean

---

isFieldPersistedPresent()

isFieldPersistedPresent(
   parentValue, 
   key, 
   _isRequired?, 
   _parentPath?
): boolean;

Defined in: application/services/core/ShadowService.ts:684

True when parentValue has an own, non-null value for key. The last two parameters are currently unused.

Parameters

Parameter	Type	Default value
parentValue	any	undefined
key	string	undefined
_isRequired?	boolean	false
_parentPath?	(string | number)[]	[]

Returns

boolean

---

isLiteralArrayField()

isLiteralArrayField(fieldSchema): boolean;

Defined in: application/services/core/ShadowService.ts:673

True when the field is an array of objects that have a text property.

Parameters

Parameter	Type
fieldSchema	any

Returns

boolean

---

isUrlLikeItem()

isUrlLikeItem(schemaNode): boolean;

Defined in: application/services/core/ShadowService.ts:530

True when an object schema has a string href and an array label, like a Url value.

Parameters

Parameter	Type
schemaNode	any

Returns

boolean

---

listAgents()

listAgents(documentData, excludePath?): object[];

Defined in: application/services/core/ShadowService.ts:765

Lists all non-empty Agent values in the document data with their paths. Agents are returned as deep copies. The agent at excludePath is skipped.

Parameters

Parameter	Type	Default value
documentData	any	undefined
excludePath?	PathSegment[] | null	null

Returns

object[]

---

matchUnionIndex()

matchUnionIndex(unionList, currentValue): number;

Defined in: application/services/core/ShadowService.ts:397

Returns the index of the union option that matches currentValue, or -1 if none matches or the value is null or undefined. Matching is based on the value's type and shape.

Parameters

Parameter	Type
unionList	any[]
currentValue	any

Returns

number

---

normalize()

normalize(documentData, options?): DocumentData;

Defined in: application/services/core/ShadowService.ts:145

Normalizes document data against the profile schema.

Parameters

Parameter	Type	Description
documentData	DocumentData	-
options?	{ pruneEmpty?: boolean; seedEmpty?: boolean; }	pruneEmpty drops blank Literal and RichText values (for load or clean passes); seedEmpty adds one blank starter item to empty multivalue fields (display only).
options.pruneEmpty?	boolean	-
options.seedEmpty?	boolean	-

Returns

DocumentData

---

pickTranslation()

pickTranslation<T>(
   list, 
   targetLang?, 
   fallbackOrder?
): object;

Defined in: application/services/core/ShadowService.ts:270

Picks an entry by lang: first targetLang, then fallbackOrder, then any entry with a language.

Type Parameters

Type Parameter
T extends object

Parameters

Parameter	Type	Default value
list	T[] | undefined	undefined
targetLang?	string	undefined
fallbackOrder?	string[]	[]

Returns

object

entry

entry: T | null;

usedLang

usedLang: string | null;

---

resolveSchemaNode()

resolveSchemaNode(node): object;

Defined in: application/services/core/ShadowService.ts:164

Resolves $ref and takes the first oneOf/anyOf option of a schema node.

Parameters

Parameter	Type
node	any

Returns

object

node

node: any;

refName

refName: string | null;

---

resolveVocabularyBinding()

resolveVocabularyBinding(path): 
  | FieldVocabularyBinding
  | null;

Defined in: application/services/core/ShadowService.ts:188

Finds the vocabulary binding (x-sidedoc.vocab or x-sidedoc-vocab) for a field path. Array indexes and _value, type and lang segments are ignored, and all union branches are searched. When several levels declare a binding, the deepest one wins. Returns null if none is found.

Parameters

Parameter	Type
path	PathSegment[]

Returns

| FieldVocabularyBinding | null