@dialecte/core 0.6.4 → 0.8.0

package/dist/errors/errors.d.ts

@@ -8,6 +8,8 @@ import { CoreCatalogueCollisions, DialecteError, DialecteErrorCatalogInput, Dial
  *
  * `key` is a key of the core catalogue, or an error a dialecte declared with `defineErrors`.
  *
+ * @intent throw a structured error, fail with a core or dialecte error key, raise an error a consumer can read by key
+ *
  * @example
  * throwDialecteError('ELEMENT_NOT_FOUND', { detail: 'parent not found' })
  */
@@ -15,12 +17,16 @@ export declare function throwDialecteError(key: DialecteErrorKey | DialecteError
 /**
  * Build the Error `throwDialecteError` throws, without throwing it — for a caller that reports an
  * error it caught instead of raising one.
+ *
+ * @intent report a caught error as a dialecte error without throwing, build the Error throwDialecteError would throw
  */
 export declare function createDialecteError(key: DialecteErrorKey | DialecteErrorDefinition, params: ThrowDialecteErrorParams): Error;
 /**
  * Declare the errors of a dialecte: each entry gets its property name as `key`, so it can be
  * passed wherever a core key is — `throwDialecteError`, `invariant`.
  *
+ * @intent declare a dialecte's own error catalogue, add error keys usable with invariant and throwDialecteError
+ *
  * @example
  * const ERRORS = defineErrors({ NAME_TAKEN: { code: 'X1001', message: 'The name is already taken' } })
  * invariant(isFree, { key: ERRORS.NAME_TAKEN, detail: '…', meta: { name } })
@@ -29,6 +35,8 @@ export declare function defineErrors<const GenericCatalog extends DialecteErrorC
 /**
  * The structured error a caught value carries — thrown by `throwDialecteError` or `invariant` —
  * or nothing when it is any other error or value.
+ *
+ * @intent read the structured error from a caught value, handle a dialecte error in a catch block
  */
 export declare function toDialecteError(thrown: unknown): DialecteError | undefined;
 /**
@@ -36,6 +44,8 @@ export declare function toDialecteError(thrown: unknown): DialecteError | undefi
  * one of the catalogues named — same key, same code. Its `key` is then narrowed to those keys, so a
  * `switch` on it or a table read with it is checked again.
  *
+ * @intent tell which error was thrown, narrow an error key for a switch, word an error for a user
+ *
  * @example
  * const error = toDialecteError(thrown)
  * if (error && isKnownDialecteError(error, { catalogues: [MY_ERRORS] })) sentences[error.key]

package/dist/errors/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors/errors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,uBAAuB,EACvB,aAAa,EACb,yBAAyB,EACzB,uBAAuB,EACvB,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,gBAAgB,GAAG,uBAAuB,EAC/C,MAAM,EAAE,wBAAwB,GAC9B,KAAK,CAEP;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,GAAG,EAAE,gBAAgB,GAAG,uBAAuB,EAC/C,MAAM,EAAE,wBAAwB,GAC9B,KAAK,CAeP;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,cAAc,SAAS,yBAAyB,EAClF,OAAO,EAAE,cAAc,GAAG,uBAAuB,CAAC,cAAc,CAAC,GAC/D,wBAAwB,CAAC,cAAc,CAAC,CA0B1C;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAO1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,KAAK,CAAC,iBAAiB,SAAS,SAAS,wBAAwB,CAAC,yBAAyB,CAAC,EAAE,EAE9F,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE;IAAE,UAAU,EAAE,iBAAiB,CAAA;CAAE,GACvC,KAAK,IAAI,aAAa,CAAC,qBAAqB,CAAC,iBAAiB,CAAC,CAAC,CAKlE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors/errors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,uBAAuB,EACvB,aAAa,EACb,yBAAyB,EACzB,uBAAuB,EACvB,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,gBAAgB,GAAG,uBAAuB,EAC/C,MAAM,EAAE,wBAAwB,GAC9B,KAAK,CAEP;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,GAAG,EAAE,gBAAgB,GAAG,uBAAuB,EAC/C,MAAM,EAAE,wBAAwB,GAC9B,KAAK,CAeP;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,cAAc,SAAS,yBAAyB,EAClF,OAAO,EAAE,cAAc,GAAG,uBAAuB,CAAC,cAAc,CAAC,GAC/D,wBAAwB,CAAC,cAAc,CAAC,CA0B1C;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAO1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CACnC,KAAK,CAAC,iBAAiB,SAAS,SAAS,wBAAwB,CAAC,yBAAyB,CAAC,EAAE,EAE9F,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE;IAAE,UAAU,EAAE,iBAAiB,CAAA;CAAE,GACvC,KAAK,IAAI,aAAa,CAAC,qBAAqB,CAAC,iBAAiB,CAAC,CAAC,CAKlE"}

package/dist/errors/types.d.ts

@@ -1,6 +1,18 @@
 import { ERROR_CATALOG } from './codes';
 export type DialecteErrorKey = keyof typeof ERROR_CATALOG;
 export type DialecteErrorCode = (typeof ERROR_CATALOG)[DialecteErrorKey]['code'];
+/**
+ * What a catalogue says of a code beyond its message, for a reader who met it and wants to act on
+ * it (`dialecte explain <code>`): when it is raised, the usual fix, and the docs page about it.
+ */
+export type CatalogueExplanation = {
+    /** When it is raised: the situation, in the reader's words. */
+    when: string;
+    /** The usual fix. */
+    fix: string;
+    /** The docs page about it, when one exists. */
+    docs?: string;
+};
 /**
  * An error a dialecte declares beside the core catalogue: its own key, its own code and the
  * default message shown when the consumer has no wording of its own for that key.
@@ -10,11 +22,13 @@ export type DialecteErrorDefinition<GenericKey extends string = string> = {
     key: GenericKey;
     code: string;
     message: string;
+    explanation?: CatalogueExplanation;
 };
 /** What a dialecte gives `defineErrors`: one entry per error, named by its key. */
 export type DialecteErrorCatalogInput = Record<string, {
     code: string;
     message: string;
+    explanation?: CatalogueExplanation;
 }>;
 /** What `defineErrors` returns: each entry of the catalogue with its property name as `key`. */
 export type DialecteErrorDefinitions<GenericCatalog extends DialecteErrorCatalogInput> = {

package/dist/errors/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/errors/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,aAAa,CAAA;AACzD,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEhF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,CAAC,UAAU,SAAS,MAAM,GAAG,MAAM,IAAI;IACzE,GAAG,EAAE,UAAU,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CACf,CAAA;AAED,mFAAmF;AACnF,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAEzF,gGAAgG;AAChG,MAAM,MAAM,wBAAwB,CAAC,cAAc,SAAS,yBAAyB,IAAI;IACxF,QAAQ,EAAE,UAAU,IAAI,MAAM,cAAc,GAAG,MAAM,GAAG,uBAAuB,CAAC,UAAU,CAAC,GAC1F,cAAc,CAAC,UAAU,CAAC;CAC3B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,uBAAuB,CAAC,cAAc,SAAS,yBAAyB,IAAI;KACtF,UAAU,IAAI,MAAM,cAAc,IAAI,UAAU,SAAS,gBAAgB,GACvE,UAAU,GACV,cAAc,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,SAAS,iBAAiB,GAC3D,UAAU,GACV,KAAK,GAAG,KAAK;CACjB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,UAAU,SAAS,MAAM,GAAG,gBAAgB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,IAAI;IACzF,iFAAiF;IACjF,IAAI,EAAE,iBAAiB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;IACvC;;;OAGG;IACH,GAAG,EAAE,UAAU,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;IACrC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,KAAK,CAAC,EAAE,KAAK,CAAA;CACb,CAAA;AAED,oEAAoE;AACpE,MAAM,MAAM,wBAAwB,GAAG;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACtC,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,KAAK,CAAC,EAAE,KAAK,CAAA;CACb,CAAA;AAED,6FAA6F;AAC7F,MAAM,MAAM,qBAAqB,CAChC,iBAAiB,SAAS,SAAS,wBAAwB,CAAC,yBAAyB,CAAC,EAAE,IACrF,gBAAgB,GAAG,eAAe,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAA;AAEjE,KAAK,eAAe,CAAC,gBAAgB,IAAI,gBAAgB,SAAS,OAAO,GACtE,MAAM,gBAAgB,GAAG,MAAM,GAC/B,KAAK,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/errors/types.ts"],"names":[],"mappings":"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"}

package/dist/helpers/assert-fixed.d.ts

@@ -3,10 +3,12 @@ import { ResolvableRecord } from '../utils';
 /**
  * Reject a write whose authored value differs from an attribute's schema `fixed`
  * value (XSD `fixed`), as declared under the record's parent. Runs on the WRITE path
- * only (`addChild`/`ensureChild`/`update`) — never on import, so an existing document
+ * only (`addChild`/`ensureChild`/`deepClone`/`update`) — never on import, so an existing document
  * that already violates a fixed value can still be loaded. Attributes are matched by
  * their canonical stored name (`prefix:local`), so pass the array produced by
  * `toFullAttributeArray`.
+ *
+ * @internal write-path guard core runs on every addChild, ensureChild, deepClone and update
  */
 export declare function assertNoFixedViolation(params: {
     dialecteConfig: AnyDialecteConfig;

package/dist/helpers/assert-fixed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert-fixed.d.ts","sourceRoot":"","sources":["../../src/helpers/assert-fixed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC9C,cAAc,EAAE,iBAAiB,CAAA;IACjC,MAAM,EAAE,gBAAgB,CAAA;IACxB,UAAU,EAAE,SAAS,YAAY,EAAE,CAAA;CACnC,GAAG,IAAI,CAaP"}
+{"version":3,"file":"assert-fixed.d.ts","sourceRoot":"","sources":["../../src/helpers/assert-fixed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC9C,cAAc,EAAE,iBAAiB,CAAA;IACjC,MAAM,EAAE,gBAAgB,CAAA;IACxB,UAAU,EAAE,SAAS,YAAY,EAAE,CAAA;CACnC,GAAG,IAAI,CAaP"}

package/dist/helpers/assert-xml-characters.d.ts

@@ -0,0 +1,35 @@
+import { NotXmlCharacterFound, NotXmlCharacterPlace, XmlCharactersWrite } from './assert-xml-characters.types';
+/**
+ * Refuse a record, or a patch of one, holding a character XML does not allow (a control character below U+0020
+ * but tab, line feed and carriage return, U+FFFE, U+FFFF) in what the writer copies into a file: its texts (value,
+ * namespace URI, attribute values and namespace URIs), its names (tag name, namespace prefix, attribute names and
+ * prefixes) and, with `withId` (a file written with the database ids), its id. XML can hold no such character, as
+ * written or as a character reference. Whether a name is otherwise a valid XML name is not checked here.
+ * `XML_CHARACTER_NOT_ALLOWED`, `meta`: `recordId`, `tagName` (when the write names it), `attribute` (its name, when
+ * in an attribute), `part` (`'value' | 'namespace' | 'name' | 'prefix' | 'id'`) and `character` (`U+XXXX`).
+ */
+export declare function assertXmlCharacters(params: {
+    record: XmlCharactersWrite;
+    withId?: boolean;
+}): void;
+/**
+ * The first character XML does not allow in the texts of `record` - its value, its namespace URI, then each
+ * attribute's value and namespace URI - and where it sits; `undefined` when none.
+ */
+export declare function findNotXmlCharacterInText(params: {
+    record: XmlCharactersWrite;
+}): NotXmlCharacterFound | undefined;
+/**
+ * The first character XML does not allow in the names of `record` - its tag name, its namespace prefix, then each
+ * attribute's prefix and name, and its id with `withId` - and where it sits; `undefined` when none.
+ */
+export declare function findNotXmlCharacterInNames(params: {
+    record: XmlCharactersWrite;
+    withId: boolean;
+}): NotXmlCharacterFound | undefined;
+/** Where a character sits, as a sentence begins: `The value of <A> 'a-1'`, `The attribute aA of ...`. */
+export declare function describePlace(params: {
+    place: NotXmlCharacterPlace;
+    element: string;
+}): string;
+//# sourceMappingURL=assert-xml-characters.d.ts.map

package/dist/helpers/assert-xml-characters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-xml-characters.d.ts","sourceRoot":"","sources":["../../src/helpers/assert-xml-characters.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,oBAAoB,EAEpB,oBAAoB,EACpB,kBAAkB,EAClB,MAAM,+BAA+B,CAAA;AAEtC;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC3C,MAAM,EAAE,kBAAkB,CAAA;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAA;CAChB,GAAG,IAAI,CAoBP;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,kBAAkB,CAAA;CAC1B,GAAG,oBAAoB,GAAG,SAAS,CAsBnC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,kBAAkB,CAAA;IAC1B,MAAM,EAAE,OAAO,CAAA;CACf,GAAG,oBAAoB,GAAG,SAAS,CAuBnC;AAED,yGAAyG;AACzG,wBAAgB,aAAa,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAc9F"}

package/dist/helpers/assert-xml-characters.types.d.ts

@@ -0,0 +1,26 @@
+import { AnyAttribute, Namespace } from '../types';
+/**
+ * What `assertXmlCharacters` reads of a record written, or of a patch of one (`tagName`, `namespace` and `value`
+ * then optional): its texts (value, namespace URI, attribute values and namespace URIs) and its names (tag name,
+ * namespace prefix, attribute names and prefixes).
+ */
+export type XmlCharactersWrite = {
+    id: string;
+    tagName?: string;
+    namespace?: Namespace;
+    value?: string;
+    attributes?: readonly AnyAttribute[];
+};
+/** Which part of a record (or of one of its attributes) holds a character XML does not allow. */
+export type NotXmlCharacterPart = 'value' | 'namespace' | 'name' | 'prefix' | 'id';
+/** Where a character XML does not allow sits in a record. */
+export type NotXmlCharacterPlace = {
+    part: NotXmlCharacterPart;
+    /** The attribute holding it, by name; absent for the record's own parts */
+    attribute?: string;
+};
+/** The first character XML does not allow in a record (`U+XXXX`), and where it sits. */
+export type NotXmlCharacterFound = NotXmlCharacterPlace & {
+    character: string;
+};
+//# sourceMappingURL=assert-xml-characters.types.d.ts.map

package/dist/helpers/assert-xml-characters.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-xml-characters.types.d.ts","sourceRoot":"","sources":["../../src/helpers/assert-xml-characters.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAEtD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;CACpC,CAAA;AAED,iGAAiG;AACjG,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAA;AAElF,6DAA6D;AAC7D,MAAM,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,mBAAmB,CAAA;IACzB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,wFAAwF;AACxF,MAAM,MAAM,oBAAoB,GAAG,oBAAoB,GAAG;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,CAAA"}

package/dist/helpers/assert-xsi-type.d.ts

@@ -6,6 +6,8 @@ import { ResolvableRecord } from '../utils';
  * nowhere. Runs on the WRITE path (`addChild`, `ensureChild`, clone, `update`) - never on import: a document is
  * loaded as it is, validation reports it. A built-in XSD type is not judged: the definition does not list the
  * built-in hierarchy.
+ *
+ * @internal write-path guard core runs on every addChild, ensureChild, deepClone and update
  */
 export declare function assertXsiTypeAdmitted(params: {
     dialecteConfig: AnyDialecteConfig;
@@ -15,6 +17,8 @@ export declare function assertXsiTypeAdmitted(params: {
  * Reject an update that changes the type an element names while it keeps content the new type does not admit: the
  * attributes the new type would drop (clear them in the same update) and the children it does not hold (an update
  * touches attributes only: delete them first). Each is named in the error's `meta`.
+ *
+ * @internal update guard core runs on every update
  */
 export declare function assertXsiTypeChangeLeavesNothing(params: {
     dialecteConfig: AnyDialecteConfig;

package/dist/helpers/assert-xsi-type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert-xsi-type.d.ts","sourceRoot":"","sources":["../../src/helpers/assert-xsi-type.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC7C,cAAc,EAAE,iBAAiB,CAAA;IACjC,MAAM,EAAE,gBAAgB,CAAA;CACxB,GAAG,IAAI,CA6BP;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE;IACxD,cAAc,EAAE,iBAAiB,CAAA;IACjC,sFAAsF;IACtF,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/B,2EAA2E;IAC3E,MAAM,EAAE,gBAAgB,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;KAAE,CAAA;CAC5E,GAAG,IAAI,CAgCP"}
+{"version":3,"file":"assert-xsi-type.d.ts","sourceRoot":"","sources":["../../src/helpers/assert-xsi-type.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE/C;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC7C,cAAc,EAAE,iBAAiB,CAAA;IACjC,MAAM,EAAE,gBAAgB,CAAA;CACxB,GAAG,IAAI,CA6BP;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE;IACxD,cAAc,EAAE,iBAAiB,CAAA;IACjC,sFAAsF;IACtF,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/B,2EAA2E;IAC3E,MAAM,EAAE,gBAAgB,GAAG;QAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;KAAE,CAAA;CAC5E,GAAG,IAAI,CAgCP"}

package/dist/helpers/converter.d.ts

@@ -1,8 +1,11 @@
 import { Ref, RefOrRecord } from '../document';
 import { RawRecord, TrackedRecord, TreeRecord, AnyDialecteConfig, Attribute, AttributeInputOf, ElementsOf, FullAttributeObjectOf, AttributesValueObjectOf, Namespace, OperationStatus, ParentRelationship, ChildRelationship } from '../types';
 /**
- * Converts a TrackedRecord | TreeRecord to RawRecord
- * If already a RawRecord, returns as-is.
+ * A new `RawRecord` holding the seven stored fields of a raw, tracked or tree record (`id`, `tagName`, `namespace`,
+ * `attributes`, `value`, `parent`, `children`); a change status or tree children are left out. Only the record
+ * object is new: `attributes`, `parent` and `children` are the same arrays and objects as the record's, not cloned.
+ *
+ * @intent strip a record to its stored fields, pass a record where a raw record is expected
  */
 export declare function toRawRecord<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(record: RawRecord<GenericConfig, GenericElement> | TrackedRecord<GenericConfig, GenericElement> | TreeRecord<GenericConfig, GenericElement>): RawRecord<GenericConfig, GenericElement>;
 /**
@@ -21,6 +24,8 @@ export declare function toRawRecord<GenericConfig extends AnyDialecteConfig, Gen
  * Use it wherever a per-element value must flow into an element-union API — e.g.
  * building an `Operation`, or passing a `Ref<Config, GenericElement>` to a
  * union-typed method.
+ *
+ * @intent pass a per-element record or ref to an API typed with the element union, fix an invariance type error on a record or ref
  */
 export declare function widen<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(thing: TreeRecord<GenericConfig, GenericElement>): TreeRecord<GenericConfig, ElementsOf<GenericConfig>>;
 export declare function widen<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(thing: TrackedRecord<GenericConfig, GenericElement>): TrackedRecord<GenericConfig, ElementsOf<GenericConfig>>;
@@ -28,16 +33,22 @@ export declare function widen<GenericConfig extends AnyDialecteConfig, GenericEl
 export declare function widen<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(thing: Ref<GenericConfig, GenericElement>): Ref<GenericConfig, ElementsOf<GenericConfig>>;
 export declare function widen<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(thing: Attribute<GenericConfig, GenericElement>): Attribute<GenericConfig, ElementsOf<GenericConfig>>;
 /**
- * Converts a RawRecord | TreeRecord to TrackedRecord
- * If already a TrackedRecord, returns as-is.
+ * A new `TrackedRecord` of a raw, tracked or tree record: its stored fields (as `toRawRecord` takes them) and a change
+ * status - the `status` given, else the record's own, else `'unchanged'`. The field values are shared with the
+ * record, not cloned.
+ *
+ * @intent give a raw record a change status, pass a raw or tree record where a tracked record is expected
  */
 export declare function toTrackedRecord<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(params: {
     record: RawRecord<GenericConfig, GenericElement> | TrackedRecord<GenericConfig, GenericElement> | TreeRecord<GenericConfig, GenericElement>;
     status?: OperationStatus;
 }): TrackedRecord<GenericConfig, GenericElement>;
 /**
- * Converts a RawRecord | TrackedRecord to TreeRecord
- * If already a TreeRecord, returns as-is.
+ * A new `TreeRecord` of a raw, tracked or tree record: its stored fields and change status as `toTrackedRecord`
+ * gives them, and its child nodes - the `tree` given, else the record's own, else `[]`. The field values and the
+ * `tree` array are shared with the record, not cloned.
+ *
+ * @intent turn a record into a tree node, build a tree record from a raw or tracked record
  */
 export declare function toTreeRecord<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(params: {
     record: RawRecord<GenericConfig, GenericElement> | TrackedRecord<GenericConfig, GenericElement> | TreeRecord<GenericConfig, GenericElement>;
@@ -48,6 +59,8 @@ export declare function toTreeRecord<GenericConfig extends AnyDialecteConfig, Ge
  * Converts attributes to FullAttributeObject array format and canonicalizes each
  * attribute name to the two naming rules (see `canonicalizeAttributeName`), so
  * records from import, create, and update share one stored name per attribute.
+ *
+ * @intent turn an attribute value object into an attribute array, canonicalize attribute names before a write
  */
 export declare function toFullAttributeArray<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(params: {
     dialecteConfig: GenericConfig;
@@ -65,6 +78,8 @@ export declare function toFullAttributeArray<GenericConfig extends AnyDialecteCo
 /**
  * Convert a Ref, ParentRelationship, ChildRelationship, or Record to a Ref.
  * ParentsOf/ChildrenOf are subsets of ElementsOf by design, so this is semantically safe.
+ *
+ * @intent get the ref of a record or a relationship, pass a ref to a query
  */
 export declare function toRef<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(input: Ref<GenericConfig, GenericElement> | undefined): Ref<GenericConfig, GenericElement>;
 export declare function toRef<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(input: ParentRelationship<GenericConfig, GenericElement> | ChildRelationship<GenericConfig, GenericElement> | undefined): Ref<GenericConfig, GenericElement>;

package/dist/helpers/converter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"converter.d.ts","sourceRoot":"","sources":["../../src/helpers/converter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"converter.d.ts","sourceRoot":"","sources":["../../src/helpers/converter.ts"],"names":[],"mappings":"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"}

package/dist/helpers/evaluate-expectations.d.ts

@@ -0,0 +1,21 @@
+import { EvaluateExpectationsParams, ExpectationsOutcome } from './evaluate-expectations.types';
+import { Query } from '../document';
+import { AnyDialecteConfig } from '../types';
+/**
+ * Check what a document holds against expectations written before the script that builds it, with
+ * no DOM: each expectation counts the elements of its tag (with its attribute values, under an
+ * element of its `under` scope) through the query, so a prepared transaction's `query` is checked
+ * on what `commit()` would write. Every expectation is answered, met or failed with the count found.
+ *
+ * @intent check a built document against expected element counts, verify a script's result before committing, test what a prepared transaction would write
+ *
+ * @example
+ * ```ts
+ * const { failed } = await evaluateExpectations(doc.query, {
+ *   expectations: [{ tag: 'Part', under: { tag: 'Assembly', where: { name: 'A1' } }, count: 2 }],
+ * })
+ * // failed: [{ expectation, actualCount: 1, message: 'expected 2 Part under Assembly[name="A1"], found 1' }]
+ * ```
+ */
+export declare function evaluateExpectations<GenericConfig extends AnyDialecteConfig>(query: Query<GenericConfig>, params: EvaluateExpectationsParams): Promise<ExpectationsOutcome>;
+//# sourceMappingURL=evaluate-expectations.d.ts.map

package/dist/helpers/evaluate-expectations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-expectations.d.ts","sourceRoot":"","sources":["../../src/helpers/evaluate-expectations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,0BAA0B,EAG1B,mBAAmB,EACnB,MAAM,+BAA+B,CAAA;AACtC,OAAO,KAAK,EAAW,KAAK,EAAE,MAAM,YAAY,CAAA;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAgC,MAAM,SAAS,CAAA;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CAAC,aAAa,SAAS,iBAAiB,EACjF,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC,EAC3B,MAAM,EAAE,0BAA0B,GAChC,OAAO,CAAC,mBAAmB,CAAC,CAiB9B"}

package/dist/helpers/evaluate-expectations.types.d.ts

@@ -0,0 +1,31 @@
+/** The elements an expectation is about: a tag, and the attribute values they must hold. */
+export type ExpectationScope = {
+    tag: string;
+    /** Attribute values, each one value or any of several - as `findByAttributes` matches them. */
+    where?: Record<string, string | string[]>;
+};
+/**
+ * What a document should hold, said before a script writes it: elements of a tag, optionally with
+ * attribute values, optionally anywhere under an element of another tag. With `count`, exactly that
+ * many (0: none); without, at least one.
+ */
+export type Expectation = ExpectationScope & {
+    under?: ExpectationScope;
+    count?: number;
+};
+/** An expectation the document does not meet: how many elements it holds, and why that fails. */
+export type ExpectationFailure = {
+    expectation: Expectation;
+    actualCount: number;
+    message: string;
+};
+/** What `evaluateExpectations` answers: every expectation, met or not, in the order given. */
+export type ExpectationsOutcome = {
+    passed: Expectation[];
+    failed: ExpectationFailure[];
+};
+/** What `evaluateExpectations` is given beside the query. */
+export type EvaluateExpectationsParams = {
+    expectations: readonly Expectation[];
+};
+//# sourceMappingURL=evaluate-expectations.types.d.ts.map

package/dist/helpers/evaluate-expectations.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate-expectations.types.d.ts","sourceRoot":"","sources":["../../src/helpers/evaluate-expectations.types.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAA;CACzC,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG;IAC5C,KAAK,CAAC,EAAE,gBAAgB,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,iGAAiG;AACjG,MAAM,MAAM,kBAAkB,GAAG;IAChC,WAAW,EAAE,WAAW,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;CACf,CAAA;AAED,8FAA8F;AAC9F,MAAM,MAAM,mBAAmB,GAAG;IACjC,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,MAAM,EAAE,kBAAkB,EAAE,CAAA;CAC5B,CAAA;AAED,6DAA6D;AAC7D,MAAM,MAAM,0BAA0B,GAAG;IACxC,YAAY,EAAE,SAAS,WAAW,EAAE,CAAA;CACpC,CAAA"}

package/dist/helpers/guard.d.ts

@@ -1,26 +1,41 @@
 import { RawRecord, TrackedRecord, AnyDialecteConfig, ElementsOf, AttributesOf, FullAttributeObjectOf, AttributesValueObjectOf, TreeRecord, AnyRelationship } from '../types';
 /**
- * Type guard to check if attributes are in array format (FullAttributeObject[])
+ * Whether attributes come as an array of attribute objects (`FullAttributeObject[]`) rather than a value object.
+ *
+ * @intent tell an attribute array from an attribute value object, narrow attribute input
  */
 export declare function isFullAttributeArray<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(attributes: AttributesValueObjectOf<GenericConfig, GenericElement> | FullAttributeObjectOf<GenericConfig, GenericElement>[]): attributes is FullAttributeObjectOf<GenericConfig, GenericElement>[];
 /**
- * Type guard to check if a record is a RawRecord (database record without API extensions)
+ * Whether a record is a `RawRecord`: the stored shape, without a change status or tree children.
+ *
+ * @intent tell a stored record from a tracked or tree record, narrow a record to its raw shape
  */
 export declare function isRawRecord<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(record: unknown): record is RawRecord<GenericConfig, GenericElement>;
 /**
- * Type guard to check if a record is a TrackedRecord
+ * Whether a record is a `TrackedRecord`: a stored record with its change status, as queries return it.
+ *
+ * @intent tell a tracked record from a raw or tree record, narrow a record to its tracked shape
  */
 export declare function isTrackedRecord<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(record: RawRecord<GenericConfig, GenericElement> | TrackedRecord<GenericConfig, GenericElement> | TreeRecord<GenericConfig, GenericElement>): record is TrackedRecord<GenericConfig, GenericElement>;
 /**
- * Type guard to check if a record is a TreeRecord
+ * Whether a record is a `TreeRecord`: a node of a tree read, holding its child nodes.
+ *
+ * @intent tell a tree record from a raw or tracked record, narrow a record to a tree node
  */
 export declare function isTreeRecord<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(record: RawRecord<GenericConfig, GenericElement> | TrackedRecord<GenericConfig, GenericElement> | TreeRecord<GenericConfig, GenericElement>): record is TreeRecord<GenericConfig, GenericElement>;
+/**
+ * Whether a record is of the tag name given, narrowing its type to that element (raw, tracked or tree record alike).
+ *
+ * @intent narrow a record to one tag name, check an element's tag with types
+ */
 export declare function isRecordOf<GenericConfig extends AnyDialecteConfig, GenericTagName extends ElementsOf<GenericConfig>>(record: TreeRecord<GenericConfig, ElementsOf<GenericConfig>>, tagName: GenericTagName): record is TreeRecord<GenericConfig, GenericTagName>;
 export declare function isRecordOf<GenericConfig extends AnyDialecteConfig, GenericTagName extends ElementsOf<GenericConfig>>(record: TrackedRecord<GenericConfig, ElementsOf<GenericConfig>>, tagName: GenericTagName): record is TrackedRecord<GenericConfig, GenericTagName>;
 export declare function isRecordOf<GenericConfig extends AnyDialecteConfig, GenericTagName extends ElementsOf<GenericConfig>>(record: RawRecord<GenericConfig, ElementsOf<GenericConfig>>, tagName: GenericTagName): record is RawRecord<GenericConfig, GenericTagName>;
 /**
  * Type predicate narrowing a relationship to a specific tag name.
  *
+ * @intent filter child refs by tag name, narrow a child relationship to one tag
+ *
  * @example
  * const aa1Refs = recordA.children.filter((child) => isChildOf(child, 'AA_1'))
  * const aa1Elements = await query.getRecords(aa1Refs) // TrackedRecord<Config, 'AA_1'>[]
@@ -31,6 +46,8 @@ export declare function isChildOf<T extends string>(child: AnyRelationship, tagN
 /**
  * Type predicate narrowing a parent relationship to a specific tag name.
  *
+ * @intent check the tag of a record's parent, narrow a parent relationship to one tag
+ *
  * @example
  * if (record.parent && isParentOf(record.parent, 'Root')) { ... }
  */
@@ -40,6 +57,7 @@ export declare function isParentOf<T extends string>(parent: AnyRelationship, ta
 /**
  * Type predicate narrowing a string to a valid element tag name for a given config.
  *
+ * @intent check that a string is a tag name of the dialecte, narrow an unknown tag name before a typed query
  *
  * @example
  * if (isElementOf<MyConfig>(tagName, dialecteConfig)) {
@@ -50,6 +68,8 @@ export declare function isElementOf<GenericConfig extends AnyDialecteConfig>(tag
 /**
  * Type predicate narrowing a string to a valid attribute name for a given record.
  *
+ * @intent check that a string is an attribute of an element, narrow an attribute name before a typed read
+ *
  * @example
  * if (isAttributeOf(record, entry.uuidAttr)) {
  *   const value = await query.getAttribute(record, entry.uuidAttr) // fully typed

package/dist/helpers/guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/helpers/guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/helpers/guard.ts"],"names":[],"mappings":"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"}

package/dist/helpers/index.d.ts

@@ -8,4 +8,6 @@ export * from './merge-extensions';
 export * from './strip-attributes';
 export * from './read-attributes';
 export type * from './read-attributes.types';
+export * from './evaluate-expectations';
+export type * from './evaluate-expectations.types';
 //# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,mBAAmB,yBAAyB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,mBAAmB,yBAAyB,CAAA;AAC5C,cAAc,yBAAyB,CAAA;AACvC,mBAAmB,+BAA+B,CAAA"}

package/dist/helpers/merge-extensions.d.ts

@@ -6,6 +6,8 @@ import { ExtensionModules, MergedExtensions } from '../document';
  * "history"), their query and transaction groups are merged at the method level.
  * A DialecteError is thrown immediately if any method name appears in both groups.
  *
+ * @intent combine extension modules into one registry, add custom extensions next to a dialecte's base extensions
+ *
  * @example
  * ```ts
  * mergeExtensions({ base: { history, dataModel }, custom: { myFeature } })

package/dist/helpers/merge-extensions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merge-extensions.d.ts","sourceRoot":"","sources":["../../src/helpers/merge-extensions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAgBpE;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,WAAW,SAAS,gBAAgB,EACpC,aAAa,SAAS,gBAAgB,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC5D,OAAO,EAAE;IACV,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,MAAM,CAAC,EAAE,aAAa,CAAA;CACtB,GAAG,gBAAgB,CAAC,WAAW,GAAG,aAAa,CAAC,CA+BhD"}
+{"version":3,"file":"merge-extensions.d.ts","sourceRoot":"","sources":["../../src/helpers/merge-extensions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAgBpE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC9B,WAAW,SAAS,gBAAgB,EACpC,aAAa,SAAS,gBAAgB,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC5D,OAAO,EAAE;IACV,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,MAAM,CAAC,EAAE,aAAa,CAAA;CACtB,GAAG,gBAAgB,CAAC,WAAW,GAAG,aAAa,CAAC,CA+BhD"}

package/dist/helpers/read-attributes.d.ts

@@ -11,6 +11,8 @@ import { AnyAttribute } from '../types';
  * Reads the record as you hold it. Inside a transaction use `tx.getAttribute`, which sees the transaction's staged
  * writes: a record held from before a write still reads its old values here.
  *
+ * @intent look up an attribute value on a record you already hold in an import hook, look up an attribute of a held record in a pure function with no query
+ *
  * @example
  * readAttribute({ record, dialecteConfig, name: 'aA' })                                      // → 'v' | ''
  * readAttribute({ record, dialecteConfig, name: 'aA', defaults: 'none', fullObject: true }) // → undefined when absent
@@ -39,6 +41,8 @@ export declare function readAttribute(params: ReadAttributesBaseParams & {
  * Reads the record as you hold it. Inside a transaction use `tx.getAttributes`, which sees the transaction's staged
  * writes: a record held from before a write still reads its old values here.
  *
+ * @intent look up the attribute values of a record you already hold in an import hook, look up the attributes of a held record in a pure function with no query
+ *
  * @example
  * readAttributes({ record, dialecteConfig })                        // → { aA: 'v', 'ext:cA': 'w' }
  * readAttributes({ record, dialecteConfig, defaults: 'none' })      // → stored only

package/dist/helpers/read-attributes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-attributes.d.ts","sourceRoot":"","sources":["../../src/helpers/read-attributes.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AACvE,OAAO,KAAK,EAAE,YAAY,EAA8C,MAAM,SAAS,CAAA;AAGvF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GACzF,MAAM,CAAA;AACT,wBAAgB,aAAa,CAC5B,MAAM,EAAE,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GACvF,YAAY,GAAG,SAAS,CAAA;AAyC3B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,wBAAwB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAC3E,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AACzB,wBAAgB,cAAc,CAC7B,MAAM,EAAE,wBAAwB,GAAG;IAAE,UAAU,EAAE,IAAI,CAAA;CAAE,GACrD,YAAY,EAAE,CAAA"}
+{"version":3,"file":"read-attributes.d.ts","sourceRoot":"","sources":["../../src/helpers/read-attributes.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AACvE,OAAO,KAAK,EAAE,YAAY,EAA8C,MAAM,SAAS,CAAA;AAGvF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GACzF,MAAM,CAAA;AACT,wBAAgB,aAAa,CAC5B,MAAM,EAAE,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,IAAI,CAAA;CAAE,GACvF,YAAY,GAAG,SAAS,CAAA;AAyC3B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,wBAAwB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAA;CAAE,GAC3E,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AACzB,wBAAgB,cAAc,CAC7B,MAAM,EAAE,wBAAwB,GAAG;IAAE,UAAU,EAAE,IAAI,CAAA;CAAE,GACrD,YAAY,EAAE,CAAA"}

package/dist/helpers/standardizing.d.ts

@@ -1,4 +1,14 @@
 import { AnyDialecteConfig, AttributeInputOf, ElementsOf, RawRecord, AttributesValueObjectOf, TransactionHooks } from '../types';
+/**
+ * The raw record core stores for an element input. A record of a tag the dialecte does not declare, or in a
+ * namespace it does not declare, returns early: only an id, the attribute array (xsi:type in stored form) and empty
+ * fields are filled in, nothing else touched, no hook run. A schema element gets canonical attribute names, xsi:type
+ * and order, its namespace resolved, then the `afterStandardizedRecord` hook applied; for it, an unqualified
+ * attribute the schema does not declare is dropped (unless its attribute wildcard admits no-namespace attributes),
+ * and so is a schema attribute without a value (an empty one is kept only where a `default` or `fixed` is declared).
+ *
+ * @internal record normalization of every record core stores (import, create, clone, update)
+ */
 export declare function standardizeRecord<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(params: {
     dialecteConfig: GenericConfig;
     hooks?: TransactionHooks<GenericConfig>;

package/dist/helpers/standardizing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"standardizing.d.ts","sourceRoot":"","sources":["../../src/helpers/standardizing.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACX,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EAEV,SAAS,EACT,uBAAuB,EACvB,gBAAgB,EAChB,MAAM,SAAS,CAAA;AAEhB,wBAAgB,iBAAiB,CAChC,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAC/C,MAAM,EAAE;IACT,cAAc,EAAE,aAAa,CAAA;IAC7B,KAAK,CAAC,EAAE,gBAAgB,CAAC,aAAa,CAAC,CAAA;IACvC,MAAM,EAAE;QACP,OAAO,EAAE,cAAc,CAAA;QACvB,UAAU,CAAC,EACR,OAAO,CAAC,uBAAuB,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,GAC/D,gBAAgB,CAAC,aAAa,EAAE,cAAc,CAAC,EAAE,CAAA;KACpD,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,EAAE,YAAY,CAAC,CAAA;CACzE,GAAG,SAAS,CAAC,aAAa,EAAE,cAAc,CAAC,CAsH3C"}
+{"version":3,"file":"standardizing.d.ts","sourceRoot":"","sources":["../../src/helpers/standardizing.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACX,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EAEV,SAAS,EACT,uBAAuB,EACvB,gBAAgB,EAChB,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAChC,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAC/C,MAAM,EAAE;IACT,cAAc,EAAE,aAAa,CAAA;IAC7B,KAAK,CAAC,EAAE,gBAAgB,CAAC,aAAa,CAAC,CAAA;IACvC,MAAM,EAAE;QACP,OAAO,EAAE,cAAc,CAAA;QACvB,UAAU,CAAC,EACR,OAAO,CAAC,uBAAuB,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,GAC/D,gBAAgB,CAAC,aAAa,EAAE,cAAc,CAAC,EAAE,CAAA;KACpD,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC,EAAE,YAAY,CAAC,CAAA;CACzE,GAAG,SAAS,CAAC,aAAa,EAAE,cAAc,CAAC,CAwH3C"}

package/dist/helpers/strip-attributes.d.ts

@@ -2,6 +2,8 @@ import { AnyDialecteConfig, ElementsOf, RawRecord, TrackedRecord, TreeRecord } f
 /**
  * Returns a new record with specified attribute names removed.
  * Pure function — does not mutate the input.
+ *
+ * @intent remove attributes from a record, drop attributes before cloning a record
  */
 export declare function stripAttributes<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(record: TreeRecord<GenericConfig, GenericElement>, names: string[]): TreeRecord<GenericConfig, GenericElement>;
 export declare function stripAttributes<GenericConfig extends AnyDialecteConfig, GenericElement extends ElementsOf<GenericConfig>>(record: TrackedRecord<GenericConfig, GenericElement>, names: string[]): TrackedRecord<GenericConfig, GenericElement>;

package/dist/helpers/strip-attributes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strip-attributes.d.ts","sourceRoot":"","sources":["../../src/helpers/strip-attributes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAElG;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAEhD,MAAM,EAAE,UAAU,CAAC,aAAa,EAAE,cAAc,CAAC,EACjD,KAAK,EAAE,MAAM,EAAE,GACb,UAAU,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA;AAE5C,wBAAgB,eAAe,CAC9B,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAEhD,MAAM,EAAE,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,EACpD,KAAK,EAAE,MAAM,EAAE,GACb,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA;AAE/C,wBAAgB,eAAe,CAC9B,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAEhD,MAAM,EAAE,SAAS,CAAC,aAAa,EAAE,cAAc,CAAC,EAChD,KAAK,EAAE,MAAM,EAAE,GACb,SAAS,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA"}
+{"version":3,"file":"strip-attributes.d.ts","sourceRoot":"","sources":["../../src/helpers/strip-attributes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAElG;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAEhD,MAAM,EAAE,UAAU,CAAC,aAAa,EAAE,cAAc,CAAC,EACjD,KAAK,EAAE,MAAM,EAAE,GACb,UAAU,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA;AAE5C,wBAAgB,eAAe,CAC9B,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAEhD,MAAM,EAAE,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,EACpD,KAAK,EAAE,MAAM,EAAE,GACb,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA;AAE/C,wBAAgB,eAAe,CAC9B,aAAa,SAAS,iBAAiB,EACvC,cAAc,SAAS,UAAU,CAAC,aAAa,CAAC,EAEhD,MAAM,EAAE,SAAS,CAAC,aAAa,EAAE,cAAc,CAAC,EAChD,KAAK,EAAE,MAAM,EAAE,GACb,SAAS,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA"}