@dialecte/core 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  import { FilterAttributes } from '../by-attribute/find-by-attributes.types';
2
2
  import { AnyDialecteConfig, DescendantsOf, ElementsOf, TrackedRecord } from '../../../../types';
3
- type Depth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20];
3
+ type Depth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8];
4
4
  type FilterNode<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>, D extends number> = Depth[D] extends never ? never : {
5
5
  [K in DescendantsOf<GenericConfig, GenericElement>]: {
6
6
  tagName: K;
@@ -24,7 +24,7 @@ export type DescendantsFilter<GenericConfig extends AnyDialecteConfig> = {
24
24
  * Default: false (required — candidates whose path lacks this element are excluded).
25
25
  */
26
26
  isOptional?: boolean;
27
- descendant?: FilterNode<GenericConfig, K, 20>;
27
+ descendant?: FilterNode<GenericConfig, K, 8>;
28
28
  };
29
29
  }[ElementsOf<GenericConfig>];
30
30
  export type FilterCondition<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>> = {
@@ -1 +1 @@
1
- {"version":3,"file":"find-descendant.types.d.ts","sourceRoot":"","sources":["../../../../../src/document/query/find/descendant/find-descendant.types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"find-descendant.types.d.ts","sourceRoot":"","sources":["../../../../../src/document/query/find/descendant/find-descendant.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6DAA6D,CAAA;AACnG,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAM1F,KAAK,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;AAE/C,KAAK,UAAU,CACd,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAChD,CAAC,SAAS,MAAM,IACb,KAAK,CAAC,CAAC,CAAC,SAAS,KAAK,GACvB,KAAK,GACL;KACC,CAAC,IAAI,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,GAAG;QACpD,OAAO,EAAE,CAAC,CAAA;QACV,uDAAuD;QACvD,UAAU,CAAC,EAAE,gBAAgB,CAAC,aAAa,EAAE,CAAC,CAAC,CAAA;QAC/C;;;WAGG;QACH,UAAU,CAAC,EAAE,OAAO,CAAA;QACpB,UAAU,CAAC,EAAE,UAAU,CAAC,aAAa,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;KACnD;CACD,CAAC,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,CAAA;AAEjD,MAAM,MAAM,iBAAiB,CAAC,aAAa,SAAS,iBAAiB,IAAI;KACvE,CAAC,IAAI,UAAU,CAAC,aAAa,CAAC,GAAG;QACjC,OAAO,EAAE,CAAC,CAAA;QACV,uDAAuD;QACvD,UAAU,CAAC,EAAE,gBAAgB,CAAC,aAAa,EAAE,CAAC,CAAC,CAAA;QAC/C;;;WAGG;QACH,UAAU,CAAC,EAAE,OAAO,CAAA;QACpB,UAAU,CAAC,EAAE,UAAU,CAAC,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;KAC5C;CACD,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAA;AAM5B,MAAM,MAAM,eAAe,CAC1B,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,IAC7C;IACH,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,CAAC,EAAE,gBAAgB,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA;IAC5D,QAAQ,EAAE,OAAO,CAAA;CACjB,CAAA;AAMD,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC,CAAA;CAAE,GACxD,CAAC,GAAG,CAAC,CAAC,SAAS;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GACjE,KAAK,CAAA;AAMR,MAAM,MAAM,SAAS,CAAC,aAAa,SAAS,iBAAiB,EAAE,WAAW,SAAS,MAAM,IAAI;KAC3F,CAAC,IAAI,WAAW,GAAG,aAAa,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE;CACrD,CAAA;AAED,MAAM,MAAM,qBAAqB,CAChC,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAChD,aAAa,SAAS,iBAAiB,CAAC,aAAa,CAAC,GAAG,SAAS,IAC/D,aAAa,SAAS,SAAS,GAChC;KACC,CAAC,IAAI,cAAc,GAAG,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,GAAG,aAAa,CAClF,aAAa,EACb,CAAC,CACD,EAAE;CACH,GACA,aAAa,SAAS,iBAAiB,CAAC,aAAa,CAAC,GACrD,SAAS,CAAC,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC,GACpD,KAAK,CAAA"}
@@ -27,29 +27,153 @@ export declare class Query<GenericConfig extends AnyDialecteConfig> {
27
27
  * the same FP functions for domain-specific queries.
28
28
  */
29
29
  protected get context(): Context<GenericConfig>;
30
+ /**
31
+ * Get the root element of the document.
32
+ *
33
+ * @returns The root record, or `undefined` if the database is empty.
34
+ *
35
+ * @example
36
+ * ```ts
37
+ * const root = await query.getRoot()
38
+ * ```
39
+ */
30
40
  getRoot(): Promise<TrackedRecord<GenericConfig, RootElementOf<GenericConfig>> | undefined>;
41
+ /**
42
+ * Get a single record by ref, record, or relationship.
43
+ *
44
+ * @param refOrRecord - A ref `{ tagName, id }`, or any record/relationship.
45
+ * @returns The tracked record, or `undefined` if not found.
46
+ *
47
+ * @example
48
+ * ```ts
49
+ * const ied = await query.getRecord({ tagName: 'IED', id: knownId })
50
+ * ```
51
+ */
31
52
  getRecord<GenericElement extends ElementsOf<GenericConfig>>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined): Promise<TrackedRecord<GenericConfig, GenericElement> | undefined>;
53
+ /**
54
+ * Get multiple records in a single call.
55
+ *
56
+ * @param refsOrRecords - Array of refs, records, or relationships.
57
+ * @returns Array of tracked records (same order, `undefined` for missing).
58
+ *
59
+ * @example
60
+ * ```ts
61
+ * const [bay1, bay2] = await query.getRecords([ref1, ref2])
62
+ * ```
63
+ */
32
64
  getRecords<GenericElement extends ElementsOf<GenericConfig>>(refsOrRecords: (RefOrRecord<GenericConfig, GenericElement> | undefined)[]): Promise<(TrackedRecord<GenericConfig, GenericElement> | undefined)[]>;
65
+ /**
66
+ * Get all records of a given tag name.
67
+ *
68
+ * @param tagName - The element type to retrieve.
69
+ * @returns All tracked records matching that tag name.
70
+ *
71
+ * @example
72
+ * ```ts
73
+ * const ieds = await query.getRecordsByTagName('IED')
74
+ * ```
75
+ */
33
76
  getRecordsByTagName<GenericElement extends ElementsOf<GenericConfig>>(tagName: GenericElement): Promise<TrackedRecord<GenericConfig, GenericElement>[]>;
77
+ /**
78
+ * Find all descendants of an element, grouped by tag name.
79
+ *
80
+ * @param refOrRecord - The ancestor element.
81
+ * @param filter - Optional filter to restrict which tag names are returned.
82
+ * @returns Object keyed by tag name, each value an array of tracked records.
83
+ *
84
+ * @example
85
+ * ```ts
86
+ * const { Bay, VoltageLevel } = await query.findDescendants(substation)
87
+ * ```
88
+ */
34
89
  findDescendants<GenericElement extends ElementsOf<GenericConfig>, GenericFilter extends DescendantsFilter<GenericConfig> | undefined = undefined>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, filter?: GenericFilter): Promise<FindDescendantsReturn<GenericConfig, GenericElement, GenericFilter>>;
90
+ /**
91
+ * Build a full tree structure from an element down.
92
+ *
93
+ * @param refOrRecord - The root of the subtree.
94
+ * @param options - Optional depth/filter controls.
95
+ * @returns A tree record with nested children, or `undefined` if not found.
96
+ *
97
+ * @example
98
+ * ```ts
99
+ * const tree = await query.getTree(bay)
100
+ * ```
101
+ */
35
102
  getTree<GenericElement extends ElementsOf<GenericConfig>>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, options?: GetTreeParams<GenericConfig, GenericElement>): Promise<TreeRecord<GenericConfig, GenericElement> | undefined>;
36
103
  /**
104
+ * Get a single attribute value from a record.
105
+ *
106
+ * @param refOrRecord - The element to read from.
107
+ * @param params - Attribute name.
108
+ * @returns The attribute value, or `''` if absent.
109
+ *
110
+ * @example
111
+ * ```ts
112
+ * const name = await query.getAttribute(bay, { name: 'name' })
113
+ * ```
114
+ */
115
+ getAttribute<GenericElement extends ElementsOf<GenericConfig>>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, params: {
116
+ name: AttributesOf<GenericConfig, GenericElement>;
117
+ fullObject?: false;
118
+ }): Promise<FullAttributeObjectOf<GenericConfig, GenericElement>['value'] | ''>;
119
+ /**
120
+ * Get the full attribute object for a single attribute.
121
+ *
122
+ * @param refOrRecord - The element to read from.
123
+ * @param params - Attribute name and `fullObject: true`.
124
+ * @returns The full attribute object, or `undefined` if absent.
125
+ *
37
126
  * @example
38
- * await doc.query.getAttribute({ ref, name: 'name' }) // → string | ''
39
- * await doc.query.getAttribute({ ref, name: 'name', fullObject: true }) // → FullAttributeObject | undefined
127
+ * ```ts
128
+ * const fullAttributeObject = await query.getAttribute(bay, { name: 'name', fullObject: true })
129
+ * ```
40
130
  */
41
- getAttribute<GenericElement extends ElementsOf<GenericConfig>, GenericAttribute extends FullAttributeObjectOf<GenericConfig, GenericElement>, FullObject extends boolean = false>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, params: {
131
+ getAttribute<GenericElement extends ElementsOf<GenericConfig>>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, params: {
42
132
  name: AttributesOf<GenericConfig, GenericElement>;
43
- fullObject?: FullObject;
44
- }): Promise<GenericAttribute | undefined | GenericAttribute['value'] | ''>;
133
+ fullObject: true;
134
+ }): Promise<FullAttributeObjectOf<GenericConfig, GenericElement> | undefined>;
135
+ /**
136
+ * Get all attributes of a record as a destructurable key/value object.
137
+ *
138
+ * @param refOrRecord - The element to read from.
139
+ * @returns A `{ name, desc, ... }` object with attribute names as keys.
140
+ *
141
+ * @example
142
+ * ```ts
143
+ * const { name, desc } = await query.getAttributes(bay)
144
+ * ```
145
+ */
146
+ getAttributes<GenericElement extends ElementsOf<GenericConfig>>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, params?: {
147
+ fullObject?: false;
148
+ }): Promise<AttributesValueObjectOf<GenericConfig, GenericElement>>;
149
+ /**
150
+ * Get all attributes of a record as an array of full attribute objects.
151
+ *
152
+ * @param refOrRecord - The element to read from.
153
+ * @returns An array of full attribute objects.
154
+ *
155
+ * @example
156
+ * ```ts
157
+ * const fullAttributeObjects = await query.getAttributes(bay, { fullObject: true })
158
+ * ```
159
+ */
160
+ getAttributes<GenericElement extends ElementsOf<GenericConfig>>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, params: {
161
+ fullObject: true;
162
+ }): Promise<FullAttributeObjectOf<GenericConfig, GenericElement>[]>;
45
163
  /**
164
+ * Find records matching specific attribute values.
165
+ *
166
+ * @param params - Tag name and attribute filter criteria.
167
+ * @returns All matching tracked records.
168
+ *
46
169
  * @example
47
- * const { name, desc } = await doc.query.getAttributes({ ref }) // destructurable
48
- * const fullAttrs = await doc.query.getAttributes({ ref, fullObject: true }) // FullAttributeObject[]
170
+ * ```ts
171
+ * const bays = await query.findByAttributes({
172
+ * tagName: 'Bay',
173
+ * attributes: { name: 'Q01' },
174
+ * })
175
+ * ```
49
176
  */
50
- getAttributes<GenericElement extends ElementsOf<GenericConfig>, GenericAttribute extends FullAttributeObjectOf<GenericConfig, GenericElement>, FullObject extends boolean = false>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, params?: {
51
- fullObject?: FullObject;
52
- }): Promise<GenericAttribute[] | AttributesValueObjectOf<GenericConfig, GenericElement>>;
53
177
  findByAttributes<GenericElement extends ElementsOf<GenericConfig>>(params: {
54
178
  tagName: GenericElement;
55
179
  attributes: FilterAttributes<GenericConfig, GenericElement>;
@@ -1 +1 @@
1
- {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/document/query/main.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/document/query/main.ts"],"names":[],"mappings":"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"}
@@ -34,9 +34,62 @@ export declare class Transaction<GenericConfig extends AnyDialecteConfig> extend
34
34
  * and a mutable stagedOperations array (mutation FP functions push to it).
35
35
  */
36
36
  protected get context(): Context<GenericConfig>;
37
+ /**
38
+ * Add a child element to a parent.
39
+ *
40
+ * @param parentRefOrRecord - The parent element (ref, record, or relationship). `undefined` for root.
41
+ * @param params - Child tagName, attributes and optional namespace, value, id.
42
+ * @returns Ref to the created child.
43
+ *
44
+ * @example
45
+ * ```ts
46
+ * const bayRef = await tx.addChild(substation, {
47
+ * tagName: 'VoltageLevel',
48
+ * attributes: { name: 'VL1' },
49
+ * })
50
+ * ```
51
+ */
37
52
  addChild<GenericElement extends ElementsOf<GenericConfig>, GenericChildElement extends ChildrenOf<GenericConfig, GenericElement>>(parentRefOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, params: AddChildParams<GenericConfig, GenericElement, GenericChildElement>): Promise<Ref<GenericConfig, GenericChildElement>>;
53
+ /**
54
+ * Update attributes of an existing element.
55
+ *
56
+ * @param refOrRecord - The element to update (ref, record, or relationship).
57
+ * @param params - New attribute values.
58
+ * @returns Ref to the updated element.
59
+ *
60
+ * @example
61
+ * ```ts
62
+ * await tx.update(bay, {
63
+ * attributes: { name: 'Q02', desc: 'Feeder bay' },
64
+ * })
65
+ * ```
66
+ */
38
67
  update<GenericElement extends ElementsOf<GenericConfig>>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, params: UpdateParams<GenericConfig, GenericElement>): Promise<Ref<GenericConfig, GenericElement>>;
68
+ /**
69
+ * Delete an element and its entire subtree.
70
+ *
71
+ * @param refOrRecord - The element to delete (ref, record, or relationship).
72
+ * @returns Ref to the deleted element's parent.
73
+ *
74
+ * @example
75
+ * ```ts
76
+ * const parentRef = await tx.delete(bay)
77
+ * ```
78
+ */
39
79
  delete<GenericElement extends ElementsOf<GenericConfig>>(refOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined): Promise<Ref<GenericConfig, ParentsOf<GenericConfig, GenericElement>>>;
80
+ /**
81
+ * Deep-clone a subtree under a new parent.
82
+ *
83
+ * @param parentRefOrRecord - The target parent for the clone.
84
+ * @param record - The tree record to clone (from `getTree`).
85
+ * @returns The cloned root ref and an ID mapping from old to new.
86
+ *
87
+ * @example
88
+ * ```ts
89
+ * const tree = await tx.getTree(bay)
90
+ * const { ref, idMap } = await tx.deepClone(substation, tree)
91
+ * ```
92
+ */
40
93
  deepClone<GenericElement extends ElementsOf<GenericConfig>, GenericChildElement extends ChildrenOf<GenericConfig, GenericElement>>(parentRefOrRecord: RefOrRecord<GenericConfig, GenericElement> | undefined, record: TreeRecord<GenericConfig, GenericChildElement>): Promise<CloneResult<GenericConfig, GenericChildElement>>;
41
94
  /** Returns a read-only view of staged operations (for prepare/preview) */
42
95
  getStagedOperations(): ReadonlyArray<Operation<GenericConfig>>;
@@ -1 +1 @@
1
- {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/document/transaction/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAShC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,KAAK,EACX,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,GAAG,EACH,WAAW,EACX,UAAU,EACV,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW,CAAC,aAAa,SAAS,iBAAiB,CAAE,SAAQ,KAAK,CAAC,aAAa,CAAC;IAC7F,SAAS,CAAC,gBAAgB,EAAE,SAAS,CAAC,aAAa,CAAC,EAAE,CAAK;IAC3D,SAAS,CAAC,aAAa,EAAE,aAAa,CAAA;IACtC,SAAS,CAAC,WAAW,4BAAkC;gBAE3C,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa;IAOrF;;OAEG;cACgB,aAAa,IAAI,SAAS,CAAC,aAAa,CAAC,EAAE;IAI9D;;;;OAIG;IACH,cAAuB,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC,CAMvD;IAIK,QAAQ,CACb,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAChD,mBAAmB,SAAS,UAAU,CAAC,aAAa,EAAE,cAAc,CAAC,EAErE,iBAAiB,EAAE,WAAW,CAAC,aAAa,EAAE,cAAc,CAAC,GAAG,SAAS,EACzE,MAAM,EAAE,cAAc,CAAC,aAAa,EAAE,cAAc,EAAE,mBAAmB,CAAC,GACxE,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC;IAS7C,MAAM,CAAC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAC5D,WAAW,EAAE,WAAW,CAAC,aAAa,EAAE,cAAc,CAAC,GAAG,SAAS,EACnE,MAAM,EAAE,YAAY,CAAC,aAAa,EAAE,cAAc,CAAC,GACjD,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IASxC,MAAM,CAAC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAC5D,WAAW,EAAE,WAAW,CAAC,aAAa,EAAE,cAAc,CAAC,GAAG,SAAS,GACjE,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,CAAC;IAIlE,SAAS,CACd,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAChD,mBAAmB,SAAS,UAAU,CAAC,aAAa,EAAE,cAAc,CAAC,EAErE,iBAAiB,EAAE,WAAW,CAAC,aAAa,EAAE,cAAc,CAAC,GAAG,SAAS,EACzE,MAAM,EAAE,UAAU,CAAC,aAAa,EAAE,mBAAmB,CAAC,GACpD,OAAO,CAAC,WAAW,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC;IAW3D,0EAA0E;IAC1E,mBAAmB,IAAI,aAAa,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IAI9D,yCAAyC;IACzC,qBAAqB,IAAI,IAAI;IAI7B,sCAAsC;IACtC,gBAAgB,IAAI,IAAI;IAIxB;;;;;;OAMG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}
1
+ {"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/document/transaction/main.ts"],"names":[],"mappings":"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"}
@@ -358,22 +358,77 @@ class fa {
358
358
  };
359
359
  }
360
360
  //== Record lookup
361
+ /**
362
+ * Get the root element of the document.
363
+ *
364
+ * @returns The root record, or `undefined` if the database is empty.
365
+ *
366
+ * @example
367
+ * ```ts
368
+ * const root = await query.getRoot()
369
+ * ```
370
+ */
361
371
  async getRoot() {
362
372
  return Re({
363
373
  context: this.context,
364
374
  ref: { tagName: this.dialecteConfig.rootElementName }
365
375
  });
366
376
  }
377
+ /**
378
+ * Get a single record by ref, record, or relationship.
379
+ *
380
+ * @param refOrRecord - A ref `{ tagName, id }`, or any record/relationship.
381
+ * @returns The tracked record, or `undefined` if not found.
382
+ *
383
+ * @example
384
+ * ```ts
385
+ * const ied = await query.getRecord({ tagName: 'IED', id: knownId })
386
+ * ```
387
+ */
367
388
  async getRecord(u) {
368
389
  return Re({ context: this.context, ref: Ne(u) });
369
390
  }
391
+ /**
392
+ * Get multiple records in a single call.
393
+ *
394
+ * @param refsOrRecords - Array of refs, records, or relationships.
395
+ * @returns Array of tracked records (same order, `undefined` for missing).
396
+ *
397
+ * @example
398
+ * ```ts
399
+ * const [bay1, bay2] = await query.getRecords([ref1, ref2])
400
+ * ```
401
+ */
370
402
  async getRecords(u) {
371
403
  const c = u.map((i) => Ne(i));
372
404
  return li({ context: this.context, refs: c });
373
405
  }
406
+ /**
407
+ * Get all records of a given tag name.
408
+ *
409
+ * @param tagName - The element type to retrieve.
410
+ * @returns All tracked records matching that tag name.
411
+ *
412
+ * @example
413
+ * ```ts
414
+ * const ieds = await query.getRecordsByTagName('IED')
415
+ * ```
416
+ */
374
417
  async getRecordsByTagName(u) {
375
418
  return ua({ context: this.context, tagName: u });
376
419
  }
420
+ /**
421
+ * Find all descendants of an element, grouped by tag name.
422
+ *
423
+ * @param refOrRecord - The ancestor element.
424
+ * @param filter - Optional filter to restrict which tag names are returned.
425
+ * @returns Object keyed by tag name, each value an array of tracked records.
426
+ *
427
+ * @example
428
+ * ```ts
429
+ * const { Bay, VoltageLevel } = await query.findDescendants(substation)
430
+ * ```
431
+ */
377
432
  async findDescendants(u, c) {
378
433
  return Qa({
379
434
  context: this.context,
@@ -382,29 +437,44 @@ class fa {
382
437
  filter: c
383
438
  });
384
439
  }
385
- async getTree(u, c) {
386
- return ca({ context: this.context, ref: Ne(u), options: c });
387
- }
388
- //== Attribute queries
389
440
  /**
441
+ * Build a full tree structure from an element down.
442
+ *
443
+ * @param refOrRecord - The root of the subtree.
444
+ * @param options - Optional depth/filter controls.
445
+ * @returns A tree record with nested children, or `undefined` if not found.
446
+ *
390
447
  * @example
391
- * await doc.query.getAttribute({ ref, name: 'name' }) // → string | ''
392
- * await doc.query.getAttribute({ ref, name: 'name', fullObject: true }) // → FullAttributeObject | undefined
448
+ * ```ts
449
+ * const tree = await query.getTree(bay)
450
+ * ```
393
451
  */
452
+ async getTree(u, c) {
453
+ return ca({ context: this.context, ref: Ne(u), options: c });
454
+ }
394
455
  async getAttribute(u, c) {
395
456
  const i = Ne(u), { fullObject: h } = c;
396
457
  return h ? ii({ context: this.context, ref: i, ...c }) : ai({ context: this.context, ref: i, ...c });
397
458
  }
398
- /**
399
- * @example
400
- * const { name, desc } = await doc.query.getAttributes({ ref }) // destructurable
401
- * const fullAttrs = await doc.query.getAttributes({ ref, fullObject: true }) // FullAttributeObject[]
402
- */
403
459
  async getAttributes(u, c) {
404
460
  const i = Ne(u), { fullObject: h } = c || {};
405
461
  return h ? si({ context: this.context, ref: i, ...c }) : oi({ context: this.context, ref: i, ...c });
406
462
  }
407
463
  //== Find queries
464
+ /**
465
+ * Find records matching specific attribute values.
466
+ *
467
+ * @param params - Tag name and attribute filter criteria.
468
+ * @returns All matching tracked records.
469
+ *
470
+ * @example
471
+ * ```ts
472
+ * const bays = await query.findByAttributes({
473
+ * tagName: 'Bay',
474
+ * attributes: { name: 'Q01' },
475
+ * })
476
+ * ```
477
+ */
408
478
  async findByAttributes(u) {
409
479
  return dr({ context: this.context, ...u });
410
480
  }
@@ -664,6 +734,21 @@ class Ti extends fa {
664
734
  };
665
735
  }
666
736
  //== Mutation methods
737
+ /**
738
+ * Add a child element to a parent.
739
+ *
740
+ * @param parentRefOrRecord - The parent element (ref, record, or relationship). `undefined` for root.
741
+ * @param params - Child tagName, attributes and optional namespace, value, id.
742
+ * @returns Ref to the created child.
743
+ *
744
+ * @example
745
+ * ```ts
746
+ * const bayRef = await tx.addChild(substation, {
747
+ * tagName: 'VoltageLevel',
748
+ * attributes: { name: 'VL1' },
749
+ * })
750
+ * ```
751
+ */
667
752
  async addChild(u, c) {
668
753
  return da({
669
754
  context: this.context,
@@ -672,6 +757,20 @@ class Ti extends fa {
672
757
  dialecteConfig: this.dialecteConfig
673
758
  });
674
759
  }
760
+ /**
761
+ * Update attributes of an existing element.
762
+ *
763
+ * @param refOrRecord - The element to update (ref, record, or relationship).
764
+ * @param params - New attribute values.
765
+ * @returns Ref to the updated element.
766
+ *
767
+ * @example
768
+ * ```ts
769
+ * await tx.update(bay, {
770
+ * attributes: { name: 'Q02', desc: 'Feeder bay' },
771
+ * })
772
+ * ```
773
+ */
675
774
  async update(u, c) {
676
775
  return _i({
677
776
  context: this.context,
@@ -680,9 +779,33 @@ class Ti extends fa {
680
779
  dialecteConfig: this.dialecteConfig
681
780
  });
682
781
  }
782
+ /**
783
+ * Delete an element and its entire subtree.
784
+ *
785
+ * @param refOrRecord - The element to delete (ref, record, or relationship).
786
+ * @returns Ref to the deleted element's parent.
787
+ *
788
+ * @example
789
+ * ```ts
790
+ * const parentRef = await tx.delete(bay)
791
+ * ```
792
+ */
683
793
  async delete(u) {
684
794
  return wi({ context: this.context, ref: Ne(u) });
685
795
  }
796
+ /**
797
+ * Deep-clone a subtree under a new parent.
798
+ *
799
+ * @param parentRefOrRecord - The target parent for the clone.
800
+ * @param record - The tree record to clone (from `getTree`).
801
+ * @returns The cloned root ref and an ID mapping from old to new.
802
+ *
803
+ * @example
804
+ * ```ts
805
+ * const tree = await tx.getTree(bay)
806
+ * const { ref, idMap } = await tx.deepClone(substation, tree)
807
+ * ```
808
+ */
686
809
  async deepClone(u, c) {
687
810
  return yi({
688
811
  dialecteConfig: this.dialecteConfig,
package/dist/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { D as s, a, Q as r, T as o, b as i, c as l, d as c, f as u, h as d, j as b, e as m, k as n, l as A, m as D, n as R, p as g, q as p, r as T, s as f, t as E, u as x, v as F, w as k, i as _, y, z as B, A as I, o as O } from "./index-B8aWgmfS.js";
1
+ import { D as s, a, Q as r, T as o, b as i, c as l, d as c, f as u, h as d, j as b, e as m, k as n, l as A, m as D, n as R, p as g, q as p, r as T, s as f, t as E, u as x, v as F, w as k, i as _, y, z as B, A as I, o as O } from "./index-CCEg5JAo.js";
2
2
  import { E as j, t as N } from "./index-B67NZSGJ.js";
3
3
  export {
4
4
  s as DexieStore,
package/dist/test.js CHANGED
@@ -1,4 +1,4 @@
1
- import { g as uu, x as fu, D as hu, i as du, o as pu, e as mu } from "./index-B8aWgmfS.js";
1
+ import { g as uu, x as fu, D as hu, i as du, o as pu, e as mu } from "./index-CCEg5JAo.js";
2
2
  import { DIALECTE_DEV_NAMESPACE as gu, standardizeRecord as yu, toTreeRecord as bu, toTrackedRecord as wu } from "./helpers.js";
3
3
  function Ha(e) {
4
4
  const t = _u(e);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dialecte/core",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Dialecte - Core functionality for Dialecte SDK",
5
5
  "license": "MIT",
6
6
  "repository": {