hexok 1.0.0

package/dist/domain/cow-draft.js

@@ -0,0 +1,147 @@
+const DRAFT = Symbol('hexok.cow');
+export function isPlainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value) || value instanceof Date)
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function isCowNode(value) {
+    return isPlainObject(value) || Array.isArray(value);
+}
+export function applyCowDraft(root, owned, producer) {
+    const copies = new WeakMap();
+    const proxies = new WeakMap();
+    const parents = new WeakMap();
+    const nextOwned = owned ?? new WeakSet();
+    let wrote = false;
+    let currentRoot = root;
+    const sourceOf = (obj) => copies.get(obj) ?? obj;
+    const dest = (obj, asWrite = true) => {
+        const copied = copies.get(obj);
+        if (copied)
+            return copied;
+        if (nextOwned.has(obj) && !Object.isFrozen(obj))
+            return obj;
+        if (asWrite)
+            wrote = true;
+        const clone = (Array.isArray(obj) ? obj.slice() : { ...obj });
+        copies.set(obj, clone);
+        nextOwned.add(clone);
+        const link = parents.get(obj);
+        if (link) {
+            const parentDest = dest(link.parent, asWrite);
+            parentDest[link.key] = clone;
+        }
+        else {
+            currentRoot = clone;
+        }
+        return clone;
+    };
+    const unwrap = (value) => {
+        if (value !== null && typeof value === 'object') {
+            const raw = value[DRAFT];
+            if (raw !== undefined)
+                return raw;
+        }
+        return value;
+    };
+    const wrap = (obj) => {
+        const existing = proxies.get(obj);
+        if (existing)
+            return existing;
+        // Frozen objects cannot be proxy targets: non-writable, non-configurable
+        // keys reject a nested draft proxy (get) and a differing assignment (set).
+        const target = Object.isFrozen(obj) ? dest(obj, false) : obj;
+        const proxy = new Proxy(target, handler);
+        proxies.set(obj, proxy);
+        if (target !== obj)
+            proxies.set(target, proxy);
+        return proxy;
+    };
+    const handler = {
+        get(target, key) {
+            if (key === DRAFT)
+                return sourceOf(target);
+            const value = Reflect.get(sourceOf(target), key);
+            if (isCowNode(value)) {
+                parents.set(value, { parent: target, key });
+                return wrap(value);
+            }
+            return value;
+        },
+        set(target, key, value) {
+            wrote = true;
+            const next = unwrap(value);
+            const targetDest = dest(target);
+            targetDest[key] = next;
+            if (isCowNode(next))
+                nextOwned.add(next);
+            return true;
+        },
+        deleteProperty(target, key) {
+            wrote = true;
+            return Reflect.deleteProperty(dest(target), key);
+        },
+        has(target, key) {
+            return Reflect.has(sourceOf(target), key);
+        },
+        ownKeys(target) {
+            return Reflect.ownKeys(sourceOf(target));
+        },
+        getOwnPropertyDescriptor(target, key) {
+            return Reflect.getOwnPropertyDescriptor(sourceOf(target), key);
+        },
+        defineProperty(target, key, attributes) {
+            wrote = true;
+            return Reflect.defineProperty(dest(target), key, attributes);
+        },
+    };
+    producer(wrap(root));
+    if (!wrote)
+        return { root, owned, wrote: false };
+    return { root: currentRoot, owned: nextOwned, wrote: true };
+}
+export function frozenSnapshot(value) {
+    return deepFreeze(deepClone(value));
+}
+/** Unfrozen deep clone of plain objects, arrays, and `Date`. */
+export function cloneValue(value) {
+    return deepClone(value);
+}
+function deepClone(value) {
+    if (value instanceof Date)
+        return new Date(value.getTime());
+    if (Array.isArray(value)) {
+        return value.map((item) => deepClone(item));
+    }
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const key of Object.keys(value)) {
+            out[key] = deepClone(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+function deepFreeze(value) {
+    if (value instanceof Date) {
+        Object.freeze(value);
+        return value;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            deepFreeze(item);
+        Object.freeze(value);
+        return value;
+    }
+    if (isPlainObject(value)) {
+        for (const key of Object.keys(value)) {
+            deepFreeze(value[key]);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+//# sourceMappingURL=cow-draft.js.map

package/dist/domain/cow-draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cow-draft.js","sourceRoot":"","sources":["../../src/domain/cow-draft.ts"],"names":[],"mappings":"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"}

package/dist/domain/entity.d.ts

@@ -0,0 +1,120 @@
+import { type ErrorMap, type Infer, type StandardSchemaV1 } from '../core/index.js';
+/** Recursively readonly view of entity props. `Date` values stay `Date`. */
+export type DeepReadonly<T> = T extends Date ? T : T extends readonly (infer U)[] ? ReadonlyArray<DeepReadonly<U>> : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/**
+ * Aggregates mutate **this** via `set` and return `this`.
+ * They never I/O, never publish, never hold ports.
+ *
+ * Validation, invariants, and declared refusals **throw**.
+ * `create` / `parse` run the schema. `restore` does not — it rehydrates
+ * mapper output as-is. `set` re-runs the schema after a write.
+ * `validate()` is the optional fail-fast for a restored instance.
+ *
+ * ```ts
+ * class Incident extends Entity<IncidentProps> {
+ *   static readonly key = 'Incident'
+ *   static readonly schema = z.object({ id: z.string(), status: z.enum(['open', 'closed']) })
+ *   static readonly errors = { ALREADY_CLOSED: { message: 'Incident already closed' } } as const
+ *   close(now: Date): this {
+ *     if (this.props.status === 'closed') Incident.error('ALREADY_CLOSED')
+ *     return this.set((draft) => {
+ *       draft.status = 'closed'
+ *       draft.closedAt = now
+ *     })
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class Entity<P extends object> {
+    #private;
+    /** Entity name used in validation and undeclared-error messages. Declare on each subclass. */
+    static readonly key: string;
+    /** Standard Schema for `create` / `parse` / `set` / `validate()`. Declare on each subclass. */
+    static readonly schema: StandardSchemaV1;
+    /** Declared refusal codes. Keys are the `error()` union. Declare on each subclass. */
+    static readonly errors: ErrorMap;
+    protected _props: P;
+    /** Live props. Read-only; write through `set`. */
+    get props(): DeepReadonly<P>;
+    /** True after `create` until `commit`. `restore` / `parse` start false. */
+    get isNew(): boolean;
+    /**
+     * True after `create`, `parse`, a writing `set`, or `validate()`.
+     * `restore` starts false — the schema has not run.
+     */
+    get isValidated(): boolean;
+    /**
+     * Pre-mutation props after the first `set` on a restored entity.
+     * `undefined` when same-ref (clean) or `create`d and never `commit`ted.
+     */
+    get original(): DeepReadonly<P> | undefined;
+    protected constructor(props: P);
+    /** Copy-on-write mutate. Edit `draft` and return `this`. Re-validates the schema after a write. */
+    set(producer: (draft: P) => void): this;
+    /**
+     * Run the schema if it has not already passed on this instance.
+     * No-op when `isValidated`. Does not rewrite props (no strip/defaults).
+     * Throws `CodedError` `VALIDATION` if the schema rejects current props.
+     */
+    validate(): this;
+    /** Shallow keys that differ from `original`. `{ deep: true }` returns dotted leaf paths. */
+    getChangedKeys(): Array<ChangedKey<P>>;
+    getChangedKeys(opts: {
+        deep: true;
+    }): string[];
+    getChangedKeys(opts?: {
+        deep?: boolean;
+    }): string[];
+    /** True when `create`d and not yet `commit`ted, or any shallow key changed. */
+    isDirty(): boolean;
+    /** Accept current props as original; `isNew` becomes false. Adapters after persist; not use-cases. */
+    commit(): this;
+    /** Deep frozen snapshot for persistence and use-case output. Reused until the next `set`. */
+    toProps(): DeepReadonly<P>;
+    /** JSON serialization is the plain props snapshot. */
+    toJSON(): DeepReadonly<P>;
+    /**
+     * Throw a declared entity error. Codes are the keys of the subclass
+     * `static errors` when called as `Incident.error('ALREADY_CLOSED')`.
+     * An undeclared code is a type error on that call, and a programming
+     * error at runtime.
+     */
+    static error<E extends object, K extends keyof E & string>(this: {
+        errors: E;
+        key: string;
+    }, code: K, data?: unknown): never;
+    /**
+     * Validate typed props and construct a new instance (`isNew: true`).
+     * Throws `CodedError` `VALIDATION` if the schema rejects the props.
+     */
+    static create<T extends EntityConstructor>(this: T, props: SchemaOutput<T> | DeepReadonly<SchemaOutput<T>>): T['prototype'];
+    /**
+     * Reconstruct an existing instance (`isNew: false`) without running the
+     * schema. Props are stored as given (no strip/defaults). `isValidated`
+     * starts false until `set` writes or `validate()` runs.
+     */
+    static restore<T extends EntityConstructor>(this: T, props: SchemaOutput<T> | DeepReadonly<SchemaOutput<T>>): T['prototype'];
+    /**
+     * Trust boundary for untyped input. Validates like `create`;
+     * tracking matches `restore` (`isNew: false`).
+     * Throws `CodedError` `VALIDATION` if the schema rejects the value.
+     */
+    static parse<T extends EntityConstructor>(this: T, value: unknown): T['prototype'];
+}
+/** Subclass constructor shape for `create` / `restore` / `parse`. */
+export type EntityConstructor = {
+    /** Entity name used in validation and error messages. */
+    readonly key: string;
+    /** Standard Schema for `create` / `parse` / `set` / `validate()`. Declare on each subclass. */
+    readonly schema: StandardSchemaV1;
+    /** Declared refusal codes. Keys are the `error()` union. Declare on each subclass. */
+    readonly errors: ErrorMap;
+    readonly prototype: Entity<any>;
+};
+type SchemaOutput<T extends EntityConstructor> = Infer<T['schema']>;
+/** `keyof object` is `never`; widen so `Entity<P>` stays assignable to `Entity<object>`. */
+type ChangedKey<P extends object> = keyof P extends never ? string : keyof P & string;
+export {};
+//# sourceMappingURL=entity.d.ts.map

package/dist/domain/entity.d.ts.map

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

package/dist/domain/entity.js

@@ -0,0 +1,263 @@
+import { CodedError, validate, validationError, } from '../core/index.js';
+import { applyCowDraft, cloneValue, frozenSnapshot, isPlainObject, } from './cow-draft.js';
+const EMPTY_CHANGED_KEYS = Object.freeze([]);
+/**
+ * Aggregates mutate **this** via `set` and return `this`.
+ * They never I/O, never publish, never hold ports.
+ *
+ * Validation, invariants, and declared refusals **throw**.
+ * `create` / `parse` run the schema. `restore` does not — it rehydrates
+ * mapper output as-is. `set` re-runs the schema after a write.
+ * `validate()` is the optional fail-fast for a restored instance.
+ *
+ * ```ts
+ * class Incident extends Entity<IncidentProps> {
+ *   static readonly key = 'Incident'
+ *   static readonly schema = z.object({ id: z.string(), status: z.enum(['open', 'closed']) })
+ *   static readonly errors = { ALREADY_CLOSED: { message: 'Incident already closed' } } as const
+ *   close(now: Date): this {
+ *     if (this.props.status === 'closed') Incident.error('ALREADY_CLOSED')
+ *     return this.set((draft) => {
+ *       draft.status = 'closed'
+ *       draft.closedAt = now
+ *     })
+ *   }
+ * }
+ * ```
+ */
+export class Entity {
+    /** Entity name used in validation and undeclared-error messages. Declare on each subclass. */
+    static key;
+    /** Standard Schema for `create` / `parse` / `set` / `validate()`. Declare on each subclass. */
+    static schema;
+    /** Declared refusal codes. Keys are the `error()` union. Declare on each subclass. */
+    static errors;
+    #isNew = false;
+    #validated = false;
+    #original = undefined;
+    #owned = undefined;
+    #snapshot = undefined;
+    _props;
+    /** Live props. Read-only; write through `set`. */
+    get props() {
+        return this._props;
+    }
+    /** True after `create` until `commit`. `restore` / `parse` start false. */
+    get isNew() {
+        return this.#isNew;
+    }
+    /**
+     * True after `create`, `parse`, a writing `set`, or `validate()`.
+     * `restore` starts false — the schema has not run.
+     */
+    get isValidated() {
+        return this.#validated;
+    }
+    /**
+     * Pre-mutation props after the first `set` on a restored entity.
+     * `undefined` when same-ref (clean) or `create`d and never `commit`ted.
+     */
+    get original() {
+        if (this.#original === undefined ||
+            Object.is(this._props, this.#original)) {
+            return undefined;
+        }
+        return this.#original;
+    }
+    constructor(props) {
+        this._props = props;
+    }
+    /** Copy-on-write mutate. Edit `draft` and return `this`. Re-validates the schema after a write. */
+    set(producer) {
+        const previousRoot = this._props;
+        const backup = cloneValue(this._props);
+        const previousSnapshot = this.#snapshot;
+        const wasOwned = this.#owned?.has(this._props) === true;
+        const result = applyCowDraft(this._props, this.#owned, producer);
+        this._props = result.root;
+        this.#owned = result.owned;
+        if (result.wrote) {
+            this.#snapshot = undefined;
+            try {
+                this.#assertSchema();
+            }
+            catch (error) {
+                this._props = wasOwned ? backup : previousRoot;
+                this.#owned = wasOwned ? new WeakSet([backup]) : undefined;
+                this.#snapshot = previousSnapshot;
+                throw error;
+            }
+            this.#validated = true;
+        }
+        return this;
+    }
+    /**
+     * Run the schema if it has not already passed on this instance.
+     * No-op when `isValidated`. Does not rewrite props (no strip/defaults).
+     * Throws `CodedError` `VALIDATION` if the schema rejects current props.
+     */
+    validate() {
+        if (this.#validated)
+            return this;
+        this.#assertSchema();
+        this.#validated = true;
+        return this;
+    }
+    getChangedKeys(opts) {
+        if (!this.#isNew &&
+            (this.#original === undefined || Object.is(this._props, this.#original))) {
+            return EMPTY_CHANGED_KEYS;
+        }
+        if (opts?.deep) {
+            const out = [];
+            diffDeep(this._props, this.#isNew ? undefined : this.#original, '', out);
+            return out.length === 0 ? EMPTY_CHANGED_KEYS : out;
+        }
+        if (this.#isNew) {
+            return Object.keys(this._props);
+        }
+        const current = this._props;
+        const original = this.#original;
+        const keys = new Set([
+            ...Object.keys(current),
+            ...Object.keys(original),
+        ]);
+        const changed = [];
+        for (const key of keys) {
+            const k = key;
+            if (!Object.is(current[k], original[k]))
+                changed.push(key);
+        }
+        return changed.length === 0 ? EMPTY_CHANGED_KEYS : changed;
+    }
+    /** True when `create`d and not yet `commit`ted, or any shallow key changed. */
+    isDirty() {
+        return this.#isNew || this.getChangedKeys().length > 0;
+    }
+    /** Accept current props as original; `isNew` becomes false. Adapters after persist; not use-cases. */
+    commit() {
+        this.#original = this._props;
+        this.#isNew = false;
+        this.#owned = undefined;
+        return this;
+    }
+    /** Deep frozen snapshot for persistence and use-case output. Reused until the next `set`. */
+    toProps() {
+        if (this.#snapshot === undefined) {
+            this.#snapshot = frozenSnapshot(this._props);
+        }
+        return this.#snapshot;
+    }
+    /** JSON serialization is the plain props snapshot. */
+    toJSON() {
+        return this.toProps();
+    }
+    /**
+     * Throw a declared entity error. Codes are the keys of the subclass
+     * `static errors` when called as `Incident.error('ALREADY_CLOSED')`.
+     * An undeclared code is a type error on that call, and a programming
+     * error at runtime.
+     */
+    static error(code, data) {
+        throwEntityError(this, code, data);
+    }
+    /**
+     * Validate typed props and construct a new instance (`isNew: true`).
+     * Throws `CodedError` `VALIDATION` if the schema rejects the props.
+     */
+    static create(props) {
+        const instance = instantiate(this, props);
+        instance.#markNew();
+        instance.#validated = true;
+        return instance;
+    }
+    /**
+     * Reconstruct an existing instance (`isNew: false`) without running the
+     * schema. Props are stored as given (no strip/defaults). `isValidated`
+     * starts false until `set` writes or `validate()` runs.
+     */
+    static restore(props) {
+        const instance = construct(this, props);
+        instance.#markRestored();
+        return instance;
+    }
+    /**
+     * Trust boundary for untyped input. Validates like `create`;
+     * tracking matches `restore` (`isNew: false`).
+     * Throws `CodedError` `VALIDATION` if the schema rejects the value.
+     */
+    static parse(value) {
+        const instance = instantiate(this, value);
+        instance.#markRestored();
+        instance.#validated = true;
+        return instance;
+    }
+    #markNew() {
+        this._props = { ...this._props };
+        this.#original = undefined;
+        this.#isNew = true;
+        this.#owned = new WeakSet();
+        this.#owned.add(this._props);
+        this.#snapshot = undefined;
+    }
+    #markRestored() {
+        this.#original = this._props;
+        this.#isNew = false;
+        this.#owned = undefined;
+        this.#snapshot = undefined;
+    }
+    #assertSchema() {
+        const Ctor = this.constructor;
+        const parsed = validate(Ctor.schema, this._props);
+        if (!parsed.ok) {
+            throw validationError(`hexok: ${Ctor.key} validation failed`, parsed.issues);
+        }
+    }
+}
+function instantiate(Ctor, value) {
+    const parsed = validate(Ctor.schema, value);
+    if (!parsed.ok) {
+        throw validationError(`hexok: ${Ctor.key} validation failed`, parsed.issues);
+    }
+    return construct(Ctor, parsed.value);
+}
+function construct(Ctor, value) {
+    const CtorImpl = Ctor;
+    return new CtorImpl(value);
+}
+function diffDeep(current, original, path, out) {
+    if (Object.is(current, original))
+        return;
+    const currentPlain = isPlainObject(current);
+    const originalPlain = isPlainObject(original);
+    if (currentPlain || originalPlain) {
+        const keys = new Set([
+            ...(currentPlain ? Object.keys(current) : []),
+            ...(originalPlain ? Object.keys(original) : []),
+        ]);
+        if (keys.size === 0) {
+            if (path)
+                out.push(path);
+            return;
+        }
+        for (const key of keys) {
+            const next = path ? `${path}.${key}` : key;
+            diffDeep(currentPlain ? current[key] : undefined, originalPlain ? original[key] : undefined, next, out);
+        }
+        return;
+    }
+    if (path)
+        out.push(path);
+}
+function throwEntityError(ctor, code, data) {
+    const def = ctor.errors[code];
+    if (def === undefined) {
+        throw new Error(`hexok: undeclared error "${code}" on ${ctor.key}`);
+    }
+    throw new CodedError({
+        code,
+        message: def.message ?? code,
+        ...(data !== undefined ? { data } : {}),
+    });
+}
+//# sourceMappingURL=entity.js.map

package/dist/domain/entity.js.map

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

package/dist/domain/envelope.d.ts

@@ -0,0 +1,59 @@
+/** `'bus'` is fan-out; `'queue'` is competing consumers with ack/nack. */
+export type CatalogKind = 'bus' | 'queue';
+/**
+ * Runtime value on the wire. `kind` is copied from the catalog.
+ */
+export type Envelope<K extends string = string, P = unknown, Cat extends string = string, Kind extends CatalogKind = CatalogKind, Ctx = unknown> = {
+    /** Event class key, e.g. `'incident.closed'`. */
+    key: K;
+    /** Event payload. */
+    payload: P;
+    /** Catalog name this event was published through. */
+    catalog: Cat;
+    /** Copied from the catalog: `'bus'` or `'queue'`. */
+    kind: Kind;
+    /** When the event was wrapped for the wire. */
+    occurredAt: Date;
+    /** Catalog ctx when `.ctx()` was declared; omitted otherwise. */
+    ctx?: Ctx;
+    /** Copied from request ctx when that field is a string. */
+    correlationId?: string;
+    /** Copied from request ctx when that field is a string. */
+    causationId?: string;
+    /** Adapter/interceptor scratch. Hexok writes `{}`; domain code should not. */
+    meta: Record<string, unknown>;
+};
+/** Fire-and-forget pub/sub. No ack, no consumer group, no persistence in the contract. */
+export interface BusAdapter {
+    /** Discriminant. Must be `'bus'`. */
+    kind: 'bus';
+    /** Put one envelope on the bus. */
+    publish(envelope: Envelope): Promise<void>;
+    /** Register a handler for one event key. */
+    subscribe(key: string, handler: (envelope: Envelope) => Promise<void>): void;
+    /** Tear down the adapter. Optional. */
+    stop?(): Promise<void>;
+}
+/** Ack/nack and delivery attempt for one queue message. */
+export interface QueueConsumeCtx {
+    /** 1-based delivery attempt. */
+    attempt: number;
+    /** Mark this delivery succeeded. */
+    ack: () => Promise<void>;
+    /** Reject this delivery so it can retry. */
+    nack: () => Promise<void>;
+}
+/** Work queue. One consumer in a group; ack/nack; `attempt`. */
+export interface QueueAdapter {
+    /** Discriminant. Must be `'queue'`. */
+    kind: 'queue';
+    /** Put one envelope on the queue. */
+    publish(envelope: Envelope): Promise<void>;
+    /** Register a competing consumer for one event key in `group`. */
+    consume(key: string, group: string, handler: (envelope: Envelope, ctx: QueueConsumeCtx) => Promise<void>): void;
+    /** Tear down the adapter. Optional. */
+    stop?(): Promise<void>;
+}
+/** Bound event transport: a bus or a queue. */
+export type EventAdapter = BusAdapter | QueueAdapter;
+//# sourceMappingURL=envelope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/domain/envelope.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,OAAO,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,QAAQ,CAClB,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,CAAC,GAAG,OAAO,EACX,GAAG,SAAS,MAAM,GAAG,MAAM,EAC3B,IAAI,SAAS,WAAW,GAAG,WAAW,EACtC,GAAG,GAAG,OAAO,IACX;IACF,iDAAiD;IACjD,GAAG,EAAE,CAAC,CAAC;IACP,qBAAqB;IACrB,OAAO,EAAE,CAAC,CAAC;IACX,qDAAqD;IACrD,OAAO,EAAE,GAAG,CAAC;IACb,qDAAqD;IACrD,IAAI,EAAE,IAAI,CAAC;IACX,+CAA+C;IAC/C,UAAU,EAAE,IAAI,CAAC;IACjB,iEAAiE;IACjE,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,CAAC;AAEF,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,IAAI,EAAE,KAAK,CAAC;IACZ,mCAAmC;IACnC,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,4CAA4C;IAC5C,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7E,uCAAuC;IACvC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,IAAI,EAAE,OAAO,CAAC;IACd,qCAAqC;IACrC,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,kEAAkE;IAClE,OAAO,CACL,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GACnE,IAAI,CAAC;IACR,uCAAuC;IACvC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC"}

package/dist/domain/envelope.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=envelope.js.map

package/dist/domain/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/domain/envelope.ts"],"names":[],"mappings":""}