Class ApiClient

API client for interacting with the Virtufin Gateway service. Provides service discovery, method invocation, and event subscription capabilities.

Constructors

constructor

Methods

close deleteBulkState deleteState deleteTrigger getBulkState getConfigService getMethodSchema getState getTrigger invoke invokeJson listConfigServices listMethods listServices listTriggers publish publishWithResult queryState saveState scheduleTrigger subscribeToTopic subscribeToTopics

Constructors

constructor

Methods

close

  • close(): void

    Aborts all shared reply-topic readers. Call when the client is no longer needed; pending publishWithResult callers will time out.

    Returns void

deleteBulkState

  • deleteBulkState(
        service: string,
        keys: string[],
        publishChange?: boolean,
        change?: ChangeNotification,
    ): Promise<DeleteBulkStateResponse>

    Deletes many keys in one round trip. On partial failure status.success is false and failedKeys names the keys that survived -- retry those rather than the whole batch.

    Parameters

    • service: string
    • keys: string[]
    • publishChange: boolean = false
    • Optionalchange: ChangeNotification

    Returns Promise<DeleteBulkStateResponse>

deleteState

  • deleteState(
        service: string,
        key: string,
        opts?: {
            change?: ChangeNotification;
            etag?: string;
            includeValue?: boolean;
            publishChange?: boolean;
        },
    ): Promise<DeleteStateResponse>

    Deletes one state value. Check status.success.

    Parameters

    • service: string
    • key: string
    • Optionalopts: {
          change?: ChangeNotification;
          etag?: string;
          includeValue?: boolean;
          publishChange?: boolean;
      }

    Returns Promise<DeleteStateResponse>

deleteTrigger

  • deleteTrigger(name: string): Promise<DeleteTriggerResponse>

    Deletes a scheduled trigger.

    Parameters

    • name: string

    Returns Promise<DeleteTriggerResponse>

getBulkState

  • getBulkState(service: string, keys: string[]): Promise<GetBulkStateResponse>

    Reads many keys in one round trip.

    Parameters

    • service: string
    • keys: string[]

    Returns Promise<GetBulkStateResponse>

getConfigService

  • getConfigService(name: string): Promise<GetConfigServiceResponse>

    Gets one service's configuration. Throws with NotFound if unregistered.

    Parameters

    • name: string

    Returns Promise<GetConfigServiceResponse>

getMethodSchema

  • getMethodSchema(
        service: string,
        method: string,
        type: string,
    ): Promise<GetMethodSchemaResponse>

    Gets the schema for a specific method.

    Parameters

    • service: string

      The name of the service.

    • method: string

      The name of the method.

    • type: string

      The type of schema to retrieve (e.g., "request" or "response").

    Returns Promise<GetMethodSchemaResponse>

    A promise resolving to the GetMethodSchemaResponse.

getState

  • getState(service: string, key: string): Promise<GetStateResponse>

    Reads one state value. Throws with NotFound if the key does not exist.

    Parameters

    • service: string
    • key: string

    Returns Promise<GetStateResponse>

getTrigger

  • getTrigger(name: string): Promise<GetTriggerResponse>

    Retrieves a scheduled trigger's details.

    Parameters

    • name: string

    Returns Promise<GetTriggerResponse>

invoke

  • invoke(
        service: string,
        method: string,
        requestData: Uint8Array,
    ): Promise<InvokeResponse>

    Invokes a method on a backend service using raw protobuf bytes.

    Parameters

    • service: string

      The name of the target service.

    • method: string

      The name of the method to invoke.

    • requestData: Uint8Array

      The serialized protobuf request data as Uint8Array.

    Returns Promise<InvokeResponse>

    A promise resolving to the InvokeResponse.

invokeJson

  • invokeJson(
        service: string,
        method: string,
        requestData: string,
    ): Promise<InvokeJsonResponse>

    Invokes a method on a backend service using JSON request/response data. This is the recommended method for most use cases.

    Parameters

    • service: string

      The name of the target service.

    • method: string

      The name of the method to invoke.

    • requestData: string

      The JSON serialized request data as string.

    Returns Promise<InvokeJsonResponse>

    A promise resolving to the InvokeJsonResponse.

listConfigServices

  • listConfigServices(): Promise<ListConfigServicesResponse>

    Lists every registered service, including non-dialable entries (those that exist only to resolve Dapr component names). Contrast listServices, which returns only the backends the gateway can invoke.

    Returns Promise<ListConfigServicesResponse>

listMethods

  • listMethods(service: string): Promise<ListMethodsResponse>

    Lists all methods available for a specific service.

    Parameters

    • service: string

      The name of the service to query.

    Returns Promise<ListMethodsResponse>

    A promise resolving to the ListMethodsResponse containing method information.

listServices

  • listServices(): Promise<ListServicesResponse>

    Lists all available services registered with the gateway.

    Returns Promise<ListServicesResponse>

    A promise resolving to the ListServicesResponse containing service names.

listTriggers

  • listTriggers(): Promise<ListTriggersResponse>

    Lists all scheduled triggers.

    Returns Promise<ListTriggersResponse>

publish

  • publish(topic: string, cloudevent: CloudEvent): Promise<PublishResponse>

    Publishes a CloudEvent to a topic via the Pubsub service.

    Parameters

    • topic: string

      The topic name.

    • cloudevent: CloudEvent

      The CloudEvent message to publish.

    Returns Promise<PublishResponse>

    A promise resolving to the PublishResponse.

publishWithResult

  • publishWithResult(
        topic: string,
        cloudevent: CloudEvent,
        replyTopic: string,
        opts?: { correlationId?: string; timeout?: number },
    ): Promise<SubscribeResponse>

    Publishes to a topic and waits for a correlated response on a reply topic. Implements the request-reply pattern over pub/sub using correlation IDs, via the shared per-reply-topic reader started by ensureReplyReader (see its documentation for why the stream is shared rather than per call).

    Parameters

    • topic: string

      The topic to publish the request to. *

    • cloudevent: CloudEvent

      The CloudEvent message to publish. *

    • replyTopic: string

      The topic to listen for responses on. *

    • Optionalopts: { correlationId?: string; timeout?: number }

      Options: timeout (ms, default 30000), correlationId. *

    Returns Promise<SubscribeResponse>

    A promise resolving to the matching SubscribeResponse. *

    Throws

    TimeoutError if no response arrives within the timeout.

queryState

  • queryState(
        service: string,
        query: string,
        limit?: number,
    ): Promise<QueryStateResponse>

    Queries state with Dapr's query-state DSL, e.g. {"filter":{"PREFIX":"workmanager.worker."}}.

    Requires a store whose Dapr component implements the Query API; for Redis/Valkey that means RediSearch plus queryIndexes metadata. Without it every query fails, including Dapr's {} match-everything query -- use getBulkState against known keys instead.

    Parameters

    • service: string
    • query: string
    • limit: number = 0

    Returns Promise<QueryStateResponse>

saveState

  • saveState(
        service: string,
        key: string,
        value: string,
        opts?: {
            change?: ChangeNotification;
            createOnly?: boolean;
            etag?: string;
            includeValue?: boolean;
            publishChange?: boolean;
            ttlSeconds?: number;
        },
    ): Promise<SaveStateResponse>

    Saves a state value. value must be valid JSON.

    Note the split error channel: validation failures throw, while a runtime failure comes back with a gRPC status of OK and status.success === false. Check status.success -- a client that only catches thrown errors will read a failed save as a success.

    With publishChange, a change notification is published after the write. By default that is the Tier 0 state.change topic, which is right for infra state. For domain state (positions, portfolios, orders) pass change with both a topic and a cloudevent: the API publishes your event verbatim to your topic and skips state.change. It cannot build that event itself -- it has the key and the bytes but not the scenario, world markers, clock type or your service identity.

    Tier 0 events carry no version, so a subscriber consuming value without a read-back is assuming writes to that key are serialized. Carry a monotonic token in your own event if you need ordering. Publication is at-most-once and not atomic with the write.

    Parameters

    • service: string
    • key: string
    • value: string
    • Optionalopts: {
          change?: ChangeNotification;
          createOnly?: boolean;
          etag?: string;
          includeValue?: boolean;
          publishChange?: boolean;
          ttlSeconds?: number;
      }
      • Optionalchange?: ChangeNotification

        Publish a domain (Tier 1) event instead of the default state.change notification. Set topic and cloudevent together; see saveState docs.

      • OptionalcreateOnly?: boolean
      • Optionaletag?: string
      • OptionalincludeValue?: boolean
      • OptionalpublishChange?: boolean
      • OptionalttlSeconds?: number

    Returns Promise<SaveStateResponse>

scheduleTrigger

  • scheduleTrigger(
        name: string,
        targetTopic: string,
        opts?: {
            dueTime?: string;
            repeats?: number;
            schedule?: string;
            ttl?: string;
        },
    ): Promise<ScheduleTriggerResponse>

    Schedules a recurring trigger. When it fires, the API publishes an empty CloudEvent to targetTopic.

    Parameters

    • name: string
    • targetTopic: string
    • Optionalopts: { dueTime?: string; repeats?: number; schedule?: string; ttl?: string }

    Returns Promise<ScheduleTriggerResponse>

subscribeToTopic

  • subscribeToTopic(topic: string): AsyncIterable<SubscribeResponse>

    Subscribes to a single pub/sub topic via the Pubsub service.

    Parameters

    • topic: string

      The topic name.

    Returns AsyncIterable<SubscribeResponse>

    An async iterable yielding SubscribeResponse messages.

subscribeToTopics

  • subscribeToTopics(topics: string[]): AsyncIterable<SubscribeResponse>

    Subscribes to multiple pub/sub topics via the Pubsub service.

    Parameters

    • topics: string[]

      List of topic names to subscribe to.

    Returns AsyncIterable<SubscribeResponse>

    An async iterable yielding SubscribeResponse messages.

Settings

Member Visibility

On This Page

Constructors
Methods