JinagaClient

The JinagaClient class provides access to Jinaga facts and results. It allows you to store facts, query the local or remote store, and observe changes in the data.

Methods

Create

static JinagaClient Create()

Creates a Jinaga client with no persistent storage or network connection.

Returns:

• A new instance of JinagaClient.

Create with Configuration

static JinagaClient Create(Action<JinagaClientOptions> configure)

Creates a Jinaga client using the provided configuration. The configuration action is used to set properties on the JinagaClientOptions object.

Parameters:

• configure: Lambda function that sets properties on the JinagaClientOptions object.

Returns:

• A new instance of JinagaClient.

Fact

Task<TFact> Fact<TFact>(TFact prototype) where TFact : class

Processes a new fact, stores it locally, and queues it to be sent upstream. Observers are notified to update the user interface.

Parameters:

• prototype: The new fact to be processed.

Returns:

• A copy of the fact as saved.

Exceptions:

• Throws ArgumentNullException if the fact is null.

Hash

string Hash<TFact>(TFact fact)

Computes the hash of a fact.

Parameters:

• fact: The fact of which to compute the hash.

Returns:

• Base 64 encoded SHA-512 hash of the fact.

Query

Task<ImmutableList<TProjection>> Query<TFact, TProjection>(
    Specification<TFact, TProjection> specification,
    TFact given,
    CancellationToken cancellationToken = default) where TFact : class

Retrieves results of a specification from the local cache or upstream.

Parameters:

• specification: Defines which facts to match and how to project them.
• given: The starting point for the query.
• cancellationToken: To cancel the operation.

Returns:

• The results of the query.

Exceptions:

• Throws ArgumentNullException if the starting point (given) is null.

Watch

IObserver Watch<TFact, TProjection>(
    Specification<TFact, TProjection> specification,
    TFact given,
    Action<TProjection> added)
    where TFact : class

Sets up an observer to watch the results of a specification, responding to new facts as they arrive. It returns an IObserver object that can be used to control the observation.

Parameters:

• specification: Defines which facts to match and how to project them.
• given: The starting point for the query.
• added: Called when a result is added.

Returns:

• An observer to control the observation.

Subscribe

IObserver Subscribe<TFact, TProjection>(
    Specification<TFact, TProjection> specification,
    TFact given,
    Action<TProjection> added)
    where TFact : class

Create a persistent connection to the remote replicator and subscribe to changes. When any client pushes a fact, the replicator will notify all subscribers in real time. Subscribe returns an IObserver object that can be used to control the subscription.

Parameters:

• specification: Defines which facts to match and how to project them.
• given: The starting point for the query.
• added: Called when a result is added.

Returns:

• An observer to control the subscription.

Push

Task Push(CancellationToken cancellationToken)

Sends any facts in the queue to the replicator.

Parameters:

• cancellationToken: To cancel the operation.

Returns:

• Resolved when the queue has been emptied.

Unload

Task Unload()

Waits for any background processes to stop.

Returns:

• Resolved when all background processes are finished.

DisposeAsync

ValueTask DisposeAsync()

Disposes of resources asynchronously.

Returns:

• A task representing the asynchronous dispose operation.

Local

LocalJinagaClient Local { get; }

Operate on the local store without making a network connection.

When the Local property is used, all fact operations are handled locally without any attempt to sync with a remote server or replicator. This mode is useful when you want to work entirely offline or avoid network overhead.

SingleUse

Task<T> SingleUse<T>(Func<User, Task<T>> func)

Create some facts owned by a single-use principal. A key pair is generated for the principal and used to sign the facts. The private key is discarded after the facts are saved.

This method allows you to generate facts that are owned by a principal that is only used once. The principal’s key pair is discarded after the facts are saved, ensuring that the private key is never persisted. This is useful in scenarios where temporary ownership or short-lived principals are needed.

Parameters:

• func: A function that saves a set of facts and returns one or more of them. The function receives a User object representing the single-use principal.

Returns:

The result of the function.

Events

OnStatusChanged

delegate void JinagaStatusChanged(JinagaStatus status);
event JinagaStatusChanged OnStatusChanged;

Event that fires when the status of the client changes. It passes a JinagaStatus object that provides information about the current state of the client.

JinagaClientOptions

Options used to configure a JinagaClient. It includes properties like HttpEndpoint, HttpAuthenticationProvider, and LoggerFactory.