@speclynx/apidom-core 4.0.2 → 4.0.3

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.0.3](https://github.com/speclynx/apidom/compare/v4.0.2...v4.0.3) (2026-03-11)
+
+### Bug Fixes
+
+- **release:** fix v4.0.2 failed release ([b4dc1c4](https://github.com/speclynx/apidom/commit/b4dc1c48e8d9b2986a70e49b5554eb0a166d7528))
+
 ## [4.0.2](https://github.com/speclynx/apidom/compare/v4.0.1...v4.0.2) (2026-03-11)
 
 **Note:** Version bump only for package @speclynx/apidom-core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-core",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "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.2",
-    "@speclynx/apidom-error": "4.0.2",
-    "@speclynx/apidom-traverse": "4.0.2",
+    "@speclynx/apidom-datamodel": "4.0.3",
+    "@speclynx/apidom-error": "4.0.3",
+    "@speclynx/apidom-traverse": "4.0.3",
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.0.0",
     "short-unique-id": "^5.3.2",
@@ -67,8 +67,7 @@
     "yaml": "^2.8.2"
   },
   "files": [
-    "src/**/*.mjs",
-    "src/**/*.cjs",
+    "src/",
     "dist/",
     "types/apidom-core.d.ts",
     "LICENSES",
@@ -76,5 +75,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "af1b05d4d5e48a11a3a03cd5699324e0f1b62765"
+  "gitHead": "6ccfa09c02232516215e7de3ead276641957e626"
 }

package/src/fields/fixed-fields.cjs

@@ -0,0 +1,47 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+exports.fixedFields = fixedFields;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+/**
+ * Represents a fixed field definition.
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * 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
+ */
+function fixedFields(elementOrClass, options) {
+  const constructor = elementOrClass instanceof _apidomDatamodel.Element ? elementOrClass.constructor : elementOrClass;
+  const fields = constructor.fixedFields ?? [];
+  if (options?.indexed) {
+    return Object.fromEntries(fields.map(f => [f.name, f]));
+  }
+  return fields;
+}
+var _default = exports.default = fixedFields;

package/src/fields/fixed-fields.mjs

@@ -0,0 +1,43 @@
+import { Element } from '@speclynx/apidom-datamodel';
+
+/**
+ * Represents a fixed field definition.
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * 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(elementOrClass, options) {
+  const constructor = elementOrClass instanceof Element ? elementOrClass.constructor : elementOrClass;
+  const fields = constructor.fixedFields ?? [];
+  if (options?.indexed) {
+    return Object.fromEntries(fields.map(f => [f.name, f]));
+  }
+  return fields;
+}
+export default fixedFields;

package/src/fields/fixed-fields.ts

@@ -0,0 +1,61 @@
+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.cjs

@@ -0,0 +1,8 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+exports.__esModule = true;
+exports.fixedFields = exports.default = void 0;
+var _fixedFields = _interopRequireWildcard(require("./fixed-fields.cjs"));
+exports.fixedFields = _fixedFields.fixedFields;
+exports.default = _fixedFields.default;

package/src/fields/index.mjs

@@ -0,0 +1 @@
+export { fixedFields, default } from "./fixed-fields.mjs";

package/src/fields/index.ts

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

package/src/identity/errors/ElementIdentityError.cjs

@@ -0,0 +1,22 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ElementIdentityError extends _apidomError.ApiDOMStructuredError {
+  value;
+  constructor(message, structuredOptions) {
+    super(message, structuredOptions);
+    if (typeof structuredOptions !== 'undefined') {
+      this.value = structuredOptions.value;
+    }
+  }
+}
+var _default = exports.default = ElementIdentityError;

package/src/identity/errors/ElementIdentityError.mjs

@@ -0,0 +1,19 @@
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ElementIdentityError extends ApiDOMStructuredError {
+  value;
+  constructor(message, structuredOptions) {
+    super(message, structuredOptions);
+    if (typeof structuredOptions !== 'undefined') {
+      this.value = structuredOptions.value;
+    }
+  }
+}
+export default ElementIdentityError;

package/src/identity/errors/ElementIdentityError.ts

@@ -0,0 +1,26 @@
+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.cjs

@@ -0,0 +1,64 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.defaultIdentityManager = exports.IdentityManager = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _shortUniqueId = _interopRequireDefault(require("short-unique-id"));
+var _ElementIdentityError = _interopRequireDefault(require("./errors/ElementIdentityError.cjs"));
+/**
+ * @public
+ */
+class IdentityManager {
+  uuid;
+  identityMap;
+  constructor({
+    length = 6
+  } = {}) {
+    this.uuid = new _shortUniqueId.default({
+      length
+    });
+    this.identityMap = new WeakMap();
+  }
+  identify(element) {
+    if (!(0, _apidomDatamodel.isElement)(element)) {
+      throw new _ElementIdentityError.default('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(element) {
+    if (this.identityMap.has(element)) {
+      this.identityMap.delete(element);
+      return true;
+    }
+    return false;
+  }
+  generateId() {
+    return this.uuid.randomUUID();
+  }
+}
+
+/**
+ * @public
+ */
+exports.IdentityManager = IdentityManager;
+const defaultIdentityManager = exports.defaultIdentityManager = new IdentityManager();

package/src/identity/index.mjs

@@ -0,0 +1,58 @@
+import { isElement } from '@speclynx/apidom-datamodel';
+import ShortUniqueId from 'short-unique-id';
+import ElementIdentityError from "./errors/ElementIdentityError.mjs";
+/**
+ * @public
+ */
+export class IdentityManager {
+  uuid;
+  identityMap;
+  constructor({
+    length = 6
+  } = {}) {
+    this.uuid = new ShortUniqueId({
+      length
+    });
+    this.identityMap = new WeakMap();
+  }
+  identify(element) {
+    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(element) {
+    if (this.identityMap.has(element)) {
+      this.identityMap.delete(element);
+      return true;
+    }
+    return false;
+  }
+  generateId() {
+    return this.uuid.randomUUID();
+  }
+}
+
+/**
+ * @public
+ */
+export const defaultIdentityManager = new IdentityManager();

package/src/identity/index.ts

@@ -0,0 +1,64 @@
+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.cjs

@@ -0,0 +1,48 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.transclude = exports.toYAML = exports.toValue = exports.toString = exports.toJSON = exports.sexprs = exports.resolveSpecification = exports.refractorPluginSemanticElementIdentity = exports.refractorPluginElementIdentity = exports.mergeRight = exports.mergeLeft = exports.from = exports.fixedFields = exports.dispatchRefractorPlugins = exports.dehydrate = exports.defaultIdentityManager = exports.deepmerge = exports.createToolbox = exports.Transcluder = exports.MediaTypes = exports.IdentityManager = exports.ElementIdentityError = void 0;
+var _index = require("./refractor/plugins/dispatcher/index.cjs");
+exports.dispatchRefractorPlugins = _index.dispatchPluginsSync;
+var _toolbox = _interopRequireDefault(require("./refractor/toolbox.cjs"));
+exports.createToolbox = _toolbox.default;
+var _elementIdentity = _interopRequireDefault(require("./refractor/plugins/element-identity.cjs"));
+exports.refractorPluginElementIdentity = _elementIdentity.default;
+var _semanticElementIdentity = _interopRequireDefault(require("./refractor/plugins/semantic-element-identity.cjs"));
+exports.refractorPluginSemanticElementIdentity = _semanticElementIdentity.default;
+var _mediaTypes = _interopRequireDefault(require("./media-types.cjs"));
+exports.MediaTypes = _mediaTypes.default;
+var _index2 = _interopRequireWildcard(require("./transcluder/index.cjs"));
+exports.transclude = _index2.transclude;
+exports.Transcluder = _index2.default;
+var _specification = require("./specification.cjs");
+exports.resolveSpecification = _specification.resolveSpecification;
+var _index3 = require("./identity/index.cjs");
+exports.defaultIdentityManager = _index3.defaultIdentityManager;
+exports.IdentityManager = _index3.IdentityManager;
+var _ElementIdentityError = _interopRequireDefault(require("./identity/errors/ElementIdentityError.cjs"));
+exports.ElementIdentityError = _ElementIdentityError.default;
+var _from = _interopRequireDefault(require("./transformers/from.cjs"));
+exports.from = _from.default;
+var _value = _interopRequireDefault(require("./transformers/serializers/value.cjs"));
+exports.toValue = _value.default;
+var _json = _interopRequireDefault(require("./transformers/serializers/json.cjs"));
+exports.toJSON = _json.default;
+var _yaml = _interopRequireDefault(require("./transformers/serializers/yaml-1-2.cjs"));
+exports.toYAML = _yaml.default;
+var _dehydrate = _interopRequireDefault(require("./transformers/dehydrate.cjs"));
+exports.dehydrate = _dehydrate.default;
+var _toString = _interopRequireDefault(require("./transformers/to-string.cjs"));
+exports.toString = _toString.default;
+var _sexprs = _interopRequireDefault(require("./transformers/sexprs.cjs"));
+exports.sexprs = _sexprs.default;
+var _deepmerge = _interopRequireDefault(require("./merge/deepmerge.cjs"));
+exports.deepmerge = _deepmerge.default;
+var _mergeRight = _interopRequireDefault(require("./merge/merge-right.cjs"));
+exports.mergeRight = _mergeRight.default;
+var _mergeLeft = _interopRequireDefault(require("./merge/merge-left.cjs"));
+exports.mergeLeft = _mergeLeft.default;
+var _index4 = require("./fields/index.cjs");
+exports.fixedFields = _index4.fixedFields;

package/src/index.mjs

@@ -0,0 +1,41 @@
+export { dispatchPluginsSync as dispatchRefractorPlugins } from "./refractor/plugins/dispatcher/index.mjs";
+export { default as createToolbox } from "./refractor/toolbox.mjs";
+export { default as refractorPluginElementIdentity } from "./refractor/plugins/element-identity.mjs";
+export { default as refractorPluginSemanticElementIdentity } from "./refractor/plugins/semantic-element-identity.mjs";
+export { default as MediaTypes } from "./media-types.mjs";
+export { transclude, default as Transcluder } from "./transcluder/index.mjs";
+export { resolveSpecification } from "./specification.mjs";
+export { defaultIdentityManager, IdentityManager } from "./identity/index.mjs";
+export { default as ElementIdentityError } from "./identity/errors/ElementIdentityError.mjs";
+/**
+ * Transforms data to an Element from a particular namespace.
+ */
+export { default as from } from "./transformers/from.mjs";
+/**
+ * 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.mjs";
+/**
+ * Transforms the ApiDOM into JSON string.
+ */
+export { default as toJSON } from "./transformers/serializers/json.mjs";
+/**
+ * Transforms the ApiDOM into YAML string.
+ */
+export { default as toYAML } from "./transformers/serializers/yaml-1-2.mjs";
+/**
+ * Creates a refract representation of an Element.
+ * https://github.com/refractproject/refract-spec
+ */
+export { default as dehydrate } from "./transformers/dehydrate.mjs";
+/**
+ * Create a refracted string representation of an Element.
+ */
+export { default as toString } from "./transformers/to-string.mjs";
+export { default as sexprs } from "./transformers/sexprs.mjs";
+export { default as deepmerge } from "./merge/deepmerge.mjs";
+export { default as mergeRight } from "./merge/merge-right.mjs";
+export { default as mergeLeft } from "./merge/merge-left.mjs";
+export { fixedFields } from "./fields/index.mjs";

package/src/index.ts

@@ -0,0 +1,81 @@
+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.cjs

@@ -0,0 +1,21 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+/**
+ * @public
+ */
+class MediaTypes extends Array {
+  unknownMediaType = 'application/octet-stream';
+  filterByFormat() {
+    throw new _apidomError.NotImplementedError('filterByFormat method in MediaTypes class is not yet implemented.');
+  }
+  findBy() {
+    throw new _apidomError.NotImplementedError('findBy method in MediaTypes class is not yet implemented.');
+  }
+  latest() {
+    throw new _apidomError.NotImplementedError('latest method in MediaTypes class is not yet implemented.');
+  }
+}
+var _default = exports.default = MediaTypes;