API reference
Every function and type exported by @hiyorios/kaji.
import {
capability,
createKaji,
knownFailure,
memoryStore,
type Capability,
type ClaimResult,
type ExecutionClaim,
type ExecutionContext,
type ExecutionEvidence,
type ExecutionRequest,
type ExecutionResult,
type ExecutionStore,
type StoredExecution,
} from "@hiyorios/kaji";
capability()
Defines one action. See Capabilities.
function capability<Schema extends StandardSchemaV1, Result>(definition: {
readonly name: string;
readonly input: Schema;
readonly authorize: (request: {
readonly principalId: string;
readonly input: SchemaOutput<Schema>;
}) => boolean | Promise<boolean>;
readonly approval?: (request: {
readonly principalId: string;
readonly input: SchemaOutput<Schema>;
}) => boolean;
readonly execute: (
input: SchemaOutput<Schema>,
context: ExecutionContext,
) => Result | Promise<Result>;
}): Capability<SchemaOutput<Schema>, Result>;
input is a Standard Schema V1 schema. capability() throws right away if name, authorize, or input is missing or invalid. StandardSchemaV1 and SchemaOutput are not exported, so you never import them.
createKaji()
Creates a Kaji instance. See Stores and Cancellation.
function createKaji(options: {
readonly store: ExecutionStore;
readonly approve?: (request: {
readonly capability: string;
readonly principalId: string;
readonly input: unknown;
readonly idempotencyKey: string;
}) =>
| { readonly approved: boolean; readonly evidence?: unknown }
| Promise<{ readonly approved: boolean; readonly evidence?: unknown }>;
readonly timeoutMs?: number;
}): {
execute<Output, Result>(
capability: Capability<Output, Result>,
request: ExecutionRequest,
): Promise<ExecutionResult<Result>>;
};
ExecutionRequest
type ExecutionRequest = {
readonly input: unknown;
readonly principalId: string; // non-empty
readonly idempotencyKey: string; // non-empty
readonly signal?: AbortSignal;
};
ExecutionContext
Passed to execute.
type ExecutionContext = {
readonly principalId: string;
readonly idempotencyKey: string;
readonly signal: AbortSignal;
};
ExecutionResult
type ExecutionResult<Result> =
| {
readonly status: "succeeded";
readonly result: Result;
readonly evidence: ExecutionEvidence;
}
| {
readonly status: "denied" | "rejected" | "failed" | "cancelled";
readonly error: unknown;
readonly evidence: ExecutionEvidence;
}
| {
readonly status: "unknown";
readonly error: unknown;
readonly evidence: ExecutionEvidence;
};
See Outcomes.
ExecutionEvidence
type ExecutionEvidence = {
readonly executionId: string;
readonly capability: string;
readonly principalId: string;
readonly idempotencyKey: string;
readonly inputFingerprint: string;
};
The IDs Kaji knows about a request, useful for looking it up later. If a request is cancelled before Kaji claims it, executionId and inputFingerprint are empty. If a call stops waiting for an identical request already in progress, executionId is empty.
InvalidInputError
kaji.execute() rejects with this error when input fails validation. It is not exported. Check error.name === "InvalidInputError".
class InvalidInputError extends Error {
readonly issues: ReadonlyArray<{
readonly message: string;
readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>;
}>;
}
issues holds the schema’s own issues, unchanged.
knownFailure()
function knownFailure(cause: unknown): Error;
Throw it from execute when you know the action did not take effect. Kaji returns failed.
Store types
See Stores for how these fit together.
type ExecutionStore = {
claim(claim: ExecutionClaim): Promise<ClaimResult>;
record(execution: StoredExecution): Promise<void>;
};
type ExecutionClaim = {
readonly capability: string;
readonly principalId: string;
readonly idempotencyKey: string;
readonly inputFingerprint: string;
};
type ClaimResult =
| { readonly status: "claimed"; readonly executionId: string }
| { readonly status: "existing"; readonly outcome: Promise<StoredExecution> }
| { readonly status: "conflict"; readonly executionId: string };
type StoredExecution = ExecutionResult<unknown>;
memoryStore()
function memoryStore(): ExecutionStore;
An in-memory store for development and tests. It works in one process and keeps nothing after restart.
Capability
type Capability<Output, Result> = { readonly name: string };
The returned object only exposes name. The type parameters let kaji.execute() check your input and result types.