SDKs

Six official clients, one behavior. Point any of them at a single node or at a discovery server — the SDK detects which from the server's own handshake, so development and production use identical code.

Every SDK ships the full feature set: authentication, TLS, discovery replica lists, replication-aware routing (reads fail over, writes fan out to all R owners), transparent reconnect (see below for what is retried), always-on keep-alive, opt-in transparent value compression, opt-in fire-and-forget replica writes, opt-in read repair, and the same rendezvous-hashing pipeline verified against shared cross-language test vectors. Values are strings first: every get returns a string, with a get_bytes-style companion for raw byte values. The text getter is strict UTF-8 in five SDKs (a stored value that is not valid UTF-8 raises); in Go, where a string can hold any bytes, Get returns the bytes unchanged and GetBytes is the []byte form.

A connection found closed is redialed on its next use in every SDK and mode. Whether a request that loses its connection while it is in flight is sent again depends on the mode. In cluster mode every SDK retries it once, after refreshing the node list from discovery, so a key whose primary died is rerouted. In single-node and proxy mode Go, Rust, Java and .NET also retry once: they redial and resend (a proxy client whose proxy is unreachable fails over to another proxy from discovery’s roster). Python does not retry in either mode, and TypeScript does not in single-node mode: the call fails with the connection-lost error and the next call redials. TypeScript in proxy mode re-fetches the proxy roster and retries once, as in cluster mode. In every case a non-idempotent request (incr/decr, the compare-and-set calls, delete-if-matches) is resent only when the SDK can show that nothing was sent.

A TTL is whole seconds; 0 (or omitting it) means no expiry. The wire field is an unsigned 64-bit decimal, and the largest value an SDK accepts is set by its integer type: 2^64 − 1 in Python and Rust, 2^63 − 1 in Go, Java and .NET, and 2^53 − 1 (Number.MAX_SAFE_INTEGER) in TypeScript, which throws RangeError above that. Any value up to 2^53 − 1 works in every SDK.

LanguageRequiresPackageDocs
TypeScript / Node.jsNode 22+nanocached (npm)README
Python3.11+, asyncionanocached (PyPI)README
Java17+org.nanocached:nanocached (Maven Central)README
Rusttokionanocached (crates.io)README
.NET.NET 10+Nanocached (NuGet)README
Go1.26+github.com/nanocached/nanocached/sdk/goREADME

None of the SDKs has runtime dependencies outside its language's standard library, except Rust: its client uses tokio, futures-util and sha2, plus flate2 and rustls behind the default compression and tls cargo features, which can be compiled out.

The SDKs are pre-1.0, and all of them ship at one version together with the server; what 1.0.0 will promise is on the compatibility page. Every SDK also builds directly from the repository.

TypeScript

npm install nanocached
import { NanocachedClient } from "nanocached";

const client = await NanocachedClient.connect({
  addresses: [{ host: "127.0.0.1", port: 8357 }],
});

await client.set("greeting", "hello", 60);       // TTL seconds; omit = no expiry
const value = await client.get("greeting");      // string | null
const existed = await client.delete("greeting"); // boolean

await client.close();

Python

pip install nanocached
import asyncio
from nanocached import NanocachedClient

async def main():
    async with await NanocachedClient.connect([("127.0.0.1", 8357)]) as client:
        await client.set("greeting", "hello", ttl_seconds=60)
        value = await client.get("greeting")        # str | None
        existed = await client.delete("greeting")   # bool

asyncio.run(main())

Java

Group/artifact: org.nanocached:nanocached.

import org.nanocached.NanocachedClient;
import org.nanocached.NanocachedClient.Address;
import org.nanocached.NanocachedClient.Options;

import java.util.List;
import java.util.Optional;

try (NanocachedClient client = NanocachedClient.connect(
        new Options().addresses(List.of(new Address("127.0.0.1", 8357))))) {
    client.set("greeting", "hello", 60);                 // TTL seconds; omit = no expiry
    Optional<String> value = client.get("greeting");     // empty when missing
    boolean existed = client.delete("greeting");
}

Spring users: the separate org.nanocached:nanocached-spring module implements Spring's CacheManager/Cache on this SDK — named caches as namespaces, per-cache TTL, clear() as the namespace's CLEAR. See adapters/spring. Spring Boot users can instead add org.nanocached:nanocached-spring-boot-starter, which autoconfigures both beans from nanocached.* properties — no Java config. See adapters/spring-boot-starter. JSR-107 (javax.cache) users can instead add org.nanocached:nanocached-jcache, an honest-subset CachingProvider/CacheManager/Cache implementation discoverable via Caching.getCachingProvider(). See adapters/jcache.

Rust

cargo add nanocached
use nanocached::{NanocachedClient, Options};

let client = NanocachedClient::connect(
    Options::new().addresses([("127.0.0.1", 8357)]),
).await?;

client.set("greeting", "hello", 60).await?;            // TTL seconds; 0 = no expiry
let value: Option<String> = client.get("greeting").await?;
let existed: bool = client.delete("greeting").await?;

client.close().await;

.NET

dotnet add package Nanocached
using Nanocached;

using NanocachedClient client = await NanocachedClient.ConnectAsync(new NanocachedClient.Options {
    Addresses = { ("127.0.0.1", 8357) },
});

await client.SetAsync("greeting", "hello", ttlSeconds: 60);  // omit = no expiry
string? value = await client.GetAsync("greeting");   // null when missing
bool existed = await client.DeleteAsync("greeting");

Go

go get github.com/nanocached/nanocached/sdk/go
import nanocached "github.com/nanocached/nanocached/sdk/go"

client, err := nanocached.Connect(nanocached.Config{
    Addresses: []nanocached.Address{{Host: "127.0.0.1", Port: 8357}},
})
if err != nil { /* ... */ }
defer client.Close()

err = client.Set("greeting", "hello", 60) // TTL seconds; 0 = no expiry
value, ok, err := client.Get("greeting")  // ok=false when missing
existed, err := client.Delete("greeting")

Shared behavior, briefly

Where the SDKs differ on purpose

The SDKs behave the same; their surfaces follow each language. These differences are intended and part of what the compatibility page covers: