@entifix/core 0.1.0-0

package/dist/entity-definition/serializer/deserialize.js

@@ -0,0 +1,145 @@
+import { Effect } from 'effect';
+import { EntifixBuildError } from '../../base-entities/entifix-error/index.js';
+import { extractMetaAccessors } from '../helpers/index.js';
+import { EntityCollectionLink } from '../links/entity-collection-link/index.js';
+import { EntityLink } from '../links/entity-link/index.js';
+//#region Validations
+function assertEntityObject(entityConstructor, entityData) {
+    if (typeof entityData !== 'object') {
+        throw new EntifixBuildError(`Failed to deserialize entity of type ${entityConstructor.name}. Expected an object but got ${typeof entityData}`, undefined, {
+            entityData,
+            entityConstructor: entityConstructor.name
+        });
+    }
+}
+function assertEntityCollection(entityConstructor, entityCollectionData) {
+    if (!Array.isArray(entityCollectionData)) {
+        throw new EntifixBuildError(`Failed to deserialize entity collection of type ${entityConstructor.name}. Expected an array but got ${typeof entityCollectionData}`, undefined, {
+            entityCollectionData,
+            entityConstructor: entityConstructor.name
+        });
+    }
+}
+//#endregion
+//#region Recursive deserialization
+function isEmbeddedData(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Populates a to-one relation from its raw value. An object is treated as
+ * embedded data and deserialized into an instance; any scalar is treated as a
+ * foreign key and stored as the link id (resolved lazily via `reload`).
+ */ function populateEntityLink(link, rawValue) {
+    if (rawValue == null) {
+        return;
+    }
+    if (isEmbeddedData(rawValue)) {
+        link.setValue(buildEntityInstance(link.entityConstructor, rawValue));
+        return;
+    }
+    link.setId(rawValue);
+}
+/**
+ * Populates a to-many relation from its raw array, mixing embedded objects
+ * (deserialized) and scalar foreign keys as they appear.
+ */ function populateEntityCollectionLink(link, rawValue) {
+    if (!Array.isArray(rawValue)) {
+        return;
+    }
+    const values = [];
+    const ids = [];
+    for (const item of rawValue){
+        if (isEmbeddedData(item)) {
+            values.push(buildEntityInstance(link.entityConstructor, item));
+        } else if (item != null) {
+            ids.push(item);
+        }
+    }
+    if (values.length > 0) {
+        link.setValues(values);
+    } else if (ids.length > 0) {
+        link.setIds(ids);
+    }
+}
+function buildEntityInstance(entityConstructor, entityData) {
+    const metaAccessors = extractMetaAccessors(entityConstructor);
+    const newInstance = new entityConstructor();
+    metaAccessors// Entities decorate their accessors on the getter, so the writable property
+    // list comes from getter-kind metadata; read-only/hidden ones are skipped.
+    // The value is then assigned through the instance's JS setter.
+    .filter((metaAccessor)=>!metaAccessor.hidden && !metaAccessor.readonly && metaAccessor.kind === 'getter').forEach((metaAccessor)=>{
+        var _metaAccessor_alias;
+        const propertyName = (_metaAccessor_alias = metaAccessor.alias) != null ? _metaAccessor_alias : metaAccessor.name;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const current = newInstance[metaAccessor.name];
+        // Relations are pre-initialized as link instances by the entity
+        // constructor. Their accessors are read-only getters, so populate the
+        // existing link from the raw value rather than assigning through a setter.
+        if (current instanceof EntityLink) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            populateEntityLink(current, entityData[propertyName]);
+            return;
+        }
+        if (current instanceof EntityCollectionLink) {
+            populateEntityCollectionLink(current, entityData[propertyName]);
+            return;
+        }
+        // Owned rows are rebuilt through the child's own accessors, the mirror of
+        // what `serializeEntity` wrote. Without this the member would hold plain
+        // objects while its declared type says otherwise — and a child whose
+        // accessor carries an `alias` would keep the storage column name as its
+        // property, which is exactly the mapping layer the serializer exists to
+        // remove.
+        if (metaAccessor.type === 'composition' && metaAccessor.childType) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const rows = entityData[propertyName];
+            if (Array.isArray(rows)) {
+                const childType = metaAccessor.childType();
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                newInstance[metaAccessor.name] = rows.map((row)=>buildEntityInstance(childType, row));
+            }
+            return;
+        }
+        if (propertyName in entityData && // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        entityData[propertyName] !== undefined) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            newInstance[metaAccessor.name] = entityData[propertyName];
+        }
+    });
+    return newInstance;
+}
+function deserializeEntity(entityConstructor, entityData) {
+    if (entityData == null) {
+        return undefined;
+    }
+    assertEntityObject(entityConstructor, entityData);
+    return buildEntityInstance(entityConstructor, entityData);
+}
+function deserializeCollection(entityConstructor, entityCollectionData, failOnNull) {
+    if (entityCollectionData == null && !failOnNull) {
+        return [];
+    }
+    assertEntityCollection(entityConstructor, entityCollectionData);
+    // Recurse into nested arrays so a collection can hold arrays of arrays,
+    // and reuse the single-entity validation/build for the leaf items.
+    return entityCollectionData.map((item)=>Array.isArray(item) ? deserializeCollection(entityConstructor, item, failOnNull) : deserializeEntity(entityConstructor, item));
+}
+//#endregion
+//#region Effect factories
+const toEntifixBuildError = (message, context)=>(error)=>error instanceof EntifixBuildError ? error : new EntifixBuildError(message, error, context);
+export const deserializeSingleEntity = (entityConstructor, entityData)=>Effect.try({
+        try: ()=>deserializeEntity(entityConstructor, entityData),
+        catch: toEntifixBuildError(`Failed to deserialize entity of type ${entityConstructor.name}`, {
+            entityData,
+            entityConstructor: entityConstructor.name
+        })
+    });
+export const deserializeEntityCollection = (entityConstructor, entityCollectionData, failOnNull = false)=>Effect.try({
+        try: ()=>deserializeCollection(entityConstructor, entityCollectionData, failOnNull),
+        catch: toEntifixBuildError(`Failed to deserialize entity collection of type ${entityConstructor.name}`, {
+            entityCollectionData,
+            entityConstructor: entityConstructor.name
+        })
+    }); //#endregion
+
+//# sourceMappingURL=deserialize.js.map

package/dist/entity-definition/serializer/deserialize.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/serializer/deserialize.ts"],"sourcesContent":["import { Effect } from 'effect';\n\nimport { EntifixBuildError } from '../../base-entities/entifix-error/index.js';\nimport { Entity, EntityConstructor, EntityId } from '../../types/Entity.js';\nimport { extractMetaAccessors } from '../helpers/index.js';\nimport { EntityCollectionLink } from '../links/entity-collection-link/index.js';\nimport { EntityLink } from '../links/entity-link/index.js';\n\n/**\n * Result of deserializing a value against an entity constructor. A value can be\n * a single entity, a missing entity (`undefined`) or an arbitrarily nested\n * array of those — which lets collections recurse into arrays of arrays.\n */\ntype DeserializedEntity<TEntity extends Entity> =\n  TEntity | undefined | DeserializedEntity<TEntity>[];\n\n//#region Validations\n\nfunction assertEntityObject<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  entityData: unknown,\n): asserts entityData is object {\n  if (typeof entityData !== 'object') {\n    throw new EntifixBuildError(\n      `Failed to deserialize entity of type ${\n        entityConstructor.name\n      }. Expected an object but got ${typeof entityData}`,\n      undefined,\n      {\n        entityData,\n        entityConstructor: entityConstructor.name,\n      },\n    );\n  }\n}\n\nfunction assertEntityCollection<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  entityCollectionData: unknown,\n): asserts entityCollectionData is unknown[] {\n  if (!Array.isArray(entityCollectionData)) {\n    throw new EntifixBuildError(\n      `Failed to deserialize entity collection of type ${\n        entityConstructor.name\n      }. Expected an array but got ${typeof entityCollectionData}`,\n      undefined,\n      {\n        entityCollectionData,\n        entityConstructor: entityConstructor.name,\n      },\n    );\n  }\n}\n\n//#endregion\n\n//#region Recursive deserialization\n\nfunction isEmbeddedData(value: unknown): value is object {\n  return value != null && typeof value === 'object' && !Array.isArray(value);\n}\n\n/**\n * Populates a to-one relation from its raw value. An object is treated as\n * embedded data and deserialized into an instance; any scalar is treated as a\n * foreign key and stored as the link id (resolved lazily via `reload`).\n */\nfunction populateEntityLink<TEntity extends Entity>(\n  link: EntityLink<TEntity>,\n  rawValue: unknown,\n): void {\n  if (rawValue == null) {\n    return;\n  }\n  if (isEmbeddedData(rawValue)) {\n    link.setValue(buildEntityInstance(link.entityConstructor, rawValue));\n    return;\n  }\n  link.setId(rawValue as EntityId);\n}\n\n/**\n * Populates a to-many relation from its raw array, mixing embedded objects\n * (deserialized) and scalar foreign keys as they appear.\n */\nfunction populateEntityCollectionLink<TEntity extends Entity>(\n  link: EntityCollectionLink<TEntity>,\n  rawValue: unknown,\n): void {\n  if (!Array.isArray(rawValue)) {\n    return;\n  }\n  const values: TEntity[] = [];\n  const ids: EntityId[] = [];\n  for (const item of rawValue) {\n    if (isEmbeddedData(item)) {\n      values.push(buildEntityInstance(link.entityConstructor, item));\n    } else if (item != null) {\n      ids.push(item as EntityId);\n    }\n  }\n  if (values.length > 0) {\n    link.setValues(values);\n  } else if (ids.length > 0) {\n    link.setIds(ids);\n  }\n}\n\nfunction buildEntityInstance<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  entityData: object,\n): TEntity {\n  const metaAccessors = extractMetaAccessors(entityConstructor);\n\n  const newInstance = new entityConstructor();\n  metaAccessors\n    // Entities decorate their accessors on the getter, so the writable property\n    // list comes from getter-kind metadata; read-only/hidden ones are skipped.\n    // The value is then assigned through the instance's JS setter.\n    .filter(\n      metaAccessor =>\n        !metaAccessor.hidden &&\n        !metaAccessor.readonly &&\n        metaAccessor.kind === 'getter',\n    )\n    .forEach(metaAccessor => {\n      const propertyName = metaAccessor.alias ?? metaAccessor.name;\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const current = (newInstance as any)[metaAccessor.name];\n\n      // Relations are pre-initialized as link instances by the entity\n      // constructor. Their accessors are read-only getters, so populate the\n      // existing link from the raw value rather than assigning through a setter.\n      if (current instanceof EntityLink) {\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        populateEntityLink(current, (entityData as any)[propertyName]);\n        return;\n      }\n      if (current instanceof EntityCollectionLink) {\n        populateEntityCollectionLink(\n          current,\n          (entityData as any)[propertyName],\n        );\n        return;\n      }\n\n      // Owned rows are rebuilt through the child's own accessors, the mirror of\n      // what `serializeEntity` wrote. Without this the member would hold plain\n      // objects while its declared type says otherwise — and a child whose\n      // accessor carries an `alias` would keep the storage column name as its\n      // property, which is exactly the mapping layer the serializer exists to\n      // remove.\n      if (metaAccessor.type === 'composition' && metaAccessor.childType) {\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        const rows = (entityData as any)[propertyName];\n        if (Array.isArray(rows)) {\n          const childType =\n            metaAccessor.childType() as EntityConstructor<Entity>;\n          // eslint-disable-next-line @typescript-eslint/no-explicit-any\n          (newInstance as any)[metaAccessor.name] = rows.map(row =>\n            buildEntityInstance(childType, row as object),\n          );\n        }\n        return;\n      }\n\n      if (\n        propertyName in entityData &&\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        (entityData as any)[propertyName] !== undefined\n      ) {\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        (newInstance as any)[metaAccessor.name] = (entityData as any)[\n          propertyName\n        ];\n      }\n    });\n\n  return newInstance;\n}\n\nfunction deserializeEntity<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  entityData: unknown,\n): TEntity | undefined {\n  if (entityData == null) {\n    return undefined;\n  }\n  assertEntityObject(entityConstructor, entityData);\n  return buildEntityInstance(entityConstructor, entityData);\n}\n\nfunction deserializeCollection<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  entityCollectionData: unknown,\n  failOnNull: boolean,\n): DeserializedEntity<TEntity>[] {\n  if (entityCollectionData == null && !failOnNull) {\n    return [];\n  }\n  assertEntityCollection(entityConstructor, entityCollectionData);\n\n  // Recurse into nested arrays so a collection can hold arrays of arrays,\n  // and reuse the single-entity validation/build for the leaf items.\n  return entityCollectionData.map(item =>\n    Array.isArray(item)\n      ? deserializeCollection(entityConstructor, item, failOnNull)\n      : deserializeEntity(entityConstructor, item),\n  );\n}\n\n//#endregion\n\n//#region Effect factories\n\nconst toEntifixBuildError =\n  (message: string, context: Record<string, unknown>) => (error: unknown) =>\n    error instanceof EntifixBuildError\n      ? error\n      : new EntifixBuildError(message, error, context);\n\nexport const deserializeSingleEntity = <TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  entityData: unknown,\n) =>\n  Effect.try({\n    try: () => deserializeEntity(entityConstructor, entityData),\n    catch: toEntifixBuildError(\n      `Failed to deserialize entity of type ${entityConstructor.name}`,\n      {\n        entityData,\n        entityConstructor: entityConstructor.name,\n      },\n    ),\n  });\n\nexport const deserializeEntityCollection = <TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  entityCollectionData: unknown,\n  failOnNull = false,\n) =>\n  Effect.try({\n    try: () =>\n      deserializeCollection(\n        entityConstructor,\n        entityCollectionData,\n        failOnNull,\n      ),\n    catch: toEntifixBuildError(\n      `Failed to deserialize entity collection of type ${entityConstructor.name}`,\n      {\n        entityCollectionData,\n        entityConstructor: entityConstructor.name,\n      },\n    ),\n  });\n\n//#endregion\n"],"names":["Effect","EntifixBuildError","extractMetaAccessors","EntityCollectionLink","EntityLink","assertEntityObject","entityConstructor","entityData","name","undefined","assertEntityCollection","entityCollectionData","Array","isArray","isEmbeddedData","value","populateEntityLink","link","rawValue","setValue","buildEntityInstance","setId","populateEntityCollectionLink","values","ids","item","push","length","setValues","setIds","metaAccessors","newInstance","filter","metaAccessor","hidden","readonly","kind","forEach","propertyName","alias","current","type","childType","rows","map","row","deserializeEntity","deserializeCollection","failOnNull","toEntifixBuildError","message","context","error","deserializeSingleEntity","try","catch","deserializeEntityCollection"],"mappings":"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"}

package/dist/entity-definition/serializer/index.d.ts

@@ -0,0 +1,3 @@
+export * from './deserialize.js';
+export * from './serialize.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/entity-definition/serializer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/entity-definition/serializer/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC"}

package/dist/entity-definition/serializer/index.js

@@ -0,0 +1,4 @@
+export * from './deserialize.js';
+export * from './serialize.js';
+
+//# sourceMappingURL=index.js.map

package/dist/entity-definition/serializer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/serializer/index.ts"],"sourcesContent":["export * from './deserialize.js';\nexport * from './serialize.js';\n"],"names":[],"mappings":"AAAA,cAAc,mBAAmB;AACjC,cAAc,iBAAiB"}

package/dist/entity-definition/serializer/serialize.d.ts

@@ -0,0 +1,26 @@
+import { Entity, EntityConstructor } from '../../types/Entity.js';
+/**
+ * A plain, JSON-safe representation of an entity — the inverse of
+ * {@link buildEntityInstance}. Relations collapse to the shape the deserializer
+ * expects to round-trip:
+ * - an {@link EntityLink} → the embedded plain object when loaded, otherwise the
+ *   scalar foreign-key id.
+ * - an {@link EntityCollectionLink} → an array mixing embedded objects (loaded)
+ *   or scalar ids.
+ * - a `composition` member → an array of plain child objects, each walked with
+ *   the child's own accessor metadata.
+ *
+ * This one serialization serves both persistence (entity → Mongo document) and
+ * transport (entity → HTTP wire shape), so a value written by an adapter reads
+ * back identically through {@link deserializeSingleEntity}.
+ */
+export type SerializedEntity = Record<string, unknown>;
+/**
+ * Serializes an entity instance into a plain object, walking the same accessor
+ * metadata the deserializer reads (getter-kind, not hidden/readonly), keyed by
+ * `alias ?? name`. `undefined` values are omitted so absent optionals and
+ * unresolved relations don't pollute the output.
+ */
+export declare function serializeEntity<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, instance: TEntity): SerializedEntity;
+export declare function serializeEntityCollection<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, instances: readonly TEntity[]): SerializedEntity[];
+//# sourceMappingURL=serialize.d.ts.map

package/dist/entity-definition/serializer/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/entity-definition/serializer/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAMlE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA4CvD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,MAAM,EACpD,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,QAAQ,EAAE,OAAO,GAChB,gBAAgB,CAoClB;AAED,wBAAgB,yBAAyB,CAAC,OAAO,SAAS,MAAM,EAC9D,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,SAAS,EAAE,SAAS,OAAO,EAAE,GAC5B,gBAAgB,EAAE,CAIpB"}

package/dist/entity-definition/serializer/serialize.js

@@ -0,0 +1,64 @@
+import { extractMetaAccessors } from '../helpers/index.js';
+import { EntityCollectionLink } from '../links/entity-collection-link/index.js';
+import { EntityLink } from '../links/entity-link/index.js';
+function serializeLink(link) {
+    var _link_id;
+    if (link.isLoaded && link.value !== undefined) {
+        return serializeEntity(link.entityConstructor, link.value);
+    }
+    return (_link_id = link.id) != null ? _link_id : undefined;
+}
+/**
+ * Owned rows, each flattened through the child's own accessors.
+ *
+ * A child is a class whose private fields carry its state, so passing the array
+ * through untouched would put `[{}, {}]` on the wire and in the database — the
+ * rows would silently never persist. Walking each one is also what keeps a
+ * child's `alias` meaning what it means everywhere else: its column name.
+ *
+ * It reads a plain object just as happily as an instance, which is deliberate:
+ * a row that never went through the deserializer (a fixture, a hand-built
+ * command payload) serializes to the same document.
+ */ function serializeComposition(rows, childType) {
+    return rows.map((row)=>serializeEntity(childType, row));
+}
+function serializeCollectionLink(link) {
+    if (link.isLoaded && link.values !== undefined) {
+        return link.values.map((value)=>serializeEntity(link.entityConstructor, value));
+    }
+    const ids = link.ids;
+    return ids.length > 0 ? ids : undefined;
+}
+/**
+ * Serializes an entity instance into a plain object, walking the same accessor
+ * metadata the deserializer reads (getter-kind, not hidden/readonly), keyed by
+ * `alias ?? name`. `undefined` values are omitted so absent optionals and
+ * unresolved relations don't pollute the output.
+ */ export function serializeEntity(entityConstructor, instance) {
+    const result = {};
+    extractMetaAccessors(entityConstructor).filter((metaAccessor)=>!metaAccessor.hidden && !metaAccessor.readonly && metaAccessor.kind === 'getter').forEach((metaAccessor)=>{
+        var _metaAccessor_alias;
+        const propertyName = (_metaAccessor_alias = metaAccessor.alias) != null ? _metaAccessor_alias : metaAccessor.name;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const value = instance[metaAccessor.name];
+        let serialized;
+        if (value instanceof EntityLink) {
+            serialized = serializeLink(value);
+        } else if (value instanceof EntityCollectionLink) {
+            serialized = serializeCollectionLink(value);
+        } else if (metaAccessor.type === 'composition' && metaAccessor.childType !== undefined && Array.isArray(value)) {
+            serialized = serializeComposition(value, metaAccessor.childType());
+        } else {
+            serialized = value;
+        }
+        if (serialized !== undefined) {
+            result[propertyName] = serialized;
+        }
+    });
+    return result;
+}
+export function serializeEntityCollection(entityConstructor, instances) {
+    return instances.map((instance)=>serializeEntity(entityConstructor, instance));
+}
+
+//# sourceMappingURL=serialize.js.map

package/dist/entity-definition/serializer/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/entity-definition/serializer/serialize.ts"],"sourcesContent":["import { Entity, EntityConstructor } from '../../types/Entity.js';\nimport { extractMetaAccessors } from '../helpers/index.js';\nimport { EntityCollectionLink } from '../links/entity-collection-link/index.js';\nimport { EntityLink } from '../links/entity-link/index.js';\nimport type { ChildConstructor } from '../meta-entities/meta-accessor/index.js';\n\n/**\n * A plain, JSON-safe representation of an entity — the inverse of\n * {@link buildEntityInstance}. Relations collapse to the shape the deserializer\n * expects to round-trip:\n * - an {@link EntityLink} → the embedded plain object when loaded, otherwise the\n *   scalar foreign-key id.\n * - an {@link EntityCollectionLink} → an array mixing embedded objects (loaded)\n *   or scalar ids.\n * - a `composition` member → an array of plain child objects, each walked with\n *   the child's own accessor metadata.\n *\n * This one serialization serves both persistence (entity → Mongo document) and\n * transport (entity → HTTP wire shape), so a value written by an adapter reads\n * back identically through {@link deserializeSingleEntity}.\n */\nexport type SerializedEntity = Record<string, unknown>;\n\nfunction serializeLink<TEntity extends Entity>(\n  link: EntityLink<TEntity>,\n): unknown {\n  if (link.isLoaded && link.value !== undefined) {\n    return serializeEntity(link.entityConstructor, link.value);\n  }\n  return link.id ?? undefined;\n}\n\n/**\n * Owned rows, each flattened through the child's own accessors.\n *\n * A child is a class whose private fields carry its state, so passing the array\n * through untouched would put `[{}, {}]` on the wire and in the database — the\n * rows would silently never persist. Walking each one is also what keeps a\n * child's `alias` meaning what it means everywhere else: its column name.\n *\n * It reads a plain object just as happily as an instance, which is deliberate:\n * a row that never went through the deserializer (a fixture, a hand-built\n * command payload) serializes to the same document.\n */\nfunction serializeComposition(\n  rows: readonly unknown[],\n  childType: ChildConstructor,\n): unknown {\n  return rows.map(row =>\n    serializeEntity(childType as EntityConstructor<Entity>, row as Entity),\n  );\n}\n\nfunction serializeCollectionLink<TEntity extends Entity>(\n  link: EntityCollectionLink<TEntity>,\n): unknown {\n  if (link.isLoaded && link.values !== undefined) {\n    return link.values.map(value =>\n      serializeEntity(link.entityConstructor, value),\n    );\n  }\n  const ids = link.ids;\n  return ids.length > 0 ? ids : undefined;\n}\n\n/**\n * Serializes an entity instance into a plain object, walking the same accessor\n * metadata the deserializer reads (getter-kind, not hidden/readonly), keyed by\n * `alias ?? name`. `undefined` values are omitted so absent optionals and\n * unresolved relations don't pollute the output.\n */\nexport function serializeEntity<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  instance: TEntity,\n): SerializedEntity {\n  const result: SerializedEntity = {};\n\n  extractMetaAccessors(entityConstructor)\n    .filter(\n      metaAccessor =>\n        !metaAccessor.hidden &&\n        !metaAccessor.readonly &&\n        metaAccessor.kind === 'getter',\n    )\n    .forEach(metaAccessor => {\n      const propertyName = metaAccessor.alias ?? metaAccessor.name;\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const value = (instance as any)[metaAccessor.name];\n\n      let serialized: unknown;\n      if (value instanceof EntityLink) {\n        serialized = serializeLink(value);\n      } else if (value instanceof EntityCollectionLink) {\n        serialized = serializeCollectionLink(value);\n      } else if (\n        metaAccessor.type === 'composition' &&\n        metaAccessor.childType !== undefined &&\n        Array.isArray(value)\n      ) {\n        serialized = serializeComposition(value, metaAccessor.childType());\n      } else {\n        serialized = value;\n      }\n\n      if (serialized !== undefined) {\n        result[propertyName as string] = serialized;\n      }\n    });\n\n  return result;\n}\n\nexport function serializeEntityCollection<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  instances: readonly TEntity[],\n): SerializedEntity[] {\n  return instances.map(instance =>\n    serializeEntity(entityConstructor, instance),\n  );\n}\n"],"names":["extractMetaAccessors","EntityCollectionLink","EntityLink","serializeLink","link","isLoaded","value","undefined","serializeEntity","entityConstructor","id","serializeComposition","rows","childType","map","row","serializeCollectionLink","values","ids","length","instance","result","filter","metaAccessor","hidden","readonly","kind","forEach","propertyName","alias","name","serialized","type","Array","isArray","serializeEntityCollection","instances"],"mappings":"AACA,SAASA,oBAAoB,QAAQ,sBAAsB;AAC3D,SAASC,oBAAoB,QAAQ,2CAA2C;AAChF,SAASC,UAAU,QAAQ,gCAAgC;AAoB3D,SAASC,cACPC,IAAyB;QAKlBA;IAHP,IAAIA,KAAKC,QAAQ,IAAID,KAAKE,KAAK,KAAKC,WAAW;QAC7C,OAAOC,gBAAgBJ,KAAKK,iBAAiB,EAAEL,KAAKE,KAAK;IAC3D;IACA,QAAOF,WAAAA,KAAKM,EAAE,YAAPN,WAAWG;AACpB;AAEA;;;;;;;;;;;CAWC,GACD,SAASI,qBACPC,IAAwB,EACxBC,SAA2B;IAE3B,OAAOD,KAAKE,GAAG,CAACC,CAAAA,MACdP,gBAAgBK,WAAwCE;AAE5D;AAEA,SAASC,wBACPZ,IAAmC;IAEnC,IAAIA,KAAKC,QAAQ,IAAID,KAAKa,MAAM,KAAKV,WAAW;QAC9C,OAAOH,KAAKa,MAAM,CAACH,GAAG,CAACR,CAAAA,QACrBE,gBAAgBJ,KAAKK,iBAAiB,EAAEH;IAE5C;IACA,MAAMY,MAAMd,KAAKc,GAAG;IACpB,OAAOA,IAAIC,MAAM,GAAG,IAAID,MAAMX;AAChC;AAEA;;;;;CAKC,GACD,OAAO,SAASC,gBACdC,iBAA6C,EAC7CW,QAAiB;IAEjB,MAAMC,SAA2B,CAAC;IAElCrB,qBAAqBS,mBAClBa,MAAM,CACLC,CAAAA,eACE,CAACA,aAAaC,MAAM,IACpB,CAACD,aAAaE,QAAQ,IACtBF,aAAaG,IAAI,KAAK,UAEzBC,OAAO,CAACJ,CAAAA;YACcA;QAArB,MAAMK,gBAAeL,sBAAAA,aAAaM,KAAK,YAAlBN,sBAAsBA,aAAaO,IAAI;QAC5D,8DAA8D;QAC9D,MAAMxB,QAAQ,AAACc,QAAgB,CAACG,aAAaO,IAAI,CAAC;QAElD,IAAIC;QACJ,IAAIzB,iBAAiBJ,YAAY;YAC/B6B,aAAa5B,cAAcG;QAC7B,OAAO,IAAIA,iBAAiBL,sBAAsB;YAChD8B,aAAaf,wBAAwBV;QACvC,OAAO,IACLiB,aAAaS,IAAI,KAAK,iBACtBT,aAAaV,SAAS,KAAKN,aAC3B0B,MAAMC,OAAO,CAAC5B,QACd;YACAyB,aAAapB,qBAAqBL,OAAOiB,aAAaV,SAAS;QACjE,OAAO;YACLkB,aAAazB;QACf;QAEA,IAAIyB,eAAexB,WAAW;YAC5Bc,MAAM,CAACO,aAAuB,GAAGG;QACnC;IACF;IAEF,OAAOV;AACT;AAEA,OAAO,SAASc,0BACd1B,iBAA6C,EAC7C2B,SAA6B;IAE7B,OAAOA,UAAUtB,GAAG,CAACM,CAAAA,WACnBZ,gBAAgBC,mBAAmBW;AAEvC"}

package/dist/envelope/event-pattern.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether an event name is matched by a subscription pattern, using AMQP topic
+ * semantics: `*` matches exactly one dot-separated word, `#` matches zero or
+ * more.
+ *
+ * The broker does this itself in production — a subscriber binds its pattern and
+ * never sees a non-matching message. This exists for the places that have no
+ * broker: the in-memory bus double, and any register check that has to decide
+ * whether a declared `subscriptions` entry is covered by someone's
+ * `publishedEvents`. Keeping one implementation of the semantics is what stops a
+ * test passing against a rule the real exchange applies differently.
+ */
+export declare function matchesEventPattern(pattern: string, name: string): boolean;
+//# sourceMappingURL=event-pattern.d.ts.map

package/dist/envelope/event-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-pattern.d.ts","sourceRoot":"","sources":["../../src/envelope/event-pattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAyB1E"}

package/dist/envelope/event-pattern.js

@@ -0,0 +1,30 @@
+/**
+ * Whether an event name is matched by a subscription pattern, using AMQP topic
+ * semantics: `*` matches exactly one dot-separated word, `#` matches zero or
+ * more.
+ *
+ * The broker does this itself in production — a subscriber binds its pattern and
+ * never sees a non-matching message. This exists for the places that have no
+ * broker: the in-memory bus double, and any register check that has to decide
+ * whether a declared `subscriptions` entry is covered by someone's
+ * `publishedEvents`. Keeping one implementation of the semantics is what stops a
+ * test passing against a rule the real exchange applies differently.
+ */ export function matchesEventPattern(pattern, name) {
+    const match = (patternWords, nameWords)=>{
+        if (patternWords.length === 0) {
+            return nameWords.length === 0;
+        }
+        const [head, ...rest] = patternWords;
+        if (head === '#') {
+            // Zero words, or one more consumed and `#` tried again.
+            return match(rest, nameWords) || nameWords.length > 0 && match(patternWords, nameWords.slice(1));
+        }
+        if (nameWords.length === 0) {
+            return false;
+        }
+        return (head === '*' || head === nameWords[0]) && match(rest, nameWords.slice(1));
+    };
+    return match(pattern.split('.'), name.split('.'));
+}
+
+//# sourceMappingURL=event-pattern.js.map

package/dist/envelope/event-pattern.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/envelope/event-pattern.ts"],"sourcesContent":["/**\n * Whether an event name is matched by a subscription pattern, using AMQP topic\n * semantics: `*` matches exactly one dot-separated word, `#` matches zero or\n * more.\n *\n * The broker does this itself in production — a subscriber binds its pattern and\n * never sees a non-matching message. This exists for the places that have no\n * broker: the in-memory bus double, and any register check that has to decide\n * whether a declared `subscriptions` entry is covered by someone's\n * `publishedEvents`. Keeping one implementation of the semantics is what stops a\n * test passing against a rule the real exchange applies differently.\n */\nexport function matchesEventPattern(pattern: string, name: string): boolean {\n  const match = (\n    patternWords: readonly string[],\n    nameWords: readonly string[],\n  ): boolean => {\n    if (patternWords.length === 0) {\n      return nameWords.length === 0;\n    }\n    const [head, ...rest] = patternWords;\n    if (head === '#') {\n      // Zero words, or one more consumed and `#` tried again.\n      return (\n        match(rest, nameWords) ||\n        (nameWords.length > 0 && match(patternWords, nameWords.slice(1)))\n      );\n    }\n    if (nameWords.length === 0) {\n      return false;\n    }\n    return (\n      (head === '*' || head === nameWords[0]) && match(rest, nameWords.slice(1))\n    );\n  };\n\n  return match(pattern.split('.'), name.split('.'));\n}\n"],"names":["matchesEventPattern","pattern","name","match","patternWords","nameWords","length","head","rest","slice","split"],"mappings":"AAAA;;;;;;;;;;;CAWC,GACD,OAAO,SAASA,oBAAoBC,OAAe,EAAEC,IAAY;IAC/D,MAAMC,QAAQ,CACZC,cACAC;QAEA,IAAID,aAAaE,MAAM,KAAK,GAAG;YAC7B,OAAOD,UAAUC,MAAM,KAAK;QAC9B;QACA,MAAM,CAACC,MAAM,GAAGC,KAAK,GAAGJ;QACxB,IAAIG,SAAS,KAAK;YAChB,wDAAwD;YACxD,OACEJ,MAAMK,MAAMH,cACXA,UAAUC,MAAM,GAAG,KAAKH,MAAMC,cAAcC,UAAUI,KAAK,CAAC;QAEjE;QACA,IAAIJ,UAAUC,MAAM,KAAK,GAAG;YAC1B,OAAO;QACT;QACA,OACE,AAACC,CAAAA,SAAS,OAAOA,SAASF,SAAS,CAAC,EAAE,AAAD,KAAMF,MAAMK,MAAMH,UAAUI,KAAK,CAAC;IAE3E;IAEA,OAAON,MAAMF,QAAQS,KAAK,CAAC,MAAMR,KAAKQ,KAAK,CAAC;AAC9C"}

package/dist/envelope/index.d.ts

@@ -0,0 +1,5 @@
+export * from './event-pattern.js';
+export * from './make-envelope.js';
+export * from './read-envelope.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/envelope/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC"}

package/dist/envelope/index.js

@@ -0,0 +1,6 @@
+export * from './event-pattern.js';
+export * from './make-envelope.js';
+export * from './read-envelope.js';
+export * from './types.js';
+
+//# sourceMappingURL=index.js.map

package/dist/envelope/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/envelope/index.ts"],"sourcesContent":["export * from './event-pattern.js';\nexport * from './make-envelope.js';\nexport * from './read-envelope.js';\nexport * from './types.js';\n"],"names":[],"mappings":"AAAA,cAAc,qBAAqB;AACnC,cAAc,qBAAqB;AACnC,cAAc,qBAAqB;AACnC,cAAc,aAAa"}

package/dist/envelope/make-envelope.d.ts

@@ -0,0 +1,45 @@
+import type { EntityMetadataDocument } from '../entity-definition/metadata/index.js';
+import type { Entity, EntityConstructor } from '../types/Entity.js';
+import type { EntityPage } from '../types/EntityPage.js';
+import type { DomainEvent, EntifixEnvelope, EntifixEnvelopeLink, EntifixEnvelopeType, EntityCollectionEnvelope, EntityEnvelope, EntityMetadataEnvelope, EntityPageEnvelope, EventEnvelope } from './types.js';
+/**
+ * The transport-free envelope builder for payloads that are not serialized
+ * entities — `command`/`transactionRecord` messages carry their own `data`
+ * shapes (defined by the transactions layer), so they cannot go through the
+ * entity builders. `entity` is still the routing label (`meta.entity`): the
+ * target entity's `key` for a command, or the entity/transaction subject for an
+ * event.
+ */
+export declare function makeEnvelope<TData>(type: EntifixEnvelopeType, entity: string, data: TData, links?: EntifixEnvelopeLink[]): EntifixEnvelope<TData>;
+/**
+ * The entity name carried in `meta.entity` — the same `key ?? name` resolution
+ * every adapter uses for collections and endpoints.
+ */
+export declare function envelopeEntityName<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>): string;
+export declare function makeEntityEnvelope<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, instance: TEntity, links?: EntifixEnvelopeLink[]): EntityEnvelope;
+export declare function makeEntityCollectionEnvelope<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, instances: readonly TEntity[], links?: EntifixEnvelopeLink[]): EntityCollectionEnvelope;
+export declare function makeEntityPageEnvelope<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, page: EntityPage<TEntity>, links?: EntifixEnvelopeLink[]): EntityPageEnvelope<TEntity>;
+/**
+ * The response to `GET /api/<entity>/$metadata`.
+ *
+ * Unlike its neighbours this serializes nothing: the document is already a plain
+ * shape of catalog keys and verbs, and it describes the class rather than any
+ * instance of it. `meta.entity` is still the target entity's key, which is what
+ * makes the document per entity rather than per service.
+ */
+export declare function makeEntityMetadataEnvelope<TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, document: EntityMetadataDocument, links?: EntifixEnvelopeLink[]): EntityMetadataEnvelope;
+/**
+ * Frames a domain event for the bus.
+ *
+ * The split is mechanical and worth stating: everything about the *message*
+ * (name, id, source, time, correlation) goes to `meta.event`; the payload — what
+ * actually happened — is `data`. A consumer therefore never has to reach into
+ * metadata to read its own domain object, and never has to reach into the
+ * payload to find the routing key.
+ *
+ * `meta.entity` is deliberately left unset. A bus message says what it *is* in
+ * `meta.event.name`; only the HTTP arm needs an entity label, and inventing one
+ * here would put `settlement` on a message about a settlement *run*.
+ */
+export declare function makeEventEnvelope<TData>(event: DomainEvent<TData>): EventEnvelope<TData>;
+//# sourceMappingURL=make-envelope.d.ts.map

package/dist/envelope/make-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"make-envelope.d.ts","sourceRoot":"","sources":["../../src/envelope/make-envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAKrF,OAAO,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAClB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAChC,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,KAAK,EACX,KAAK,CAAC,EAAE,mBAAmB,EAAE,GAC5B,eAAe,CAAC,KAAK,CAAC,CASxB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,MAAM,EACvD,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAC5C,MAAM,CAGR;AAED,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,MAAM,EACvD,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,QAAQ,EAAE,OAAO,EACjB,KAAK,CAAC,EAAE,mBAAmB,EAAE,GAC5B,cAAc,CAShB;AAED,wBAAgB,4BAA4B,CAAC,OAAO,SAAS,MAAM,EACjE,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,SAAS,EAAE,SAAS,OAAO,EAAE,EAC7B,KAAK,CAAC,EAAE,mBAAmB,EAAE,GAC5B,wBAAwB,CAS1B;AAED,wBAAgB,sBAAsB,CAAC,OAAO,SAAS,MAAM,EAC3D,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,EACzB,KAAK,CAAC,EAAE,mBAAmB,EAAE,GAC5B,kBAAkB,CAAC,OAAO,CAAC,CAa7B;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,SAAS,MAAM,EAC/D,iBAAiB,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAC7C,QAAQ,EAAE,sBAAsB,EAChC,KAAK,CAAC,EAAE,mBAAmB,EAAE,GAC5B,sBAAsB,CASxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,GACxB,aAAa,CAAC,KAAK,CAAC,CAMtB"}

package/dist/envelope/make-envelope.js

@@ -0,0 +1,111 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { extractMetaEntity } from '../entity-definition/helpers/index.js';
+import { serializeEntity, serializeEntityCollection } from '../entity-definition/serializer/index.js';
+/**
+ * The transport-free envelope builder for payloads that are not serialized
+ * entities — `command`/`transactionRecord` messages carry their own `data`
+ * shapes (defined by the transactions layer), so they cannot go through the
+ * entity builders. `entity` is still the routing label (`meta.entity`): the
+ * target entity's `key` for a command, or the entity/transaction subject for an
+ * event.
+ */ export function makeEnvelope(type, entity, data, links) {
+    return {
+        meta: _extends({
+            type,
+            entity
+        }, links ? {
+            links
+        } : {}),
+        data
+    };
+}
+/**
+ * The entity name carried in `meta.entity` — the same `key ?? name` resolution
+ * every adapter uses for collections and endpoints.
+ */ export function envelopeEntityName(entityConstructor) {
+    var _metaEntity_key;
+    const metaEntity = extractMetaEntity(entityConstructor);
+    return (_metaEntity_key = metaEntity.key) != null ? _metaEntity_key : metaEntity.name;
+}
+export function makeEntityEnvelope(entityConstructor, instance, links) {
+    return {
+        meta: _extends({
+            type: 'entity',
+            entity: envelopeEntityName(entityConstructor)
+        }, links ? {
+            links
+        } : {}),
+        data: serializeEntity(entityConstructor, instance)
+    };
+}
+export function makeEntityCollectionEnvelope(entityConstructor, instances, links) {
+    return {
+        meta: _extends({
+            type: 'entityCollection',
+            entity: envelopeEntityName(entityConstructor)
+        }, links ? {
+            links
+        } : {}),
+        data: serializeEntityCollection(entityConstructor, instances)
+    };
+}
+export function makeEntityPageEnvelope(entityConstructor, page, links) {
+    return {
+        meta: _extends({
+            type: 'entityPage',
+            entity: envelopeEntityName(entityConstructor)
+        }, links ? {
+            links
+        } : {}),
+        data: {
+            items: serializeEntityCollection(entityConstructor, page.items),
+            total: page.total,
+            request: page.request
+        }
+    };
+}
+/**
+ * The response to `GET /api/<entity>/$metadata`.
+ *
+ * Unlike its neighbours this serializes nothing: the document is already a plain
+ * shape of catalog keys and verbs, and it describes the class rather than any
+ * instance of it. `meta.entity` is still the target entity's key, which is what
+ * makes the document per entity rather than per service.
+ */ export function makeEntityMetadataEnvelope(entityConstructor, document, links) {
+    return {
+        meta: _extends({
+            type: 'entityMetadata',
+            entity: envelopeEntityName(entityConstructor)
+        }, links ? {
+            links
+        } : {}),
+        data: document
+    };
+}
+/**
+ * Frames a domain event for the bus.
+ *
+ * The split is mechanical and worth stating: everything about the *message*
+ * (name, id, source, time, correlation) goes to `meta.event`; the payload — what
+ * actually happened — is `data`. A consumer therefore never has to reach into
+ * metadata to read its own domain object, and never has to reach into the
+ * payload to find the routing key.
+ *
+ * `meta.entity` is deliberately left unset. A bus message says what it *is* in
+ * `meta.event.name`; only the HTTP arm needs an entity label, and inventing one
+ * here would put `settlement` on a message about a settlement *run*.
+ */ export function makeEventEnvelope(event) {
+    const { data } = event, eventMeta = _object_without_properties_loose(event, [
+        "data"
+    ]);
+    return {
+        meta: {
+            type: 'event',
+            event: eventMeta
+        },
+        data
+    };
+}
+
+//# sourceMappingURL=make-envelope.js.map

package/dist/envelope/make-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/envelope/make-envelope.ts"],"sourcesContent":["import { extractMetaEntity } from '../entity-definition/helpers/index.js';\nimport type { EntityMetadataDocument } from '../entity-definition/metadata/index.js';\nimport {\n  serializeEntity,\n  serializeEntityCollection,\n} from '../entity-definition/serializer/index.js';\nimport type { Entity, EntityConstructor } from '../types/Entity.js';\nimport type { EntityPage } from '../types/EntityPage.js';\nimport type {\n  DomainEvent,\n  EntifixEnvelope,\n  EntifixEnvelopeLink,\n  EntifixEnvelopeType,\n  EntityCollectionEnvelope,\n  EntityEnvelope,\n  EntityMetadataEnvelope,\n  EntityPageEnvelope,\n  EventEnvelope,\n} from './types.js';\n\n/**\n * The transport-free envelope builder for payloads that are not serialized\n * entities — `command`/`transactionRecord` messages carry their own `data`\n * shapes (defined by the transactions layer), so they cannot go through the\n * entity builders. `entity` is still the routing label (`meta.entity`): the\n * target entity's `key` for a command, or the entity/transaction subject for an\n * event.\n */\nexport function makeEnvelope<TData>(\n  type: EntifixEnvelopeType,\n  entity: string,\n  data: TData,\n  links?: EntifixEnvelopeLink[],\n): EntifixEnvelope<TData> {\n  return {\n    meta: {\n      type,\n      entity,\n      ...(links ? { links } : {}),\n    },\n    data,\n  };\n}\n\n/**\n * The entity name carried in `meta.entity` — the same `key ?? name` resolution\n * every adapter uses for collections and endpoints.\n */\nexport function envelopeEntityName<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n): string {\n  const metaEntity = extractMetaEntity(entityConstructor);\n  return metaEntity.key ?? metaEntity.name;\n}\n\nexport function makeEntityEnvelope<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  instance: TEntity,\n  links?: EntifixEnvelopeLink[],\n): EntityEnvelope {\n  return {\n    meta: {\n      type: 'entity',\n      entity: envelopeEntityName(entityConstructor),\n      ...(links ? { links } : {}),\n    },\n    data: serializeEntity(entityConstructor, instance),\n  };\n}\n\nexport function makeEntityCollectionEnvelope<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  instances: readonly TEntity[],\n  links?: EntifixEnvelopeLink[],\n): EntityCollectionEnvelope {\n  return {\n    meta: {\n      type: 'entityCollection',\n      entity: envelopeEntityName(entityConstructor),\n      ...(links ? { links } : {}),\n    },\n    data: serializeEntityCollection(entityConstructor, instances),\n  };\n}\n\nexport function makeEntityPageEnvelope<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  page: EntityPage<TEntity>,\n  links?: EntifixEnvelopeLink[],\n): EntityPageEnvelope<TEntity> {\n  return {\n    meta: {\n      type: 'entityPage',\n      entity: envelopeEntityName(entityConstructor),\n      ...(links ? { links } : {}),\n    },\n    data: {\n      items: serializeEntityCollection(entityConstructor, page.items),\n      total: page.total,\n      request: page.request,\n    },\n  };\n}\n\n/**\n * The response to `GET /api/<entity>/$metadata`.\n *\n * Unlike its neighbours this serializes nothing: the document is already a plain\n * shape of catalog keys and verbs, and it describes the class rather than any\n * instance of it. `meta.entity` is still the target entity's key, which is what\n * makes the document per entity rather than per service.\n */\nexport function makeEntityMetadataEnvelope<TEntity extends Entity>(\n  entityConstructor: EntityConstructor<TEntity>,\n  document: EntityMetadataDocument,\n  links?: EntifixEnvelopeLink[],\n): EntityMetadataEnvelope {\n  return {\n    meta: {\n      type: 'entityMetadata',\n      entity: envelopeEntityName(entityConstructor),\n      ...(links ? { links } : {}),\n    },\n    data: document,\n  };\n}\n\n/**\n * Frames a domain event for the bus.\n *\n * The split is mechanical and worth stating: everything about the *message*\n * (name, id, source, time, correlation) goes to `meta.event`; the payload — what\n * actually happened — is `data`. A consumer therefore never has to reach into\n * metadata to read its own domain object, and never has to reach into the\n * payload to find the routing key.\n *\n * `meta.entity` is deliberately left unset. A bus message says what it *is* in\n * `meta.event.name`; only the HTTP arm needs an entity label, and inventing one\n * here would put `settlement` on a message about a settlement *run*.\n */\nexport function makeEventEnvelope<TData>(\n  event: DomainEvent<TData>,\n): EventEnvelope<TData> {\n  const { data, ...eventMeta } = event;\n  return {\n    meta: { type: 'event', event: eventMeta },\n    data,\n  };\n}\n"],"names":["extractMetaEntity","serializeEntity","serializeEntityCollection","makeEnvelope","type","entity","data","links","meta","envelopeEntityName","entityConstructor","metaEntity","key","name","makeEntityEnvelope","instance","makeEntityCollectionEnvelope","instances","makeEntityPageEnvelope","page","items","total","request","makeEntityMetadataEnvelope","document","makeEventEnvelope","event","eventMeta"],"mappings":";;AAAA,SAASA,iBAAiB,QAAQ,wCAAwC;AAE1E,SACEC,eAAe,EACfC,yBAAyB,QACpB,2CAA2C;AAelD;;;;;;;CAOC,GACD,OAAO,SAASC,aACdC,IAAyB,EACzBC,MAAc,EACdC,IAAW,EACXC,KAA6B;IAE7B,OAAO;QACLC,MAAM;YACJJ;YACAC;WACIE,QAAQ;YAAEA;QAAM,IAAI,CAAC;QAE3BD;IACF;AACF;AAEA;;;CAGC,GACD,OAAO,SAASG,mBACdC,iBAA6C;QAGtCC;IADP,MAAMA,aAAaX,kBAAkBU;IACrC,QAAOC,kBAAAA,WAAWC,GAAG,YAAdD,kBAAkBA,WAAWE,IAAI;AAC1C;AAEA,OAAO,SAASC,mBACdJ,iBAA6C,EAC7CK,QAAiB,EACjBR,KAA6B;IAE7B,OAAO;QACLC,MAAM;YACJJ,MAAM;YACNC,QAAQI,mBAAmBC;WACvBH,QAAQ;YAAEA;QAAM,IAAI,CAAC;QAE3BD,MAAML,gBAAgBS,mBAAmBK;IAC3C;AACF;AAEA,OAAO,SAASC,6BACdN,iBAA6C,EAC7CO,SAA6B,EAC7BV,KAA6B;IAE7B,OAAO;QACLC,MAAM;YACJJ,MAAM;YACNC,QAAQI,mBAAmBC;WACvBH,QAAQ;YAAEA;QAAM,IAAI,CAAC;QAE3BD,MAAMJ,0BAA0BQ,mBAAmBO;IACrD;AACF;AAEA,OAAO,SAASC,uBACdR,iBAA6C,EAC7CS,IAAyB,EACzBZ,KAA6B;IAE7B,OAAO;QACLC,MAAM;YACJJ,MAAM;YACNC,QAAQI,mBAAmBC;WACvBH,QAAQ;YAAEA;QAAM,IAAI,CAAC;QAE3BD,MAAM;YACJc,OAAOlB,0BAA0BQ,mBAAmBS,KAAKC,KAAK;YAC9DC,OAAOF,KAAKE,KAAK;YACjBC,SAASH,KAAKG,OAAO;QACvB;IACF;AACF;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,2BACdb,iBAA6C,EAC7Cc,QAAgC,EAChCjB,KAA6B;IAE7B,OAAO;QACLC,MAAM;YACJJ,MAAM;YACNC,QAAQI,mBAAmBC;WACvBH,QAAQ;YAAEA;QAAM,IAAI,CAAC;QAE3BD,MAAMkB;IACR;AACF;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASC,kBACdC,KAAyB;IAEzB,MAAM,EAAEpB,IAAI,EAAgB,GAAGoB,OAAdC,6CAAcD;;;IAC/B,OAAO;QACLlB,MAAM;YAAEJ,MAAM;YAASsB,OAAOC;QAAU;QACxCrB;IACF;AACF"}

package/dist/envelope/read-envelope.d.ts

@@ -0,0 +1,48 @@
+import { Effect } from 'effect';
+import { EntifixBuildError } from '../base-entities/entifix-error/index.js';
+import type { EntityMetadataDocument } from '../entity-definition/metadata/index.js';
+import type { Entity, EntityConstructor } from '../types/Entity.js';
+import type { DomainEvent, EntifixEnvelope, EntifixEnvelopeType } from './types.js';
+/**
+ * Structural check only — `meta.type` is validated separately so a mismatch
+ * reports the expected/actual types rather than a generic "not an envelope".
+ */
+export declare function isEntifixEnvelope(body: unknown): body is EntifixEnvelope;
+/**
+ * Narrows an arbitrary body to an envelope of the expected `meta.type` without
+ * requiring an entity constructor — for `command`/`transactionRecord` messages
+ * whose `data` is not a serialized entity. `label` only sharpens error text.
+ */
+export declare function readEnvelope<TData>(body: unknown, expected: EntifixEnvelopeType, label?: string): Effect.Effect<EntifixEnvelope<TData>, EntifixBuildError>;
+export declare const readEntityEnvelope: <TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, body: unknown) => Effect.Effect<TEntity, EntifixBuildError, never>;
+export declare const readEntityCollectionEnvelope: <TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, body: unknown) => Effect.Effect<TEntity[], EntifixBuildError, never>;
+export declare const readEntityPageEnvelope: <TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, body: unknown) => Effect.Effect<{
+    items: TEntity[];
+    total: number;
+    request: import("../index.js").EntityLoadRequest<TEntity>;
+}, EntifixBuildError, never>;
+/**
+ * Reads a `$metadata` response back into its document.
+ *
+ * No deserialization step, and no defaulting of the members either: an envelope
+ * whose `data` is missing a list would leave a form guessing whether "no
+ * actions" meant "denied" or "malformed", so a broken payload fails loudly here
+ * the way a half-populated entity does.
+ */
+export declare const readEntityMetadataEnvelope: <TEntity extends Entity>(entityConstructor: EntityConstructor<TEntity>, body: unknown) => Effect.Effect<EntityMetadataDocument, EntifixBuildError, never>;
+/**
+ * Reads a bus message back into a {@link DomainEvent}.
+ *
+ * The metadata is validated rather than defaulted, and that is the point: a
+ * message missing `id` cannot be deduplicated and a message missing `name`
+ * cannot be routed, so both are failures a consumer must see rather than
+ * absences it silently works around. It is the same call
+ * {@link readEntityMetadataEnvelope} makes — a broken payload fails loudly
+ * instead of arriving half-populated.
+ *
+ * Note this does not validate `data`. The transport has no idea what a
+ * `catalog.published` payload should look like, and inventing an opinion here
+ * is how the bus would start knowing about domains.
+ */
+export declare function readEventEnvelope<TData = unknown>(body: unknown): Effect.Effect<DomainEvent<TData>, EntifixBuildError>;
+//# sourceMappingURL=read-envelope.d.ts.map

package/dist/envelope/read-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-envelope.d.ts","sourceRoot":"","sources":["../../src/envelope/read-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAC5E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAKrF,OAAO,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGpE,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,mBAAmB,EAGpB,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,eAAe,CAQxE;AAmCD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAChC,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,SAAY,GAChB,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC,CAoB1D;AAED,eAAO,MAAM,kBAAkB,GAAI,OAAO,SAAS,MAAM,EACvD,mBAAmB,iBAAiB,CAAC,OAAO,CAAC,EAC7C,MAAM,OAAO,qDAwBX,CAAC;AAEL,eAAO,MAAM,4BAA4B,GAAI,OAAO,SAAS,MAAM,EACjE,mBAAmB,iBAAiB,CAAC,OAAO,CAAC,EAC7C,MAAM,OAAO,uDAaX,CAAC;AAEL,eAAO,MAAM,sBAAsB,GAAI,OAAO,SAAS,MAAM,EAC3D,mBAAmB,iBAAiB,CAAC,OAAO,CAAC,EAC7C,MAAM,OAAO;WAYO,OAAO,EAAE;;;4BAI3B,CAAC;AAEL;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GAAI,OAAO,SAAS,MAAM,EAC/D,mBAAmB,iBAAiB,CAAC,OAAO,CAAC,EAC7C,MAAM,OAAO,oEAwBX,CAAC;AAKL;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAG,OAAO,EAC/C,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC,CAoBtD"}