@speclynx/apidom-core 4.0.3 → 4.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-core",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "description": "Tools for manipulating ApiDOM structures.",
   "keywords": [
     "apidom",
@@ -57,9 +57,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-datamodel": "4.0.3",
-    "@speclynx/apidom-error": "4.0.3",
-    "@speclynx/apidom-traverse": "4.0.3",
+    "@speclynx/apidom-datamodel": "4.0.5",
+    "@speclynx/apidom-error": "4.0.5",
+    "@speclynx/apidom-traverse": "4.0.5",
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.0.0",
     "short-unique-id": "^5.3.2",
@@ -67,7 +67,8 @@
     "yaml": "^2.8.2"
   },
   "files": [
-    "src/",
+    "src/**/*.mjs",
+    "src/**/*.cjs",
     "dist/",
     "types/apidom-core.d.ts",
     "LICENSES",
@@ -75,5 +76,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "6ccfa09c02232516215e7de3ead276641957e626"
+  "gitHead": "5a85d2a832eeefb07d03760faa391b457447e966"
 }

package/src/fields/fixed-fields.ts

@@ -1,61 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-
-/**
- * Represents a fixed field definition.
- * @public
- */
-export interface FixedField {
-  name: string;
-  [key: string]: unknown;
-}
-
-/**
- * @public
- */
-export type FixedFieldsElementClass = typeof Element & {
-  fixedFields?: FixedField[];
-};
-
-/**
- * Returns the fixed fields for an Element class or instance.
- *
- * @param elementOrClass - Element instance or class
- * @param options - Options for return format
- * @returns Array of fixed fields, or object indexed by name if options.indexed is true
- *
- * @example
- * ```ts
- * import { fixedFields } from '@speclynx/apidom-core';
- *
- * // Get fixed fields as array
- * const fields = fixedFields(ParameterElement);
- *
- * // Get fixed fields as indexed object for O(1) lookups
- * const fieldsIndex = fixedFields(ParameterElement, { indexed: true });
- * if (Object.hasOwn(fieldsIndex, 'description')) {
- *   // field exists
- * }
- * ```
- *
- * @public
- */
-export function fixedFields<T extends boolean = false>(
-  elementOrClass: Element | FixedFieldsElementClass,
-  options?: { indexed?: T },
-): T extends true ? Record<string, FixedField> : FixedField[] {
-  const constructor = (
-    elementOrClass instanceof Element ? elementOrClass.constructor : elementOrClass
-  ) as FixedFieldsElementClass;
-
-  const fields = constructor.fixedFields ?? [];
-
-  if (options?.indexed) {
-    return Object.fromEntries(fields.map((f) => [f.name, f])) as T extends true
-      ? Record<string, FixedField>
-      : FixedField[];
-  }
-
-  return fields as T extends true ? Record<string, FixedField> : FixedField[];
-}
-
-export default fixedFields;

package/src/fields/index.ts

@@ -1,2 +0,0 @@
-export { fixedFields, default } from './fixed-fields.ts';
-export type { FixedField, FixedFieldsElementClass } from './fixed-fields.ts';

package/src/identity/errors/ElementIdentityError.ts

@@ -1,26 +0,0 @@
-import { ApiDOMStructuredError } from '@speclynx/apidom-error';
-import type { ApiDOMErrorOptions } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-export interface ElementIdentityErrorOptions extends ApiDOMErrorOptions {
-  readonly value: unknown;
-}
-
-/**
- * @public
- */
-class ElementIdentityError extends ApiDOMStructuredError {
-  public readonly value: unknown;
-
-  constructor(message?: string, structuredOptions?: ElementIdentityErrorOptions) {
-    super(message, structuredOptions);
-
-    if (typeof structuredOptions !== 'undefined') {
-      this.value = structuredOptions.value;
-    }
-  }
-}
-
-export default ElementIdentityError;

package/src/identity/index.ts

@@ -1,64 +0,0 @@
-import { Element, isElement } from '@speclynx/apidom-datamodel';
-import ShortUniqueId from 'short-unique-id';
-
-import ElementIdentityError from './errors/ElementIdentityError.ts';
-
-/**
- * @public
- */
-export class IdentityManager {
-  protected readonly uuid: ShortUniqueId;
-
-  protected readonly identityMap: WeakMap<Element, string>;
-
-  constructor({ length = 6 } = {}) {
-    this.uuid = new ShortUniqueId({ length });
-    this.identityMap = new WeakMap();
-  }
-
-  identify<T extends Element>(this: IdentityManager, element: T): string {
-    if (!isElement(element)) {
-      throw new ElementIdentityError(
-        'Cannot not identify the element. `element` is neither structurally compatible nor a subclass of an Element class.',
-        {
-          value: element,
-        },
-      );
-    }
-
-    // use already assigned identity
-    if (element.hasMetaProperty('id')) {
-      const existingId = element.id;
-      if (typeof existingId === 'string' && existingId !== '') {
-        return existingId;
-      }
-    }
-
-    // assign identity in immutable way
-    if (this.identityMap.has(element)) {
-      return this.identityMap.get(element)!;
-    }
-
-    // return element identity
-    const id = this.generateId();
-    this.identityMap.set(element, id);
-    return id;
-  }
-
-  forget<T extends Element>(element: T): boolean {
-    if (this.identityMap.has(element)) {
-      this.identityMap.delete(element);
-      return true;
-    }
-    return false;
-  }
-
-  generateId(): string {
-    return this.uuid.randomUUID();
-  }
-}
-
-/**
- * @public
- */
-export const defaultIdentityManager = new IdentityManager();

package/src/index.ts

@@ -1,81 +0,0 @@
-export { dispatchPluginsSync as dispatchRefractorPlugins } from './refractor/plugins/dispatcher/index.ts';
-export type {
-  DispatchPluginsSync,
-  DispatchPluginsAsync,
-  DispatchPluginsOptions,
-} from './refractor/plugins/dispatcher/index.ts';
-
-export { default as createToolbox } from './refractor/toolbox.ts';
-export type { Toolbox, Predicates } from './refractor/toolbox.ts';
-
-export { default as refractorPluginElementIdentity } from './refractor/plugins/element-identity.ts';
-export { default as refractorPluginSemanticElementIdentity } from './refractor/plugins/semantic-element-identity.ts';
-
-export { default as MediaTypes } from './media-types.ts';
-
-export { transclude, default as Transcluder } from './transcluder/index.ts';
-
-export { resolveSpecification, type ResolvedSpecification } from './specification.ts';
-
-export { defaultIdentityManager, IdentityManager } from './identity/index.ts';
-export { default as ElementIdentityError } from './identity/errors/ElementIdentityError.ts';
-export type { ElementIdentityErrorOptions } from './identity/errors/ElementIdentityError.ts';
-
-/**
- * Transforms data to an Element from a particular namespace.
- */
-export { default as from } from './transformers/from.ts';
-
-/**
- * Transforms the ApiDOM into JavaScript POJO.
- * This POJO would be the result of interpreting the ApiDOM
- * into JavaScript structure.
- */
-export { default as toValue } from './transformers/serializers/value.ts';
-
-/**
- * Transforms the ApiDOM into JSON string.
- */
-export { default as toJSON, type JSONSerializerOptions } from './transformers/serializers/json.ts';
-
-/**
- * Transforms the ApiDOM into YAML string.
- */
-export {
-  default as toYAML,
-  type YAMLSerializerOptions,
-} from './transformers/serializers/yaml-1-2.ts';
-
-/**
- * Creates a refract representation of an Element.
- * https://github.com/refractproject/refract-spec
- */
-export { default as dehydrate } from './transformers/dehydrate.ts';
-
-/**
- * Create a refracted string representation of an Element.
- */
-export { default as toString } from './transformers/to-string.ts';
-
-export { default as sexprs } from './transformers/sexprs.ts';
-
-export { default as deepmerge } from './merge/deepmerge.ts';
-export type {
-  DeepMergeUserOptions,
-  ObjectOrArrayElement,
-  AnyElement,
-  DeepMerge,
-  DeepMergeOptions,
-  ArrayElementMerge as DeepMergeArrayElementMerge,
-  ObjectElementMerge as DeepMergeObjectElementMerge,
-  CustomMerge as DeepMergeCustomMerge,
-  CustomMetaMerge as DeepMergeCustomMetaMerge,
-  CustomAttributesMerge as DeepMergeCustomAttributesMerge,
-} from './merge/deepmerge.ts';
-export { default as mergeRight } from './merge/merge-right.ts';
-export type { MergeRightOptions } from './merge/merge-right.ts';
-export { default as mergeLeft } from './merge/merge-left.ts';
-export type { MergeRightOptions as MergeLeftOptions } from './merge/merge-right.ts';
-
-export { fixedFields } from './fields/index.ts';
-export type { FixedField, FixedFieldsElementClass } from './fields/index.ts';

package/src/media-types.ts

@@ -1,24 +0,0 @@
-import { NotImplementedError } from '@speclynx/apidom-error';
-
-/**
- * @public
- */
-class MediaTypes<T> extends Array<T> {
-  unknownMediaType = 'application/octet-stream';
-
-  filterByFormat() {
-    throw new NotImplementedError(
-      'filterByFormat method in MediaTypes class is not yet implemented.',
-    );
-  }
-
-  findBy() {
-    throw new NotImplementedError('findBy method in MediaTypes class is not yet implemented.');
-  }
-
-  latest() {
-    throw new NotImplementedError('latest method in MediaTypes class is not yet implemented.');
-  }
-}
-
-export default MediaTypes;

package/src/merge/deepmerge.ts

@@ -1,274 +0,0 @@
-import {
-  ObjectElement,
-  ArrayElement,
-  MemberElement,
-  Element,
-  Metadata,
-  isObjectElement,
-  isArrayElement,
-  cloneDeep,
-  cloneShallow,
-} from '@speclynx/apidom-datamodel';
-
-import toValue from '../transformers/serializers/value.ts';
-
-/**
- * @public
- */
-export type ObjectOrArrayElement = ObjectElement | ArrayElement;
-
-/**
- * @public
- */
-export type AnyElement = ObjectElement | ArrayElement | Element;
-
-/**
- * @public
- */
-export type DeepMerge = (
-  targetElement: ObjectOrArrayElement,
-  sourceElement: ObjectOrArrayElement,
-  options?: DeepMergeOptions,
-) => AnyElement;
-
-/**
- * @public
- */
-export type CustomMerge = (keyElement: Element, options: DeepMergeOptions) => DeepMerge;
-
-/**
- * @public
- */
-export type CustomMetaMerge = (
-  targetElementMeta: Metadata,
-  sourceElementMeta: Metadata,
-) => Metadata;
-
-/**
- * @public
- */
-export type CustomAttributesMerge = (
-  targetElementAttributes: ObjectElement,
-  sourceElementAttributes: ObjectElement,
-) => ObjectElement;
-
-/**
- * @public
- */
-export type ArrayElementMerge = (
-  targetElement: ArrayElement,
-  sourceElement: ArrayElement,
-  options: DeepMergeOptions,
-) => ArrayElement;
-
-/**
- * @public
- */
-export type ObjectElementMerge = (
-  targetElement: ObjectElement,
-  source: ObjectElement,
-  options: DeepMergeOptions,
-) => ObjectElement;
-
-/**
- * @public
- */
-export type DeepMergeUserOptions = {
-  clone?: boolean;
-  isMergeableElement?: (element: Element) => boolean;
-  arrayElementMerge?: ArrayElementMerge;
-  objectElementMerge?: ObjectElementMerge;
-  customMerge?: CustomMerge;
-  customMetaMerge?: CustomMetaMerge;
-  customAttributesMerge?: CustomAttributesMerge;
-};
-
-/**
- * @public
- */
-export type DeepMergeOptions = DeepMergeUserOptions & {
-  clone: boolean;
-  isMergeableElement: (element: Element) => boolean;
-  arrayElementMerge: ArrayElementMerge;
-  objectElementMerge: ObjectElementMerge;
-  customMerge: CustomMerge | undefined;
-  customMetaMerge: CustomMetaMerge | undefined;
-  customAttributesMerge: CustomAttributesMerge | undefined;
-};
-
-export const emptyElement = (element: ObjectElement | ArrayElement) => {
-  const meta = !element.isMetaEmpty ? element.meta.cloneDeep() : undefined;
-  const attributes = !element.isAttributesEmpty ? cloneDeep(element.attributes) : undefined;
-
-  // @ts-ignore
-  return new element.constructor(undefined, meta, attributes);
-};
-
-const cloneUnlessOtherwiseSpecified = (
-  element: AnyElement,
-  options: DeepMergeOptions,
-): AnyElement =>
-  options.clone && options.isMergeableElement(element)
-    ? deepmerge(
-        emptyElement(element as ObjectOrArrayElement),
-        element as ObjectOrArrayElement,
-        options,
-      )
-    : element;
-
-const getMergeFunction = (keyElement: Element, options: DeepMergeOptions): DeepMerge => {
-  if (typeof options.customMerge !== 'function') {
-    return deepmerge;
-  }
-  const customMerge = options.customMerge(keyElement, options);
-  return typeof customMerge === 'function' ? customMerge : deepmerge;
-};
-
-const getMetaMergeFunction = (options: DeepMergeOptions): CustomMetaMerge => {
-  if (typeof options.customMetaMerge !== 'function') {
-    return (targetMeta) => targetMeta.cloneDeep();
-  }
-  return options.customMetaMerge;
-};
-
-const getAttributesMergeFunction = (options: DeepMergeOptions): CustomAttributesMerge => {
-  if (typeof options.customAttributesMerge !== 'function') {
-    return (targetAttributes) => cloneDeep(targetAttributes);
-  }
-  return options.customAttributesMerge;
-};
-
-const mergeArrayElement: ArrayElementMerge = (targetElement, sourceElement, options) => {
-  const Ctor = targetElement.constructor as new (content: Element[]) => ArrayElement;
-  const merged = targetElement.concat(sourceElement) as ArrayElement;
-  return new Ctor(merged.map((item: Element) => cloneUnlessOtherwiseSpecified(item, options)));
-};
-
-const mergeObjectElement: ObjectElementMerge = (targetElement, sourceElement, options) => {
-  const destination = isObjectElement(targetElement)
-    ? emptyElement(targetElement)
-    : emptyElement(sourceElement);
-
-  if (isObjectElement(targetElement)) {
-    targetElement.forEach((value, key, member) => {
-      const clonedMember = cloneShallow(member as MemberElement);
-      clonedMember.value = cloneUnlessOtherwiseSpecified(value, options);
-      destination.content.push(clonedMember);
-    });
-  }
-
-  sourceElement.forEach((value, key, member) => {
-    const keyValue = toValue(key) as string;
-    let clonedMember;
-
-    if (
-      isObjectElement(targetElement) &&
-      targetElement.hasKey(keyValue) &&
-      options.isMergeableElement(value)
-    ) {
-      const targetValue = targetElement.get(keyValue)!;
-      clonedMember = cloneShallow(member as MemberElement);
-      clonedMember.value = getMergeFunction(key, options)(
-        targetValue as ObjectOrArrayElement,
-        value as ObjectOrArrayElement,
-        options,
-      );
-    } else {
-      clonedMember = cloneShallow(member as MemberElement);
-      clonedMember.value = cloneUnlessOtherwiseSpecified(value as AnyElement, options);
-    }
-
-    destination.remove(keyValue);
-    destination.content.push(clonedMember);
-  });
-
-  return destination;
-};
-
-export const defaultOptions: DeepMergeOptions = {
-  clone: true,
-  isMergeableElement: (element) => isObjectElement(element) || isArrayElement(element),
-  arrayElementMerge: mergeArrayElement,
-  objectElementMerge: mergeObjectElement,
-  customMerge: undefined,
-  customMetaMerge: undefined,
-  customAttributesMerge: undefined,
-};
-
-/**
- * @public
- */
-const deepmerge = (
-  targetElement: ObjectOrArrayElement,
-  sourceElement: ObjectOrArrayElement,
-  options?: DeepMergeUserOptions,
-): AnyElement => {
-  const mergedOptions: DeepMergeOptions = { ...defaultOptions, ...options };
-  mergedOptions.isMergeableElement =
-    mergedOptions.isMergeableElement ?? defaultOptions.isMergeableElement;
-  mergedOptions.arrayElementMerge =
-    mergedOptions.arrayElementMerge ?? defaultOptions.arrayElementMerge;
-  mergedOptions.objectElementMerge =
-    mergedOptions.objectElementMerge ?? defaultOptions.objectElementMerge;
-
-  const sourceIsArrayElement = isArrayElement(sourceElement);
-  const targetIsArrayElement = isArrayElement(targetElement);
-  const sourceAndTargetTypesMatch = sourceIsArrayElement === targetIsArrayElement;
-
-  if (!sourceAndTargetTypesMatch) {
-    return cloneUnlessOtherwiseSpecified(sourceElement, mergedOptions);
-  }
-
-  // merging two elements
-  const mergedElement =
-    sourceIsArrayElement && typeof mergedOptions.arrayElementMerge === 'function'
-      ? mergedOptions.arrayElementMerge(
-          targetElement as ArrayElement,
-          sourceElement as ArrayElement,
-          mergedOptions,
-        )
-      : mergedOptions.objectElementMerge(
-          targetElement as ObjectElement,
-          sourceElement as ObjectElement,
-          mergedOptions,
-        );
-
-  // merging meta & attributes
-  if (!targetElement.isMetaEmpty && !sourceElement.isMetaEmpty) {
-    mergedElement.meta = getMetaMergeFunction(mergedOptions)(
-      targetElement.meta,
-      sourceElement.meta,
-    );
-  } else if (!targetElement.isMetaEmpty) {
-    mergedElement.meta = targetElement.meta.cloneDeep();
-  } else if (!sourceElement.isMetaEmpty) {
-    mergedElement.meta = sourceElement.meta.cloneDeep();
-  }
-  if (!targetElement.isAttributesEmpty && !sourceElement.isAttributesEmpty) {
-    mergedElement.attributes = getAttributesMergeFunction(mergedOptions)(
-      targetElement.attributes,
-      sourceElement.attributes,
-    );
-  } else if (!targetElement.isAttributesEmpty) {
-    mergedElement.attributes = cloneDeep(targetElement.attributes);
-  } else if (!sourceElement.isAttributesEmpty) {
-    mergedElement.attributes = cloneDeep(sourceElement.attributes);
-  }
-
-  return mergedElement;
-};
-
-deepmerge.all = (list: ObjectOrArrayElement[], options?: DeepMergeUserOptions) => {
-  if (!Array.isArray(list)) {
-    throw new TypeError('First argument of deepmerge should be an array.');
-  }
-  if (list.length === 0) {
-    return new ObjectElement();
-  }
-
-  return list.reduce((target, source) => {
-    return deepmerge(target, source, options);
-  }, emptyElement(list[0]));
-};
-
-export default deepmerge;

package/src/merge/merge-left.ts

@@ -1,14 +0,0 @@
-import mergeRight from './merge-right.ts';
-
-/**
- * @public
- */
-const mergeLeft: typeof mergeRight = (...[sourceElement, targetElement, options]) => {
-  return mergeRight(targetElement, sourceElement, options);
-};
-
-mergeLeft.all = ((...[list, options]) => {
-  return mergeRight.all([...list].reverse(), options);
-}) as typeof mergeRight.all;
-
-export default mergeLeft;

package/src/merge/merge-right.ts

@@ -1,42 +0,0 @@
-import { ObjectElement } from '@speclynx/apidom-datamodel';
-
-import deepmerge, { defaultOptions as defaultDeepmergeOptions, emptyElement } from './deepmerge.ts';
-import type { ObjectOrArrayElement, DeepMergeUserOptions, AnyElement } from './deepmerge.ts';
-
-/**
- * @public
- */
-export type MergeRightOptions = Omit<DeepMergeUserOptions, 'customMerge' | 'clone'>;
-
-/**
- * @public
- */
-const mergeRight = (
-  targetElement: ObjectOrArrayElement,
-  sourceElement: ObjectOrArrayElement,
-  options?: MergeRightOptions,
-): AnyElement => {
-  const mergedOptions = {
-    ...defaultDeepmergeOptions,
-    ...options,
-    customMerge: () => (target: ObjectOrArrayElement, source: ObjectOrArrayElement) => source,
-    clone: false,
-  };
-
-  return deepmerge(targetElement, sourceElement, mergedOptions);
-};
-
-mergeRight.all = (list: ObjectOrArrayElement[], options?: MergeRightOptions) => {
-  if (!Array.isArray(list)) {
-    throw new TypeError('First argument of mergeRight should be an array.');
-  }
-  if (list.length === 0) {
-    return new ObjectElement();
-  }
-
-  return list.reduce((target, source) => {
-    return mergeRight(target, source, options);
-  }, emptyElement(list[0]));
-};
-
-export default mergeRight;

package/src/namespace.ts

@@ -1,8 +0,0 @@
-import { Namespace } from '@speclynx/apidom-datamodel';
-
-/**
- * Default namespace instance with all base elements registered.
- */
-const namespace = new Namespace();
-
-export default namespace;