70 lines
2.1 KiB
Markdown
70 lines
2.1 KiB
Markdown
|
# Storage — `client.storage` + `client.projectStorage`
|
||
|
|
|
||
|
|
Two key/value stores: per-player (`StorageDomain`, revision key `storage`) and
|
||
|
|
project-wide shared (`ProjectStorageDomain`, revision key `projectStorage`).
|
||
|
|
Sources: `src/domains/StorageDomain.ts`, `src/domains/ProjectStorageDomain.ts`.
|
||
|
|
|
||
|
|
## Player storage
|
||
|
|
|
||
|
|
```ts
|
||
|
|
client.storage.data // GetStorageResponse | undefined
|
||
|
|
await client.storage.save(items);
|
||
|
|
await client.storage.delete(type);
|
||
|
|
```
|
||
|
|
|
||
|
|
```ts
|
||
|
|
interface GetStorageResponse {
|
||
|
|
items?: StorageItem[];
|
||
|
|
nextCursor?: string;
|
||
|
|
}
|
||
|
|
interface StorageItem {
|
||
|
|
data?: string; // opaque payload, JSON-stringify yourself if needed
|
||
|
|
id?: string;
|
||
|
|
type?: string; // the storage "collection" key
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
- `save(items: StorageItem[]): Promise<void>` — upserts items, then
|
||
|
|
invalidates the domain so subscribers refetch.
|
||
|
|
- `delete(type: string): Promise<void>` — deletes **all** player storage items
|
||
|
|
of that type, then invalidates.
|
||
|
|
|
||
|
|
## Project storage
|
||
|
|
|
||
|
|
```ts
|
||
|
|
client.projectStorage.data // GetProjectStorageResponse | undefined
|
||
|
|
await client.projectStorage.save(items);
|
||
|
|
```
|
||
|
|
|
||
|
|
```ts
|
||
|
|
interface GetProjectStorageResponse {
|
||
|
|
items?: ProjectStorageItem[];
|
||
|
|
nextCursor?: string;
|
||
|
|
}
|
||
|
|
interface ProjectStorageItem {
|
||
|
|
data?: string;
|
||
|
|
expiresAt?: string;
|
||
|
|
id?: string;
|
||
|
|
readPermission?: 'public' | 'serverOnly';
|
||
|
|
size?: number;
|
||
|
|
type?: string;
|
||
|
|
updatedAt?: string;
|
||
|
|
version?: number;
|
||
|
|
writePermission?: 'public' | 'serverOnly';
|
||
|
|
}
|
||
|
|
interface ProjectStorageUpdateItem { data?: string; type?: string }
|
||
|
|
```
|
||
|
|
|
||
|
|
- `save(items: ProjectStorageUpdateItem[]): Promise<void>` — upserts, then
|
||
|
|
invalidates. Writing is only possible for items whose `writePermission` is
|
||
|
|
`public`; `serverOnly` items are read-only for clients.
|
||
|
|
- The SDK exposes no client-side project-storage delete.
|
||
|
|
|
||
|
|
## Limits and notes
|
||
|
|
|
||
|
|
- Both domains load with `{ limit: 100 }` — the observable snapshot holds at
|
||
|
|
most 100 items and `nextCursor` pagination is not surfaced by the domain.
|
||
|
|
- `data` is a raw string on the wire; serialize/deserialize JSON yourself.
|
||
|
|
- Both are observable (`SyncedState`) and warmed by the revision poll only when
|
||
|
|
in use; mutations self-invalidate.
|