@sekiban/dcb-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+import type { AppendedEvent, CommandDefinition, CommandOutcome, EventDefinition, JsonValue, TagDefinition, TagInput } from "@sekiban/dcb-core";
+export interface ReadonlyTagStateResponse {
+    readonly payload: JsonValue;
+    readonly version: number;
+    readonly lastSortedUniqueId: string;
+    readonly tagGroup: string;
+    readonly tagContent: string;
+    readonly tagProjector: string;
+    readonly tagPayloadName?: string;
+    /** Runtime tag-state responses serialize projectorVersion as a string. */
+    readonly projectorVersion?: string;
+}
+export type TagStateSnapshot = ReadonlyTagStateResponse & {
+    readonly tag: string;
+    readonly tagStateId: string;
+};
+export interface CommitCandidate {
+    readonly eventId: string;
+    readonly eventPayloadName: string;
+    readonly payload: JsonValue;
+    readonly tags: readonly string[];
+}
+export interface ConsistencyEntry {
+    readonly tag: string;
+    /** §3.1 commit-envelope spelling; §5.3 tag-state keeps lastSortedUniqueId. */
+    readonly lastSortableUniqueId: string;
+}
+export interface CommitEnvelope {
+    readonly candidates: readonly CommitCandidate[];
+    readonly consistency: readonly ConsistencyEntry[];
+    readonly [key: string]: unknown;
+}
+export interface CommitHttpResult {
+    readonly status: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: unknown;
+}
+export interface TagLatestSortableResponse {
+    readonly exists: boolean;
+    readonly lastSortableUniqueId: string;
+}
+export interface QueryRequest {
+    readonly queryType: string;
+    readonly queryParamsJson: string;
+    readonly waitForSortableUniqueId?: string;
+}
+export interface QueryResponse {
+    readonly resultJson: string;
+}
+export interface ListQueryRequest extends QueryRequest {
+    readonly queryParamsJson: string;
+}
+export interface ListQueryResponse {
+    readonly itemsJson: string;
+    readonly totalCount: number;
+    readonly totalPages: number;
+    readonly currentPage: number;
+    readonly pageSize: number;
+}
+export interface SerializedDcbTransport {
+    readonly readTagState: (request: {
+        readonly tagStateId: string;
+    }, signal?: AbortSignal) => Promise<ReadonlyTagStateResponse | CommitHttpResult>;
+    readonly readTagLatestSortable?: (request: {
+        readonly tag: string;
+    }, signal?: AbortSignal) => Promise<TagLatestSortableResponse | CommitHttpResult>;
+    readonly commit: (request: CommitEnvelope, signal?: AbortSignal) => Promise<unknown | CommitHttpResult>;
+    /** G57 makes the two read-only query endpoints part of every transport. */
+    readonly query: (request: QueryRequest, signal?: AbortSignal) => Promise<QueryResponse | CommitHttpResult>;
+    readonly listQuery: (request: ListQueryRequest, signal?: AbortSignal) => Promise<ListQueryResponse | CommitHttpResult>;
+    /** Optional identity supplied by a transport that is already scoped. */
+    readonly serviceId?: string;
+}
+export declare class ClientError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly partial?: unknown;
+    constructor(code: string, message: string, options?: {
+        readonly status?: number;
+        readonly partial?: unknown;
+        readonly cause?: unknown;
+    });
+}
+export declare class SerializedDcbClient implements SerializedDcbTransport {
+    readonly baseUrl: string;
+    private readonly fetchImpl;
+    constructor(baseUrl: string, fetchImpl?: typeof fetch);
+    readTagState(request: {
+        readonly tagStateId: string;
+    }, signal?: AbortSignal): Promise<ReadonlyTagStateResponse>;
+    readTagLatestSortable(request: {
+        readonly tag: string;
+    }, signal?: AbortSignal): Promise<TagLatestSortableResponse>;
+    query(request: QueryRequest, signal?: AbortSignal): Promise<QueryResponse>;
+    listQuery(request: ListQueryRequest, signal?: AbortSignal): Promise<ListQueryResponse>;
+    readonly tagLatestSortable: (request: {
+        readonly tag: string;
+    }, signal?: AbortSignal) => Promise<TagLatestSortableResponse>;
+    readonly tagState: (request: {
+        readonly tagStateId: string;
+    }, signal?: AbortSignal) => Promise<ReadonlyTagStateResponse>;
+    commit(request: CommitEnvelope, signal?: AbortSignal): Promise<unknown>;
+    private readResponse;
+}
+export declare class ClaimLedger {
+    private readonly snapshotsByStateId;
+    private readonly snapshotsByTag;
+    private readonly transport;
+    constructor(transport: SerializedDcbTransport);
+    readTagState(tagStateId: string, signal?: AbortSignal): Promise<TagStateSnapshot>;
+    readTagState(tag: TagInput, projector: string, signal?: AbortSignal): Promise<TagStateSnapshot>;
+    read(tagStateId: string, signal?: AbortSignal): Promise<TagStateSnapshot>;
+    get snapshots(): readonly TagStateSnapshot[];
+    clear(): void;
+}
+export interface PreflightInput {
+    readonly candidates: readonly Pick<CommitCandidate, "tags">[];
+    readonly consistency: readonly ConsistencyEntry[];
+    readonly claims: readonly Pick<TagStateSnapshot, "tag" | "lastSortedUniqueId">[];
+}
+/** Validate the commit envelope before any transport call. */
+export declare function preflightCommit(input: PreflightInput): void;
+export interface ClientCommandContext {
+    readonly readTagState: (tagStateId: string, signal?: AbortSignal) => Promise<TagStateSnapshot>;
+    readonly state: (tagStateId: string, signal?: AbortSignal) => Promise<JsonValue | undefined>;
+    readonly assertEmpty: (tagStateId: string, signal?: AbortSignal) => Promise<void>;
+    readonly append: (event: EventDefinition | string, payload: unknown, tags: readonly TagInput[]) => CommitCandidate;
+    readonly claims: readonly TagStateSnapshot[];
+    readonly candidates: readonly CommitCandidate[];
+}
+export type ClientCommandDecision = {
+    readonly kind: "committed" | "done";
+    readonly value?: JsonValue;
+    readonly envelope?: Partial<CommitEnvelope>;
+} | {
+    readonly kind: "noop";
+    readonly reason?: string;
+} | {
+    readonly kind: "rejected";
+    readonly error: string;
+    readonly code?: string;
+} | {
+    readonly kind: "invalid";
+    readonly error: string;
+    readonly code?: string;
+};
+export interface ExecuteOptions {
+    readonly input?: unknown;
+    readonly maxConflictRetries?: number;
+    readonly signal?: AbortSignal;
+    readonly totalBudgetMs?: number;
+}
+export interface ExecuteCommon {
+    readonly attempts: number;
+    readonly status?: number;
+    readonly code?: string;
+    readonly error?: string;
+    readonly cause?: unknown;
+}
+export interface ExecuteCommitted extends ExecuteCommon {
+    readonly kind: "committed";
+    readonly response: unknown;
+}
+export interface ExecuteNoop extends ExecuteCommon {
+    readonly kind: "noop";
+    readonly reason?: string;
+}
+export interface ExecuteRejected extends ExecuteCommon {
+    readonly kind: "rejected";
+    readonly error: string;
+}
+export interface ExecuteConflict extends ExecuteCommon {
+    readonly kind: "conflict";
+    readonly response?: unknown;
+}
+export interface ExecutePartial extends ExecuteCommon {
+    readonly kind: "partial";
+    readonly partial: unknown;
+}
+export interface ExecuteTimeout extends ExecuteCommon {
+    readonly kind: "timeout";
+}
+export interface ExecuteUnavailable extends ExecuteCommon {
+    readonly kind: "unavailable";
+}
+export interface ExecuteTransport extends ExecuteCommon {
+    readonly kind: "transport";
+}
+export interface ExecuteInvalid extends ExecuteCommon {
+    readonly kind: "invalid";
+}
+export type ExecuteResult = ExecuteCommitted | ExecuteNoop | ExecuteRejected | ExecuteConflict | ExecutePartial | ExecuteTimeout | ExecuteUnavailable | ExecuteTransport | ExecuteInvalid;
+export interface ClaimLedgerExecutorOptions {
+    readonly transport: SerializedDcbTransport;
+    readonly maxConflictRetries?: number;
+    readonly totalBudgetMs?: number;
+}
+type CommandLike = ((context: ClientCommandContext, input?: unknown) => ClientCommandDecision | Promise<ClientCommandDecision>) | CommandDefinition;
+export declare class ClaimLedgerExecutor {
+    private readonly transport;
+    private readonly defaultRetries;
+    private readonly defaultBudget?;
+    constructor(options: ClaimLedgerExecutorOptions);
+    execute(command: CommandLike, options?: ExecuteOptions): Promise<ExecuteResult>;
+}
+export declare const createClaimLedgerExecutor: (options: ClaimLedgerExecutorOptions) => ClaimLedgerExecutor;
+export declare const createSerializedDcbClient: (baseUrl: string, fetchImpl?: typeof fetch) => SerializedDcbClient;
+export type { AppendedEvent, CommandDefinition, CommandOutcome, EventDefinition, JsonValue, TagDefinition, TagInput };
+export * from "./executor.js";