Arki

TypeScript libraries for building apps that both people and agents can read.

Arki is a family of small @arki/* packages. Use one on its own, like @arki/date or @arki/money. Or compose a whole backend with @arki/dot: typed units for infra, features and entrypoints, wired by the compiler and booted in declaration order.

Every package follows the same rules:

• Types are written once. A type is declared at its source (a schema, a table, a builder chain) and inferred everywhere else.
• Schemas own validation. Unknown input becomes typed data only through a Standard Schema (Zod, Valibot or ArkType).
• Failures are values. Expected errors are returned with a stable code, not thrown. See @arki/failure.
• Agents are first-class readers. Stable error codes, --json output on every CLI, an llms.txt and an agent guide in every package.
• Proof, not promises. Tests run on real Postgres and Redis. Packages are checked on Node, Bun, Deno and browsers. Benchmarks run against competitors with the methods published.

The full list, with the reason behind each rule, is in docs/arki/principles.md.

Quick start

bun add @arki/dot @arki/failure

import { defineApp, infra } from '@arki/dot';
import { isFailure } from '@arki/failure';
import { openDb } from './db'; // your own database client

const database = infra({
  name: 'database',
  provides: { db: () => openDb(process.env.DATABASE_URL) },
  async dispose({ db }) {
    await db.close();
  },
});

const app = await defineApp('pizzeria').infra(database).start();
if (isFailure(app)) throw new Error(app.code);

Read the @arki/dot README for features, entrypoints and the dot CLI.

Packages

The stack

Package	What it does
@arki/dot	Compose an app from typed units; the compiler checks the wiring
@arki/cli	Typed CLIs from one defineCommand, with a JSON envelope when piped
@arki/env	Type-safe environment variables
@arki/http	Route contracts as data, schema-validated handlers
@arki/contracts	Shared schemas and Drizzle contract helpers
@arki/db	Drizzle repositories for Postgres and PGlite
@arki/journal	Every entity change as an immutable event row
@arki/live	Live queries for oRPC and TanStack Query on your own Postgres
@arki/kv	Key-value store with pluggable adapters
@arki/lock	Distributed locks over memory, Postgres, SQLite, Redis and files

Standalone libraries

Package	What it does
@arki/schema	Standard Schema helpers: parse with typed failures
@arki/date	Temporal-based dates, instants, durations and intervals
@arki/string	Grapheme-aware string toolkit
@arki/math	Exact Decimal and Rational arithmetic on bigint
@arki/money	Exact, fast money for every runtime
@arki/expr	A safe expression language with a typed AST
@arki/cas	A bounded computer algebra system on @arki/expr
@arki/async	Abortable sleep, debounce, throttle and concurrency helpers
@arki/clock	A clock you can control in tests
@arki/resilience	Retry, circuit breaker, timeout and bulkhead

Packages marked "private": true in their package.json are still in development and are not published yet.

Status

Every package is below 1.0. While a package is 0.x, a breaking change ships as a minor release and a fix as a patch. Read a package's CHANGELOG.md before you upgrade.

Develop

You need Bun (version in package.json) and Node 26. Docker is needed for tests that start Postgres or Redis.

bun install
bun run build       # build every package
bun run typecheck
bun run test
bun run lint

Work on one package with a Turbo filter:

bun run turbo run test --filter=@arki/date

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md. Security issues go through SECURITY.md, never a public issue.

License

MIT