---
title: Using namespaces
description: Create scoped views of your store to organize keys by purpose or application.
url: https://pr-1-c0fdf0ef9f59.thally.app/guides/using-namespaces
---

# Using namespaces

Create scoped views of your store to organize keys by purpose or application.

## Create scoped store views

Namespaces let you create isolated views of a single store, with keys transparently prefixed to prevent collisions. Use namespaces to organize entries by feature, module, or tenant.

## Basic usage

Call `namespace(name)` on your store to create a scoped view:

```typescript
import { DriftStore, NAMESPACE_DELIMITER } from "driftkv";

const store = new DriftStore();

// Create namespaced views
const users = store.namespace("users");
const sessions = store.namespace("sessions");

// Keys are independent within each view
users.set("alice", { id: 1, name: "Alice" });
sessions.set("alice", { token: "xyz", exp: 1234567890 });

// Each view only sees its own keys
users.get("alice"); // → { id: 1, name: 'Alice' }
sessions.get("alice"); // → { token: 'xyz', exp: 1234567890 }

// Different views with the same name never see each other's data
users.keys(); // → ['alice']
sessions.keys(); // → ['alice']
```

## How namespaces work

Each namespace transparently prefixes keys with the namespace name and a delimiter (`:`). When you call methods on a namespace view, the results are scoped to only that namespace's entries:

- **`get()`, `set()`, `has()`, `delete()`** — operate only on the namespaced entries
- **`keys()`, `size()`, `clear()`, `sweep()`** — report and affect only the namespace's entries; `keys()` returns keys without the prefix
- **`flush()`** — writes the **entire store** (all namespaces), not just the view

If you inspect the root store's `keys()`, you'll see the full prefixed names:

```typescript
store.set("user:alice", "direct");
users.set("bob", { name: "Bob" });

store.keys(); // → ['user:alice', 'users:bob']
users.keys(); // → ['bob']
```

Use the exported `NAMESPACE_DELIMITER` constant if you need to parse full keys:

```typescript
import { NAMESPACE_DELIMITER } from "driftkv";

const fullKey = "users:bob";
const [namespace, key] = fullKey.split(NAMESPACE_DELIMITER);
```

## Nesting namespaces

Call `namespace()` on a namespace view to create nested scopes. Keys nest with repeated delimiters:

```typescript
const store = new DriftStore();
const tenants = store.namespace("tenants");
const acmeTenant = tenants.namespace("acme");

acmeTenant.set("config", { plan: "pro" });

// In the root store, the key is fully qualified
store.keys(); // → ['tenants:acme:config']

// Each level sees only its own prefix
tenants.keys(); // → ['acme:config']
acmeTenant.keys(); // → ['config']
```

## Persistence with namespaces

When you call `flush()` on any namespace view, the entire store is written to disk — not just that view's entries. All namespaces are persisted together:

```typescript
const store = new DriftStore({ persistPath: "./store.json" });
const users = store.namespace("users");
const sessions = store.namespace("sessions");

users.set("alice", { name: "Alice" });
sessions.set("token-123", { user: "alice" });

users.flush(); // Writes both users and sessions to persistPath
```

## What's next

Learn more about [persistence](/api) and [TTL](/api) options in the full API reference.