Skip to content

README.md

Latest commit

 

History

History
216 lines (170 loc) · 8.04 KB

README.md

File metadata and controls

216 lines (170 loc) · 8.04 KB
Raw

Rizzbase

Rizzbase is a local-first database for Node.js. Each Project is one encrypted, Brainrot-encoded .rizz file on your computer. There is no cloud service, network database, account, or realtime connection.

Why Rizzbase?

  • Your data stays local. No hosted database, account, or network service.
  • Encrypted Projects. AES-256-GCM protects one portable .rizz file with a key derived from your passphrase.
  • Ordinary TypeScript. Store JSON documents and query them with a small, typed API backed by a Go engine.
  • Back up on your terms. Keep encrypted .rizz copies, or export a decrypted JSON snapshot when you need an interoperable backup.
  • Small, transparent scope. Rizzbase is a local file library, not a realtime cloud platform. Queries scan a Lobby in memory; there are no indexes.

V1 includes the Go engine and CLI, the TypeScript/Node.js SDK, Project/Lobby/Yap operations, in-memory filters and ordering, and JSON export/restore. The React product UI is a preview and is not connected to local database files.

Install

npm install rizzbase

Requires Node.js 20 or newer. The first SDK operation downloads the matching engine binary for macOS, Linux or Windows on x64 or arm64. Later calls use the verified local cache. Downloads come from versioned GitHub releases and are checked against the release's SHA-256 manifest.

The rizzbase@1.1.0 package is published on npm, and the matching v1.1.0 GitHub release contains the engine binaries and SHA-256 manifest:

The published SDK includes query ordering and JSON backup/restore. Install it with npm install rizzbase.

60-second quick start

Requires Node.js 20+ and a supported macOS, Linux, or Windows x64/arm64 machine. Install the published SDK:

npm install rizzbase
read -rsp "Project passphrase: " RIZZBASE_PASSPHRASE
printf '\n'
export RIZZBASE_PASSPHRASE

These passphrase commands are for Bash/Zsh. In other environments, use a private prompt or secret manager. Do not commit the passphrase or put it in application arguments. Save this as quick-start.mjs:

import { Rizzbase, RizzbaseError } from "rizzbase";

const passphrase = process.env.RIZZBASE_PASSPHRASE;
if (!passphrase) throw new Error("Set RIZZBASE_PASSPHRASE privately.");

const db = new Rizzbase("./journal.rizz", passphrase);
try {
  await db.open();
} catch (error) {
  if (!(error instanceof RizzbaseError) || error.code !== "FILE_NOT_FOUND") throw error;
  await db.create("Personal journal");
}
const notes = (await db.listLobbies()).find(lobby => lobby.name === "notes")
  ?? await db.createLobby("notes");

await db.createYap(notes.id, `note-${Date.now()}`, {
  title: "Hello, local storage",
  text: "This is encrypted in my local Project file.",
  createdAt: new Date().toISOString(),
});

const latest = await db.query(notes.id)
  .limit(10)
  .exec();
console.log(latest);

Run node quick-start.mjs. The example opens an existing Project if present; create() itself intentionally refuses to overwrite one.

Examples

The repository includes interactive Notes and Todo list apps. They demonstrate persistent data, filtered/ordered queries, and updates. See how to run the examples. The example scripts import the SDK from this repository, so build the local SDK and engine before running them.

Build and test from source

cd sdk
npm install
npm run build
npm test

Deploy the UI to Vercel

The React preview is a Vite static site. Import this repository into Vercel with the repository root as the project root; Vercel detects Vite automatically. Use npm run build as the build command and dist as the output directory if setting these manually. The app uses hash-based navigation, so it does not require server rewrites. The deployed UI remains a mock preview and does not connect to local .rizz files or provide hosted database features.

Reopen an existing Project

import { Rizzbase } from "rizzbase";

const passphrase = process.env.RIZZBASE_PASSPHRASE;
if (!passphrase) throw new Error("Set RIZZBASE_PASSPHRASE privately.");
const db = new Rizzbase("./journal.rizz", passphrase);
const project = await db.open();
const [notes] = await db.listLobbies();
const recent = await db.query(notes.id).limit(10).exec();
console.log(project.name, recent.length);

create() is for first-time project setup and refuses to overwrite an existing file. Keep the project path and passphrase private. Read the beginner-friendly guide and API reference.

Project vocabulary

  • Project: one encrypted .rizz file. It holds its name, metadata and Lobbies.
  • Lobby: a named group in a Project, with a generated ID and a set of Yaps.
  • Yap: a JSON document with an ID you choose, stored inside a Lobby.

Query example

Filters are AND-combined, dot-separated paths access nested object fields, and the optional limit is applied after filtering and ordering. Without orderBy, results are sorted by Yap ID. Queries read the Lobby into memory; V1 has no indexes or persisted query engine.

const active = await db.query("YOUR-LOBBY-ID")
  .where("user.active", "==", true)
  .where("score", ">=", 10)
  .orderBy("score", "desc")
  .limit(20)
  .exec();

Supported operators: ==, !=, >, >=, <, <=. Equality compares JSON values (including objects and arrays); filter comparisons support numbers and strings. orderBy sorts by a numeric or string field before limit; see query details.

JSON backup and restore

await db.export("./backup.json");

const restored = new Rizzbase("./restored.rizz", getPassphrasePrivately());
await restored.importBackup("./backup.json");

JSON backups contain decrypted project data. Store them securely, do not commit them, and remove them when no longer needed. Export and import refuse to overwrite files; restore creates an encrypted Project using the supplied passphrase. See the SDK backup API and safety details.

Security and limits

  • Choose a strong, unique passphrase and obtain it through private user input or a secrets manager. Do not commit, log, print, or place it in command-line arguments. The SDK sends it only to its local engine over stdin.
  • Projects use AES-256-GCM with PBKDF2-HMAC-SHA256 at 600,000 iterations. Wrong passphrases and damaged ciphertext fail authentication. There is no passphrase recovery or key rotation.
  • The SDK downloads a platform binary over HTTPS and validates its SHA-256 against a versioned release manifest. Set binaryPath to use a build you obtained and trust yourself. Checksums detect corruption; they are not a signed provenance system.
  • Keep secure backups of .rizz files. JSON export is also available, but it contains decrypted data and must be protected accordingly. A local file lock blocks a second writer; after a crash, check that no process is still writing before manually removing its adjacent .lock directory.
  • Each operation's JSON request is limited to 64 KiB; query results are bounded by the 64 MiB encoded-project file limit.
  • This is local-only V1: no realtime, cloud storage, multi-user access, remote backup, or UI connection. The Go API and CLI have their own documented limits.

Develop this repository

cd engine
go test -race ./...
go vet ./...
cd ../sdk
npm install
npm test
npx tsc --noEmit --strict --target ES2022 --module Node16 \
  --moduleResolution Node16 --types node test/typecheck.ts

Go 1.24+ and Node.js 20+ are required. The SDK's tests build the local Go CLI and exercise it using temporary encrypted projects. Binary releases build six OS/architecture variants when a matching version tag is pushed; the current source version expects v1.1.0.

See SDK guide, file format and Go API, contributing and security. Rizzbase is licensed under the MIT License.