📑 Index

• Overview
• About getMe Core Engine
• Server Dependency & Docker
  • Running the Core Engine via Docker
  • Connecting the SDK to the Core Engine
  • Why manage the core engine separately?
• Installation & Usage
• Other Available SDKs
• Links and Resources
• License

📖 Overview

The official JavaScript/TypeScript client library for the getMe key-value store. This SDK abstracts the underlying API calls, providing Node.js developers with a simple, strongly-typed, and idiomatic interface to interact directly with the getMe runtime.

🧠 About getMe Core Engine

getMe is a persistent, embeddable key-value store written in Go. It is heavily inspired by the design of Bitcask and is optimized for high write throughput and low-latency reads.

The engine runs on a few core principles:

• Log-Structured Storage: All data is written to an append-only log file, maximizing write speed by avoiding slow, random disk I/O.
• In-Memory Hash Index: A hash table is maintained in memory mapping each key to its exact on-disk location, enabling single disk seek lookups.
• Compaction: A background process that periodically removes stale data to reclaim disk space.
• Batch Operations: A batch API amortizes the cost of writes, allowing for extremely high ingestion rates.

For a deep dive into the architecture, please refer to the Root README and the Server README.

🚀 Server Dependency & Docker

Important: This SDK acts merely as a client. The getMe core server engine must be running independently for this library to function. The SDK interacts with the Core Engine through a Unix Domain Socket (UDS).

Running the Core Engine via Docker

You can use the official Docker images mentioned in our DockerHub README.

For maximum performance, we recommend using the Core Server Only container (ContainerFile.server), which isolates the database engine:

docker build -t getme-core -f ../../ContainerFile.server ../../
docker run -d \
  --name getme-engine \
  -v getme_data:/var/lib/getMeStore \
  -v /tmp/getMeStore/sockDir:/tmp/getMeStore/sockDir \
  getme-core

Connecting the SDK to the Core Engine

The SDK communicates with the engine via the Unix Domain Socket (getMe.sock). Because the engine creates the socket in /tmp/getMeStore/sockDir, it is critical that this exact directory is bind-mounted when running the container so that your local Node.js application can reach it.

To connect your JS/TS SDK to the core engine:

1. Ensure the getMe server is running (either locally or via Docker with the /tmp/getMeStore/sockDir volume mounted).
2. Point your SDK initialization to the socket file location by setting the GETME_SOCKET_PATH environment variable (default: /tmp/getMeStore/sockDir/getMe.sock).

Why manage the core engine separately?

Decoupling the database engine from the JavaScript logic provides several critical advantages:

• Performance & Isolation: The core engine heavily utilizes memory for its hash index and performs continuous background disk I/O for compaction. Running it separately prevents the storage engine from starving your Node.js application (and V8 garbage collector) of memory or compute resources (and vice-versa).
• Independent Scaling: You can scale your Node.js applications dynamically while connecting to a centralized, standalone getMe instance.
• Polyglot Ecosystems: A decoupled server can serve multiple applications simultaneously, even if those applications are built across entirely different technology stacks.

💻 Installation & Usage

Install the SDK via npm, yarn, or pnpm:

npm install getme-js-sdk
# or
pnpm add getme-js-sdk

Next, ensure you tell the SDK where to find your locally mounted Unix socket by setting the GETME_SOCKET_PATH environment variable:

export GETME_SOCKET_PATH=/tmp/getMeStore/sockDir/getMe.sock

Basic Example

import { GetMeClient } from 'getme-js-sdk';

const client = new GetMeClient(); // Connects automatically using GETME_SOCKET_PATH

async function run() {
  // Store a value
  await client.put('myKey', 'myValue');

  // Retrieve the value
  const value = await client.get('myKey');
  console.log('Value:', value);
}

run();

📦 Other Available SDKs

While this is the JavaScript/TypeScript client, getMe supports multiple languages. Detailed information on all available SDKs can be found in the Root README.

• Go SDK
• Java SDK
• JavaScript/TypeScript SDK (This package)
• Python SDK

🔗 Links and Resources

Below is a comprehensive list of resources and documentation linked throughout the getMe ecosystem:

• getMe Root Repository
• Root README
• DockerHub README
• Server Engine Source
• AGPLv3 License

Engineering Blog Series

• Building getMe - Part I
• Building getMe - Part II

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3) - see the LICENSE file for details.