@speclynx/apidom-core 2.13.0 → 3.0.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.0.0](https://github.com/speclynx/apidom/compare/v2.13.1...v3.0.0) (2026-03-05)
+
+### Features
+
+- introduce new memory efficient meta data management ([#129](https://github.com/speclynx/apidom/issues/129)) ([82ae0d7](https://github.com/speclynx/apidom/commit/82ae0d7cc2e9ee7037c3d9681817add2ca18dc92))
+
+### BREAKING CHANGES
+
+- meta data use to be elements before, now they are simple primitives
+
+## [2.13.1](https://github.com/speclynx/apidom/compare/v2.13.0...v2.13.1) (2026-02-28)
+
+**Note:** Version bump only for package @speclynx/apidom-core
+
 # [2.13.0](https://github.com/speclynx/apidom/compare/v2.12.4...v2.13.0) (2026-02-28)
 
 **Note:** Version bump only for package @speclynx/apidom-core

package/README.md

@@ -377,16 +377,20 @@ The `customMetaMerge` function will be passed target and source metadata. If not
 the default behavior is to deep copy metadata from target to new merged element.
 
 ```js
-import { ObjectElement } from '@speclynx/apidom-datamodel';
+import { ObjectElement, Metadata } from '@speclynx/apidom-datamodel';
 import { deepmerge } from '@speclynx/apidom-core';
 
 const alex = new ObjectElement({ name: { first: 'Alex' } }, { metaKey: true });
 const tony = new ObjectElement({ name: { first: 'Tony' } }, { metaKey: false });
 
-const customMetaMerge = (targetMeta, sourceMeta) => deepmerge(targetMeta, sourceMeta);
+const customMetaMerge = (targetMeta, sourceMeta) => {
+  const merged = new Metadata();
+  Object.assign(merged, targetMeta, sourceMeta);
+  return merged;
+};
 
 const output = deepmerge(alex, tony, { customMetaMerge });
-// output.meta.get('metaKey') // => BooleanElement(false)
+// output.meta.get('metaKey') // => false
 ```
 
 #### customAttributesMerge

package/dist/apidom-core.browser.js

@@ -106,10 +106,9 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */   defaultIdentityManager: () => (/* binding */ defaultIdentityManager)
 /* harmony export */ });
 /* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(5162);
-/* harmony import */ var _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(8121);
-/* harmony import */ var short_unique_id__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(4279);
-/* harmony import */ var short_unique_id__WEBPACK_IMPORTED_MODULE_2___default = /*#__PURE__*/__webpack_require__.n(short_unique_id__WEBPACK_IMPORTED_MODULE_2__);
-/* harmony import */ var _errors_ElementIdentityError_ts__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(421);
+/* harmony import */ var short_unique_id__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(4279);
+/* harmony import */ var short_unique_id__WEBPACK_IMPORTED_MODULE_1___default = /*#__PURE__*/__webpack_require__.n(short_unique_id__WEBPACK_IMPORTED_MODULE_1__);
+/* harmony import */ var _errors_ElementIdentityError_ts__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(421);
 
 
 
@@ -123,23 +122,23 @@ class IdentityManager {
   constructor({
     length = 6
   } = {}) {
-    this.uuid = new (short_unique_id__WEBPACK_IMPORTED_MODULE_2___default())({
+    this.uuid = new (short_unique_id__WEBPACK_IMPORTED_MODULE_1___default())({
       length
     });
     this.identityMap = new WeakMap();
   }
   identify(element) {
     if (!(0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isElement)(element)) {
-      throw new _errors_ElementIdentityError_ts__WEBPACK_IMPORTED_MODULE_3__["default"]('Cannot not identify the element. `element` is neither structurally compatible nor a subclass of an Element class.', {
+      throw new _errors_ElementIdentityError_ts__WEBPACK_IMPORTED_MODULE_2__["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.meta.get('id');
-      if ((0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_0__.isStringElement)(existingId) && !existingId.equals('')) {
-        return element.id;
+      const existingId = element.id;
+      if (typeof existingId === 'string' && existingId !== '') {
+        return existingId;
       }
     }
 
@@ -149,7 +148,7 @@ class IdentityManager {
     }
 
     // return element identity
-    const id = new _speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__["default"](this.generateId());
+    const id = this.generateId();
     this.identityMap.set(element, id);
     return id;
   }
@@ -258,7 +257,7 @@ __webpack_require__.r(__webpack_exports__);
  */
 
 const emptyElement = element => {
-  const meta = !element.isMetaEmpty ? (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(element.meta) : undefined;
+  const meta = !element.isMetaEmpty ? element.meta.cloneDeep() : undefined;
   const attributes = !element.isAttributesEmpty ? (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(element.attributes) : undefined;
 
   // @ts-ignore
@@ -274,7 +273,7 @@ const getMergeFunction = (keyElement, options) => {
 };
 const getMetaMergeFunction = options => {
   if (typeof options.customMetaMerge !== 'function') {
-    return targetMeta => (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(targetMeta);
+    return targetMeta => targetMeta.cloneDeep();
   }
   return options.customMetaMerge;
 };
@@ -346,8 +345,20 @@ const deepmerge = (targetElement, sourceElement, options) => {
   const mergedElement = sourceIsArrayElement && typeof mergedOptions.arrayElementMerge === 'function' ? mergedOptions.arrayElementMerge(targetElement, sourceElement, mergedOptions) : mergedOptions.objectElementMerge(targetElement, sourceElement, mergedOptions);
 
   // merging meta & attributes
-  mergedElement.meta = getMetaMergeFunction(mergedOptions)(targetElement.meta, sourceElement.meta);
-  mergedElement.attributes = getAttributesMergeFunction(mergedOptions)(targetElement.attributes, sourceElement.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 = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(targetElement.attributes);
+  } else if (!sourceElement.isAttributesEmpty) {
+    mergedElement.attributes = (0,_speclynx_apidom_datamodel__WEBPACK_IMPORTED_MODULE_1__.cloneDeep)(sourceElement.attributes);
+  }
   return mergedElement;
 };
 deepmerge.all = (list, options) => {
@@ -24783,6 +24794,104 @@ class KeyValuePair {
 
 /***/ },
 
+/***/ 1844
+(__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) {
+
+__webpack_require__.r(__webpack_exports__);
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
+/* harmony export */ });
+/* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(8138);
+
+/**
+ * Lightweight meta container for Element metadata.
+ *
+ * Data is stored as own properties on the instance; methods live on the prototype.
+ * `Object.keys()`, `Object.entries()`, etc. only see data properties.
+ *
+ * @public
+ */
+class Metadata {
+  // Set via prototype assignment in registration.ts to avoid circular dependency
+
+  get(name) {
+    return this[name];
+  }
+  set(name, value) {
+    this[name] = value;
+  }
+  hasKey(name) {
+    return Object.hasOwn(this, name);
+  }
+  keys() {
+    return Object.keys(this);
+  }
+  remove(name) {
+    delete this[name];
+  }
+  get isEmpty() {
+    return Object.keys(this).length === 0;
+  }
+  get isFrozen() {
+    return Object.isFrozen(this);
+  }
+  freeze() {
+    for (const value of Object.values(this)) {
+      if (value instanceof this.Element) {
+        value.freeze();
+      } else if (Array.isArray(value) || value !== null && typeof value === 'object') {
+        Object.freeze(value);
+      }
+    }
+    Object.freeze(this);
+  }
+
+  /**
+   * Creates a shallow clone. Same references, new container.
+   */
+  cloneShallow() {
+    const clone = new Metadata();
+    Object.assign(clone, this);
+    return clone;
+  }
+
+  /**
+   * Merges another Metadata into a new instance.
+   * Arrays are concatenated, all other values are overwritten by source.
+   */
+  merge(source) {
+    const result = this.cloneShallow();
+    for (const [key, value] of Object.entries(source)) {
+      const existing = result.get(key);
+      if (Array.isArray(existing) && Array.isArray(value)) {
+        result.set(key, [...existing, ...value]);
+      } else {
+        result.set(key, value);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Creates a deep clone. Elements are deep cloned,
+   * all other values are deep cloned via ramda clone.
+   */
+  cloneDeep() {
+    const copy = new Metadata();
+    for (const [key, value] of Object.entries(this)) {
+      if (value instanceof this.Element) {
+        copy.set(key, this.cloneDeepElement(value));
+      } else {
+        copy.set(key, (0,ramda__WEBPACK_IMPORTED_MODULE_0__["default"])(value));
+      }
+    }
+    return copy;
+  }
+}
+/* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (Metadata);
+
+/***/ },
+
 /***/ 5156
 (__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) {
 
@@ -25423,7 +25532,7 @@ const cloneShallowElement = element => {
   const copy = new Ctor();
   copy.element = element.element;
   if (!element.isMetaEmpty) {
-    copy.meta = cloneDeep(element.meta);
+    copy.meta = element.meta.cloneDeep();
   }
   if (!element.isAttributesEmpty) {
     copy.attributes = cloneDeep(element.attributes);
@@ -25451,8 +25560,8 @@ const cloneShallowElement = element => {
 
 /**
  * Creates a shallow clone of an ApiDOM Element, KeyValuePair, or ObjectSlice.
- * The element itself is cloned, but content references are shared (except for
- * meta and attributes which are deep cloned to preserve semantic information).
+ * The element itself is cloned, but content references are shared.
+ * Meta and attributes are deep cloned to preserve semantic information.
  * @public
  */
 const cloneShallow = value => {
@@ -26514,7 +26623,7 @@ class CollectionElement extends _Element_mjs__WEBPACK_IMPORTED_MODULE_0__["defau
    * Search the tree recursively and find the element with the matching ID.
    */
   getById(id) {
-    return this.find(item => item.id.toValue() === id).first;
+    return this.find(item => item.id === id).first;
   }
 
   /**
@@ -26543,18 +26652,24 @@ class CollectionElement extends _Element_mjs__WEBPACK_IMPORTED_MODULE_0__["defau
 
 __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   Metadata: () => (/* reexport safe */ _Metadata_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]),
 /* harmony export */   "default": () => (__WEBPACK_DEFAULT_EXPORT__)
 /* harmony export */ });
 /* harmony import */ var ramda__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(3654);
-/* harmony import */ var _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(6663);
-/* harmony import */ var _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(8504);
+/* harmony import */ var _Metadata_mjs__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(1844);
+/* harmony import */ var _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(6663);
+/* harmony import */ var _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_3__ = __webpack_require__(8504);
+
 
 
+ // shared singleton for frozen elements with no meta — avoids allocation on every access
+const FROZEN_EMPTY_METADATA = Object.freeze(new _Metadata_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]());
 
 /**
  * Valid content types for an Element.
  * @public
  */
+
 /**
  * Base Element class that all ApiDOM elements extend.
  *
@@ -26652,7 +26767,7 @@ class Element {
   _attributes;
 
   // ============================================================
-  // Prototype-assigned properties (set in elements.ts)
+  // Prototype-assigned properties (set in registration.ts)
   // Using 'declare' allows TypeScript to know about these
   // without generating runtime code.
   // ============================================================
@@ -26713,13 +26828,13 @@ class Element {
     }
 
     // KeyValuePair
-    if (value instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]) {
+    if (value instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]) {
       this._content = value;
       return;
     }
 
     // ObjectSlice - extract elements array
-    if (value instanceof _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]) {
+    if (value instanceof _ObjectSlice_mjs__WEBPACK_IMPORTED_MODULE_3__["default"]) {
       this._content = value.elements;
       return;
     }
@@ -26740,24 +26855,22 @@ class Element {
 
   /**
    * Metadata about this element (id, classes, title, description, links).
-   * Lazily creates an ObjectElement if not set.
+   * Lazily creates a Metadata instance if not set.
    */
   get meta() {
     if (!this._meta) {
-      if (this.isFrozen) {
-        const meta = new this.ObjectElement();
-        meta.freeze();
-        return meta;
-      }
-      this._meta = new this.ObjectElement();
+      if (this.isFrozen) return FROZEN_EMPTY_METADATA;
+      this._meta = new _Metadata_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]();
     }
     return this._meta;
   }
   set meta(value) {
-    if (value instanceof Element) {
+    if (value instanceof _Metadata_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]) {
       this._meta = value;
-    } else {
-      this.meta.set(value ?? {});
+    } else if (value && typeof value === 'object') {
+      const meta = new _Metadata_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]();
+      Object.assign(meta, value);
+      this._meta = meta;
     }
   }
 
@@ -26790,10 +26903,8 @@ class Element {
 
   /** Unique identifier for this element. */
   get id() {
-    if (this.isFrozen) {
-      return this.getMetaProperty('id', '');
-    }
     if (!this.hasMetaProperty('id')) {
+      if (this.isFrozen) return '';
       this.setMetaProperty('id', '');
     }
     return this.meta.get('id');
@@ -26804,10 +26915,8 @@ class Element {
 
   /** CSS-like class names. */
   get classes() {
-    if (this.isFrozen) {
-      return this.getMetaProperty('classes', []);
-    }
     if (!this.hasMetaProperty('classes')) {
+      if (this.isFrozen) return [];
       this.setMetaProperty('classes', []);
     }
     return this.meta.get('classes');
@@ -26818,11 +26927,13 @@ class Element {
 
   /** Hyperlinks associated with this element. */
   get links() {
-    if (this.isFrozen) {
-      return this.getMetaProperty('links', []);
-    }
     if (!this.hasMetaProperty('links')) {
-      this.setMetaProperty('links', []);
+      if (this.isFrozen) {
+        const empty = new this.ArrayElement();
+        empty.freeze();
+        return empty;
+      }
+      this.setMetaProperty('links', new this.ArrayElement());
     }
     return this.meta.get('links');
   }
@@ -26842,7 +26953,7 @@ class Element {
     if (Array.isArray(content)) {
       return content;
     }
-    if (content instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]) {
+    if (content instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]) {
       const children = [];
       if (content.key) children.push(content.key);
       if (content.value) children.push(content.value);
@@ -26872,7 +26983,6 @@ class Element {
 
     // Freeze meta and attributes
     if (this._meta) {
-      this._meta.parent = this;
       this._meta.freeze();
     }
     if (this._attributes) {
@@ -26907,7 +27017,7 @@ class Element {
     if (_content instanceof Element) {
       return _content.toValue();
     }
-    if (_content instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_1__["default"]) {
+    if (_content instanceof _KeyValuePair_mjs__WEBPACK_IMPORTED_MODULE_2__["default"]) {
       return _content.toValue();
     }
     if (Array.isArray(_content)) {
@@ -26963,7 +27073,7 @@ class Element {
    * @throws Error if this element has no ID
    */
   toRef(path) {
-    const idValue = this.id.toValue();
+    const idValue = this.id;
     if (idValue === '') {
       throw new Error('Cannot create reference to an element without an ID');
     }
@@ -26975,26 +27085,16 @@ class Element {
   }
 
   /**
-   * Gets a meta property.
+   * Gets a meta property value.
    *
    * When the property doesn't exist:
-   * - With defaultValue: returns a new refracted element instance (not cached)
+   * - With defaultValue: returns the provided default value
    * - Without defaultValue: returns undefined
-   *
-   * Note: Each call with a default creates a new instance. Use setMetaProperty
-   * first if you need reference equality across multiple accesses.
    */
 
   getMetaProperty(name, defaultValue) {
     if (!this.hasMetaProperty(name)) {
-      if (defaultValue === undefined) {
-        return undefined;
-      }
-      const element = this.refract(defaultValue);
-      if (element && this.isFrozen) {
-        element.freeze();
-      }
-      return element;
+      return defaultValue;
     }
     return this.meta.get(name);
   }
@@ -27007,20 +27107,17 @@ class Element {
   }
 
   /**
-   * Has meta property.
+   * Checks whether a meta property exists.
    */
   hasMetaProperty(name) {
-    if (!this.isMetaEmpty) {
-      return this.meta.hasKey(name);
-    }
-    return false;
+    return this._meta !== undefined && this._meta.hasKey(name);
   }
 
   /**
    * Checks if meta is empty.
    */
   get isMetaEmpty() {
-    return this._meta === undefined || this.meta.isEmpty;
+    return this._meta === undefined || this._meta.isEmpty;
   }
 
   /**
@@ -27046,7 +27143,7 @@ class Element {
   }
 
   /**
-   * Has attributes property.
+   * Checks whether an attributes property exists.
    */
   hasAttributesProperty(name) {
     if (!this.isAttributesEmpty) {
@@ -27065,6 +27162,7 @@ class Element {
 
 // Re-export types for convenience
 
+
 /* harmony default export */ const __WEBPACK_DEFAULT_EXPORT__ = (Element);
 
 /***/ },
@@ -27506,7 +27604,13 @@ class JSONSerialiser {
       element: element.element
     };
     if (!element.isMetaEmpty) {
-      payload.meta = this.serialiseObject(element.meta);
+      const serialisedMeta = this.serialiseMeta(element);
+      if (serialisedMeta) {
+        payload.meta = serialisedMeta.meta;
+        if (serialisedMeta.rawKeys.length > 0) {
+          payload.__meta_raw__ = serialisedMeta.rawKeys;
+        }
+      }
     }
     if (!element.isAttributesEmpty) {
       payload.attributes = this.serialiseObject(element.attributes);
@@ -27553,7 +27657,7 @@ class JSONSerialiser {
       element.element = value.element;
     }
 
-    // Extract __mappings__ and __styles__ without mutating input, filter remaining meta
+    // Extract special meta keys without mutating input, filter remaining meta
     let mappingsDoc;
     let stylesDoc;
     let metaToDeserialize = value.meta;
@@ -27567,8 +27671,15 @@ class JSONSerialiser {
       stylesDoc = __styles__;
       metaToDeserialize = Object.keys(rest).length > 0 ? rest : undefined;
     }
+
+    // determine which meta keys were raw primitives before serialization
+    const rawKeys = value.__meta_raw__ ? new Set(value.__meta_raw__) : undefined;
     if (metaToDeserialize) {
-      this.deserialiseObject(metaToDeserialize, element.meta);
+      for (const [key, doc] of Object.entries(metaToDeserialize)) {
+        const deserialized = this.deserialise(doc);
+        // unwrap keys that were raw primitives before serialization
+        element.setMetaProperty(key, rawKeys?.has(key) ? deserialized.toValue() : deserialized);
+      }
     }
 
     // Restore source position from __mappings__
@@ -27631,6 +27742,27 @@ class JSONSerialiser {
     }
     return content;
   }
+  serialiseMeta(element) {
+    const meta = {};
+    const rawKeys = [];
+    let hasEntries = false;
+    for (const [key, value] of Object.entries(element.meta)) {
+      if (value instanceof this.namespace.elements.Element) {
+        meta[key] = this.serialise(value);
+        hasEntries = true;
+      } else if (value !== undefined) {
+        // refract primitives to maintain JSON Refract spec compatibility
+        const refracted = element.refract(value);
+        meta[key] = this.serialise(refracted);
+        rawKeys.push(key);
+        hasEntries = true;
+      }
+    }
+    return hasEntries ? {
+      meta,
+      rawKeys
+    } : undefined;
+  }
   serialiseObject(obj) {
     const result = {};
     obj.forEach((value, key) => {