TinyKV

TinyKV is a local application memory runtime built in Go.

The goal is simple: start with a small command-line key-value store, then gradually grow it into a serious local cache/runtime with TTLs, concurrency safety, daemon mode, observability, and migration tooling.

This is not trying to be Redis on day one.

TinyKV is a learning-first infrastructure project designed to build real systems programming skill through progressively harder milestones.

Why TinyKV?

Most applications eventually need some kind of fast temporary memory:

• cached API responses
• counters
• session-like data
• temporary workflow state
• short-lived lookup data
• local development cache

Usually, developers reach for Redis early, even when the application may not need a networked external cache yet.

TinyKV explores a smaller idea:

What if an application could start with simple local memory, then grow toward a daemonized runtime when needed?

Current Status

TinyKV is currently in Phase 1: Go Foundations & CLI Store.

The current focus is building a clean command-line key-value store while learning Go fundamentals.

Phase 1 Features

• SET
• GET
• DEL
• EXISTS
• LIST
• HELP
• EXIT

Not Built Yet

The following are intentionally out of scope for the first phase:

• networking
• persistence
• concurrency
• daemon mode
• distributed systems

The point of Phase 1 is to build the foundation correctly before adding complexity.

Project Goals

TinyKV is being built to learn and demonstrate:

• Go syntax and project structure
• structs, methods, maps, and slices
• command parsing
• package organization
• unit testing
• cache design
• TTL and expiration logic
• concurrency with goroutines and mutexes
• daemon architecture
• local networking
• Unix sockets
• memory management
• observability
• open-source infrastructure practices

Roadmap

Phase 1: Go Foundations & CLI Store

Build a working CLI key-value store.

Core commands:

SET <key> <value>
GET <key>
DEL <key>
EXISTS <key>
LIST
HELP
EXIT

Deliverables:

• working CLI
• unit tests
• README

Phase 2: Expiration, TTL & Concurrency

Transform the store into a real cache.

Planned features:

• TTL support
• expiration timestamps
• background cleanup worker
• INCR
• DECR
• namespaces
• thread-safe operations

Concepts:

• goroutines
• channels
• sync.Mutex
• sync.RWMutex
• Go time package

Phase 3: Daemon Architecture

Separate application memory from the application process.

Planned components:

• appmemd daemon
• appmemctl CLI client
• request/response protocol
• TCP localhost transport
• graceful shutdown

Phase 4: Unix Socket Runtime

Move toward production-quality local communication.

Planned features:

• Unix socket support
• socket permissions
• connection pooling
• local-only runtime mode

Phase 5: Memory Management

Prevent unbounded memory growth.

Planned features:

• memory limits
• LRU eviction
• access tracking
• object sizing
• stress tests
• benchmarks

Phase 6: Observability

Make TinyKV operable.

Planned features:

• structured logging
• metrics endpoint
• health checks
• STATS command
• troubleshooting guide

Phase 7: Import/Export System

Add portability.

Planned features:

• JSONL export
• JSONL import
• validation
• backup workflow
• restore workflow

Phase 8: TypeScript SDK

Make TinyKV easier to adopt from JavaScript and TypeScript applications.

Planned features:

• TypeScript client
• typed APIs
• examples for Express, NestJS, and Next.js
• npm package

Phase 9: Migration Framework

Allow users to graduate from TinyKV.

Planned features:

• Redis export
• database export
• migration reports
• migration CLI

Phase 10: Open Source Launch

Prepare the project for public use and contribution.

Planned features:

• CI/CD
• release automation
• Docker image
• Homebrew package
• architecture documentation
• contributing guide
• benchmarks

Future Direction

A distributed memory runtime may be explored later, but it is intentionally not part of the early roadmap.

Potential future features:

• replication
• consistent hashing
• failover
• rebalancing
• namespace ownership
• cluster discovery

This would turn TinyKV into a distributed systems project and should only happen after the local runtime is mature.

Project Structure

Current intended structure:

cmd/
  TinyKV/
    main.go

internal/
  commands/
    command.go
    handler.go

  store/
    store.go
    store_test.go

Package Responsibilities

cmd/TinyKV

Application entry point. Handles CLI startup and the input loop.

internal/commands

Parses user input into commands and executes those commands against the store.

internal/store

Owns the key-value data model and store behavior.

The store package should not know about CLI input, terminal output, or command strings.

Example Usage

$ TinyKV

TinyKV CLI
Type HELP for commands

> SET name Shanil
OK

> GET name
Shanil

> EXISTS name
true

> LIST
name = Shanil

> DEL name
deleted

> GET name
(nil)

> EXIT
bye

Development

Run the CLI:

go run ./cmd/TinyKV

Run tests:

go test ./...

Format code:

go fmt ./...

Design Principles

Start Small

Do not build networking, persistence, or concurrency before the basic store is solid.

Keep Responsibilities Separate

Command parsing belongs in the commands package.

Storage logic belongs in the store package.

The CLI should wire the system together, not contain the entire application.

Prefer Boring Code

TinyKV should grow through clear, understandable Go code rather than unnecessary abstractions.

Learn by Building

This project is not only about the finished tool. It is about learning the engineering behind caches, runtimes, daemons, memory management, and observability.

Success Criteria

This project succeeds if it helps build deep Go and systems programming skill.

Specific goals:

• learn Go deeply
• understand cache design
• understand daemon architecture
• understand concurrency
• build a useful open-source project
• document the journey clearly

Revenue is optional.

Learning is mandatory.

License

MIT License.