pluts 0.1.1 → 0.1.2

package/README.md

@@ -45,6 +45,35 @@ Pluts persists over a SQLite-backed Durable Object's own storage (`ctx.storage.s
 - `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`.
 
+### Serialization at boundaries
+
+Pluts domain objects cannot cross either exit from a Durable Object:
+
+- **Workers RPC** serializes method arguments/returns with structured clone. `bigint` is clone-safe, but class instances like `Amount` and `Entry` are rejected with `DataCloneError`.
+- **JSON REST** uses `JSON.stringify`, which throws `TypeError` on `bigint`.
+
+Returning a raw `Entry` (or any object carrying `Amount`/`Account` instances) from a DO RPC method or HTTP handler fails at runtime.
+
+**RPC methods must return DTOs, never domain objects.** Use the mappers exported from `pluts`:
+
+- `toEntryDTO(entry)` → `EntryDTO`
+- `toAmountLineDTO(line)` → `AmountLineDTO`
+- `toAccountDTO(account)` → `AccountDTO`
+
+These produce deep-plain objects whose monetary fields are fixed-precision decimal strings (`"10.00"`), safe for both structured clone and `JSON.stringify`.
+
+`Amount#toJSON()` returns the major-units decimal string, which makes `JSON.stringify` safe for objects containing an `Amount` — but it does **not** help Workers RPC, because structured clone ignores `toJSON`. Use the DTO mappers at RPC boundaries.
+
+```ts
+// Inside a Durable Object RPC method:
+async postEntry(input: EntryInput): Promise<EntryDTO> {
+  const payload = buildEntry(input, (name) => this.repository.getAccountByName(name));
+  const entry = await this.repository.insertEntry(payload);
+  return toEntryDTO(entry);
+}
+```
+
+
 ### 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)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pluts",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A double-entry accounting ledger for TypeScript, targeting Cloudflare Durable Objects (SQLite-backed storage).",
   "type": "module",
   "license": "MIT",

package/src/domain/amount.ts

@@ -129,8 +129,17 @@ export class Amount {
     return `${whole}.${frac.toString().padStart(SCALE, "0")}`;
   }
 
+  /**
+   * Serialize as a major-units decimal string (e.g. "10.00").
+   *
+   * This makes `JSON.stringify` safe for objects containing an {@link Amount}
+   * (a raw `bigint` would otherwise throw a TypeError). It does NOT help
+   * Workers RPC: structured clone ignores `toJSON` and rejects class
+   * instances, so RPC boundaries must use the DTO mappers (`toEntryDTO`, etc.)
+   * instead.
+   */
   toJSON(): string {
-    return this.minor.toString();
+    return this.toMajor();
   }
 
   toString(): string {

package/src/domain/dto.ts

@@ -0,0 +1,77 @@
+import type { Account } from "./account.js";
+import type { AmountRecord, Entry } from "./entry.js";
+
+/**
+ * Plain, boundary-safe projections of the pluts domain objects.
+ *
+ * The pluts domain types (Account, AmountRecord, Entry) carry `class`
+ * instances and `bigint` values, which cannot cross the two exits from a
+ * Durable Object: Workers RPC (structured clone rejects class instances) and
+ * JSON REST (JSON.stringify throws on bigint). These mappers produce deep-plain
+ * objects whose monetary fields are fixed-precision decimal strings, suitable
+ * for both. Use them at every RPC/REST boundary; never return a raw domain
+ * object across one.
+ */
+
+export interface AccountDTO {
+  id: string;
+  name: string;
+  type: string;
+  contra: boolean;
+  createdAt: string;
+  /** Optional pre-computed balance, formatted in major units. */
+  balance?: string;
+}
+
+export interface AmountLineDTO {
+  id: string;
+  kind: "debit" | "credit";
+  account: AccountDTO;
+  /** Major-units decimal string, e.g. "10.00". */
+  amount: string;
+  entryId: string;
+}
+
+export interface EntryDTO {
+  id: string;
+  description: string;
+  date: string;
+  debitAmounts: AmountLineDTO[];
+  creditAmounts: AmountLineDTO[];
+  postedAt: string;
+}
+
+function freeze<T>(value: T): T {
+  return Object.freeze(value);
+}
+
+export function toAccountDTO(account: Account): AccountDTO {
+  return freeze({
+    id: account.id,
+    name: account.name,
+    type: account.type,
+    contra: account.contra,
+    createdAt: account.createdAt,
+  });
+}
+
+export function toAmountLineDTO(line: AmountRecord): AmountLineDTO {
+  return freeze({
+    id: line.id,
+    kind: line.kind,
+    account: toAccountDTO(line.account),
+    amount: line.amount.toMajor(),
+    entryId: line.entryId,
+  });
+}
+
+export function toEntryDTO(entry: Entry): EntryDTO {
+  return freeze({
+    id: entry.id,
+    description: entry.description,
+    date: entry.date,
+    debitAmounts: entry.debitAmounts.map(toAmountLineDTO),
+    creditAmounts: entry.creditAmounts.map(toAmountLineDTO),
+    postedAt: entry.postedAt,
+  });
+}

package/src/index.ts

@@ -11,6 +11,14 @@ export {
   computeBalance,
 } from "./domain/account.js";
 export { Amount, formatAmount, SCALE } from "./domain/amount.js";
+export {
+  type AccountDTO,
+  type AmountLineDTO,
+  type EntryDTO,
+  toAccountDTO,
+  toAmountLineDTO,
+  toEntryDTO,
+} from "./domain/dto.js";
 export {
   type AmountKind,
   AmountRecord,