pluts 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# Pluts
+
+A double-entry accounting ledger for TypeScript, targeting Cloudflare Durable Objects (SQLite-backed storage).
+
+Pluts is a TypeScript refactor of the Ruby [Plutus](https://github.com/mbulat/plutus) gem. It implements a complete double-entry bookkeeping system: accounts (Asset, Liability, Equity, Revenue, Expense), journal entries with balanced debit/credit amounts, and reporting (trial balance, balance sheet, income statement).
+
+All monetary amounts are stored as exact integer minor units (no floating-point errors), with a configurable scale (currently 2 decimal places, suitable for AUD, USD, NZD).
+
+## Design
+
+### Amounts
+
+Money is represented by the `Amount` value object, stored internally as a `bigint` of minor units (cents at scale 2). The `SCALE` constant in `src/domain/amount.ts` is the single source of truth for precision. Rounding to the supported scale happens only at the input boundary, using half-up rounding; stored values are never rounded, so posted entries and the trial balance remain exact.
+
+At public input boundaries (entry amounts, account creation), amounts accept `number | string | Amount`. A Zod schema parses raw values to `Amount` via half-up rounding at the boundary, so float imprecision (e.g. `0.1 + 0.2` = 0.30000000000000004) is resolved before storage. The stored integer is exact.
+
+To support higher-precision currencies in the future (e.g. 3 decimals for KWD, 8 for crypto), raise `SCALE` and run a rescale migration on stored minor units. The rest of the domain is scale-agnostic.
+
+### Accounts
+
+The five account types are represented by the `AccountType` enum. Balance logic is driven by `normalCreditBalance(type)` plus the account's `contra` flag:
+
+- Normal credit balance (Liability, Equity, Revenue), non-contra: `credits - debits`
+- Normal credit balance, contra: `debits - credits`
+- Normal debit balance (Asset, Expense), non-contra: `debits - credits`
+- Normal debit balance, contra: `credits - debits`
+
+Contra accounts are automatically subtracted from type-level balance aggregation.
+
+### Entries
+
+An entry requires a description, at least one debit and one credit, and the sum of debits must exactly equal the sum of credits. Validation is driven by [Zod](https://zod.dev) schemas: input shape (per-line account/amount presence, amount positivity) is validated by the schema, and entry-level invariants (≥1 debit, ≥1 credit, debits-sum === credits-sum) are enforced via `superRefine`. On failure, `Ledger.postEntry` throws a `ValidationError` carrying a flat list of path-tagged `issues`.
+
+`Entry` (the persisted read model) and `EntryPayload` (the validated, pre-persistence input) are distinct immutable types — there is no mutable "new record" state.
+
+### Validation
+
+All public input boundaries are Zod-gated: entry input, account creation, amount parsing, and date ranges. `ValidationError.issues` is a flat array of `{ path: PropertyKey[]; message: string }` (Zod-native); record-level invariants use an empty path. Use `errorsByField()` to collapse paths to a field-keyed map for form binding.
+
+### Persistence
+
+Pluts persists over a SQLite-backed Durable Object's own storage (`ctx.storage.sql`), using the synchronous `SqlStorage` API (`sql.exec(sql, ...binds).toArray()/.one()`). The `Repository` interface decouples the domain from persistence, so the domain can be unit-tested with an in-memory repository. `SqlStorageRepository` is the production implementation.
+
+- `src/db/schema.ts` is the single source of truth for DDL: idempotent `CREATE TABLE IF NOT EXISTS` / `CREATE INDEX IF NOT EXISTS` statements.
+- `migrate(sql)` applies the schema via `sql.exec(...)`. It is idempotent and safe to run on every cold start; existing tables and indexes are left untouched. There is no separate migrations tracking table and no code generator to run.
+- A ledger is hosted _inside_ a Durable Object: the DO's private SQLite database (declared via `new_sqlite_classes` in `wrangler.jsonc`) is the ledger. One DO instance = one isolated ledger. `migrate(ctx.storage.sql)` self-provisions each one, typically in the DO constructor under `blockConcurrencyWhile`.
+
+### SQL implementation and portability
+
+Pluts's production persistence is implemented against Cloudflare Durable Objects' embedded SQLite via the synchronous `SqlStorage` API. The concrete implementation lives in `src/db/sqlite-storage-repository.ts` and runs the schema statements defined in `src/db/schema.ts` using `migrate(ctx.storage.sql)`.
+
+If you want to run Pluts outside of Cloudflare (or support additional backends), implement the `Repository` interface in `src/db/repository.ts` for your chosen storage. Key guidance:
+
+- Implement the same transactional semantics for `insertEntry` (all row inserts + idempotency-key insert must be atomic). Use your DB's transactions.
+- Apply the schema in `SCHEMA_STATEMENTS` (see `src/db/schema.ts`) or translate it to your DB's DDL before first use.
+- Persist amounts as integer minor units (the library uses `bigint` internally; convert to/from your driver's numeric type safely).
+- Ensure `getAccountByName`, `sumByType`, `sumCredits`/`sumDebits`, and `amountsForAccount` match the SQL semantics expected by the domain code.
+
+Examples:
+
+- Node + SQLite: implement a `NodeSqliteRepository` using `better-sqlite3` or `sqlite3`, run the `SCHEMA_STATEMENTS` once on startup, and wrap `insertEntry` in a transaction.
+- Postgres: translate the DDL (types, index syntax) and implement `Repository` methods with `pg`/`knex`; be mindful of integer sizes and use `bigint`/numeric as appropriate.
+
+Because the domain is decoupled via `Repository` and tests exercise the domain with an in-memory repository, porting is limited to a single new repository adapter — the rest of Pluts should work unchanged.
+
+### Tenancy
+
+Tenancy is intentionally **not** included. Multi-tenancy is provided by Durable Object isolation: one DO instance = one ledger. Account names are unique within a ledger.
+
+### Schema
+
+Four tables (prefixed `pluts_`), defined in `src/db/schema.ts`:
+
+- `pluts_accounts` — id, name, type (CHECK-constrained to the five account types), contra, created_at
+- `pluts_entries` — id, description, date, posted_at
+- `pluts_amounts` — id, type (`'credit'` | `'debit'`), account_id, entry_id, amount (integer minor units)
+- `pluts_entry_keys` — key, entry_id (idempotency-key dedup table)
+
+Run `migrate(ctx.storage.sql)` to apply the schema; it is idempotent and a no-op on an up-to-date database.
+
+## Installation
+
+```sh
+bun add pluts
+```
+
+Peer dependency: `zod`. Types for the Workers runtime (`SqlStorage`, `DurableObjectStorage`, `crypto`) come from `@cloudflare/workers-types`.
+
+## Usage
+
+Hosted inside a Durable Object, where `ctx.storage.sql` is the ledger's database:
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+import {
+  AccountType,
+  Amount,
+  Ledger,
+  migrate,
+  SqlStorageRepository,
+} from "pluts";
+
+export class LedgerDO extends DurableObject {
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    // Provision the schema before any request is served.
+    ctx.blockConcurrencyWhile(() => {
+      migrate(ctx.storage.sql);
+      return Promise.resolve();
+    });
+  }
+
+  async fetch(req: Request): Promise<Response> {
+    const ledger = new Ledger(new SqlStorageRepository(this.ctx.storage));
+    // ...route requests to ledger.createAccount / ledger.postEntry / reports...
+    return new Response("ok");
+  }
+}
+
+// Create accounts
+const cash = await ledger.createAccount({
+  name: "Cash",
+  type: AccountType.Asset,
+});
+await ledger.createAccount({
+  name: "Sales Revenue",
+  type: AccountType.Revenue,
+});
+await ledger.createAccount({
+  name: "Sales Tax Payable",
+  type: AccountType.Liability,
+});
+
+// Post a balanced entry (debits === credits). Amounts accept number|string|Amount.
+await ledger.postEntry({
+  description: "Sold widgets",
+  debits: [{ accountName: "Cash", amount: 50 }],
+  credits: [
+    { accountName: "Sales Revenue", amount: 45 },
+    { accountName: "Sales Tax Payable", amount: "5.00" },
+  ],
+});
+
+// Balances
+await ledger.accountBalance(cash); // per-account
+await ledger.balanceByType(AccountType.Asset); // per-type
+await ledger.trialBalance(); // should be zero
+
+// Reports
+await ledger.balanceSheet(); // { assets, liabilities, equity, balanced }
+await ledger.incomeStatement({ fromDate: "2024-01-01" }); // { revenue, expenses, netIncome }
+```
+
+A complete runnable example lives in the [pluts-ledger-do](https://github.com/adamburmister/pluts-ledger-do) app, which wraps this pattern in a DO with a JSON REST surface and a seed route.
+
+### Contra accounts
+
+A contra account has its normal balance swapped:
+
+```ts
+await ledger.createAccount({
+  name: "Drawing",
+  type: AccountType.Equity,
+  contra: true,
+});
+```
+
+### Date ranges
+
+Balance methods accept an optional `{ fromDate, toDate }` (Date or `yyyy-mm-dd` string):
+
+```ts
+await ledger.accountBalance(cash, {
+  fromDate: "2024-01-01",
+  toDate: new Date(),
+});
+```
+
+## Validation
+
+`Ledger.postEntry` and `Ledger.createAccount` throw `ValidationError` with a flat list of path-tagged `issues` on failure:
+
+```ts
+try {
+  await ledger.postEntry({ ... });
+} catch (e) {
+  if (e instanceof ValidationError) {
+    // e.issues: { path: PropertyKey[]; message: string }[]
+    // e.g. [{ path: [], message: 'The credit and debit amounts are not equal' }]
+    console.log(e.issues);
+    // For form binding, collapse paths to a field-keyed map:
+    console.log(e.errorsByField()); // { _base: ['The credit and debit amounts are not equal'] }
+  }
+}
+```
+
+Rules (enforced via Zod schema + `superRefine`):
+
+- `description` required (non-empty)
+- at least one debit and one credit
+- every amount requires an account and a non-negative value
+- sum(debits) === sum(credits) (exact)
+- `date` defaults to today if omitted
+- account names must resolve to existing accounts
+
+## Testing
+
+```sh
+bun run test            # all tests
+bun run test:unit       # domain unit tests (in-memory, fast)
+bun run typecheck       # tsc --noEmit
+bun run lint            # biome
+```
+
+The unit tests cover amount math, balance computation for all account types and contra variants, entry validation, and the trial balance invariant, all against an in-memory `Repository`. The `SqlStorageRepository` (production) is exercised end-to-end by the [pluts-ledger-do](https://github.com/adamburmister/pluts-ledger-do) app's Durable Object.
+
+## Development
+
+```sh
+bun install
+bun run test     # vitest (domain unit tests, in-memory)
+```
+
+Pluts is a library; the runnable Durable Object app that consumes it lives in [pluts-ledger-do](https://github.com/adamburmister/pluts-ledger-do) project. Run `npm run dev` there for a local DO with SQLite storage.
+
+### Migrations
+
+The schema is defined as idempotent DDL in `src/db/schema.ts` (the `SCHEMA_STATEMENTS` array). To change the schema, edit that file and add/adjust the `CREATE TABLE IF NOT EXISTS` / `CREATE INDEX IF NOT EXISTS` statements. `migrate(ctx.storage.sql)` applies them on every cold start; existing objects are skipped, so there is no separate "generate migrations" step or tracking table.
+
+Fresh-DBs only: if you change a `CREATE TABLE` definition in a way that conflicts with an already-provisioned DO SQLite database, reset the local DO storage so it is recreated cleanly:
+
+```sh
+rm -rf ../ledger/.wrangler/state/v3/do
+```
+
+The next `npm run dev` in `ledger` provisions a fresh DO and `migrate` applies the schema cleanly.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "pluts",
+  "version": "0.1.0",
+  "description": "A double-entry accounting ledger for TypeScript, targeting Cloudflare Durable Objects (SQLite-backed storage).",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adamburmister/pluts.git"
+  },
+  "keywords": [
+    "typescript",
+    "accounting",
+    "double-entry",
+    "ledger",
+    "bookkeeping",
+    "cloudflare",
+    "durable-objects",
+    "sqlite"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src test",
+    "fix": "biome check --write src test",
+    "format": "biome format --write src test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.2",
+    "@cloudflare/workers-types": "^5.20260706.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/src/db/repository.ts

@@ -0,0 +1,42 @@
+import type { Account } from "../domain/account";
+import type { Amount } from "../domain/amount";
+import type { AmountRecord, Entry, EntryPayload } from "../domain/entry";
+import type { AccountType, DateRange } from "../domain/types";
+
+export interface Repository {
+  insertAccount(input: {
+    name: string;
+    type: AccountType;
+    contra: boolean;
+  }): Promise<Account>;
+
+  getAccount(id: string): Promise<Account | null>;
+  getAccountByName(name: string): Promise<Account | null>;
+  getAccountsByType(type: AccountType): Promise<Account[]>;
+  allAccounts(): Promise<Account[]>;
+
+  /** Validate and persist an entry (and its amounts) atomically. Returns the persisted entry. */
+  insertEntry(payload: EntryPayload): Promise<Entry>;
+
+  getEntry(id: string): Promise<Entry | null>;
+  /** Look up an entry by its client-supplied idempotency key, or null if none. */
+  getEntryByKey(key: string): Promise<Entry | null>;
+  allEntries(order?: "asc" | "desc"): Promise<Entry[]>;
+
+  /** Sum of credit amounts for an account, optionally within a date range. */
+  sumCredits(accountId: string, range?: DateRange): Promise<Amount>;
+  /** Sum of debit amounts for an account, optionally within a date range. */
+  sumDebits(accountId: string, range?: DateRange): Promise<Amount>;
+
+  /** Sum of amounts of a given kind across all accounts of a type, optionally within a date range. */
+  sumByType(
+    type: AccountType,
+    kind: "credit" | "debit",
+    range?: DateRange,
+  ): Promise<Amount>;
+
+  /** All amounts (credit + debit) for an account, with their entries. */
+  amountsForAccount(accountId: string): Promise<AmountRecord[]>;
+  /** All entries referencing an account (via credit or debit amounts). */
+  entriesForAccount(accountId: string): Promise<Entry[]>;
+}

package/src/db/schema.ts

@@ -0,0 +1,83 @@
+import type { SqlStorage } from "@cloudflare/workers-types";
+
+/**
+ * Pluts schema — the single source of truth for DDL, applied to a
+ * SQLite-backed Durable Object's own storage (`ctx.storage.sql`).
+ *
+ * Precision note: `SqlStorage` returns INTEGER as a JS number. `amount` (minor
+ * units) is exact up to Number.MAX_SAFE_INTEGER (~$90T at scale 2), an accepted
+ * ceiling for a personal-finance ledger. The write path binds
+ * `Number(amount.minor)`.
+ */
+
+export const SCHEMA_STATEMENTS: string[] = [
+  `CREATE TABLE IF NOT EXISTS pluts_accounts (
+  id TEXT PRIMARY KEY NOT NULL,
+  name TEXT NOT NULL,
+  type TEXT NOT NULL,
+  contra INTEGER DEFAULT 0 NOT NULL,
+  created_at TEXT NOT NULL,
+  CONSTRAINT pluts_accounts_type_check CHECK (type IN ('Asset','Liability','Equity','Revenue','Expense'))
+)`,
+  `CREATE UNIQUE INDEX IF NOT EXISTS pluts_accounts_name_type_idx ON pluts_accounts (name, type)`,
+  `CREATE INDEX IF NOT EXISTS pluts_accounts_type_idx ON pluts_accounts (type, name)`,
+  `CREATE TABLE IF NOT EXISTS pluts_entries (
+  id TEXT PRIMARY KEY NOT NULL,
+  description TEXT NOT NULL,
+  date TEXT NOT NULL,
+  posted_at TEXT NOT NULL
+)`,
+  `CREATE INDEX IF NOT EXISTS pluts_entries_date_idx ON pluts_entries (date)`,
+  `CREATE TABLE IF NOT EXISTS pluts_amounts (
+  id TEXT PRIMARY KEY NOT NULL,
+  type TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  entry_id TEXT NOT NULL,
+  amount INTEGER NOT NULL,
+  FOREIGN KEY (account_id) REFERENCES pluts_accounts(id) ON UPDATE no action ON DELETE no action,
+  FOREIGN KEY (entry_id) REFERENCES pluts_entries(id) ON UPDATE no action ON DELETE no action
+)`,
+  `CREATE INDEX IF NOT EXISTS pluts_amounts_type_idx ON pluts_amounts (type)`,
+  `CREATE INDEX IF NOT EXISTS pluts_amounts_account_entry_idx ON pluts_amounts (account_id, entry_id)`,
+  `CREATE INDEX IF NOT EXISTS pluts_amounts_entry_account_idx ON pluts_amounts (entry_id, account_id)`,
+  `CREATE TABLE IF NOT EXISTS pluts_entry_keys (
+  key TEXT PRIMARY KEY NOT NULL,
+  entry_id TEXT NOT NULL,
+  FOREIGN KEY (entry_id) REFERENCES pluts_entries(id) ON UPDATE no action ON DELETE no action
+)`,
+];
+
+/**
+ * The full Pluts schema as a single SQL string (statements joined with `;\n`),
+ * for inspection or for runtimes whose `exec` splits on `;`. To apply it to a
+ * Durable Object's storage, prefer {@link migrate}, which runs each
+ * statement individually via `SqlStorage.exec` (robust across runtimes).
+ */
+export const SCHEMA_SQL: string = SCHEMA_STATEMENTS.map((s) => `${s};`).join(
+  "\n",
+);
+
+/**
+ * Apply the Pluts schema to a SQLite-backed Durable Object's own storage
+ * (`ctx.storage.sql`). Idempotent: a database already at the latest schema is a
+ * no-op. `SqlStorage.exec` runs synchronously against the DO's embedded SQLite
+ * with no network round-trip, so it is safe to call from the DO constructor
+ * inside `blockConcurrencyWhile` — the recommended place to provision storage
+ * before any request is served.
+ *
+ * ```ts
+ * import { migrate } from 'pluts';
+ *
+ * export class LedgerDO extends DurableObject {
+ *   constructor(ctx, env) {
+ *     super(ctx, env);
+ *     ctx.blockConcurrencyWhile(() => { migrate(ctx.storage.sql); return Promise.resolve(); });
+ *   }
+ * }
+ * ```
+ */
+export function migrate(sql: SqlStorage): void {
+  for (const stmt of SCHEMA_STATEMENTS) {
+    sql.exec(stmt).toArray();
+  }
+}