@endge/core 1.2.5 → 1.2.8

package/dist/domain/types/source/composition-source.types.d.ts

@@ -0,0 +1,321 @@
+import { ProgramDiagnostic } from '../program/program.types';
+import { ProgramMetadataMap } from '../program/program-metadata.types';
+import { RuntimeHost } from '../runtime/runtime-host.types';
+import { RuntimeScopeHandle } from '../runtime/runtime-scope.types';
+import { VocabLoadPolicy } from '../runtime/vocab-cache.types';
+import { CompositionRuntimeHost } from '../../entities/runtime/hosts/CompositionRuntimeHost';
+import { SourceExpressionIR, SourceFieldDefinition } from './source-expression.types';
+import { FilterViewControlDefinition } from '../ui/filter-view.type';
+import { EndgeMockReference } from '../mock';
+import { I18nCompiledLocales } from '../i18n.types';
+export type CompositionRuntimeKind = 'filter' | 'query' | 'component' | 'composition' | 'filter-view';
+export type CompositionActivationMode = 'startup' | 'manual';
+export interface CompositionActivationDescriptor {
+    mode: CompositionActivationMode;
+}
+export interface CompositionResourceDescriptor {
+    name: string;
+    path: string;
+    scopePath: string;
+    kind: 'style' | 'i18n';
+    identity: string;
+    sourceOrder: number;
+}
+/** Материализованный i18n-resource внутри Composition program artifact. */
+export interface CompositionI18nResourceArtifact {
+    name: string;
+    path: string;
+    scopePath: string;
+    identity: string;
+    sourceOrder: number;
+    messages: I18nCompiledLocales;
+}
+export interface CompositionScopeDescriptor {
+    name: string;
+    /** Публичный path; implicit scope_default имеет path "scope_default". */
+    path: string;
+    parentPath: string | null;
+    activationOverride: CompositionActivationDescriptor | null;
+    effectiveActivation: CompositionActivationDescriptor;
+    /** Data dependencies, активируемые вместе с lifecycle scope. */
+    data?: string[];
+    resources: string[];
+    runtimes: string[];
+    children: string[];
+    sourceOrder: number;
+}
+export type CompositionBindingValue = {
+    kind: 'literal';
+    value: unknown;
+} | {
+    kind: 'output';
+    runtime: string;
+    output: string;
+} | {
+    kind: 'outputs';
+    runtime: string;
+    outputs?: string[];
+} | {
+    kind: 'store';
+    key: string;
+} | {
+    kind: 'data';
+    data: string;
+    path: string;
+} | {
+    kind: 'runtime-metadata';
+    runtime: string;
+    namespace?: string;
+} | {
+    kind: 'filter-fields';
+    runtime: string;
+    fields: string[];
+} | {
+    kind: 'expression';
+    expression: SourceExpressionIR;
+};
+export interface CompositionDataDescriptor {
+    name: string;
+    /** Полный data path. Для root data совпадает с name. */
+    path?: string;
+    /** Lifecycle scope, которому принадлежит dependency. */
+    scopePath?: string;
+    kind: 'store' | 'vocab';
+    identity: string;
+    /** Политика разрешения Store; для Vocab не используется. */
+    resolution?: 'contextual' | 'isolated' | 'injected';
+    /** Provider slot для нескольких Store instances с одной identity. */
+    slot?: string | null;
+    /** Нормализованная политика загрузки Vocab; для Store не используется. */
+    policy?: VocabLoadPolicy;
+}
+export interface CompositionStorePublication {
+    data: string;
+    fields: Record<string, string>;
+}
+export interface CompositionFilterFieldsSlice {
+    kind: 'filter-fields';
+    runtimeId: string;
+    runtimeName: string;
+    fieldKeys: string[];
+    fields: SourceFieldDefinition[];
+    values: Record<string, unknown>;
+}
+export interface CompositionRuntimeDescriptor {
+    name: string;
+    /** Полный публичный path runtime внутри Composition. */
+    path: string;
+    /** Internal path owning RuntimeScope. */
+    scopePath: string;
+    /** Source offsets used by authoring tools; runtime does not interpret them. */
+    sourceLocations?: {
+        runtime: {
+            start: number;
+            end: number;
+        };
+        call: {
+            start: number;
+            end: number;
+        };
+        withProps: {
+            start: number;
+            end: number;
+        } | null;
+    };
+    kind: CompositionRuntimeKind;
+    identity: string;
+    /** Явный override в месте вызова runtime. */
+    activationOverride: CompositionActivationDescriptor | null;
+    /** Compiler-linked activation, которую runtime применяет без интерпретации source. */
+    effectiveActivation: CompositionActivationDescriptor;
+    fields?: string[];
+    controls?: Record<string, FilterViewControlDefinition>;
+    componentIdentity?: string;
+    persistKey?: string;
+    props: Record<string, CompositionBindingValue>;
+    /** Локальный data alias child -> data alias owner Composition. */
+    dataBindings?: Record<string, string>;
+    storeTo: CompositionStorePublication[];
+}
+export interface CompositionRuntimeChildHandle {
+    name: string;
+    descriptor: CompositionRuntimeDescriptor;
+    runtime: RuntimeHost<any, any>;
+}
+/** Источник изменения для управляемого повторного запуска Query. */
+export type CompositionChangeSource = {
+    kind: 'runtime-output';
+    runtime: string;
+    output: string;
+} | {
+    kind: 'prop';
+    path: string;
+};
+export type CompositionHook = {
+    kind: 'mount';
+    target: string;
+} | {
+    kind: 'change';
+    source: CompositionChangeSource;
+    target: string;
+    debounceMs: number;
+} | {
+    kind: 'success';
+    runtime: string;
+    target: string;
+};
+export interface CompositionRuntimeOutputDescriptor {
+    key: string;
+    kind: 'runtime';
+    runtime: string;
+    output?: string;
+}
+export interface CompositionScopeOutputDescriptor {
+    key: string;
+    kind: 'scope';
+    scope: string;
+}
+export type CompositionOutputDescriptor = CompositionRuntimeOutputDescriptor | CompositionScopeOutputDescriptor;
+export type CompositionPreviewLiteral = null | string | number | boolean | CompositionPreviewLiteral[] | {
+    [key: string]: CompositionPreviewLiteral;
+};
+export type CompositionPreviewPropValue = {
+    kind: 'literal';
+    value: CompositionPreviewLiteral;
+} | EndgeMockReference;
+export type CompositionPreviewProps = Record<string, CompositionPreviewPropValue>;
+export interface CompositionSourceDocument {
+    activation: CompositionActivationDescriptor | null;
+    /** Публичный props contract Composition. */
+    props: SourceFieldDefinition[];
+    /** Preview-only fixtures. Не являются runtime defaults. */
+    previewProps?: CompositionPreviewProps | null;
+    data: CompositionDataDescriptor[];
+    resources: CompositionResourceDescriptor[];
+    scopes: CompositionScopeDescriptor[];
+    runtimes: CompositionRuntimeDescriptor[];
+    hooks: CompositionHook[];
+    outputs: CompositionOutputDescriptor[];
+}
+/** Добавление data dependency в canonical Composition source. */
+export interface CompositionSourceAddDataPatch {
+    type: 'add-data';
+    name: string;
+    kind: CompositionDataDescriptor['kind'];
+    identity: string;
+}
+/** Добавление owned resource в canonical Composition source. */
+export interface CompositionSourceAddResourcePatch {
+    type: 'add-resource';
+    name: string;
+    kind: CompositionResourceDescriptor['kind'];
+    identity: string;
+}
+/** Добавление runtime dependency в canonical Composition source. */
+export interface CompositionSourceAddRuntimePatch {
+    type: 'add-runtime';
+    name: string;
+    kind: Exclude<CompositionRuntimeKind, 'filter-view'>;
+    identity: string;
+    activation?: CompositionActivationMode;
+}
+/** Одна узкая source-preserving операция над Composition dependencies. */
+export type CompositionSourcePatchOperation = CompositionSourceAddDataPatch | CompositionSourceAddResourcePatch | CompositionSourceAddRuntimePatch;
+/** Composition source patch: одиночная операция или атомарная пачка. */
+export type CompositionSourcePatch = CompositionSourcePatchOperation | CompositionSourcePatchOperation[];
+/** Нормализованная связь input runtime-ноды. */
+export interface CompositionRuntimeInputConnection {
+    targetRuntime: string;
+    targetProp: string;
+    source: CompositionBindingValue;
+}
+/** Явная передача Store data из owner Composition во вложенную Composition. */
+export interface CompositionRuntimeDataConnection {
+    targetRuntime: string;
+    targetData: string;
+    sourceData: string;
+}
+/** Нормализованный trigger логического update runtime-ноды. */
+export interface CompositionRuntimeUpdateConnection {
+    id: string;
+    source: CompositionChangeSource;
+    targetRuntime: string;
+    updateKind: 'run';
+    debounceMs: number;
+}
+/** Запуск target Query после успешного выполнения source Query. */
+export interface CompositionRuntimeSuccessConnection {
+    id: string;
+    sourceRuntime: string;
+    targetRuntime: string;
+    updateKind: 'run';
+}
+/** Публикация output runtime-ноды в Composition data. */
+export interface CompositionRuntimePublicationConnection {
+    id: string;
+    sourceRuntime: string;
+    sourceOutput: string;
+    targetData: string;
+    targetPath: string;
+}
+/** Действие, выполняемое после mount всего графа. */
+export interface CompositionRuntimeMountConnection {
+    targetRuntime: string;
+    updateKind: 'run';
+}
+/** Исполняемый граф Composition, построенный компилятором из source document. */
+export interface CompositionRuntimeGraph {
+    inputs: CompositionRuntimeInputConnection[];
+    dataInputs?: CompositionRuntimeDataConnection[];
+    updates: CompositionRuntimeUpdateConnection[];
+    /** Optional для чтения artifacts, скомпилированных до появления onSuccess. */
+    successes?: CompositionRuntimeSuccessConnection[];
+    publications: CompositionRuntimePublicationConnection[];
+    mounts: CompositionRuntimeMountConnection[];
+}
+/** Payload Composition artifact без runtime state. */
+export interface CompositionProgramPayload extends CompositionSourceDocument {
+    type: 'composition';
+    sourceVersion: number;
+    /** Снимки словарей, которые runtime читает без обращения к Domain. */
+    i18nResources?: CompositionI18nResourceArtifact[];
+    graph: CompositionRuntimeGraph;
+}
+export interface CompositionSourceCompileResult {
+    ast: unknown | null;
+    document: CompositionSourceDocument | null;
+    artifact: CompositionProgramPayload | null;
+    metadata: ProgramMetadataMap;
+    diagnostics: Omit<ProgramDiagnostic, 'entityRef'>[];
+}
+export interface CompositionRuntimeOutputHandle {
+    kind: 'runtime';
+    runtime: RuntimeHost<any, any> | null;
+    output?: string;
+}
+export interface CompositionRuntimeActivationHandle {
+    readonly path: string;
+    readonly state: 'inactive' | 'active' | 'paused' | 'disposed';
+    readonly runtime: RuntimeHost<any, any> | null;
+    activate: () => Promise<RuntimeHost<any, any>>;
+    pause: () => Promise<void>;
+    resume: () => Promise<void>;
+    deactivate: () => Promise<void>;
+    dispose: () => Promise<void>;
+    getOutput: (name: string) => unknown;
+}
+export type CompositionPublicOutputHandle = CompositionRuntimeOutputHandle | CompositionRuntimeActivationHandle | RuntimeScopeHandle;
+export interface CompositionMountOptions {
+    id?: string;
+    /** Значения публичных Composition props для standalone mount. */
+    props?: Record<string, unknown>;
+    /** Явные runtime-id Store instances для data aliases. */
+    dataRuntimes?: Record<string, string>;
+}
+export interface CompositionSession {
+    id: string;
+    host: CompositionRuntimeHost;
+    outputs: Readonly<Record<string, CompositionPublicOutputHandle>>;
+    output: <T = unknown>(name: string) => T | undefined;
+    unmount: () => Promise<void>;
+}

package/dist/domain/types/source/data-view-source.types.d.ts

@@ -0,0 +1,111 @@
+import { ProgramDiagnostic } from '../program/program.types';
+import { ProgramMetadataMap } from '../program/program-metadata.types';
+import { SourceExpressionIR } from './source-expression.types';
+export type DataViewSourceMode = 'manual' | 'pipeline' | 'projection' | 'expression';
+export type DataViewIncrementalRequest = {
+    mode: 'auto';
+} | {
+    mode: 'full';
+} | {
+    mode: 'collection-by-key';
+    key: string;
+};
+export type DataViewMaterializationStrategy = {
+    kind: 'full';
+} | {
+    kind: 'collection-by-key';
+    key: string;
+};
+export interface DataViewSourceDocument {
+    mode: DataViewSourceMode;
+    incremental: DataViewIncrementalRequest;
+    transform?: DataViewManualTransform;
+    steps?: DataViewPipelineStep[];
+    output?: Record<string, SourceExpressionIR>;
+    expression?: SourceExpressionIR;
+}
+export interface DataViewManualTransform {
+    params: string[];
+    body: string;
+}
+export type DataViewPipelineStep = DataViewFromStep | DataViewJoinStep | DataViewMapStep | DataViewSelectStep;
+export interface DataViewSelectStep {
+    type: 'select';
+    expression: SourceExpressionIR;
+}
+export interface DataViewFromStep {
+    type: 'from';
+    source: string;
+    as: string;
+    dataViews?: DataViewRef[];
+}
+export type DataViewRef = DataViewExternalRef | DataViewInlineRef | DataViewLocalRef;
+export interface DataViewExternalRef {
+    kind: 'external';
+    identity: string;
+}
+export interface DataViewInlineRef {
+    kind: 'inline';
+    source: string;
+}
+export interface DataViewLocalRef {
+    kind: 'local';
+    ref: {
+        entityType: 'data-view';
+        id: string | number;
+        identity: string;
+    };
+}
+export interface DataViewJoinStep {
+    type: 'join';
+    source: string;
+    left: string;
+    right: string;
+    as: string;
+}
+export interface DataViewMapStep {
+    type: 'map';
+    spreads: DataViewMapSpread[];
+    fields: Record<string, DataViewExpression>;
+}
+export interface DataViewMapSpread {
+    source: string;
+}
+export type DataViewExpression = DataViewPathExpression | DataViewTemplateExpression | DataViewLiteralExpression | SourceExpressionIR;
+export interface DataViewPathExpression {
+    type: 'path';
+    path: string;
+    operations: DataViewPathOperation[];
+}
+export type DataViewPathOperation = {
+    type: 'find';
+    criteria: Record<string, unknown>;
+} | {
+    type: 'pick';
+    path: string;
+} | {
+    type: 'convert';
+    converter: string;
+    options?: Record<string, unknown>;
+};
+export interface DataViewTemplateExpression {
+    type: 'template';
+    template: string;
+}
+export interface DataViewLiteralExpression {
+    type: 'literal';
+    value: unknown;
+}
+export interface DataViewSourceCompileResult {
+    ast: unknown;
+    document: DataViewSourceDocument | null;
+    artifact: unknown | null;
+    metadata: ProgramMetadataMap;
+    diagnostics: Omit<ProgramDiagnostic, 'entityRef'>[];
+}
+export interface DataViewRunTools {
+    convert: (identity: string, value: unknown, options?: Record<string, unknown>) => unknown;
+    pick: (value: unknown, path: string) => unknown;
+    path: (scope: unknown, path: string) => unknown;
+    template: (template: string, scope?: Record<string, unknown>) => string;
+}

package/dist/domain/types/source/filter-source.types.d.ts

@@ -0,0 +1,55 @@
+import { ProgramDiagnostic } from '../program/program.types';
+import { ProgramMetadataMap } from '../program/program-metadata.types';
+import { SourceExpressionIR, SourceFieldDefinition } from './source-expression.types';
+/** Source-описание Filter v1. */
+export interface FilterSourceDocument {
+    fields: SourceFieldDefinition[];
+    outputs: FilterProgramOutput[];
+}
+/** JSON-output фильтра. */
+export interface FilterProgramJsonOutput {
+    key: string;
+    kind: 'json';
+    expression: SourceExpressionIR;
+}
+/** Локальный predicate, вычисляемый над строкой и state фильтра. */
+export interface FilterProgramPredicateOutput {
+    key: string;
+    kind: 'predicate';
+    expression: SourceExpressionIR;
+}
+export type FilterProgramOutput = FilterProgramJsonOutput | FilterProgramPredicateOutput;
+/** Payload Filter artifact без persisted source и diagnostics envelope. */
+export interface FilterProgramPayload {
+    type: 'filter';
+    sourceVersion: number;
+    fields: SourceFieldDefinition[];
+    defaults: Record<string, SourceExpressionIR | undefined>;
+    outputs: FilterProgramOutput[];
+}
+/** Результат компиляции Filter source. */
+export interface FilterSourceCompileResult {
+    ast: unknown | null;
+    document: FilterSourceDocument | null;
+    artifact: FilterProgramPayload | null;
+    metadata: ProgramMetadataMap;
+    diagnostics: Omit<ProgramDiagnostic, 'entityRef'>[];
+}
+/** Runtime-value одного Filter output. */
+export type FilterRuntimeOutput = {
+    key: string;
+    kind: 'json';
+    value: unknown;
+} | {
+    key: string;
+    kind: 'predicate';
+    test: (row: unknown) => boolean;
+};
+export type FilterRuntimeActionId = 'patch' | 'set' | 'reset' | 'clear';
+export interface FilterRuntimeSetPayload {
+    key: string;
+    value: unknown;
+}
+export interface FilterRuntimeActionHandle {
+    run: (payload?: unknown) => Promise<void>;
+}

package/dist/domain/types/source/index.d.ts

@@ -0,0 +1,8 @@
+export * from './composition-source.types';
+export * from './data-view-source.types';
+export * from './filter-source.types';
+export * from './query-source.types';
+export * from './source-engine.types';
+export * from './source-expression.types';
+export * from './store-source.types';
+export * from './type-source.types';

package/dist/domain/types/source/query-source.types.d.ts

@@ -0,0 +1,88 @@
+import { RQueryAuth } from '../document/query.types';
+import { ProgramDiagnostic, QueryProgramPayload } from '../program/program.types';
+import { DataViewRef } from './data-view-source.types';
+import { ProgramMetadataMap } from '../program/program-metadata.types';
+import { QueryProgramProp, SourceExpressionIR } from './source-expression.types';
+/** Поддерживаемые kind query source v1. */
+export type QuerySourceKind = 'rest';
+/** Static request value or a safe expression evaluated from Query props at runtime. */
+export type QuerySourceRequestValue<T> = T | SourceExpressionIR;
+/** Source-описание HTTP request части REST-запроса. */
+export interface QuerySourceRequest {
+    /** Endpoint или Endge var-token вида {API_URL}. */
+    endpoint: QuerySourceRequestValue<string>;
+    /** REST path. В legacy RQuery это поле хранится как query. */
+    path: QuerySourceRequestValue<string>;
+    /** HTTP method. */
+    method: QuerySourceRequestValue<string>;
+    /** HTTP headers. */
+    headers: QuerySourceRequestValue<Record<string, string>>;
+    /** Auth config. */
+    auth: QuerySourceRequestValue<RQueryAuth>;
+    /** Request timeout. */
+    timeoutMs?: QuerySourceRequestValue<number>;
+    /** Отправлять body как application/x-www-form-urlencoded. */
+    formUrlencoded?: QuerySourceRequestValue<boolean>;
+    /** Безопасный body expression для query source v2. */
+    body?: SourceExpressionIR | null;
+}
+/** Source-описание mock-режима запроса. */
+export interface QuerySourceMock {
+    /** Включены ли mock data. */
+    enabled: boolean;
+    /** Mock payload. */
+    data: unknown;
+}
+export type QueryOutputSource = {
+    type: 'response';
+    path: string | null;
+    expression?: SourceExpressionIR;
+} | {
+    type: 'output';
+    key: string;
+};
+export interface QuerySourceOutput {
+    key: string;
+    source: QueryOutputSource;
+    dataViews: DataViewRef[];
+}
+export type QuerySourceOutputs = QuerySourceOutput[];
+/** Canonical authoring-модель source-only Query v2. */
+export interface QuerySourceDocument {
+    /** Тип source query. */
+    kind: QuerySourceKind;
+    /** Request config. */
+    request: QuerySourceRequest;
+    /** Единственный runtime input contract Query. */
+    props: QueryProgramProp[];
+    /** Ordered output graph: response/output sources and transformations. */
+    outputs: QuerySourceOutputs;
+    /** Mock config. */
+    mock: QuerySourceMock;
+}
+/** Публичные editor-slots, которые query source patcher умеет менять точечно. */
+export type QuerySourcePatchPath = 'kind' | 'request.endpoint' | 'request.path' | 'request.method' | 'request.headers' | 'request.auth' | 'request.timeoutMs' | 'request.formUrlencoded' | 'request.body' | 'props' | 'outputs' | 'mock.enabled' | 'mock.data';
+/** Операция AST-патчинга query source. */
+export interface QuerySourcePatchOperation {
+    /** Изменяемый editor-slot. */
+    path: QuerySourcePatchPath;
+    /** Новое normalized значение, если patcher должен сам напечатать expression. */
+    value?: unknown;
+    /** Готовое source-expression для сложных DSL-значений: env(...), field(...), filter... */
+    expression?: string;
+}
+/** Patch query source: одиночная операция или пачка операций. */
+export type QuerySourcePatch = QuerySourcePatchOperation | QuerySourcePatchOperation[];
+/** Результат компиляции query source. */
+export interface QuerySourceCompileResult {
+    /** Parser-level AST. */
+    ast: unknown | null;
+    /** Canonical authoring-модель. */
+    document: QuerySourceDocument | null;
+    /** Query artifact payload для Endge.program. */
+    artifact: QueryProgramPayload | null;
+    /** Публичная metadata, извлечённая из canonical source. */
+    metadata: ProgramMetadataMap;
+    /** Diagnostics source compiler-а. */
+    diagnostics: Omit<ProgramDiagnostic, 'entityRef'>[];
+}