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.