pluts 0.1.0

package/src/domain/entry.ts

@@ -0,0 +1,181 @@
+import type { Account } from "./account.js";
+import type { Amount } from "./amount.js";
+import { ValidationError, type ValidationIssue } from "./errors.js";
+import {
+  type AmountLine,
+  type EntryInput,
+  entryInputSchema,
+  toIssues,
+} from "./schemas.js";
+import { toDateISO } from "./types.js";
+
+export type AmountKind = "credit" | "debit";
+
+/** A debit/credit line with a resolved account (no name lookup pending). */
+export interface ResolvedAmountLine {
+  readonly account: Account;
+  readonly amount: Amount;
+}
+
+/**
+ * A validated, unpersisted entry: description, date, and resolved debit/credit
+ * lines (each carrying an `Account` and an `Amount`). Has no id; persistence
+ * assigns one. Immutable. Carries an optional client-supplied
+ * {@link idempotencyKey} so the repository can dedup retries atomically.
+ */
+export interface EntryPayload {
+  readonly idempotencyKey?: string;
+  readonly description: string;
+  readonly date: string;
+  readonly debits: readonly ResolvedAmountLine[];
+  readonly credits: readonly ResolvedAmountLine[];
+}
+
+/**
+ * A persisted debit or credit leg of an entry. Immutable.
+ */
+export class AmountRecord {
+  constructor(
+    readonly id: string,
+    readonly kind: AmountKind,
+    readonly account: Account,
+    readonly amount: Amount,
+    readonly entryId: string,
+  ) {}
+
+  toJSON(): Record<string, unknown> {
+    return {
+      id: this.id,
+      kind: this.kind,
+      accountId: this.account.id,
+      amount: this.amount.toMajor(),
+      entryId: this.entryId,
+    };
+  }
+}
+
+/**
+ * A persisted journal entry: one or more debits and credits that balance.
+ * Immutable; constructed fully-formed with an assigned id and a posted-at
+ * timestamp (when it was recorded). The `date` field is the transaction date
+ * (when the economic event occurred) — kept distinct from `postedAt` for audit
+ * clarity.
+ */
+export class Entry {
+  constructor(
+    readonly id: string,
+    readonly description: string,
+    readonly date: string,
+    readonly debitAmounts: readonly AmountRecord[],
+    readonly creditAmounts: readonly AmountRecord[],
+    readonly postedAt: string,
+  ) {}
+
+  toJSON(): Record<string, unknown> {
+    return {
+      id: this.id,
+      description: this.description,
+      date: this.date,
+      debitAmounts: this.debitAmounts.map((d) => ({
+        ...d,
+        amount: d.amount.toMajor(),
+      })),
+      creditAmounts: this.creditAmounts.map((c) => ({
+        ...c,
+        amount: c.amount.toMajor(),
+      })),
+      postedAt: this.postedAt,
+    };
+  }
+}
+
+function newId(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Validate input and assemble an {@link EntryPayload}. Throws
+ * {@link ValidationError} on failure with a flat list of path-tagged issues.
+ *
+ * Validation:
+ * - shape and per-line rules via {@link entryInputSchema} (Zod)
+ * - entry-level invariants (≥1 debit, ≥1 credit, debits-sum === credits-sum)
+ *   via the schema's `superRefine`
+ * - account-name resolution happens *after* schema validation (DB lookups
+ *   aren't schema concerns); unresolved accounts are reported as issues
+ *   with path `[root, index, 'account']`
+ *
+ * @param resolveAccount looks up an account by name; returns null if missing
+ */
+export function buildEntry(
+  input: EntryInput,
+  resolveAccount: (name: string) => Account | null = () => null,
+  now: () => Date = () => new Date(),
+): EntryPayload {
+  const parsed = entryInputSchema.safeParse(input);
+  if (!parsed.success) {
+    throw new ValidationError(toIssues(parsed.error.issues));
+  }
+  const { description, debits, credits } = parsed.data;
+  const date = parsed.data.date ?? toDateISO(now());
+  const { idempotencyKey } = parsed.data;
+
+  // Resolve accounts by name (post-parse). Unresolved names become issues.
+  const issues: ValidationIssue[] = [];
+  const resolveLine = (
+    line: AmountLine,
+    index: number,
+    root: "debits" | "credits",
+  ): ResolvedAmountLine | null => {
+    if (line.account) return { account: line.account, amount: line.amount };
+    const name = line.accountName;
+    if (name) {
+      const found = resolveAccount(name);
+      if (found) return { account: found, amount: line.amount };
+      issues.push({
+        path: [root, index, "account"],
+        message: `Account "${name}" not found`,
+      });
+    }
+    return null;
+  };
+
+  const resolvedDebits: ResolvedAmountLine[] = [];
+  const resolvedCredits: ResolvedAmountLine[] = [];
+  debits.forEach((l, i) => {
+    const r = resolveLine(l, i, "debits");
+    if (r) resolvedDebits.push(r);
+  });
+  credits.forEach((l, i) => {
+    const r = resolveLine(l, i, "credits");
+    if (r) resolvedCredits.push(r);
+  });
+
+  if (issues.length > 0) {
+    throw new ValidationError(issues);
+  }
+
+  const payload: EntryPayload = {
+    description,
+    date,
+    debits: resolvedDebits,
+    credits: resolvedCredits,
+    ...(idempotencyKey ? { idempotencyKey } : {}),
+  };
+  return payload;
+}
+
+/** Build {@link AmountRecord}s from a payload, assigning fresh ids. */
+export function amountsFromPayload(
+  payload: EntryPayload,
+  entryId: string,
+): { debits: AmountRecord[]; credits: AmountRecord[] } {
+  return {
+    debits: payload.debits.map(
+      (l) => new AmountRecord(newId(), "debit", l.account, l.amount, entryId),
+    ),
+    credits: payload.credits.map(
+      (l) => new AmountRecord(newId(), "credit", l.account, l.amount, entryId),
+    ),
+  };
+}

package/src/domain/errors.ts

@@ -0,0 +1,61 @@
+/**
+ * A single validation issue. `path` follows Zod's convention: an array of
+ * property keys / indices locating the offending field within the input.
+ * Record-level invariants (e.g. "debit and credit totals must cancel") use
+ * an empty path `[]`.
+ */
+export interface ValidationIssue {
+  path: PropertyKey[];
+  message: string;
+}
+
+/**
+ * Thrown when a domain operation (e.g. posting an entry, creating an account)
+ * fails validation. Carries a flat list of {@link ValidationIssue}s rather than
+ * an ActiveRecord-style field-keyed map, preserving path precision (you can tell
+ * *which* debit's amount was bad).
+ */
+export class ValidationError extends Error {
+  readonly issues: ValidationIssue[];
+
+  constructor(issues: ValidationIssue[], message = "Validation failed") {
+    super(message);
+    this.name = "ValidationError";
+    this.issues = issues;
+  }
+
+  /**
+   * Collapses issue paths to a field-keyed map for form binding.
+   * - Issues with an empty path go under `'_base'`.
+   * - Otherwise the root key of the path is used (e.g. `['debits', 0, 'account']` → `'account'`).
+   *
+   * Note: this loses path precision (which array index). Use `issues` directly
+   * when you need that.
+   */
+  errorsByField(): Record<string, string[]> {
+    const out: Record<string, string[]> = {};
+    for (const issue of this.issues) {
+      const key = issue.path.length === 0 ? "_base" : String(issue.path[0]);
+      const list = out[key];
+      if (list) {
+        list.push(issue.message);
+      } else {
+        out[key] = [issue.message];
+      }
+    }
+    return out;
+  }
+}
+
+/**
+ * Thrown when the persistence layer rejects an operation for a reason that
+ * isn't input validation (e.g. a foreign-key violation at the storage level).
+ * Carries the underlying cause for diagnostics. Used by the SqlStorage
+ * repository to give callers a typed alternative to raw storage errors.
+ */
+export class RepositoryError extends Error {
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause });
+    this.name = "RepositoryError";
+  }
+}

package/src/domain/ledger.ts

@@ -0,0 +1,188 @@
+import type { Repository } from "../db/repository";
+import { type Account, aggregateBalances, computeBalance } from "./account";
+import {
+  type AmountRecord,
+  buildEntry,
+  type Entry,
+  type EntryPayload,
+} from "./entry";
+import { ValidationError } from "./errors";
+import {
+  type CreateAccountInput,
+  createAccountSchema,
+  type EntryInput,
+  toIssues,
+} from "./schemas";
+import { AccountType, type DateRange } from "./types";
+
+/**
+ * Balances are signed `bigint` minor units. A balance may legitimately be
+ * negative (e.g. an overdrawn asset), which the strictly-non-negative
+ * {@link Amount} type cannot represent, so report fields expose raw `bigint`.
+ * Format for display with {@link formatAmount} from `./amount.js`.
+ */
+export interface BalanceSheet {
+  assets: bigint;
+  liabilities: bigint;
+  equity: bigint;
+  /** Assets - (Liabilities + Equity + Net Income). Should be zero in a balanced ledger. */
+  balanced: bigint;
+}
+
+export interface IncomeStatement {
+  revenue: bigint;
+  expenses: bigint;
+  netIncome: bigint;
+}
+
+/**
+ * High-level facade over a {@link Repository}. Provides the accounting
+ * operations of the Pluts domain: account creation, entry posting, and
+ * balance/report queries. This is the primary public API surface.
+ */
+export class Ledger {
+  constructor(private readonly repo: Repository) {}
+
+  async createAccount(input: CreateAccountInput): Promise<Account> {
+    const parsed = createAccountSchema.safeParse(input);
+    if (!parsed.success) {
+      throw new ValidationError(
+        toIssues(parsed.error.issues),
+        "Invalid account input",
+      );
+    }
+    // The DB unique index (name, type) is the source of truth; insertAccount
+    // catches the constraint violation and re-throws as ValidationError. This
+    // avoids a check-then-act TOCTOU window under concurrent DO requests.
+    return this.repo.insertAccount(parsed.data);
+  }
+
+  /**
+   * Validate and persist an entry. Each amount may reference an account either
+   * directly (`account`) or by name (`accountName`, resolved against the repo).
+   * Amounts accept `number | string | Amount`. Throws {@link ValidationError}
+   * on failure with a flat list of path-tagged issues.
+   */
+  async postEntry(input: EntryInput): Promise<Entry> {
+    // Exactly-once posting: if a client-supplied idempotency key is present and
+    // a matching entry was already persisted, return it instead of re-posting.
+    // This guards against retries in a Durable Object (network replays or
+    // re-execution after eviction) that would otherwise create a silent duplicate.
+    if (input.idempotencyKey) {
+      const existing = await this.repo.getEntryByKey(input.idempotencyKey);
+      if (existing) return existing;
+    }
+
+    const names = new Set<string>();
+    for (const a of [...input.debits, ...input.credits]) {
+      if (a.accountName) names.add(a.accountName);
+    }
+    const accountMap = new Map<string, Account>();
+    for (const name of names) {
+      const acc = await this.repo.getAccountByName(name);
+      if (acc) accountMap.set(name, acc);
+    }
+
+    const payload: EntryPayload = buildEntry(
+      input,
+      (name) => accountMap.get(name) ?? null,
+    );
+    return this.repo.insertEntry(payload);
+  }
+
+  async getAccount(id: string): Promise<Account | null> {
+    return this.repo.getAccount(id);
+  }
+
+  async getAccountByName(name: string): Promise<Account | null> {
+    return this.repo.getAccountByName(name);
+  }
+
+  /** All accounts, ordered by name. */
+  async allAccounts(): Promise<Account[]> {
+    return this.repo.allAccounts();
+  }
+
+  /** Balance of a single account, optionally within a date range. */
+  async accountBalance(account: Account, range?: DateRange): Promise<bigint> {
+    const [credits, debits] = await Promise.all([
+      this.repo.sumCredits(account.id, range),
+      this.repo.sumDebits(account.id, range),
+    ]);
+    return computeBalance(account.type, account.contra, credits, debits);
+  }
+
+  /** Aggregate balance of all accounts of a type (contra accounts subtracted). */
+  async balanceByType(type: AccountType, range?: DateRange): Promise<bigint> {
+    const accounts = await this.repo.getAccountsByType(type);
+    const balances = await Promise.all(
+      accounts.map(async (a) => ({
+        type: a.type,
+        contra: a.contra,
+        balance: await this.accountBalance(a, range),
+      })),
+    );
+    return aggregateBalances(balances, type);
+  }
+
+  /**
+   * Trial balance: should always be zero for a balanced ledger.
+   * Asset - (Liability + Equity + Revenue - Expense). Optionally scoped to a
+   * date range (all entries up to/within the range), matching `balanceSheet`
+   * and `incomeStatement`.
+   */
+  async trialBalance(range?: DateRange): Promise<bigint> {
+    const [assets, liabilities, equity, revenue, expenses] = await Promise.all([
+      this.balanceByType(AccountType.Asset, range),
+      this.balanceByType(AccountType.Liability, range),
+      this.balanceByType(AccountType.Equity, range),
+      this.balanceByType(AccountType.Revenue, range),
+      this.balanceByType(AccountType.Expense, range),
+    ]);
+    return assets - (liabilities + equity + revenue - expenses);
+  }
+
+  async balanceSheet(range?: DateRange): Promise<BalanceSheet> {
+    const [assets, liabilities, equity, revenue, expenses] = await Promise.all([
+      this.balanceByType(AccountType.Asset, range),
+      this.balanceByType(AccountType.Liability, range),
+      this.balanceByType(AccountType.Equity, range),
+      this.balanceByType(AccountType.Revenue, range),
+      this.balanceByType(AccountType.Expense, range),
+    ]);
+    // Net income (revenue - expenses) is retained earnings, part of equity on
+    // a real balance sheet. The balanced check includes it so the accounting
+    // equation holds: Assets = Liabilities + Equity + Net Income.
+    const netIncome = revenue - expenses;
+    return {
+      assets,
+      liabilities,
+      equity,
+      balanced: assets - (liabilities + equity + netIncome),
+    };
+  }
+
+  async incomeStatement(range?: DateRange): Promise<IncomeStatement> {
+    const [revenue, expenses] = await Promise.all([
+      this.balanceByType(AccountType.Revenue, range),
+      this.balanceByType(AccountType.Expense, range),
+    ]);
+    return {
+      revenue,
+      expenses,
+      netIncome: revenue - expenses,
+    };
+  }
+
+  async entriesForAccount(account: Account): Promise<Entry[]> {
+    return this.repo.entriesForAccount(account.id);
+  }
+
+  async amountsForAccount(account: Account): Promise<AmountRecord[]> {
+    return this.repo.amountsForAccount(account.id);
+  }
+
+  async allEntries(order: "asc" | "desc" = "desc"): Promise<Entry[]> {
+    return this.repo.allEntries(order);
+  }
+}

package/src/domain/schemas.ts

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { Account } from "./account";
+import { Amount } from "./amount";
+import type { ValidationIssue } from "./errors";
+import { AccountType, toDateISO } from "./types";
+
+/**
+ * Amount input: accepts an already-built {@link Amount}, a non-negative finite
+ * number, or a digit-only string. The transform parses raw values to an
+ * `Amount` via half-up rounding at the supported scale, so float imprecision
+ * (e.g. `0.1 + 0.2`) is resolved at the input boundary. Stored values stay
+ * exact integers.
+ *
+ * `z.custom<Amount>` (rather than `z.instanceof(Amount)`) is used because
+ * {@link Amount} has a private constructor and Zod v4's `z.instanceof`
+ * requires a public one. `amountLineSchema` below uses `z.instanceof(Account)`
+ * because `Account`'s constructor is public.
+ */
+export const amountSchema = z
+  .union([
+    z.custom<Amount>((v) => v instanceof Amount, { message: "Invalid Amount" }),
+    z.number().finite().nonnegative(),
+    z.string().regex(/^\d+(\.\d+)?$/),
+  ])
+  .transform((v) => (v instanceof Amount ? v : Amount.fromMajor(v)));
+
+/** A `Date | string` normalized to an ISO `yyyy-mm-dd` string. */
+const isoDateSchema = z.union([z.date(), z.string()]).transform(toDateISO);
+
+/** Optional inclusive date range, normalized to ISO strings. */
+export const dateRangeSchema = z
+  .object({
+    fromDate: isoDateSchema.optional(),
+    toDate: isoDateSchema.optional(),
+  })
+  .optional();
+
+/** Input for account creation. `name` is trimmed; `contra` defaults to false. */
+export const createAccountSchema = z.object({
+  name: z.string().trim().min(1),
+  type: z.nativeEnum(AccountType),
+  contra: z.boolean().default(false),
+});
+
+export type CreateAccountInput = z.input<typeof createAccountSchema>;
+
+/** A single debit/credit line. Either `account` or `accountName` is required. */
+const amountLineSchema = z
+  .object({
+    account: z.instanceof(Account).optional(),
+    accountName: z.string().min(1).optional(),
+    amount: amountSchema,
+  })
+  .refine((v) => v.account || v.accountName, {
+    message: "can't be blank",
+    path: ["account"],
+  });
+
+export type AmountLine = z.output<typeof amountLineSchema>;
+export type AmountInput = z.input<typeof amountLineSchema>;
+
+/** Input shape for building an entry (mirrors Ruby's `Entry.new` hash). */
+export const entryInputSchema = z
+  .object({
+    idempotencyKey: z.string().min(1).optional(),
+    description: z.string().min(1),
+    date: isoDateSchema.optional(),
+    debits: z.array(amountLineSchema),
+    credits: z.array(amountLineSchema),
+  })
+  .superRefine((v, ctx) => {
+    if (v.debits.length === 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["debits"],
+        message: "Entry must have at least one debit amount",
+      });
+    }
+    if (v.credits.length === 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["credits"],
+        message: "Entry must have at least one credit amount",
+      });
+    }
+    // Only reconcile totals once every line parsed to an `Amount`. If a line's
+    // amount failed the union (e.g. a negative number), its per-line issue
+    // already explains the failure, and summing the raw value here would throw
+    // `TypeError: Cannot mix BigInt and other types` — turning a clean
+    // validation failure into a crash (and `safeParse` must never throw).
+    const amounts = [...v.debits, ...v.credits].map((l) => l.amount);
+    if (amounts.every((a) => a instanceof Amount)) {
+      const debitSum = v.debits.reduce((acc, l) => acc + l.amount.minor, 0n);
+      const creditSum = v.credits.reduce((acc, l) => acc + l.amount.minor, 0n);
+      if (debitSum !== creditSum) {
+        ctx.addIssue({
+          code: "custom",
+          path: [],
+          message: "The credit and debit amounts are not equal",
+        });
+      } else if (debitSum === 0n) {
+        ctx.addIssue({
+          code: "custom",
+          path: [],
+          message: "Entry amounts must be greater than zero",
+        });
+      }
+    }
+  });
+
+export type EntryInput = z.input<typeof entryInputSchema>;
+
+/**
+ * Maps Zod issues to {@link ValidationIssue}s, preserving paths.
+ */
+export function toIssues(zodIssues: z.ZodIssue[]): ValidationIssue[] {
+  return zodIssues.map((i) => ({ path: i.path, message: i.message }));
+}

package/src/domain/types.ts

@@ -0,0 +1,45 @@
+/** The five account types, mirroring Plutus' single-table-inheritance subclasses. */
+export enum AccountType {
+  Asset = "Asset",
+  Liability = "Liability",
+  Equity = "Equity",
+  Revenue = "Revenue",
+  Expense = "Expense",
+}
+
+export const ACCOUNT_TYPES: readonly AccountType[] = [
+  AccountType.Asset,
+  AccountType.Liability,
+  AccountType.Equity,
+  AccountType.Revenue,
+  AccountType.Expense,
+];
+
+/**
+ * Whether an account type normally has a credit balance.
+ * Asset/Expense => debit normal balance (false); others => credit (true).
+ */
+export function normalCreditBalance(type: AccountType): boolean {
+  return (
+    type === AccountType.Liability ||
+    type === AccountType.Equity ||
+    type === AccountType.Revenue
+  );
+}
+
+/** Optional inclusive date range for balance calculations. Strings are "yyyy-mm-dd". */
+export interface DateRange {
+  fromDate?: Date | string;
+  toDate?: Date | string;
+}
+
+/** Normalizes a Date | string to an ISO yyyy-mm-dd string. */
+export function toDateISO(d: Date | string): string {
+  if (typeof d === "string") {
+    return d;
+  }
+  const year = d.getUTCFullYear();
+  const month = String(d.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(d.getUTCDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export type { Repository } from "./db/repository.js";
+export {
+  migrate,
+  SCHEMA_SQL,
+  SCHEMA_STATEMENTS,
+} from "./db/schema.js";
+export { SqlStorageRepository } from "./db/sqlite-storage-repository.js";
+export {
+  Account,
+  aggregateBalances,
+  computeBalance,
+} from "./domain/account.js";
+export { Amount, formatAmount, SCALE } from "./domain/amount.js";
+export {
+  type AmountKind,
+  AmountRecord,
+  amountsFromPayload,
+  buildEntry,
+  Entry,
+  type EntryPayload,
+  type ResolvedAmountLine,
+} from "./domain/entry.js";
+export {
+  RepositoryError,
+  ValidationError,
+  type ValidationIssue,
+} from "./domain/errors.js";
+export {
+  type BalanceSheet,
+  type IncomeStatement,
+  Ledger,
+} from "./domain/ledger.js";
+export {
+  type AmountInput,
+  amountSchema,
+  type CreateAccountInput,
+  createAccountSchema,
+  dateRangeSchema,
+  type EntryInput,
+  entryInputSchema,
+  toIssues,
+} from "./domain/schemas.js";
+export {
+  ACCOUNT_TYPES,
+  AccountType,
+  type DateRange,
+  normalCreditBalance,
+  toDateISO,
+} from "./domain/types.js";