HiLang 2.5.0

• .NETStandard 2.0

  • FSharp.Core (>= 9.0.303)
  • FsLexYacc (>= 11.3.0)
  • FsLexYacc.Runtime (>= 11.3.0)
  • Microsoft.CodeAnalysis.CSharp (>= 4.14.0)

https://www.cepheis.com/hiperspace/20251020
## Overview

This release introduced the **message**  element for client/server scenarios where you might want to run a  query on a server and transfer only the final results to a client.  This is especially useful for whole graph queries that select every element that is related to the subject ***node*** for a *butterfly* view.

-----

## Message
The [HiLang Message](https://www.cepheis.com/hiperspace/message) page goes into detail about the structure of *messages*.. but it is worth referring to an example for clarity. The `CustomerCube` *message*  takes a reference to a *Customer* and returns all the information need to display a *hipercube* in a [Web Assembly](https://webassembly.org/) browser client, transfered with [Protobuf](https://protobuf.dev/) compression between client and server
```
message API.CustomerCube
(
   Customer        : Acc.Customer #1
)
{
   CustomerTree    : List<Acc.Customer> #2,
   Sector          : List<Acc.Sector> #3,
   Accounts        : List<Acc.Account> #4 ,

   "Using the generated cube element from Transaction and its dimensions"
   Cube            : List<Acc.Transaction_Cube> #5,

   "Using the generated cube drilldown from cube"
   Drilldown       : List<Acc.Transaction_CubeDrillDown> #6
};
```
**NB** `Cube            : List<Acc.Transaction_Cube>` is a *physical* element, generated from the `Transaction` *@Fact* property, and including the *@Dimension*  {*Customer, Account, Sector*} and *@Measure* analysis properties

When the schema is compiled with [HiLang](HiLang), implementations are not provided for
```
namespace API
{
   public partial class CustomerCube : IMessage
   {
       public Task<IMessage> InvokeAsync(CancellationToken token = default)
       {
       }
       public async IAsyncEnumerable<IMessage> InvokeStreamAsync([EnumeratorCancellation]CancellationToken token = default)
       {
           yield return await InvokeAsync(token);
       }
   }
}
```
which must be added to the schema project to provide implementation for the server-side functions

-----

### HiperSpace
`HiperSpace` has two additional methods that transfer messages through the layers of Hiperspaces, until a server `SubSpace` is found that will execute the message, and return the value
```
       public virtual Task<byte[]> InvokeAsync(byte[] key, CancellationToken token = default) => Task.FromResult(key);
       public virtual IAsyncEnumerable<byte[]> InvokeStreamAsync(byte[] key, CancellationToken token = default) => new byte[][] { key }.ToAsyncEnumerable();
```

### SubSpace
`SubSpace` has the above functions (*because they also implement* `HiperSpace`), plus the domain specific functions needed for code like `var msg = await space.InvokeAsync(new CustomerCube {Customer = myCust}); to be executed on a client.

```
       public async Task<TMessage> InvokeAsync<TMessage>(TMessage item, CancellationToken token = default)
           where TMessage : class, IMessage
       public async IAsyncEnumerable<TMessage> InvokeStreamAsync<TMessage>(TMessage item, [EnumeratorCancellation]CancellationToken token = default)
```
There are no equivalent synchronous messages handling functions because the only reason for using messages is to perform query processing on a server, and Blazor client cannot use any blocking operations.

With this release the *obsolete* function `public abstract object? Get(string sid);`  has been removed, and `Get<object?>(string sid)` should be used instead.


-----

#### Domain implementation
The Domain implementation of `SubSpace` (*generated by HiLang*) includes logic to execute the message logic in the first *domain Space* that has the `RemoteLabel` set to true.  Generated HiLang schema will not compile until the `InvokeAsync` and `InvokeStreamAsync` functions have been added by the implementor.


-----

### HiLang

HiLang `segment` (*many*) and `aspect` (*optionally one*) can be applied to any `entity` to extend the definition of the entity with information that is versioned separately.  Consider the example of [TOGAF](https://github.com/channell/Hiperspace/blob/master/examples/TOGAF/TOGAF.hilang) where every entity type can include any  number of ***Gaps*** each of which have separate storage and references to their `owner` with navigation from the `owner` using the ***Gap*** property.

[HiLang](HiLang) Generates {*ServiceGap, DriverGap, ActorGap, FunctionGap, CapabilityGap, ProductGap, GoalGap, ObjectiveGap, MeasureGap, ActivityGap, EventGap, ProcessGap, ControlGap, ValueStreamGap, CourseOfActionGap, EntityGap, LogicalGap, PhysicalGap, SystemGap, ComponentGap, DeployedGap, PlatformGap, HostGap, InstanceGap*} to provide storage for entity specific versions of the ***Gap***, and *View* to bring togther every different implementation for query together.

When *segment*/*aspect* is only used in a single comtext, we can end-up with very long segment implementation names like `CustomerAccountTransaction` when `Customer` has many `Account` *segments* , which has many `Transaction` segments.  To minimise the generated classes, an additional *step* has been added to HiLang to remove the generated prefix when a segment is only used in one context.

This version changes `CustomerAccountTransaction`  to `Transaction`.  If we subsequently need to add the segment to another *entity*, the prefix would be added back to distinguish different owners of `Transaction`.

**NB** Hiperspace does not  store the name of the *element* with every instance (only the #id is stored), so any change will be transparent.


-----

### LatestSpace
`LatestSpace` is a specialisation fo HeapSpace, that discards history to reduce memory usage.  the main use-case is with  Blazor Web-Assembly clients that have no interest in the history of an Element, but need to hold the durable representation for synchronization at the end of a session.

## References
References to other libraries have been updated