@stll/money 0.0.1-placeholder.0 → 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# @stll/money
+
+Branded minor-unit monetary values and exact billing arithmetic for Stella.
+
+The package keeps money in integer minor units, rejects fractional cents, and
+separates totals by currency so incompatible amounts cannot be combined.
+
+```ts
+import { MoneyTotals, cents } from "@stll/money";
+
+const totals = new MoneyTotals();
+totals.add("EUR", cents(1250));
+```
+
+Public API changes require a changeset.

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+//#region src/index.d.ts
+/**
+ * Branded monetary amounts and minor-unit billing arithmetic.
+ *
+ * Money in this codebase is stored and computed in minor units
+ * ("cents" for USD/EUR, halere for CZK, etc.). The `CentsAmount`
+ * brand prevents the canonical 100x bug where a major-unit value
+ * (12.50 dollars) is silently mixed with minor-unit math (1250 cents).
+ *
+ * The brand lives here, in a shared package, so it threads end to end:
+ * the same `CentsAmount` flows from a Drizzle column declared with
+ * `.$type<CentsAmount>()`, across the API boundary (Eden infers the
+ * brand from the handler's return type), into browser previews and back.
+ * A plain `number` is not assignable to `CentsAmount`; mint one with
+ * `cents()` after validating minor-unit input, or `unsafeCents()` at a
+ * documented boundary.
+ *
+ * Currency-agnostic: the currency code lives alongside the amount in the
+ * schema (e.g. invoices.currency); pairing them is the call site's
+ * responsibility.
+ */
+declare const __cents: unique symbol;
+type CentsAmount = number & {
+  readonly [__cents]: "CentsAmount";
+};
+/**
+ * Construct a CentsAmount from a value already known to be in minor
+ * units. Use at boundaries where the input is validated as an integer
+ * minor-unit value (e.g. after Elysia `t.Integer({ minimum: 0 })` or
+ * after parsing user input that has been multiplied by 100).
+ *
+ * Throws on non-integer input — money math at the minor-unit level must
+ * be exact.
+ */
+declare const cents: (value: number) => CentsAmount;
+/**
+ * Escape hatch for code paths that genuinely need to attach the brand
+ * without a runtime check (test fixtures, generated code). Prefer
+ * `cents()` everywhere else; reach for this only with a `// SAFETY:`
+ * comment naming why the value is already a valid minor-unit integer.
+ */
+declare const unsafeCents: (value: number) => CentsAmount;
+type ProrateHourlyCentsInput = {
+  billedMinutes: number;
+  hourlyRateCents: CentsAmount;
+};
+declare const prorateHourlyCents: ({ billedMinutes, hourlyRateCents }: ProrateHourlyCentsInput) => CentsAmount;
+type ApplyMarkupCentsInput = {
+  amountCents: CentsAmount;
+  markupPercent: number;
+};
+declare const applyMarkupCents: ({ amountCents, markupPercent }: ApplyMarkupCentsInput) => CentsAmount;
+declare const __currency: unique symbol;
+/**
+ * A `CentsAmount` additionally branded with its ISO 4217-ish currency code
+ * `C`. This makes cross-currency addition a compile error instead of a
+ * runtime bug: `addCents` only accepts two `CurrencyCents` sharing the same
+ * `C`, so `addCents(usdAmount, eurAmount)` fails to typecheck rather than
+ * silently producing a meaningless sum.
+ *
+ * Mint one with `currencyCents()`; there is no unsafe escape hatch because
+ * the underlying `CentsAmount` validation (`cents()`) is cheap and the
+ * currency code is a plain string carried alongside it, so there is no
+ * boundary that needs to skip it.
+ */
+type CurrencyCents<C extends string = string> = CentsAmount & {
+  readonly [__currency]: C;
+};
+/**
+ * Construct a `CurrencyCents<C>` from a currency code and a minor-unit
+ * amount. The only producer of `CurrencyCents`; downstream code narrows `C`
+ * from the literal `currency` argument (e.g. `currencyCents("USD", 100)`
+ * infers `CurrencyCents<"USD">`).
+ */
+declare const currencyCents: <C extends string>(currency: C, amount: number) => CurrencyCents<C>;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+type IsSingletonCurrency<C extends string> = string extends C ? never : [C] extends [UnionToIntersection<C>] ? C : never;
+/**
+ * Add two `CurrencyCents` amounts of the SAME currency. The second
+ * parameter's currency `B` is constrained to `extends A`, so passing a
+ * different currency literal (e.g. `addCents(usdAmount, eurAmount)`) is a
+ * compile error, not a runtime bug — see `packages/money/src/index.test.ts`
+ * for the `@ts-expect-error` proof.
+ *
+ * Both operands are further constrained by `IsSingletonCurrency` to reject
+ * any non-singleton currency type: the WIDE `CurrencyCents<string>`, and
+ * also a finite union such as `CurrencyCents<"USD" | "EUR">` (e.g. from a
+ * validator's `t.UnionEnum`). A currency read back from a DB row or
+ * narrowed only to a finite set of allowed codes types as `string` or a
+ * union, not a single literal, so without this, `addCents(currencyCents(a,
+ * x), currencyCents(b, y))` would still typecheck even when `a`/`b` are
+ * both known only up to a union of currencies that could differ at
+ * runtime — the compile-time guarantee above only bites for a genuine
+ * single-literal currency type on both operands. Code that aggregates rows
+ * with a dynamic or union (non-singleton) currency must use `MoneyTotals`
+ * instead, which buckets by currency at runtime and is the runtime-correct
+ * tool for that case.
+ */
+declare const addCents: <A extends string, B extends A = A>(a: IsSingletonCurrency<A> extends never ? never : CurrencyCents<A>, b: IsSingletonCurrency<B> extends never ? never : CurrencyCents<B>) => CurrencyCents<A>;
+/**
+ * Per-currency accumulator for aggregating money across rows that may carry
+ * different currencies (e.g. time entries across matters, expenses across
+ * clients). There is deliberately no method that returns a single combined
+ * number: the only way to read totals out is `entries()`, which groups by
+ * currency and sorts deterministically by currency code. This keeps
+ * cross-currency summation structurally unreachable through this package's
+ * API — callers must handle each currency's total explicitly.
+ *
+ * Division of responsibility with `addCents`: `addCents` gives a
+ * compile-time guarantee, but only when both operands carry a single
+ * string-literal currency type (`CurrencyCents<"USD">`); it rejects both
+ * the wide `CurrencyCents<string>` and a finite union such as
+ * `CurrencyCents<"USD" | "EUR">` outright. Any flow whose currency is
+ * dynamic or only known up to a union of allowed codes (read from a DB row,
+ * request body, etc.) cannot satisfy that singleton-literal constraint and
+ * must bucket through `MoneyTotals` instead, which enforces
+ * the same "never sum across currencies" invariant at runtime via the
+ * per-currency `Map`.
+ */
+type MoneyTotalsEntry = {
+  currency: string;
+  amountCents: CentsAmount;
+};
+declare class MoneyTotals {
+  #private;
+  /** Add `amountCents` to the running total for `currency`. */
+  add(currency: string, amountCents: CentsAmount): void;
+  /**
+   * Per-currency totals, sorted deterministically by currency code so
+   * output (PDF lines, API responses) does not depend on insertion order.
+   * Sorts by UTF-16 code unit (default `Array.sort`) rather than
+   * `localeCompare`, so ordering does not vary with the runtime's locale.
+   */
+  entries(): MoneyTotalsEntry[];
+}
+//#endregion
+export { ApplyMarkupCentsInput, CentsAmount, CurrencyCents, MoneyTotals, MoneyTotalsEntry, ProrateHourlyCentsInput, addCents, applyMarkupCents, cents, currencyCents, prorateHourlyCents, unsafeCents };

package/dist/index.js

@@ -0,0 +1,89 @@
+//#region src/index.ts
+/**
+* Construct a CentsAmount from a value already known to be in minor
+* units. Use at boundaries where the input is validated as an integer
+* minor-unit value (e.g. after Elysia `t.Integer({ minimum: 0 })` or
+* after parsing user input that has been multiplied by 100).
+*
+* Throws on non-integer input — money math at the minor-unit level must
+* be exact.
+*/
+const cents = (value) => {
+	if (!Number.isInteger(value)) throw new TypeError(`cents(${value}): money values must be integer minor units`);
+	return value;
+};
+/**
+* Escape hatch for code paths that genuinely need to attach the brand
+* without a runtime check (test fixtures, generated code). Prefer
+* `cents()` everywhere else; reach for this only with a `// SAFETY:`
+* comment naming why the value is already a valid minor-unit integer.
+*/
+const unsafeCents = (value) => value;
+const prorateHourlyCents = ({ billedMinutes, hourlyRateCents }) => {
+	assertNonNegativeInteger("billedMinutes", billedMinutes);
+	assertNonNegativeInteger("hourlyRateCents", hourlyRateCents);
+	return cents(Math.floor((billedMinutes * hourlyRateCents + 30) / 60));
+};
+const applyMarkupCents = ({ amountCents, markupPercent }) => {
+	assertNonNegativeInteger("amountCents", amountCents);
+	assertNonNegativeInteger("markupPercent", markupPercent);
+	return cents(Math.floor((amountCents * (100 + markupPercent) + 50) / 100));
+};
+function assertNonNegativeInteger(name, value) {
+	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) throw new TypeError(`${name} must be a finite non-negative integer`);
+}
+/**
+* Construct a `CurrencyCents<C>` from a currency code and a minor-unit
+* amount. The only producer of `CurrencyCents`; downstream code narrows `C`
+* from the literal `currency` argument (e.g. `currencyCents("USD", 100)`
+* infers `CurrencyCents<"USD">`).
+*/
+const currencyCents = (currency, amount) => {
+	if (!currency) throw new TypeError("currencyCents(): currency must be a non-empty code");
+	return cents(amount);
+};
+/**
+* Add two `CurrencyCents` amounts of the SAME currency. The second
+* parameter's currency `B` is constrained to `extends A`, so passing a
+* different currency literal (e.g. `addCents(usdAmount, eurAmount)`) is a
+* compile error, not a runtime bug — see `packages/money/src/index.test.ts`
+* for the `@ts-expect-error` proof.
+*
+* Both operands are further constrained by `IsSingletonCurrency` to reject
+* any non-singleton currency type: the WIDE `CurrencyCents<string>`, and
+* also a finite union such as `CurrencyCents<"USD" | "EUR">` (e.g. from a
+* validator's `t.UnionEnum`). A currency read back from a DB row or
+* narrowed only to a finite set of allowed codes types as `string` or a
+* union, not a single literal, so without this, `addCents(currencyCents(a,
+* x), currencyCents(b, y))` would still typecheck even when `a`/`b` are
+* both known only up to a union of currencies that could differ at
+* runtime — the compile-time guarantee above only bites for a genuine
+* single-literal currency type on both operands. Code that aggregates rows
+* with a dynamic or union (non-singleton) currency must use `MoneyTotals`
+* instead, which buckets by currency at runtime and is the runtime-correct
+* tool for that case.
+*/
+const addCents = (a, b) => cents(a + b);
+var MoneyTotals = class {
+	#totals = /* @__PURE__ */ new Map();
+	/** Add `amountCents` to the running total for `currency`. */
+	add(currency, amountCents) {
+		if (!currency) throw new TypeError("MoneyTotals.add(): currency must be a non-empty code");
+		const running = this.#totals.get(currency) ?? cents(0);
+		this.#totals.set(currency, cents(running + amountCents));
+	}
+	/**
+	* Per-currency totals, sorted deterministically by currency code so
+	* output (PDF lines, API responses) does not depend on insertion order.
+	* Sorts by UTF-16 code unit (default `Array.sort`) rather than
+	* `localeCompare`, so ordering does not vary with the runtime's locale.
+	*/
+	entries() {
+		return [...this.#totals.keys()].sort().map((currency) => ({
+			currency,
+			amountCents: this.#totals.get(currency) ?? cents(0)
+		}));
+	}
+};
+//#endregion
+export { MoneyTotals, addCents, applyMarkupCents, cents, currencyCents, prorateHourlyCents, unsafeCents };

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@stll/money",
-  "version": "0.0.1-placeholder.0",
-  "description": "Placeholder to bootstrap npm trusted publishing. Real releases are published from stella/stella via GitHub Actions.",
-  "license": "Apache-2.0"
+  "version": "0.1.0",
+  "description": "Branded minor-unit monetary amounts and currency-safe billing arithmetic.",
+  "keywords": [
+    "billing",
+    "currency",
+    "minor-units",
+    "money",
+    "typescript"
+  ],
+  "homepage": "https://github.com/stella/stella/tree/main/packages/money",
+  "bugs": {
+    "url": "https://github.com/stella/stella/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stella/stella.git",
+    "directory": "packages/money"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "git clean -xdf dist .cache .turbo node_modules",
+    "build": "tsdown",
+    "pack:dry-run": "bun pm pack --dry-run",
+    "test": "bun test src",
+    "typecheck": "bun ../../packages/scripts/src/tsc-native.ts --noEmit",
+    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware packages/money",
+    "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/money",
+    "format": "oxfmt .",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@stll/typescript-config": "0.0.0",
+    "@types/bun": "1.3.14",
+    "tsdown": "0.22.14"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }