@salsita-ai/sdk 0.50.0-develop.d81d7591c5 → 0.50.0-develop.d9534cf412

package/dist/domain/core/index.d.ts

@@ -1,16 +1,14 @@
-export * from './schema/index.js';
-export type { ActionContext, ActionDefinition, ActionDefinitions, ActionImplementation, ActionImplementations, ActionStateChange, ActionTypes, AnyActionContext, AnyActionImplementation, AnyActionImplementations, PreparedAction, } from './action.js';
-export { _unsafeBuildDomainEntityId, domainEntityTypeFromId, createVirtualEntityId, isDomainEntityId, isVirtualEntityId, VirtualEntityIdSchema, isEqualEntityTypeAndId, parseDomainEntityId, DomainEntityIdSchema, DomainEntitySchema, $DomainEntitySchema, } from './model.js';
-export type { $DomainEntity, DomainEntity, VirtualEntityId, DomainEntityId, EntityIdSchema, EntityByType, EntityId, } from './model.js';
-export type { PartialSchemaOfObject, SchemaOfObject, EnumLike, EntityReflections } from './reflection.js';
-export { type Migration, MigrateFunctionBuilder, type MigrateFunction, type VersionedState, type MigrateFunctionOptions, type AnyVersionedState, StateMigrationError, isStateMigrationError, } from './migrations.js';
-export * from './reflection.js';
-export type { ComponentInstance, StateOfComponent, WritableStateOfComponent, SystemComponentType, SystemComponentTypeConstraint, ComponentSnapshot, } from './component.js';
-export { isEqualComponentInstance, areEqualComponentSnapshots, isEqualComponentSnapshot, isSnapshotOfComponentType, isInstanceOfComponentType, getComponentInstanceKey, getComponentSnapshotKey, } from './component.js';
-export { type DomainState, type DomainStateFactory, createInitialDomainState } from './state.js';
-export type * from './expression.js';
-export * from './alias.js';
-export * from './domain.js';
+export * from './action/index.js';
+export * from './component/index.js';
+export type * from './data-schema/index.js';
+export * from './decoder/index.js';
 export * from './domain-factory.js';
-export * from './preset.js';
-export { getCommonPhxDefinitions, availableDefinitions } from './common-definitions.js';
+export * from './domain.js';
+export type * from './emission/index.js';
+export * from './expression/index.js';
+export * from './invariant/index.js';
+export * from './model/index.js';
+export * from './recipe/index.js';
+export * from './relation/index.js';
+export * from './schema/index.js';
+export * from './state/index.js';

package/dist/domain/core/index.js

@@ -1 +1 @@
-export*from"./schema/index.js";export{_unsafeBuildDomainEntityId,domainEntityTypeFromId,createVirtualEntityId,isDomainEntityId,isVirtualEntityId,VirtualEntityIdSchema,isEqualEntityTypeAndId,parseDomainEntityId,DomainEntityIdSchema,DomainEntitySchema,$DomainEntitySchema}from"./model.js";export{MigrateFunctionBuilder,StateMigrationError,isStateMigrationError}from"./migrations.js";export*from"./reflection.js";export{isEqualComponentInstance,areEqualComponentSnapshots,isEqualComponentSnapshot,isSnapshotOfComponentType,isInstanceOfComponentType,getComponentInstanceKey,getComponentSnapshotKey}from"./component.js";export{createInitialDomainState}from"./state.js";export*from"./alias.js";export*from"./domain.js";export*from"./domain-factory.js";export*from"./preset.js";export{getCommonPhxDefinitions,availableDefinitions}from"./common-definitions.js";
+export*from"./action/index.js";export*from"./component/index.js";export*from"./decoder/index.js";export*from"./domain-factory.js";export*from"./domain.js";export*from"./expression/index.js";export*from"./invariant/index.js";export*from"./model/index.js";export*from"./recipe/index.js";export*from"./relation/index.js";export*from"./schema/index.js";export*from"./state/index.js";

package/dist/domain/core/invariant/builtin-invariant.d.ts

@@ -0,0 +1,5 @@
+import type { DomainEntity, DomainEntityId } from '../model/index.js';
+import type { DomainState } from '../state/index.js';
+import type { Invariant } from './invariants.js';
+import type { Violation } from './violation.js';
+export declare const createInvariant: <VIOLATION_TYPE extends string>(evaluate: (selfId: DomainEntityId<string>, state: DomainState<DomainEntity<string>>) => ReadonlyArray<Violation<VIOLATION_TYPE>>) => Invariant<DomainEntity<string>, DomainEntity<string>, Record<string, unknown>, Record<string, unknown>, Record<string, unknown>, DomainEntity<string>, VIOLATION_TYPE>;

package/dist/domain/core/invariant/custom-invariants.d.ts

@@ -0,0 +1,13 @@
+import type { CustomExpression } from '../expression/index.js';
+import type { $DomainEntity, DomainEntity, TypeOrAlias } from '../model/index.js';
+import type { AliasedInvariants } from './invariants.js';
+import type { Violation } from './violation.js';
+export type CustomInvariantsFromBlueprints<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, BLUEPRINTS extends Partial<Record<keyof $MAP & string, Record<string, boolean | string>>>, CONTEXT_EXTENSION = unknown> = {
+    [TYPE_OR_ALIAS in keyof BLUEPRINTS]: {
+        [NAME in keyof BLUEPRINTS[TYPE_OR_ALIAS]]: TYPE_OR_ALIAS extends keyof $MAP ? CustomExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, $MAP[TYPE_OR_ALIAS], BLUEPRINTS[TYPE_OR_ALIAS][NAME] extends string ? ReadonlyArray<Violation<BLUEPRINTS[TYPE_OR_ALIAS][NAME]>> : BLUEPRINTS[TYPE_OR_ALIAS][NAME], CONTEXT_EXTENSION> : never;
+    };
+};
+/** The violation a static invariant reports when it does not hold, by entity type or alias and by invariant name. */
+type StaticViolations = Readonly<Record<string, Readonly<Record<string, Violation<string>>>>>;
+export declare const createCustomInvariantFactory: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<TypeOrAlias<ENTITIES, ALIASES>, $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ALIASES extends Record<string, ENTITIES>, BLUEPRINTS extends Partial<Record<TypeOrAlias<ENTITIES, ALIASES>, Record<string, boolean | string>>>, CONTEXT_EXTENSION = unknown>() => (staticViolations: StaticViolations) => <TYPES_OR_ALIASES extends keyof BLUEPRINTS & string>(implementations: Pick<CustomInvariantsFromBlueprints<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, BLUEPRINTS, CONTEXT_EXTENSION>, TYPES_OR_ALIASES>) => AliasedInvariants<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ALIASES, string>;
+export {};

package/dist/domain/core/invariant/custom-invariants.js

@@ -0,0 +1 @@
+import{withProfilerLabel as t}from"../../utils/profiler-label.js";export const createCustomInvariantFactory=()=>e=>r=>{let n={};return Object.entries(r).forEach(([r,o])=>{let a=Object.entries(o).map(([n,o])=>({evaluate:t(`${r}_invariant_${n}`,(t,a,i)=>{let l=o(i.domain.get$Entity(t,a),a,i);if("boolean"==typeof l){let t=e[r]?.[n];if(!t)throw Error(`Cannot find statically defined violation for ${r}.${n}`);return l?[]:[t]}return l})}));n[r]=a}),n};

package/dist/domain/core/invariant/index.d.ts

@@ -0,0 +1,5 @@
+export * from './builtin-invariant.js';
+export * from './custom-invariants.js';
+export type * from './invariants.js';
+export * from './violation-component.js';
+export * from './violation.js';

package/dist/domain/core/invariant/index.js

@@ -0,0 +1 @@
+export*from"./builtin-invariant.js";export*from"./custom-invariants.js";export*from"./violation-component.js";export*from"./violation.js";

package/dist/domain/core/invariant/invariants.d.ts

@@ -0,0 +1,10 @@
+import type { OpenExpressionContext } from '../expression/index.js';
+import type { DomainEntity, ExpandAlias, TypeOrAlias } from '../model/index.js';
+import type { DomainState } from '../state/index.js';
+import { type Violation } from './violation.js';
+export interface Invariant<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ENTITY extends ENTITIES, VIOLATION_TYPE extends string, CONTEXT_EXTENSION = unknown> {
+    evaluate(selfId: ENTITY['id'], state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, CONTEXT_EXTENSION>): ReadonlyArray<Violation<VIOLATION_TYPE>>;
+}
+export type AliasedInvariants<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ALIASES extends Record<string, ENTITIES>, VIOLATION_TYPES extends string> = {
+    [K in TypeOrAlias<ENTITIES, ALIASES>]?: ReadonlyArray<Invariant<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ExpandAlias<ENTITIES, ALIASES, K>, VIOLATION_TYPES>>;
+};

package/dist/domain/core/invariant/invariants.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/core/invariant/violation-component.js

@@ -0,0 +1 @@
+import{SystemComponentBuilder as o}from"../component/index.js";import{ViolationSchema as t}from"./violation.js";export const violationsComponent=o.component("violations").withState({tsType:"ViolationComponentState",type:"object",properties:{violations:{type:"array",items:t}},required:["violations"],additionalProperties:!1}).build();

package/dist/domain/core/invariant/violation.d.ts

@@ -0,0 +1,133 @@
+import type { I18n } from '@lingui/core';
+import { type Localizable } from '@salsita-ai/common/utils';
+import type { StateEmission } from '../emission/index.js';
+import type { $DomainEntity, DomainEntity, EntityId } from '../model/index.js';
+/**
+ * An **ORDERED** list of violation severities.
+ * Do not change the order of the items in this list.
+ */
+declare const VIOLATION_SEVERITIES: readonly [
+/**
+ * A fatal error that will never be propagated to the scene, undo stack or saved.
+ *
+ *  If a feature uses "dry-run" to verify whether an action should be allowed,
+ *  this severity will prohibit the change.
+ */
+'fatal', 
+/**
+ * Similar semantics to `fatal` - i.e. the violation will never be propagated to the scene, undo stack or saved
+ * - but unlike `fatal`, "dry-run" will allow the change and expect a custom logic to suggest or apply a fix.
+ */
+'fixable', 
+/**
+ * A warning that will be propagated to the scene, undo stack and saved.
+ * However, it will prevent the configuration from being "finalized" (e.g. added to e-commerce cart).
+ */
+'warning', 
+/**
+ * An informative notice that will be propagated to the scene, undo stack and saved.
+ * This severity does not impose any restrictions on the configuration.
+ */
+'notice'];
+export type ViolationSeverity = (typeof VIOLATION_SEVERITIES)[number];
+export declare const compareSeverity: (a: ViolationSeverity, b: ViolationSeverity) => number;
+export interface Violation<TYPE extends string> {
+    readonly type: TYPE;
+    readonly severity: ViolationSeverity;
+    readonly message?: Localizable;
+    /**
+     * Only violations with the highest priority will be shown during on input controls.
+     * If there are multiple violations with the same priority,
+     * all of them will be shown in the tooltip, concatenated with a dot.
+     *
+     * Default priority is 0.
+     */
+    readonly controlViolationPriority?: number;
+    /**
+     * An optional callback to format the violation message for control tooltips.
+     * Unlike the general `message` field, this callback receives the state emission
+     * and can format the message based on what updates occurred.
+     *
+     * @returns A message formatted specifically for this state emission,
+     * `null` to skip the message when generating tooltip text,
+     * or `undefined` to fallback to the general `message` field.
+     */
+    readonly formatControlViolationMessage?: (stateEmission: StateEmission<DomainEntity<string>, Record<string, $DomainEntity<DomainEntity<string>>>>, context: {
+        i18n: I18n;
+    }) => Localizable | undefined | null;
+}
+export declare const ViolationSchema: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly type: {
+            readonly type: 'string';
+        };
+        readonly severity: {
+            readonly enum: ("fatal" | "fixable" | "notice" | "warning")[];
+        };
+        readonly message: {
+            readonly anyOf: [{
+                readonly type: 'string';
+            }, {
+                readonly type: 'object';
+                readonly properties: {
+                    readonly id: {
+                        readonly type: 'string';
+                    };
+                    readonly comment: {
+                        readonly type: 'string';
+                    };
+                    readonly message: {
+                        readonly type: 'string';
+                    };
+                    readonly values: {
+                        readonly type: 'object';
+                        readonly additionalProperties: true;
+                    };
+                };
+                readonly required: ["id"];
+                readonly additionalProperties: false;
+                readonly import: [{
+                    readonly module: '@lingui/core';
+                    readonly member: 'MessageDescriptor';
+                }];
+                readonly tsType: 'MessageDescriptor';
+            }, {
+                readonly import: [{
+                    readonly module: '@salsita-ai/sdk/common/utils';
+                    readonly member: 'MultilingualString';
+                }];
+                readonly tsType: 'MultilingualString';
+                readonly type: 'object';
+                readonly properties: {
+                    readonly $lang: {
+                        readonly type: 'object';
+                        readonly additionalProperties: {
+                            readonly type: 'string';
+                        };
+                    };
+                };
+                readonly required: ["$lang"];
+                readonly additionalProperties: false;
+            }];
+            readonly tsType: 'Localizable';
+            readonly import: [{
+                readonly module: '@salsita-ai/sdk/common/utils';
+                readonly member: 'Localizable';
+            }];
+        };
+        readonly controlViolationPriority: {
+            readonly type: 'number';
+        };
+    };
+    readonly required: ["type", "severity"];
+    readonly additionalProperties: false;
+};
+export type ViolationTypesOf$Entity<$ENTITY extends $DomainEntity<DomainEntity<string>>> = $ENTITY extends {
+    $violations: ReadonlyArray<Violation<infer VIOLATION_TYPE>>;
+} ? VIOLATION_TYPE : never;
+export interface EntityViolation<ENTITIES extends DomainEntity<string>, VIOLATION_TYPE extends string> {
+    readonly entityId: EntityId<ENTITIES>;
+    readonly violation: Violation<VIOLATION_TYPE>;
+}
+export {};

package/dist/domain/core/invariant/violation.js

@@ -0,0 +1 @@
+import{MessageDescriptorSchema as e,MultilingualStringSchema as t}from"@salsita-ai/common/utils";let i=["fatal","fixable","warning","notice"];export const compareSeverity=(e,t)=>i.indexOf(e)-i.indexOf(t);export const ViolationSchema={type:"object",properties:{type:{type:"string"},severity:{enum:i.slice()},message:{anyOf:[{type:"string"},e,t],tsType:"Localizable",import:[{module:"@salsita-ai/sdk/common/utils",member:"Localizable"}]},controlViolationPriority:{type:"number"}},required:["type","severity"],additionalProperties:!1};

package/dist/domain/core/model/component.d.ts

@@ -0,0 +1,46 @@
+import { type ExtendedJsonSchema } from '@salsita-ai/common/utils';
+import type { PhxValidateFunction } from '../schema/index.js';
+import type { EntityId } from './model.js';
+/**
+ * Definition of how the component looks like, it's name, state and other properties. It is used to instantiate components.
+ */
+export interface SystemComponentType<NAME extends string, COMPONENT_STATE extends Record<string, unknown>, WRITABLE_KEYS extends keyof COMPONENT_STATE> {
+    readonly name: NAME;
+    readonly writableKeys: WRITABLE_KEYS[];
+    readonly schema: ExtendedJsonSchema;
+    readonly validateState: PhxValidateFunction<COMPONENT_STATE>;
+    readonly validateWritableState: PhxValidateFunction<Pick<COMPONENT_STATE, WRITABLE_KEYS>>;
+}
+/**
+ * Concrete version of SystemComponentType with the widest possible constraints. Use it when you don't care about generic constraints
+ * of component types, eg. in extend expressions.
+ */
+export type SystemComponentTypeConstraint = SystemComponentType<string, Record<string, unknown>, string>;
+/**
+ * Instantiation of a component for a specific entity and instance name. It is used as concrete identification of a component in the system.
+ */
+export interface ComponentInstance<COMPONENT_TYPE extends SystemComponentTypeConstraint> {
+    readonly entityId: EntityId;
+    readonly instanceName: string;
+    readonly componentType: COMPONENT_TYPE;
+}
+export declare const isInstanceOfComponentType: <COMPONENT_TYPE extends SystemComponentTypeConstraint>(componentType: COMPONENT_TYPE) => (instance: ComponentInstance<SystemComponentTypeConstraint>) => instance is ComponentInstance<COMPONENT_TYPE>;
+/**
+ * Checks if two component instances are equal - are of same ComponentType, belong to the same entity and have the same instance name.
+ */
+export declare const isEqualComponentInstance: (a: ComponentInstance<SystemComponentTypeConstraint>, b: ComponentInstance<SystemComponentTypeConstraint>) => boolean;
+export type StateOfComponent<COMPONENT_TYPE extends SystemComponentTypeConstraint> = COMPONENT_TYPE extends SystemComponentType<any, infer COMPONENT_STATE, any> ? COMPONENT_STATE : never;
+export type WritableStateOfComponent<COMPONENT_TYPE extends SystemComponentTypeConstraint> = COMPONENT_TYPE extends SystemComponentType<any, infer COMPONENT_STATE, infer WRITABLE_KEYS> ? Pick<COMPONENT_STATE, WRITABLE_KEYS> : never;
+/**
+ * Instantiated component for a given entity/instanceName with a state. Snapshots are returned from the component reader.
+ */
+export interface ComponentSnapshot<COMPONENT_TYPE extends SystemComponentTypeConstraint> {
+    readonly componentInstance: ComponentInstance<COMPONENT_TYPE>;
+    readonly state: StateOfComponent<COMPONENT_TYPE>;
+}
+export declare const isEqualComponentSnapshot: (a: ComponentSnapshot<SystemComponentTypeConstraint>, b: ComponentSnapshot<SystemComponentTypeConstraint>) => boolean;
+export declare const areEqualComponentSnapshots: (a: ReadonlyArray<ComponentSnapshot<SystemComponentTypeConstraint>>, b: ReadonlyArray<ComponentSnapshot<SystemComponentTypeConstraint>>) => boolean;
+export declare const isSnapshotOfComponentType: <COMPONENT_TYPE extends SystemComponentTypeConstraint>(componentType: COMPONENT_TYPE) => (snapshot: ComponentSnapshot<SystemComponentTypeConstraint>) => snapshot is ComponentSnapshot<COMPONENT_TYPE>;
+export declare const isSnapshotInstance: <COMPONENT_TYPE extends SystemComponentTypeConstraint>(entityId: EntityId, instanceName: string, componentType: COMPONENT_TYPE) => (snapshot: ComponentSnapshot<SystemComponentTypeConstraint>) => snapshot is ComponentSnapshot<COMPONENT_TYPE>;
+export declare const getComponentInstanceKey: (componentInstance: ComponentInstance<SystemComponentTypeConstraint>) => string;
+export declare const getComponentSnapshotKey: (snapshot: ComponentSnapshot<SystemComponentTypeConstraint>) => string;

package/dist/domain/core/model/index.d.ts

@@ -0,0 +1,6 @@
+export * from './alias.js';
+export * from './common-definitions.js';
+export * from './component.js';
+export * from './model.js';
+export * from './preset.js';
+export * from './reflection.js';

package/dist/domain/core/model/index.js

@@ -0,0 +1 @@
+export*from"./alias.js";export*from"./common-definitions.js";export*from"./component.js";export*from"./model.js";export*from"./preset.js";export*from"./reflection.js";

package/dist/domain/core/model/model.d.ts

@@ -0,0 +1,127 @@
+declare const VirtualEntityIdSymbol: unique symbol;
+export interface VirtualEntityId {
+    [VirtualEntityIdSymbol]: true;
+    name: string;
+    toString: () => string;
+}
+export declare const VirtualEntityIdSchema: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly [VirtualEntityIdSymbol]: {
+            readonly type: 'boolean';
+            readonly const: true;
+        };
+        readonly name: {
+            readonly type: 'string';
+        };
+    };
+    readonly required: ["name"];
+    readonly additionalProperties: false;
+    readonly import: [{
+        readonly module: '@salsita-ai/sdk/domain';
+        readonly member: 'VirtualEntityId';
+    }];
+    readonly tsType: 'VirtualEntityId';
+};
+export declare const createVirtualEntityId: (name: string) => VirtualEntityId;
+export declare const isVirtualEntityId: (value: EntityId<any>) => value is VirtualEntityId;
+export type DomainEntityId<TYPE extends string = string> = `${TYPE}-${number}` & {
+    __brand: TYPE;
+};
+/**
+ * This function is meant for internal use and for test fixtures only.
+ * **DO NOT USE IT IN PRODUCTION CODE.**
+ */
+export declare const _unsafeBuildDomainEntityId: <TYPE extends string>(type: TYPE, sequenceNumber: number) => DomainEntityId<TYPE>;
+export declare const parseDomainEntityId: <TYPE extends string>(id: DomainEntityId<TYPE>) => {
+    type: TYPE;
+    sequenceNumber: number;
+};
+export declare const domainEntityTypeFromId: <TYPE extends string>(id: DomainEntityId<TYPE>) => TYPE;
+export declare const isDomainEntityId: <ENTITIES extends DomainEntity<string> = DomainEntity<string>>(value: EntityId<ENTITIES>) => value is ENTITIES['id'];
+export declare const isEqualEntityTypeAndId: (a: DomainEntity<string>, b: DomainEntity<string>) => boolean;
+export declare const DomainEntityIdSchema: {
+    readonly type: 'string';
+    readonly pattern: '^[A-Z]\\w*-\\d+$';
+    readonly import: [{
+        readonly module: '@salsita-ai/sdk/domain';
+        readonly member: 'DomainEntityId';
+    }];
+    readonly tsType: 'DomainEntityId';
+};
+export type EntityId<ENTITY extends DomainEntity<string> = DomainEntity<string>> = ENTITY['id'] | VirtualEntityId;
+export declare const EntityIdSchema: {
+    readonly anyOf: [{
+        readonly type: 'string';
+        readonly pattern: '^[A-Z]\\w*-\\d+$';
+        readonly import: [{
+            readonly module: '@salsita-ai/sdk/domain';
+            readonly member: 'DomainEntityId';
+        }];
+        readonly tsType: 'DomainEntityId';
+    }, {
+        readonly type: 'object';
+        readonly properties: {
+            readonly [VirtualEntityIdSymbol]: {
+                readonly type: 'boolean';
+                readonly const: true;
+            };
+            readonly name: {
+                readonly type: 'string';
+            };
+        };
+        readonly required: ["name"];
+        readonly additionalProperties: false;
+        readonly import: [{
+            readonly module: '@salsita-ai/sdk/domain';
+            readonly member: 'VirtualEntityId';
+        }];
+        readonly tsType: 'VirtualEntityId';
+    }];
+};
+export interface DomainEntity<TYPE extends string> {
+    type: TYPE;
+    id: DomainEntityId<TYPE>;
+}
+export declare const DomainEntitySchema: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly id: {
+            readonly $ref: '#/definitions/DomainEntityId';
+        };
+        readonly type: {
+            readonly type: 'string';
+        };
+    };
+    readonly import: [{
+        readonly module: '@salsita-ai/sdk/domain';
+        readonly member: 'DomainEntity';
+    }];
+    readonly tsType: 'DomainEntity';
+};
+export type $DomainEntity<ENTITY extends DomainEntity<string>> = ENTITY & {
+    _raw: ENTITY;
+};
+export declare const $DomainEntitySchema: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly _raw: {
+            readonly $ref: '#/definitions/DomainEntity';
+        };
+        readonly id: {
+            readonly $ref: '#/definitions/DomainEntityId';
+        };
+        readonly type: {
+            readonly type: 'string';
+        };
+    };
+    readonly import: [{
+        readonly module: '@salsita-ai/sdk/domain';
+        readonly member: '$DomainEntity';
+    }];
+    readonly tsType: '$DomainEntity';
+};
+export type EntityByType<ENTITIES extends DomainEntity<string>, TYPE extends ENTITIES['type']> = Extract<ENTITIES, {
+    type: TYPE;
+}>;
+export {};

package/dist/domain/core/model/reflection.d.ts

@@ -0,0 +1,114 @@
+import type { ExtendedJsonSchema } from '@salsita-ai/common/utils';
+import { type PhxValidateFunction } from '../schema/index.js';
+import { type $DomainEntity, type DomainEntity, type EntityByType, type EntityId } from './model.js';
+type RequiredKeys<T> = {
+    [K in keyof T]: undefined extends T[K] ? never : K;
+}[keyof T];
+export type SchemaOfObject<T extends object> = ExtendedJsonSchema & {
+    type: 'object';
+    properties: {
+        [K in keyof T]: ExtendedJsonSchema;
+    };
+    required: Array<RequiredKeys<T>>;
+    additionalProperties: false;
+};
+interface SchemaReflectionMeta<T, S extends ExtendedJsonSchema> {
+    readonly name: string;
+    readonly schema: S;
+    readonly validator: PhxValidateFunction<T>;
+}
+export type PartialSchemaOfObject<T extends object> = ExtendedJsonSchema & {
+    type: 'object';
+    properties: {
+        [K in keyof T]?: ExtendedJsonSchema;
+    };
+    required: Array<RequiredKeys<T>>;
+    additionalProperties: false;
+};
+export declare class SchemaReflection<T, S extends ExtendedJsonSchema = ExtendedJsonSchema> {
+    readonly _meta: SchemaReflectionMeta<T, S>;
+    constructor(name: string, schema: S);
+    is: (value: unknown) => value is T;
+    assert(value: unknown): asserts value is T;
+}
+export declare class EnumReflection<T extends string> extends SchemaReflection<T, ExtendedJsonSchema & {
+    readonly enum: T[];
+}> {
+    constructor(name: string, schema: ExtendedJsonSchema & {
+        readonly enum: T[];
+    });
+    values: () => T[];
+}
+export type EnumLike<T extends string> = EnumReflection<T> & {
+    [K in T]: K;
+};
+declare class BaseDomainEntityReflection<UNKNOWN extends DomainEntity<string> | $DomainEntity<DomainEntity<string>>, ENTITY extends UNKNOWN> {
+    readonly type: ENTITY['type'];
+    constructor(type: ENTITY['type']);
+    is: (entity: UNKNOWN) => entity is ENTITY;
+    assert(entity: UNKNOWN): asserts entity is ENTITY;
+    isId: (entityId: EntityId) => entityId is ENTITY['id'];
+    assertId(entityId: EntityId): asserts entityId is ENTITY['id'];
+    assertIds(entityIds: readonly EntityId[]): asserts entityIds is ReadonlyArray<ENTITY['id']>;
+}
+export declare class DomainEntityReflection<ENTITY extends DomainEntity<string>> extends BaseDomainEntityReflection<DomainEntity<string>, ENTITY> {
+    readonly _meta: SchemaReflectionMeta<ENTITY, SchemaOfObject<ENTITY>>;
+    constructor(type: ENTITY['type'], schemas: Array<PartialSchemaOfObject<ENTITY>>);
+}
+/**
+ * Expression member names of an enhanced entity type — the keys an enhanced reflection may
+ * expose as module-level constants.
+ */
+export type ExpressionKeys<ENTITY> = Extract<keyof ENTITY, `$${string}`>;
+declare class $DomainEntityReflectionClass<ENTITY extends $DomainEntity<DomainEntity<string>>, CONSTANT_KEYS extends ExpressionKeys<ENTITY>> extends BaseDomainEntityReflection<$DomainEntity<DomainEntity<string>>, ENTITY> {
+    readonly expressions: string[];
+    constructor(type: ENTITY['type'], expressions: string[], constants: Pick<ENTITY, CONSTANT_KEYS>);
+}
+/**
+ * Enhanced entity reflection: knows the entity's expression names and exposes its self-free
+ * `constants:` values as own members, so `phx.domain.enhancedModel.$Wall.$maxWidth` reads a
+ * constant without an entity instance. `CONSTANT_KEYS` names the exposed constants; their types
+ * come from the entity's expression types.
+ */
+export type $DomainEntityReflection<ENTITY extends $DomainEntity<DomainEntity<string>>, CONSTANT_KEYS extends ExpressionKeys<ENTITY> = never> = $DomainEntityReflectionClass<ENTITY, CONSTANT_KEYS> & Pick<ENTITY, CONSTANT_KEYS>;
+interface $DomainEntityReflectionConstructor {
+    new <ENTITY extends $DomainEntity<DomainEntity<string>>, CONSTANT_KEYS extends ExpressionKeys<ENTITY> = never>(type: ENTITY['type'], expressions: string[], constants: Pick<ENTITY, CONSTANT_KEYS>): $DomainEntityReflection<ENTITY, CONSTANT_KEYS>;
+}
+export declare const $DomainEntityReflection: $DomainEntityReflectionConstructor;
+export type Any$EntityReflections = Record<string, $DomainEntityReflection<$DomainEntity<DomainEntity<string>>>>;
+declare class BaseAliasReflection<UNKNOWN extends DomainEntity<string> | $DomainEntity<DomainEntity<string>>, ENTITIES extends UNKNOWN> {
+    readonly name: string;
+    readonly types: ReadonlyArray<ENTITIES['type']>;
+    readonly typeSet: Set<ENTITIES['type']>;
+    constructor(name: string, types: ReadonlyArray<ENTITIES['type']>);
+    is: (entity: UNKNOWN) => entity is ENTITIES;
+    assert(entity: UNKNOWN): asserts entity is ENTITIES;
+    isId: (entityId: EntityId) => entityId is ENTITIES['id'];
+    assertId(entityId: EntityId): asserts entityId is ENTITIES['id'];
+    assertIds(entityIds: readonly EntityId[]): asserts entityIds is ReadonlyArray<ENTITIES['id']>;
+}
+export declare class RawAliasReflection<ENTITIES extends DomainEntity<string>> extends BaseAliasReflection<DomainEntity<string>, ENTITIES> {
+    readonly reflections: ReadonlyArray<ENTITIES extends any ? DomainEntityReflection<ENTITIES> : never>;
+    constructor(name: string, reflections: ReadonlyArray<ENTITIES extends any ? DomainEntityReflection<ENTITIES> : never>);
+}
+declare class EnhancedAliasReflectionClass<ENTITIES extends $DomainEntity<DomainEntity<string>>, CONSTANT_KEYS extends ExpressionKeys<ENTITIES>> extends BaseAliasReflection<$DomainEntity<DomainEntity<string>>, ENTITIES> {
+    constructor(name: string, types: ReadonlyArray<ENTITIES['type']>, constants: Pick<ENTITIES, CONSTANT_KEYS>);
+}
+/**
+ * Enhanced alias reflection: the alias membership check plus the alias-declared self-free
+ * `constants:` values as own members (`phx.domain.enhancedModel.$TopElement.$defaultHeight`).
+ * Alias expressions exist on every member, so `CONSTANT_KEYS` picks from the member union.
+ */
+export type EnhancedAliasReflection<ENTITIES extends $DomainEntity<DomainEntity<string>>, CONSTANT_KEYS extends ExpressionKeys<ENTITIES> = never> = EnhancedAliasReflectionClass<ENTITIES, CONSTANT_KEYS> & Pick<ENTITIES, CONSTANT_KEYS>;
+interface EnhancedAliasReflectionConstructor {
+    new <ENTITIES extends $DomainEntity<DomainEntity<string>>, CONSTANT_KEYS extends ExpressionKeys<ENTITIES> = never>(name: string, types: ReadonlyArray<ENTITIES['type']>, constants: Pick<ENTITIES, CONSTANT_KEYS>): EnhancedAliasReflection<ENTITIES, CONSTANT_KEYS>;
+}
+export declare const EnhancedAliasReflection: EnhancedAliasReflectionConstructor;
+export type EntityReflections<ENTITIES extends DomainEntity<string>> = {
+    [TYPE in ENTITIES['type']]: DomainEntityReflection<EntityByType<ENTITIES, TYPE>>;
+};
+export type AnyEntityReflections = Record<string, DomainEntityReflection<DomainEntity<string>>>;
+export declare function assertString(value: unknown): asserts value is string;
+export declare function assertNumber(value: unknown): asserts value is number;
+export declare function assertBoolean(value: unknown): asserts value is boolean;
+export {};

package/dist/domain/core/model/reflection.js

@@ -0,0 +1 @@
+import{extendedSchemaValidator as t}from"../schema/index.js";import{domainEntityTypeFromId as e,isDomainEntityId as s}from"./model.js";export class SchemaReflection{_meta;constructor(e,s){this._meta={name:e,schema:s,validator:t.compile(s)}}is=t=>this._meta.validator(t);assert(t){if(!this._meta.validator(t))throw Error(`Expected value to match schema of '${this._meta.name}' but got ${t}`)}}export class EnumReflection extends SchemaReflection{constructor(t,e){for(let s of(super(t,e),e.enum))Object.defineProperty(this,s,{value:s,writable:!1,enumerable:!0,configurable:!1})}values=()=>this._meta.schema.enum}let o=class BaseDomainEntityReflection{type;constructor(t){this.type=t}is=t=>t.type===this.type;assert(t){if(!this.is(t))throw Error(`Expected entity #${t.id} to be of type ${this.type} but got ${t.type}`)}isId=t=>s(t)&&e(t)===this.type;assertId(t){if(!this.isId(t))throw Error(`Expected entity id to be of type ${this.type} but got ${t}`)}assertIds(t){t.forEach(t=>{this.assertId(t)})}};export class DomainEntityReflection extends o{_meta;constructor(e,s){super(e);let o=s.reduce((t,e)=>{let s=e.$defs;return"object"==typeof s&&null!==s&&Object.assign(t,s),t},{}),r={type:"object",properties:{id:{type:"string",pattern:`^${e}-[0-9]+$`},type:{type:"string",const:e},...s.reduce((t,e)=>({...t,...e.properties}),{})},required:["id","type",...s.flatMap(t=>t.required??[])],additionalProperties:!1},i={...r,$defs:o};this._meta={name:e,schema:r,validator:t.compile(i)}}}let r=class $DomainEntityReflectionClass extends o{expressions;constructor(t,e,s){super(t),this.expressions=e,Object.assign(this,s)}};export const $DomainEntityReflection=r;let i=class BaseAliasReflection{name;types;typeSet;constructor(t,e){this.name=t,this.types=e,this.typeSet=new Set(e)}is=t=>this.typeSet.has(t.type);assert(t){if(!this.is(t))throw Error(`Expected entity #${t.id} to be a member of alias ${this.name} but got ${t.type}`)}isId=t=>s(t)&&this.typeSet.has(e(t));assertId(t){if(!this.isId(t))throw Error(`Expected entity id to be of a member of alias ${this.name} but got ${t}`)}assertIds(t){t.forEach(t=>{this.assertId(t)})}};export class RawAliasReflection extends i{reflections;constructor(t,e){super(t,e.map(t=>t.type)),this.reflections=e}}let a=class EnhancedAliasReflectionClass extends i{constructor(t,e,s){super(t,e),Object.assign(this,s)}};export const EnhancedAliasReflection=a;export function assertString(t){if("string"!=typeof t)throw Error(`Expected value to be a string but got ${t}`)}export function assertNumber(t){if("number"!=typeof t)throw Error(`Expected value to be a number but got ${t}`)}export function assertBoolean(t){if("boolean"!=typeof t)throw Error(`Expected value to be a boolean but got ${t}`)}

package/dist/domain/core/recipe/index.d.ts

@@ -0,0 +1 @@
+export * from './recipes.js';

package/dist/domain/core/recipe/index.js

@@ -0,0 +1 @@
+export*from"./recipes.js";

package/dist/domain/core/recipe/recipes.d.ts

@@ -0,0 +1,23 @@
+import { type AnyAliasMap, type DomainEntity, type DomainEntityReflection, type EntityByType } from '../model/index.js';
+/** The entity a recipe yields: a whole entity, which the recipe system gives a new id when it cooks the recipe. */
+export type EntityRecipe<ENTITY extends DomainEntity<string>> = ENTITY;
+/** What a project passes to its recipe factory: the entity type, and the properties that differ from the defaults. */
+export type EntityOverrides<ENTITIES extends DomainEntity<string>, TYPE extends ENTITIES['type']> = Partial<Omit<EntityByType<ENTITIES, TYPE>, 'type'>> & {
+    type: TYPE;
+};
+/** The function a project creates recipes with, `phx.domain.createRecipe`. */
+export type RecipeFactory<ENTITIES extends DomainEntity<string>> = <TYPE extends ENTITIES['type']>(overrides: EntityOverrides<ENTITIES, TYPE>) => EntityRecipe<EntityByType<ENTITIES, TYPE>>;
+/**
+ * Creates the recipe factory of a domain from the `defaults` of its spec.
+ *
+ * Defaults declared for an alias apply to every entity type of the alias, and a later key overrides
+ * an earlier one. The defaults of an entity type must be a whole entity of that type: they are
+ * validated here against the entity's schema, so a domain with invalid defaults fails when its
+ * module loads. An entity type without defaults is not checked.
+ *
+ * `ENTITIES` is the only type the result depends on, and no argument determines it, so the caller
+ * states it.
+ *
+ * @param defaults Property values by entity type or alias.
+ */
+export declare const createRecipeFactory: <ENTITIES extends DomainEntity<string>>(aliasMap: AnyAliasMap, entityReflections: ReadonlyArray<ENTITIES extends unknown ? DomainEntityReflection<ENTITIES> : never>, defaults: Readonly<Record<string, Readonly<Record<string, unknown>>>>) => RecipeFactory<ENTITIES>;

package/dist/domain/core/recipe/recipes.js

@@ -0,0 +1 @@
+import{_unsafeBuildDomainEntityId as e,expandAlias as r}from"../model/index.js";export const createRecipeFactory=(t,o,i)=>{let a={};Object.entries(i).forEach(([e,o])=>{r(t,e).forEach(e=>{a[e]={...a[e],...o}})});let n=new Map(o.map(e=>[e.type,e._meta.validator]));return Object.entries(a).forEach(([r,t])=>{let o=n.get(r);if(!o)throw Error(`Defaults provided for unknown entity ${r}`);if(!o({id:e(r,1),type:r,...t}))throw console.error(o.errors,t),Error(`Invalid defaults for ${r} entity.`)}),r=>({id:e(r.type,1),...a[r.type],...r})};

package/dist/domain/core/relation/all-of-type-relation.d.ts

@@ -0,0 +1,19 @@
+import type { ExpressionMeta } from '../expression/index.js';
+import { type AnyAliasMap, type DomainEntity, type DomainEntityId } from '../model/index.js';
+import type { DomainState } from '../state/index.js';
+/** A relation whose related entities are all entities of the target type or alias. */
+export interface AllOfTypeRelation {
+    kind: 'allOfType';
+    target: string;
+    cardinality: '0-1' | '1-1' | '0-N' | '1-N';
+    meta?: ExpressionMeta;
+}
+/**
+ * Resolves `allOfType` relations from a per-state index. Relations targeting the same set of types
+ * share one bucket; the first resolution on a state walks the entities once to fill every bucket,
+ * and every later resolution on that state is a lookup. Registration closes once the first state
+ * has been indexed, so a bucket can never be missing from an index that was already built.
+ */
+export declare const createAllOfTypeRelation: (aliasMap: AnyAliasMap) => (relation: {
+    readonly target: string;
+}) => (_selfId: DomainEntityId<string>, state: DomainState<DomainEntity<string>>) => DomainEntityId<string>[];

package/dist/domain/core/relation/all-of-type-relation.js

@@ -0,0 +1 @@
+import{expandAlias as e}from"../model/index.js";export const createAllOfTypeRelation=t=>{let r=new Map,a=new WeakMap,n=!1;return o=>{if(n)throw Error(`Cannot register all-of-type relation targeting ${o.target} after evaluation started. Create all relation expressions before evaluating the domain state.`);let l=new Set(e(t,o.target)),i=[...l].sort().join("|");return r.set(i,l),(e,t)=>(e=>{let t=a.get(e);if(t)return t;n=!0;let o=new Map([...r.keys()].map(e=>[e,[]]));for(let t of e.entities)for(let[e,a]of r)a.has(t.type)&&o.get(e).push(t.id);return a.set(e,o),o})(t).get(i)}};

package/dist/domain/core/relation/component-factories.d.ts

@@ -0,0 +1,14 @@
+import type { DomainEntity, DomainEntityId, DomainEntityReflection, RawAliasReflection } from '../model/index.js';
+import type { ComposedOfComponentState } from './composed-of.js';
+import type { ReferenceComponentState } from './reference-component.js';
+export declare const createSingleReferenceRead: <TARGET extends DomainEntity<string>>(_targetReflection: DomainEntityReflection<TARGET> | RawAliasReflection<TARGET>, field: string) => (self: object, state: unknown, ctx: unknown) => ReferenceComponentState;
+export declare const createSingleReferenceWrite: <TARGET extends DomainEntity<string>>(targetReflection: DomainEntityReflection<TARGET> | RawAliasReflection<TARGET>, field: string) => (writableState: ReferenceComponentState) => {
+    [x: string]: DomainEntityId<string> | null;
+};
+export declare const createMultipleReferenceRead: <TARGET extends DomainEntity<string>>(_targetReflection: DomainEntityReflection<TARGET> | RawAliasReflection<TARGET>, field: string) => (self: object, state: unknown, ctx: unknown) => ReferenceComponentState;
+export declare const createMultipleReferenceWrite: <TARGET extends DomainEntity<string>>(targetReflection: DomainEntityReflection<TARGET> | RawAliasReflection<TARGET>, field: string) => (writableState: ReferenceComponentState) => {
+    [x: string]: readonly DomainEntityId<string>[];
+};
+export declare const createSingleCompositionRead: (relationName: string) => (self: object, state: unknown, ctx: unknown) => ComposedOfComponentState;
+export declare const createMultipleCompositionRead: (relationName: string) => (self: object, state: unknown, ctx: unknown) => ComposedOfComponentState;
+export declare const createEmptyWrite: () => () => {};

package/dist/domain/core/relation/component-factories.js

@@ -0,0 +1 @@
+import{memoEval as e}from"../../utils/memo-eval.js";export const createSingleReferenceRead=(t,r)=>e(e=>[e[r]],e=>({referencedEntityIds:null===e?[]:[e]}));export const createSingleReferenceWrite=(e,t)=>r=>{let n=r.referencedEntityIds[0];return n&&e.assertId(n),{[t]:n??null}};export const createMultipleReferenceRead=(t,r)=>e(e=>[e[r]],e=>({referencedEntityIds:e}));export const createMultipleReferenceWrite=(e,t)=>r=>(e.assertIds(r.referencedEntityIds),{[t]:r.referencedEntityIds});export const createSingleCompositionRead=t=>e(e=>[e[t]?.id??null],e=>({childEntityIds:null===e?[]:[e]}));export const createMultipleCompositionRead=t=>e(e=>e[t].map(e=>e.id),(...e)=>({childEntityIds:e}));export const createEmptyWrite=()=>()=>({});