Skip to content

💰 Abstractions / Primitives

🎯 Purpose

The Primitives folder defines the core value types and result structures used throughout the Currency system.

These are the lowest-level building blocks. They are data-oriented, deterministic, and implementation-agnostic.

🧠 Usage Guidance

Primitives are intended to:

  • Provide stable, reusable value types
  • Define operation results and outcome codes
  • Support deterministic currency logic
  • Avoid primitive leakage (e.g. raw strings, floats, ad-hoc structs)

🧩 What Lives Here

CurrencyId

  • Canonical currency identifier (e.g. "gold", "gems")

  • Normalized:

  • trimmed

  • lowercase (invariant)
  • Suitable for dictionary keys and hashing

Money

  • Integer currency amount (minor units, long)
  • No floats or decimals
  • Checked arithmetic (overflow-aware)
  • Includes TryAdd / TrySub helpers

CurrencyDelta

  • Immutable snapshot of a committed balance change

  • Contains:

  • owner

  • currency
  • before/after values

CurOpCode

  • Machine-readable operation outcomes

  • Examples:

  • Ok

  • InvalidArgs
  • InsufficientFunds
  • Unauthorized

CurOpResult

  • Result of a currency operation

  • Contains:

  • outcome code

  • optional message
  • Success is derived from Code

⚠️ Important Notes

  • Primitives do not perform business or orchestration logic
  • Behaviour is limited to value semantics, validation, and simple arithmetic
  • Currency is represented in minor units (integers)
  • Conversion from floats/decimals should occur at system boundaries
  • CurOpResult.Message is intended for human-readable output only
  • Overflow handling is explicit via checked arithmetic

🧠 Usage Guidance

Mental model

  • These types form the language of the Currency system
  • Higher-level systems compose behaviour using these primitives
  • Consumers should treat identifiers and results as opaque data

🚫 Internal Use Only

This folder defines shared primitives.

Do not:

  • Add business or orchestration logic
  • Introduce dependencies on higher-level systems
  • Rely on internal formatting or representation details

🧹 Safe to Remove

This folder should not be removed if any Currency system is in use.

All higher-level systems depend on these primitives.

  • Abstractions / Services — uses these primitives
  • PublicAPI — consumes these types in helpers and workflows
  • Internal — implements behaviour using these primitives