Skip to content

Commit 4c98954

Browse files
committed
Add TigerBeetle Schema Wizard
1 parent 712c56a commit 4c98954

File tree

8 files changed

+589
-0
lines changed

8 files changed

+589
-0
lines changed
Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules
2+
dist
Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
<img src="https://github.com/emschwartz/tigerbeetle-schema-wizard/assets/3262610/046153f4-4657-4109-89b0-cb990b790621" width=200 />
2+
3+
# TigerBeetle Schema Wizard
4+
5+
## Backstory
6+
7+
_Once in the whimsical world of DataOz, a place where semicolons frolicked and functions danced, there was a legendary accounting database known as TigerBeetle, the guardian of debits and credits. Like Dorothy in her quest for the Emerald City, our heroes—Alice the Analyst, Bob the Backend Dev, and Charlie the CPA—were on a quest to master this digital beast to balance their mystical ledgers. "If only we could speak 'TigerBeetlese'," sighed Alice, as they stared at a maze of numbers more perplexing than the riddles of the Sphinx._
8+
9+
_Bob, ever the optimist despite once trying to use a sandwich as a floppy disk, chimed in, "Fear not, for legend speaks of the TigerBeetle Schema Wizard, a being who can conjure a robot so smart, it would turn our business logic into TigerBeetle treats!" Off they went, down the winding paths of code, through forests of parentheses, and over mountains of syntax errors. They faced obstacles like the Wicked Witch of the Wrong Data Type and the Flying Monkeys of Misplaced Decimals. "Remember," Charlie said as they debugged yet another haunted function, "when we find the Schema Wizard, we must ask for client code that's as easy to use as a scarecrow's brain is to install—plug, play, and no hay required!"_
10+
11+
## Overview
12+
13+
When using TigerBeetle, you need to model your use case in terms of [ledgers](https://docs.tigerbeetle.com/reference/accounts#ledger), [codes](https://docs.tigerbeetle.com/reference/accounts#code), [accounts](https://docs.tigerbeetle.com/reference/accounts), and [transfers](https://docs.tigerbeetle.com/reference/transfers). That means developers need to first wrap their heads around double-entry bookkeeping in order to take advantage of the power of TigerBeetle.
14+
15+
This project aims to simplify the usage of TigerBeetle by allowing you to define the schema of your business logic in a simple TOML format. It then generates client code in any of the supported languages to make building systems on top of TigerBeetle easy and error-free.
16+
17+
By generating the client code from provided ledger types, we make it easier for developers to use TigerBeetle without thinking about questions like:
18+
19+
- What `ledger` numbers should we use for each currency?
20+
- What's the difference between a `ledger` and a `code`?
21+
- Is a user's balance equal to the debits minus credits or vice versa?
22+
- How do we use linked transfers to enable cross-currency transfers across ledgers?
23+
24+
## Contents
25+
26+
- [Schema](./schema.toml)
27+
- [Generated TypeScript client code\*](./src/generated.ts)
28+
- [Example usage script](./src/index.ts)
29+
30+
\* Note: the client code is not currently being generated 😋
31+
32+
## Trying it out
33+
34+
1. [Run TigerBeetle on your local machine](https://docs.tigerbeetle.com/quick-start/single-binary)
35+
2. Clone this repo
36+
3. `npm install`
37+
4. Run `npm run dev` to create two accounts, fund them, and send a transfer between them
38+
39+
## Challenges we ran into
40+
41+
The biggest one was actually wrapping my head around the double-entry bookkeeping model, which gave me more of an appreciation for what developers trying to use TigerBeetle will need to do. Aside from that, I ran into the following documentation and client library issues:
42+
43+
- https://github.com/tigerbeetle/docs/issues/36
44+
- https://github.com/tigerbeetle/docs/issues/37
45+
- https://github.com/tigerbeetle/tigerbeetle/issues/1284
46+
- https://github.com/tigerbeetle/tigerbeetle/issues/1285
47+
- https://github.com/tigerbeetle/tigerbeetle/issues/1287
48+
- https://github.com/tigerbeetle/tigerbeetle/issues/1290
49+
50+
Oh, also, I didn't actually have enough time to start generating the client code from the schema 😋
51+
52+
## Accomplishments that we're proud of
53+
54+
TigerBeetle's model seems -- and is -- very simple. However, figuring out how to correctly model your application's business logic using double-entry bookkeeping is quite tricky, unless you have prior experience with it. Something along the lines of this project would probably help developers get started with standard use cases much more quickly.
55+
56+
## What's next for TigerBeetle Schema Wizard
57+
58+
1. Actually generate the TypeScript client code from the schema
59+
2. Add more transfer types (including currency exchange)
60+
3. Add more ledger types
61+
4. Add support for other programming languages

projects/tigerbeetle-schema-wizard/package-lock.json

Lines changed: 247 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"name": "tigerbeetle-schema-wizard",
3+
"version": "1.0.0",
4+
"description": "",
5+
"main": "dist/index.js",
6+
"type": "module",
7+
"scripts": {
8+
"test": "echo \"Error: no test specified\" && exit 1",
9+
"build": "tsc",
10+
"dev": "ts-node ."
11+
},
12+
"author": "",
13+
"license": "ISC",
14+
"devDependencies": {
15+
"@types/node": "^20.9.0",
16+
"ts-node": "^10.9.1",
17+
"type-fest": "^4.6.0",
18+
"typescript": "^5.2.2"
19+
},
20+
"dependencies": {
21+
"tigerbeetle-node": "^0.14.160",
22+
"uuidv7": "^0.6.3"
23+
}
24+
}
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# This is a simple schema that the TigerBeetle Schema Wizard
2+
# can use to generate client code to interact with TigerBeetle
3+
4+
[ledgers]
5+
6+
[ledgers.eur]
7+
type = "simple_bank_accounts"
8+
9+
[ledgers.usd]
10+
type = "simple_bank_accounts"
11+
allow_negative = false # change this and you're going to jail!

0 commit comments

Comments
 (0)