@elyx-code/project-logic-tree 0.0.6996 → 0.0.7000

package/dist/tree/state/validate.d.ts

@@ -0,0 +1,467 @@
+import { CallableEntityGenerationTarget, ElementGenerationTarget, EntityId, EntityType, IGenericReference, Reference, UserManagedElementGenerationTarget, IValueReadingEntityGenerationTarget, IPropertyGenerationTarget, IFunctionDeclarationGenerationTarget } from '../../definitions';
+import { default as Zod, SafeParseReturnType } from 'zod';
+import { EntityError, EntityGenerationError } from './error';
+import { ProjectState } from './project';
+import { DefinitionEntityState } from './definition-entity';
+import { PropertyState } from './property';
+import { InputMapState } from './input-map';
+import { ArgumentDeclarationState } from './argument-declaration';
+import { ReturnStatementState } from './return-statement';
+import { BreakStatementState } from './break-statement';
+import { ContinueStatementState } from './continue-statement';
+import { ValueDescriptorState } from './value-descriptor';
+import { IGetConnectionCompatibilityOptions } from '../utils';
+import { CallableEntityState, CallerEntityState, EntityState, EntityWithNamesState, EntityWithValueState, EntryPointEntityState, PassThroughCallableEntityState, UserManagedEntityState, ValueReadingEntityState, ValueWritingEntityState, VariableState } from '.';
+import { IDataTypeCompatible, IDataTypeIncompatibile } from '../utils/data-type';
+import { SearchStatementState } from './search/query/search-statement-state';
+
+type UnkownEntity = {
+    id: string;
+    type: EntityType;
+    [key: string]: any;
+};
+export type GeneratedPayload = ElementGenerationTarget | {
+    id: string;
+} | {
+    type: EntityType;
+} | IGenericReference | {
+    [key: string]: any;
+} | UnkownEntity;
+export declare function validateGeneration(generatedPayload: GeneratedPayload, projectState: ProjectState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+    modifiedData: ElementGenerationTarget | null;
+};
+export declare function generateMutablePropertiesExplanation(entityToUpdate: EntityState): string;
+export declare enum EntityFieldType {
+    MUTABLE_BASE_PROPERTIES = "MUTABLE_BASE_PROPERTIES",
+    INMUTABLE_BASE_PROPERTIES = "INMUTABLE_BASE_PROPERTIES",
+    BASE_PROPERTIES = "BASE_PROPERTIES",
+    MUTABLE_META_PROPERTIES = "MUTABLE_META_PROPERTIES",
+    INMUTABLE_META_PROPERTIES = "INMUTABLE_META_PROPERTIES",
+    META_PROPERTIES = "META_PROPERTIES",
+    MUTABLE_UPSTREAM_PROPERTIES = "MUTABLE_UPSTREAM_PROPERTIES",
+    INMUTABLE_UPSTREAM_PROPERTIES = "INMUTABLE_UPSTREAM_PROPERTIES",
+    UPSTREAM_PROPERTIES = "UPSTREAM_PROPERTIES",
+    MUTABLE_DOWNSTREAM_PROPERTIES = "MUTABLE_DOWNSTREAM_PROPERTIES",
+    INMUTABLE_DOWNSTREAM_PROPERTIES = "INMUTABLE_DOWNSTREAM_PROPERTIES",
+    DOWNSTREAM_PROPERTIES = "DOWNSTREAM_PROPERTIES",
+    PROPERTIES = "PROPERTIES"
+}
+export declare function findEntityTypeWithFieldName(fieldName: string): Map<EntityType, EntityFieldType>;
+export declare function fieldTypeToReadableString(fieldType: EntityFieldType): string;
+export declare function validateGenerationUpdate(generatedPayload: Partial<UserManagedElementGenerationTarget>, entityToUpdate: UserManagedEntityState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+    modifiedData: Partial<UserManagedElementGenerationTarget> | null;
+    messageAddition: string;
+};
+export declare function getBaseSchemaBasedOnType(entity: {
+    type: EntityType;
+    [key: string]: any;
+}): Zod.Schema | null;
+export declare function getGenerationTargetSchemaBasedOnType(entity: {
+    type: EntityType;
+    [key: string]: any;
+}): Zod.Schema | null;
+export declare function validateReferenceObject(reference: Reference): EntityGenerationError[];
+export declare function fromZodParseToEntityGenerationErrors(data: Partial<ElementGenerationTarget> & {
+    id: EntityId;
+    type: EntityType;
+}, result: SafeParseReturnType<any, any>): EntityGenerationError[];
+export declare function validateGenerationTarget(data: ElementGenerationTarget, _: ProjectState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+export declare function validateGeneratedEntityParentIsNotBuiltInEntity(data: ElementGenerationTarget, project: ProjectState): EntityGenerationError[];
+export declare function getReferencedEntityStateOrErrors(data: ElementGenerationTarget, referenceDef: {
+    key: string;
+    types: EntityType[];
+    optional?: boolean;
+}, project: ProjectState): {
+    entityState: EntityState | null;
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+    modifiedData: ElementGenerationTarget;
+};
+export declare function getReferencedEntitiesStateOrErrors(data: ElementGenerationTarget, propertyKey: string, project: ProjectState): {
+    entities: {
+        entityState: EntityState | null;
+        errors: EntityGenerationError[];
+    }[];
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+    modifiedData: ElementGenerationTarget;
+};
+export declare function validateReferenceToOne(data: ElementGenerationTarget, referenceDef: {
+    key: string;
+    types: EntityType[];
+    optional?: boolean;
+}, project: ProjectState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+    modifiedData: ElementGenerationTarget;
+};
+export declare function joinListWithLastSeparator(list: string[], separator: string, lastSeparator: string): string;
+export declare const PASS_THROUGH_CALLABLE_ENTITIES_EXPLANATION: string;
+export declare const ENTRY_POINT_ENTITIES_EXPLANATION: string;
+export declare const CALLER_ENTITIES_EXPLANATION: string;
+export declare const CALLABLE_ENTITIES_EXPLANATION: string;
+export declare const CALLS_UPDATE_EXPLANATION = "Caller to callee relationships can be updated with the 'add_caller' and 'remove_caller' generation action with the properties: 'callerEntityId', a 'calleeEntityId'. For adding a caller, you can optionally add a boolean property 'fromError' (if the caller calls when an error occured in its execution).\nEither of these two actions will only affect the one relationship between the given caller and callee and ignore any others present in either entity.";
+export declare const BREAK_AND_CONTINUE_STATEMENTS_SHAPE_EXPLANATION = "Loops can return values. Similar to a `.map()` in JavaScript. In break and continue statements their data-type and therefore number of 'input-maps' if any, is determined by the output of the parent loop. They all, including the loop itself must return the same data-type.";
+export declare const RETURN_STATEMENT_SHAPE_EXPLANATION = "Return statements need to be identical inside the same scope. For example if a 'return-statement' belongs to a function, with multiple branches of logic, leading to multiple 'return-statement' entities, all of them need to have the exact same amount of 'input-map' entities (if any) and main reading value ('readsValue' field of the return-statement itself), all of which should have the same data-type as their counter-parts in the other branches of the parent function-declaration.\nFurthermore, some 'function-declarations' and all 'global-events' might be implementing a base 'action-descriptor' entity, which defines exactly what shape the returned output must be.\nInput-maps represent properties of an object, if the return-statement isn't returning an object, it shouldn't have any input-maps.";
+export declare const VARIABLE_DATA_TYPE_INFERRANCE_EXPLANATION = "A variable without a data type which reads an-untyped object value, or has object properties written into it as input-map writes, will infere its data-type. This means that a 'data-type' will be created, with an implicitly declared 'definition-entity' as its 'entity' property, defining the structure of the object.\nThis data type entity is what will define which properties are available to be read from the variable or any of its instances as 'output-map' entities.";
+export declare const NON_INTERACTIVE_BASE_ENTITIES_EXPLANATION = "Entities of type 'built-in-base-entity' that have the 'interactive' property set to false cannot be used programmatically during runtime. They can't be used as data types or instanciated in variables. Their methods can't be called by the code, and are only called by the system in the background. Their properties' values are constant and set only once when declared. They also can't be extended with unrecognized properties or methods that aren't part of the base out-of-the-box entity.";
+export declare const VALUE_READING_ENTITIES_EXPLANATION: string;
+export declare const VALUE_WRITING_ENTITIES_EXPLANATION: string;
+export declare const PROPERTY_NOT_VALUE_READER_WRITER_EXPLANATION = "A property entity, is neither a value reading, or a value writing entity, but they are often confused with one.\nBecause a 'property' can have a default value.\nThe 'property' entity only represents the data field in the declaration, and it can't write or read values.\nWhen a 'definition-entity' is instantiated as a variable, any writes or reads to its properties are done through 'input-map's and 'output-map's.";
+export declare const ENTITIES_WITH_VALUES_EXPLANATION: string;
+export declare const AI_VALUE_CONNECTION_GENERATION_ACTION_EXPLANATION = "To establish a connection of a reader and writer value during the generation process you can use the 'connect_values' generation action, like so:\n```json\n{\n\t\"connect_values\": {\n\t\t\"writerEntityId\": \"writer-entity-id\"; // Id of the entity that will give the value\n    \"readerEntityId\": \"reader-entity-id\"; // Id of the entity that will receive the value\n\t}\n}\n```\nYou can use the 'disconnect_values' generation action to remove the connection between two value holding entities in the same way.";
+export declare const PARENT_AUTO_CALCULATION_FROM_CALLER_EXPLANATION = "If an explicit 'parent' isn't given for a callable entity, the scope will be auto-calculated to match the parent scope of the caller entity.\nIf the entity that should be the parent of a callable entity is unclear, you can always skip the 'parent' property and the system will automatically calculate the parent based on the caller entity.";
+export declare const DEFINITION_ENTITIES_EXPLANATION = "Definition entities define object/key-value-pair data-structures and are equivalent to classes in object-oriented programming languages.\nThey can extend and implement other definition entities and built-in-base-entities, inheriting their properties and methods as well as any built-in functionality linked to them.\nFor example.: If one implements the persisted built in entity, it will become an SQL table when the project is published, same with the base endpoint built-in-base entities.\nThey can be instantiated as variables where the data-type has a reference to them in the 'entity' field.\nSome are not interactive and cannot be instantiated or extended.\nThrough their metadata, they can be made 'abstract', 'static', whether they take 'additionalProperties' or not, and other OOP related features.\nIf a definition entity doesn't extend or implement any built-in-base-entity directly or indirectly, it is equivalent to a type declaration in TypeScript and a class in Javascript.";
+export declare const PROPERTY_IMPLEMENTATION_AND_EXTENSION_AUTO_ENRICHMENT_EXPLANATION = "When a 'property' entity is added to a 'definition-entity', the system will automatically enrich the property based on the parent definition-entity's implemented and extended entities.\nThis means that if a property is required, the parent 'definition-entity' will have auto-generated it. If a manually added property can fit into a parent, it will be auto-enriched with any required 'implementation' or 'extension' references, and the data-type will be recalculated or constrained based on said extensions and implementations.\nThis means that manually adding an 'extends' field to a new property is not necessary, and only specific, non-required 'implements' references need to be added manually if needed.";
+export declare const METHOD_IMPLEMENTATION_AND_EXTENSION_AUTO_ENRICHMENT_EXPLANATION = "When a 'function-declaration' entity is added to a 'definition-entity', the system will automatically enrich the function based on the parent definition-entity's implemented and extended entities.\nThis means that if a function is required, the parent 'definition-entity' will have auto-generated it. If a manually added function can fit into a parent, it will be auto-enriched with any required 'implementation' or 'extension' references, and its signature (inputs and output data-type) will be recalculated or constrained based on said extensions and implementations.\nThis means that manually adding an 'extends' or 'implements' field to a new function is not necessary.";
+export declare const EDITING_PROPERTIES_EXPLANATION = "Entities of any type have two types of fields: primitive meta-data fields, and relational fields that point to other entities.\nRelational fields can be upstream or downstream.\nOnly upstream fields are owned and can be edited by the entity itself.\nDownstream fields are owned and edited by the downstream entity that points to this entity.\nFor example, many entities have a 'parent' field that points to their parent entity. Once the parent is set, they show up in one of the downstream fields of the parent entity, like 'inputs' or 'body'.";
+export declare const MUTABLE_META_PROPERTIES_EXPLANATION = "Some meta-data properties of entities can be changed after the initial creation, like 'name', 'description', etc...\nThese are called mutable meta-properties.";
+export declare const INMUTABLE_META_PROPERTIES_EXPLANATION = "Some meta-data properties of entities cannot be changed after the initial creation, like 'type', 'id', etc...\nThese are called inmutable meta-properties.";
+export declare const INMUTABLE_UPSTREAM_PROPERTIES_EXPLANATION = "Some upstream relational properties of entities cannot be changed after the initial creation, like 'parent' for some entities, etc...\nThese are called inmutable upstream properties.";
+export declare const DOWNSTREAM_PROPERTIES_EXPLANATION = "Some fields on an entity point to a downstream/nested entity, which means it is a child of the current entity in the tree. Downstream properties are owned and managed by the downstream entity itself, and cannot be modified directly on the upstream entity.\nFor example, a 'function-declaration' entity has a list of downstream references to its 'argument-declaration' in the property called 'inputs'. To edit the relationship, or modify any of the inputs, the input itself must be targeted directly.";
+export declare const FULL_EDITING_PROPERTIES_EXPLANATION = "Entities of any type have two types of fields: primitive meta-data fields, and relational fields that point to other entities.\nRelational fields can be upstream or downstream.\nOnly upstream fields are owned and can be edited by the entity itself.\nDownstream fields are owned and edited by the downstream entity that points to this entity.\nFor example, many entities have a 'parent' field that points to their parent entity. Once the parent is set, they show up in one of the downstream fields of the parent entity, like 'inputs' or 'body'.\n\nSome meta-data properties of entities can be changed after the initial creation, like 'name', 'description', etc...\nThese are called mutable meta-properties.\n\nSome meta-data properties of entities cannot be changed after the initial creation, like 'type', 'id', etc...\nThese are called inmutable meta-properties.\n\nSome upstream relational properties of entities cannot be changed after the initial creation, like 'parent' for some entities, etc...\nThese are called inmutable upstream properties.\n\nSome fields on an entity point to a downstream/nested entity, which means it is a child of the current entity in the tree. Downstream properties are owned and managed by the downstream entity itself, and cannot be modified directly on the upstream entity.\nFor example, a 'function-declaration' entity has a list of downstream references to its 'argument-declaration' in the property called 'inputs'. To edit the relationship, or modify any of the inputs, the input itself must be targeted directly.";
+export declare const OUTPUT_MAPS_AUTOGENERATION_EXPLANATION = "Output-maps don't ever need to be explicitly created by the user. They are automatically generated to match the shape required by the parent callable entity. For example, a variable that contains an object will have one output-map for each property of the object. Or a function-call or operation will have one output-map for each property of the returned object, if any. ONLY output-maps that have a 'parentRelationType' of 'error' can be added manually, to represent the value of a caught error, and as long as one doesn't already exist in the same parent callable node.";
+export declare const INPUT_MAPS_AUTOGENERATION_EXPLANATION = "Input-maps don't ever need to be explicitly created by the user. They are automatically generated to match the shape required by the parent callable entity. For example, a variable that contains an object will have one input-map for each property of the object. Or a function-declaration or operation will have one input-map for each property of the returned object, if any.";
+export declare const INTERNAL_CALLS_AUTOGENERATION_EXPLANATION = "Internal calls are automatically generated for any method of an applicable definition-entity that is the 'entity' of a data-type of a variable-declaration. So they never need to be created manually.\nTo use an internal call, it is almost always the only correct way, to create a dedicated variable-instance for it, with the 'implement_internal_call' generation action, which will create and instance and wire the call all in once and avoiding generation conflics.";
+export declare const INTERNAL_CALLS_EXPLANATION = "An internal call is a callable entity type that can be called on a variable-instance to trigger the logic of a method (function-declaration in a definition-entity) of its data-type 'entity'.\nInternal calls are equivalent to method calls in other programing languages like Javascript, where you need a class instance initialized with the right state, then you call the method on it.\nIn our case, first we need a 'variable-declaration' with a data-type that has its 'entity' field pointing to a 'definition-entity' that contains a 'function-declaration' method called somewhere earlier in the same scopes' callstack.\nThis variable-declaration acts as the initialization of the class. Only then we can use a SEPARATE variable-instance to call the internal-call on.\nThis is equivalent to calling 'new' on a class to create an instance in Javascript, then calling a method on that instance in the next step. The internal call will have access to the state of the variable-declaration.";
+export declare const REASONS_FOR_METHODS_NOT_AVAILABLE_AS_INTERNAL_CALLS_EXPLANATION = "Not all methods of a definition-entity are available as internal calls. For a method to be available as an internal call its parent definition-entity needs to be the 'entity' of a data-type of a variable. It needs to belong to an 'interactive' definition-entity. It needs to not be part of an abstract definition-entity.";
+export declare const SEARCH_STATEMENT_HYDRATION_EXPLANATION = "The 'query' field of 'search' entities gets stored naively as pure text, but when we interact with it, it gets just-in-time hydration against the existing project state to become a fully typed SQL AST.\nThis means that you can write any raw SQL query in the 'query' field, and the project checks that any column and table references are actually found in the project.\nSpecifically the names of the 'properties' of any 'definition-entity' that implements the \"persisted\" 'built-in-base-entity' are matched against any columns and tables, respectively, found in the query.\nDefinition entity names are turned into table names by converting them to pascal case. For example \"My new Entity\" turns into \"MyNewEntity\".\nProperty names are turned into column names by converting them to camel case. For example \"My new property\" turns into \"myNewProperty\".\nIf any of the referenced tables or columns aren't found in the project, an error is shown and the reference is SAFELY removed from the query.\nSame occurs with interpolated values.\nOnly 'input-map' values belonging to the same parent 'search' entity can be used inside the query. Like so: {{::inputMapId}}.\nIf any of the referenced input-maps aren't found in the parent 'search' entity, they will be ignored and SAFELY removed from the query, no errors are shown.\nA query (and therefore a 'search' entity) can only reference tables in a single database, if two 'definition-entities' that implement the \"persisted\" 'built-in-base-entity' belong to two different parent databases, the table selected first will determine what database is being queried, and the other table won't be available for this query.\nIf any of the referenced entities changes, the project will auto-update the query to reflect the changes.\n\nSQL DIALECT:\nThe hydrator parses the 'query' string with the SQLite dialect. Use SQLite-compatible syntax \u2014 quoted identifiers use double quotes (\"Employee\", \"myColumn\"), string literals use single quotes ('hello'). The hydrator round-trips through AST \u2192 SQL \u2192 AST every time the query changes, so anything that doesn't survive a SQLite-dialect re-parse will be dropped.\n\nSUPPORTED SQL FUNCTIONS:\nA fixed registry of SQL functions is supported. Anything outside this list is unknown to the hydrator and will be dropped on the next round trip. Do NOT invent functions outside this list (no NOW_UTC(), IF(), IIF(), CASE-as-function, STRFTIME(), DATE_ADD(), LEFT(), RIGHT(), SUBSTRING(), REPLACE(), CAST(), NULLIF(), etc. \u2014 none of those are wired up). Function names are case-insensitive but the canonical casing shown below is what gets re-emitted on round trip.\n\nFunctions belong to one of three categories, and the category determines where the function may legally appear:\n- Scalar: usable anywhere a value is expected (SELECT items, WHERE/ON sides, ORDER BY, LIMIT, OFFSET, function arguments).\n- Aggregate: usable in SELECT items and ORDER BY. NOT allowed directly in WHERE/Filter-Condition expressions \u2014 the validator flags this with \"Aggregate functions (like COUNT or SUM) cannot be used directly in Filter Conditions\". HAVING is not implemented yet, so aggregates can currently only filter via a wrapping subquery.\n- Table-valued (set-returning): usable ONLY as a data source in FROM or JOIN, NEVER as a SELECT item or inside WHERE/ON. The validator emits \"Table-Valued functions (like generate_series or unnest) can only be used as Data Sources (in FROM or JOIN), not in the Output Format\" if misplaced.\n\nScalar functions:\n- UPPER(text) \u2014 string \u2192 string. Uppercase.\n- LOWER(text) \u2014 string \u2192 string. Lowercase.\n- LENGTH(text) \u2014 string \u2192 number. Character count.\n- ROUND(value, decimal_places?) \u2014 number, optional number \u2192 number.\n- NOW() \u2014 no args \u2192 date. Current date/time.\n- COALESCE(value1, value2, ...) \u2014 variadic any \u2192 any. First non-null.\n- CONCAT(str1, str2, ...) \u2014 variadic strings (any-typed args are coerced) \u2192 string.\n- json_build_object(key1, value1, key2, value2, ...) \u2014 variadic alternating key/value pairs \u2192 json.\n- row_to_json(record) \u2014 table/any \u2192 json. Wraps a row as a JSON object.\n\nAggregate functions:\n- COUNT(expression) \u2014 any (column ref or * star selector) \u2192 number.\n- MAX(expression) \u2014 number/date/string \u2192 same type.\n- MIN(expression) \u2014 number/date/string \u2192 same type.\n- SUM(expression) \u2014 number \u2192 number.\n- json_agg(expression) \u2014 any \u2192 json. Aggregates values (including nulls) as a JSON array.\n\nTable-valued / set-returning functions:\n- generate_series(start, stop, step?) \u2014 start/stop are number or date; step is optional number. Must appear in FROM or JOIN.\n- unnest(array) \u2014 variadic any. Expands an array (or JSON-array string \u2014 see \"Array literals\" below) into one row per item. Must appear in FROM or JOIN.\nTable-valued data sources require an alias (AS something) and expose a single column reachable as <alias>.value \u2014 that is the column name to use in SELECT items and ON/WHERE expressions referencing the function's output. Example: LEFT JOIN unnest('[1,2,3]') AS arr ON arr.value > 0, and you'd select it as arr.value AS arrItem.\n\nFunctions can be nested freely as long as argument types match (e.g. UPPER(COALESCE(myCol, 'fallback')), LENGTH(CONCAT('prefix-', myCol)), ROUND(SUM(price), 2)). Argument type-matching is lenient about castable types: UUID, enum, date, and JSON values are accepted where 'string' is expected (they get coerced at the SQL layer), and a 'number' is accepted where 'date' is expected.\n\nLITERAL VALUES INSIDE QUERIES:\nSupported in expressions: strings ('text'), numbers (42, 3.14), booleans (true/false), NULL, dates (ISO-8601 strings), and arrays. Arrays are serialised as a SINGLE-QUOTED JSON-array string for SQLite compatibility \u2014 SQLite has no native array type, so an array literal must be written as e.g. '[1,2,3]' or '[\"a\",\"b\",\"c\"]' and consumed via unnest('[1,2,3]') or similar. Nested arrays ('[[1,2],[3,4]]') are allowed. A literal that fails its own internal validity (e.g. an empty string, or an array with an invalid item) is dropped during hydration the same way a missing column would be.\n\nJOINS AND MERGES:\nAll standard JOIN types are supported: INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN, SELF JOIN, NATURAL JOIN. Each JOIN requires an alias on its right-hand data source (... AS Something). For everything except CROSS JOIN and NATURAL JOIN, an ON <condition> clause is required; without one, the JOIN is treated as in-progress and the hydrator falls back to ON 1 = 1 so the SQL stays parseable through the round trip. If you omit the alias, the entire JOIN is dropped silently \u2014 always emit an alias.\n\nData sources for the main FROM and for each JOIN can be:\n1) A table (the PascalCase definition-entity name).\n2) A nested subquery wrapped in parentheses: FROM (SELECT ...) AS aliasName or JOIN (SELECT ...) AS aliasName ON .... Nested subqueries can themselves contain joins and further nested subqueries \u2014 there is no depth limit. Every nested subquery MUST be given an alias; without one the hydrator drops it.\n3) A table-valued function call (see above), which also requires an alias.\n\nA query as a whole \u2014 and any nested subquery \u2014 must have a valid main data source in its FROM clause, otherwise the entire (sub)query is treated as invalid and dropped on the next round trip.\n\nWHERE, ORDER, LIMIT, OFFSET:\nThe query may include a WHERE clause with arbitrary AND/OR nesting using parentheses. Both sides of a comparison can be a column reference, a literal, an input-map interpolation ({{::inputMapId}}), or a scalar/table-valued function-call result (with the category restrictions above). ORDER BY accepts column references and scalar/aggregate function calls and supports ASC/DESC. LIMIT and OFFSET accept either an integer literal or an input-map interpolation.\n\nINTERPOLATION DETAILS:\n{{::inputMapId}} is replaced at runtime with the input-map's resolved value. Strings, numbers, booleans, dates, and JSON-stringified arrays/objects are all supported. The interpolation token is emitted in the SQL as a single-quoted string ('{{::...}}') regardless of the underlying type \u2014 the runtime substitutes the real typed value before execution. Interpolations may appear anywhere a literal could: SELECT items, WHERE/ON sides, ORDER BY, LIMIT, OFFSET, function arguments, etc.\n\nCOLUMN-REFERENCE SYNTAX:\nAlways qualify columns with their source: Employee.id, arr.value, OrgJoin.someColumn. A bare unqualified column name is harder for the hydrator to attribute and may be dropped. For columns coming from a JOIN-aliased subquery, reference them by the JOIN's alias and the subquery's SELECT alias (e.g. if (SELECT User.id AS userId FROM User) AS NestedUser, reference it as NestedUser.userId, not NestedUser.id).\n\nThe SELECT clause should use <source>.<column> AS <outputName> aliasing for every column you want surfaced \u2014 outputs without an AS alias may collide or be dropped. Output aliases must use only letters, numbers, and underscores, must not be SQL reserved keywords, and must be 50 characters or fewer. Duplicate output aliases within the same SELECT are flagged and the duplicates ignored.\n\nVALIDATION RULES TO KEEP IN MIND:\n- A column reference whose PascalCase/camelCase name doesn't exist on the targeted definition-entity is dropped with a 'column not-found' error.\n- A table reference whose PascalCase name doesn't exist (or whose entity doesn't implement the \"persisted\" built-in-base-entity) is dropped with a 'table not-found' error.\n- A JOIN missing either its data source or its alias is dropped.\n- An ON clause referencing columns from outside the JOIN's scope is dropped.\n- Mixing aggregate functions and raw columns in the same SELECT without proper grouping (the \"Giant Bucket\" rule) emits a validation error.\n- Aggregate functions in WHERE / Filter Conditions emit a validation error.\n- Table-valued functions in SELECT / Output Format emit a validation error.";
+export declare const PERSISTED_ENTITIES_EXPLANATION: string;
+export declare const ATTACHING_PERSISTED_ENTITIES_TO_DATABASES_EXPLANATION: string;
+export declare enum GenerationExplanationIds {
+    PassThroughCallableEntities = "pass-through-callable-entities-explanation",
+    EntryPointEntities = "entry-point-entities-explanation",
+    CallerEntities = "caller-entities-explanation",
+    CallableEntities = "callable-entities-explanation",
+    CallsUpdate = "calls-update-explanation",
+    BreakAndContinueStatements = "break-and-continue-statements-explanation",
+    ReturnStatement = "return-statement-explanation",
+    VariableDataTypeInferrance = "variable-data-type-inferrance-explanation",
+    NonInteractiveBaseEntities = "non-interactive-base-entities-explanation",
+    ValueReadingEntities = "value-reading-entities-explanation",
+    ValueWritingEntities = "value-writing-entities-explanation",
+    PropertyNotValueReaderWriter = "property-not-value-reader-writer-explanation",
+    EntitiesWithValues = "entities-with-values-explanation",
+    AIValueConnectionGenerationAction = "ai-value-connection-generation-action-explanation",
+    ParentAutoCalculationFromCaller = "parent-auto-calculation-from-caller-explanation",
+    DataTypeEntityField = "data-type-entity-field-explanation",
+    DataTypeEntityFieldOptions = "data-type-entity-field-options-explanation",
+    PropertyParentField = "property-parent-field-explanation",
+    PropertyParentFieldOptions = "property-parent-field-options-explanation",
+    MethodParentFieldOptions = "method-parent-field-options-explanation",
+    AllAvailableValueReaderEntities = "all-available-value-reader-entities-explanation",
+    AllAvailableValueWriterEntities = "all-available-value-writer-entities-explanation",
+    AvailableValueReadersForGivenWriter = "available-value-readers-for-given-writer-explanation",
+    AvailableValueWritersForGivenReader = "available-value-writers-for-given-reader-explanation",
+    AllAvailableCallableEntities = "all-available-callable-entities-explanation",
+    AllAvailableEntryPointEntities = "all-available-entry-point-entities-explanation",
+    AllAvailablePassThroughCallableEntities = "all-available-pass-through-callable-entities-explanation",
+    AllAvailableCallerEntities = "all-available-caller-entities-explanation",
+    AllAvailableTerminationEntities = "all-available-termination-entities-explanation",
+    AllAvailableCallerEntitiesForGivenCallee = "all-available-caller-entities-for-given-callee-explanation",
+    AllAvailableCalleeEntitiesForGivenCaller = "all-available-callee-entities-for-given-caller-explanation",
+    AllAvailableGlobalFunctionDeclarationsForFunctionCall = "all-available-global-function-declarations-for-function-call-explanation",
+    AllNoneInteractiveBaseEntities = "all-non-interactive-base-entities-explanation",
+    AllOperationActionDescriptors = "all-operation-action-descriptors-explanation",
+    AllConditionActionDescriptors = "all-condition-action-descriptors-explanation",
+    AllLoopActionDescriptors = "all-loop-action-descriptors-explanation",
+    AllGlobalEventsActionDescriptors = "all-global-events-action-descriptors-explanation",
+    DefinitionEntities = "definition-entities-explanation",
+    PropertyImplementationAndExtensionAutoEnrichment = "property-implementation-and-extension-auto-enrichment-explanation",
+    MethodImplementationAndExtensionAutoEnrichment = "method-implementation-and-extension-auto-enrichment-explanation",
+    ActualOwnersOfMisplacedProperties = "actual-owners-of-misplaced-properties-explanation",
+    EditingProperties = "editing-properties-explanation",
+    MutableMetaProperties = "mutable-meta-properties-explanation",
+    InmutableMetaProperties = "inmutable-meta-properties-explanation",
+    InmutableUpstreamProperties = "inmutable-upstream-properties-explanation",
+    DownstreamProperties = "downstream-properties-explanation",
+    FullEditingProperties = "full-editing-properties-explanation",
+    OutputMapsAutogeneration = "output-maps-autogeneration-explanation",
+    AvailableOutputMapsForGivenParentCallableEntity = "available-output-maps-for-given-parent-callable-entity-explanation",
+    InputMapsAutogeneration = "input-maps-autogeneration-explanation",
+    InternalCallsAutogeneration = "internal-calls-autogeneration-explanation",
+    AvailableInputMapsForGivenParentCallableEntity = "available-input-maps-for-given-parent-callable-entity-explanation",
+    AvailableInternalCallsForGivenVariablesDataTypeEntity = "available-internal-calls-for-given-variables-data-type-entity-explanation",
+    NonAvailableInternalCallsWithSameDeclarationInExistingInstanciatedVariables = "non-available-internal-calls-with-same-declaration-in-existing-instanciated-variables-explanation",
+    AvailableInternalCallsWithSameDeclarationInExistingInstanciatedVariables = "available-internal-calls-with-same-declaration-in-existing-instanciated-variables-explanation",
+    AvailableInternalCallsOfAnyDeclarationInAllInstanciatedVariablesDataTypeEntities = "available-internal-calls-of-any-declaration-in-all-instanciated-variables-data-type-entities-explanation",
+    AllAvailableMethodsThatCanBeCalledAsInternalCalls = "all-available-methods-that-can-be-called-as-internal-calls",
+    InternalCalls = "internal-calls-explanation",
+    ReasonsForMethodsNotAvailableAsInternalCalls = "reasons-for-methods-not-available-as-internal-calls-explanation",
+    AllNonInteractiveDefinitionEntities = "all-non-interactive-definition-entities-explanation",
+    AllStaticAndAbstractDefinitionEntities = "all-static-and-abstract-definition-entities-explanation",
+    AllStaticNonAbstractDefinitionEntities = "all-static-non-abstract-definition-entities-explanation",
+    AllAbstractNonStaticDefinitionEntities = "all-abstract-non-static-definition-entities-explanation",
+    AllInstanciatableDefinitionEntities = "all-instantiatable-definition-entities-explanation",
+    AutoReplacedExistingValueWriterForNewGiven = "auto-replaced-existing-value-writer-for-new-given-explanation",
+    AutoResolvedCalledByBasedOnValueWriter = "auto-resolved-calledBy-based-on-value-writer-explanation",
+    AllAvailableColumnNamesForSQLEnrichmentInCurrentQuery = "all-available-column-names-for-sql-enrichment-in-current-query-explanation",
+    AllPropertiesThatCouldBeSelectedAsColumnsInSQLQuery = "all-properties-that-could-be-selected-as-columns-in-sql-query-explanation",
+    AllTableNamesForSQLEnrichmentForGivenDatabase = "all-table-names-for-sql-enrichment-for-given-database-explanation",
+    AllTableNamesForSQLEnrichment = "all-table-names-for-sql-enrichment-explanation",
+    SearchStatementHydration = "search-statement-hydration-explanation",
+    PersistedEntities = "persisted-entities-explanation",
+    AttachingPersistedEntitiesToDatabases = "attaching-persisted-entities-to-databases-explanation",
+    FullSQLSelectableBreakdown = "full-sql-selectable-breakdown-explanation",
+    CurrentlyUnattachedPersistedEntities = "currently-unattached-persisted-entities-explanation",
+    ReferencedInputDeclarationReplacedWithInputMapInQuery = "referenced-input-declaration-replaced-with-input-map-in-query-explanation"
+}
+export declare function asGenerationActionExample(payload: Record<string, any> | string): string;
+export declare function generateActionExample(actionName: string, properties: Record<string, string>): string;
+export declare function generateAllAvailableCallersExplanation(project: ProjectState, callee: CallableEntityState | null, fromError?: boolean, options?: IGetConnectionCompatibilityOptions): Promise<{
+    explanations: {
+        id: GenerationExplanationIds.AllAvailableCallerEntitiesForGivenCallee | GenerationExplanationIds.AllAvailableCallerEntities;
+        message: string;
+    }[];
+}>;
+export declare function generateAllAvailableCalleesExplanation(project: ProjectState, caller: CallerEntityState | null, fromError?: boolean, options?: IGetConnectionCompatibilityOptions): Promise<{
+    explanations: {
+        id: GenerationExplanationIds.AllAvailableCalleeEntitiesForGivenCaller | GenerationExplanationIds.AllAvailableCallableEntities;
+        message: string;
+    }[];
+}>;
+export declare function validateSuccessCaller(data: CallableEntityGenerationTarget, callerEntity: CallerEntityState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+    modifiedData: CallableEntityGenerationTarget;
+};
+export declare function validateErrorCaller(data: ElementGenerationTarget, callerEntity: CallerEntityState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+export declare function validateEntryCaller(data: ElementGenerationTarget, callerEntity: CallerEntityState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+export declare function validateCallers(data: ElementGenerationTarget, project: ProjectState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+    modifiedData: ElementGenerationTarget;
+};
+export declare function validateValueWriter(data: ElementGenerationTarget, valueWriterEntity: ValueWritingEntityState): EntityGenerationError[];
+export declare function validateReferences(data: ElementGenerationTarget, referenceDefs: {
+    [key: string]: {
+        types: EntityType[];
+        list: boolean;
+        optional?: boolean;
+    };
+}, project: ProjectState, ignoreDefaultValidations?: boolean): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+    modifiedData: ElementGenerationTarget;
+};
+export declare function validateCalledByIdInAction(calledById: EntityId, project: ProjectState, propertyName?: string): EntityGenerationError[];
+export declare function validateCalledByErrorIdInAction(calledByErrorId: EntityId, project: ProjectState, propertyName?: string): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+export declare function validateReadsValueInActionPayload(readsValue: EntityId, project: ProjectState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+export declare function getAllGloballyDeclaredFunctionDeclarationsExplanation(project: ProjectState): string;
+export declare function getAllActionDescriptorsForGlobalEventsListExplanation(project: ProjectState): string;
+export declare function getAllAvailableParentsForFunctionDeclarationExplanation(data: IFunctionDeclarationGenerationTarget, project: ProjectState): {
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+/**
+ * Returns a human readable explanation of all available parent entities that can own a new property entity.
+ * The new data for the property to be created can be used to filter the list of available parents.
+ * For example if the property 'implements', 'extends', is 'static' or 'abstract', or has a set 'parentRelationType' field, we can reduce the options
+ *
+ * @param data
+ * @param project
+ * @returns
+ */
+export declare function getAllAvailableParentsForPropertyExplanation(data: IPropertyGenerationTarget, project: ProjectState): {
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+export declare function getAvailableValueReadersForGivenWritter(project: ProjectState, valueWriterEntity: ValueWritingEntityState, options?: IGetConnectionCompatibilityOptions): Promise<{
+    explanations: {
+        id: GenerationExplanationIds.AvailableValueReadersForGivenWriter | GenerationExplanationIds.EntitiesWithValues;
+        message: string;
+    }[];
+}>;
+export declare function getAvailableValueWritersForGivenReader(project: ProjectState, valueReaderEntity: ValueReadingEntityState, options?: IGetConnectionCompatibilityOptions): Promise<{
+    explanations: {
+        id: GenerationExplanationIds.AvailableValueWritersForGivenReader | GenerationExplanationIds.EntitiesWithValues;
+        message: string;
+    }[];
+}>;
+export declare function getAllAvailableValueReaderEntities(project: ProjectState): {
+    explanations: {
+        id: GenerationExplanationIds.AllAvailableValueReaderEntities | GenerationExplanationIds.EntitiesWithValues;
+        message: string;
+    }[];
+};
+export declare function getAllValueWriterEntities(project: ProjectState): {
+    explanations: {
+        id: GenerationExplanationIds.AllAvailableValueWriterEntities | GenerationExplanationIds.EntitiesWithValues;
+        message: string;
+    }[];
+};
+export declare function getFullSQLSelectableBreakdown(project: ProjectState): {
+    explanations: {
+        id: GenerationExplanationIds.FullSQLSelectableBreakdown | GenerationExplanationIds.PersistedEntities | GenerationExplanationIds.AttachingPersistedEntitiesToDatabases;
+        message: string;
+    }[];
+};
+export declare function getAllColumnNamesSelectableInQueryExplanation(state: SearchStatementState, project: ProjectState): {
+    explanations: {
+        id: GenerationExplanationIds.AllAvailableColumnNamesForSQLEnrichmentInCurrentQuery;
+        message: string;
+    }[];
+};
+export declare function getAllTableNamesForGivenDatabaseExplanation(database: DefinitionEntityState): {
+    explanations: {
+        id: GenerationExplanationIds.AllTableNamesForSQLEnrichmentForGivenDatabase | GenerationExplanationIds.PersistedEntities | GenerationExplanationIds.AttachingPersistedEntitiesToDatabases;
+        message: string;
+    }[];
+};
+export declare function getAllActionDescriptorsForLoopsListExplanation(project: ProjectState): string;
+export declare function getAllActionDescriptorsForOperationsListExplanation(project: ProjectState): string;
+export declare function getAllActionDescriptorsForConditionsListExplanation(project: ProjectState): string;
+export declare function validateFunctionCallDeclaration(functionDeclarationId: EntityId, project: ProjectState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+export declare function validateOperationEntityDeclaration(operationDeclarationId: EntityId, project: ProjectState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+export declare function validateConditionEntityDeclaration(conditionDeclarationId: EntityId, project: ProjectState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+export declare function validateLoopEntityDeclaration(loopDeclarationId: EntityId, project: ProjectState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+};
+export declare function dataTypeCompatibilityToErrorExplanation(entityWithValueA: EntityWithValueState, entityWithValueB: EntityWithValueState, compatibility: IDataTypeCompatible | IDataTypeIncompatibile): string;
+export declare function validateValueReaderGenerationUpdate(data: Partial<IValueReadingEntityGenerationTarget>, self: ValueReadingEntityState): {
+    errors: EntityGenerationError[];
+    explanations: {
+        id: GenerationExplanationIds;
+        message: string;
+    }[];
+    modifiedData: Partial<IValueReadingEntityGenerationTarget>;
+};
+/**
+ * Validates whether the callable entity is reachable from the project's closest entry point
+ *
+ * @param {PassThroughCallableEntityState} self
+ * @returns {EntityError[]}
+ */
+export declare function validateReachability(self: PassThroughCallableEntityState): EntityError[];
+/**
+ * Validates the error handling of the callable entity
+ * If a parent scope should return, then the current entity can't catch and not call another entity
+ * Because that means there is a branch without a return
+ *
+ * @param {PassThroughCallableEntityState} self
+ * @returns {EntityError[]}
+ */
+export declare function validateErrorHandling(self: PassThroughCallableEntityState): EntityError[];
+/**
+ * Validates that if the current entity ends its branch, it meets the output data-type of the parent
+ *
+ * @param {PassThroughCallableEntityState} self
+ * @returns {EntityError[]}
+ */
+export declare function validateBranchTerminations(self: PassThroughCallableEntityState): EntityError[];
+export declare function validateMissingValue(self: EntityWithValueState): EntityError[];
+export declare function validateWithCodeNativeValueValidation(self: ArgumentDeclarationState | InputMapState | ReturnStatementState | BreakStatementState | ContinueStatementState | PropertyState | ValueDescriptorState): EntityError[];
+export declare function hasMissingValue(self: EntityWithValueState): boolean;
+export declare function validateVariableInternalCallUse(self: VariableState): EntityError[];
+export declare function getOnlyRelevantErrorsForPublication(project: ProjectState): EntityError[];
+/**
+ * Checks whether a the scope owner requires all branches to end in return.
+ *
+ * This could be because of its type signature or because there is already one or more returns that would create a race condition
+ * for any branches not connected to it.
+ *
+ * @param {PassThroughCallableEntityState} self
+ * @returns
+ */
+export declare function checkParentEntryPointRequiresEndingBranchesInReturn(self: PassThroughCallableEntityState): boolean;
+/**
+ * Validates that if the entity implements a descriptor with return values,
+ * it has a termination on every branch
+ *
+ * @param {EntryPointEntityState} self
+ * @returns {EntityError[]}
+ */
+export declare function validateEntryPointsTermination(self: EntryPointEntityState): EntityError[];
+export declare function validateCallableEntityShouldCallReturnStatement(self: CallableEntityState): EntityError[];
+/**
+ * Holds keywords that are forbidden (so far in Javascript) to be used as names for entities.
+ * This is used to validate the names of entities, such as functions, variables, etc.
+ * For example, a property named "class", or "function" is forbidden, because those are reserved keywords in Javascript.
+ */
+export declare const FORBIDDEN_KEYWORDS: string[];
+export declare function validateEntityName(self: EntityWithNamesState, toCodeNameTransformers?: ((name: string) => string)[], otherRelevantEntitiesInNameSpace?: EntityWithNamesState[], newName?: string | null): EntityError[];
+export {};

package/dist/tree/state/value-descriptor/index.d.ts

@@ -0,0 +1,3 @@
+export * from './value-descriptor';
+import * as valueDescriptorValidation from './validation/logic-validation';
+export { valueDescriptorValidation };

package/dist/tree/state/value-descriptor/init.d.ts

@@ -0,0 +1,4 @@
+import { ProjectState } from '../project';
+import { ValueDescriptorState } from './value-descriptor';
+
+export declare function initAllBuiltInValueDescriptors(project: ProjectState): ValueDescriptorState[];

package/dist/tree/state/value-descriptor/validation/logic-validation.d.ts

@@ -0,0 +1,6 @@
+import { YieldOptions } from '@elyx-code/common-ts-utils';
+import { EntityError } from '../../error';
+import { ValueDescriptorState } from '../value-descriptor';
+
+export declare function validateAsync(self: ValueDescriptorState, options?: YieldOptions): Promise<EntityError[]>;
+export declare function validate(self: ValueDescriptorState): EntityError[];