@speclynx/apidom-datamodel 4.0.2 → 4.0.3

package/src/elements/SourceMap.mjs

@@ -0,0 +1,134 @@
+import StringElement from "../primitives/StringElement.mjs";
+/**
+ * Shape with optional source position properties.
+ * @public
+ */
+/**
+ * SourceMapElement stores source position as a compact VLQ-encoded string.
+ *
+ * The encoded string contains 6 values: startLine, startCharacter, startOffset,
+ * endLine, endCharacter, endOffset. All values use UTF-16 code units,
+ * compatible with LSP, TextDocument, and JavaScript string indexing.
+ *
+ * web-tree-sitter automatically provides position data in UTF-16 code units.
+ *
+ * @public
+ */
+class SourceMapElement extends StringElement {
+  constructor(content, meta, attributes) {
+    super(content, meta, attributes);
+    this.element = 'sourceMap';
+  }
+
+  /**
+   * Transfers source position properties from one object to another.
+   */
+  static transfer(from, to) {
+    to.startLine = from.startLine;
+    to.startCharacter = from.startCharacter;
+    to.startOffset = from.startOffset;
+    to.endLine = from.endLine;
+    to.endCharacter = from.endCharacter;
+    to.endOffset = from.endOffset;
+  }
+
+  /**
+   * Creates a SourceMapElement from source position properties.
+   * Returns undefined if any position property is not a number.
+   * Also assigns position properties to the instance for inspection.
+   */
+  static from(source) {
+    const {
+      startLine,
+      startCharacter,
+      startOffset,
+      endLine,
+      endCharacter,
+      endOffset
+    } = source;
+    if (typeof startLine !== 'number' || typeof startCharacter !== 'number' || typeof startOffset !== 'number' || typeof endLine !== 'number' || typeof endCharacter !== 'number' || typeof endOffset !== 'number') {
+      return undefined;
+    }
+    const packed = packSourceMap([startLine, startCharacter, startOffset, endLine, endCharacter, endOffset]);
+    const sourceMap = new SourceMapElement(packed);
+    sourceMap.startLine = startLine;
+    sourceMap.startCharacter = startCharacter;
+    sourceMap.startOffset = startOffset;
+    sourceMap.endLine = endLine;
+    sourceMap.endCharacter = endCharacter;
+    sourceMap.endOffset = endOffset;
+    return sourceMap;
+  }
+
+  /**
+   * Decodes the VLQ string and applies source position properties to the target.
+   */
+  applyTo(target) {
+    if (!this.content) return;
+    [target.startLine, target.startCharacter, target.startOffset, target.endLine, target.endCharacter, target.endOffset] = unpackSourceMap(this.content);
+  }
+}
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+// Encode one unsigned integer to Base64-VLQ
+function vlqEncodeInt(value) {
+  let vlq = value >>> 0; // ensure unsigned 32-bit
+  let out = '';
+  do {
+    let digit = vlq & 31; // 5 bits
+    vlq >>>= 5;
+    if (vlq !== 0) digit |= 32; // continuation bit
+    out += BASE64[digit];
+  } while (vlq !== 0);
+  return out;
+}
+
+// Decode one unsigned integer from Base64-VLQ, starting at `index`
+function vlqDecodeInt(str, index = 0) {
+  let result = 0;
+  let shift = 0;
+  let i = index;
+  while (true) {
+    const ch = str[i++];
+    const digit = BASE64.indexOf(ch);
+    if (digit === -1) throw new Error(`Invalid Base64 VLQ char: ${ch}`);
+    const cont = (digit & 32) !== 0;
+    result |= (digit & 31) << shift;
+    shift += 5;
+    if (!cont) break;
+  }
+  return {
+    value: result >>> 0,
+    next: i
+  };
+}
+
+/**
+ * Span of 6 position values: [startLine, startCharacter, startOffset, endLine, endCharacter, endOffset]
+ * @public
+ */
+
+/**
+ * Encodes 6 position values into a compact VLQ string.
+ * @public
+ */
+function packSourceMap(v) {
+  return 'sm1:' + v.map(vlqEncodeInt).join('');
+}
+
+/**
+ * Decodes a VLQ string into 6 position values.
+ * @public
+ */
+function unpackSourceMap(packed) {
+  const s = packed.startsWith('sm1:') ? packed.slice(4) : packed;
+  const out = [];
+  let i = 0;
+  for (let k = 0; k < 6; k++) {
+    const r = vlqDecodeInt(s, i);
+    out.push(r.value);
+    i = r.next;
+  }
+  return out;
+}
+export default SourceMapElement;

package/src/elements/SourceMap.ts

@@ -0,0 +1,170 @@
+import StringElement from '../primitives/StringElement.ts';
+import type { Meta, Attributes } from '../types.ts';
+
+/**
+ * Shape with optional source position properties.
+ * @public
+ */
+interface SourceMapShape {
+  startLine?: number;
+  startCharacter?: number;
+  startOffset?: number;
+  endLine?: number;
+  endCharacter?: number;
+  endOffset?: number;
+}
+
+/**
+ * SourceMapElement stores source position as a compact VLQ-encoded string.
+ *
+ * The encoded string contains 6 values: startLine, startCharacter, startOffset,
+ * endLine, endCharacter, endOffset. All values use UTF-16 code units,
+ * compatible with LSP, TextDocument, and JavaScript string indexing.
+ *
+ * web-tree-sitter automatically provides position data in UTF-16 code units.
+ *
+ * @public
+ */
+class SourceMapElement extends StringElement {
+  constructor(content?: string, meta?: Meta, attributes?: Attributes) {
+    super(content, meta, attributes);
+    this.element = 'sourceMap';
+  }
+
+  /**
+   * Transfers source position properties from one object to another.
+   */
+  static transfer(from: SourceMapShape, to: SourceMapShape): void {
+    to.startLine = from.startLine;
+    to.startCharacter = from.startCharacter;
+    to.startOffset = from.startOffset;
+    to.endLine = from.endLine;
+    to.endCharacter = from.endCharacter;
+    to.endOffset = from.endOffset;
+  }
+
+  /**
+   * Creates a SourceMapElement from source position properties.
+   * Returns undefined if any position property is not a number.
+   * Also assigns position properties to the instance for inspection.
+   */
+  static from(source: SourceMapShape): SourceMapElement | undefined {
+    const { startLine, startCharacter, startOffset, endLine, endCharacter, endOffset } = source;
+
+    if (
+      typeof startLine !== 'number' ||
+      typeof startCharacter !== 'number' ||
+      typeof startOffset !== 'number' ||
+      typeof endLine !== 'number' ||
+      typeof endCharacter !== 'number' ||
+      typeof endOffset !== 'number'
+    ) {
+      return undefined;
+    }
+
+    const packed = packSourceMap([
+      startLine,
+      startCharacter,
+      startOffset,
+      endLine,
+      endCharacter,
+      endOffset,
+    ]);
+
+    const sourceMap = new SourceMapElement(packed);
+    sourceMap.startLine = startLine;
+    sourceMap.startCharacter = startCharacter;
+    sourceMap.startOffset = startOffset;
+    sourceMap.endLine = endLine;
+    sourceMap.endCharacter = endCharacter;
+    sourceMap.endOffset = endOffset;
+
+    return sourceMap;
+  }
+
+  /**
+   * Decodes the VLQ string and applies source position properties to the target.
+   */
+  public applyTo(target: SourceMapShape): void {
+    if (!this.content) return;
+    [
+      target.startLine,
+      target.startCharacter,
+      target.startOffset,
+      target.endLine,
+      target.endCharacter,
+      target.endOffset,
+    ] = unpackSourceMap(this.content as string);
+  }
+}
+
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+// Encode one unsigned integer to Base64-VLQ
+function vlqEncodeInt(value: number): string {
+  let vlq = value >>> 0; // ensure unsigned 32-bit
+  let out = '';
+
+  do {
+    let digit = vlq & 31; // 5 bits
+    vlq >>>= 5;
+    if (vlq !== 0) digit |= 32; // continuation bit
+    out += BASE64[digit];
+  } while (vlq !== 0);
+
+  return out;
+}
+
+// Decode one unsigned integer from Base64-VLQ, starting at `index`
+function vlqDecodeInt(str: string, index = 0): { value: number; next: number } {
+  let result = 0;
+  let shift = 0;
+  let i = index;
+
+  while (true) {
+    const ch = str[i++];
+    const digit = BASE64.indexOf(ch);
+    if (digit === -1) throw new Error(`Invalid Base64 VLQ char: ${ch}`);
+
+    const cont = (digit & 32) !== 0;
+    result |= (digit & 31) << shift;
+    shift += 5;
+
+    if (!cont) break;
+  }
+
+  return { value: result >>> 0, next: i };
+}
+
+/**
+ * Span of 6 position values: [startLine, startCharacter, startOffset, endLine, endCharacter, endOffset]
+ * @public
+ */
+type Span6 = [number, number, number, number, number, number];
+
+/**
+ * Encodes 6 position values into a compact VLQ string.
+ * @public
+ */
+function packSourceMap(v: Span6): string {
+  return 'sm1:' + v.map(vlqEncodeInt).join('');
+}
+
+/**
+ * Decodes a VLQ string into 6 position values.
+ * @public
+ */
+function unpackSourceMap(packed: string): Span6 {
+  const s = packed.startsWith('sm1:') ? packed.slice(4) : packed;
+  const out: number[] = [];
+  let i = 0;
+  for (let k = 0; k < 6; k++) {
+    const r = vlqDecodeInt(s, i);
+    out.push(r.value);
+    i = r.next;
+  }
+  return out as Span6;
+}
+
+export default SourceMapElement;
+export type { Span6, SourceMapShape };

package/src/elements/Style.cjs

@@ -0,0 +1,54 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ObjectElement = _interopRequireDefault(require("../primitives/ObjectElement.cjs"));
+/**
+ * Shape with optional style property.
+ * @public
+ */
+
+/**
+ * StyleElement stores format-specific style information for round-trip preservation.
+ *
+ * The style data is stored as a plain object with format-specific namespaces
+ * (e.g., `yaml`, `json`). This element exists only during serialization/deserialization
+ * (refract format) - in memory, style lives directly on `element.style`.
+ *
+ * Follows the same pattern as SourceMapElement with __mappings__.
+ *
+ * @public
+ */
+class StyleElement extends _ObjectElement.default {
+  constructor(content, meta, attributes) {
+    super(content, meta, attributes);
+    this.element = '__styles__';
+  }
+
+  /**
+   * Transfers style property from one element to another.
+   */
+  static transfer(from, to) {
+    to.style = from.style;
+  }
+
+  /**
+   * Creates a StyleElement from an element's style property.
+   * Returns undefined if the element has no style.
+   */
+  static from(source) {
+    if (!source.style) {
+      return undefined;
+    }
+    return new StyleElement(source.style);
+  }
+
+  /**
+   * Restores the style property on the target element from this StyleElement.
+   */
+  applyTo(target) {
+    target.style = this.toValue();
+  }
+}
+var _default = exports.default = StyleElement;

package/src/elements/Style.mjs

@@ -0,0 +1,48 @@
+import ObjectElement from "../primitives/ObjectElement.mjs";
+/**
+ * Shape with optional style property.
+ * @public
+ */
+/**
+ * StyleElement stores format-specific style information for round-trip preservation.
+ *
+ * The style data is stored as a plain object with format-specific namespaces
+ * (e.g., `yaml`, `json`). This element exists only during serialization/deserialization
+ * (refract format) - in memory, style lives directly on `element.style`.
+ *
+ * Follows the same pattern as SourceMapElement with __mappings__.
+ *
+ * @public
+ */
+class StyleElement extends ObjectElement {
+  constructor(content, meta, attributes) {
+    super(content, meta, attributes);
+    this.element = '__styles__';
+  }
+
+  /**
+   * Transfers style property from one element to another.
+   */
+  static transfer(from, to) {
+    to.style = from.style;
+  }
+
+  /**
+   * Creates a StyleElement from an element's style property.
+   * Returns undefined if the element has no style.
+   */
+  static from(source) {
+    if (!source.style) {
+      return undefined;
+    }
+    return new StyleElement(source.style);
+  }
+
+  /**
+   * Restores the style property on the target element from this StyleElement.
+   */
+  applyTo(target) {
+    target.style = this.toValue();
+  }
+}
+export default StyleElement;

package/src/elements/Style.ts

@@ -0,0 +1,56 @@
+import ObjectElement from '../primitives/ObjectElement.ts';
+import type { Meta, Attributes } from '../types.ts';
+
+/**
+ * Shape with optional style property.
+ * @public
+ */
+interface StyleShape {
+  style?: Record<string, unknown>;
+}
+
+/**
+ * StyleElement stores format-specific style information for round-trip preservation.
+ *
+ * The style data is stored as a plain object with format-specific namespaces
+ * (e.g., `yaml`, `json`). This element exists only during serialization/deserialization
+ * (refract format) - in memory, style lives directly on `element.style`.
+ *
+ * Follows the same pattern as SourceMapElement with __mappings__.
+ *
+ * @public
+ */
+class StyleElement extends ObjectElement {
+  constructor(content?: Record<string, unknown>, meta?: Meta, attributes?: Attributes) {
+    super(content, meta, attributes);
+    this.element = '__styles__';
+  }
+
+  /**
+   * Transfers style property from one element to another.
+   */
+  static transfer(from: StyleShape, to: StyleShape): void {
+    to.style = from.style;
+  }
+
+  /**
+   * Creates a StyleElement from an element's style property.
+   * Returns undefined if the element has no style.
+   */
+  static from(source: StyleShape): StyleElement | undefined {
+    if (!source.style) {
+      return undefined;
+    }
+    return new StyleElement(source.style);
+  }
+
+  /**
+   * Restores the style property on the target element from this StyleElement.
+   */
+  public applyTo(target: StyleShape): void {
+    target.style = this.toValue() as Record<string, unknown>;
+  }
+}
+
+export default StyleElement;
+export type { StyleShape };

package/src/index.cjs

@@ -0,0 +1,58 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.refract = exports.isStringElement = exports.isSourceMapElement = exports.isRefElement = exports.isPrimitiveElement = exports.isParseResultElement = exports.isObjectElement = exports.isNumberElement = exports.isNullElement = exports.isMemberElement = exports.isLinkElement = exports.isElement = exports.isCommentElement = exports.isBooleanElement = exports.isArrayElement = exports.isAnnotationElement = exports.includesSymbols = exports.includesClasses = exports.hasElementStyle = exports.hasElementSourceMap = exports.cloneShallow = exports.cloneDeep = exports.StyleElement = exports.StringElement = exports.SourceMapElement = exports.ShallowCloneError = exports.RefElement = exports.ParseResultElement = exports.ObjectSlice = exports.ObjectElement = exports.NumberElement = exports.NullElement = exports.Namespace = exports.Metadata = exports.MemberElement = exports.LinkElement = exports.KeyValuePair = exports.JSONSerialiser = exports.Element = exports.DeepCloneError = exports.CommentElement = exports.CollectionElement = exports.CloneError = exports.BooleanElement = exports.ArrayElement = exports.AnnotationElement = void 0;
+var _Namespace = _interopRequireDefault(require("./Namespace.cjs"));
+exports.Namespace = _Namespace.default;
+var _KeyValuePair = _interopRequireDefault(require("./KeyValuePair.cjs"));
+exports.KeyValuePair = _KeyValuePair.default;
+var _Metadata = _interopRequireDefault(require("./Metadata.cjs"));
+exports.Metadata = _Metadata.default;
+var _index = require("./clone/index.cjs");
+exports.cloneShallow = _index.cloneShallow;
+exports.cloneDeep = _index.cloneDeep;
+exports.CloneError = _index.CloneError;
+exports.DeepCloneError = _index.DeepCloneError;
+exports.ShallowCloneError = _index.ShallowCloneError;
+var _registration = require("./registration.cjs");
+exports.ObjectSlice = _registration.ObjectSlice;
+exports.Element = _registration.Element;
+exports.CollectionElement = _registration.CollectionElement;
+exports.StringElement = _registration.StringElement;
+exports.NumberElement = _registration.NumberElement;
+exports.BooleanElement = _registration.BooleanElement;
+exports.NullElement = _registration.NullElement;
+exports.ArrayElement = _registration.ArrayElement;
+exports.ObjectElement = _registration.ObjectElement;
+exports.MemberElement = _registration.MemberElement;
+exports.RefElement = _registration.RefElement;
+exports.LinkElement = _registration.LinkElement;
+exports.AnnotationElement = _registration.AnnotationElement;
+exports.CommentElement = _registration.CommentElement;
+exports.ParseResultElement = _registration.ParseResultElement;
+exports.SourceMapElement = _registration.SourceMapElement;
+exports.StyleElement = _registration.StyleElement;
+exports.refract = _registration.refract;
+var _JSONSerialiser = _interopRequireDefault(require("./serialisers/JSONSerialiser.cjs"));
+exports.JSONSerialiser = _JSONSerialiser.default;
+var _index2 = require("./predicates/index.cjs");
+exports.isElement = _index2.isElement;
+exports.isStringElement = _index2.isStringElement;
+exports.isNumberElement = _index2.isNumberElement;
+exports.isNullElement = _index2.isNullElement;
+exports.isBooleanElement = _index2.isBooleanElement;
+exports.isObjectElement = _index2.isObjectElement;
+exports.isArrayElement = _index2.isArrayElement;
+exports.isMemberElement = _index2.isMemberElement;
+exports.isLinkElement = _index2.isLinkElement;
+exports.isRefElement = _index2.isRefElement;
+exports.isAnnotationElement = _index2.isAnnotationElement;
+exports.isCommentElement = _index2.isCommentElement;
+exports.isParseResultElement = _index2.isParseResultElement;
+exports.isSourceMapElement = _index2.isSourceMapElement;
+exports.isPrimitiveElement = _index2.isPrimitiveElement;
+exports.hasElementStyle = _index2.hasElementStyle;
+exports.hasElementSourceMap = _index2.hasElementSourceMap;
+exports.includesSymbols = _index2.includesSymbols;
+exports.includesClasses = _index2.includesClasses;

package/src/index.mjs

@@ -0,0 +1,11 @@
+export { default as Namespace } from "./Namespace.mjs";
+export { default as KeyValuePair } from "./KeyValuePair.mjs";
+export { default as Metadata } from "./Metadata.mjs"; // Clone utilities
+export { cloneShallow, cloneDeep, CloneError, DeepCloneError, ShallowCloneError } from "./clone/index.mjs";
+// Re-export elements directly to preserve JSDoc
+export { ObjectSlice, Element, CollectionElement, StringElement, NumberElement, BooleanElement, NullElement, ArrayElement, ObjectElement, MemberElement, RefElement, LinkElement, AnnotationElement, CommentElement, ParseResultElement, SourceMapElement, StyleElement, refract } from "./registration.mjs";
+export { default as JSONSerialiser } from "./serialisers/JSONSerialiser.mjs"; // Re-export types - essential public API
+// Re-export types - for advanced users extending the library
+// Re-export types - used in public method signatures
+// Re-export predicates
+export { isElement, isStringElement, isNumberElement, isNullElement, isBooleanElement, isObjectElement, isArrayElement, isMemberElement, isLinkElement, isRefElement, isAnnotationElement, isCommentElement, isParseResultElement, isSourceMapElement, isPrimitiveElement, hasElementStyle, hasElementSourceMap, includesSymbols, includesClasses } from "./predicates/index.mjs";

package/src/index.ts

@@ -0,0 +1,79 @@
+export { default as Namespace } from './Namespace.ts';
+export { default as KeyValuePair } from './KeyValuePair.ts';
+export { default as Metadata } from './Metadata.ts';
+
+// Clone utilities
+export {
+  cloneShallow,
+  cloneDeep,
+  CloneError,
+  DeepCloneError,
+  ShallowCloneError,
+} from './clone/index.ts';
+export type { FinalCloneTypes, DeepCloneOptions, CloneErrorOptions } from './clone/index.ts';
+
+// Re-export elements directly to preserve JSDoc
+export {
+  ObjectSlice,
+  Element,
+  CollectionElement,
+  StringElement,
+  NumberElement,
+  BooleanElement,
+  NullElement,
+  ArrayElement,
+  ObjectElement,
+  MemberElement,
+  RefElement,
+  LinkElement,
+  AnnotationElement,
+  CommentElement,
+  ParseResultElement,
+  SourceMapElement,
+  StyleElement,
+  refract,
+} from './registration.ts';
+
+export { default as JSONSerialiser } from './serialisers/JSONSerialiser.ts';
+
+// Re-export types - essential public API
+export type { Meta, Attributes, ElementContent } from './primitives/Element.ts';
+export type { PrimitiveValue } from './types.ts';
+
+// Re-export types - for advanced users extending the library
+export type { ElementClass, NamespaceOptions, NamespacePlugin } from './Namespace.ts';
+export type { SerializedElement, RefractDocument } from './serialisers/JSONSerialiser.ts';
+
+// Re-export types - used in public method signatures
+export type { DetectionTest, DetectionEntry, ElementsMap } from './Namespace.ts';
+export type { ObjectSliceCallback, ObjectSliceForEachCallback } from './ObjectSlice.ts';
+export type { FindCondition, FindOptions } from './primitives/CollectionElement.ts';
+export type { ToValue, Equatable, Freezable } from './types.ts';
+export type { ObjectElementCallback } from './primitives/ObjectElement.ts';
+export type { SerializedContent, SerializedKeyValuePair } from './serialisers/JSONSerialiser.ts';
+export type { Span6, SourceMapShape } from './elements/SourceMap.ts';
+export type { StyleShape } from './elements/Style.ts';
+
+// Re-export predicates
+export {
+  isElement,
+  isStringElement,
+  isNumberElement,
+  isNullElement,
+  isBooleanElement,
+  isObjectElement,
+  isArrayElement,
+  isMemberElement,
+  isLinkElement,
+  isRefElement,
+  isAnnotationElement,
+  isCommentElement,
+  isParseResultElement,
+  isSourceMapElement,
+  isPrimitiveElement,
+  hasElementStyle,
+  hasElementSourceMap,
+  includesSymbols,
+  includesClasses,
+} from './predicates/index.ts';
+export type { PrimitiveElement } from './predicates/index.ts';

package/src/predicates/elements.cjs

@@ -0,0 +1,46 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.isSourceMapElement = exports.isRefElement = exports.isParseResultElement = exports.isLinkElement = exports.isCommentElement = exports.isAnnotationElement = void 0;
+var _LinkElement = _interopRequireDefault(require("../elements/LinkElement.cjs"));
+var _RefElement = _interopRequireDefault(require("../elements/RefElement.cjs"));
+var _Annotation = _interopRequireDefault(require("../elements/Annotation.cjs"));
+var _Comment = _interopRequireDefault(require("../elements/Comment.cjs"));
+var _ParseResult = _interopRequireDefault(require("../elements/ParseResult.cjs"));
+var _SourceMap = _interopRequireDefault(require("../elements/SourceMap.cjs"));
+/**
+ * @public
+ */
+const isLinkElement = element => element instanceof _LinkElement.default;
+
+/**
+ * @public
+ */
+exports.isLinkElement = isLinkElement;
+const isRefElement = element => element instanceof _RefElement.default;
+
+/**
+ * @public
+ */
+exports.isRefElement = isRefElement;
+const isAnnotationElement = element => element instanceof _Annotation.default;
+
+/**
+ * @public
+ */
+exports.isAnnotationElement = isAnnotationElement;
+const isCommentElement = element => element instanceof _Comment.default;
+
+/**
+ * @public
+ */
+exports.isCommentElement = isCommentElement;
+const isParseResultElement = element => element instanceof _ParseResult.default;
+
+/**
+ * @public
+ */
+exports.isParseResultElement = isParseResultElement;
+const isSourceMapElement = element => element instanceof _SourceMap.default;
+exports.isSourceMapElement = isSourceMapElement;