@actyx/sdk/lib/types/various.d.ts

Actyx SDK

import { Ord } from 'fp-ts/lib/Ord';
import { OffsetMap } from './offsetMap';
import { Tags } from './tags';
/**
 * An Actyx source id.
 * @public
 */
export declare type NodeId = string;
/**
 * `SourceId` associated functions.
 * @public
 */
export declare const NodeId: {
    /**
     * Creates a NodeId from a string
     */
    of: (text: string) => NodeId;
    /**
     * Creates a random SourceId with the given number of digits
     */
    random: (digits?: number | undefined) => string;
    streamNo: (nodeId: NodeId, num: number) => string;
};
/**
 * An Actyx stream id.
 * @public
 */
export declare type StreamId = string;
/**
 * `SourceId` associated functions.
 * @public
 */
export declare const StreamId: {
    /**
     * Creates a StreamId from a string
     */
    of: (text: string) => StreamId;
    /**
     * Creates a random StreamId off a random NodeId.
     */
    random: () => string;
};
/**
 * An Actyx app id.
 * @public
 */
export declare type AppId = string;
/**
 * `AppId` associated functions.
 * @public
 */
export declare const AppId: {
    /**
     * Creates a AppId from a string
     */
    of: (text: string) => AppId;
};
/**
 * Lamport timestamp, cf. https://en.wikipedia.org/wiki/Lamport_timestamp
 * @public
 */
export declare type Lamport = number;
/** @public */
export declare const Lamport: {
    of: (value: number) => Lamport;
    zero: number;
};
/** Offset within an Actyx event stream.
 * @public */
export declare type Offset = number;
/** Functions related to Offsets.
 * @public */
export declare const Offset: {
    of: (n: number) => Offset;
    zero: number;
    /**
     * A value that is below any valid Offset
     */
    min: number;
    /**
     * A value that is above any valid Offset
     */
    max: number;
};
/** Timestamp (UNIX epoch), MICROseconds resolution.
 * @public */
export declare type Timestamp = number;
/** Helper functions for making sense of and converting Timestamps.
 * @public */
export declare const Timestamp: {
    of: (time: number) => Timestamp;
    zero: number;
    maxSafe: number;
    now: (now?: number | undefined) => number;
    format: (timestamp: Timestamp) => string;
    toSeconds: (value: Timestamp) => number;
    toMilliseconds: (value: Timestamp) => Milliseconds;
    toDate: (value: Timestamp) => Date;
    fromDate: (date: Date) => Timestamp;
    fromDays: (value: number) => number;
    fromSeconds: (value: number) => number;
    fromMilliseconds: (value: number) => number;
    min: (...values: Timestamp[]) => number;
    max: (values: Timestamp[]) => number;
};
/** Some number of milliseconds.
 * @public */
export declare type Milliseconds = number;
/** Helper functions for making sense of and converting Milliseconds.
 * @public */
export declare const Milliseconds: {
    of: (time: number) => Milliseconds;
    fromDate: (date: Date) => Milliseconds;
    zero: number;
    now: (now?: number | undefined) => Milliseconds;
    toSeconds: (value: Milliseconds) => number;
    toTimestamp: (value: Milliseconds) => Timestamp;
    fromSeconds: (value: number) => number;
    fromMinutes: (value: number) => number;
    fromAny: (value: number) => Milliseconds;
};
/**
 * Triple that Actyx events are sorted and identified by.
 *
 * @public
 */
export declare type EventKey = {
    lamport: Lamport;
    offset: Offset;
    stream: StreamId;
};
/** Functions related to EventKey.
 * @public */
export declare const EventKey: {
    zero: EventKey;
    ord: Ord<EventKey>;
    format: (key: EventKey) => string;
};
/** Generic Metadata attached to every event.
 * @public */
export declare type Metadata = {
    isLocalEvent: boolean;
    tags: string[];
    timestampMicros: Timestamp;
    timestampAsDate: () => Date;
    lamport: Lamport;
    eventId: string;
    appId: AppId;
    stream: StreamId;
    offset: Offset;
};
/**
 * Cancel an ongoing aggregation (the provided callback will stop being called).
 * @public
 */
export declare type CancelSubscription = () => void;
/**
 * Allows you to register actions for when event emission has completed.
 * @public
 */
export declare type PendingEmission = {
    subscribe: (whenEmitted: (meta: Metadata[]) => void) => void;
    toPromise: () => Promise<Metadata[]>;
};
/** An event with tags attached.
 * @public */
export declare type TaggedEvent = {
    tags: string[];
    event: unknown;
};
/** A typed event with tags attached.
 * @public */
export interface TaggedTypedEvent<E = unknown> extends TaggedEvent {
    readonly tags: string[];
    readonly event: E;
    withTags<E1>(tags: Tags<E1> & (E extends E1 ? unknown : never)): TaggedTypedEvent<E>;
}
/** An event with its metadata.
 * @public */
export declare type ActyxEvent<E = unknown> = {
    meta: Metadata;
    payload: E;
};
/** Things related to ActyxEvent.
 * @public */
export declare const ActyxEvent: {
    ord: Ord<ActyxEvent<unknown>>;
};
/**
 * A raw Actyx event to be emitted by the TestEventStore, as if it really arrived from the outside.
 * @public
 */
export declare type TestEvent = {
    offset: number;
    stream: string;
    timestamp: Timestamp;
    lamport: Lamport;
    tags: string[];
    payload: unknown;
};
/**
 * A chunk of events, with lower and upper bound.
 * A call to `queryKnownRange` with the included bounds is guaranteed to return exactly the contained set of events.
 * A call to `subscribe` with the included `lowerBound`, however, may find new events from sources not included in the bounds.
 *
 * @public
 */
export declare type EventChunk = {
    /** The event data. Sorting depends on the request which produced this chunk. */
    events: ActyxEvent[];
    /** The lower bound of the event chunk, independent of its sorting in memory. */
    lowerBound: OffsetMap;
    /** The upper bound of the event chunk, independent of its sorting in memory. */
    upperBound: OffsetMap;
};
/** Options used when creating a new `Actyx` instance.
 * @public */
export declare type ActyxOpts = {
    /** Host of the Actxy service. This defaults to localhost and should stay localhost in almost all cases. */
    actyxHost?: string;
    /** API port of the Actyx service. Defaults to 4454. */
    actyxPort?: number;
    /** Hook, when the connection to the store is closed */
    onConnectionLost?: () => void;
    /**
     * Hook, when the connection to the store has been established.
     */
    onConnectionEstablished?: () => void;
};
/**
 * Test tool.
 * @beta
 */
export declare type TimeInjector = (tags: string[], events: unknown) => Timestamp;
/** Options used when creating a new TEST `Actyx` instance.
 * @public */
export declare type ActyxTestOpts = {
    /** Local node id to use
     * @public */
    nodeId?: NodeId;
    /** Install the given time source for test purposes
     * @beta */
    timeInjector?: TimeInjector;
};
/** Manifest describing an Actyx application. Used for authorizing API access.
 * @public */
export declare type AppManifest = {
    /**
     * Structured application id.
     * For testing and development purposes, you can always pass 'com.example.somestring'
     * For production, you will buy a license from Actyx for your specific app id like com.my-company.my-app.
     */
    appId: string;
    /** Arbitrary string describing the app. */
    displayName: string;
    /** Arbitrary version string */
    version: string;
    /** Manifest signature, if it’s not an example app. */
    signature?: string;
};
/**
 * Sort order for persisted events.
 * @public
 */
export declare enum EventsSortOrder {
    /** Strictly ascending, meaning events are strictly ordered by eventId. */
    Ascending = "asc",
    /** Strictly descending, meaning events are strictly ordered by eventId, reverse. */
    Descending = "desc",
    /** Ascending per stream, meaning between different streams there is no specific order guaranteed. */
    StreamAscending = "stream-asc"
}
/** AQL message describing the offsets at the current state of the response stream.
 * @beta */
export declare type AqlOffsetsMsg = {
    type: 'offsets';
    offsets: OffsetMap;
};
/** AQL message conveying a raw event or a record created by mapping an event via SELECT.
 * @beta */
export declare type AqlEventMessage = {
    /** A simply-mapped event */
    type: 'event';
    /** Payload data generated by the AQL query via SELECT statements. */
    payload: unknown;
    /** Metadata of the event that yielded this record. */
    meta: Metadata;
};
/** AQL diagnostic output describing an error that occured during query evaluation.
 * @beta */
export declare type AqlDiagnosticMessage = {
    /** A problem occured */
    type: 'diagnostic';
    severity: string;
    message: string;
};
/** Future versions of AQL will know additional response message types.
 * @beta */
export declare type AqlFutureCompat = {
    /** Consult AQL documentation to find out about future available types. */
    type: Exclude<'event' | 'offsets' | 'diagnostic', string>;
    payload: unknown;
    /** Consult AQL documentation to find out about future metadata contents. */
    meta: Record<string, unknown>;
};
/** Response message returned by running AQL query.
 * @beta */
export declare type AqlResponse = AqlEventMessage | AqlOffsetsMsg | AqlDiagnosticMessage | AqlFutureCompat;
/**
 * Status of another node as observed by the local node
 * @public
 */
export declare enum NodeStatus {
    /**
     * Replicates all streams within at most two gossip cycles
     */
    LowLatency = "LowLatency",
    /**
     * Replicates all streams within at most five gossip cycles
     */
    HighLatency = "HighLatency",
    /**
     * Replicates at least half of all streams within five gossip cycles
     */
    PartiallyWorking = "PartiallyWorking",
    /**
     * Replicates less than half of all streams within five gossip cycles
     *
     * This state either means that the node is disconnected from our part of
     * the network or that it has been shut down or decommissioned. Old streams
     * will stay in the swarm in this state.
     */
    NotWorking = "NotWorking"
}