> ## Documentation Index
> Fetch the complete documentation index at: https://botmesh.afaya.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# UserData

> Interface exported by @botmesh/core.

Defined in: [user/types.ts:91](https://github.com/andresayac/botmesh/blob/main/packages/core/src/user/types.ts#L91)

Persistent, per-user key/value profile — `ctx.user` in handlers and
`bot.user(userId)` anywhere else.

**Scope.** Keyed by the canonical sender (`ctx.sender`, the provider-resolved
`senderId`), so it is shared across every chat that person writes from (DM
and groups) and survives conversations and restarts (with a persistent
store). It lives inside the bot's store namespace (tenant / environment /
bot / provider / connection), so two bots sharing one backend never see each
other's profiles.

**Namespaces.** `ctx.user` is the `'default'` namespace; `ctx.user.ns('game')`
returns the same API scoped to `'game'`. Namespace names are flat and
absolute (`ctx.user.ns('a').ns('b')` is namespace `'b'`). Use one per
feature/plugin to avoid key collisions.

**Paths.** Every method takes a dot path: `'name'`, `'address.city'`,
`'items.0'`. The FIRST segment is the top-level key, which is the unit the
store persists atomically; deeper segments are resolved inside its JSON value
(array elements by index). Keys cannot contain dots; `__proto__`,
`prototype`, `constructor`, empty segments and control characters are
rejected with `UserDataError('INVALID_PATH')`.

**Values** are JSON data: they are deep-copied through JSON on write (a
`Date` becomes its ISO string, `undefined` members vanish) and every read
returns a fresh copy. BigInt, functions, symbols and cycles reject with
`UserDataError('INVALID_VALUE')`. Writing `undefined` deletes the path.

**Concurrency.** The dispatcher's per-chat FIFO does NOT serialise one user
across several chats (the same person can be handled in a group and in a DM
at the same time), so the profile serialises writes itself: inside one
process, every write of a user (`set` / `update` / `delete` / `clear` and the
bot's subject erasure) runs in call order, one at a time. A top-level
`set`/`delete` is a single atomic store write; a nested write is a
read-modify-write of its top-level key. Across several bot replicas sharing a
store, top-level writes stay atomic (last writer wins) but two replicas
writing nested paths of the SAME top-level key concurrently can lose one
update — keep such keys owned by one replica or write whole top-level values.
Reads never wait for writes; `await` your writes before reading them back.

## Example

```ts theme={null}
bot.when('hola', async (ctx) => {
  const name = await ctx.user.get<string>('name')
  await ctx.user.set('name', 'Juan')
  await ctx.user.set('address.city', 'Bogotá')
  await ctx.user.update({ lang: 'es', 'address.zip': '110111' })
  await ctx.user.ns('game').set('board', board, { ttl: '30m' })
  await ctx.user.ns('game').clear()
})
```

## Properties

### userId

```ts theme={null}
readonly userId: string;
```

Defined in: [user/types.ts:93](https://github.com/andresayac/botmesh/blob/main/packages/core/src/user/types.ts#L93)

Subject this profile belongs to (`ctx.sender`).

***

### namespace

```ts theme={null}
readonly namespace: string;
```

Defined in: [user/types.ts:95](https://github.com/andresayac/botmesh/blob/main/packages/core/src/user/types.ts#L95)

Namespace this handle reads and writes (`'default'` for `ctx.user`).

## Methods

### get()

```ts theme={null}
get<T>(path): Promise<T | undefined>;
```

Defined in: [user/types.ts:101](https://github.com/andresayac/botmesh/blob/main/packages/core/src/user/types.ts#L101)

Value at `path`, or `undefined` when missing or expired. `T` is an
unchecked convenience cast — validate untrusted shapes yourself.

#### Type Parameters

| Type Parameter | Default type |
| - | - |
|  `T` | `unknown` |

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |

#### Returns

`Promise`\<`T` | `undefined`>

***

### all()

```ts theme={null}
all(): Promise<Record<string, unknown>>;
```

Defined in: [user/types.ts:103](https://github.com/andresayac/botmesh/blob/main/packages/core/src/user/types.ts#L103)

Every live top-level key of this namespace as a plain object (`{}` when empty).

#### Returns

`Promise`\<`Record`\<`string`, `unknown`>>

***

### set()

```ts theme={null}
set(
   path, 
   value, 
   options?
): Promise<void>;
```

Defined in: [user/types.ts:105](https://github.com/andresayac/botmesh/blob/main/packages/core/src/user/types.ts#L105)

Write `value` at `path` (see [UserSetOptions.ttl](https://botmesh.afaya.com.co/api/core/interfaces/UserSetOptions.md#ttl) for expiry). `undefined` deletes.

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |
| `value` | `unknown` |
| `options?` | [`UserSetOptions`](https://botmesh.afaya.com.co/api/core/interfaces/UserSetOptions) |

#### Returns

`Promise`\<`void`>

***

### update()

```ts theme={null}
update(values, options?): Promise<void>;
```

Defined in: [user/types.ts:118](https://github.com/andresayac/botmesh/blob/main/packages/core/src/user/types.ts#L118)

Apply several writes: each own enumerable property of `values` is a PATH
(`{ name: 'Juan', 'address.city': 'Bogotá' }`), applied in object key
order like [set](#set); keys not mentioned are left alone. Paths, values,
`ttl` and array indexes (against the stored values) are validated before
anything is written, so an invalid batch writes nothing. All paths under
one top-level key become a single store write; the batch as a whole is not
atomic: each top-level key is its own write, so if the STORE fails one of
them the others may already be persisted. The call rejects with the first
store error only after every write of the batch has settled, so the next
write (or erasure) of this user never overlaps it.

#### Parameters

| Parameter | Type |
| - | - |
| `values` | `Record`\<`string`, `unknown`> |
| `options?` | [`UserSetOptions`](https://botmesh.afaya.com.co/api/core/interfaces/UserSetOptions) |

#### Returns

`Promise`\<`void`>

***

### delete()

```ts theme={null}
delete(path): Promise<void>;
```

Defined in: [user/types.ts:120](https://github.com/andresayac/botmesh/blob/main/packages/core/src/user/types.ts#L120)

Remove `path` (a top-level key or a nested member). Missing paths are a no-op.

#### Parameters

| Parameter | Type |
| - | - |
| `path` | `string` |

#### Returns

`Promise`\<`void`>

***

### clear()

```ts theme={null}
clear(): Promise<void>;
```

Defined in: [user/types.ts:122](https://github.com/andresayac/botmesh/blob/main/packages/core/src/user/types.ts#L122)

Remove every key of THIS namespace for this user (other namespaces are untouched).

#### Returns

`Promise`\<`void`>

***

### ns()

```ts theme={null}
ns(name): UserData;
```

Defined in: [user/types.ts:124](https://github.com/andresayac/botmesh/blob/main/packages/core/src/user/types.ts#L124)

Same API scoped to namespace `name`. Throws `UserDataError('INVALID_NAMESPACE')` synchronously.

#### Parameters

| Parameter | Type |
| - | - |
| `name` | `string` |

#### Returns

`UserData`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.