Quick start ¶
Fresh TypeScript project to a typed write in ≤5 minutes.
Install ¶
mkdir my-data && cd my-data
git init -b main
npm init -y
npm install gitsheets zod
Declare a sheet ¶
Create .gitsheets/users.toml:
[gitsheet]
root = 'users'
path = '${{ slug }}'
[gitsheet.schema]
type = 'object'
required = ['slug', 'email']
additionalProperties = false
[gitsheet.schema.properties.slug]
type = 'string'
pattern = '^[a-z0-9-]+$'
[gitsheet.schema.properties.email]
type = 'string'
format = 'email'
Commit it so gitsheets sees it:
git add .gitsheets/
git commit -m "add users sheet"
Write your first record ¶
import { openRepo, openStore } from 'gitsheets';
import { z } from 'zod';
const UserSchema = z.object({
slug: z.string(),
email: z.string().email(),
fullName: z.string().optional(),
});
const repo = await openRepo();
const store = await openStore(repo, {
validators: { users: UserSchema },
});
await store.transact(
{
message: 'janedoe: POST /api/users',
author: { name: 'Jane Doe', email: 'jane@x.org' },
trailers: { Action: 'user.create' },
},
async (tx) => {
await tx.users.upsert({ slug: 'janedoe', email: 'jane@x.org' });
},
);
That produces a commit on the current branch:
git log -1 --format=fuller
Read it back ¶
const jane = await store.users.queryFirst({ slug: 'janedoe' });
// jane is z.infer<typeof UserSchema> | undefined
What just happened ¶
openStorediscovered theuserssheet from.gitsheets/.tx.users.upsert(...)validated the record against the persisted JSON Schema and the Zod schema, applied canonical normalization, rendered the pathusers/janedoe.toml, and staged the write.store.transactcommitted the staged tree with your message, author, and trailers, and advancedmainto the new commit.
That commit landed on main, the branch you have checked out, so git status
will now show the new record file as missing from your working tree until you
git checkout HEAD -- . — gitsheets writes refs, not files. To keep records off
the code branch entirely, bind the repository to a data branch or a data
submodule: see the headless data recipe.
See docs/cli.md for the shell-side surface or the
specs/
directory for the full contract.